C5 TBColumn Class

Overview

 Provides column objects for TBrowse objects

Description

     A TBColumn object is a simple object containing the information needed
     to fully define one data column of a TBrowse object (see the TBrowse
     reference in this chapter).  TBColumn objects have no methods, only
     exported instance variables.

Examples

     .  This example is a code fragment that creates a TBrowse object
        and adds some TBColumn objects to it:

        USE Customer NEW
        //

        // Create a new TBrowse object
        objBrowse := TBrowseDB(1, 1, 23, 79)
        //

        // Create some new TBColumn objects and
        // add them to the TBrowse object
        objBrowse:addColumn(TBColumnNew( "Customer", ;
              {|| Customer->Name} ))
        objBrowse:addColumn(TBColumnNew( "Address", ;
              {|| Customer->Address} ))
        objBrowse:addColumn(TBColumnNew( "City", ;
              {|| Customer->City} ))
        .
        . <statements to actually browse the data>
        .
        CLOSE Customer

        For more information on TBrowse, refer to the Introduction to TBrowse
        chapter in the Programming and Utilitites guide.  For a fully
        operational example of a TBrowse object, see also TbDemo.prg located
        in \CLIPPER5\SOURCE\SAMPLE.

Class Function
     TBColumnNew()   Create a new TBColumn object

     TBColumnNew(<cHeading>, <bBlock>) --> objTBColumn

        Returns a new TBColumn object with the specified heading and data
        retrieval block.  Other elements of the TBColumn object can be
        assigned directly using the syntax for assigning exported instance
        variables.

More ...

See Also: BROWSE()* DBEDIT()* TBrowse

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



C5 GET Class

Overview

     Provides objects for interactive editing of database fields and variables

Description

     A Get object is a general purpose mechanism for editing data.  It is
     used in CA-Clipper to implement the @...GET and READ commands.  Get
     objects provide a sophisticated architecture for formatting and editing
     data, including cursor navigation and data validation.  Data validation
     is performed via user-supplied code blocks, and display formatting can
     be controlled using standard picture strings.

     Normally, a Get object is associated with a particular variable
     (referred to as the Get variable).  The Get object does not directly
     access this variable; instead, the variable is manipulated by evaluating
     a supplied code block.  When a Get object is created using the standard
     @...GET command, a code block is automatically created which provides
     access to the variable named in the command.  For a Get object created
     with the GetNew() function, you must specify an appropriate code block.

     A Get object evaluates the supplied code block to retrieve the value of
     the Get variable.  The value is converted to displayable form and copied
     into a buffer referred to as the editing buffer.  You can display the
     editing buffer on the screen for editing.  Programmable behaviors allow
     the navigation of the editing buffer and subsequent copying of its
     contents back to the Get variable.

 Examples

     .  This example creates a new Get object, assigns some new
        attributes to its instance variables, then edits the Get with the
        READMODAL() function:

        LOCAL cVar := SPACE(10)
        //

        // Create a new Get object
        objGet := GetNew()
        //

        // Assign some instance variables
        objGet:row := 10
        objGet:col := 10
        //

        // Assign the name of the associated
        // variable and the block
        objGet:name := "cVar"
        objGet:block := { |cValue| IF(PCOUNT() > 0,;
                           cVar := cValue, cVar) }
        //
        objGet:picture := "@!"
        objGet:colorSpec := "BG+/B, W+/BG"
        objGet:postBlock := { |oGet| !EMPTY(oGet:varGet()) }
        //

        // Edit the single Get object
        READMODAL({objGet})

 Files:  Source file is Getsys.prg.


Class Function

     GetNew()        Create a new Get object
     GetNew([<nRow>], [<nCol>], [<bBlock>], [<cVarName>],
        [<cPicture>], [<cColorSpec>]) --> objGet

        Returns a new Get object with the row, col, block, picture, and
        colorSpec instance variables set from the supplied arguments.

More ...

See Also: @…GET READ READMODAL() READVAR() SETCOLOR()

 

C5 Error Class

Error Class Overview

     Provides objects containing information about runtime errors

