summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Tk/TList.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/TList.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/TList.pod597
1 files changed, 597 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/TList.pod b/Master/tlpkg/tlperl/lib/Tk/TList.pod
new file mode 100644
index 00000000000..b8937fa8ef0
--- /dev/null
+++ b/Master/tlpkg/tlperl/lib/Tk/TList.pod
@@ -0,0 +1,597 @@
+# Copyright (c) 1996, Expert Interface Technologies
+# See the file "license.terms" for information on usage and redistribution
+# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+#
+# The file man.macros and some of the macros used by this file are
+# copyrighted: (c) 1990 The Regents of the University of California.
+# (c) 1994-1995 Sun Microsystems, Inc.
+# The license terms of the Tcl/Tk distribution are in the file
+# license.tcl.
+
+=head1 NAME
+
+Tk::TList - Create and manipulate Tix Tabular List widgets
+
+=for category Tix Extensions
+
+=head1 SYNOPSIS
+
+S< >I<$tlist> = I<$parent>-E<gt>B<TList>(?I<options>?);
+
+=head1 SUPER-CLASS
+
+None.
+
+=head1 STANDARD OPTIONS
+
+B<-background> B<-borderwidth> B<-class> B<-cursor> B<-foreground>
+B<-font> B<-height> B<-highlightcolor> B<-highlightthickness>
+B<-relief> B<-selectbackground> B<-selectforeground>
+B<-xscrollcommand> B<-yscrollcommand> B<-width>
+
+See L<Tk::options> for details of the standard options.
+
+=head1 WIDGET-SPECIFIC OPTIONS
+
+=over 4
+
+=item Name: B<browsecmd>
+
+=item Class: B<BrowseCmd>
+
+=item Switch: B<-browsecmd>
+
+Specifies a perl/Tk B<callback> to be executed when the user browses through the
+entries in the TList widget.
+
+=item Name: B<command>
+
+=item Class: B<Command>
+
+=item Switch: B<-command>
+
+Specifies the perl/Tk B<callback> to be executed when the user invokes a list
+entry in the TList widget. Normally the user invokes a list
+entry by double-clicking it or pressing the Return key.
+
+=item Name: B<foreground>
+
+=item Class: B<Foreground>
+
+=item Switch: B<-foreground>
+
+=item Alias: B<-fg>
+
+Specifies the default foreground color for the list entries.
+
+=item Name: B<height>
+
+=item Class: B<Height>
+
+=item Switch: B<-height>
+
+Specifies the desired height for the window in number of characters.
+
+=item Name: B<itemType>
+
+=item Class: B<ItemType>
+
+=item Switch: B<-itemtype>
+
+Specifies the default type of display item for this TList widget. When
+you call the B<insert> methods, display items of this
+type will be created if the B<-itemtype> option is not specified.
+
+=item Name: B<orient>
+
+=item Class: B<Orient>
+
+=item Switch: B<-orient>
+
+Specifies the order of tabularizing the list entries. When set to
+"B<vertical>", the entries are arranged in a column, from top to
+bottom. If the entries cannot be contained in one column, the
+remaining entries will go to the next column, and so on. When set to
+"B<horizontal>", the entries are arranged in a row, from left to
+right. If the entries cannot be contained in one row, the remaining
+entries will go to the next row, and so on.
+
+=item Name: B<padX>
+
+=item Class: B<Pad>
+
+=item Switch: B<-padx>
+
+The default horizontal padding for list entries.
+
+=item Name: B<padY>
+
+=item Class: B<Pad>
+
+=item Switch: B<-padx>
+
+The default vertical padding for list entries.
+
+=item Name: B<selectBackground>
+
+=item Class: B<SelectBackground>
+
+=item Switch: B<-selectbackground>
+
+Specifies the background color for the selected list entries.
+
+=item Name: B<selectBorderWidth>
+
+=item Class: B<BorderWidth>
+
+=item Switch: B<-selectborderwidth>
+
+Specifies a non-negative value indicating the width of the 3-D border
+to draw around selected items. The value may have any of the forms
+acceptable to B<Tk_GetPixels>.
+
+=item Name: B<selectForeground>
+
+=item Class: B<SelectForeground>
+
+=item Switch: B<-selectforeground>
+
+Specifies the foreground color for the selected list entries.
+
+=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<single>.
+
+=item Name: B<sizeCmd>
+
+=item Class: B<SizeCmd>
+
+=item Switch: B<-sizecmd>
+
+Specifies a perl/Tk B<callback> to be called whenever the TList widget
+changes its size. This command can be useful to implement "user scroll
+bars when needed" features.
+
+=item Name: B<state>
+
+=item Class: B<State>
+
+=item Switch: B<-state>
+
+Specifies whether the TList command should react to user actions. When
+set to "B<normal>", the TList reacts to user actions in the normal
+way. When set to "B<disabled>", the TList can only be scrolled, but
+its entries cannot be selected or activated.
+
+=item Name: B<width>
+
+=item Class: B<Width>
+
+=item Switch: B<-width>
+
+Specifies the desired width for the window in characters.
+
+=back
+
+=head1 DESCRIPTION
+
+The B<TList> method creates a new window (given by the
+$widget argument) and makes it into a TList widget.
+Additional options, described above, may be specified on the command
+line or in the option database to configure aspects of the
+TList widget such as its cursor and relief.
+
+The TList widget can be used to display data in a tabular format. The
+list entries of a TList widget are similar to the entries in the Tk
+listbox widget. The main differences are (1) the TList widget can
+display the list entries in a two dimensional format and (2) you can
+use graphical images as well as multiple colors and fonts for
+the list entries.
+
+Each list entry is identified by an B<index>, which can be in the
+following forms:
+
+=over 4
+
+=item I<number>
+
+An integer that indicates the position of the entry in the list. 0
+means the first position, 1 means the second position, and so on.
+
+=item B<end>
+
+Indicates the end of the listbox. For some commands this means just
+after the last entry; for other commands it means the last entry.
+
+=item B<@>I<x>,I<y>
+
+Indicates the element that covers the point in the listbox window
+specified by x and y (in pixel coordinates). If no element covers that
+point, then the closest element to that point is used.
+
+=back
+
+=head1 DISPLAY ITEMS
+
+Each list entry in an TList widget is associated with a B<display>
+item. The display item determines what visual information should
+be displayed for this list entry. Please see L<Tk::DItem>
+for a list of all display items.
+
+When a list entry is created by the B<insert> command, the type of
+its display item is determined by the B<-itemtype> option passed
+to these commands. If the B<-itemtype> is omitted, then by default
+the type specified by this TList widget's B<-itemtype> option is
+used.
+
+=head1 WIDGET METHODS
+
+The B<TList> 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 TList widgets:
+
+=over 4
+
+=item I<$tlist>-E<gt>B<anchorSet>(I<index>)
+
+Sets the anchor to the list entry identified by I<index>. The
+anchor is the end of the selection that is fixed while dragging out a
+selection with the mouse.
+
+=item I<$tlist>-E<gt>B<anchorClear>
+
+Removes the anchor, if any, from this TList widget. This only removes
+the surrounding highlights of the anchor entry and does not affect its
+selection status.
+
+=item I<$tlist>-E<gt>B<delete>(I<from, >?I<to>?)
+
+Deletes one or more list entries between the two entries specified by
+the indices I<from> and I<to>. If I<to> is not specified, deletes
+the single entry specified by I<from>.
+
+=item I<$tlist>-E<gt>B<dragsiteSet>(I<index>)
+
+Sets the dragsite to the list entry identified by
+I<index>. The dragsite is used to indicate the source of a
+drag-and-drop action. Currently drag-and-drop functionality has not
+been implemented in Tix yet.
+
+=item I<$tlist>-E<gt>B<dragsiteClear>
+
+Remove the dragsite, if any, from the this TList widget. This only
+removes the surrounding highlights of the dragsite entry and does not
+affect its selection status.
+
+=item I<$tlist>-E<gt>B<dropsiteSet>(I<index>)
+
+Sets the dropsite to the list entry identified by I<index>. The
+dropsite is used to indicate the target of a drag-and-drop
+action. Currently drag-and-drop functionality has not been implemented
+in Tix yet.
+
+=item I<$tlist>-E<gt>B<dropsiteClear>
+
+Remove the dropsite, if any, from the this TList widget. This only
+removes the surrounding highlights of the dropsite entry and does not
+affect its selection status.
+
+=item I<$tlist>-E<gt>B<entrycget>(I<index, option>)
+
+Returns the current value of the configuration option given by
+I<option> for the entry indentfied by I<index>. I<Option> may
+have any of the values accepted by the B<insert> method.
+
+=item I<$tlist>-E<gt>B<entryconfigure>(I<index, >?I<option>?, I<?value, option, value, ...>?)
+
+Query or modify the configuration options of the list entry identified
+by I<index>. If no I<option> is specified, returns a list
+describing all of the available options for I<index> (see
+B<Tk_ConfigureInfo> for information on the format of this list). If
+I<option> is specified with no I<value>, then the method
+returns a list describing the one named option (this list will be
+identical to the corresponding sublist of the value returned if no
+I<option> is specified). If one or more I<option-value> pairs
+are specified, then the command modifies the given option(s) to have
+the given value(s); in this case the method returns an empty string.
+I<Option> may have any of the values accepted by the B<insert>
+method. The exact set of options depends on the
+value of the B<-itemtype> option passed to the the B<insert>
+method when this list entry is created.
+
+=item I<$tlist>-E<gt>B<insert>(I<index, >?I<option, value, ...>?)
+
+Creates a new list entry at the position indicated by I<index>. The
+following configuration options can be given to configure the list
+entry:
+
+=over 8
+
+=item B<-itemtype> => I<type>
+
+Specifies the type of display item to be display for the new list
+entry. I<type> must be a valid display item type. Currently the
+available display item types are B<image>, B<imagetext>,
+B<text>, and I<$widget>. If this option is not specified, then by
+default the type specified by this TList widget's B<-itemtype>
+option is used.
+
+=item B<-state> => I<state>
+
+Specifies whether this entry can be selected or invoked by the user.
+Must be either B<normal> or B<disabled>.
+
+=item B<-data> => I<data>
+
+Arbitrary data to be associated with the entry (a perl scalar value).
+
+=back
+
+The B<insert> method accepts additional configuration options
+to configure the display item associated with this list entry. The set
+of additional configuration options depends on the type of the display
+item given by the B<-itemtype> option. Please see
+L<Tk::DItem> for a list of the configuration options for
+each of the display item types.
+
+=item I<$tlist>-E<gt>B<info>(I<option, >I<arg, ...>)
+
+Query information about the TList widget. I<option> can be one
+of the following:
+
+=over 8
+
+=item I<$tlist>-E<gt>B<info>(B<anchor, >I<index>)
+
+Returns the index of the current anchor, if any, of the TList
+widget. If the anchor is not set, returns the empty string.
+
+=item I<$tlist>-E<gt>B<info>(B<dragsite, >I<index>)
+
+Returns the index of the current dragsite, if any, of the TList
+widget. If the dragsite is not set, returns the empty string.
+
+=item I<$tlist>-E<gt>B<info>(B<dropsite, >I<index>)
+
+Returns the index of the current dropsite, if any, of the TList
+widget. If the dropsite is not set, returns the empty string.
+
+=item I<$tlist>-E<gt>B<info>(B<selection>)
+
+Returns a list of selected elements in the TList widget. If no entries
+are selected, returns an empty string.
+
+=back
+
+=item I<$tlist>-E<gt>B<nearest>(I<x, y>)
+
+Given an I<(x,y)> coordinate within the TList window, this command
+returns the index of the TList element nearest to that coordinate.
+
+=item I<$tlist>-E<gt>B<see>(I<index>)
+
+Adjust the view in the TList so that the entry given by I<index> is
+visible. If the entry is already visible then the command has no
+effect; otherwise TList scrolls to bring the element into view at the edge
+to which it is nearest.
+
+=item I<$tlist>-E<gt>B<selection>(I<option, >I<arg, ...>)
+
+This command is used to adjust the selection within a TList widget. It
+has several forms, depending on I<option>:
+
+=over 8
+
+=item I<$tlist>-E<gt>B<selectionClear>(?I<from>?, ?I<to>?)
+
+When no extra arguments are given, deselects all of the list entrie(s)
+in this TList widget. When only I<from> is given, only the list
+entry identified by I<from> is deselected. When both I<from> and
+I<to> are given, deselects all of the list entrie(s) between
+between I<from> and I<to>, inclusive, without affecting the
+selection state of entries outside that range.
+
+=item I<$tlist>-E<gt>B<selectionIncludes>(I<index>)
+
+Returns 1 if the list entry indicated by I<index> is currently
+selected; returns 0 otherwise.
+
+=item I<$tlist>-E<gt>B<selectionSet>(I<from, >?I<to>?)
+
+Selects all of the list entrie(s) between between I<from> and
+I<to>, inclusive, without affecting the selection state of entries
+outside that range. When only I<from> is given, only the list entry
+identified by I<from> is selected.
+
+=back
+
+=item I<$tlist>-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<$tlist>-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
+0.2 and the second element is 0.6, 20% of the TList entry is
+off-screen to the left, the middle 40% is visible in the window, and
+40% of the entry is off-screen to the right. These are the same values
+passed to scrollbars via the B<-xscrollcommand> option.
+
+=item I<$tlist>-E<gt>B<xview>(I<index>)
+
+Adjusts the view in the window so that the list entry identified by
+I<index> is aligned to the left edge of the window.
+
+=item I<$tlist>-E<gt>B<xviewMoveto>(I<fraction>)
+
+Adjusts the view in the window so that I<fraction> of the total
+width of the TList is off-screen to the left. I<fraction> must be
+a fraction between 0 and 1.
+
+=item I<$tlist>-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<$tlist>-E<gt>B<yview>(I<?args>?)
+
+This command is used to query and change the vertical position of the
+entries in the widget's window. It can take any of the following forms:
+
+=over 8
+
+=item I<$tlist>-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 list element at the top of the window, relative to the TList as a
+whole (0.5 means it is halfway through the TList, for example). The
+second element gives the position of the list entry just after the
+last one in the window, relative to the TList as a whole. These are
+the same values passed to scrollbars via the B<-yscrollcommand>
+option.
+
+=item I<$tlist>-E<gt>B<yview>(I<index>)
+
+Adjusts the view in the window so that the list entry given by
+I<index> is displayed at the top of the window.
+
+=item I<$tlist>-E<gt>B<yviewMoveto>(I<fraction>)
+
+Adjusts the view in the window so that the list entry given by
+I<fraction> appears at the top of the window. I<Fraction> is a
+fraction between 0 and 1; 0 indicates the first entry in the TList,
+0.33 indicates the entry one-third the way through the TList, and so
+on.
+
+=item I<$tlist>-E<gt>B<yviewScroll>(I<number, what>)
+
+This command adjust 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 entries become visible; if
+it is positive then later entries become visible.
+
+=back
+
+=back
+
+=head1 BINDINGS
+
+=over 4
+
+=item [1]
+
+If the B<-selectmode> is "browse", when the user drags the mouse
+pointer over the list entries, the entry under the pointer will be
+highlighted and the B<-browsecmd> procedure will be called with
+one parameter, the index of the highlighted entry. Only one entry
+can be highlighted at a time. The B<-command> procedure will be
+called when the user double-clicks on a list entry.
+
+=item [2]
+
+If the B<-selectmode> is "single", the entries will only be
+highlighted by mouse E<lt>ButtonRelease-1E<gt> events. When a new list entry
+is highlighted, the B<-browsecmd> procedure will be called with
+one parameter indicating the highlighted list entry. The
+B<-command> procedure will be called when the user double-clicks
+on a list entry.
+
+=item [3]
+
+If the B<-selectmode> is "multiple", when the user drags the mouse
+pointer over the list entries, all the entries under the pointer will
+be highlighted. However, only a contiguous region of list entries can
+be selected. When the highlighted area is changed, the
+B<-browsecmd> procedure will be called with an undefined
+parameter. It is the responsibility of the B<-browsecmd> procedure
+to find out the exact highlighted selection in the TList. The
+B<-command> procedure will be called when the user double-clicks
+on a list entry.
+
+=item [4]
+
+If the B<-selectmode> is "extended", when the user drags the mouse
+pointer over the list entries, all the entries under the pointer will
+be highlighted. The user can also make disjointed selections using
+E<lt>Control-ButtonPress-1E<gt>. When the highlighted area is changed, the
+B<-browsecmd> procedure will be called with an undefined
+parameter. It is the responsibility of the B<-browsecmd> procedure
+to find out the exact highlighted selection in the TList. The
+B<-command> procedure will be called when the user double-clicks
+on a list entry.
+
+=back
+
+=cut
+
+# BUG:
+# click on 'one' in example below does not make
+# it 'active' item (didn't GBARR reported this before!?)
+
+=head1 EXAMPLE
+
+This example demonstrates how to use an TList to store a list of
+numbers:
+
+ use strict;
+ use Tk ();
+ use Tk::TList;
+
+ my $mw = Tk::MainWindow->new();
+ my $image = $mw->Getimage('folder');
+ my $tlist = $mw->TList(-orient => 'vertical');
+ for my $text ( qw/one two three four five six seven eight nine/ ) {
+ $tlist->insert('end',
+ -itemtype=>'imagetext', -image=>$image, -text=>$text);
+ }
+
+ $tlist->pack(-expand=>'yes', -fill=>'both');
+
+ Tk::MainLoop;
+
+=head1 SEE ALSO
+
+L<Tk::options|Tk::options>
+L<Tk::Widget|Tk::Widget>
+L<Tk::DItem|Tk::DItem>
+L<Tk::HList|Tk::HList>
+L<Tk::TixGrid|Tk::TixGrid>
+
+=head1 KEYWORDS
+
+Tix(n), Tabular Listbox, Display Items
+
+=cut
+