Widget Reference

Complete guide to all EZInput widgets with examples for Jupyter and terminal environments.

`add_text()`

Both Environments

Single-line text input widget.

Parameter	Type	Description
`unique_tag`	str	Unique identifier for this widget
`description`	str	Label/prompt text shown to user
Optional Parameters
`placeholder`	str	Placeholder text shown when empty (default: "")
`remember_value`	bool	Whether to remember value between sessions (default: True)
`*args`	tuple	Additional positional arguments passed to `ipywidgets.Text` (Jupyter) or `prompt_toolkit` (Terminal)
`**kwargs`	dict	Additional keyword arguments passed to `ipywidgets.Text` (Jupyter) or `prompt_toolkit` (Terminal). Common: `value` for initial value

from ezinput import EZInput

gui = EZInput("text_example")

# Basic text input
name = gui.add_text("user_name", "Enter your name:")

# With placeholder
email = gui.add_text("email", "Email address:", 
                     placeholder="user@example.com")

# With initial value
project = gui.add_text("project_name", "Project:", 
                       value="MyProject")

gui.show()

print(f"Name: {name.value}")
print(f"Email: {email.value}")

💻 In Jupyter Notebook

Displays as an ipywidgets.Text widget with a text box

🖥️ In Terminal

Prompts with prompt_toolkit providing autocomplete and history

`add_text_area()`

Both Environments

Multi-line text input widget for longer text content.

Parameter	Type	Description
`unique_tag`	str	Unique identifier for this widget
`description`	str	Label/prompt text
Optional Parameters
`placeholder`	str	Placeholder text (default: "")
`remember_value`	bool	Whether to remember value between sessions (default: True)
`*args`	tuple	Additional positional arguments passed to `ipywidgets.Textarea` (Jupyter) or `prompt_toolkit` (Terminal)
`**kwargs`	dict	Additional keyword arguments passed to `ipywidgets.Textarea` (Jupyter) or `prompt_toolkit` (Terminal)

# Multi-line text input
description = gui.add_text_area("desc", "Project description:", 
                                placeholder="Enter detailed description...")

# For code snippets
code_input = gui.add_text_area("code", "Paste your code:",
                               value="# Your code here\n")

gui.show()
print(description.value)

`add_int_range()`

Both Environments

Integer input with minimum and maximum bounds. Shows as slider in Jupyter.

Parameter	Type	Description
`unique_tag`	str	Unique identifier
`description`	str	Label text
`min_val`	int	Minimum allowed value
`max_val`	int	Maximum allowed value
Optional Parameters
`value`	int	Initial value (default: min_val)
`remember_value`	bool	Whether to remember value between sessions (default: True)
`*args`	tuple	Additional positional arguments passed to `ipywidgets.IntSlider` (Jupyter) or `prompt_toolkit` (Terminal)
`**kwargs`	dict	Additional keyword arguments passed to `ipywidgets.IntSlider` (Jupyter) or `prompt_toolkit` (Terminal)

# Integer slider/range input
iterations = gui.add_int_range("iter", "Iterations:", 1, 1000, value=100)

# Age input with bounds
age = gui.add_int_range("age", "Your age:", 0, 120, value=25)

gui.show()
print(f"Iterations: {iterations.value}")

`add_float_range()`

Both Environments

Float input with minimum and maximum bounds. Shows as slider in Jupyter.

Parameter	Type	Description
`unique_tag`	str	Unique identifier
`description`	str	Label text
`min_val`	float	Minimum allowed value
`max_val`	float	Maximum allowed value
Optional Parameters
`value`	float	Initial value (default: min_val)
`remember_value`	bool	Whether to remember value between sessions (default: True)
`*args`	tuple	Additional positional arguments passed to `ipywidgets.FloatSlider` (Jupyter) or `prompt_toolkit` (Terminal)
`**kwargs`	dict	Additional keyword arguments passed to `ipywidgets.FloatSlider` (Jupyter) or `prompt_toolkit` (Terminal)

