PyMsgBox

https://pymsgbox.readthedocs.io/en/latest/
Admin
PyMsgBox is a Python library that provides simple message box functions (alert, confirm, prompt,...
Tokens:3,265
Snippets:34
Trust Score:9.6
Update:5 months ago
Show doc for...
Tokens:
Raw
### Basic PyMsgBox Functions

Source: https://pymsgbox.readthedocs.io/en/latest/quickstart.html

Demonstrates the basic usage of alert, confirm, prompt, and password message boxes. Ensure Tkinter is installed on Linux Python 2.

```python
>>> import pymsgbox
>>> pymsgbox.alert('This is an alert.')
```

```python
>>> pymsgbox.confirm('Click OK to continue, click Cancel to cancel.')
```

```python
>>> pymsgbox.prompt('Enter your name.')
```

```python
>>> pymsgbox.password('Enter your password. (It will appear hidden in this text field.)')
```

--------------------------------

### Display a prompt message box for user input

Source: https://pymsgbox.readthedocs.io/en/latest/basics.html

Use `prompt` to get text input from the user with OK and Cancel buttons. It returns the entered text or None if Cancel is clicked.

```python
>>> pymsgbox.prompt('What does the fox say?', default='This reference dates this example.')
'This reference dates this example.'
```

--------------------------------

### Using Native Confirm

Source: https://pymsgbox.readthedocs.io/en/latest/native.html

Demonstrates how to display a native confirmation message box.

```APIDOC
## `native.confirm()`

### Description
Displays a native confirmation message box with OK and Cancel buttons.

### Method
`pymsgbox.native.confirm(text, title, buttons=['OK', 'Cancel'])

### Parameters
- **text** (str) - The message to display in the confirmation box.
- **title** (str) - The title of the confirmation box.
- **buttons** (list of str, optional) - A list of strings for the button labels. Defaults to `['OK', 'Cancel']`.

### Response
- **str** - Returns the label of the button clicked. If 'OK' is clicked, the first item in the `buttons` list is returned. If 'Cancel' is clicked, the second item is returned.

### Request Example
```python
>>> import pymsgbox
>>> pymsgbox.native.confirm('Nuke the site from orbit?', 'Confirm nuke', ["Yes, I'm sure.", 'Cancel'])
"Yes, I'm sure."
```

### Special Notes (Windows)
On Windows, the confirm box will only show "OK" and "Cancel" buttons, regardless of the `buttons` argument. The return value corresponds to the first or second button in the default `['OK', 'Cancel']` list.
```

--------------------------------

### Using Native Alert

Source: https://pymsgbox.readthedocs.io/en/latest/native.html

Demonstrates how to display a native alert message box.

```APIDOC
## `native.alert()`

### Description
Displays a native alert message box.

### Method
`pymsgbox.native.alert(text, title)`

### Parameters
- **text** (str) - The message to display in the alert box.
- **title** (str) - The title of the alert box.

### Response
- **OK** (str) - Returns the string 'OK' when the user clicks the OK button.

### Request Example
```python
>>> import pymsgbox
>>> pymsgbox.native.alert('This is an alert.', 'The title.')
'OK'
```

### Special Notes (Windows)
On Windows, the alert box will only show an "OK" button, regardless of the `button` argument. The `button` argument's value is what is returned by the function.
```

--------------------------------

### prompt

Source: https://pymsgbox.readthedocs.io/en/latest/basics.html

Displays a message box with text input, and OK & Cancel buttons. Returns the text entered, or None if Cancel was clicked.

```APIDOC
## prompt(text='', title='', defaultValue='')

### Description
Displays a message box with a text input field, and OK & Cancel buttons. Returns the text entered by the user, or None if the Cancel button was clicked.

### Parameters
- **text** (string) - Optional - The message to display above the input field.
- **title** (string) - Optional - The title of the prompt box window.
- **defaultValue** (string) - Optional - The default text to pre-fill in the input field.

### Returns
- (string or None) - The text entered by the user, or None if Cancel was clicked.

### Request Example
```python
import pymsgbox
pymsgbox.prompt('What does the fox say?', default='This reference dates this example.')
```

### Response Example
```
'This reference dates this example.'
```
```

--------------------------------

### Import and Use Native Alert

Source: https://pymsgbox.readthedocs.io/en/latest/native.html

Import the native module and call the alert function. This is the primary way to access native message boxes.

```python
>>> import pymsgbox
>>> pymsgbox.native.alert('This is an alert.', 'The title.')
```

--------------------------------

### Display an alert message box

Source: https://pymsgbox.readthedocs.io/en/latest/basics.html

Use `alert` for simple informational messages with a single OK button. It returns 'OK' when the button is clicked.

```python
>>> pymsgbox.alert('This is an alert.', 'Alert!')
'OK'
```

--------------------------------

### alert

Source: https://pymsgbox.readthedocs.io/en/latest/basics.html

Displays a simple message box with text and a single OK button. Returns the text of the button clicked on.

```APIDOC
## alert(text='', title='', button='OK')

### Description
Displays a simple message box with text and a single OK button.

### Parameters
- **text** (string) - Optional - The message to display in the alert box.
- **title** (string) - Optional - The title of the alert box window.
- **button** (string) - Optional - The text for the button. Defaults to 'OK'.

### Returns
- (string) - The text of the button clicked on. For this function, it will always be the value of the `button` parameter.

### Request Example
```python
import pymsgbox
pymsgbox.alert('This is an alert.', 'Alert!')
```

### Response Example
```
'OK'
```
```

--------------------------------

### Localization

Source: https://pymsgbox.readthedocs.io/en/latest/basics.html

Allows customization of the default button texts and timeout message for PyMsgBox functions.

```APIDOC
## Localization Variables

### Description
Customize the default text for common buttons and messages used across PyMsgBox functions.

### Variables
- **pymsgbox.OK_TEXT**: String - The default text for 'OK' buttons.
- **pymsgbox.CANCEL_TEXT**: String - The default text for 'Cancel' buttons.
- **pymsgbox.TIMEOUT_TEXT**: String - The default message returned when a timeout occurs.

### Usage Example
```python
import pymsgbox

pymsgbox.OK_TEXT = 'Confirm'
pymsgbox.CANCEL_TEXT = 'Abort'
pymsgbox.TIMEOUT_TEXT = 'Operation timed out'

# Now, any confirm or prompt boxes will use these texts by default
# For example, a confirm box would show 'Confirm' and 'Abort' buttons
# and return 'Operation timed out' if it times out.
```
```

--------------------------------

### PyMsgBox Function Default Arguments

Source: https://pymsgbox.readthedocs.io/en/latest/quickstart.html

Shows the default arguments for alert, confirm, prompt, and password functions. These can be customized when calling the functions.

```python
>>> pymsgbox.alert(text='', title='', button='OK')
```

```python
>>> pymsgbox.confirm(text='', title='', buttons=['OK', 'Cancel'])
```

```python
>>> pymsgbox.prompt(text='', title='' , defaultValue='')
```

```python
>>> pymsgbox.password(text='', title='', defaultValue='', mask='*')
```

--------------------------------

### Display a confirmation message box

Source: https://pymsgbox.readthedocs.io/en/latest/basics.html

Use `confirm` for yes/no or custom button choices. It returns the text of the button clicked. The number and text of buttons can be customized.

```python
>>> pymsgbox.confirm('Nuke the site from orbit?', 'Confirm nuke', ["Yes, I'm sure.", 'Cancel'])
"Yes, I'm sure."
```

--------------------------------

### password

Source: https://pymsgbox.readthedocs.io/en/latest/basics.html

Displays a message box with text input, and OK & Cancel buttons. Typed characters appear as *. Returns the text entered, or None if Cancel was clicked.

```APIDOC
## password(text='', title='', defaultValue='', mask='*')

### Description
Displays a message box with a text input field for passwords, where typed characters are masked with the specified character (default is '*'). It includes OK & Cancel buttons. Returns the entered text, or None if Cancel was clicked.

### Parameters
- **text** (string) - Optional - The message to display above the input field.
- **title** (string) - Optional - The title of the password box window.
- **defaultValue** (string) - Optional - The default text to pre-fill in the input field.
- **mask** (string) - Optional - The character used to mask the input. Defaults to '*'.

### Returns
- (string or None) - The text entered by the user, or None if Cancel was clicked.

### Request Example
```python
import pymsgbox
pymsgbox.password('Enter your password.')
```

### Response Example
```
'12345'
```
```

--------------------------------

### Using Native OS Message Boxes

Source: https://pymsgbox.readthedocs.io/en/latest/quickstart.html

Imports the native module for PyMsgBox to utilize operating system-specific message boxes. Note that not all message boxes have native support and will fall back to the default implementation.

```python
>>> import pymsgbox.native as pymsgbox
```

--------------------------------

### Windows Native Confirm Behavior

Source: https://pymsgbox.readthedocs.io/en/latest/native.html

On Windows, the native confirm() function only supports 'OK' and 'Cancel' buttons, regardless of the 'buttons' argument. The return value corresponds to the clicked button's text.

```python
>>> pymsgbox.native.confirm('Nuke the site from orbit?', 'Confirm nuke', ["Yes, I'm sure.", 'Cancel'])
"Yes, I'm sure."
```

--------------------------------

### confirm

Source: https://pymsgbox.readthedocs.io/en/latest/basics.html

Displays a message box with OK and Cancel buttons. Number and text of buttons can be customized. Returns the text of the button clicked on.

```APIDOC
## confirm(text='', title='', buttons=['OK', 'Cancel'])

### Description
Displays a message box with OK and Cancel buttons. The number and text of buttons can be customized. Returns the text of the button clicked on.

### Parameters
- **text** (string) - Optional - The message to display in the confirmation box.
- **title** (string) - Optional - The title of the confirmation box window.
- **buttons** (list of strings) - Optional - A list of strings representing the buttons to display. Defaults to ['OK', 'Cancel'].

### Returns
- (string) - The text of the button clicked on.

### Request Example
```python
import pymsgbox
pymsgbox.confirm('Nuke the site from orbit?', 'Confirm nuke', ["Yes, I'm sure.", 'Cancel'])
```

### Response Example
```
"Yes, I'm sure."
```
```

--------------------------------

### Display a password input message box

Source: https://pymsgbox.readthedocs.io/en/latest/basics.html

Use `password` for secure text input, masking characters with an asterisk. It returns the entered text or None if Cancel is clicked.

```python
>>> pymsgbox.password('Enter your password.')
'12345'
```

--------------------------------

### Windows Native Alert Behavior

Source: https://pymsgbox.readthedocs.io/en/latest/native.html

On Windows, the native alert() function ignores the 'button' argument and always displays an 'OK' button. The return value is always 'OK'.

```python
>>> pymsgbox.native.alert('This is an alert.', 'Alert!')
'OK'
```

--------------------------------

### Use timeout for message boxes

Source: https://pymsgbox.readthedocs.io/en/latest/basics.html

All PyMsgBox functions accept a `timeout` parameter in milliseconds. If the timeout is reached before user interaction, the function returns 'Timeout'.

```python
>>> pymsgbox.confirm('Nuke the site from orbit?', 'Confirm nuke', ["Yes, I'm sure.", 'Cancel'], timeout=2000)  # closes after 2000 milliseconds (2 seconds)
"Timeout"
```

--------------------------------

### Timeout Functionality

Source: https://pymsgbox.readthedocs.io/en/latest/basics.html

All four PyMsgBox functions (alert, confirm, prompt, password) support a `timeout` parameter. If the message box is not interacted with before the specified time, it will close automatically and return the string 'Timeout'.

```APIDOC
## Timeout Parameter

### Description
Adds a timeout to any of the PyMsgBox functions. If the user does not respond within the specified time (in milliseconds), the message box will close and return the string 'Timeout'.

### Parameters
- **timeout** (integer) - Optional - The duration in milliseconds before the message box automatically closes.

### Request Example
```python
import pymsgbox

# Example using confirm with a timeout of 2 seconds (2000 milliseconds)
result = pymsgbox.confirm('Nuke the site from orbit?', 'Confirm nuke', ["Yes, I'm sure.", 'Cancel'], timeout=2000)
print(result)
```

### Response Example
```
"Timeout"
```
```
Tokens:
Raw