Selection List

Selection lists allow users to pick one item from a list. Type 'S' next to an item and press Enter to select it. This is commonly used for F4=Prompt functionality.

Basic Usage

from ux3270.dialog import SelectionList

sel = SelectionList("SELECT DEPARTMENT", panel_id="SEL01")
sel.add_column("Code")
sel.add_column("Name")

sel.add_row(Code="ENG", Name="Engineering")
sel.add_row(Code="SAL", Name="Sales")
sel.add_row(Code="MKT", Name="Marketing")

selected = sel.show()
if selected:
    print(f"Selected: {selected['Code']}")

Using with Form Prompts

Selection lists work well as F4 prompts in forms:

from ux3270.dialog import Form, SelectionList

def select_department():
    sel = SelectionList("SELECT DEPARTMENT")
    sel.add_column("Code")
    sel.add_column("Name")
    for dept in db.get_departments():
        sel.add_row(**dept)
    selected = sel.show()
    return selected["Code"] if selected else None

form = Form("EMPLOYEE FORM")
form.add_field("Name", length=30)
form.add_field("Department", length=10, prompt=select_department)

F6=Add Callback

Allow adding new items from the selection list:

def add_department():
    form = Form("ADD DEPARTMENT")
    form.add_field("Code", length=5, required=True)
    form.add_field("Name", length=30, required=True)
    result = form.show()
    if result:
        db.insert_department(result)
        return result  # Return as selected item
    return None

sel.set_add_callback(add_department)

Bulk Loading

Load multiple rows at once:

departments = [
    {"Code": "ENG", "Name": "Engineering"},
    {"Code": "SAL", "Name": "Sales"},
]
sel.add_rows(departments)

API Reference

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

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

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

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