Class ::tycho::ListBrowser


Inherits: ::tycho::Query - Source File - Contents: itk_options - public methods - protected methods
Create a list browser window that consists of a scrolled list box. If the -command option is specified, then the value of the option is taken as a command to execute when the user has selected an item from the list. Before executing the command, the item selected by the user is appended to the command as an argument. If no -command option is specified, then the default behavior is to return the selected item when the ListBrowser is waited for using ::tycho::Dialog::wait procedure.

When the user has selected an item, the processItem protected method is consulted. If this method return 1, then the list browser is destroyed. However, this method could change the contents of the list browser and return 0, in which case the user can make another selection.

For example, the following command will query the user to select an item from a list, and then post that item in top-level window:

::tycho::ListBrowser .w -command ::tycho::post -items {a b c d}
.w centerOnScreen

The list browser performs automatic completion of partial entries and pattern matching on entries. See the help page for details. It is not case sensitive in its matching.


Itk_options

-command ::tycho::Dialog::answer
Specify the command to execute on an item when one is chosen.
-default
Specify the default entry.
-items
Specify items in the listbox.

Public constructs

Public Methods

breakCompleteSequence
Break the interpretation of a sequence of Tabs to scroll over matches. This is bound to every key other than Tab.
chooseItem lb ypos
Determine the item name in the listbox given by the first argument that is closest to the mouse position in the vertical direction given by the second argument and insert its name in the entry box.
clearselection
Clear any selections made by item completion.
complete {case 0}
Complete a partially entered item. On the first invocation, this method finds an entry in the listbox that has the contents of the entry box as a prefix. Glob-style rules are used, so the entry can be a pattern (* for any substring, ? for any single character, [chars] for a set of characters, or \x for a single character. If there is more than one matching entry, then all matching entries are selected in the listbox. The selected entries can then be scrolled with the up and down arrow keys. If the method is invoked again without an intervening invocation of breakCompleteSequence, then it scrolls through the selected entries as if the down arrow had been pressed. If the optional argument is given and has a non-zero value, then the match is case sensitive. Otherwise, it is not case sensitive. Return 0 if no matching entry is found, 1 if one matching entry is found, and 2 if more than one matching entry is found.
goto item
Goto the specified item in the listbox. The item identifier can be an integer (starting with 0), the word "end", or any of the index forms understood by the Tk listbox widget.
help
Open a help window.
ok
Select the item specified in the entry box.
scroll num what
Move up or down a number of pages or units in the listbox or selection. The first argument is an integer (negative means to move up). If the second argument is "pages", then scrolling is by screenfulls. If it is "units", then scrolling is by individual items. If it is "selection", then we move up or down by individual items within the selected items, if any items are selected. If there are no items selected, then we move up and down as if the value of second argument were "units".
select name
Invoke processItem on the item specified in the argument, then self-destruct.

Protected constructs

Protected Methods

processItem item
This procedure checks and processes the user selection. If it return 1, then the ListBrowser is destroyed. If it returns 0, then it is not destroyed. Note that if processItem aborts with an error, then the list browser is disabled. Thus, unless the error is fatal, processItem should just issue a message and return 0.
setEntry string
This method clears the current contents of the entry box and replaces them with the string passed as an argument. Derived classes may redefine this to take further action as well.
updateListbox
This procedure fills the listbox with items. By default, it just uses the -items option.

Index of classes



Author: Edward A. Lee
Version: @(#)ListBrowser.itcl 1.22 11/16/96
Copyright: (c) 1995-1996 The Regents of the University of California.