I_NEXT

Specify the next input field or button to be processed

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
xcall I_NEXT(window_id, [set_name][, field_spec])

Arguments

window_id

The ID of the input window containing the field. (n)

set_name

(optional) The name of the input set to use or *CURR* to use the currently loaded set. (a)

field_spec

(optional) The specification for the field or one of the keywords listed below (which must be specified in uppercase). Field_spec must be enclosed in quotation marks. (For information on field specifications, see Field specifications.) (a)

*FRST*

First enabled field.

*LAST*

Last enabled field.

*NEXT*

Next enabled field.

*PREV*

Previous enabled field.

*FCLR*

First empty enabled field. (default)

*NCLR*

Next empty enabled field.

*MENU*

Set the context based on the contents of g_entnam.

*NMBR*, field#

Field# if enabled, otherwise next enabled field after field#.

*BUTTON*, button

Specified button on Windows. Button can be either the name (case-insensitive) or index number of a button.

*NONE*

No field.

*DFLT*

Fill default values on all empty fields with defaults and set context to next enabled empty field.

*DONE*

Complete input on all empty, enabled fields.

*LASTCTL*

Last enabled control (field or button).

*NEXTCTL*

Next enabled control (field or button).

*PREVCTL*

Previous enabled control (field or button).

Discussion

I_NEXT sets the input context. When processing input, Toolkit moves through fields according to their order in the input set; when a user is finished with a field, Toolkit moves to the next active field in the set. With I_NEXT, however, you can determine which field or button (on Windows) Toolkit will advance to. For example, if your application displays an error when a user enters an invalid item code, Toolkit automatically advances to the next field in the input set after the error is displayed. Using I_NEXT, however, you can instead instruct Toolkit to go back to the field that caused the break.

These are the general rules for context changes:

Note that set names are sometimes inaccessible to the utility subroutines. To call I_NEXT from within a utility subroutine, use *CURR* instead of a specific set name. This enables I_NEXT to use the current set even if it can’t access the name of the current set. If set_name is not passed, I_NEXT uses the first input set in the window.

If you don’t pass field_spec, the context is set to the first empty enabled field, which is the equivalent of setting *FCLR*. (An empty field is one that the user hasn’t entered anything in and that has not been displayed using I_DSPFLD or I_DISPLAY.)

Use *NMBR* followed by a numeric argument (field#) to specify the next field by index. This index is a number that represents the field’s position in the input set and is limited to the valid range for the input set. (A value less than 1 or greater than the number of fields in the window will result in a fatal Toolkit error.) For example, the following sets the context to the third field in an input set named setnam.

xcall i_next(inpid, setnam, "*NMBR*", 3)

On Windows, use *BUTTON* followed by a button name or index to move context to a specific button. (On UNIX and OpenVMS, passing *BUTTON* will cause a fatal Toolkit error.) The button argument is required if you pass *BUTTON*.

xcall i_next(inpid,, "*BUTTON*", 2)

*NONE* prevents I_INPUT from performing input to any field. Instead, Toolkit uses single-keystroke input. This option is rarely used.

Using *DONE* or *DFLT* is like pressing enter for each remaining field without entering any input. The difference is that *DONE* completes the input set while *DFLT* displays any defaults that are specified in the script file, leaves all other fields unmodified (which does not affect their empty state), and allows input to continue on the next empty field.

On Windows, *NEXTCTL*, *LASTCTL*, and *PREVCTL* set context to the next, last, or previous enabled field or button. On UNIX or OpenVMS, if you are using termination processing, you can use *NEXTCTL*, *LASTCTL*, and *PREVCTL* to set context to the termination message.

Note

If you call I_NEXT with *FCLR* or *NCLR* in a change method, I_NEXT uses the current state of the field set to determine where to move input context. This causes I_NEXT to set input context to the current field if it’s empty. To instead move context to the next enabled empty field, use %M_SIGNAL to signal I_NXTCLR. This moves context to the next empty field (unless you signal some other menu entry at the same time) because I_NXTCLR won’t be processed until the change method has returned and the input has been accepted. And because a menu entry was generated, Toolkit won’t move input context until the menu entry is processed.

If an application is in I_DONE (*DONE*), I_DFLT (*DFLT*), or I_OK processing, calling I_NEXT from a method will cancel that processing and move focus to the field specified by I_NEXT. If you do not want this to happen, test the value of inp_nulinp (which is in the inputinfo group defined in inpinf.def) before calling I_NEXT. If inp_nulinp is non-zero, the application is performing one of these types of processing.

If you pass *MENU*, I_NEXT will set context based on the value of g_entnam at the time that I_NEXT is called. (So with *MENU*, I_NEXT recognizes only menu entries that start with I_, such as I_NEXT, I_PREV, and I_DONE.) This is useful when a menu entry has been signaled outside of an input routine (such as I_INPUT, I_INPFLD, etc.) in order to force that menu entry to be applied upon re-entry to that routine. For example, while within a method in I_INPUT, passing “I_OK” to M_SIGNAL will cause validation of all fields to occur upon exiting the method, and (presuming no validation errors result) I_INPUT will then exit. However, if you make the same call to M_SIGNAL during break processing, then that menu entry will not apply to the next call to I_INPUT unless you also call I_NEXT with *MENU*.

See also

Examples

In the following example, I_NEXT resets the context in input set cusmas by skipping all remaining fields without entering input. The next time I_INPUT is called on this set, it will complete the set as if the user pressed enter at each field (using the default for each) and perform termination processing.

xcall i_next(inpid, "cusmas", "*DONE*")

The next example sets the context of maindcs to the first empty field (the default).

xcall i_next(dcswnd, "maindcs")