TBrowseDB()

TBrowseDB()

Create a new TBrowse object to be used with database file

Syntax

      TBrowseDB( [<nTop>],  [<nLeft>],  [<nBottom>],  [<nRight>] ) --> oBrowse

Arguments

<nTop> coordinate for top row display.

<nLeft> coordinate for left column display.

<nBottom> coordinate for bottom row display.

<nRight> coordinate for right column display.

Returns

TBrowseDB() return new TBrowse object with the specified coordinate and a default :SkipBlock, :GoTopBlock and :GoBottomBlock to browse a database file.

Description

TBrowseDB() is a quick way to create a TBrowse object along with the minimal support needed to browse a database. Note that the returned TBrowse object contain no TBColumn objects and you need to add column for each field by your self.

Examples

    For a good example, look at the source code for Browse() function at src/rtl/browse.prg

Compliance

Harbour

Files

Library is core

Seealso

Browse(), TBColumn class, TBrowse class, TBrowseNew()

dbEdit()

Template

Function

Name

dbEdit()*

Category

API

Subcategory

User interface

Oneliner

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. <nTop> could range from 0 to MaxRow(), default is 0.

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

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

<nRight> coordinate for right column display. <nRight> 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 <xColumnSayPictures>
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()

Compliance

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

CA-Cl*pper will throw an error if there’s no database open, Harbour
would return .F.

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

The CA-Cl*pper 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 CA-Cl*pper (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 core

Seealso

@…SAY, Browse(), TBrowse class, Transform()

Browse()

BROWSE()

Browse a database file

Syntax

      BROWSE( [<nTop>, <nLeft>, <nBottom>, <nRight>] ) --> lOk

Arguments

<nTop> coordinate for top row display.

<nLeft> coordinate for left column display.

<nBottom> coordinate for bottom row display.

<nRight> coordinate for right column display.

Returns

BROWSE() return .F. if there is no database open in this work area, else it return .T.

Description

BROWSE() is a general purpose database browser, without any thinking you can browse a file using the following keys:

       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
       Esc              Terminate BROWSE()

On top of the screen you see a status line with the following indication:

       Record ###/###   Current record number / Total number of records.
       <none>           There are no records, the file is empty.
       <new>            You are in append mode at the bottom of file.
       <Deleted>        Current record is deleted.
       <bof>            You are at the top of file.

You should pass whole four valid coordinate, if less than four parameters are passed to BROWSE() the coordinate are default to: 1, 0, MAXROW(), MAXCOL().

Examples

      // this one shows you how to browse around
      USE Around
      Browse()

Compliance

Clipper

Files

Library is rtl

Seealso

DBEDIT()*, TBrowse class

C5 TBrowse Class

Overwiev
 Provides objects for browsing table-oriented data
------------------------------------------------------------------------------
 Description

     A TBrowse object is a general purpose browsing mechanism for
     table-oriented data.  TBrowse objects provide a sophisticated architecture
     for acquiring, formatting, and displaying data.  Data retrieval and file
     positioning are performed via user-supplied code blocks, allowing a high
     degree of flexibility and interaction between the browsing mechanism and
     the underlying data source.  The format of individual data items can be
     precisely controlled via the TBColumn data retrieval code blocks;
     overall display formatting and attributes can be controlled by sending
     appropriate messages to the TBrowse object.

     A TBrowse object relies on one or more TBColumn objects.  A TBColumn
     object contains the information necessary to define a single column of
     the browse table (see TBColumn class in this chapter).

     During operation, a TBrowse object retrieves data by evaluating code
     blocks.  The data is organized into rows and columns and displayed
     within a specified rectangular region of the screen.  The TBrowse object
     maintains an internal browse cursor.  The data item on which the browse
     cursor rests is displayed in a highlighted color.  (The actual screen
     cursor is also positioned to the first character of this data item.)

     Initially, the browse cursor is placed on the data item at the top left
     of the browse display.  Messages can then be sent to the TBrowse object
     to navigate the displayed data, causing the browse cursor to move.
     These messages are normally sent in response to user keystrokes.

     New data is automatically retrieved as required by navigation requests.
     When navigation proceeds past the edge of the visible rectangle, rows or
     columns beyond that edge are automatically brought into view.  When new
     rows are brought into view, the underlying data source is repositioned
     by evaluating a code block.

     Note:  TBrowse objects do not clear the entire window before output
     during redisplay operations.  Part of the window may still be cleared
     when data from the existing display is scrolled.

 Examples

     For fully operational examples of a TBrowse object, refer to the TBrowse
     introduction chapter in the Programming and Utilities guide and to
     TbDemo.prg located in \CLIPPER5\SOURCE\SAMPLE.

Class Functions

 TBrowseNew()      Create a new TBrowse object

     TBrowseNew(<nTop>, <nLeft>, <nBottom>, <nRight>)
        --> objTBrowse

     Returns a new TBrowse object with the specified coordinate settings.
     The TBrowse object is created with no columns and no code blocks for
     data positioning.  These must be provided before the TBrowse object
     can be used.

 TBrowseDB() Create a new TBrowse object for browsing a database file

 TBrowseDB(<nTop>, <nLeft>, <nBottom>, <nRight>)

        --> objTBrowse

  Returns a new TBrowse object with the specified coordinate settings
  and default code blocks for data source positioning within database
  files.  The default code blocks execute the GO TOP, GO BOTTOM, and
  SKIP operations.

  Note that TBrowseDB() creates an object with no column objects.  To
  make the TBrowse object usable, you must add a column for each field
  to be displayed.

 

More …


See Also: BROWSE()* DBEDIT()* SETCOLOR() TBColumn