Dialog Layer API

The dialog layer provides high-level components for building terminal UIs.

Import

from ux3270.dialog import (
    Form,
    Menu,
    Table,
    WorkWithList,
    SelectionList,
    TabularEntry,
    MessagePanel,
    show_message,
)

Components

Form

`ux3270.dialog.Form`

High-level form builder with IBM 3270-style layout.

Follows IBM CUA conventions: - Panel ID at top-left, title centered - Instruction line below title - Labels in protected (turquoise) color - Input fields with underscores showing field length - Function key hints at bottom - F1 displays context-sensitive help

The dialog builds a Screen definition and hands control to Screen for all rendering and input handling.

`init(title='', panel_id='', instruction='', help_text='')`

Initialize a form.

Parameters:

Name	Type	Description	Default
`title`	`str`	Form title (displayed in uppercase per IBM convention)	`''`
`panel_id`	`str`	Optional panel identifier (shown at top-left per CUA)	`''`
`instruction`	`str`	Optional instruction text (shown on row 2 per CUA)	`''`
`help_text`	`str`	Panel-level help text shown when F1 is pressed	`''`

`add_field(label, length=20, field_type=FieldType.TEXT, default='', required=False, validator=None, prompt=None, help_text='')`

Add a field to the form.

Parameters:

Name	Type	Description	Default
`label`	`str`	Field label	required
`length`	`int`	Field length	`20`
`field_type`	`FieldType`	Field type	`TEXT`
`default`	`str`	Default value	`''`
`required`	`bool`	Whether field is required	`False`
`validator`	`Optional[Callable[[str], bool]]`	Optional validation function	`None`
`prompt`	`Optional[Callable[[], Optional[str]]]`	Optional F4=Prompt callback; should return selected value as string, or None if cancelled	`None`
`help_text`	`str`	Help text shown when F1 is pressed on this field	`''`

Returns:

Type	Description
`Form`	Self for method chaining

`add_text(text)`

Add static text to the form.

Parameters:

Name	Type	Description	Default
`text`	`str`	Text to display	required

Returns:

Type	Description
`Form`	Self for method chaining

`show()`

Display the form and return field values.

Returns:

Type	Description
`Optional[Dict[str, Any]]`	Dictionary of field values, or None if cancelled (F3)

`ux3270.dialog.Menu`

IBM 3270-style menu screen.

Displays a list of options with single-key selection. Follows IBM CUA (Common User Access) conventions: - Panel ID at top-left, title centered - Instruction line below title - Menu items in body area - Function keys at bottom

The dialog builds a Screen definition and hands control to Screen for all rendering and input handling.

`init(title='MAIN MENU', panel_id='', instruction='Select an option')`

Initialize a menu.

Parameters:

Name	Type	Description	Default
`title`	`str`	Menu title (displayed in uppercase per IBM convention)	`'MAIN MENU'`
`panel_id`	`str`	Optional panel identifier (shown at top-left per CUA)	`''`
`instruction`	`str`	Instruction text (shown on row 2 per CUA)	`'Select an option'`

`add_item(key, label, action)`

Add a menu item.

Parameters:

Name	Type	Description	Default
`key`	`str`	Single character key to select this item	required
`label`	`str`	Display label	required
`action`	`Callable`	Function to call when selected	required

Returns:

Type	Description
`Menu`	Self for method chaining

`show()`

Display the menu and wait for user selection.

Returns:

Type	Description
`Optional[str]`	Selected key, or None if user exits (F3 or X)

`run()`

Run the menu in a loop until user exits.

Table

`ux3270.dialog.Table`

IBM 3270-style table/list display with pagination.

Displays tabular data with column headers following CUA conventions: - Panel ID at top-left, title centered - Optional header fields (e.g., "Position to" filter) - Column headers in intensified text - Data rows in default (green) color - Row count/pagination info on message line - F7/F8 for page up/down (CUA standard) - Function keys at bottom

The dialog builds a Screen definition and hands control to Screen for all rendering and input handling.

`init(title='', panel_id='', instruction='')`

Initialize a table.

Parameters:

Name	Type	Description	Default
`title`	`str`	Table title (displayed in uppercase per IBM convention)	`''`
`panel_id`	`str`	Optional panel identifier (shown at top-left per CUA)	`''`
`instruction`	`str`	Optional instruction text	`''`

`add_column(name, width=None, align='left')`

Add a column definition.

Parameters:

Name	Type	Description	Default
`name`	`str`	Column name (used as header)	required
`width`	`Optional[int]`	Display width (None = auto-calculate from content)	`None`
`align`	`Literal['left', 'right']`	Text alignment ("left" or "right")	`'left'`

Returns:

Type	Description
`Table`	Self for method chaining

`add_header_field(label, length=10, default='', field_type=FieldType.TEXT)`

Add a header field (e.g., "Position to" filter).

Parameters:

Name	Type	Description	Default
`label`	`str`	Field label	required
`length`	`int`	Field length	`10`
`default`	`str`	Default value	`''`
`field_type`	`FieldType`	Field type	`TEXT`

Returns:

Type	Description
`Table`	Self for method chaining

`get_header_values()`

Get current header field values.

`add_row(*values)`

Add a row to the table.

Parameters:

Name	Type	Description	Default
`values`		Column values for the row	`()`

Returns:

Type	Description
`Table`	Self for method chaining

`show()`

Display the table with pagination and wait for user input.

Returns:

Type	Description
`Optional[Dict[str, str]]`	Dictionary of header field values, or None if no header fields.

WorkWithList

`ux3270.dialog.WorkWithList`

IBM 3270-style work-with list with action codes.

Displays a list of records with an Opt input field per row. Users type action codes (2=Change, 4=Delete, etc.) and press Enter to process actions.

The dialog builds a Screen definition and hands control to Screen for all rendering and input handling.

`show()`

Display the work-with list and handle user input.

Returns:

Type	Description
`Optional[List[Dict[str, Any]]]`	List of actions: [{"action": "2", "row": {...}}, ...]
`Optional[List[Dict[str, Any]]]`	Empty list if no actions selected.
`Optional[List[Dict[str, Any]]]`	None if cancelled (F3).

SelectionList

`ux3270.dialog.SelectionList`

CUA selection list for F4=Prompt functionality.

Displays a scrollable list where user can select an item by typing 'S' next to the item and pressing Enter.

Follows CUA conventions: - Panel ID at top-left, title centered - Column headers in intensified text - Action input field per row for selection (type S=Select) - F3=Cancel, F6=Add (optional), F7=Backward, F8=Forward - Enter with 'S' action code selects the item

The dialog builds a Screen definition and hands control to Screen for all rendering and input handling.

`init(title='SELECTION LIST', panel_id='', instruction='Type S to select item, press Enter')`

Initialize a selection list.

Parameters:

Name	Type	Description	Default
`title`	`str`	List title (displayed in uppercase per CUA)	`'SELECTION LIST'`
`panel_id`	`str`	Optional panel identifier	`''`
`instruction`	`str`	Instruction text	`'Type S to select item, press Enter'`

`add_column(name, width=None, align='left')`

Add a column definition.

Parameters:

Name	Type	Description	Default
`name`	`str`	Column name (used as header and key in row data)	required
`width`	`Optional[int]`	Display width (None = auto-calculate from content)	`None`
`align`	`Literal['left', 'right']`	Text alignment ("left" or "right")	`'left'`

Returns:

Type	Description
`SelectionList`	Self for method chaining

`set_add_callback(callback)`

Set callback for F6=Add.

The callback should add a new item and return it as a dictionary with the same keys as the list columns. If the callback returns an item, it will be returned as the selection. If it returns None, the selection list returns None.

Parameters:

Name	Type	Description	Default
`callback`	`Callable`	Function to call when F6 is pressed.	required

Returns:

Type	Description
`SelectionList`	Self for method chaining

`add_row(**values)`

Add a row to the selection list.

Parameters:

Name	Type	Description	Default
`**values`		Column name to value mapping	`{}`

Returns:

Type	Description
`SelectionList`	Self for method chaining

`add_rows(rows)`

Add multiple rows to the selection list.

Parameters:

Name	Type	Description	Default
`rows`	`List[Dict[str, Any]]`	List of dictionaries with column values	required

Returns:

Type	Description
`SelectionList`	Self for method chaining

`show()`

Display the selection list and wait for user selection.

Returns:

Type	Description
`Optional[Dict[str, Any]]`	Selected row as dictionary, or None if cancelled

TabularEntry

`ux3270.dialog.TabularEntry`

IBM 3270-style tabular entry with mixed static and input columns.

Displays a table where some columns are editable input fields and others are static display text. Supports multi-row data entry.

Follows CUA conventions: - Panel ID at top-left, title centered - Column headers in intensified text - Static columns in turquoise (protected) - Input columns in green with underscore placeholders - Tab navigates between editable cells - F7/F8 for pagination - Enter submits, F3 cancels

The dialog builds a Screen definition and hands control to Screen for all rendering and input handling.

`init(title='', panel_id='', instruction='Enter values and press Enter to submit')`

Initialize a tabular entry.

Parameters:

Name	Type	Description	Default
`title`	`str`	Table title (displayed in uppercase per CUA)	`''`
`panel_id`	`str`	Optional panel identifier	`''`
`instruction`	`str`	Instruction text	`'Enter values and press Enter to submit'`

`add_column(name, width=10, editable=False, field_type=FieldType.TEXT, required=False, validator=None)`

Add a column definition.

Parameters:

Name	Type	Description	Default
`name`	`str`	Column name	required
`width`	`int`	Display width	`10`
`editable`	`bool`	Whether this column is an input field	`False`
`field_type`	`FieldType`	Field type (TEXT, NUMERIC, etc.)	`TEXT`
`required`	`bool`	Whether field is required (editable columns only)	`False`
`validator`	`Optional[Callable[[str], bool]]`	Optional validation function	`None`

Returns:

Type	Description
`TabularEntry`	Self for method chaining

`add_row(**values)`

Add a data row.

Parameters:

Name	Type	Description	Default
`**values`		Column name to value mapping	`{}`

Returns:

Type	Description
`TabularEntry`	Self for method chaining

`show()`

Display the tabular entry and process user input.

Returns:

Type	Description
`Optional[List[Dict[str, Any]]]`	List of dicts with row data (original + edited values),
`Optional[List[Dict[str, Any]]]`	or None if cancelled.

MessagePanel

`ux3270.dialog.MessagePanel`

CUA-style message panel for displaying information to the user.

This is an information panel - displays a message and waits for acknowledgment (Enter or F3). No command line per CUA conventions for simple information panels.

The dialog builds a Screen definition and hands control to Screen for all rendering and input handling.

`init(message='', msg_type='info', panel_id='', title='')`

Initialize a message panel.

Parameters:

Name	Type	Description	Default
`message`	`str`	The message to display	`''`
`msg_type`	`str`	One of "error", "success", "warning", "info"	`'info'`
`panel_id`	`str`	Optional panel identifier	`''`
`title`	`str`	Optional title	`''`

`show()`

Display the message and wait for user acknowledgment.

show_message

`ux3270.dialog.show_message(message, msg_type='info', panel_id='', title='')`

Convenience function to display a message panel.

Parameters:

Name	Type	Description	Default
`message`	`str`	The message to display	required
`msg_type`	`str`	One of "error", "success", "warning", "info"	`'info'`
`panel_id`	`str`	Optional panel identifier	`''`
`title`	`str`	Optional title	`''`

Dialog Layer API

Import

Components

Form

ux3270.dialog.Form

__init__(title='', panel_id='', instruction='', help_text='')

add_field(label, length=20, field_type=FieldType.TEXT, default='', required=False, validator=None, prompt=None, help_text='')

add_text(text)

show()

Menu

ux3270.dialog.Menu

__init__(title='MAIN MENU', panel_id='', instruction='Select an option')

add_item(key, label, action)

show()

run()

Table

ux3270.dialog.Table

__init__(title='', panel_id='', instruction='')

add_column(name, width=None, align='left')

add_header_field(label, length=10, default='', field_type=FieldType.TEXT)

get_header_values()

add_row(*values)

show()

WorkWithList

ux3270.dialog.WorkWithList

show()

SelectionList

ux3270.dialog.SelectionList

__init__(title='SELECTION LIST', panel_id='', instruction='Type S to select item, press Enter')

add_column(name, width=None, align='left')

set_add_callback(callback)

add_row(**values)

add_rows(rows)

show()

TabularEntry

ux3270.dialog.TabularEntry

__init__(title='', panel_id='', instruction='Enter values and press Enter to submit')

add_column(name, width=10, editable=False, field_type=FieldType.TEXT, required=False, validator=None)

add_row(**values)

show()

MessagePanel

ux3270.dialog.MessagePanel

__init__(message='', msg_type='info', panel_id='', title='')

show()

show_message

ux3270.dialog.show_message(message, msg_type='info', panel_id='', title='')

`ux3270.dialog.Form`

`init(title='', panel_id='', instruction='', help_text='')`

`add_field(label, length=20, field_type=FieldType.TEXT, default='', required=False, validator=None, prompt=None, help_text='')`

`add_text(text)`

`show()`

`ux3270.dialog.Menu`

`init(title='MAIN MENU', panel_id='', instruction='Select an option')`

`add_item(key, label, action)`

`show()`

`run()`

`ux3270.dialog.Table`

`init(title='', panel_id='', instruction='')`

`add_column(name, width=None, align='left')`

`add_header_field(label, length=10, default='', field_type=FieldType.TEXT)`

`get_header_values()`

`add_row(*values)`

`show()`

`ux3270.dialog.WorkWithList`

`show()`

`ux3270.dialog.SelectionList`

`init(title='SELECTION LIST', panel_id='', instruction='Type S to select item, press Enter')`

`add_column(name, width=None, align='left')`

`set_add_callback(callback)`

`add_row(**values)`

`add_rows(rows)`

`show()`

`ux3270.dialog.TabularEntry`

`init(title='', panel_id='', instruction='Enter values and press Enter to submit')`

`add_column(name, width=10, editable=False, field_type=FieldType.TEXT, required=False, validator=None)`

`add_row(**values)`

`show()`

`ux3270.dialog.MessagePanel`

`init(message='', msg_type='info', panel_id='', title='')`

`show()`

`ux3270.dialog.show_message(message, msg_type='info', panel_id='', title='')`