DBEDIT()*

Browse records in a table

Syntax

DBEDIT( [<nTop>], [<nLeft>], [<nBottom>], [<nRight>], [<acColumns>], [<xUserFunc>], [<xColumnSayPictures>], [<xColumnHeaders>], [<xHeadingSeparators>], [<xColumnSeparators>], [<xFootingSeparators>], [<xColumnFootings>] ) --> lOk

Arguments

<nTop> coordinate for top row display. could range from 0 to MAXROW(), default is 0.

<nLeft> coordinate for left column display. could range from 0 to MAXCOL(), default is 0.

<nBottom> coordinate for bottom row display. could range from 0 to MAXROW(), default is MAXROW().

<nRight> coordinate for right column display. could range from 0 to MAXCOL(), default is MAXCOL().

<acColumns> is an array of character expressions that contain database fields names or expressions to display in each column. If not specified, the default is to display all fields from the database in the current work area.

<xUserFunc> is a name of a user defined function or a code block that would be called every time unrecognized key is been pressed or when there are no keys waiting to be processed and DBEDIT() goes into idle mode. If <xUserFunc> is a character string, it must contain root name of a valid user define function without parentheses. Both the user define function or the code block should accept two parameters: nMode, nCurrentColumn. Both should return a numeric value that correspond to one of the expected return codes (see table below for a list of nMode and return codes).

<xColumnSayPictures> is an optional picture. If is a character string, all columns would used this value as a picture string. If <xColumnSayPictures> is an array, each element should be a character string that correspond to a picture string for the column with the same index. Look at the help for @...SAY to get more information about picture values.

<xColumnHeaders> contain the header titles for each column, if this is a character string, all columns would have that same header, if this is an array, each element is a character string that contain the header title for one column. Header may be split to more than one line by placing semicolon (;) in places where you want to break line. If omitted, the default value for each column header is taken from <acColumns> or field name if <acColumns> was not specified.

<xHeadingSeparators> is an array that contain characters that draw the lines separating the headers and the fields data. Instead of an array you can use a character string that would be used to display the same line for all fields. Default value is a double line.

<xColumnSeparators> is an array that contain characters that draw the lines separating displayed columns. Instead of an array you can use a character string that would be used to display the same line for all fields. Default value is a single line.

<xFootingSeparators> is an array that contain characters that draw the lines separating the fields data area and the footing area. Instead of an array you can use a character string that would be used to display the same line for all footers. Default is to have to no footing separators.

<xColumnFootings> contain the footing to be displayed at the bottom of each column, if this is a character string, all columns would have that same footer, if this is an array, each element is a character string that contain the footer for one column. Footer may be split to more than one line by placing semicolon (;) in places where you want to break line. If omitted, no footer are displayed.

Returns

DBEDIT() return .F. if there is no database in use or if the number of columns to display is zero, else DBEDIT() return .T.

Description

DBEDIT() display and edit records from one or more work areas in a grid on screen. Each column is defined by element from <acColumns> and is the equivalent of one field. Each row is equivalent of one database record.

Following are active keys that handled by DBEDIT():

---------------------------------------------------

Key	Meaning
Left	Move one column to the left (previous field)
Right	Move one column to the right (next field)
Up	Move up one row (previous record)
Down	Move down one row (next record)
Page-Up	Move to the previous screen
Page-Down	Move to the next screen
Ctrl Page-Up	Move to the top of the file
Ctrl Page-Down	Move to the end of the file
Home	Move to the leftmost visible column
End	Move to the rightmost visible column
Ctrl Left	Pan one column to the left
Ctrl Right	Pan one column to the right
Ctrl Home	Move to the leftmost column
Ctrl End	Move to the rightmost column

When <xUserFunc> is omitted, two more keys are active:

Key	Meaning
Esc	Terminate BROWSE()
Enter	Terminate BROWSE()

When DBEDIT() execute <xUserFunc> it pass the following arguments: nMode and the index of current record in <acColumns>. If <acColumns> is omitted, the index number is the FIELD() number of the open database structure.

DBEDIT() nMode could be one of the following:

---------------------------------------------

Dbedit.ch	Meaning
DE_IDLE	DBEDIT() is idle, all movement keys have been handled.
DE_HITTOP	Attempt to cursor past top of file.
DE_HITBOTTOM	Attempt to cursor past bottom of file.
DE_EMPTY	No records in work area, database is empty.
DE_EXCEPT	Key exception.

The user define function or code block must return a value that tell DBEDIT() what to do next.

User function return codes:

---------------------------

Dbedit.ch	Value	Meaning
DE_ABORT	0	Abort DBEDIT().
DE_CONT	1	Continue DBEDIT() as is.
DE_REFRESH	2	Force reread/redisplay of all data rows.

The user function is called once in each of the following cases: - The database is empty. - The user try to move past top of file or past bottom file. - Key exception, the uses had pressed a key that is not handled by DBEDIT(). - The keyboard buffer is empty or a screen refresh had just occurred DBEDIT() is a compatibility function, it is superseded by the TBrowse class and there for not recommended for new applications.

      // Browse a file using default values
      USE Test
      DBEDIT()

Status

Started

Compliance

<xUserFunc> can take a code block value, this is a Harbour extension.

CA-Clipper will throw an error if there's no database open, Harbour would return .F.

CA-Clipper is buggy and will throw an error if the number of columns zero, Harbour would return .F.

The CA-Clipper 5.2 NG state that the return value is NIL, this is wrong and should be read logical.

There is an undocumented result code (3) from the user defined function in Clipper (both 87 and 5.x). This is an Append Mode which: "split the screen to allow data to be appended in windowed area". This mode is not supported by Harbour.

Files

Header files are dbedit.ch, inkey.ch Library is rtl

See Also

• @...SAY
• BROWSE()
• TBrowse class
• TRANSFORM()