Class XbpQuickBrowse() Foundation

Class function of the XbpQuickBrowse class

Superclass
Description

The XbpQuickBrowse() class is used for fast browsing of tabular data. The major difference to the XbpBrowse() class is that an XbpQuickBrowse object has a higher level of autonomy than an XbpBrowse object and, therefore, less possibilities to configure the appearance of the browser. Instead of embedding XbpColumn() objects for displaying the columns in the browser, an XbpQuickBrowse object uses a single object of the XbpMultiCellGroup() class to visualize alldata columns of the browser. This reduces the GUI resources required by the browser drastically and allows for a fast creation of the browse object.

The next major difference to the XbpBrowse() class is the lack of most of the navigation code blocks which operate directly on the data source of the browser, be it an array or a database opened in a work area. The data source for an XbpQuickBrowse object must be an object of the DacPagedDataStore() class that needs to be assigned to the instance variable :dataLink before the :create() method is called for the XbpQuickBrowse object.

When the XbpQuickBrowse object is created and visible, it communicates with its data source object stored in :dataLink and calls the appropriate methods for navigating the record pointer of the data source when a keyboard or mouse event occurs within the browser. The following events are recognized by an XbpQuickBrowse object:

Events recognized by an XbpQuickBrowse object
Event constant Reaction
xbeK_LEFT One column to the left
xbeK_RIGHT One column to the right
xbeK_UP Moves browse cursor to previous record
xbeK_DOWN Moves browse cursor to next record
xbeK_PGUP Displays previous page
xbeK_DOWN Displays next page
xbeK_CTRL_UP Scrolls the browse display one record up without moving the browse cursor
xbeK_CTRL_DOWN Scrolls the browse display one record down without moving the browse cursor
xbeK_CTRL_PGUP Displays first page
xbeK_CTRL_PGDN Displays last page
xbeK_HOME Displays first column
xbeK_END Displays last column
xbeK_RETURN Evaluates the :itemSelected code block
xbeM_LbDown Moves browse cursor to mouse pointer and evaluates the :itemMarked code block
xbeM_LbDblClick Evaluates the :itemSelected code block

Since the data source of an XbpQuickBrowse object is a PagedDataSource object, it is possible to scroll the browse display without moving the browse cursor. This is achieved with the key combinations Ctrl+Up arrow and Ctrl+Down arrow or when navigation is done via the vertical scrollbar. As a consequence, the browse cursor does not reflect the actual position of the record pointer of the physical data source maintained by the PagedDataSource object. The browse cursor can even be scrolled off the browse display. The method :getData() must be called to obtain the position of the data source's record pointer that matches with the position of the browse cursor.

Class methods
:new()
Creates an instance of the XbpQuickBrowse class.
Configuration

The instance variables in this group configure system resources. If changes are made to the default values, they must be made before the :create() method is executed or :configure() must be called to activate the changes.

