Panel: text

Syntax

{<name>:} text {<string>}

Description

Text input sub-panel. The box may be single or multi-line.

Membership

• Panel window

• Tab window

• Table window

Parameters

• <name>
  A name to be given to the sub-panel for reference purposes.

• <string>
  The default value to appear in the input box. This can be omitted.

Switches

• -bc=<color>
  The background color for the text box. If omitted, the background color of the parent window is used.

• -c=<num>
  The width of the text box in characters. If omitted, a suitable default is computed from the values in the pulldown menu.

• -dim=<screen_xy>
  Define the dimensions of the sub-panel in pixels. This is usually redundant because text boxes are by default created sized-to-fit, but is useful when the size needs to be overridden. This is a two center element numeric array providing width and height. If only one is required, the other can be set to -1 and will be ignored.

• -er
  Extend the width of the sub-panel to the right of its parent row or column.

• -fo=<font>
  The font to be used for the text. This must be a fixed font. If omitted the text box inherits the font of its parent row or column.

• -gh
  The sub-panel should be initially ghosted, i.e. insensitive to user-interaction.

• -inv
  Make the sub-panel invisible on creation.

• -j=<just>
  The justification of the text box within its parent row or column. Within a parent row the value should be one of L, M, R. Within a parent column the value should be one of T, M or B. The default in both cases is M.

• -lim=<num>
  The maximum number of characters which can be input/displayed in the text box.

• -link=<text>
  The resize linkage for the panel. This ties panel edges to one or more edges of the parent window, with the result that when the parent window gets resized, the panel can be automatically resized as well. <text> is a combination of the characters L, R, T, B and M. A value of "LRTB" means that the left, right, top and bottom edges of a sub-panel are linked to its parent. The default value is "TL", which links the left and top edges to the parent window but does no resizing because its right and bottom edges are not linked. Note that the linkage is to edges of the parent window, not to column/row extremities. More complicated linkage requirements should be done via the window.resize callback on the parent window.

• -lv
  When the sub-panel text is defined or redefined, and its new value is too long for the text box, ensure that the left-most part of the text is visible. The default behavior is for the text to be scrolled so that the rightmost part is visible. This applies to single line text sub-panels only.

• -max=<num>
  The maximum number of text rows which may be set in the text box.

• -out
  Output only. The presence of this switch will prevent the contents of the text box being changed interactively.

• -pj=<just>
  The position justification of the sub-panel within the panel window. This combined with the -x and -y switches can be used to position the sub-panel by one of its corners. The default is 'TL'. It also defines the control point to be used when repositioning the sub-panel after creation.

• -r=<num>
  The number of rows in the text box. If this switch is present then a multiple number of rows of text may be input. The parameter <num> supplies the size of the displayed input box and does not restrict the number of text rows which may be input, unless -max is present.

• -sec
  Use this field as a password-type secret text field, so that the value is hidden from the viewer by replacing all characters with the * character as they are typed.

• -sel
  Define the focus mode as "select-on-enter", whereby whenever the panel gains the keyboard focus the whole field is selected, thus enabling it to be replaced by the the first subsequent keystroke.

• -tc=<color>
  The color for text in the text box. If omitted the parent window "other color" is used.

• -tj=<just>
  The justification of text within the text box. Possible values are 'L' for left, 'R' for right and 'M' for middle. The default is 'L'. The setting cannot be changed after panel creation.

• -w=<num>
  The width of the text box in pixels. If omitted, the width will be sized to fit.

• -ww
  Wrap words. This is active only when multiple rows are enabled (-r). The text will wrap preventing words being split across rows.

• -x=<num>
  The x position of the text box relative to the top-left corner of its parent row or column. If omitted, the text box is placed adjacent to the previously defined sub-panel.

• -y=<num>
  The y position of the text box relative to the top-left corner of its parent row or column. If omitted, the text box is placed below the previously defined sub-panel.

Callbacks

Called as the text panel is about to lose the keyboard focus. If a non-empty after callback exists for the panel, the focus remains with the panel until directed elsewhere by a focus command.

<panel>.after(<window>,<panel>{,<row>})

• Panel/Tab Window

panel.after {
    args w=window, p=panel
}

• Table Window

panel.after {
    args w=window, p=panel, row=numeric
}

Called as the text box receives the keyboard focus.

<panel>.before(<window>,<panel>{,<row>})

• Panel/Tab Window:

panel.before {
    args w=window, p=panel
}

• Table Window

panel.before {
    args w=window, p=panel, row=numeric
}

Called when:

    <Return> is hit in a single line text box,
    <Ctrl-Return> is hit in a multi-line text box.

<panel>.exec(<window>,<panel>{,<row>})

• Panel/Tab Window

panel.exec {
    args w=window, p=panel
}

• Table Window

panel.exec {
    args w=window, p=panel, row=numeric
}

Notes

Switches -j, -pj, -x and -y apply only to text boxes within a panel window. Text boxes within other windows cannot have a user-defined position or justification.

Examples

Create a panel window containing a labelled single line text box of character width. The font gets set via a row definition.

window w = wpanel {
    row -fo=big_xfont {
        label 'Name:'
        nam: text -c=32
    }
}

Create a similar text box window with color changes and an initial value.

window w = wpanel {
    row {
        label 'Name:'
        nam: text 'Beauregard',-c=32,-bc=white,-tc=red
    }
}

Create a panel window containing a multi-line text box. The maximum number of input lines is set to 10. The visible number of rows is set to 5. Word-wrap is also set.

window w = wpanel {
    t: text -c=48,-r=5,-max=10,-bc=white,-ww
}