Description

     An Error object is a simple object that contains information pertaining
     to a runtime error.  Error objects have no methods, only exported
     instance variables.  When a runtime error occurs, CA-Clipper creates a
     new Error object and passes it as an argument to the error handler block
     specified with the ERRORBLOCK() function.  Within the error handler, the
     Error object can then be queried to determine the nature of the error
     condition.

     Error objects can also be returned to the RECOVER statement of a BEGIN
     SEQUENCE construct with a BREAK statement.  Here, the error object can
     be queried for local error handling.  For more detailed information and
     examples refer to the Error Handling Strategies chapter in the
     Programming and Utilities guide.

 Examples

     .  This example demonstrates how a file open operation might be
        handled in an error handler replicating the default CA-Clipper
        behavior.  When, for example, an attempt to open a database file with
        a USE command fails, control returns to the statement following the
        offending command:

        #include "Error.ch"
        #command RETRY      => RETURN (.T.)    // Retry operation
        #command RESUME     => RETURN (.F.)    // Default recovery
        //

        FUNCTION MyError( objError )
           //
           // Handle file open error
           IF objError:genCode == EG_OPEN .AND.;
              objError:canDefault .AND.;
              NETERR()
              //
              RESUME
           ENDIF
           .
           . <other error statements>
           .
           RETURN NIL

     .  This example retries an operation within an error handler a
        specified number of times:

        #include "Error.ch"
        #command RETRY      => RETURN (.T.)    // Retry operation
        #command RESUME     => RETURN (.F.)    // Default recovery
        //

        FUNCTION MyError( objError )
           //
           // Handle printer not ready error
           IF objError:genCode == EG_PRINT .AND.;
              objError:canRetry .AND.;
              objError:tries < 25
              //
              RETRY
           ENDIF
           .
           . <other error statements>
           .
           RETURN NIL

     .  This code fragment returns an error object from an error
        handler to the RECOVER statement for further processing:

        LOCAL objLocal, bLastHandler
        //
        // Save current and set new error handler
        bLastHandler := ERRORBLOCK({    |objErr| ;
                          MyHandler(objErr, .T.)})
        //
        BEGIN SEQUENCE
           .
           . <operation that might fail>
           .
        RECOVER USING objLocal
           .
           . <send messages to objLocal and handle the error>
           .
        END
        //
        // Restore previous error handler
        ERRORBLOCK( bLastHandler )

        FUNCTION MyHandler( objError, lLocalHandler )
           //
           // Handle locally returning the error object
           IF lLocalHandler
              BREAK objError
           ENDIF
           .
           . <other statements to handle the error>
           .
           RETURN NIL

 Files:  Header file is Error.ch, default error handler is in Errorsys.prg.

 
Class Function 

     ErrorNew()    Create a new error object
        ErrorNew() --> objError

        Returns a new Error object.


Exported Instance Variables

args                  An array of function or operator arguments (Assignable)

Contains an array of the arguments supplied to an operator or function when an  argument error occurs. For other types of errors, Error:args contains a NIL value.

canDefault   Indicates whether or not default recovery is available (Assignable)

Contains a logical value indicating whether the subsystem can perform default error recovery for the error condition. A value of true (.T.) indicates that default recovery  is available. Availability of default handling and the actual default recovery strategy  depends on the subsystem and the error condition. The minimum action is simply to  ignore the error condition.

Default recovery is requested by returning false (.F.) from the error block invoked to handle the error. Note that Error:canDefault is never true (.T.) if Error:canSubstitute is true (.T.).

canRetry       Indicates whether or not a retry is possible after an error (Assignable)

Contains a logical value indicating whether the subsystem can retry the operation that caused the error condition. A value of true (.T.) indicates that a retry is possible. Retry may or may not be available, depending on the subsystem and the error condition.

Retry is requested by returning true (.T.) from the error block invoked to handle the error. Note that Error:canRetry never contains true (.T.) if Error:canSubstitute contains true (.T.).

canSubstitute Indicates if a new result can be substituted after an error (Assignable)

Contains a logical value indicating whether a new result can be substituted for the operation that produced the error condition. Argument errors and certain other simple errors allow the error handler to substitute a new result value for the failed operation. A value of true (.T.) means that substitution is possible.

The substitution is performed by returning the new result value from the code block invoked to handle the error. Note that Error:canSubstitute is never true (.T.) if either Error:canDefault or Error:canRetry is true (.T.).

