Skip to content

Panel Layer API

The panel layer provides low-level terminal emulation. Most applications use the dialog layer, but the panel layer is available for custom components.

Import

from ux3270.panel import Screen, Field, FieldType, Colors

Screen

The Screen class is a low-level terminal emulator. It accepts a screen definition (text and fields) and handles all rendering and input.

from ux3270.panel import Screen, Field, Colors

screen = Screen()

# Add static text
screen.add_text(0, 0, "PANEL01", Colors.PROTECTED)
screen.add_text(0, 35, "MY SCREEN", Colors.INTENSIFIED)
screen.add_text(2, 2, "Enter data:", Colors.PROTECTED)

# Add input field
screen.add_field(Field(row=4, col=2, length=20, label="Name"))

# Show and get result
result = screen.show()
# result = {"aid": "ENTER", "fields": {"Name": "value"}, "current_field": "Name"}

Screen Methods

ux3270.panel.Screen

Emulates an IBM 3270 terminal screen.

The screen accepts: - Text at positions with optional colors (protected content) - Field definitions (unprotected, editable areas)

When show() is called, the terminal: - Renders all text and fields - Handles all keyboard input (field editing, navigation) - Returns when user presses an AID key (Enter, F3, etc.)

add_text(row, col, text, color=Colors.PROTECTED)

Add text to the screen at a specific position.

Parameters:

Name Type Description Default
row int

Row position (0-indexed)

 required
col int

Column position (0-indexed)

 required
text str

Text to display

 required
color str

ANSI color code (default: protected/turquoise)

 PROTECTED

Returns:

Type Description
Screen

Self for method chaining

add_field(field)

Add an input field to the screen.

Parameters:

Name Type Description Default
field Field

Field definition with position, length, type, etc.

 required

Returns:

Type Description
Screen

Self for method chaining

set_any_key_mode(enabled=True)

Enable any-key mode where show() returns on any key press.

Used for menus where single-key selection is needed.

Parameters:

Name Type Description Default
enabled bool

Whether to enable any-key mode

 True

Returns:

Type Description
Screen

Self for method chaining

show()

Display the screen and handle user input.

Returns:

Type Description
Optional[Dict[str, Any]]

Dictionary with:
Optional[Dict[str, Any]]
  • "aid": The AID key pressed (ENTER, F3, F6, etc.)
Optional[Dict[str, Any]]
  • "fields": Dict mapping field labels to values
Optional[Dict[str, Any]]

Returns None if no fields defined.

get_field_values()

Get all field values as a dictionary.

Field

Represents an input field on a screen.

from ux3270.panel import Field, FieldType

field = Field(
    row=4,
    col=10,
    length=20,
    label="Username",
    field_type=FieldType.TEXT,
    default="",
    required=False,
    validator=None,
    prompt=None
)

ux3270.panel.Field

Represents an input field on a terminal screen.

An IBM 3270 field has attributes like position, length, protected status, and can have different display attributes.

value property writable

Get the current field value.

__init__(row, col, length, field_type=FieldType.TEXT, label='', default='', required=False, validator=None, help_text='', prompt=None)

Initialize a field.

Parameters:

Name Type Description Default
row int

Row position (0-indexed)

 required
col int

Column position (0-indexed)

 required
length int

Maximum length of the field

 required
field_type FieldType

Type of field (text, password, numeric, readonly)

 TEXT
label str

Optional label to display before the field

 ''
default str

Default value

 ''
required bool

Whether the field is required

 False
validator Optional[Callable[[str], bool]]

Optional validation function

 None
help_text str

Help text shown when F1 is pressed on this field

 ''
prompt Optional[Callable[[], Any]]

Optional callback for F4=Prompt; should return selected value as string, or None if cancelled

 None

validate()

Validate the field value.

Returns:

Type Description
tuple[bool, str]

Tuple of (is_valid, error_message)

render_label_col()

Calculate the column position for the label.

CUA convention: * Label: [input field] Required fields have asterisk prefix. So we need room for: optional asterisk + label text + colon + space

FieldType

Enumeration of field types.

Value Description
FieldType.TEXT Standard text input
FieldType.NUMERIC Numbers only
FieldType.PASSWORD Hidden input (asterisks)
FieldType.READONLY Display only

Colors

Constants for IBM 3270 colors.

Constant Color Usage
Colors.DEFAULT Green Input fields
Colors.INPUT Green Input fields
Colors.PROTECTED Turquoise Labels, static text
Colors.INTENSIFIED White Titles, headers
Colors.DIM Gray Separators
Colors.ERROR Red Error messages
Colors.WARNING Yellow Warnings
Colors.SUCCESS Green Success messages

AID Keys

The result["aid"] value indicates which key was pressed:

AID Key
ENTER Enter key
F1 - F10 Function keys
PGUP Page Up
PGDN Page Down
KEY Any key (in any-key mode)