# Threshold slider/input
threshold = gui.add_float_range("thresh", "Threshold:", 0.0, 1.0, value=0.5)

# Learning rate with precision
lr = gui.add_float_range("lr", "Learning rate:", 0.0001, 0.1, value=0.01)

gui.show()
print(f"Threshold: {threshold.value}")

`add_bounded_int_text()`

Both Environments

Integer text input with validation against min/max bounds.

# Bounded integer with validation
percentage = gui.add_bounded_int_text("coverage", "Coverage %:", 0, 100)

# Port number input
port = gui.add_bounded_int_text("port", "Port:", 1024, 65535, value=8080)

gui.show()

`add_bounded_float_text()`

Both Environments

Float text input with validation against min/max bounds.

# Bounded float with validation
ratio = gui.add_bounded_float_text("ratio", "Aspect ratio:", 0.5, 2.0)

# Temperature range
temp = gui.add_bounded_float_text("temp", "Temperature:", -273.15, 1000.0)

gui.show()

`add_int_text()` & `add_float_text()`

Both Environments

Unbounded numeric text input (no min/max validation).

# Unbounded integer input
count = gui.add_int_text("count", "Number of samples:")

# Unbounded float input
weight = gui.add_float_text("weight", "Weight (kg):")

gui.show()

`add_check()`

Both Environments

Boolean checkbox or yes/no prompt.

Parameter	Type	Description
`unique_tag`	str	Unique identifier
`description`	str	Label/question text
Optional Parameters
`value`	bool	Initial value (default: False)
`remember_value`	bool	Whether to remember value between sessions (default: True)
`*args`	tuple	Additional positional arguments passed to `ipywidgets.Checkbox` (Jupyter) or `prompt_toolkit` (Terminal)
`**kwargs`	dict	Additional keyword arguments passed to `ipywidgets.Checkbox` (Jupyter) or `prompt_toolkit` (Terminal)

# Boolean checkbox (Jupyter) or yes/no prompt (terminal)
debug = gui.add_check("debug", "Enable debug mode?", value=False)

use_gpu = gui.add_check("gpu", "Use GPU acceleration?", value=True)

verbose = gui.add_check("verbose", "Verbose output?")

gui.show()

if debug.value:
    print("Debug mode enabled")

if use_gpu.value:
    print("Using GPU")

💻 In Jupyter Notebook

Displays as a checkbox widget

🖥️ In Terminal

Shows as "Yes/No" prompt with default selection

`add_dropdown()`

Both Environments

Single selection from a list of options.

Parameter	Type	Description
`unique_tag`	str	Unique identifier
`options`	list	List of options to choose from
`description`	str	Label text
Optional Parameters
`value`	any	Initial selected value (default: first option)
`remember_value`	bool	Whether to remember value between sessions (default: True)
`*args`	tuple	Additional positional arguments passed to `ipywidgets.Dropdown` (Jupyter) or `prompt_toolkit` (Terminal)
`**kwargs`	dict	Additional keyword arguments passed to `ipywidgets.Dropdown` (Jupyter) or `prompt_toolkit` (Terminal)

# Dropdown selection
algorithm = gui.add_dropdown("algo", 
                             ["linear", "polynomial", "rbf", "sigmoid"],
                             "Kernel method:",
                             value="rbf")

# File format selection
format_opt = gui.add_dropdown("format",
                              ["PNG", "JPEG", "TIFF", "BMP"],
                              "Output format:")

# Mode selection
mode = gui.add_dropdown("mode",
                       ["CPU", "GPU", "Multi-GPU"],
                       "Execution mode:")

gui.show()
print(f"Selected: {algorithm.value}")

💻 In Jupyter Notebook

Displays as a dropdown menu widget

🖥️ In Terminal

Shows as an autocomplete-enabled selection prompt

`add_file_upload()`

Jupyter Only

Visual file picker for Jupyter notebooks. Uses ipyfilechooser.

