BROWSE widget

A browse widget lets you see data and select records from all the records associated with a database query. You can define a static browse widget with the DEFINE BROWSE statement or a dynamic browse widget with the CREATE BROWSE statement. A browse can be either a read-only tool for browsing through records, or it can be an editing tool for updating records, depending on the options you specify.

You can move and resize the browse and its components. Specifically, in graphical interfaces, you can move and resize the browse, move and change the width of the browse-column, and change the height of the browse-row. You can do all this through direct manipulation (by pointing, clicking, and dragging) and through ABL.

You can also use the mouse wheel to scroll the browse widget horizontally and vertically in Windows. When you rotate the mouse wheel up and down, the browse scrolls vertically up and down. When you rotate the mouse wheel up and down while holding down the CTRL key, the browse scrolls horizontally left and right. You can specify the number of rows the browse scrolls up and down per click of the mouse wheel on the Wheel tab in the Windows Mouse Properties dialog box (accessed through the Windows Control Panel).

The following figure shows a read-only browse widget with colors applied to some of the rows using the BGCOLOR attribute. Note that the fifth row is selected:



The following figure shows an updatable browse. Note the inline editing capability in the focused row:



Accessing browse attributes and methods

When accessing browse attributes and methods, it is important to understand the scope of each attribute and method. An attribute or method can apply to:

Syntax

When accessing attributes and methods that apply to a browse widget as a whole, you must reference the browse widget using its name or handle, as shown in the following syntax examples:

/* For a static browse */
browse-name:attribute-or-method-name IN FRAME frame-name 

/* For a dynamic or static browse */
browse-handle:attribute-or-method-name

The IN FRAME qualifier is only necessary for a static browse to avoid ambiguity.

When accessing attributes and methods that apply to a browse column or cell, you must reference the browse column or cell using the browse column's name or handle, as shown in the following syntax examples:

/* For a static browse column */
column-name:attribute-or-method-name IN BROWSE browse-name 

/* For a dynamic or static browse column */
column-handle:attribute-or-method-name

The IN BROWSE qualifier is only necessary for a static browse to avoid ambiguity, but it is good programming practice to always include it, especially when you reference the same field as a separate widget type.

To access attributes and methods for a specific browse cell, you must be sure that a row is selected. You typically access browse cell attributes and methods in a ROW-DISPLAY trigger.

For more information about accessing widget attributes and methods, see the Handle Attributes and Methods Reference.

Attributes

The following table lists all the attributes for the browse widget and their scope:

