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:

The following figure shows an updateable 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:

The browse widget as a whole.

A single browse column. In this case, any attribute or method that applies to a browse column, applies to:

All cells in the browse column (that is, all cells of the given column for all rows of the browse)

Any type of browse column (fill-in, combo-box, or toggle-box), except where noted

A single browse cell. In this case, the attribute or method applies to only the given cell at the intersection of the referenced column and the focused row.

Both the browse as a whole and a column or cell. For example, in the same trigger, you could change the background color of the whole browse to blue and the background color of the current cell to yellow.

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:

 

Syntax 

/* 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:

 

Syntax 

/* 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” section.

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 attribute2	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

---

1

This attribute applies only to combo-box browse columns.

2

This attribute applies only to fill-in and combo-box browse columns.

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( ) method1	Column
ADD-LAST( ) method1	Column
ADD-LIKE-COLUMN( ) method	Browse
CLEAR-SELECTION( ) method2	Column
CLEAR-SORT-ARROWS( ) method	Browse
CREATE-RESULT-LIST-ENTRY( ) method	Browse
DELETE( ) method1	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( ) method2	Cell
EDIT-COPY( ) method2	Cell
EDIT-CUT( ) method2	Cell
EDIT-PASTE( ) method2	Cell
EDIT-UNDO( ) method2	Cell
END-FILE-DROP( ) method	Browse
ENTRY( ) method1	Column
FETCH-SELECTED-ROW( ) method	Browse
GET-BROWSE-COLUMN( ) method	Browse
GET-DROPPED-FILE( ) method	Browse
GET-REPOSITIONED-ROW( ) method	Browse
INSERT( ) method1	Column
INSERT-ROW( ) method	Browse
IS-ROW-SELECTED( ) method	Browse
LOAD-MOUSE-POINTER( ) method	Browse, Column
LOOKUP( ) method1	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	Browse
REPLACE( ) method1	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( ) method2	Column
SET-SORT-ARROW( ) method	Browse
VALIDATE( ) method	Browse, Column

---

1

This method applies only to combo-box browse columns.

2

This method applies only to fill-in and combo-box browse columns.

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-SEARCH1	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-SEARCH1	Browse
VALUE-CHANGED	Browse

See also 

DEFINE BROWSE statement, CREATE BROWSE statement