summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Tk/Listbox.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/Listbox.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Listbox.pod794
1 files changed, 794 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/Listbox.pod b/Master/tlpkg/tlperl/lib/Tk/Listbox.pod
new file mode 100644
index 00000000000..ba00afe3ed9
--- /dev/null
+++ b/Master/tlpkg/tlperl/lib/Tk/Listbox.pod
@@ -0,0 +1,794 @@
+# Copyright (c) 1990 The Regents of the University of California.
+# Copyright (c) 1994-1997 Sun Microsystems, Inc.
+# See the file "license.terms" for information on usage and redistribution
+# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+#
+#
+
+=head1 NAME
+
+Tk::Listbox - Create and manipulate Listbox widgets
+
+=for category Tk Widget Classes
+
+=head1 SYNOPSIS
+
+I<$listbox> = I<$parent>-E<gt>B<Listbox>(?I<options>?);
+
+=head1 STANDARD OPTIONS
+
+B<-background> B<-borderwidth> B<-cursor> B<-disabledforeground>
+B<-exportselection> B<-font> B<-foreground> B<-height>
+B<-highlightbackground> B<-highlightcolor> B<-highlightthickness>
+B<-offset> B<-relief> B<-selectbackground> B<-selectborderwidth>
+B<-selectforeground> B<-setgrid> B<-state> B<-takefocus> B<-tile>
+B<-width> B<-xscrollcommand> B<-yscrollcommand>
+
+
+See L<Tk::options> for details of the standard options.
+
+=head1 WIDGET-SPECIFIC OPTIONS
+
+=over 4
+
+=item Name: B<activeStyle>
+
+=item Class: B<ActiveStyle>
+
+=item Switch: B<-activestyle>
+
+Specifies the style in which to draw the active element. This must be
+one of B<dotbox> (show a focus ring around the active element), B<none>
+(no special indication of active element) or B<underline> (underline the
+active element). The default is B<underline>.
+
+=item Name: B<height>
+
+=item Class: B<Height>
+
+=item Switch: B<-height>
+
+Specifies the desired height for the window, in lines.
+If zero or less, then the desired height for the window is made just
+large enough to hold all the elements in the listbox.
+
+=item Name: B<listVariable>
+
+=item Class: B<Variable>
+
+=item Switch: B<-listvariable>
+
+I<The following is only partially implemented in Perl/Tk:>
+
+Specifies the reference of a variable. The value of the variable is an array
+to be displayed inside the widget; if the variable value changes
+then the widget will automatically update itself to reflect the new
+value. Attempts to assign a variable with an invalid list value to
+B<-listvariable> will cause an error. Attempts to unset a variable in use
+as a B<-listvariable> will fail but will not generate an error.
+
+=item Name: B<selectMode>
+
+=item Class: B<SelectMode>
+
+=item Switch: B<-selectmode>
+
+Specifies one of several styles for manipulating the selection.
+The value of the option may be arbitrary, but the default bindings
+expect it to be either B<single>, B<browse>, B<multiple>,
+or B<extended>; the default value is B<browse>.
+
+=item Name: B<state>
+
+=item Class: B<State>
+
+=item Switch: B<-state>
+
+Specifies one of two states for the listbox: B<normal> or B<disabled>.
+If the listbox is disabled then items may not be inserted or deleted,
+items are drawn in the B<-disabledforeground> color, and selection
+cannot be modified and is not shown (though selection information is
+retained).
+
+=item Name: B<width>
+
+=item Class: B<Width>
+
+=item Switch: B<-width>
+
+Specifies the desired width for the window in characters.
+If the font doesn't have a uniform width then the width of the
+character ``0'' is used in translating from character units to
+screen units.
+If zero or less, then the desired width for the window is made just
+large enough to hold all the elements in the listbox.
+
+=back
+
+=head1 DESCRIPTION
+
+The B<Listbox> method creates a new window (given by the
+$widget argument) and makes it into a listbox widget.
+Additional
+options, described above, may be specified on the command line
+or in the option database
+to configure aspects of the listbox such as its colors, font,
+text, and relief. The B<listbox> command returns its
+$widget argument. At the time this command is invoked,
+there must not exist a window named $widget, but
+$widget's parent must exist.
+
+A listbox is a widget that displays a list of strings, one per line.
+When first created, a new listbox has no elements.
+Elements may be added or deleted using methods described
+below. In addition, one or more elements may be selected as described
+below.
+If a listbox is exporting its selection (see B<exportSelection>
+option), then it will observe the standard X11 protocols
+for handling the selection.
+Listbox selections are available as type B<STRING>;
+the value of the selection will be the text of the selected elements, with
+newlines separating the elements.
+
+It is not necessary for all the elements to be
+displayed in the listbox window at once; commands described below
+may be used to change the view in the window. Listboxes allow
+scrolling in both directions using the standard B<xScrollCommand>
+and B<yScrollCommand> options.
+They also support scanning, as described below.
+
+=head1 INDICES
+
+Many of the methods for listboxes take one or more indices
+as arguments.
+An index specifies a particular element of the listbox, in any of
+the following ways:
+
+=over 4
+
+=item I<number>
+
+Specifies the element as a numerical index, where 0 corresponds
+to the first element in the listbox.
+
+=item B<active>
+
+Indicates the element that has the location cursor. This element
+will be displayed with an underline when the listbox has the
+keyboard focus, and it is specified with the B<activate>
+method.
+
+=item B<anchor>
+
+Indicates the anchor point for the selection, which is set with the
+B<selection anchor> method.
+
+=item B<end>
+
+Indicates the end of the listbox.
+For most commands this refers to the last element in the listbox,
+but for a few commands such as B<index> and B<insert>
+it refers to the element just after the last one.
+
+=item B<@>I<x>B<,>I<y>
+
+Indicates the element that covers the point in the listbox window
+specified by I<x> and I<y> (in pixel coordinates). If no
+element covers that point, then the closest element to that
+point is used.
+
+=back
+
+In the method descriptions below, arguments named I<index>,
+I<first>, and I<last> always contain text indices in one of
+the above forms.
+
+=head1 WIDGET METHODS
+
+The B<Listbox> method creates a widget object.
+This object supports the B<configure> and B<cget> methods
+described in L<Tk::options> which can be used to enquire and
+modify the options described above.
+The widget also inherits all the methods provided by the generic
+L<Tk::Widget|Tk::Widget> class.
+
+The following additional methods are available for listbox widgets:
+
+=over 4
+
+=item I<$listbox>-E<gt>B<activate>(I<index>)
+
+Sets the active element to the one indicated by I<index>.
+If I<index> is outside the range of elements in the listbox
+then the closest element is activated.
+The active element is drawn with an underline when the widget
+has the input focus, and its index may be retrieved with the
+index B<active>.
+
+=item I<$listbox>-E<gt>B<bbox>(I<index>)
+
+Returns a list of four numbers describing the bounding box of
+the text in the element given by I<index>.
+The first two elements of the list give the x and y coordinates
+of the upper-left corner of the screen area covered by the text
+(specified in pixels relative to the widget) and the last two
+elements give the width and height of the area, in pixels.
+If no part of the element given by I<index> is visible on the
+screen,
+or if I<index> refers to a non-existent element,
+then the result is an empty string; if the element is
+partially visible, the result gives the full area of the element,
+including any parts that are not visible.
+
+=item I<$listbox>-E<gt>B<curselection>
+
+Returns a list containing the numerical indices of
+all of the elements in the listbox that are currently selected.
+If there are no elements selected in the listbox then an empty
+string is returned.
+
+=item I<$listbox>-E<gt>B<delete>(I<first, >?I<last>?)
+
+Deletes one or more elements of the listbox. I<First> and I<last>
+are indices specifying the first and last elements in the range
+to delete. If I<last> isn't specified it defaults to
+I<first>, i.e. a single element is deleted.
+
+=item I<$listbox>-E<gt>B<get>(I<first, >?I<last>?)
+
+If I<last> is omitted, returns the contents of the listbox
+element indicated by I<first>,
+or an empty string if I<first> refers to a non-existent element.
+If I<last> is specified, the command returns a list whose elements
+are all of the listbox elements between I<first> and I<last>,
+inclusive.
+Both I<first> and I<last> may have any of the standard
+forms for indices.
+
+=item I<$listbox>-E<gt>B<index>(I<index>)
+
+Returns the integer index value that corresponds to I<index>.
+If I<index> is B<end> the return value is a count of the number
+of elements in the listbox (not the index of the last element).
+
+=item I<$listbox>-E<gt>B<insert>(I<index, >?I<element, element, ...>?)
+
+Inserts zero or more new elements in the list just before the
+element given by I<index>. If I<index> is specified as
+B<end> then the new elements are added to the end of the
+list. Returns an empty string.
+
+=item I<$listbox>-E<gt>B<itemcget>(I<index>, I<option>)
+
+Returns the current value of the item configuration option given by
+I<option>. Option may have any of the values accepted by the listbox
+B<itemconfigure> command.
+
+=item I<$listbox>-E<gt>B<itemconfigure>(I<index, >?I<option, value,
+option, value, ...>?)
+
+Query or modify the configuration options of an item in the listbox.
+If no option is specified, returns a list describing all of the
+available options for the item (see Tk_ConfigureInfo for information
+on the format of this list). If option is specified with no value,
+then the command returns a list describing the one named option (this
+list will be identical to the corresponding sublist of the value
+returned if no option is specified). If one or more option-value pairs
+are specified, then the command modifies the given widget option(s) to
+have the given value(s); in this case the command returns an empty
+string. The following options are currently supported for items:
+
+=over
+
+=item B<-background> =E<gt> I<color>
+
+I<Color> specifies the background color to use when displaying the
+item. It may have any of the forms accepted by Tk_GetColor.
+
+=item B<-foreground> =E<gt> I<color>
+
+I<Color> specifies the foreground color to use when displaying the
+item. It may have any of the forms accepted by Tk_GetColor.
+
+=item B<-selectbackground> =E<gt> I<color>
+
+I<Color> specifies the background color to use when displaying the
+item while it is selected. It may have any of the forms accepted by
+Tk_GetColor.
+
+=item B<-selectforeground> =E<gt> I<color>
+
+I<Color> specifies the foreground color to use when displaying the
+item while it is selected. It may have any of the forms accepted by
+Tk_GetColor.
+
+=back
+
+=item I<$listbox>-E<gt>B<nearest>(I<y>)
+
+Given a y-coordinate within the listbox window, this command returns
+the index of the (visible) listbox element nearest to that y-coordinate.
+
+=item I<$listbox>-E<gt>B<scan>(I<option, args>)
+
+This command is used to implement scanning on listboxes. It has
+two forms, depending on I<option>:
+
+=over 8
+
+=item I<$listbox>-E<gt>B<scanMark>(I<x, y>)
+
+Records I<x> and I<y> and the current view in the listbox
+window; used in conjunction with later B<scan dragto> commands.
+Typically this command is associated with a mouse button press in
+the widget. It returns an empty string.
+
+=item I<$listbox>-E<gt>B<scanDragto>(I<x, y>.)
+
+This command computes the difference between its I<x> and I<y>
+arguments and the I<x> and I<y> arguments to the last
+B<scan mark> command for the widget.
+It then adjusts the view by 10 times the
+difference in coordinates. This command is typically associated
+with mouse motion events in the widget, to produce the effect of
+dragging the list at high speed through the window. The return
+value is an empty string.
+
+=back
+
+=item I<$listbox>-E<gt>B<see>(I<index>)
+
+Adjust the view in the listbox so that the element given by I<index>
+is visible.
+If the element is already visible then the command has no effect;
+if the element is near one edge of the window then the listbox
+scrolls to bring the element into view at the edge; otherwise
+the listbox scrolls to center the element.
+
+=item I<$listbox>-E<gt>B<selection>(I<option, arg>)
+
+This command is used to adjust the selection within a listbox. It
+has several forms, depending on I<option>:
+
+=over 8
+
+=item I<$listbox>-E<gt>B<selectionAnchor>(I<index>)
+
+Sets the selection anchor to the element given by I<index>.
+If I<index> refers to a non-existent element, then the closest
+element is used.
+The selection anchor is the end of the selection that is fixed
+while dragging out a selection with the mouse.
+The index B<anchor> may be used to refer to the anchor
+element.
+
+=item I<$listbox>-E<gt>B<selectionClear>(I<first, >?I<last>?)
+
+If any of the elements between I<first> and I<last>
+(inclusive) are selected, they are deselected.
+The selection state is not changed for elements outside
+this range.
+
+=item I<$listbox>-E<gt>B<selectionIncludes>(I<index>)
+
+Returns 1 if the element indicated by I<index> is currently
+selected, 0 if it isn't.
+
+=item I<$listbox>-E<gt>B<selectionSet>(I<first, >?I<last>?)
+
+Selects all of the elements in the range between
+I<first> and I<last>, inclusive, without affecting
+the selection state of elements outside that range.
+
+=back
+
+=item I<$listbox>-E<gt>B<size>
+
+Returns a decimal string indicating the total number of elements
+in the listbox.
+
+=item I<$listbox>-E<gt>B<xview>(I<args>)
+
+This command is used to query and change the horizontal position of the
+information in the widget's window. It can take any of the following
+forms:
+
+=over 8
+
+=item I<$listbox>-E<gt>B<xview>
+
+Returns a list containing two elements.
+Each element is a real fraction between 0 and 1; together they describe
+the horizontal span that is visible in the window.
+For example, if the first element is .2 and the second element is .6,
+20% of the listbox's text is off-screen to the left, the middle 40% is visible
+in the window, and 40% of the text is off-screen to the right.
+These are the same values passed to scrollbars via the B<-xscrollcommand>
+option.
+
+=item I<$listbox>-E<gt>B<xview>(I<index>)
+
+Adjusts the view in the window so that the character position given by
+I<index> is displayed at the left edge of the window.
+Character positions are defined by the width of the character B<0>.
+
+=item I<$listbox>-E<gt>B<xviewMoveto>( I<fraction> );
+
+Adjusts the view in the window so that I<fraction> of the
+total width of the listbox text is off-screen to the left.
+I<fraction> must be a fraction between 0 and 1.
+
+=item I<$listbox>-E<gt>B<xviewScroll>( I<number, what> );
+
+This command shifts the view in the window left or right according to
+I<number> and I<what>.
+I<Number> must be an integer.
+I<What> must be either B<units> or B<pages> or an abbreviation
+of one of these.
+If I<what> is B<units>, the view adjusts left or right by
+I<number> character units (the width of the B<0> character)
+on the display; if it is B<pages> then the view adjusts by
+I<number> screenfuls.
+If I<number> is negative then characters farther to the left
+become visible; if it is positive then characters farther to the right
+become visible.
+
+=back
+
+=item I<$listbox>-E<gt>B<yview>(I<?args>?)
+
+This command is used to query and change the vertical position of the
+text in the widget's window.
+It can take any of the following forms:
+
+=over 8
+
+=item I<$listbox>-E<gt>B<yview>
+
+Returns a list containing two elements, both of which are real fractions
+between 0 and 1.
+The first element gives the position of the listbox element at the
+top of the window, relative to the listbox as a whole (0.5 means
+it is halfway through the listbox, for example).
+The second element gives the position of the listbox element just after
+the last one in the window, relative to the listbox as a whole.
+These are the same values passed to scrollbars via the B<-yscrollcommand>
+option.
+
+=item I<$listbox>-E<gt>B<yview>(I<index>)
+
+Adjusts the view in the window so that the element given by
+I<index> is displayed at the top of the window.
+
+=item I<$listbox>-E<gt>B<yviewMoveto>( I<fraction> );
+
+Adjusts the view in the window so that the element given by I<fraction>
+appears at the top of the window.
+I<Fraction> is a fraction between 0 and 1; 0 indicates the first
+element in the listbox, 0.33 indicates the element one-third the
+way through the listbox, and so on.
+
+=item I<$listbox>-E<gt>B<yviewScroll>( I<number, what> );
+
+This command adjusts the view in the window up or down according to
+I<number> and I<what>.
+I<Number> must be an integer.
+I<What> must be either B<units> or B<pages>.
+If I<what> is B<units>, the view adjusts up or down by
+I<number> lines; if it is B<pages> then
+the view adjusts by I<number> screenfuls.
+If I<number> is negative then earlier elements
+become visible; if it is positive then later elements
+become visible.
+
+=back
+
+=back
+
+=head1 DEFAULT BINDINGS
+
+Tk automatically creates class bindings for listboxes that give them
+Motif-like behavior. Much of the behavior of a listbox is determined
+by its B<selectMode> option, which selects one of four ways
+of dealing with the selection.
+
+If the selection mode is B<single> or B<browse>, at most one
+element can be selected in the listbox at once.
+In both modes, clicking button 1 on an element selects
+it and deselects any other selected item.
+In B<browse> mode it is also possible to drag the selection
+with button 1.
+
+If the selection mode is B<multiple> or B<extended>,
+any number of elements may be selected at once, including discontiguous
+ranges. In B<multiple> mode, clicking button 1 on an element
+toggles its selection state without affecting any other elements.
+In B<extended> mode, pressing button 1 on an element selects
+it, deselects everything else, and sets the anchor to the element
+under the mouse; dragging the mouse with button 1
+down extends the selection to include all the elements between
+the anchor and the element under the mouse, inclusive.
+
+Most people will probably want to use B<browse> mode for
+single selections and B<extended> mode for multiple selections;
+the other modes appear to be useful only in special situations.
+
+Any time the selection changes in the listbox, the virtual event
+B<<< <<ListboxSelect>> >>> will be generated. It is easiest to bind to this
+event to be made aware of any changes to listbox selection.
+
+
+In addition to the above behavior, the following additional behavior
+is defined by the default bindings:
+
+=over 4
+
+=item [1]
+
+In B<extended> mode, the selected range can be adjusted by pressing
+button 1 with the Shift key down: this modifies the selection to
+consist of the elements between the anchor and the element under
+the mouse, inclusive.
+The un-anchored end of this new selection can also be dragged with
+the button down.
+
+=item [2]
+
+In B<extended> mode, pressing button 1 with the Control key down
+starts a toggle operation: the anchor is set to the element under
+the mouse, and its selection state is reversed. The selection state
+of other elements isn't changed.
+If the mouse is dragged with button 1 down, then the selection state
+of all elements between the anchor and the element under the mouse
+is set to match that of the anchor element; the selection state of
+all other elements remains what it was before the toggle operation
+began.
+
+=item [3]
+
+If the mouse leaves the listbox window with button 1 down, the window
+scrolls away from the mouse, making information visible that used
+to be off-screen on the side of the mouse.
+The scrolling continues until the mouse re-enters the window, the
+button is released, or the end of the listbox is reached.
+
+=item [4]
+
+Mouse button 2 may be used for scanning.
+If it is pressed and dragged over the listbox, the contents of
+the listbox drag at high speed in the direction the mouse moves.
+
+=item [5]
+
+If the Up or Down key is pressed, the location cursor (active
+element) moves up or down one element.
+If the selection mode is B<browse> or B<extended> then the
+new active element is also selected and all other elements are
+deselected.
+In B<extended> mode the new active element becomes the
+selection anchor.
+
+=item [6]
+
+In B<extended> mode, Shift-Up and Shift-Down move the location
+cursor (active element) up or down one element and also extend
+the selection to that element in a fashion similar to dragging
+with mouse button 1.
+
+=item [7]
+
+The Left and Right keys scroll the listbox view left and right
+by the width of the character B<0>.
+Control-Left and Control-Right scroll the listbox view left and
+right by the width of the window.
+Control-Prior and Control-Next also scroll left and right by
+the width of the window.
+
+=item [8]
+
+The Prior and Next keys scroll the listbox view up and down
+by one page (the height of the window).
+
+=item [9]
+
+The Home and End keys scroll the listbox horizontally to
+the left and right edges, respectively.
+
+=item [10]
+
+Control-Home sets the location cursor to the the first element in
+the listbox, selects that element, and deselects everything else
+in the listbox.
+
+=item [11]
+
+Control-End sets the location cursor to the the last element in
+the listbox, selects that element, and deselects everything else
+in the listbox.
+
+=item [12]
+
+In B<extended> mode, Control-Shift-Home extends the selection
+to the first element in the listbox and Control-Shift-End extends
+the selection to the last element.
+
+=item [13]
+
+In B<multiple> mode, Control-Shift-Home moves the location cursor
+to the first element in the listbox and Control-Shift-End moves
+the location cursor to the last element.
+
+=item [14]
+
+The space and Select keys make a selection at the location cursor
+(active element) just as if mouse button 1 had been pressed over
+this element.
+
+=item [15]
+
+In B<extended> mode, Control-Shift-space and Shift-Select
+extend the selection to the active element just as if button 1
+had been pressed with the Shift key down.
+
+=item [16]
+
+In B<extended> mode, the Escape key cancels the most recent
+selection and restores all the elements in the selected range
+to their previous selection state.
+
+=item [17]
+
+Control-slash selects everything in the widget, except in
+B<single> and B<browse> modes, in which case it selects
+the active element and deselects everything else.
+
+=item [18]
+
+Control-backslash deselects everything in the widget, except in
+B<browse> mode where it has no effect.
+
+=item [19]
+
+The F16 key (labelled Copy on many Sun workstations) or Meta-w
+copies the selection in the widget to the clipboard, if there is
+a selection.
+
+The behavior of listboxes can be changed by defining new bindings for
+individual widgets or by redefining the class bindings.
+
+=back
+
+=head1 TIED INTERFACE
+
+The Tk::Listbox widget can also be tied to a scalar or array variable, with
+different behaviour depending on the variable type, with the following
+tie commands:
+
+ use Tk;
+
+ my ( @array, $scalar, $other );
+ my %options = ( ReturnType => "index" );
+
+ my $MW = MainWindow->new();
+ my $lbox = $MW->Listbox()->pack();
+
+ my @list = ( "a", "b", "c", "d", "e", "f" );
+ $lbox->insert('end', @list );
+
+ tie @array, "Tk::Listbox", $lbox
+ tie $scalar, "Tk::Listbox", $lbox;
+ tie $other, "Tk::Listbox", $lbox, %options;
+
+currently only one modifier is implemented, a 3 way flag for tied scalars
+"ReturnType" which can have values "element", "index" or "both". The default
+is "element".
+
+=over 4
+
+=item Tied Arrays
+
+If you tie an array to the Listbox you can manipulate the items currently
+contained by the box in the same manner as a normal array, e.g.
+
+ print @array;
+ push(@array, @list);
+ my $popped = pop(@array);
+ my $shifted = shift(@array);
+ unshift(@array, @list);
+ delete $array[$index];
+ print $string if exists $array[$i];
+ @array = ();
+ splice @array, $offset, $length, @list
+
+The delete function is implemented slightly differently from the standard
+array implementation. Instead of setting the element at that index to undef
+it instead physically removes it from the Listbox. This has the effect of
+changing the array indices, so for instance if you had a list on non-continuous
+indices you wish to remove from the Listbox you should reverse sort the list
+and then apply the delete function, e.g.
+
+ my @list = ( 1, 2, 4, 12, 20 );
+ my @remove = reverse sort { $a <=> $b } @list;
+ delete @array[@remove];
+
+would safely remove indices 20, 12, 4, 2 and 1 from the Listbox without
+problems. It should also be noted that a similar warning applies to the
+splice function (which would normally be used in this context to perform
+the same job).
+
+
+=item Tied Scalars
+
+Unlike tied arrays, if you tie a scalar to the Listbox you can retrieve the
+currently selected elements in the box as an array referenced by the scalar,
+for instance
+
+ my @list = ( "a", "b", "c", "d", "e", "f" );
+ $lbox->insert('end', sort @list );
+ $lbox->selectionSet(1);
+
+inserts @list as elements in an already existing listbox and selects the
+element at index 1, which is "b". If we then
+
+ print @$selected;
+
+this will return the currently selected elements, in this case "b".
+
+However, if the "ReturnType" arguement is passed when tying the Listbox to the
+scalar with value "index" then the indices of the selected elements will be
+returned instead of the elements themselves, ie in this case "1". This can be
+useful when manipulating both contents and selected elements in the Listbox at
+the same time.
+
+Importantly, if a value "both" is given the scalar will not be tied to an
+array, but instead to a hash, with keys being the indices and values being
+the elements at those indices
+
+You can also manipulate the selected items using the scalar. Equating the
+scalar to an array reference will select any elements that match elements
+in the Listbox, non-matching array items are ignored, e.g.
+
+ my @list = ( "a", "b", "c", "d", "e", "f" );
+ $lbox->insert('end', sort @list );
+ $lbox->selectionSet(1);
+
+would insert the array @list into an already existing Listbox and select
+element at index 1, i.e. "b"
+
+ @array = ( "a", "b", "f" );
+ $selected = \@array;
+
+would select elements "a", "b" and "f" in the Listbox.
+
+Again, if the "index" we indicate we want to use indices in the options hash
+then the indices are use instead of elements, e.g.
+
+ @array = ( 0, 1, 5 );
+ $selected = \@array;
+
+would have the same effect, selecting elements "a", "b" and "f" if the
+$selected variable was tied with %options = ( ReturnType => "index" ).
+
+If we are returning "both", i.e. the tied scalar points to a hash, both key and
+value must match, e.g.
+
+ %hash = ( 0 => "a", 1 => "b", 5 => "f" );
+ $selected = \%hash;
+
+would have the same effect as the previous examples.
+
+It should be noted that, despite being a reference to an array (or possibly a has), you still can not copy the tied variable without it being untied, instead
+you must pass a reference to the tied scalar between subroutines.
+
+=back
+
+=head1 KEYWORDS
+
+listbox, widget, tied
+
+=head1 SEE ALSO
+
+L<Tk::HList>, L<Tk::TextList>.
+
+=cut
+