IB_FIELD
Add an input field to a new input window
WTSupported in traditional Synergy on Windows
|
WNSupported in Synergy .NET on Windows
|
USupported on UNIX
|
VSupported on OpenVMS
|
xcall IB_FIELD(build_id, field_spec[, qualifier, ...])
Arguments
build_id
The ID of the input window under construction. (n)
field_spec
The field specification for the input window field. See Field specifications for information. (a)
qualifier
(optional) One or more of the field qualifiers shown in the Field qualifiers table. (n)
IB_FIELD adds a field to a new input window being built at runtime. The maximum number of input fields in an input window or input set is 253.
IB_FIELD’s options are also available with the .FIELD script command. For more detailed information on IB_FIELD options, see the corresponding qualifier in .FIELD qualifiers. |
Defaults are used for qualifiers that are not specified. If IB_RPS_STRUCTURE has been called prior to IB_FIELD, default values will be drawn from the repository, and the field must exist in the repository or a fatal error will occur. For notes on fields drawn from repositories, see Using .FIELD with .REPOSITORY_STRUCTURE.
If you specify a qualifier that does not apply to the field’s destination type, it is ignored. (Integer fields support all qualifiers that are valid for decimal fields without precision.)
Any D_FLD_xxx qualifier not listed will result in the fatal error “Invalid IB_FIELD code (code),” where code is the invalid value passed.
Qualifier and argument |
Definition |
---|---|
D_FLD_TYPE, type |
Field type. See D_FLD_TYPE for valid values for type. |
D_FLD_SIZE, storage_size |
Storage size. See D_FLD_SIZE for size limits. |
D_FLD_DEC, num_places |
Decimal places. |
D_FLD_DIM, dim_size |
Dimension. Only single dimension alpha arrays are supported. |
D_ON |
Turn on one or more of the following field qualifiers. See D_ON and D_OFF for details. (default) |
D_OFF |
Turn off one or more of the following field qualifiers. When qualifiers are preceded by D_OFF, flags that normally require a following argument do not need one. See D_ON and D_OFF for details. |
D_FLD_ALLOW, num_entries, entry_array |
Allow list. |
D_FLD_ARRIVE, arrive_method |
Arrive method. |
D_FLD_ATTR, attribute |
Attributes. See D_FLD_ATTR for valid values for attribute. |
D_FLD_AUTO |
Auto entry. |
D_FLD_BREAK |
Cause break processing to occur when the field is changed. See BREAK, NOBREAK for more information. |
D_FLD_BRK_ALWAYS |
Cause break processing to occur every time the user leaves the field. See BREAK, NOBREAK for more information. |
D_FLD_BRK_RTRN |
Cause break processing to occur only when the field is changed or Enter is pressed. See BREAK, NOBREAK for more information. |
D_FLD_BZRO |
Blank if zero. |
D_FLD_CASE |
Match case. |
D_FLD_CHANGE, change_method |
Change method. |
D_FLD_CHECKBOX |
Check box. |
D_FLD_COLOR, palette# |
Color. |
D_FLD_COPY |
Copy default. |
D_FLD_DATE, date_type |
Date field. See D_FLD_DATE for valid values for date_type. |
D_FLD_DECR |
Decrement default. |
D_FLD_DISABLED |
Disabled. |
D_FLD_DISPLAY, display_method |
Display method. |
D_FLD_DFLT, default_string |
Default entry. |
D_FLD_DRILL, drill_method |
Drill method. |
D_FLD_DSPLEN, display_len |
Display length. Cannot be specified for check boxes, radio buttons, selection windows, or multi-line text fields. |
D_FLD_EDITFMT, editfmt_method |
Edit format method. |
D_FLD_ENUM, dsp_len,[base],[step] |
Enumeration properties. |
D_FLD_EXACT |
Match exact. |
D_FLD_FMT, string |
Format string. |
D_FLD_FONT, font_id |
Field font. See D_FLD_FONT and D_FLD_PROMPTFONT for valid values for font_id. |
D_FLD_FPOS [, D_CHANGE], row, col |
Field position. |
D_FLD_HELP, help_id |
Help identifier. |
D_FLD_HYPERLINK, hyper_method |
Hyperlink method. |
D_FLD_INCR |
Increment default. |
D_FLD_INFO, string |
Information text. |
D_FLD_INPLEN, input_len |
Maximum input length. Cannot be specified for check boxes, radio buttons, selection windows, or multi-line text fields |
D_FLD_JUST, just_flag |
Justification, where just_flag is D_JST_CENTER, D_JST_LEFT, or D_JST_RIGHT. |
D_FLD_LEAVE, leave_method |
Leave method. |
D_FLD_NEG |
Negative allowed. |
D_FLD_NEGONLY |
Negative allowed only. |
D_FLD_NEGORZERO |
Negative or zero allowed only. |
D_FLD_NODEC |
No decimal required. |
D_FLD_NOECHO |
No echo. |
D_FLD_NOECHR, char |
Fill character when D_FLD_NOECHO is specified (otherwise ignored). |
D_FLD_NOTERM |
No termination required. |
D_FLD_PAINT, char |
Paint character. |
D_FLD_POS [, D_CHANGE], row, col |
Prompt position. |
D_FLD_PROMPT, prompt_string |
Prompt. |
D_FLD_PROMPTFONT, font_id |
Prompt font. See D_FLD_FONT and D_FLD_PROMPTFONT for valid values for font_id. |
D_FLD_PROMPTLEN, length |
Runtime prompt. |
D_FLD_RADIO |
Radio buttons. See D_FLD_RADIO. |
D_FLD_RANGE, min, max |
Range for numeric field. If you use variables for the min and max arguments, they must be alpha variable; decimal variables will not work. |
D_FLD_READONLY |
Read-only. |
D_FLD_REQUIRED |
Required entry. |
D_FLD_RETPOS |
Retain position in text field. |
D_FLD_SELECT, row, col, numrows, [numcols], num_entries, entry_array |
Selection list. On Windows, use with D_FLD_RADIO to specify radio buttons or without to specify a combo box. For the former, see D_FLD_RADIO. |
D_FLD_SELWND, row, col, window_name |
Selection window. On Windows, use with D_FLD_RADIO to specify radio buttons or without to specify a combo box. For the former, see D_FLD_RADIO. |
D_FLD_TIME, time_type |
Time field. See D_FLD_TIME for valid values for time_type. |
D_FLD_TIMESTAMP, format |
Timestamp field. See D_FLD_TIMESTAMP for details on this option and valid values for format. |
D_FLD_UC |
Uppercase only. |
D_FLD_USER, string |
User-defined text string. |
D_FLD_VIEWLEN, view_length |
The width of the field (i.e., the width of the area on the screen that will display data for the field). Cannot be specified for check boxes or radio buttons |
D_FLD_WAIT, wait_time |
Input time-out for the field. See D_FLD_WAIT for valid values for wait_time. |
D_FLD_TYPE supports the following options for type:
D_ALPHA |
Alphanumeric |
D_DECIMAL |
Decimal |
D_INTEGER |
Integer |
D_NUMERIC |
Numeric (same as decimal) |
D_USERTYPE, type_string |
User-defined |
If you use D_FLD_TYPE to change the field to D_INTEGER type, the storage size is changed to the nearest (but not larger) valid integer storage size. Supported sizes are 1, 2, 4, and 8. Integer fields support all qualifiers that are valid for decimal fields without precision.
Alpha and alpha arrayed fields can have up to 65,535 characters. Decimal fields (including implied decimal fields) have a maximum size of 28, and for implied-decimal fields, up to 28 digits can follow the decimal point. Integer fields on any operating system can have 1, 2, 4, or 8 digits, depending on size. If the size is not correct, Toolkit will ignore the field.
If IB_FIELD creates a text field that is too large for the window, a warning will display only if g_dtkbounds is set to a value of 2 or greater. See g_dtkbounds.
The D_ON and D_OFF codes indicate whether the field qualifiers that follow in the argument list are to be turned on or off. D_ON is the default state for any qualifiers listed.
When qualifiers are preceded by D_OFF, flags that normally require a following argument do not need one. Thus, a prompt defined with the following call to IB_FIELD
xcall ib_field(bldid, "myfield", D_FLD_PROMPT, "Help")
can be turned off with the following:
xcall ib_field(bldid, "myfield", D_OFF, D_FLD_PROMPT)
Even though the prompt defined above is a text prompt, it could also be turned off by using D_OFF with D_FLD_PROMPTLEN. This is because, when used with either D_FLD_PROMPT or D_FLD_PROMPTLEN, D_OFF always turns off the specified prompt, regardless of its type (text or runtime).
Turning off D_FLD_BRK, D_FLD_BRK_ALWAYS, or D_FLD_BRK_RTRN results in no break for the field.
D_FLD_ATTR accepts the following values for attribute (defined in tools.def):
A_ALL |
All attributes (same as A_BHRU) |
A_NONE |
No attributes |
A_B | A_I |
Blinking (UNIX and OpenVMS) or italic (Windows). |
A_BH |
Blinking, highlighted |
A_BHR |
Blinking, highlighted, reverse |
A_BHRU |
Blinking, highlighted, reverse, underlined |
A_BHU |
Blinking, highlighted, underlined |
A_BR |
Blinking, reverse |
A_BRU |
Blinking, reverse, underlined |
A_BU |
Blinking, underlined |
A_H |
Highlighted |
A_HR |
Highlighted, reverse |
A_HRU |
Highlighted, reverse, underlined |
A_HU |
Highlighted, underlined |
A_R |
Reverse |
A_RU |
Reverse, underlined |
A_U |
Underlined |
D_FLD_DATE accepts the following values for date_type:
D_DATE_Y2J |
YYJJJ date format |
D_DATE_Y2MD |
YYMMDD date format |
D_DATE_Y2P |
YYPP date format |
D_DATE_Y4J |
YYYJJJ date format |
D_DATE_Y4MD |
YYYYMMDD date format |
D_DATE_Y4P |
YYYYPP date format |
To make the field default to the today’s date, add D_DATE_TODAY to any of the above. For a short date, add D_DATE_SHORT to any of the above. (You can add both of these if desired,)
D_FLD_FONT and D_FLD_PROMPTFONT
The font_id argument to D_FLD_FONT and D_FLD_PROMPTFONT can be the name of a font palette entry, a font handle, or one of the following:
DF_ALTERNATE |
Alternate font |
DF_CURRENT |
Current font |
DF_DEBUGGER |
Debugger font |
DF_DEFAULT |
Global font |
On Windows, use D_FLD_RADIO with either D_FLD_SELECT or D_FLD_SELWND to specify a field that is a group of radio buttons. (If you use D_FLD_SELECT or D_FLD_SELWND without specifying D_FLD_RADIO on Windows, the field will be a combo box.)
- If you use D_FLD_SELECT with D_FLD_RADIO, the numrows argument for D_FLD_SELECT determines how may radio buttons can fit in a column. If numrows is not passed, the radio buttons will be placed vertically in a single column.
- If you use D_FLD_SELWND with D_FLD_RADIO, the height of the associated selection window determines how many buttons can fit in a column. You can control spacing between radio button columns by changing the column width for the selection window. This spacing is calculated by adding the width of the radio button to the width of a column in the selection window (which is equal to the number of characters times the character width for the font).
For more information on radio buttons, see RADIO, NORADIO .
D_FLD_TIME accepts the following values for time_type:
D_TIME_HM |
HHMM time format |
D_TIME_HMS |
HHMMSS time format |
To make the field default to the current time, add D_TIME_NOW to either of the above. To add AM/PM to the display, add D_TIME_AMPM to either of the above. (You can add both of these if desired.)
By default, an autotime or ctimestamp field from a repository results in a timestamp field in a Toolkit application. However, you can use D_FLD_TIMESTAMP with D_OFF to create a standard integer field from a repository autotime field or with D_ON to create a timestamp field from scratch or from a standard repository 8-byte integer field.
When D_OFF is in effect, do not use the format argument. (It will be interpreted as another qualifier.)
When D_ON is in effect, D_FLD_TIMESTAMP must be followed by the format argument, which enables you to change the formatting used for a timestamp field. The format argument can be one or both of the following, or 0 (for neither):
D_TIMESTAMP_AMPM |
Use 12-hour notation and AM/PM designation |
D_TIMESTAMP_SHORT |
Use short display format (no century, seconds, or milliseconds) |
To specify both D_TIMESTAMP_AMPM and D_TIMESTAMP_SHORT, use the bitwise OR operator (.BOR. or |) or add them. If a flag isn’t passed, it will be reset to its default value. For example, if you don’t pass D_TIMESTAMP_SHORT, the long display format will be used even if the field was previously set to use the short format.
For D_ON, D_FLD_TYPE must be set to D_INTEGER, and the field must be a read-only, 8-byte integer. It cannot be a selection field, a radio button set, or a check box. Otherwise, an error will occur.
The wait_time argument to D_FLD_WAIT can be the number of seconds to wait or one of the following:
D_FOREVER or -1 |
Wait until I/O processing is completed |
D_GLOBAL or -2 |
Use the globally specified time-out |
D_IMMEDIATE or 0 |
Time out immediately |
See also
- .FIELD script command
- Renditions for information and notes on setting field-level renditions
- I_FLDMOD routine to modify an existing field at runtime
- Basic field information for information on using implicit groups to combine repository structures
- Using fonts on Windows for information on fonts and font palettes
Examples
The following example adds the field company to the current input window being built. It is an alpha field, 15 characters long.
xcall ib_field(bldid, "company", D_FLD_TYPE, D_ALPHA, D_FLD_SIZE, 15)
The next example adds the field age to the current input window being built. It is a three-digit decimal field, which the user is required to input. The field will prompt the user with the string “Enter your age.”
xcall ib_field(bldid, "age", D_FLD_TYPE, D_DECIMAL, D_FLD_SIZE, 3, & D_FLD_REQUIRED, D_FLD_PROMPT, "Enter your age ")
The following example adds the field date[2,6] to the current input window being built. It is an eight-digit decimal field from an array named date defined in a repository named cusmas. Note that the IB_FIELD call specifies the format (YYYYMMDD), information that Toolkit does not import from the repository. The field will default to today’s date if the user presses Enter without entering any data.
xcall ib_rps_structure(bldid, "cusmas") xcall ib_field(bldid, "date[2,6]",D_FLD_DATE, D_DATE_Y4MD+D_DATE_TODAY)