description  Character description of the error condition (Assignable)

Contains a character string that describes the error condition.  A zero-length string indicates that the subsystem does not provide a printable description for the error. If Error:genCode is not zero, a printable description is always available.

filename        Name of the file associated with the error (Assignable)

Contains a character value representing the name originally used to open the file associated with the error condition. A zero-length string indicates either that the error condition is not associated with a particular file or that the subsystem does not retain filename information.

genCode        Clipper error code number (Assignable)

Contains an integer numeric value representing a Clipper generic error code. Generic error codes allow default handling of similar errors from different subsystems. A value of zero indicates that the error condition is specific to the subsystem and does not correspond to any of the generic error codes. The header file, Error.ch, provides a set of manifest constants for generic error codes.

operation     Character description of the failed operation (Assignable)

Contains a character string that describes the operation being attempted when the error occurred. For operators and functions, Error:operation contains the name of the operator or function. For undefined variables or functions, it contains the name of the variable or function. A zero-length string indicates that the subsystem does not provide a printable description of the operation.

osCode            Operating system error code number (Assignable)

Contains an integer numeric value representing the operating system error code associated with the error condition. A value of zero indicates that the error condition was not caused by an error from the operating system. When Error:osCode is set to a value other than zero DOSERROR() is updated with the same value.

Error:osCode properly reflects the DOS extended error code for file errors. This allows proper distinction between errors which result from sharing violations (e.g., opening EXCLUSIVE when another process has already opened the file) and access violations (e.g., opening read/write when the file is marked read-only).

For a list of DOS error codes refer to the Error Messages and Appendices guide.

severity          Indicates error severity (Assignable)

Contains a numeric value indicating the severity of the error condition. Four standard values are defined in Error.ch:

Error:severity Values
———————————————————————
Error.ch               Meaning
———————————————————————
ES_WHOCARES The condition does not represent a failure; the
error is informational.
ES_WARNING  The condition does not prevent further operations,
but may result in a more serious error later.
ES_ERROR         The condition prevents further operations without
corrective action of some kind.
ES_CATASTROPHIC The condition requires immediate termination of
the application.
———————————————————————

Note that the Clipper runtime support code only generates errors with severities of ES_WARNING or ES_ERROR.

subCode         Subsystem-specific error code number (Assignable)

Contains an integer numeric value representing a subsystem-specific error code. A value of zero indicates that the subsystem does not assign any particular number to the error condition.

subSystem   Character description of the subsystem generating the error (Assignable)

Contains a character string representing the name of the subsystem generating the error. For errors with basic Clipper operators and functions, the subsystem name “BASE” is given. For errors generated by a database driver, Error:subSystem contains the name of the database driver.

tries                   Number of times the failed operation has been attempted (Assignable)

Contains an integer numeric value representing the number of times the failed operation has been attempted. When Error:canRetry is true (.T.), Error:tries can be used to limit the number of retry attempts. A value of zero indicates that the subsystem does not track the number of times the operation has been tried.

See Also: BEGIN SEQUENCE DOSERROR() ERRORBLOCK() NETERR()

C5 UI – TBrowse Classes

C5 UI – TBrowse Classes

TBrowse :

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.

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

Exported Instance Variables:

autoLite : Logical value to control highlighting (Assignable)

Contains a logical value. When autoLite is set to true (.T.), the stabilize method automatically highlights the current cell as part of stabilization. The default for autoLite is true (.T.).

cargo : User-definable variable  (Assignable)

Contains a value of any data type provided as a user-definable slot. TBrowse:cargo allows arbitrary information to be attached to a TBrowse object and retrieved later.

colCount : Number of browse columns

Contains a numeric value indicating the total number of data columns in the browse. For each column, there is an associated TBColumn object.

colorSpec : Color table for the TBrowse display (Assignable)

Contains a character string defining a color table for the TBrowse display. As a default, the current SETCOLOR() value is copied into this variable when the TBrowse object is created (see the SETCOLOR() reference in this chapter).

colPos : Current cursor column position (Assignable)

Contains a numeric value indicating the data column where the browse cursor is currently located. Columns are numbered from one, starting with the leftmost column.