Parameter	Type	Description
`unique_tag`	str	Unique identifier
Optional Parameters
`accept`	str	File filter pattern (e.g., ".tif", ".csv") (default: "")
`description`	str	Label text (default: "")
`*args`	tuple	Additional positional arguments passed to `ipyfilechooser.FileChooser`
`**kwargs`	dict	Additional keyword arguments passed to `ipyfilechooser.FileChooser`

# File picker for TIFF images
input_file = gui.add_file_upload("input_image", accept="*.tif")

# CSV file picker
data_file = gui.add_file_upload("data", accept="*.csv", 
                                description="Select data file:")

# Accept multiple file types
config_file = gui.add_file_upload("config", accept="*.yml,*.yaml,*.json")

gui.show()
print(f"Selected file: {input_file.value}")

⚠️ Jupyter Only: This widget only works in Jupyter notebooks. For terminal, use add_path_completer() instead.

`add_path_completer()`

Terminal Only

Path input with autocomplete for terminal environments.

Parameter	Type	Description
`unique_tag`	str	Unique identifier
`description`	str	Prompt text
Optional Parameters
`value`	str	Initial path (default: "")
`remember_value`	bool	Whether to remember value between sessions (default: True)
`*args`	tuple	Additional positional arguments passed to `prompt_toolkit`
`**kwargs`	dict	Additional keyword arguments passed to `prompt_toolkit`

# Path input with autocomplete
input_file = gui.add_path_completer("input", "Select input file:")

output_dir = gui.add_path_completer("output_dir", "Output directory:",
                                    value="./output")

gui.show()
print(f"File path: {input_file.value}")

⚠️ Terminal Only: This widget only works in terminal. For Jupyter, use add_file_upload() instead.

💡 Cross-Environment File Selection

For code that needs to work in both environments, you can use conditional logic:

from ezinput import EZInput
import sys

gui = EZInput("file_selector")

# Detect environment and use appropriate widget
if 'ipykernel' in sys.modules:
    # Jupyter notebook
    input_file = gui.add_file_upload("input", accept="*.csv")
else:
    # Terminal
    input_file = gui.add_path_completer("input", "Select CSV file:")

gui.show()
print(f"File: {input_file.value}")

Or better yet, just handle the file path as a string in your processing code and let users choose the appropriate input method!

`add_label()`

Both Environments

Static text label for headers and instructions.

Parameter	Type	Description
Optional Parameters
`tag`	str	Optional unique identifier (default: None)
`value`	str	Text to display (default: "")
`*args`	tuple	Additional positional arguments passed to `ipywidgets.Label` (Jupyter) or displayed as text (Terminal)
`**kwargs`	dict	Additional keyword arguments passed to `ipywidgets.Label` (Jupyter) or ignored (Terminal)

# Section headers
gui.add_label(value="=== Input Parameters ===")
input_file = gui.add_text("input", "Input file path:", placeholder="/path/to/file.tif")

gui.add_label(value="=== Processing Options ===")
threshold = gui.add_float_range("thresh", "Threshold:", 0, 1)

gui.add_label(value="=== Advanced Settings ===")
gpu = gui.add_check("gpu", "Use GPU?")

gui.show()

`add_output()`

Jupyter Only

Output display area for showing results in Jupyter notebooks.

Parameter	Type	Description
`unique_tag`	str	Unique identifier
Optional Parameters
`*args`	tuple	Additional positional arguments passed to `ipywidgets.Output`
`**kwargs`	dict	Additional keyword arguments passed to `ipywidgets.Output`

# Create output area
gui.add_output("results")

gui.show()

# Use output area
with gui["results"]:
    print("Processing started...")
    # Your processing code
    print("Complete!")

`add_HTML()`

Jupyter Only

Display rich HTML content in Jupyter notebooks.

Parameter	Type	Description
`unique_tag`	str	Unique identifier
Optional Parameters
`value`	str	HTML content to display (default: "")
`*args`	tuple	Additional positional arguments passed to `ipywidgets.HTML`
`**kwargs`	dict	Additional keyword arguments passed to `ipywidgets.HTML`

