Manipulate field sets within a window
|
WSupported on Windows
|
USupported on Unix
|
VSupported on OpenVMS
|
NSupported in Synergy .NET
|
xcall W_FLDS(id, function, arguments[, function, arguments][, ...])
Arguments
id
A variable that contains the window ID. The ID must be the same as the one specified in the WP_CREATE function. (n)
function
One or more of the following functions, which are divided into two categories, window field set functions and user data set functions.
Window field set functions:
WF_ATTR = Alter character attributes in the field.
WF_COLOR = Set the window field’s color.
WF_CREATE = Create a set of window fields.
WF_FILL = Fill a window field with a specified character.
WF_GET = Get data from a window field.
WF_INPUT = Perform window field input.
WF_PARAM = Return the position and length of a window field.
WF_POS = Set the current window position.
WF_PUT = Put data in a window field.
WF_SET = Set the position and length of a window field.
WF_WAIT = Set input time limit.
User data set functions:
WF_UGET = Get data from a user data set window field.
WF_UPUT = Put data into a user data set window field.
WF_USER = Create a user data set.
WF_USERID = Change the active user data set.
arguments
(optional) Any arguments used by the specified function.
Discussion
W_FLDS manipulates a set of fields in a window. It enables you to retrieve data from, load data into, and modify the attributes of regions in a window, without affecting any other portion of the window. We call these regions window fields. Window fields are one-row-high regions characterized by their length and position in the window. A window field has no relation to the data fields you define in the data division of your program.
With W_FLDS you can create a single window field or window field sets. Each window field has a height of one row and a length ranging from one column to the width of the window. The length, position, data, and attributes of a window field, or an entire window field set, can be modified by W_FLDS. These changes become visible with the next screen update (if the window is placed and the window field is not occluded).
If you use ^VARARGARRAY, function is the last declared argument for this routine.
Many of the window field set functions for W_FLDS require a field_number argument, which can be one of the following values:
|
number |
A numeric expression that references the window field specified by number. |
|
WFN_ALL |
References all fields. |
|
WFN_FIRST |
References the first field. |
|
WFN_LAST |
References the last field. |
|
WFN_NEXT |
References the next field. |
|
WFN_CURR |
References the current field. |
|
WFN_PREV |
References the previous field. |
If number is specified, it wraps around the last field. For example, if you create 15 fields, a field_number of 18 references field number 3.
For all functions except WF_FILL, WF_ATTR, and WF_COLOR, the value WFN_ALL is the same as WFN_FIRST.
If you specify the current field (WFN_CURR) and the last field was WFN_ALL, all fields are affected if the function allows it. If the function doesn’t allow it, WFN_CURR is the same as WFN_FIRST.
If you use WFN_NEXT and the last field number was WFN_ALL, WFN_NEXT is the same as WFN_FIRST.
If you specify WFN_PREV and the last field specified was WFN_ALL, WFN_PREV is the same as WFN_LAST.
The user data set functions are WF_UGET, WF_UPUT, WF_USER, and WF_USERID. A user data set is information that you can associate with a window for your own use. You completely control and maintain the parameters and contents of this information. Conceptually, a user data set is a one-dimensional alpha array. The WF_USER function is used to create the array; WF_UPUT writes elements to the array; and WF_UGET reads elements from the array. WF_USERID changes the active data set for a window.
WF_ATTR, field_number, attributes
WF_ATTR alters the attributes of the characters in the window starting at the row and column of the specified window field for the length of the field. See The field_number argument for possible values for field_number. If field_number is WFN_ALL, the attributes of all fields are altered. See Attributes for a description of standard window attributes.
WF_COLOR, field_number, color
WF_COLOR alters the window field’s color starting at the row and column of the specified window field for the length of the field. See The field_number argument for possible values for field_number. If field_number is WFN_ALL, the color affects all fields. Color is a decimal variable that contains a palette number between 1 and 16. See Colors and the color palette for more information about color.
WF_CREATE, num_fields
WF_CREATE sets a number of window fields and a default length and width, where num_fields is the number of fields to create. The first window field’s parameter is set to the first row of the processing area; the second window field’s parameter is set to the second row of the processing area; and so forth. If the number of window fields is greater than the number of rows, the extra fields are set to the last row. (You can change the parameters of the individual window fields with the WF_SET function.)
The WF_CREATE function replaces any existing window field set, so that the number of created fields is not cumulative. For example, if you create a set of three window fields with one WF_CREATE function and then you create a set of five window fields with a second WF_CREATE function, you get a total of five window fields, not eight.
In the following example we create three fields with WF_CREATE and then fill them with the letter “a.” Notice that the field occupies the width of the total area; for shorter fields, you must set the field length with WF_SET.
.define MAXWINS, 15
.define WNDCHNL, 1
.include "WND:windows.def"
record
wndw_1 ,i4
proc
open(WNDCHNL, o, "tt:")
xcall w_init(0, WNDCHNL, MAXWINS)
xcall w_proc(WP_CREATE, wndw_1, "window1", 11, 50)
xcall w_area(wndw_1, WA_FILL, ".")
xcall w_proc(WP_PLACE, wndw_1, 12, 15)
xcall w_updt
sleep 1
xcall w_flds(wndw_1, WF_CREATE, 3, WF_FILL, WFN_ALL, "a")
xcall w_exit
stop
end
WF_FILL, field_number, character
WF_FILL outputs the first character in character to the window starting at the row and column of the specified window field for the length of the field. The output characters have the default display attributes. See The field_number argument for possible values for field_number. If field_number is WFN_ALL, all fields are filled with the specified character.
In this subroutine, we first create four fields and fill them all with the letter “a.” Next, we create five fields. (Because the second WF_CREATE function overrides any previous WF_CREATE function, we have a total of five fields, not nine fields.) We fill all the fields with the letter “b” before creating six fields and filling them with the letter “c.” Since the processing area is too small to hold six fields, fields 5 and 6 are both set to the bottom row.
.define MAXWINS, 15
.define WNDCHNL, 1
.include "WND:windows.def"
record
wndw_1 ,i4
proc
open(WNDCHNL, o, "tt:")
xcall w_init(0, WNDCHNL, MAXWINS)
xcall w_proc(WP_CREATE, wndw_1, "window1", 11, 50)
xcall w_area(wndw_1, WA_SET, 5, 11, 5, 30, WA_FILL, ".")
xcall w_proc(WP_PLACE, wndw_1, 12, 15)
call pause
xcall w_flds(wndw_1, WF_CREATE, 4, WF_FILL, WFN_ALL, "a")
call pause
xcall w_flds(wndw_1, WF_CREATE, 5, WF_FILL, WFN_ALL, "b")
call pause
xcall w_flds(wndw_1, WF_CREATE, 6, WF_FILL, WFN_ALL, "c")
call pause
xcall w_exit
stop
pause,
xcall w_updt
sleep 1
return
end
WF_GET, field_number, alpha_field
WF_GET transfers data from a window, starting at the row and column of the specified window field for the length of the field. This function does not obtain input from the terminal. WF_GET and WF_PUT only transfer the contents of window fields. See The field_number argument for possible values for field_number.
The following routine creates four fields and then accepts input from the user. It uses WF_GET to transfer the window data, starting at the row and column of the window field for the length of the field, and store it in beta. The field Beta contains whatever the user types in, along with dots, because the field in this example is as wide as the processing area, which has been filled with dots.
.define MAXWINS, 15
.define WNDCHNL, 1
.include "WND:windows.def"
record
wndw_1 ,i4
alpha ,a20
beta ,a20
proc
open(WNDCHNL, o, "tt:")
xcall w_init(0, WNDCHNL, MAXWINS)
xcall w_proc(WP_CREATE, wndw_1, "window1", 11, 20)
xcall w_area(wndw_1, WA_FILL, ".")
xcall w_proc(WP_PLACE, wndw_1, 12, 15)
xcall w_flds(wndw_1, WF_CREATE, 4)
xcall w_disp(wndw_1, WD_POS, 1, 1, WD_READS, alpha)
xcall w_flds(wndw_1, WF_GET, WFN_NEXT, beta)
xcall w_exit
stop
end
WF_INPUT, field_number, mode, length, curr_pos, min_pos, status
|
On Windows, WF_INPUT is supported through UI Toolkit. We do not recommend direct use of WF_INPUT. |
WF_INPUT performs terminal input using a window field, where field_number is the window field to use. See The field_number argument for possible values for field_number. WF_INPUT performs an automatic W_UPDT.
Mode defines the properties of the input operation. It can be one or more of the following options, with multiple modes combined using .BOR. or a vertical bar (|):
|
WFI_INSRT |
Perform input in insert mode. |
|
WFI_NODEL |
Terminate when the delete character (rubout) is entered. |
|
WFI_PRELOAD |
Use entering status value as the first input character. |
|
WFI_TFULL |
Terminate when the input field is full. |
|
WFI_TOVRFL |
Terminate when the input field overflows. |
|
WFI_TOCCL |
Terminate when the cursor is occluded. |
|
WFI_TUNDFL |
Terminate when input field underflows. |
|
WFI_GUI |
Return menu ID in extra argument. (traditional Synergy on Windows only) |
Length specifies the number of characters that are already in the window field on entry, and is set to the number of characters within the field on exit. The valid values for length are between zero and the size of the window field.
Curr_pos specifies the current cursor position on entry, and is set to the final cursor position on exit. The valid values for curr_pos are between one and the size of the field plus one. Curr_pos cannot be greater than one more than length on entry.
Min_pos is the minimum cursor position that is to be allowed within the window field. The valid values are the same as for curr_pos. Min_pos cannot be greater than the entering value of curr_pos.
Status is the resulting status of the operation. If you set WFI_PRELOAD, the value of status on entry is automatically processed as the ASCII value of the first character to be input; on exit, the value is set to one of the following options:
|
0 |
A terminating character was entered. |
|
WFI_SEID |
GUI menu selection ID was returned. |
|
WFI_SFULL |
Mode included WFI_TFULL and the input field is exactly full. |
|
WFI_SOVRFL |
Mode included WFI_TOVRFL; the input field is full; and an additional, nonterminating character was typed. |
|
WFI_SUNDFL |
Mode included WFI_TUNDFL, curr_pos is equal to min_pos, and a delete character was typed. |
|
WFI_SNOTPL |
The window containing the input field is not placed, and no operation has occurred. |
|
WFI_SOCCL |
The cursor or field is, or has become, occluded. |
|
WFI_SINVIS |
The window’s display area does not include the input field, and no operation has occurred. |
|
WFI_STMOUT |
Operation was terminated on input time-out. |
If mode includes WFI_NODEL, all activation characters are considered terminating characters; however, if mode does not include WFI_NODEL, Backspace and Rubout (ASCII characters 8 and 127) are considered to be delete characters.
If mode does not contain WFI_TOCCL and the window field is not completely within the window’s display area or occluded in any way by any other placed window, no input occurs and WFI_SOCCL status is set. However, if mode contains WFI_TOCCL, only the current cursor position must be visible within the window field, and a WFI_SOCCL termination occurs only when the cursor is no longer visible (either initially or during input processing).
If length is nonzero on entry, the windowing system assumes that length characters are currently displayed within the window field.
If there is room within the field and a nonterminating character is typed, the following occurs if WFI_INSRT is set:
- If curr_pos is less than or equal to length, the text is redisplayed within the window field from position curr_pos through the end of the field minus one, one position to the right.
- The typed character is displayed at curr_pos within the field, with the window’s current display attributes.
- Curr_pos and length are incremented.
However, if WFI_INSRT is not set, the following occurs:
- The typed character is displayed at curr_pos within the field, with the window’s current display attributes.
- Length is incremented if it is less than curr_pos.
- Curr_pos is incremented.
If there is not room within the field, mode does not contain WFI_TFULL or WFI_TOVRFL, and a nonterminating character is typed, the terminal bell rings and the character is ignored.
If curr_pos is greater than min_pos, mode does not include WFI_NODEL, and a delete character is typed, the following occurs if WFI_INSRT is set:
- If curr_pos is less than or equal to length, the text is redisplayed within the window field from positions curr_pos through the end of the field, one position to the left.
- If length is greater than its entering value, the “recovered” character is redisplayed at the field’s end; otherwise, a blank is displayed with the window’s current attributes.
- Curr_pos and length are decremented.
However, if WFI_INSRT is not set, the following occurs:
- A blank is displayed at curr_pos within the field, with the window’s current display attributes.
- Length is decremented if it is less than curr_pos.
- Curr_pos is decremented.
If curr_pos is equal to min_pos, mode does not include WFI_NODEL or WFI_TUNDFL, and a delete character is typed, the terminal bell rings and the character is ignored.
If the returned status is zero or WFI_SOVRFL, %RTERM (or %RDTRM) returns the ASCII value of the character that caused the termination. If mode contained WFI_TOCCL and the returned status is WFI_SOCCL, %RTERM (or %RDTRM) is either zero, if the cursor was not initially visible, or the character that caused the cursor to be invisible during input processing.
Setting flag #5 in the FLAGS subroutine causes no echoing to occur during input. On Unix and OpenVMS, the characters are stored in the window’s character array. If the area of the screen containing the input is caused to be redrawn, the non-echoed characters are displayed. Following the WF_INPUT, we suggest you perform a WF_GET to retrieve the input followed by a WF_PUT of new characters.
On Windows, input done through WF_INPUT overrides the WF_ATTR and WF_COLOR subroutines since WF_INPUT uses a native edit control.
WF_PARAM, field_number, row, column, length
WF_PARAM returns the row, column, and length of the specified field. See The field_number argument for possible values for field_number.
This subroutine positions to a field in a window and accepts input for the length of the field. It assumes the window system was initialized in an earlier routine. The subroutine uses WF_PARAM to obtain the position and length of the field.
subroutine fld_input
wndid ,n
fld_num ,n
data ,a
.include "WND:windows.def"
record
frow ,i4
fcol ,i4
flen ,i4
proc
xcall w_flds(wndid, WF_PARAM, fld_num, frow, fcol, flen)
xcall w_disp(wndid, WD_POS, frow, fcol, WD_READS, data(1:flen))
return
endsubroutine
WF_POS, field_number
WF_POS sets the current window position to the row and column of the specified field. See The field_number argument for possible values for field_number.
WF_PUT, field_number, alpha_field
WF_PUT transfers data from the alpha field to the window, starting at the row and column of the specified window field for the length of the field. The output data has the current default display attributes. The data won’t be displayed until the window is updated. If the alpha field is longer than the window field, only the characters that fit are loaded into the field. See The field_number argument for possible values for field_number.
The following example uses the WF_PUT function to display selections. Notice that if you haven’t used a field yet, WFN_NEXT is the same as WFN_FIRST.
.define MAXWINS, 15
.define WNDCHNL, 1
.include "WND:windows.def"
record
wndw_1 ,i4
proc
open(WNDCHNL, o, "tt:")
xcall w_init(0, WNDCHNL, MAXWINS)
xcall w_proc(WP_CREATE, wndw_1, "window1", 11, 50)
xcall w_area(wndw_1, WA_FILL, ".")
xcall w_proc(WP_PLACE, wndw_1, 12, 15)
xcall w_flds(wndw_1, WF_CREATE, 4,
& WF_PUT, WFN_NEXT, "Selection one",
& WF_PUT, WFN_NEXT, "Selection two",
& WF_PUT, WFN_NEXT, "Selection three",
& WF_PUT, WFN_NEXT, "Last selection")
call pause
xcall w_exit
stop
pause,
xcall w_updt
sleep 1
return
end
WF_SET, field_number, row, column, length
WF_SET redefines the row, column, and length of the specified window field. See The field_number argument for possible values for field_number. Row and column specify the position where the field begins within the window. Length indicates the length of the field. If length is an alpha string, the field is as long as that string, and it contains the alpha string. If length is numeric, it indicates the number of characters in the field.
If length is a numeric expression, the length of the window field is set equal to length. If length is an alpha expression, the length is set to the length of the expression and a WF_PUT of the text is executed.
If the field is too long for the window, it is truncated so that it fits.
In the example below, we set four window fields, using the length of the alpha field we want to display to define the length of the field. Notice that at the first WF_SET function, we use WFN_NEXT for the field number when we intend to set the first field. When you’ve created fields that aren’t yet displayed, WFN_NEXT is the same as WFN_FIRST. When you’re on the last field, WFN_NEXT is also the same as WFN_FIRST.
.define MAXWINS, 15
.define WNDCHNL, 1
.include "WND:windows.def"
record
wndw_1 ,i4
proc
open(WNDCHNL, o, "tt:")
xcall w_init(0, WNDCHNL, MAXWINS)
xcall w_proc(WP_CREATE, wndw_1, "window1", 11, 50)
xcall w_area(wndw_1, WA_FILL, ".")
xcall w_proc(WP_PLACE, wndw_1, 12, 15)
xcall w_flds(wndw_1, WF_CREATE, 4,
& WF_SET, WFN_NEXT, 6, 29, "Selection one",
& WF_SET, WFN_NEXT, 4, 15, "Selection two",
& WF_SET, WFN_NEXT, 8, 10, "Selection three",
& WF_SET, WFN_NEXT, 5, 12, "Last selection",
& WF_ATTR, WFN_NEXT, ATTR_SET + ATTR_RVRS)
call pause
xcall w_exit
stop
pause,
xcall w_updt
sleep 1
return
end
WF_WAIT, wait_time
WF_WAIT specifies a time-out value for a subsequent WF_INPUT function in the same call to W_FLDS. Wait_time can be the number of seconds to wait or one of the following:
|
Q_NOWAIT or 0 |
Don’t wait if I/O processing can’t be completed. |
|
Q_WAIT or -1 |
Wait until I/O processing is completed. |
The Q_ identifiers are defined by the compiler.
WF_UGET, element_num, variable
WF_UGET reads an element of the user data set array, where element_num is the element of the user data set array to read and variable is a Synergy DBL variable that receives the data. The data is moved to variable according to the rules for moving alpha data. (See Assignment statements for more information about moving alpha data.)
WF_UPUT, element_num, data
WF_UPUT writes an element of the user data set array, where element_num is the element of the user data set array to write and data is the data to be placed in the field entry. Data is moved according to the rules for moving alpha data. (See Assignment statements for more information about moving alpha data.)
WF_USER, dimension, size WF_USER, set_name, dimension, size
WF_USER creates an alpha array that is a user data set, in one of two forms. In both forms, dimension is the number of elements in array, size is the size of each element, and the user data set is initialized to blanks. If the first argument to WF_USER is alphanumeric, non-null, and nonblank, the windowing system assumes the three-argument form of this function. In all other cases, the two-argument form is assumed.
The two-argument form of WF_USER creates an unnamed user data set for the window, which is considered the default user data set. If a default data set already exists for the window, the existing data set is first removed.
The three-argument form of WF_USER creates a new user data set with the name set_name. If a data set already exists with that name, it is first removed. You can have multiple user data sets with different names. After the user data set is created, it automatically becomes the “active” data set for the window. (The active user data set is referenced by WF_UGET and WF_UPUT.)
In either form of WF_USER, if dimension or size is less than or equal to zero, the existing user data set (that is, either the default set or the set referenced by set_name) is deleted.
WF_USERID, set_name
WF_USERID changes the active user data set for a window, where set_name is the alphanumeric name of the user data set you want to activate. (The active user data set is referenced by WF_UGET and WF_UPUT.) If set_name is non-null or nonblank, it must contain the name of an existing user data set. If set_name is null or blank, the existing default (unnamed) user data set is activated.
|
|
You can use the WIF_USERID function of %W_INFO to test for user data sets and/or make them active. Also, the WIF_UFLDS and WIF_UFLDSIZ functions of %W_INFO references the active data set of a window. (See %W_INFO for more information.) |