colSep : Column separator character  (Assignable)

Contains a character value that defines a column separator for TBColumns that do not contain a column separator of their own (see TBColumn class in this chapter for more information).

footSep : Footing separator character (Assignable)

Contains a character value that defines a footing separator for TBColumns not containing a footing separator of their own (see TBColumn class in this chapter).

freeze : Number of columns to freeze (Assignable)

Contains a numeric value that defines the number of data columns frozen on the left side of the display. Frozen columns are always visible, even when other columns are panned off the display.

goBottomBlock : Code block executed by TBrowse:goBottom() (Assignable)

Contains a code block executed in response to the TBrowse:goBottom() message. This block is responsible for repositioning the data source to the last record displayable in the browse. Typically the data source is a database file, and this block contains a call to a user-defined function that executes a GO BOTTOM command.

goTopBlock : Code block executed by TBrowse:goTop() (Assignable)

Contains a code block that is executed in response to the TBrowse:goTop() message. This block is responsible for repositioning the data source to the first record displayable in the browse. Typically the data source is a database file, and this block contains a call to a user-defined function that executes a GO TOP command.

headSep : Heading separator character  (Assignable)

Contains a character value that defines a heading separator for TBColumns not containing a heading separator of their own (see TBColumn class in this chapter).

hitBottom : Indicates the end of available data (Assignable)

Contains a logical value indicating whether an attempt was made to navigate beyond the end of the available data. TBrowse:hitBottom contains true (.T.) if an attempt was made; otherwise it contains false (.F.). During stabilization, the TBrowse object sets this variable if TBrowse:skipBlock indicates it was unable to skip forward as many records as requested.

hitTop : Indicates the beginning of available data  (Assignable)

Contains a logical value indicating whether an attempt was made to navigate past the beginning of the available data. TBrowse:hitTop contains true (.T.) if an attempt was made; otherwise it contains false (.F.). During stabilization, the TBrowse object sets this variable if TBrowse:skipBlock indicates that it was unable to skip backward as many records as requested.

leftVisible : Indicates position of leftmost unfrozen column in display

Contains a numeric value indicating the position of the leftmost unfrozen column visible in the browse display. If every column is frozen in the display, TBrowse:leftVisible contains zero.

nBottom : Bottom row number for the TBrowse display  (Assignable)

Contains a numeric value defining the bottom screen row used for the TBrowse display.

nLeft : Leftmost column for the TBrowse display (Assignable)

Contains a numeric value defining the leftmost screen column used for the TBrowse display.

nRight : Rightmost column for the TBrowse display (Assignable)

Contains a numeric value defining the rightmost screen column used for the TBrowse display.

nTop : Top row number for the TBrowse display  (Assignable)

Contains a numeric value defining the top screen row used for the TBrowse display.

rightVisible : Indicates position of rightmost unfrozen column in display

Contains a numeric value indicating the position of the rightmost unfrozen column visible in the browse display. If all columns visible in the display are frozen, TBrowse:rightVisible contains zero.

rowCount : Number of visible data rows in the TBrowse display

Contains a numeric value indicating the number of data rows visible in the browse display. Only data rows are included in the count. Rows occupied by headings, footings, or separators are not included.

rowPos : Current cursor row position

skipBlock : Code block used to reposition data source (Assignable)

Contains a code block that repositions the data source. During stabilization, this code block is executed with a numeric argument when the TBrowse object needs to reposition the data source. The numeric argument passed to the block represents the number of records to be skipped. A positive value means skip forward, and a negative value means skip backward. A value of zero indicates that the data source does not need to be repositioned, but the current record may need to be refreshed. Typically the data source is a database file, and this block calls a user-defined function that executes a SKIP command to reposition the record pointer.

The block must return the number of rows (positive, negative, or zero) actually skipped. If the value returned is not the same as the value requested, the TBrowse object assumes that the skip operation encountered the beginning or end of file.

stable : Indicates if the TBrowse object is stable  (Assignable)

Contains a logical value indicating whether the TBrowse object is stable. It contains true (.T.) if the TBrowse object is stable; otherwise, it contains false (.F.). The browse is considered stable when all data has been retrieved and displayed, the data source has been repositioned to the record corresponding to the browse cursor, and the current cell has been highlighted. When navigation messages are sent to the TBrowse object, TBrowse:stable is set to false (.F.). After stabilization is performed using the TBrowse:stabilize() message, TBrowse:stable is set to true (.T.).

