Class XbpBrowse() Foundation

Class function of the XbpBrowse class

Superclass
Description

General description: The XbpBrowse class is used to create a GUI browser to display data organized in table form. These can be databases or arrays. An XbpBrowse object on its own is a container for XbpColumn objects which are necessary to display a single column of a table. An XbpColumn object has a data code block to retrieve data, for example from a database field, and displays it on the screen.

Similar to the TBrowse class (text mode browser), the :addColumn()method is used to add a table column, or XbpColumn object, to an XbpBrowse object. The latter is not able to display table data on its own, it rather navigates through a table and positions columns on the screen.

Navigation: An XbpBrowse object navigates through a table by means of a browse cursor that can be configured optionally as a row cursor or a cell cursor. The browse cursor corresponds to the record pointer of the underlying data source, and both are automatically synchronized during navigation. To enable an XbpBrowse object to navigate, seven code blocks must be assigned to the object, three of which are used to configure a vertical scroll bar (see the example).

Display: Data is displayed on screen when an XbpBrowse object executes its :forceStable() method. Normally, this method need not be called in a program explicitly. It is executed automatically when an XbpBrowse object processes the xbeBRW_ForceStable event. This event is created by navigation methods, such as :up(), :left()or :pageDown(). This means, an XbpBrowse object has a default behaviour to react to keyboard or mouse events.

Difference to TBrowse: For an XbpBrowse object to display a table, it is sufficient to assign navigation code blocks to the object. This is a major difference between the TBrowse and XbpBrowse class. A TBrowse object requires code to be implemented for display (DO WHILE .NOT. oBrowse:stabilize()) and to process keyboard input. This is not the case with an XbpBrowse object, because it displays data and processes events within the event loop (nEvent := AppEvent() ; oBrowse:handleEvent(nEvent)).

Event handling: The next table lists all keys which are recognized by an XbpBrowse object for navigation:

Keys which are processed by XbpBrowse
Key Description
Left Arrow One column to the left
Right Arrow One column to the right
Up Arrow Previous record
Down Arrow Next record
Ctrl+Up Arrow Scrolls the display down a line
Ctrl+Down Arrow Scrolls the display up a line
Page Up Previous screen
Page Down Next screen
Ctrl+Page Up First record
Ctrl+Page Down Last record
Home First column
End Last column
Return Evaluates :itemSelected code block
Left click Moves browse cursor to mouse pointer
Left double click Evaluates :itemSelected code block

Configuration: The appearance of a table on screen can be configured very detailed by means of presentation parameters. When an XbpBrowse object is created presentation parameters can be specified, too, which are valid for XbpColumn objects. These settings are then used by all XbpColumn objects subsequently added to the XbpBrowse object.

Class methods
:new()
Creates instances of the XbpBrowse class.
Configuration

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

:cursorMode
Selects the cursor mode of the browser.
:drawMode
Specifies the drawing mode of the browse object.
:hScroll
Display a horizontal scroll bar
:navigationMode
Sets the navigation mode.
:sizeCols
Allow the width of columns to be changed with the mouse.
:softTrack
Scroll the display only when the left mouse button is released.
:useVisualStyle
Determines whether the object uses Visual Styles for display.
:vScroll
Display a vertical scroll bar
Runtime
:colCount
Contains the number of columns (XbpColumn objects) in the XbpBrowse object.
:colPos
Contains the current column position of the browse cursor.
: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.
:rowPhyPos
Contains the physical position of the browse cursor.
:vScrollObject
The object displaying the vertical scroll bar.
Code blocks for navigation
:firstPosBlock
Code block returning the lower limit for the vertical scroll bar.
:goBottomBlock
Code block which moves the record pointer to the end of a table.
:goPosBlock
Code block which moves the record pointer via the vertical scroll bar.
:goPhyPosBlock
Code block which moves the record pointer to a physical position.
:goTopBlock
Code block which moves the record pointer to the beginning of a table.
:hitBottomBlock
Code block, evaluated when the record pointer hits the end of a table.
:hitTopBlock
Code block, evaluated when the record pointer hits the beginning of a table.
:lastPosBlock
Code block returning the upper linit for the vertical scroll bar
:phyPosBlock
Code block returning the physical position of the record pointer.
:posBlock
Code block returning the logical position of the record pointer.
:skipBlock
Code block that calls a routine moving the record pointer
:stableBlock
Indicates that the display of the browse is stable
Life cycle
:create()
Requests system resources for the XbpBrowse object.
:configure()
Reconfigures the XbpBrowse object after :create() has been executed.
:destroy()
Releases the system resources of the XbpBrowse object.
Methods for columns
:addColumn()
Attaches a column (XbpColumn object) to an XbpBrowse object.
:delColumn()
Deletes a column (XbpColumn object) from an XbpBrowse object.
:getColumn()
Retrieves a reference to a column (XbpColumn object ) in an XbpBrowse object.
:insColumn()
Inserts a column (XbpColumn object) into an XbpBrowse object.
:setColumn()
Replaces a column (XbpColumn object) within an XbpBrowse object.
:setLeftFrozen()
Freeze table columns on the left side of the browse window.
:setRightFrozen()
Freeze table columns on the right side of the browse window.
Cursor Navigation and Scrolling
:down()
Moves the browse cursor down one line.
:firstCol()
Moves the browse cursor to the first column defined in the XbpBrowse.
:goBottom()
Positions the record pointer to the last data record in the data source.
:goTop()
Positions record pointer to the first data record of the data source.
:lastCol()
Moves the browse cursor to the last column defined in the XbpBrowse.
:left()
Moves the browse cursor one column to the left.
:pageDown()
Moves the browse cursor one page down.
:pageUp()
Moves the browse cursor one page up.
:panDown()
Scrolls down one line.
:panEnd()
Scrolls to the last column defined in the XbpBrowse.
:panHome()
Scrolls to the first column defined in the XbpBrowse.
:panLeft()
Scrolls the browse window one column to the left.
:panPageDown()
Scrolls one page down.
:panPageUp()
Scrolls one page up.
:panRight()
Scrolls the browse window one column to the right.
:panUp()
Scrolls down up line.
:right()
Moves the browse cursor one column to the right.
:up()
Moves the browse cursor one row up.
Display methods
:deHilite()
Displays browse cursor in normal color.
:forceStable()
Forces complete stabilization of the display.
:hilite()
Displays the browse cursor in highlight color.
:refreshAll()
Refreshes all data rows in the browse window.
:refreshCurrent()
Refreshes the current data row in the browse window.
Data access
:getData()
Retrieves data from the current cell or row of the browser.
Asynchronous events
:footerRbDown
Right button is pressed in the footing of a column
:headerRbDown
Right button is pressed in the heading of a column
:itemMarked
Left mouse button is pressed on a data row of the browser
:itemRbDown
Right button is pressed on a data row of a column
:itemSelected
Left double click or return key is pressed
Synchronous events

