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_messageActivated on left-click list_browser <->select_middle_messageActivated on middle-click list_browser <->open_messageActivated 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.
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)).
up outside browser. Forwarding:
@receiver: The list_browser object.
list_browser. New functions may
be added using:
... send(LB?key_binding, function, Name, Action) ...
These functions are local to this 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.->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
->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.
@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)
|member:dict_item*<->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.
<->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.
<-dict
that is not empty. Note that typing in a list_browser searches for an
item.->typed).
Incremental search is normally canceled when the pointer leaves the
window and when the user hits ESC or Control-G.|chain]->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.
->clear
to the
list_browser<-dict.->compute’s
the list_browser<-image
and list_browser<-scroll_bar. Initialises list_browser<-start_cell
to speed up redraw.<-key_binding
when the user hits return to confirm searching for an item.
->event
and succeed if this succeeds.
->typed
to realise incremental search.
<-popup,
open the popup using @_popup_gesture.
<-selection
using list_browser->change_selection
and, If appropriate, execute one of the messages
list_browser <-open_messagedouble-click list_browser <-select_messageleft-click list_browser <-select_middle_messagemiddle-click
<-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.->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.<-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.<-image
and list_browser<-scroll_bar.<-height.size
is used. The size is interpreted in character units.<-label->advance).
See also
text_item->next.->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.
See also list_browser->scroll_to.
Defaults: By default scrolls to the last item.
<-member is
selected.<-show_label-size
<->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).
->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).
|event_id<-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.
<-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.
<-width
<-members
chain of the list_browser<-dict.<-width
and list_browser<->size.<-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.
<-length, list_browser<-start
and list_browser<-view
are used by the list_browser<-scroll_bar
and describe the following properties:
list_browser <-lengthNumber of items in the browser list_browser <-startFirst item on the window list_browser <-viewNumber of items on the window
<-window
is this is an instance of class browser.
See
visual<-master
for details.|dict_itemselection. Defined as a
method to overrule the corresponding method defined on class device.
<-label_text
and list_browser<->label.<-font’s font<-ex
units.