Exported Methods:

Cursor Movement Methods :

down() : Moves the cursor down one row

down() --> self

Moves the browse cursor down one row. If the cursor is already on the bottom row, the display is scrolled up and a new row is brought into view. If the data source is already at the logical end of file and the browse cursor is already on the bottom row, TBrowse:hitBottom is set true (.T.).

end() : Moves the cursor to the rightmost visible data column

end() --> self

Moves the browse cursor to the rightmost data column currently visible.

goBottom() : Repositions the data source to the bottom of file

goBottom() --> self

Repositions the data source to logical bottom of file (by evaluating the TBrowse:goBottomBlock), refills the display with the bottommost available data, and moves the browse cursor to the lowermost data row for which data is available. The pan position of the window is not changed.

goTop() : Repositions the data source to the top of file

goTop() --> self

Repositions the data source to the logical beginning of file (by evaluating the TBrowse:goTopBlock), refills the display with the topmost available data, and moves the browse cursor to the uppermost data row for which data is available. The pan position of the window is not changed.

home() : Moves the cursor to the leftmost visible data column

home() --> self

Moves the browse cursor to the leftmost unfrozen column on the display.

left() : Moves the cursor left one column

left() --> self

Moves the browse cursor left one data column. If the cursor is already on the leftmost displayed column, the display is panned and the previous data column (if there is one) is brought into view.

pageDown() : Repositions the data source downward

pageDown() --> self

Repositions the data source downward and refills the display. If the data source is already at the logical end of file (i.e., the bottommost available record is already shown), the browse cursor is simply moved to the lowermost row containing data. If the data source is already at the logical end of file and the browse cursor is already on the bottom row, TBrowse:hitBottom is set true (.T.).

pageUp() : Repositions the data source upward

pageUp() --> self

Repositions the data source upward and refills the display. If the data source is already at logical beginning of file (i.e., the topmost available record is already shown), the browse cursor is simply moved to the top data row. If the data source is already at logical beginning of file and the browse cursor is already on the first data row, TBrowse:hitTop is set true (.T.).

panEnd() : Moves the cursor to the rightmost data column

panEnd() --> self

Moves the browse cursor to the rightmost data column, causing the display to be panned completely to the right.

panHome() : Moves the cursor to the leftmost visible data column

panHome() --> self

Moves the browse cursor to the leftmost data column, causing the display to be panned all the way to the left.

panLeft() : Pans left without changing the cursor position

panLeft() --> self

Pans the display without changing the browse cursor, if possible. When the screen is panned with TBrowse:panLeft(), at least one data column out of view to the left is brought into view, while one or more columns are panned off screen to the right.

panRight() : Pans right without changing the cursor position

panRight() --> self

Pans the display without changing the browse cursor, if possible. When the screen is panned with TBrowse:panRight(), at least one data column out of view to the right is brought into view, while one or more columns are panned off the screen to the left.

right() : Moves the cursor right one column

right() --> self

Moves the browse cursor right one data column. If the cursor is already at the right edge, the display is panned and the next data column (if there is one) is brought into view.

up() : Moves the cursor up one row

up() --> self

Moves the browse cursor up one row. If the cursor is already on the top data row, the display is scrolled down and a new row is brought into view. If the data source is already at the logical beginning of file and the browse cursor is already on the top data row, TBrowse:hitTop is set true (.T.).

Miscellaneous Methods :

addColumn() : Adds a TBColumn object to the TBrowse object

addColumn(<objColumn>) --> self

Adds a new TBColumn object to the TBrowse object and TBrowse:colCount is increased by one.

colorRect() : Alters the color of a rectangular group of cells

colorRect(<aRect>, <aColors>) --> self

Directly alters the color of a rectangular group of cells. <aRect> is an array of four numbers (top, left, bottom, and right). The numbers refer to cells within the data area of the browse display, not to screen coordinates. <aColors> is an array of two numbers. The numbers are used as indexes into the color table for the browse. These colors will become the normal and highlighted colors for the cells within the specified rectangle.

