Function ReadModal() | Xbase++

Functions and Directives Functions and Directives

Activates interactive data input for a GetList array.

ReadModal( <aGetList> [,<nStartGet>] ) --> lUpdated

<aGetList> is an array of Get objects. A Get object allows data input into a single input field on the screen.

The optional <nStartGet> is a positive integer which identifies the Get object in <aGetList> which gets the initial input focus.

The return value of ReadModal() is a logical value which indicates whether a change has occurred during data input. It is identical to the return value of Updated() (see Updated()).

ReadModal() navigates the display and input of data in a list of several Get input fields or Get objects. It is Part of GETSYS.PRG.

The first Get object or input field in the list to receive input focus can be specified by the parameter <nStartGet>. This cannot be done with the READ command.

A Get object manages an edit buffer and assigns its contents to a variable after data input. Data which is entered can be validated automatically (see the VALID option with the command @...GET or the instance variable :postBlock of a Get object).

Mouse support for data input is included in the Xbase++ Get system, but it is turned off by default for compatibility reasons. This guarantees compatibility with the Clipper Get system, which reads only keyboard entries using Inkey(). In native Xbase++ code, events (not just keyboard entries) are retrieved by AppEvent() and handled by GetHandleEvent() (Inkey() and AppEvent() are not compatible). The Get system's use of events can be set in two ways. First, if SetMouse(.T.) executes before the first call to ReadModal(), then the mouse is activated, Gets can be navigated by clicking the left mouse button, and keyboard events are checked by AppEvent() instead of Inkey(). Second, GetEnableEvents() can be called to switch between the use of Inkey() or AppEvent().

The Xbase++ Get system makes some globally visible service functions available for use by a user-defined Get reader. A list of these functions is included in the following table. Detailed descriptions of these functions can be found in the language reference or in the Online help:

Function	Description
GetActive()	Returns the Get object with input focus
GetApplyKey()	Applies key code to Get object
GetToMousePos()	Moves cursor in the Get input field to the mouse pointer
GetDoSetkey()	Executes code block during input
GetEventReader()	READ behavior for a single Get object ->AppEvent()
GetHandleEvent()	Applies event to Get object
GetKillActive()	Removes the input focus of active Get object
GetList()	Returns reference to the current GetList array
GetListPos()	Returns position of the current Get object in the GetList array
GetPostValidate()	Validation after input
GetPreValidate()	Validation before input
GetReader()	Implements READ behavior for a single Get object ->Inkey()
ReadKill()	Terminates READ or ReadModal()
ReadUpdated()	Reads or sets Updated status

The functions GetApplyKey() and GetHandleEvent() in the file GETSYS.PRG define the standard behavior of Get objects during data input. A detailed description of all navigation keys which are handled by default in the Get system can be found in the documentation of the READ command.

The @...GET command is translated by the preprocessor to a call to Get():new(). When @...GET produces Get objects, they are inserted in an array which is referenced in the variable GetList. By default, there is a PUBLIC declared variable GetList, which contains an empty array. If no new variable GetList with an empty array is declared before the command @...GET, the newly generated Get object is inserted into the PUBLIC array.

The READ command is translated by the preprocessor to a call to ReadModal(), which is passed the array GetList. After the READ ends, an empty array is assigned to the variable GetList. If the SAVE option is used with the READ command, the empty array is not assigned, so that the GetList array is left intact.

Function ReadModal() Foundation