[<<Previous Entry]
[^^Up^^]
[Next Entry>>]
[Menu]
[About The Guide]
DBEDIT()
Browse records in a table layout
------------------------------------------------------------------------------
Syntax
DBEDIT([<nTop>], [<nLeft>],
[<nBottom>], <nRight>],
[<acColumns>],
[<cUserFunction>],
[<acColumnSayPictures> | <cColumnSayPicture>],
[<acColumnHeaders> | <cColumnHeader>],
[<acHeadingSeparators> | <cHeadingSeparator>],
[<acColumnSeparators> | <cColumnSeparator>],
[<acFootingSeparators> | <cFootingSeparator>],
[<acColumnFootings> | <cColumnFooting>]) --> NIL
Arguments
<nTop>, <nLeft>, <nBottom>, and <nRight> define the
upper-left and lower-right coordinates of the DBEDIT() window. Row
values can range from zero to MAXROW() and column positions can range
from zero to MAXCOL(). If not specified, the default coordinates are 0,
0, MAXROW(), and MAXCOL().
<acColumns> is an array of character expressions containing database
field names or expressions to use as column values for each row
displayed. If this argument is not specified, DBEDIT() displays all
fields in the current work area as columns.
<cUserFunction> is the name of a user-defined function that executes
when an unrecognizable key is pressed or there are no keys pending in
the keyboard buffer. Specify the function name as a character
expression without parentheses or arguments. Note that the behavior of
DBEDIT() is affected by the presence of this argument. Refer to the
discussion below for more information.
<acColumnSayPictures> is a parallel array of picture clauses to
format each column. Specifying <cColumnSayPicture> instead of an array
displays all columns with the same format. Refer to TRANSFORM() or
@...SAY for more information on pictures.
<acColumnHeaders> is a parallel array of character expressions that
define the headings for each column. Specifying <cColumnHeader> gives
the same heading for all columns. To display a multi-line heading,
embed a semicolon in the heading expression where you want the string to
break. If not specified, column headings are taken from the <acColumns>
array or the field names in the current work area, if the <acColumns>
argument is not specified.
<acHeadingSeparators> is a parallel array of character expressions
that define the characters used to draw horizontal lines separating
column headings from the field display area. Specifying
<cHeadingSeparator> instead of an array uses the same heading separator
for all columns. If this argument is not specified, the default
separator is a double graphics line.
<acColumnSeparators> is a parallel array of character expressions
that define the characters used to draw vertical lines separating the
columns. Specifying <cColumnSeparator> instead of an array uses the
same separator for all columns. If this argument is not specified, the
default separator is a single graphics line.
<acFootingSeparators> is a parallel array of character expressions
that define the characters used to draw horizontal lines separating
column footings from the field display area. Specifying
<cFootingSeparator> instead of an array uses the same footing separator
for all columns. If this argument is not specified, there is no footing
separator.
<acColumnFootings> is a parallel array of character expressions that
define footings for each column. Specifying <cColumnFooting> instead of
an array gives the same footing for all columns. To display a multi-
line footing, embed a semicolon in the footing expression where you want
the string to break. If this argument is not specified, there are no
column footings.
Returns
DBEDIT() always returns NIL.
Description
DBEDIT() is a user interface and compatibility function that displays
records from one or more work areas in a table form. The DBEDIT()
window display is a grid of cells divided into columns and rows.
Columns correspond to database fields and rows correspond to database
records. Each column is defined by an element of the <acColumns> array.
The display width of each column is determined by the evaluation of the
column expression in <acColumns> array or the column picture specified
in the <acColumnSayPictures> array.
All cursor movement keys are handled within DBEDIT(), including Page up,
Page down, Home, End, the four arrow keys, and all Ctrl key combinations
that produce cursor movement. The navigation keys that DBEDIT()
responds to when a user function argument is not specified are listed in
the Active Keys table below:
DBEDIT() Active Keys
------------------------------------------------------------------------
Key Action
------------------------------------------------------------------------
Up arrow Up one row
Down arrow Down one row
Left arrow Column left
Right arrow Column right
Ctrl+Left arrow Pan left one column
Ctrl+Right arrow Pan right one column
Home Leftmost current screen column
End Rightmost current screen column
Ctrl+Home Leftmost column
Ctrl+End Rightmost column
PgUp Previous screen
PgDn Next screen
Ctrl+PgUp First row of current column
Ctrl+PgDn Last row of current column
Return Terminate DBEDIT()
Esc Terminate DBEDIT()
------------------------------------------------------------------------
When the user function argument (<cUserFunction>) is specified, all keys
indicated in the Active Keys table are active with the exception of Esc
and Return. When DBEDIT() calls the user function, it automatically
passes two arguments:
. The current mode passed as a numeric value
. The index of the current column in <acColumns> passed as a
numeric value
The mode parameter indicates the current state of DBEDIT() depending on
the last key executed. The possible mode values are listed in the
DBEDIT() Modes table below:
DBEDIT() Modes
------------------------------------------------------------------------
Status Dbedit.ch Description
------------------------------------------------------------------------
0 DE_IDLE Idle, any cursor movement keystrokes have been
handled and no keystrokes are pending
1 DE_HITTOP Attempt to cursor past top of file
2 DE_HITBOTTOM Attempt to cursor past bottom of file
3 DE_EMPTY No records in work area
4 DE_EXCEPT Key exception
------------------------------------------------------------------------
The index parameter points to the position of the current column
definition in the <acColumns> array. If <acColumns> is not specified,
the index parameter points to the position of the field in the current
database structure. Access the field name using FIELD().
A user-defined function must return a value that indicates to DBEDIT()
the action to perform. The User Function Return Values table below
lists the possible return values and the corresponding actions:
DBEDIT() User Function Return Values
------------------------------------------------------------------------
Value Dbedit.ch Description
------------------------------------------------------------------------
0 DE_ABORT Abort DBEDIT()
1 DE_CONT Continue DBEDIT()
2 DE_REFRESH Force reread/repaint and continue; after repaint,
process keys and go to idle
------------------------------------------------------------------------
A number of instances affect calls to the user function:
. A key exception occurs. This happens when DBEDIT() fetches a
keystroke that it does not recognize from the keyboard. Any pending
keys remain in the keyboard buffer until fetched within the user
function or until DBEDIT() continues.
. DBEDIT() enters the idle mode (i.e., all pending keys have
been processed). This happens when the keyboard is empty or after a
screen refresh. In this instance, there is one call to the user
function and then DBEDIT() waits for a key.
. Beginning or end of file is encountered. This is the same as
idle. All executable keys are performed, and there is one call to
the user function with the appropriate status message.
Note that when DBEDIT() is first executed, all keys pending in the
keyboard buffer are executed and then DBEDIT() enters the idle mode with
a user function call. If no keys are pending, the idle mode is
immediate.
The user function should handle all modes and status messages received
from DBEDIT().
A user-defined function must ensure that the DBEDIT() status is
equivalent to DE_EXCEPT (4); otherwise, the value of LASTKEY() is
meaningless and a Return value of DE_REFRESH (2) will place the
application into an endless loop. For example:
FUNCTION DBEditFunc ( nMode, nColumnPos )
LOCAL RetVal := DE_CONT
IF ( nMode == DE_EXCEPT )
IF ( LASTKEY() == K_F5 )
RetVal := DE_REFRESH
ENDIF
ENDIF
RETURN( RetVal )
DBEDIT() is fully re-entrant, which means you can make nested calls to
it. Using this feature, you can have multiple browse windows on the
screen at the same time.
DBEDIT() is a compatibility function and, therefore, no longer
recommended as a programmable browse facility. As such, it is
superseded by the TBrowse object class. For more information, refer to
TBrowse class in this chapter.
Examples
. This example demonstrates a generic call to DBEDIT():
USE Names NEW
DBEDIT()
. This example demonstrates calling DBEDIT() with a user
function:
#include "dbedit.ch"
#include "inkey.ch"
// Array must be visible to other user-defined programs in
// program
STATIC acColumns := {}
PROCEDURE Main()
USE Names NEW
INDEX ON Names->Lastname + Names->FirstName TO Names
CLS
acColumns := { "LastName", "FirstName" }
DBEDIT( 5, 5, 20, 70, acColumns, "UserFunc" )
RETURN
FUNCTION UserFunc( nMode, nCol )
LOCAL nKey := LASTKEY()
LOCAL nRetVal := DE_CONT // Default return value
DO CASE
CASE nMode == DE_IDLE
nRetVal := IdleFunc()
CASE nMode == DE_HITTOP
TONE( 100, 3 )
CASE nMode == DE_HITBOTTOM
TONE( 100, 3 )
nRetVal := AppendFunc( nKey )
CASE nMode == DE_EMPTY
nRetVal := EmptyFunc()
CASE nMode == DE_EXCEPT
nRetVal := ExceptFunc( nKey, nCol )
OTHERWISE
TONE( 100, 3 )
ENDCASE
RETURN nRetVal
FUNCTION AppendFunc( nKey )
LOCAL nRetVal := DE_CONT // Default return value
IF nKey == K_DOWN // If DOWN ARROW
APPEND BLANK // Append blank record
// Note: The appended record will appear at the top of the
// DBEDIT() screen when the database file is indexed.
nRetVal := DE_REFRESH // Refresh screen
ENDIF
RETURN nRetVal
FUNCTION ExceptFunc( nKey, nCol )
LOCAL nRetVal := DE_CONT // Default return value
DO CASE
CASE nKey == K_ESC // If ESCAPE
nRetVal := DE_ABORT // Exit
CASE nKey == K_RETURN // If RETURN
nRetVal := EditFunc( nCol ) // Function to edit
// field
// Toggle DELETED status
CASE nKey == K_DEL .AND. LASTREC() != 0 // DELETE pressed
IF DELETED()
RECALL
ELSE
DELETE
ENDIF
OTHERWISE
TONE( 100, 1 )
ENDCASE
RETURN nRetVal
FUNCTION EditFunc( nCol )
LOCAL cIndexVal // Value of current key expression
LOCAL nRetVal // Return value
LOCAL nField // Position of current field
LOCAL cFieldVal // Value of current field
LOCAL nCursSave // Preserve state of cursor
// This will return an error if no index is open
cIndexVal := &( INDEXKEY(0) )
nField := FIELDPOS( acColumns[nCol] )
IF nField != 0
nCursSave := SETCURSOR() // Save state of cursor
SETCURSOR(1) // Change cursor shape
cFieldVal := FIELDGET( nField ) // Save contents
// of field
@ ROW(), COL() GET cFieldVal // GET new value
READ
FIELDPUT( nField, cFieldVal ) // REPLACE with
// new value
SETCURSOR( nCursSave ) // Restore cursor
// shape
ENDIF
IF cIndexVal != &( INDEXKEY(0) ) // If key expression
// changed
nRequest := DE_REFRESH // Refresh screen
ELSE // Otherwise
nRequest := DE_CONT // Continue
ENDIF
RETURN nRequest
FUNCTION IdleFunc()
// Idle routine
RETURN DE_CONT
FUNCTION EmptyFunc()
// Empty Records routine
RETURN DE_CONT
Files Library is EXTEND.LIB, header files are Dbedit.ch and Inkey.ch.
See Also:
@...GET
ACHOICE()
BROWSE()*
MEMOEDIT()
READ
This page created by ng2html v1.05, the Norton guide to HTML conversion utility.
Written by Dave Pearson