Callback code blocks for synchronous messages differ from other callback code blocks by their return value. If the return value is NIL, the XbpBrowse object performs no further action. For any other return value, the XbpBrowse object shows its default behaviour after the code block is evaluated. Therefore, returning NIL suppresses the default behaviour of an XbpBrowse object.

:forceStable
Forces complete stabilization of the display.
:navigate
The browse cursor must be navigated.
:pan
Scroll the browse window horizontally.
:scroll
Scroll the browse window vertically.
:customDrawCell
A cell within an owner-drawn browse object needs to be redrawn.
Examples
Graphic browser for databases

// In the example, the user defined function GuiBrowseDB() is 
// programmed. It assigns all navigation code blocks to an 
// XbpBrowse object which are necessary to browse a database. 
// Table columns are created within a FOR..NEXT loop. 
// The browser is displayed in the event loop. 

#include "Appevent.ch" 
#include "Common.ch" 

PROCEDURE AppSys 
// Desktop remains application window 
RETURN 


PROCEDURE Main 
   LOCAL nEvent, mp1, mp2, oXbp, oBrowse, cField, i 

   USE Customer NEW 

   // Create a hidden dialog window 
   oXbp := GuiStdDialog( "Standard GUI Browser for DBF" ) 

   // Create browser in the window 
   oBrowse := GuiBrowseDb( oXbp:drawingArea ) 

   // Add columns for all fields of the database 
   FOR i:=1 TO FCount() 
      cField := FieldName( i ) 
      oBrowse:addColumn( FieldBlock(cField), , cField ) 
   NEXT 

   // The browser always fills the entire window after :resize() 
   oXbp:drawingArea:resize := ; 
      {|mp1,mp2,obj| obj:childList()[1]:setSize(mp2) } 

   oXbp:show() 
   oBrowse:show() 
   SetAppFocus( oBrowse ) 

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


****************************************************************** 
* Create a GUI browser with navigation code blocks for a database 
****************************************************************** 
FUNCTION GuiBrowseDB( oParent, aPos, aSize ) 
   LOCAL oBrowse 

   oBrowse := XbpBrowse():new( oParent,, aPos, aSize ):create() 

   // Navigation code blocks for the browser   
   oBrowse:skipBlock     := {|n| DbSkipper(n) } 
   oBrowse:goTopBlock    := {| | DbGoTop()    } 
   oBrowse:goBottomBlock := {| | DbGoBottom() } 
   oBrowse:phyPosBlock   := {| | Recno()      } 
   oBrowse:goPhyPosBlock := {|n| DbGoto(n)    } 

   // Navigation code blocks for the vertical scroll bar 
   oBrowse:posBlock      := {| | DbPosition()    } 
   oBrowse:goPosBlock    := {|n| DbGoPosition(n) } 
   oBrowse:lastPosBlock  := {| | 100             } 
   oBrowse:firstPosBlock := {| | 0               } 

RETURN oBrowse 