Attribute Applies to
ALLOW-COLUMN-SEARCHING attribute Browse
AUTO-COMPLETION attribute1 Column
AUTO-RESIZE attribute Column
AUTO-RETURN attribute Column
AUTO-VALIDATE attribute Browse
AUTO-ZAP attribute 2 Cell
BGCOLOR attribute Browse, Column, Cell
BUFFER-FIELD attribute Column
COLUMN attribute Browse, Column
COLUMN-BGCOLOR attribute Column
COLUMN-DCOLOR attribute Column
COLUMN-FGCOLOR attribute Column
COLUMN-FONT attribute Column
COLUMN-MOVABLE attribute Browse
COLUMN-PFCOLOR attribute Column
COLUMN-READ-ONLY attribute Column
COLUMN-RESIZABLE attribute Browse
COLUMN-SCROLLING attribute Browse
CONTEXT-HELP-ID attribute Browse
CURRENT-COLUMN attribute Browse
CURRENT-ROW-MODIFIED attribute Browse
CURSOR-OFFSET attribute2 Cell
DATA-TYPE attribute Column
DBNAME attribute Column
DCOLOR attribute Browse, Column, Cell
DELIMITER attribute1 Column
DISABLE-AUTO-ZAP attribute Column
DOWN attribute Browse
DROP-TARGET attribute Browse
DYNAMIC attribute Browse
EDIT-CAN-PASTE attribute2 Cell
EDIT-CAN-UNDO attribute2 Cell
EXPANDABLE attribute Browse
FGCOLOR attribute Browse, Column, Cell
FIRST-COLUMN attribute Browse
FIT-LAST-COLUMN attribute Browse
FOCUSED-ROW attribute Browse
FOCUSED-ROW-SELECTED attribute Browse
FONT attribute2 Browse, Column, Cell
FORMAT attribute2 Cell
FRAME attribute Browse
FRAME-COL attribute Browse
FRAME-NAME attribute Browse
FRAME-ROW attribute Browse
FRAME-X attribute Browse
FRAME-Y attribute Browse
HANDLE attribute Browse, Column, Cell
HEIGHT-CHARS attribute Browse, Cell
HEIGHT-PIXELS attribute Browse, Cell
HELP attribute Browse, Column
HIDDEN attribute Browse
HWND attribute Browse, Cell
INDEX attribute Column, Cell
INNER-LINES attribute1 Column
INPUT-VALUE attribute Cell
INSTANTIATING-PROCEDURE attribute Browse, Column
LABEL attribute Column
LABELS attribute Browse
LABEL-BGCOLOR attribute Browse, Column
LABEL-DCOLOR attribute Browse, Column
LABEL-FGCOLOR attribute Browse, Column
LABEL-FONT attribute Browse, Column
LIST-ITEM-PAIRS attribute1 Column
LIST-ITEMS attribute1 Column
MANUAL-HIGHLIGHT attribute Browse
MAX-CHARS attribute1 Column
MAX-DATA-GUESS attribute Browse
MENU-KEY attribute Browse
MENU-MOUSE attribute Browse
MIN-COLUMN-WIDTH-CHARS attribute Browse
MIN-COLUMN-WIDTH-PIXELS attribute Browse
MIN-HEIGHT-CHARS attribute Browse
MODIFIED attribute Browse, Column
MOUSE-POINTER attribute Browse, Column
MOVABLE attribute Browse, Column
MULTIPLE attribute Browse
NAME attribute Browse, Column, Cell
NEW-ROW attribute Browse
NEXT-COLUMN attribute Column
NEXT-SIBLING attribute Browse
NEXT-TAB-ITEM attribute Browse
NO-EMPTY-SPACE attribute Browse
NO-VALIDATE attribute Browse
NUM-COLUMNS attribute Browse
NUM-DROPPED-FILES attribute Browse
NUM-ITEMS attribute1 Column
NUM-ITERATIONS attribute (widget objects) Browse
NUM-LOCKED-COLUMNS attribute Browse
NUM-SELECTED-ROWS attribute Browse
NUM-VISIBLE-COLUMNS attribute Browse
PARENT attribute Browse, Column
PFCOLOR attribute Browse, Column, Cell
POPUP-MENU attribute Browse
PREV-COLUMN attribute Column
PREV-SIBLING attribute Browse
PREV-TAB-ITEM attribute Browse
PRIVATE-DATA attribute Browse, column
QUERY attribute Browse
READ-ONLY attribute Browse, column
REFRESHABLE attribute Browse
RESIZABLE attribute Browse, column
ROW attribute Browse, cell
ROW-HEIGHT-CHARS attribute Browse
ROW-HEIGHT-PIXELS attribute Browse
ROW-MARKERS attribute Browse
ROW-RESIZABLE attribute Browse
SCREEN-VALUE attribute Cell
SCROLLBAR-VERTICAL attribute Browse
SELECTABLE attribute Browse
SELECTED attribute Browse
SELECTION-END attribute Column
SELECTION-START attribute Column
SELECTION-TEXT attribute Column
SENSITIVE attribute Browse
SEPARATORS attribute Browse
SEPARATOR-FGCOLOR attribute Browse
SORT attribute1 Column
SORT-ASCENDING attribute Column
SORT-NUMBER attribute Column
SUBTYPE attribute1 Column
TAB-POSITION attribute Browse
TAB-STOP attribute Browse
TABLE attribute Browse, Column
TEXT-SELECTED attribute Column
TITLE attribute Browse
TITLE-BGCOLOR attribute Browse
TITLE-DCOLOR attribute Browse
TITLE-FGCOLOR attribute Browse
TITLE-FONT attribute Browse
TOOLTIP attribute Browse
TYPE attribute Browse, Column, Cell
UNIQUE-MATCH attribute1 Column
VIEW-FIRST-COLUMN-ON-REOPEN attribute Browse
VISIBLE attribute Browse, Column
WIDGET-ID attribute Browse
WIDTH-CHARS attribute Browse, Column, Cell
WIDTH-PIXELS attribute Browse, Column, Cell
WINDOW attribute Browse
X attribute Browse, Column
Y attribute Browse, Cell

