Screens: @Layout and Screen

A Screen is an interactive 5250 screen: it defines its layout (@Layout) and reacts to user events (@Source).

1. Minimal structure

@Properties {
    Type : Screen
    Name : SFORM01
    Description : "Sample screen"
    Path : Screens
}
@References {
    Tables = ["../tables/TLADD50.warp"]
}
@Variables {
    Global {
        Username char(10)
        MyDate   Date
    }
}
@Parameters {
}
@Layout {
    @Label(1,2,&Username)
    @Label(1,70,&MyDate)
    @Input("txtRequestNo", 3, 1, "Request No.: ", &RequestNo, true)
}
@Source {
    Event Init
        &Username = UserId()
        &MyDate   = Today()
    EndEvent
}

Unlike a Program, a Screen doesn’t have its own @Structure — it only references tables to read/write.

Screen parameters

The @Parameters block in the example is empty, but a Screen (full screen or Popup) can declare it just like a Program: @Parameters { in:&X, inout:&Y, out:&Z }. Values are available from Event Init and the Screen is invoked with Call(Name, ...). In a Popup it is used to receive data and return the user’s selection. See @Parameters.

2. @Layout controls

• Label(x, y, text): static text/variable. x,y = 1,1 (exact corner) is forbidden — DDS rejects it.

• Input("Name", x, y, text, &Variable, enabled): editable field. "Name" is what CurrentInput() returns when the cursor lands there. enabled is optional (default true): a literal, &Variable, a Function() returning number, or a full condition (Not &Locked = 1 And &Status <> "9").

  If the variable is char/varchar, the field accepts lowercase and the program receives what was typed as is (Lima, not LIMA); to ignore the difference when comparing, use Upper(&field). Numeric, date and time Input fields are unchanged.

• DataGridView("Name", x, y, rows)[...]: grid — see DataGridView.

Control names can be prefixed with @ (@Label, @Input) or not — it’s purely stylistic, same meaning.

Available width and error E00353

No element may end beyond the last column of the screen: 80 by default, 132 if the project declares that size, or the window width in a popup. Ending exactly on the last column fits. If it does not fit, the compiler reports E00353 (IBM i would reject the field or split it across two rows). The width of each element is computed as follows:

• Label: the length of the text.

• Input: the label + 1 space + the width of the variable.

• DataGridView: the sum of the widths of its visible columns, plus the gap between each pair of contiguous columns. A column’s width is the larger of the header and the data. The gap is the declared separator or, if there is none or it is shorter, at least 1 position (a space). Hidden columns do not count: they are declared as hidden subfile fields, with no line or position on the screen.

  In 5250 every field carries an attribute byte right before its first character; without that free position, a column’s attribute byte would overlap the last character of the previous one (CPD7866) and the column would not be displayed. So, with no separator, each column sits one position further right than the previous one.

  Example: three columns of 6, 20 and 15 positions, with no separator, take 6 + 1 + 20 + 1 + 15 = 43 positions; with the grid at column 2 they end at column 44.

The column where the element ends is x + width - 1; if it exceeds the maximum, shorten the text or the widths, or move the element to the left.

Color and attributes with Style

Label, Input and Column (of a DataGridView) accept one or more trailing Style(...) entries with a color (Green, White, Red, Blue, Yellow, Pink, Turquoise) and attributes (Reverse, High, Underline, Blink, Hidden). A Style can end with a condition, in which case it applies only while the condition holds:

Label(1,2,&Title,Style(Reverse,High))
Label(5,2,&Desc,Style(Red,&Status = "9"),Style(Green))
Input("TxtOp",7,2,"Operation:",&Op,Not &Locked = 1,Style(Yellow,Underline))

Each element accepts at most one Style without a condition and up to three with a condition. In a Column the condition is evaluated per row, at the time of LoadRow(), with the values the variables hold at that instant (assign them before LoadRow()); the color is stored with the row:

Column("Quantity",&VQty,Style(Red,High,&VQty > 100),Style(Green))

Per-row dynamic enabling (a conditional Column(..., Input)) does not exist yet. Full details in @Layout: Style.

3. Standard events

@Source {
    Event Init
        &Username = UserId()
    EndEvent

    Event Load
        For Each In LADD50 Index LADD5010
        Where SPT25COUNTRY = &nCountry
            &cState = ADSTS50
            LoadRow()
        EndFor
    EndEvent

    Event Enter
        &Control = CurrentInput()
        Message("Active control: " + &Control, Info)
    EndEvent
}

Two statements help control the screen from any event: &Variable.SetFocus() places the cursor on an Input, and Refresh / Refresh Keep reload the DataGridView. See @Source: Event and Screen.

4. Custom function keys

Besides the standard events, you can attach an event to any F1-F24 key (F13-F24 via Shift):

@Source {
    Event 'FindCustomer' 4
        Message("F4 was pressed", Info)
    EndEvent
}

By default, the function-key line shows the event name (F4=FindCustomer). To show a different text, add it in quotes after the key (up to 20 characters):

Event 'FindCustomer' 4 "Find"

The event name ('FindCustomer') becomes the name of an RPG subprocedure, so it must be an identifier: letters, digits and _, starting with a letter (E00357). Text with spaces goes in the third value: Event 'Delete' 7 "Delete row".

This text takes precedence over the one declared in the project’s .warpcfg @FunctionKeys — see Project.

Position and color of the key line

By default the line is drawn at Rows - 1 (row 23 on a 24x80 screen; in a popup, the window’s last row minus one). Function Keys Row picks another row, and Function Keys Color colors the whole line. Both are declared in @GeneratorConfig/@Screen (project-wide) or in a Screen’s @Properties (that object only, and it wins over the project):

@Properties {
    Type               : Screen
    Name               : SCUSTOMERS
    Function Keys Row  : 22
    Function Keys Color: Blue
}

The row must be between 1 and Rows - 1 (the last one is kept for messages); otherwise E00346 is reported. The compiler does not warn if the row overlaps the @Layout: leave it free. An invalid color gives E00347.

Each Event can carry its own color at the end, which wins over the line’s:

Event 'Delete' 7 "Delete" Red

The colors are Green, White, Red, Blue, Yellow, Pink and Turquoise.

Key rotation with F24

If F24 is declared in @FunctionKeys (for example F24 : "More keys") and no Event uses it, the keys that do not fit in one line are split into rotating sets. With F3 : "Exit", F5 : "Refresh" and the events Event 'Home' 6, Event 'Output' 7, Event 'Cursor' 8 and Event 'After' 9 "After Refresh":

Set 1: F3=Exit  F5=Refresh  F6=Home  F7=Output  F8=Cursor  F24=More keys
Set 2: F9=After Refresh  F24=More keys

Each set fits in a single line (screen width minus 2 columns; the window width in a popup), keys are ordered by number and every set ends with F24. Pressing F24 shows the next set and after the last one it returns to the first; the keypress only changes the key line and does not run any event. If all keys fit in one line there is no rotation. If F24 is not declared, or an Event uses it, the line shows all keys in one or two lines.

5. Messages to the user

Message("Rows found: " + String(&nRows, 5), Info)

Error (red), Warning (yellow), Info (normal color). Shown on the next refresh and cleared after one cycle.

6. Next step

If the screen needs to show a list of rows with selection/pagination, see DataGridView.