:cursorMode
Selects the cursor mode of the browser.
:dataLink
The object providing the data source of the browser.
:drawMode
Specifies the drawing mode of the XbpQuickBrowse object.
:hScroll
Display a horizontal scroll bar.
:style
Selects a pre-defined style for the browser display.
:useVisualStyle
Determines whether the object uses Visual Styles for display.
:vScroll
Display a vertical scroll bar
Runtime
:colCount
Contains the number of columns in the XbpQuickBrowse object.
:colPos
Contains the current column position of the browse cursor.
:dataArea
The object displaying the data columns in the browser.
:heading
The object displaying the column headings in the browser.
:hScrollObject
The object displaying the horizontal scroll bar.
:rowCount
Contains the number of visible rows in the data area of the browser.
:rowPos
Contains the current row position of the browse cursor.
:vScrollObject
The object displaying the vertical scroll bar.
Navigation code blocks
:beginStabilize
Browser begins with stabilization.
:endStabilize
Browser stabilization is finished.
Life cycle
:create()
Requests system resources for the XbpQuickBrowse object.
:configure()
Reconfigures the XbpQuickBrowse object after :create() has been executed.
:destroy()
Releases the system resources of the XbpQuickBrowse object.
Methods for columns
:getColRepresentation()
Determines the images defined for the visual representation of a value.
:getColType()
Retrieves the type attributes of a column.
:getColWidth()
Determines the width of a column in pixel.
:getRowHeight()
Determines the height of the rows in pixel.
:setColRepresentation()
Defines the visual representation of data displayed in a column.
:setColType()
Defines the display type of a column.
:setColWidth()
Sets the column width in pixel.
:setHeader()
Sets the column headers.
:setRowHeight()
Sets the row height in pixel.
Cursor navigation
:down()
Displays the next record.
:goBottom()
Displays the last page.
:goTop()
Displays the first page.
:goToRecord()
Moves the browse cursor to a particular record.
:left()
Displays the next column to the left.
:pageDown()
Displays the next page.
:pageUp()
Displays the previous page.
:panFirstCol()
Displays the first column.
:panLastCol()
Displays the last column
:right()
Displays the next column to the right.
:up()
Displays the previous record.
Display methods
:cellRect()
Determines the graphical X/Y coordinates of a single cell.
:deHilite()
Displays the browse cursor in normal color.
:drawRow()
Displays values in one browser row.
:forceStable()
Forces complete stabilization of the display.
:hilite()
Displays the browse cursor in highlight color.
:refreshAll()
Refreshes all data rows in the browse window.
:refreshRows()
Refreshes particular data rows in the browse window.
Data access
:getData()
Determines the record ID of the record matching the browse cursor.
:setDataLink()
Specify a new datalink for the object or return the old one.
Events
:customDrawCell
A cell within an owner-drawn XbpQuickBrowse object needs to be redrawn.
:itemMarked
Left mouse button is pressed on a data row of the browser.
:itemSelected
Left double click or return key is pressed.
Examples
Browsing a database
// This example shows the minimum code required for browsing a 
// database with an XbpQuickBrowse object. The example uses the 
// default application window created in AppSys (XbpCrt window) 

  // make sure to link the correct libraries 
  #pragma Library( "Adac20b.lib" ) 

  #include "Appevent.ch" 

  PROCEDURE Main 
     LOCAL nEvent, mp1, mp2, oXbp 

     // Open a database file before creating 
     // an XbpQuickBrowse object 
     USE Customer 
     INDEX ON Upper(LASTNAME+FIRSTNAME) TO Cust_A 

     // {640,400} is the default size of the display 
     // area inside an XbpCrt window 
     oXbp := XbpQuickBrowse():new(,,, {640,400} ) 

     // Assign the data store object 
     oXbp:dataLink := DacPagedDataStore():new() 

     // Request system resources for the browser 
     // after the data source object is assigned 
     oXbp:create() 

     // Set focus to the browser 
     SetAppFocus( oXbp ) 

     // Run the event loop 
     DO WHILE nEvent <> xbeP_Close 
        nEvent := AppEvent( @mp1, @mp2, @oXbp ) 
        oXbp:handleEvent( nEvent, mp1, mp2 ) 
     ENDDO 
  RETURN 
Browsing an array
// This example demonstrates how to use an XbpQuickBrowse object 
// for browsing a two-dimensional array. 

#pragma Library( "Adac20b.lib" ) 

#include "Appevent.ch" 
#include "Directry.ch" 

PROCEDURE Main 
   LOCAL nEvent, mp1, mp2, oXbp 

   // The directory array is the data source 
   LOCAL aData    := Directory( "*.*" ) 

   // Array columns to display 
   LOCAL aColumns :=    { ; 
         F_NAME         , ; 
         F_SIZE         , ; 
         F_WRITE_DATE   , ; 
         F_WRITE_TIME   , ; 
         F_CREATION_DATE, ; 
         F_CREATION_TIME  } 

   // Column headings 
   LOCAL aHeader  :=    { ; 
         "File name"    , ; 
         "File size"    , ; 
         "Access date"  , ; 
         "Access time"  , ; 
         "Creation date", ; 
         "Creation time"  } 

   oXbp          := XbpQuickBrowse():new(,,, {640,400} ) 

   // Assign the data store object 
   oXbp:dataLink := DacPagedDataStore():new( aData   , ; 
                                             aColumns  ) 

   // Request system resources and assign headers 
   oXbp:create() 
   oXbp:setHeader( aHeader ) 

   SetAppFocus( oXbp ) 

   DO WHILE nEvent <> xbeP_Close 
      nEvent := AppEvent( @mp1, @mp2, @oXbp ) 
      oXbp:handleEvent( nEvent, mp1, mp2 ) 
   ENDDO 
RETURN 

Feedback

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.