Cells that are colored using colorRect retain their color until they are scrolled off the screen up or down. Horizontal panning has no affect on these colors and, in fact, cells that are currently off screen left or right can be colored even if they are not visible.

This example colors the entire virtual window (on and off screen):

aRect := {1, 1, browse:rowCount, browse:colCount} browse:colorRect( aRect, {2, 1} )

colWidth() : Returns the display width of a particular column

colWidth(<nColumn>) --> nWidth

Returns the display width of column number <nColumn> as known to the browse. If <nColumn> is out of bounds or not supplied or not a number, the method returns zero.

configure() : Reconfigures the internal settings of the TBrowse object

configure() --> self

Causes the TBrowse object to reexamine all instance variables and TBColumn objects, reconfiguring its internal settings as required. This message can force reconfiguration when a TBColumn object is modified directly.

deHilite() : Dehighlights the current cell

deHilite() --> self

Causes the current cell (the cell to which the browse cursor is positioned) to be dehighlighted. This method is designed for use when TBrowse:autoLite is set to false (.F.).

delColumn() : Delete a column object from a browse

delColumn(<nPos>) --> objColumn

This new method allows a column to be deleted from a browse. The return value is a reference to the column object being deleted so that the column object may be preserved.

forceStable() : Performs a full stabilization .

forceStable()

Performs a full stabilization of the TBrowse. It is analogous to the following code, only slightly faster:

         DO WHILE .NOT. oBrowse:stabilize()
         ENDDO

getColumn() : Gets a specific TBColumn object

getColumn(<nColumn>) --> objColumn

Returns the TBColumn object specified by <nColumn>.

hilite() : Highlights the current cell

hilite() --> self

Causes the current cell (the cell to which the browse cursor is positioned) to be highlighted. This method is designed for use when TBrowse:autoLite is set to false (.F.).

insColumn() : Insert a column object in a browse

insColumn(<nPos>, <objColumn>) --> objColumn

This method allows a column object to be inserted into the middle of a browse. The return value is a reference to the column object being inserted.

invalidate() : Forces redraw during next stabilization

invalidate() --> self

TBrowse:invalidate() causes the next stabilization of the TBrowse object to redraw the entire TBrowse display, including headings, footings, and all data rows. Note that sending this message has no effect on the values in the data rows; it simply forces the display to be updated during the next stabilization. To force the data to be refreshed from the underlying data source, send the TBrowse:refreshAll() message.

refreshAll() : Causes all data to be refreshed during the next stabilize

refreshAll() --> self

Internally marks all data rows as invalid, causing them to be refilled and redisplayed during the next stabilize loop.

refreshCurrent() : Causes the current row to be refreshed on next stabilize

refreshCurrent() --> self

Internally marks the current data row as invalid, causing it to be refilled and redisplayed during the next stabilize loop.

setColumn() : Replaces one TBColumn object with another

setColumn(<nColumn>, <oColumnNew>) --> oColumnCurrent

Replaces the TBColumn object indicated by <nColumn> with the TBColumn object specified by <oColumnNew>. The value returned is the current TBColumn object.

stabilize() : Performs incremental stabilization

stabilize() --> lStable

Performs incremental stabilization. Each time this message is sent, some part of the stabilization process is performed. Stabilization is performed in increments so that it can be interrupted by a keystroke or other asynchronous event.

If the TBrowse object is already stable, a value of true (.T.) is returned. Otherwise, a value of false (.F.) is returned indicating that further stabilize messages should be sent. The browse is considered stable when all data has been retrieved and displayed, the data source has been repositioned to the record corresponding to the browse cursor, and the current cell has been highlighted.

TBColumn :

Provides the column objects TBrowse objects.

Description :

A TBColumn object is a simple object containing the information needed to fully define one data column of a TBrowse object (see the TBrowse reference in this chapter). TBColumn objects have no methods, only exported instance variables.

Class Function :

TBColumnNew() :

Create a new TBColumn object.

TBColumnNew(<cHeading>, <bBlock>) --> objTBColumn

Exported Instance Variables :

block : Code block to retrieve data for the column (Assignable)

