Click above to get retro games delivered to your door ever month!

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.

 Examples

  
      // 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