Command APPBROWSE Foundation

Creates an Application Part to browse databases

    [ INTO <oAppBrowse> ]
  [ FIELDS <cFieldNames,...> ] ;
  [ PARENT <oParent> ] ;
[ POSITION <pos1> [, <pos2>] ] ; 
    [ SIZE <size1> [, <size2>] [ PERCENT ] ] ; 
   [ TITLE <cTitle> ] ;
   [ COLOR <nForeGround1> [, <nBackGround1> ] ] ;
    [ FONT <cFontCompoundName> ] ;
  [ HILITE <nForeGround2> [, <nBackGround2> ] ] ;
   [ STYLE PLAIN | 3D | FANCY | <nStyle> ] ;
   [ ALIAS <cAlias> ] ;
     [ FOR <lForCondition> ] 
<oAppBrowse> is the name of the memory variable that gets the AppBrowse object assigned which is created by the APPBROWSE command. If the INTO clause is used it must appear as the first option of the APPBROWSE command. If it is not used the object is assigned to the variable appObject.
The option FIELDS specifies a comma-separated list of field names to be displayed in the AppBrowse window. The field names can be specified as literals or as character expressions in parentheses. If particular fonts or colors should be used for single fields the APPFIELD command must be used for field specification (see there). If neither the FIELDS option nor command APPFIELD is used, all fields of the current work area are displayed in the AppBrowse window.
The option PARENT defines the parent of the AppBrowse object. It is displayed in the parent window <oParent> at position POS and has the size SIZE. If the PARENT option is omitted the AppBrowse window is displayed in a separate dialog window and the return value of AppDesktop() is used as parent.
<pos1> [, <pos2>]
The option POSITION positions an AppBrowse window. If not specified the AppBrowse window is displayed at the point {0,0} (bottom left corner of the parent).
There are three possibilities to position an AppBrowse object. Depending on the data types used for <pos1> and/or <pos2> the AppBrowse window can be positioned absolute or relative in its parent window. In addidion, text oriented (row, column) or graphic coordinates (x,y) may be used:
Coordinates to position an AppBrowse window
<pos1> Value <pos2> Value Description
Array {nX,nY} n.a. NIL <pos1> is an array containing grafic coordinates for the AppBrowse window
Numeric nRow Numeric nCol <pos1> is a numeric value used as row coordinate, and <pos2> specifies the column coordinate according to a text mode window
Key word TOP Key word TOP The AppBrowse window is displayed
Key word LEFT Key word LEFT at the top, left, bottom, right
Key word BOTTOM Key word BOTTOM and/or centered within its parent,
Key word RIGHT Key word RIGHT according to the keywords used
Key word CENTER Key word CENTER for positioning
<size1> [, <size2>] [ PERCENT ]
The key word SIZE defines the size of an AppBrowse window. As with POSITION, the size can be specified using graphic or text oriented coordinates. Additionaly, percentage values may be used. The next table shows different possibilities:
Coordinates used for size definition of an AppBrowse window
<size1> Value <size2> Value Description
Array {nXsize,nYsize} n.a. NIL A two element array defines the size in pixel
Numeric nHeight Numeric nWidth Two numeric values specify the number of rows and columns according to a text mode window
If a numeric value is used for <size1> and/or <size2> in conjunction with the key word PERCENT, the values are interpreted as percentage of the parent window's height and/or width.
<cTitle> is a character expression which is displayed in the title bar of an AppBrowse window. It defaults to the alias name of the current work area.
<nForeGround1> [, <nBackGround1> ]
The COLOR option specifies foreground and background color for the AppBrowse window. #define constants from XBP.CH or GRA.CH must be used (XBPSYSCLR_* or GRA_CLR_*). If single columns in the browser are to have different colors, the APPFIELD command must be used (see there).
The FONT clause optionally specifies a character string defining the compound name of the font to be used for display (see also the :setFontCompoundName() method of Xbase Parts).
<nForeGround2> [, <nBackGround2> ]
The option HILITE specifies foreground and background color for the browse cursor in the AppBrowse window. #define constants from XBP.CH or GRA.CH must be used (XBPSYSCLR_* or GRA_CLR_*).
3D | PLAIN | FANCY | <nStyle>
The key word STYLE defines the style, or the appearance, of an AppBrowse window. Default styles are selected specifying either option 3D, PLAIN, or FANCY. Optionally, styles can be defined by adding constants listed in the next table, and using the result for <nStyle>:
Constants for style definition of an AppBrowse window
Constant Description
APPSTYLE_3D Is equal to STYLE 3D
APPSTYLE_NOBORDER The border of the dialog window is suppressed
APPSTYLE_NOTITLEBAR The title of the dialog window is suppressed
APPSTYLE_NOFRAMECONTROLS Control elements in the title bar are suppressed (maximize, minimize button and system menu)
The option ALIAS specifies the alias name for the work area to be used for database navigation by the AppBrowse object. It defaults to the current work area.
<lForCondition> is an optional logical expression defining a condition, or a code block with a logical return value. Only records for which <lForCondition> returns the value .T. (true) are displayed. This allows to display a subset of database records.