****************************************************************** 
* Create a hidden dialog window 
****************************************************************** 
FUNCTION GuiStdDialog( cTitle ) 
   LOCAL oDlg 

   DEFAULT cTitle TO "Standard Dialog Window" 

   oDlg          := XbpDialog():new( ,,{10,10}, {600,400},, .F. ) 
   oDlg:icon     := 1 
   oDlg:taskList := .T. 
   oDlg:title    := cTitle 
   oDlg:create() 
   oDlg:drawingArea:setFontCompoundName( "8.Helv" ) 

RETURN oDlg 
Example for browsing an array
// This example illustrates how XbpBrowse objects can be used for 
// browsing an array. In addition, the example shows how the 
// visualization of the browse can be adjusted for platforms which 
// support visual styles. This is important for computers running 
// Windows XP or newer. 

  ****************************************************************** 
  * IMPORTANT: A manifest file or resource must be added to the 
  * example! More information on defining manifests can be found 
  * in the documentation of the function "IsThemeActive()". 
  ****************************************************************** 

  #include "xbp.ch" 
  #include "appevent.ch" 

  #PRAGMA LIBRARY( "XPPUI2.LIB" ) 

  // Global variables for maintaining 
  // the data source (array) 
  STATIC aData 
  STATIC nLastRec 
  STATIC nRecno   

  PROCEDURE Main() 

   LOCAL oBrowse 
   LOCAL nEvent 
   LOCAL oXbp := NIL 
   LOCAL mp1  := NIL 
   LOCAL mp2  := NIL 
   LOCAL oCol 
   LOCAL nWidth 
   LOCAL oGroup 

     // Configure the application window (XbpCrt) 
     SetMouse( .T. ) 
     SetColor( "N/W+" ) 
     CLS 
     SetAppWindow():UseShortCuts := .T. 

     // Create group box as backdrop for the 
     // browse 
     oGroup := XbpStatic():New() 
     oGroup:Type    := XBPSTATIC_TYPE_GROUPBOX 
     oGroup:Caption := "Inventory" 
     oGroup:Create( ,,, {440,250} ) 

     CenterControl( oGroup ) 

     // Initialize array data for the browse as 
     // well as associated status variables 
     aData    := { {"Magazines",  133, .T.},; 
                   {"Newspapers", 15,  .T.},; 
                   {"Books",      32,  .T.},; 
                   {"Postcards",  833, .F.} } 
     nLastRec := Len(aData) 
     nRecno   := 1 

     // Create the browse and associate it with the 
     // data source. Note that visual styles are 
     // switched off to ensure that cell frames are 
     // displayed as configured, irrespective of the 
     // operating system being used 
     oBrowse := XbpBrowse():New( oGroup ) 
     oBrowse:SkipBlock     := {|nSkip,oBrowse| DoSkip(nSkip,oBrowse) } 
     oBrowse:GoBottomBlock := {||  nRecno := Len(aData) } 
     oBrowse:GoTopBlock    := {||  nRecno := 1 } 
     oBrowse:PosBlock      := {||  nRecno } 
     oBrowse:PhyPosBlock   := {||  nRecno } 
     oBrowse:GoPhyPosBlock := {|n| nRecno := n } 

     oBrowse:LastPosBlock  := {|| Len(aData) } 
     oBrowse:FirstPosBlock := {|| 1 } 
     oBrowse:CursorMode    := XBPBRW_CURSOR_ROW 
     oBrowse:UseVisualStyle := .F. 
     oBrowse:Create( ,, {20,20}, {400,200},, .F. ) 

     // Add columns to the browse 
     oBrowse:AddColumn( {|| aData[nRecno,1]}, 15, "Publication" ) 
     oBrowse:AddColumn( {|| aData[nRecno,2]}, 5,  "In Stock" ) 
     oBrowse:AddColumn( {|| aData[nRecno,3]}, 1,  "Web Shop" ) 

     // Enable visual styles for the scroll 
     // bars. This way, the data area remains 
     // fully configurable while the scroll 
     // bars use platform-default visuals. 
     oBrowse:HScrollObject:UseVisualStyle  := .T. 
     oBrowse:VScrollObject:UseVisualStyle  := .T. 

     oBrowse:Show() 
     SetAppFocus( oBrowse ) 

     nEvent := xbeP_None 
     DO WHILE nEvent != xbeP_Close 
        nEvent := AppEvent( @mp1, @mp2, @oXbp ) 
        oXbp:HandleEvent( nEvent, mp1, mp2 ) 
     ENDDO 

     oBrowse:Destroy() 

  RETURN 

  ****************************************************************** 
  * Skipper function that moves the record pointer through the 
  * data source (array) 
  ****************************************************************** 
  FUNCTION DoSkip( nSkip ) 

   LOCAL nCanSkip 

     IF nRecno + nSkip < 1             // "BoF" 
        nCanSkip := 1 - nRecno 
     ELSEIF nRecno + nSkip > nLastRec  // "EoF" 
        nCanSkip := nLastRec - nRecno 
     ELSE 
        nCanSkip := nSkip 
     ENDIF 

     nRecno += nCanSkip 

  RETURN nCanSkip 
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.