Form

Forms display input fields and collect user data. They follow IBM CUA conventions with panel IDs, titles, and function key hints.

Basic Usage

from ux3270.dialog import Form
from ux3270.panel import FieldType

form = Form("DATA ENTRY", panel_id="FORM01", instruction="Enter data below")
form.add_field("Name", length=30, required=True)
form.add_field("Email", length=40)
form.add_field("Age", length=3, field_type=FieldType.NUMERIC)

result = form.show()
if result:
    print(f"Name: {result['Name']}")

Field Types

Type	Description
FieldType.TEXT	Standard text input (default)
FieldType.NUMERIC	Numbers only
FieldType.PASSWORD	Hidden input (shows asterisks)
FieldType.READONLY	Display only, not editable

Help Text

Forms support F1 help at both panel and field level:

form = Form("HELP DEMO", help_text="This is panel-level help")
form.add_field("Username", help_text="Enter your login ID")
form.add_field("Department", help_text="Your department code")

Press F1 to display help. If the cursor is on a field with help text, that field's help is shown.

F4 Prompt

Fields can have a prompt callback for selection lists:

from ux3270.dialog import Form, SelectionList

def select_department():
    sel = SelectionList("SELECT DEPARTMENT")
    sel.add_column("Code")
    sel.add_column("Name")
    sel.add_row(Code="ENG", Name="Engineering")
    sel.add_row(Code="SAL", Name="Sales")
    selected = sel.show()
    return selected["Code"] if selected else None

form = Form("ASSIGNMENT")
form.add_field("Department", length=10, prompt=select_department)
result = form.show()

Press F4 when on a field with a prompt to show the selection list.

Validation

def validate_email(value):
    return "@" in value

form.add_field("Email", validator=validate_email)

API Reference

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)