# Rich HTML display
gui.add_HTML("warning", 
             '⚠️ Experimental Feature')

gui.add_HTML("info",
             '''
                Note: This analysis may take several minutes.
                ''')

gui.show()

`add_callback()`

Both Environments

Execute a function with current GUI values. Creates a button in Jupyter, executes immediately in terminal.

Parameter	Type	Description
`unique_tag`	str	Unique identifier
`callback_function`	callable	Function to execute
`arguments_dict`	dict	Arguments to pass (typically `gui.get_values()`)
Optional Parameters
`description`	str	Button label (Jupyter) or action description (default: "")
`*args`	tuple	Additional positional arguments passed to `ipywidgets.Button` (Jupyter) or ignored (Terminal)
`**kwargs`	dict	Additional keyword arguments passed to `ipywidgets.Button` (Jupyter) or ignored (Terminal)

from ezinput import EZInput

def process_data(values):
    """Process data with current parameter values."""
    threshold = values["threshold"].value
    method = values["method"].value
    input_file = values["input_file"].value
    
    print(f"Processing {input_file}")
    print(f"Method: {method}, Threshold: {threshold}")
    
    # Your processing code here
    result = perform_analysis(input_file, method, threshold)
    
    return result

# Create GUI
gui = EZInput("data_processor")

gui.add_text("input_file", "Input file path:", placeholder="/path/to/image.tif")
gui.add_float_range("threshold", "Threshold:", 0.0, 1.0)
gui.add_dropdown("method", ["watershed", "otsu"], "Method:")

# Add callback button/action
gui.add_callback("run", process_data, gui.get_values(),
                 description="Start Processing")

gui.show()

💻 In Jupyter Notebook

Creates a clickable button. Function executes when clicked.

🖥️ In Terminal

Function executes immediately after all inputs are collected.

Why "add_callback"? The name maintains API consistency between Jupyter's event-driven (button click) and terminal's sequential (immediate execution) models.

Widget Reference

Text Input Widgets

`add_text()`

💻 In Jupyter Notebook

🖥️ In Terminal

`add_text_area()`

Numeric Input Widgets

`add_int_range()`

`add_float_range()`

`add_bounded_int_text()`

`add_bounded_float_text()`

`add_int_text()` & `add_float_text()`

Selection Widgets

`add_check()`

💻 In Jupyter Notebook

🖥️ In Terminal

`add_dropdown()`

💻 In Jupyter Notebook

🖥️ In Terminal

File & Path Widgets

`add_file_upload()`

`add_path_completer()`

💡 Cross-Environment File Selection

Display Widgets

`add_label()`

`add_output()`

`add_HTML()`

Callbacks & Actions

`add_callback()`

💻 In Jupyter Notebook

🖥️ In Terminal

Widget Reference

Text Input Widgets

add_text()

💻 In Jupyter Notebook

🖥️ In Terminal

add_text_area()

Numeric Input Widgets

add_int_range()

add_float_range()

add_bounded_int_text()

add_bounded_float_text()

add_int_text() & add_float_text()

Selection Widgets

add_check()

💻 In Jupyter Notebook

🖥️ In Terminal

add_dropdown()

💻 In Jupyter Notebook

🖥️ In Terminal

File & Path Widgets

add_file_upload()

add_path_completer()

💡 Cross-Environment File Selection

Display Widgets

add_label()

add_output()

add_HTML()

Callbacks & Actions

add_callback()

💻 In Jupyter Notebook

🖥️ In Terminal

`add_text()`

`add_text_area()`

`add_int_range()`

`add_float_range()`

`add_bounded_int_text()`

`add_bounded_float_text()`

`add_int_text()` & `add_float_text()`

`add_check()`

`add_dropdown()`

`add_file_upload()`

`add_path_completer()`

`add_label()`

`add_output()`

`add_HTML()`

`add_callback()`