1.94 class list_browser

A list_browser object is a visualisation of a dict object. It appears as a scrollable list of (textual) items. The user may examine this list by scrolling and searching. S/he may select one or multiple items from the list (see list_browser<-multiple_selection).

List Browsers are commonly used for browsing or selection from a (possibly) large list of (named) objects. For example the manual's card viewer uses a browser to show existing see-also relation. The class-browser and various of the other manual tools use them to visualise sets of documentation cards.

List browsers are normally used through class browser which defines a window displaying a list_browser (like class view displays an editor object).

Various messages may be associated with list_browser objects:

list_browser<->select_message	Activated on left-click
list_browser<->select_middle_message	Activated on middle-click
list_browser<->open_message	Activated on double-click

The list_browser<->open_message is also activated when an item is selected using the keyboard.

All these messages forward the following arguments:

@receiver	The browser or list_browser object
@arg1	The dict_item object selected.

It is possible to associate a popup with a list_browser. See list_browser->popup. Finally, it is possible to program the event-handling yourself. The method list_browser<-dict_item may be used to translate events to dict_item objects.

1.94.1 Fonts and images

XPCE browsers support multiple fonts and images indicating the type of the item. Each item can only be displayed in one font. Font and icon specification use the style object based mechanism to specify the appearance of a dict_item object of specified style. For example, to make a browser for files and directories, where the directories are printed purple and using the dir.bm icon, use the following code as a starting point:

...
new(B, browser),
send(B, style, directory,
         style(icon := 'dir.bm', colour := purple)),
send(B, style, file,
         style(icon := 'file.bm')),
...

append_directory(B, Name) :-
        send(B, append,
                 dict_item(Name, style := directory)).

See also

- class key_binding
- class browser
- class dict

1.94.2 Class variables

list_browser.search_ignore_case: bool =

@on

1.94.3 Instance variables

list_browser <-> cancel_message: code*

Send on drag-select with up outside browser. Forwarding:

@receiver:	The list_browser object.

list_browser <- dict: dict*

Associated dict object (table of items).

list_browser <- image: text_image

Text_image object used for visualisation of the items. Class text_image is also used by class editor. There are many similarities in the architecture of class editor and class list_browser.

list_browser <-> key_binding: key_binding

A key_binding object that maps typing in the list_browser object to actions. The initial value is an empty table that delegates to the predifined table named list_browser. New functions may be added using:

...
send(LB?key_binding, function, Name, Action)
...

These functions are local to this list_browser.

list_browser <- label_text: text*

Text object used to display the list_browser<->label. When @nil, no label is displayed (default). The list_browser<-label_text may be accessed directly, but be aware that the layout of the list_browser (i.e. placement and sizes of the list_browser<-scroll_bar, list_browser<-image and list_browser<-label_text) will not be updated automatically.

list_browser <- multiple_selection: bool

When @on, any number of items may be in the selected state. When @off (default), only zero or one item may be selected. This flag has consequences for the way events are processed and the selection is communicated.

See also

list_browser-selection

list_browser <-> open_message: code*

This message is send when the user double-clicks an item or selected an item using the keyboard (see also list_browser->enter). During the execution of this message the graphical<-cursor is switched to the wait cursor. The following arguments are forwarded:

@receiver	The browser or list_browser
@arg1	The dict_item object selected

See also list_browser<->select_message

list_browser <-> popup: popup*

There are two ways to associate a popup with a browser. One is to use list_browser->popup. In this case the popup will only be displayed if the right-down event is detected on an item and @arg1 will be bound to the dict_item object on which the right-down was trapped.

Alternatively, one may attach a popup_gesture using‘Object graphical->recogniser’. In this case the popup will behave as if it were attached to any graphical object.

See also

class popup

list_browser <-> select_message: code*

If not @nil, this message is sent when the user clicks on an item with the left mouse-button. The following arguments are forwarded:

@receiver:	The (list_)browser
@arg1:	The current list_browser<-selection

See also list_browser<->open_message and list_browser->change_selection.

Defaults: @nil (no message is sent)

See also

list_browser-select_middle_message

list_browser-selection: chain|member:dict_item*

