Metadata-Version: 2.4
Name: dynamicinputbox
Version: 3.1
Summary: Dynamic and customizable Tkinter input dialogs with text fields, alternatives, and typed results
Author-email: Smorkster <smorkster@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/Smorkster/dynamicinputbox
Project-URL: Repository, https://github.com/Smorkster/dynamicinputbox
Project-URL: Issues, https://github.com/Smorkster/dynamicinputbox/issues
Keywords: tkinter,dialog,gui,input,messagebox
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Environment :: Win32 (MS Windows)
Classifier: Environment :: MacOS X
Classifier: Environment :: X11 Applications :: GTK
Classifier: Topic :: Software Development :: User Interfaces
Classifier: Topic :: Desktop Environment
Classifier: Topic :: Utilities
Classifier: Natural Language :: English
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown

PePy statistics  
[![PyPI Downloads](https://static.pepy.tech/badge/dynamicinputbox)](https://pepy.tech/projects/dynamicinputbox)

# dynamicinputbox

A dynamic and customizable input dialog box built with Tkinter.

`dynamicinputbox` creates a dialog window that can:

- show an optional message
- collect one or more text inputs
- support default values and preset placeholder text
- hide sensitive input behind a masking character
- present alternative selections through comboboxes
- return the clicked button together with collected values

## Installation

```bash
pip install dynamicinputbox
```

## Basic usage
```python
from dynamicinputbox import DynamicInputBox

dlg = DynamicInputBox(
    title = 'Example',
    message = 'Enter your information',
    inputs = [
        { 'label': 'Username', 'name': 'username' },
        { 'label': 'Password', 'name': 'password', 'show': '*' },
    ],
    buttons = [ 'OK', 'Cancel' ],
    cancel_button = 'Cancel',
).show()

result = dlg.get( dictionary = True )
print( result )
```

See ``demo.py`` for further examples

## Parameters
### General
  * title (str): Window title. Default is "DynamicInputBox".
  * message (str | None): Optional message displayed above the dialog content.

### Inputs
  * inputs (list[InputDict] | None): Collection of input definitions.

Each input definition supports:

  * label (str): Display label for the input field.
  * name (str, optional): Name used as the key in the returned input data. If omitted, a name is generated automatically.
  * default (str, optional): Initial text shown in the input field.
  * show (str, optional): Masking character for hidden input, such as passwords.
  * preset (str, optional): Placeholder-style text shown until the user starts typing.

### Alternatives
  * alternatives (list[AlternativeDict] | None): Collection of alternative selection definitions.

Each alternative definition supports:

  * label (str): Display label for the alternative field.
  * options (list[str] | None): Selectable values shown in the combobox.
  * default (str | None): Initially selected value.

### Buttons
  * buttons (list[str]): Labels for buttons shown in the dialog. Default is [ 'OK' ].
  * default_button (str | None): Button triggered by Enter.
  * cancel_button (str | None): Button triggered by Escape and intended to represent cancellation.

### Behavior
  * dictionary (bool): Default result format used by get(). If True, get() returns dictionary form unless overridden.
  * wipe_after_get (bool): If True, secure values are wiped after they are retrieved.
  * topmost (bool): Whether the dialog should stay above other windows.
  * resizable (bool): Whether the dialog window should be resizable.
  * parent (Tk | Toplevel | None): Optional parent window.

### Layout
  * message_wraplength (int | None): Preferred wrap width for the message area, in pixels.
  * max_width_ratio (float): Maximum portion of screen width the dialog may occupy.
  * min_width_px (int): Minimum dialog width in pixels.
  * max_width_px (int | None): Optional absolute maximum dialog width in pixels.
  * padding_px (int): Base padding value for layout.

### Return values
The dialog instance is returned from .show().

After the dialog closes, call .get() to retrieve the result.

For type-checker-friendly access, you can also call `.get_dict()` or `.get_tuple()`.
The overloaded `.get()` method also narrows correctly when you pass
`dictionary = True` or `dictionary = False` as a literal.

#### Tuple form
```python
dlg.get()
```

or

```python
dlg.get_tuple()
```

**Returns:**
```python
(inputs_dict_or_none, alternatives_dict, clicked_button)
```

Where:
  * inputs_dict_or_none is dict[str, str | bytearray] | None
  * alternatives_dict is dict[str, str]
  * clicked_button is str

Sensitive inputs defined with show are returned as bytearray.

#### Dictionary form
```python
dlg.get( dictionary = True )
```

Or:

```python
dlg.get_dict()
```

**Returns:**
```python
{
    'button': 'OK',
    'inputs': { ... },
    'alternatives': { ... },
}
```

### Notes:
  * 'button' is always included
  * 'inputs' is only included if input fields were defined
  * 'alternatives' is only included if alternative fields were defined

### Secure input handling
Inputs configured with show are internally wrapped in SecureString and returned as bytearray values rather than plain strings. This allows the internal buffer to be wiped after retrieval when wipe_after_get = True.

## Public types
The package exposes a few public helper types:
  * InputDict
  * AlternativeDict
  * Result
  * ResultDict
  * ResultTuple
  * SecureString

Example:
```python
from dynamicinputbox import DynamicInputBox, InputDict, ResultDict
```

## Legacy API
The legacy single-input API is still supported for backward compatibility.

Deprecated parameters:
  * input
  * input_default
  * input_label
  * input_show

Example:
```python
dlg = DynamicInputBox(
    title = 'Legacy example',
    message = 'Enter a value',
    input = True,
    input_label = 'Value',
    input_default = 'Example',
    input_show = '*',
).show()

print( dlg.get( dictionary = True ) )
```

New code should prefer inputs = [...].

## Imports and backward compatibility

The preferred import style is:

```python
from dynamicinputbox import DynamicInputBox
```

For backward compatibility, the legacy alias is also still available:

```python
from dynamicinputbox import dynamic_inputbox
```

Older module-path imports can still work through a compatibility shim:

```python
from dynamicinputbox.dynamicinputbox import DynamicInputBox
from dynamicinputbox.dynamicinputbox import dynamic_inputbox
```

New code should prefer importing directly from dynamicinputbox.

## Notes
* Built on Tkinter
* Designed for simple desktop dialogs
* Uses comboboxes for alternative selections
* Intended to work across Windows, macOS, and Linux environments where Tkinter is available