The command APPBROWSE defines an Application Part (APP) that displays databases. It creates an object of the AppBrowse class which is a container for a GUI browser. The minimum requirements to display a database are three lines of code:

USE Customer NEW 

These three lines open a database (USE), create an AppBrowse object (APPBROWSE), and display it (APPDISPLAY). In this case the browser displays all database fields. All other options of the APPBROWSE command are used to configure the browser in detail or to specify the fields to be displayed.

Options for display
Key word Description
PARENT Defines the parent
POSITION Positions the AppBrowse window within the parent
SIZE Defines the size of the AppBrowse window
TITLE Character string to be displayed in the title bar
COLOR Defines colors for table columns
FONT Defines font for table columns
HILITE Defines colors for browse cursor
STYLE Defines display style

The most important options for display are PARENT, STYLE, POS and SIZE.


The key word PARENT decides whether or not an AppBrowse object is displayed within its own dialog window. When the option PARENT is used, the browser is displayed without a dialog frame within the parent window. If PARENT is not specified, the AppBrowse window is created having its own dialog window. It is then displayed on the desktop window (AppDesktop()).


The option STYLE defines the appearance of an AppBrowse window. The default style is 3D. Three predefined styles can be selected for an AppBrowse window using key words: STYLE PLAIN, STYLE 3D and STYLE FANCY.


The option POS allows to position an AppBrowse window within its parent window using different units for coordinates. The units 'pixel', 'text coordinates' and the key words TOP, LEFT, BOTTOM, RIGHT, CENTER are supported. This provides maximum flexibility for positioning of an AppBrowse window. Different possibilities are shown below:

POS {100,200}        // Array     => x,y coordinates in pixel 
POS 10, 20           // Numeric   => Row and column coordinates 
POS TOP,CENTER       // Key words => Default positions 

A pixel-exact positioning is achieved with a two element array containing graphic x,y coordinates (the origin of the coordinate system is bottom, left). Numeric values are interpreted as row and column text-coordinates (the origin is top, left). Using key words an AppBrowse window can be placed at well defined positions. The key word LEFT means, for example, that the AppBrowse is displayed on the left side of its parent window. TOP, CENTER displays it at the top and centers it horizontally.


The option SIZE defines the size of the display area of the AppBrowse window (this is equal to the size of XbpDialog:drawingArea). A two element array defines the size in x and y direction (width and height), the unit is 'pixel'. Numeric values specify the number of rows and columns according to a text-mode window. If the key word PERCENT is specified, numeric values are used as percentage to calculate width and height from the size of the parent window (range 0-100).

Options for database access

The next table list all options relevant for database access:

Key word Description
FIELDS Names of fields to be displayed
ALIAS Alias name of the work area used for navigation
FOR Condition for database records to display

If database navigation is not to take place in the current work area, the alias name of the corresponding work area must be specified with the ALIAS option. The option FIELD specifies the fields to be displayed in the AppBrowse window. Field names must be programmed as literals or as character expressions in parentheses. If fields from multiple work areas are to be displayed, the field names must be alias referenced. Table columns in the browser are displayed in the same order like the fields are specified. Instead of using the FIELDS option, fields can be specified using the APPFIELD command prior to displaying the browser with APPDISPLAY. If neither FIELDS nor APPFIELD is used the browser contains columns for all fields of the specified work area.

The FOR option defines a logical condition. If it is used, only those records are displayed where the condition yields the value .T. (true).

Programming a GUI browser using command syntax

// The example demonstrates the sequence of commands necessary 
// to create and display a GUI browser. The browser is displayed 
// modal. Therefore, an event loop is not necessary. 

#include "" 

MEMVAR appObject 

// Desktop remains application window 


   USE Customer                     // Open database 

   APPBROWSE ;                      // Define browser 
      FIELDS Firstname, Lastname, Phone, Street, Zip, City ; 
       TITLE "Address List" ; 
        SIZE  40, 60 PERCENT 

   APPDISPLAY                       // Display browser modal 


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.