Methods

The following table lists all the methods for the browse widget and their scope:

Method Applies to
ADD-CALC-COLUMN( ) method Browse
ADD-COLUMNS-FROM( ) method Browse
ADD-FIRST( ) method3 Column
ADD-LAST( ) method3 Column
ADD-LIKE-COLUMN( ) method Browse
CLEAR-SELECTION( ) method4 Column
CLEAR-SORT-ARROWS( ) method Browse
CREATE-RESULT-LIST-ENTRY( ) method Browse
DELETE( ) method3 Column
DELETE-CURRENT-ROW( ) method Browse
DELETE-RESULT-LIST-ENTRY( ) method Browse
DELETE-SELECTED-ROW( ) method Browse
DELETE-SELECTED-ROWS( ) method Browse
DESELECT-FOCUSED-ROW( ) method Browse
DESELECT-ROWS( ) method Browse
DESELECT-SELECTED-ROW( ) method Browse
EDIT-CLEAR( ) method4 Cell
EDIT-COPY( ) method4 Cell
EDIT-CUT( ) method4 Cell
EDIT-PASTE( ) method4 Cell
EDIT-UNDO( ) method4 Cell
END-FILE-DROP( ) method Browse
ENTRY( ) method3 Column
FETCH-SELECTED-ROW( ) method Browse
GET-BROWSE-COLUMN( ) method Browse
GET-DROPPED-FILE( ) method Browse
GET-REPOSITIONED-ROW( ) method Browse
INSERT( ) method3 Column
INSERT-ROW( ) method Browse
IS-ROW-SELECTED( ) method Browse
LOAD-MOUSE-POINTER( ) method Browse, Column
LOOKUP( ) method3 Column
MOVE-AFTER-TAB-ITEM( ) method Browse
MOVE-BEFORE-TAB-ITEM( ) method Browse
MOVE-COLUMN( ) method Browse
MOVE-TO-BOTTOM( ) method Browse
MOVE-TO-TOP( ) method Browse
REFRESH( ) method (Handle) Browse
REPLACE( ) method3 Column
SCROLL-TO-CURRENT-ROW( ) method Browse
SCROLL-TO-SELECTED-ROW( ) method Browse
SELECT-ALL( ) method Browse
SELECT-FOCUSED-ROW( ) method Browse
SELECT-NEXT-ROW( ) method Browse
SELECT-PREV-ROW( ) method Browse
SELECT-ROW( ) method Browse
SET-REPOSITIONED-ROW( ) method Browse
SET-SELECTION( ) method4 Column
SET-SORT-ARROW( ) method Browse
VALIDATE( ) method Browse, Column

Events

The following table lists all the events for the browse widget and their scope:

Event Applies to
Default keyboard events Browse, Cell
Developer events Browse, Column, Cell
Field editing key function events Cell
General direct manipulation events Browse, Column
Mouse events Browse, Column, Cell
Navigation key function events Browse, Cell
Universal key function events Browse, Column, Cell
DEFAULT-ACTION Browse
DROP-FILE-NOTIFY Browse
END Browse
END-SEARCH Browse
ENTRY Browse, Cell
HOME Browse
LEAVE Browse, Cell
OFF-END Browse
OFF-HOME Browse
ROW-DISPLAY Browse
ROW-ENTRY Browse
ROW-LEAVE Browse
SCROLL-NOTIFY Browse
START-SEARCH Browse
VALUE-CHANGED Browse

See also

DEFINE BROWSE statement, CREATE BROWSE statement