The current selection of the list_browser. If list_browser<->multiple_selection equals @on, this is an (empty) chain of dict_items. If list_browser<->multiple_selection equals @off, this is either @nil or a dict_item.

See also

- list_browser-multiple_selection
- list_browser<-selection

list_browser <- size: characters=size

Set the size of the list browser. The list_browser<->width and list_browser<->height attributes of the size are interpreted in characters of the current font.

To resize in pixel units, please see ListBrowser->_size and ListBrowser->set.

list_browser <- start: int

0-based index number of the first visible dict_item object.

list_browser <- styles: sheet

Sheet object mapping logical style-names onto style objects.

1.94.4 Send methods

list_browser ->_size: pixels=size

Resizes the list_browser to the indicated pixel size. Normally list_browser sizes are communicated in character units. This method is used internally to handle resize requests of the browser window.

See also

graphical->size

list_browser ->_wants_keyboard_focus:

Succeeds if the list_browser has a list_browser<-dict that is not empty. Note that typing in a list_browser searches for an item.

list_browser ->cancel_search:

Cancel the incremental search (see list_browser->typed). Incremental search is normally canceled when the pointer leaves the window and when the user hits ESC or Control-G.

list_browser ->change_selection: action={set,toggle,extend,clear,cancel}, context=[dict_item|chain]

Hook in selection management. This method is invoked from list_browser->event and may be used to keep track of selection changes in the list_browser object. If action is set, the selection will be cleared and then set to the argument dict_item object. Action toggle will toggle the status of the argument dict_item, while clear will empty the selection.

Redefinition of this method may be used to keep track of the selection. See also list_browser->select_message and list_browser->open_message.

list_browser ->clear:

Removes all items from the browser. Invokes dict->clear to the list_browser<-dict.

list_browser ->compute:

list_browser->compute’s the list_browser<-image and list_browser<-scroll_bar. Initialises list_browser<-start_cell to speed up redraw.

list_browser ->enter:

Select current item as double-click. This method is normally invoked through the list_browser<-key_binding when the user hits return to confirm searching for an item.

list_browser ->event: event

Performs the following steps:

1. Invoke device->event and succeed if this succeeds.
2. If the event is a keyboard event, invoke list_browser->typed to realise incremental search.
3. If the event is an area_exit event, cancel an ongoing search.
4. If the event is a right-button-down (ms_right_down) and there is a list_browser<-popup, open the popup using @_popup_gesture.
5. If the event is a left-or middle-click, modify the list_browser<-selection using list_browser->change_selection and, If appropriate, execute one of the messages

   list_browser<-open_message	double-click
   list_browser<-select_message	left-click
   list_browser<-select_middle_message	middle-click

list_browser ->extend_prefix:

Part of incremental search. Determines all items who's‘dict_item list_browser<-label’start with the list_browser<-current_search and extends the search string to the common prefix of the matching items. In other words, it will extend the search string to the next choice-point.

list_browser ->extend_prefix_or_next:

If the list_browser is searching (see list_browser->insert_self), this method extends the current -search_string to the next choice-point (see list_browser->extend_prefix). Otherwise list_browser->next is invoked to advance to the next item requesting the keyboard in the same device.

list_browser ->extend_to_current:

Extends the list_browser<-search_string to the current item. Useful when the user is searching for an item that starts as the current. See also list_browser->extend_prefix.

list_browser ->geometry: x=[int], y=[int], width=[int], height=[int]

Resize the list_browser<-image and list_browser<-scroll_bar.

graphical ->height: int

Inherits description from: list_browser<-height

list_browser ->initialise: dict=[dict], width=[int], height=[int]

Create a list_browser for the specified dict object with specified width and height. If no dict is specified a default dict is created. If no size is specified list_browser.size is used. The size is interpreted in character units.

list_browser ->insert_self: times=[int], character=[char]

Start/Continue incremental search.

list_browser ->label: name

Inherits description from: list_browser<-label

list_browser ->next:

Move caret to next item (device->advance). See also text_item->next.

list_browser ->previous_line: [int]

Set selection to previous item.

list_browser ->next_line: [int]