Contains a code block that retrieves data for the column. Any code block is valid, and no block arguments are supplied when the block is evaluated. The code block must return the appropriate data value for the column.

cargo : User-definable variable (Assignable)

Contains a value of any data type provided as a user-definable slot, allowing arbitrary information to be attached to a TBColumn and retrieved later.

colorBlock : Code block that determines color of data items (Assignable)

Contains an optional code block that determines the color of data items as they are displayed. If present, this block is executed each time a new value is retrieved via the TBColumn:block (the data retrieval block). The newly retrieved data value is passed as an argument to the TBColumn:colorBlock, which must return an array containing two numeric values. The values returned are used as indexes into the color table of the TBrowse object as described in the TBColumn:defColor reference below.

The TBColumn:colorBlock allows display colors for data items based on the value of the data being displayed. For example, negative numbers may be displayed in a different color than positive numbers.

colSep : Column separator character (Assignable)

Contains an optional character string that draws a vertical separator to the left of this column if there is another column to the left of it. If no value is supplied for TBColumn:colSep, the value contained in TBrowse:colSep is used instead.

defColor : Array of numeric indexes into the color table (Assignable)

Contains an array of two numeric values used as indexes into the color table in the TBrowse object. The first value determines the unselected color which displays headings, footings, etc. It also displays data values when the browse cursor is not on the data value being displayed. The second value determines the selected color. The selected color displays the current browse cell.

The default value for TBColumn:defColor is {1, 2}. This causes the first two colors in the TBrowse color table to be used for unselected and selected, respectively. Note that colors set using TBColumn:colorBlock override those set by TBColumn:defColor.

footing : Column footing (Assignable)

Contains a character value that defines the footing for this data column.

footSep : Footing separator character (Assignable)

Contains a character value that draws a horizontal line between the data values and the footing. If it does not contain a character value: TBrowse:footSep is used instead.

heading : Column heading (Assignable)

Contains a character value that defines the heading for this data column.

headSep : Heading separator character (Assignable)

Contains an optional character string that draws a horizontal separator between the heading and the data values. If it does not contain a character value, the TBrowse:headSep is used instead.

width : Column display width  (Assignable)

Contains a numeric value that defines the display width for the column. If TBColumn:width is not explicitly set, the width of the column will be the greater of: the length of the heading, the length of the footing, or the length of the data at the first evaluation of TBColumn:block.

If this instance variable is explicitly set, the width of the column will be TBColumn:width. Displayed headings, footings, and data will all be truncated to this width when necessary. The width of the displayed data will be the length at the first evaluation of TBColumn:block for all data types other than character. Character data will be extended to TBColumn:width for display purposes.

Example :

This example is a code fragment that creates a TBrowse object and adds some TBColumn objects to it:

USE Customer NEW
//
// Create a new TBrowse object
objBrowse := TBrowseDB(1, 1, 23, 79)
//
// Create some new TBColumn objects and
// add them to the TBrowse object
objBrowse:addColumn(TBColumnNew( "Customer", ;
                    {|| Customer->Name} ))
objBrowse:addColumn(TBColumnNew( "Address", ;
                    {|| Customer->Address} ))
objBrowse:addColumn(TBColumnNew( "City", ;
                    {|| Customer->City} ))
.
. <statements to actually browse the data>
.
CLOSE Customer

For a simple and working sample look at here.

 

C5 UI – Menu System

C5 UI – Menu System 

@…PROMPT :

Paint a menu item and define a message

@ <nRow>, <nCol> PROMPT <cMenuItem>
     [MESSAGE <cExpression>]

MENU TO :

Execute a lightbar menu for defined PROMPTs

     MENU TO <idVar>

          MENUMODAL :

Activate a top bar menu

         MENUMODAL(<oTopBar>, <nSelection>, <nMsgRow>,
             <nMsgLeft>, <nMsgRight>, <cMsgColor>) --> MenuID

SET MESSAGE :

Set the @…PROMPT message line row

SET MESSAGE TO [<nRow> [CENTER | CENTRE]]

SET INTENSITY :

Toggle enhanced display of GETs and PROMPTs

SET INTENSITY ON | off | <xlToggle>

SET WRAP :

Toggle wrapping of the highlights in MENUs

SET WRAP on | OFF | <xlToggle>