Function DbEdit() Foundation
Browses records in a work area.
DbEdit( [<nTop>] , ;
[<nLeft>] , ;
[<nBottom>] , ;
[<nRight>] , ;
[<aColumns>] , ;
[<bcUserFunc>], ;
[<acPicture>] , ;
[<acHeading>] , ;
[<acHeadSep>] , ;
[<acColSep>] , ;
[<acFootSep>] , ;
[<acFooting>] ) --> NIL
The return value of DbEdit() is always NIL.
The function DbEdit() is purely a compatibility function which makes a database file browser available. The capabilities of a TBrowse object should be used instead of DbEdit() (see function TBrowseNew() or TBrowseDb()).
The dialog function DbEdit() displays the contents of fields from one or more work areas in columns. The columns are defined by the elements of the array<aColumns>. The appearance of the field contents can be modified by including PICTURE formatting in the array <acPicture>. The data is displayed within a window. When a work area has more records than the window has rows, the window contents are scrolled as soon as the user moves to a record outside the window using the arrow keys.
The color of records is determined by the system colors set with SetColor(). All data is displayed in the default color (first color value), except the current field (the current cell) which is displayed in the "highlight" color (second color value).
Cursor navigation within DbEdit() occurs using the following keys:
Key | Inkey constant | Action |
---|---|---|
Up Arrow | K_UP | Previous record |
Down Arrow | K_DOWN | Next record |
Left Arrow | K_LEFT | One column to the left |
Right Arrow | K_RIGHT | One column to the right |
Home | K_HOME | Left column in the window |
End | K_END | Right column in the window |
Page Up | K_PGUP | Previous screen |
Page Down | K_PGDN | Next screen |
Ctrl+Left Arrow | K_CTRL_LEFT | Scroll columns to the left |
Ctrl+Right Arrow | K_CTRL_RIGHT | Scroll columns to the right |
Ctrl+Home | K_CTRL_HOME | First column |
Ctrl+End | K_CTRL_END | Last column |
Ctrl+Page Up | K_CTRL_PGUP | First record |
Ctrl+Page Down | K_CTRL_PGDN | Last record |
Return *) | K_RETURN | Terminate DbEdit() |
Esc *) | K_ESC | Terminate DbEdit() |
|
If the function SetMouse(.T.) was called before DbEdit(), the cursor can be positioned within the browse window by a click of the left mouse button. If DbEdit() is used with Xbase Parts in hybrid mode, events for an Xbase Part are automatically sent to the applicable Xbase Part and not processed by DbEdit().
The argument <bcUserFunc> modifies the functionality of DbEdit(). <bcUserFunc> contains either a character string with the name of a function or a code block.
When <bcUserFunc> contains a function name, the corresponding function cannot be declared STATIC and must be specified as a character string without () parentheses.
When <bcUserFunc> contains a code block, it must contain the function call of a user function. If called within a code block, a user function declared as STATIC can be used.
The user function allows DbEdit() behavior to be modified to be user specific. When a value for <bcUserFunc> is passed to DbEdit(), DbEdit() calls the user function (or evaluates the code block) every time a key is pressed that DbEdit() does not automatically process. DbEdit() automatically processes all keys from the above table until Return or Esc are processed. Unknown keys can be processed in the user function and the RETURN value of the user function informs DbEdit() how to react to the key.
When it calls the user function, DbEdit() passes two numeric values to the function or code block: the current DbEdit() mode and the number of the current column where the cursor or highlight is currently located. The column number corresponds to the element in the array <aColumns>.
The mode designates the present mode of DbEdit() and depends on the last pressed key or the last action DbEdit() executed before calling the user function. In the header file "Dbedit.ch" symbolic constants are defined which identify the various modes of DbEdit():
Constant | Description |
---|---|
DE_IDLE | Idle, all keys processed |
DE_HITTOP | Bof() was reached |
DE_HITBOTTOM | Eof() was reached |
DE_EMPTY | No records available |
DE_EXCEPT | Unknown key |
The mode DE_IDLE means that no more keys are waiting to be processed and DbEdit() is waiting for a new keypress. Each time DbEdit() does not find another value in the keyboard buffer, the user function is called once and then DbEdit() waits for a new keypress.
DbEdit() uses the modes DE_HITTOP and DE_HITBOTTOM to signal that the user has attempted to position the highlight before the first or beyond the last record.
The mode DE_EXCEPT indicates that an unknown key code or an unknown event is waiting to be processed. The action DbEdit() should execute after an unknown keypress or event is defined by the return value of the user function. Returning DE_CONT causes DbEdit() to execute its default action. If a value not equal to DE_CONT is returned, DbEdit() executes a different action. Symbolic constants are defined in the header file "Dbedit.ch" for the possible return values of the user function. These identify the various DbEdit() actions which can be requested by the user function:
Dbedit.ch | Action |
---|---|
DE_ABORT | Terminates DbEdit() |
DE_CONT | Continues DbEdit() |
DE_REFRESH | Rereads data and rebuilds screen |
The value DE_REFRESH can be returned to DbEdit() only when the mode is DE_EXCEPT. Otherwise it may cause an infinite loop.
If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.