Move forward by arg lines. If an incremental search is in progress, moves it moves the current search to the next line. If the current search pattern does not match the new item, it is set to the entire next item. If there is no search in progress, the browsercan only select a single object (list_browser->multiple_selection: @off) and the selection is in the visible part of the browser, the selected object is taken as the start of the search. Otherwise, the top of the visible page is choosen.

list_browser->previous_line simply negates the argument before calling list_browser->next_line.

list_browser ->normalise: member:dict_item

Scroll window such that the indicated dict_item is visible. If this requires the window to be scrolled one line up or down the indicated item will be the first or last in the window. Otherwise the item will be centered in the window,

See also list_browser->scroll_to.

See also

list_browser->scroll_to

list_browser ->scroll_to: [int]

Make nth-1 item first of window

Defaults: By default scrolls to the last item.

See also

list_browser->normalise

list_browser ->selected: member:dict_item

Test whether the indicated dict_item object or list_browser<-member is selected.

list_browser ->show_label: show=bool

Inherits description from: list_browser<-show_label

graphical ->size: size

Inherits description from: list_browser-size

See also

list_browser->_size

list_browser ->style: style_name=name, style=style

Display any item with dict_item<->style = name using the attributes from the given style object.

Suppose one has a list_browser that visualises a lexicon and we want the present all items that also appear in a glossary on the same domain in bold-face. This may be achieved using:

show_lexicon :-
        new(B, browser('Lexicon')),
        send(B, style, glossary, style(bold := @on)),
        (   lexicon(Item),
                send(B, append, new(D, dict_item(Item))),
                (   glossary(Item)
                ->  send(D, style, glossary)
                ;   true
                ),
                fail
        ;   true
        ),
        send(B, open).

list_browser ->tab_stops: vector*

Set a number of tabulator stops. The argument is a vector with pixel locations of the tab stops. See also text_image->tab_stops.

This feature may be used for multi-column tables and is especially useful when the items in the browser are displayed in a proportional font. The following example displays a database of persons where each person has a unique id and a name. The database is in the predicate person/2.

?- new(B, browser('Persons')),
   send(B, tab_stops, vector(200)),
   forall(person(Id, Name),
                  send(B, append,
                           dict_item(Id, string('%s\t%s',
                                                                        Id, Name)))),
   send(B, open).

list_browser ->typed: event|event_id

Activates the key_binding object list_browser<-key_binding. list_browser<-key_binding is filled in list_browser->initialise with an empty sub-keybinding of the default key_binding named list_browser from @key_bindings.

The default key_binding object implements incremental search. See also class key_binding and class editor.

list_browser ->unlink:

Unlinks the list_browser<-dict from the list_browser object and then invokes device->unlink.

Bugs: Implicitely created dict objects generally will not be garbage collected as a dict has internal references.

graphical ->width: int

Inherits description from: list_browser<-width

1.94.5 Get methods

list_browser <-contains: -> chain

Return the dict<-members chain of the list_browser<-dict.

list_browser <-dict_item: event -> dict_item

dict_item object on which event occurred. This message may be used to redefine the list_browser event handling.

list_browser <-height: -> characters=int

Set/Query the height in lines. See also list_browser<-width and list_browser<->size.

list_browser <-label: -> name

A list_browser may be assigned a label. When a label is assigned, a list_browser<-label_text will be displayed on the list_browser. See also list_browser<->show_label.

Note that class browser inherits list_browser->label from class window.

list_browser <-view: -> int

list_browser <-length: -> int

The triple list_browser<-length, list_browser<-start and list_browser<-view are used by the list_browser<-scroll_bar and describe the following properties:

list_browser<-length	Number of items in the browser
list_browser<-start	First item on the window
list_browser<-view	Number of items on the window

list_browser <-master: -> device

Return the graphical<-window is this is an instance of class browser. See visual<-master for details.

list_browser <-selection: -> chain|dict_item

Get the value of the variable selection. Defined as a method to overrule the corresponding method defined on class device.

See also

list_browser-selection

list_browser <-show_label: -> bool

If @on, the label is visible. See also list_browser<-label_text and list_browser<->label.

list_browser <-width: -> characters=int

Width of the list_browser in the list_browser<-font’s font<-ex units.