diff options
Diffstat (limited to 'iwidgets/doc/scrolledlistbox.n')
| -rw-r--r-- | iwidgets/doc/scrolledlistbox.n | 356 |
1 files changed, 356 insertions, 0 deletions
diff --git a/iwidgets/doc/scrolledlistbox.n b/iwidgets/doc/scrolledlistbox.n new file mode 100644 index 00000000000..9e5de5cd72c --- /dev/null +++ b/iwidgets/doc/scrolledlistbox.n @@ -0,0 +1,356 @@ +'\" +'\" Copyright (c) 1995 DSC Technologies Corporation +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" @(#) scrolledlistbox.n 1.21 94/12/17 16:04:44 +'\" +.so man.macros +.HS iwidgets::scrolledlistbox iwid +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +iwidgets::scrolledlistbox \- Create and manipulate scrolled listbox widgets +.SH SYNOPSIS +\fBiwidgets::scrolledlistbox\fI \fIpathName \fR?\fIoptions\fR? +.SH "INHERITANCE" +itk::Widget <- iwidgets::Labeledwidget <- iwidgets::Scrolledwidget <- iwidgets::Scrolledlistbox +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +\fB +activeBackground background borderWidth cursor +exportSelection foreground highlightColor highlightThickness +relief selectBackground selectBorderWidth selectForeground\fR +.fi +.LP +See the "options" manual entry for details on the standard options. +.SH "ASSOCIATED OPTIONS" +.LP +.nf +.ta 4c 8c 12c +\fBselectMode\fR \fBlistvariable\fR +.fi +.LP +See the "listbox" widget manual entry for details on the above +associated options. +.LP +.nf +.ta 4c 8c 12c +\fBactiveRelief\fR \fBelementBorderwidth\fR \fBjump\fR \fBtroughColor\fR +.fi +.LP +See the "scrollbar" widget manual entry for details on the above +associated options. +.SH "INHERITED OPTIONS" +.LP +.nf +.ta 4c 8c 12c +\fBdisabledForeground\fR \fBlabelBitmap\fR \fBlabelFont\fR \fBlabelImage\fR +\fBlabelMargin\fR \fBlabelPos\fR \fBlabelText\fR \fBlabelVariable\fR +\fBstate\fR \fBsticky\fR +.fi +.LP +See the "labeledwidget" class manual entry for details on the inherited +options. +.SH "WIDGET-SPECIFIC OPTIONS" +.LP +.nf +Name: \fBdblClickCommand\fR +Class: \fBCommand\fR +Command-Line Switch: \fB-dblclickcommand\fR +.fi +.IP +Specifies a Tcl command procedure which is called when an item is +double clicked. Typically this occurs when mouse button 1 is double +clicked over an item. Selection policy does not matter. +.LP +.nf +Name: \fBheight\fR +Class: \fBHeight\fR +Command-Line Switch: \fB-height\fR +.fi +.IP +Specifies the height of the scrolled list box as an entire unit. +The value may be specified in any of the forms acceptable to +\fBTk_GetPixels\fR. Any additional space needed to display the other +components such as labels, margins, and scrollbars force the listbox +to be compressed. A value of zero along with the same value for +the width causes the value given for the visibleitems option +to be applied which administers geometry constraints in a different +manner. The default height is zero. +.LP +.nf +Name: \fBhscrollMode\fR +Class: \fBScrollMode\fR +Command-Line Switch: \fB-hscrollmode\fR +.fi +.IP +Specifies the the display mode to be used for the horizontal +scrollbar: \fBstatic, dynamic,\fR or \fBnone\fR. In static mode, the +scroll bar is displayed at all times. Dynamic mode displays the +scroll bar as required, and none disables the scroll bar display. The +default is static. +.LP +.nf +Name: \fBsbWidth\fR +Class: \fBWidth\fR +Command-Line Switch: \fB-sbwidth\fR +.fi +.IP +Specifies the width of the scrollbar in any of the forms acceptable +to \fBTk_GetPixels\fR. The default width is 15 pixels.. +.LP +.nf +Name: \fBscrollMargin\fR +Class: \fBMargin\fR +Command-Line Switch: \fB-scrollmargin\fR +.fi +.IP +Specifies the distance between the listbox and scrollbar in any of the +forms acceptable to \fBTk_GetPixels\fR. The default is 3 pixels. +.LP +.nf +Name: \fBselectionCommand\fR +Class: \fBCommand\fR +Command-Line Switch: \fB-selectioncommand\fR +.fi +.IP +Specifies a Tcl command procedure which is called when an item is +selected. Selection policy does not matter. +.LP +.nf +Name: \fBstate\fR +Class: \fBState\fR +Command-Line Switch: \fB-state\fR +.fi +.IP +Specifies one of two states for the listbox: \fBnormal\fR or \fBdisabled\fR. +If the listbox is disabled then selection is ignored. The default is +normal. +.LP +.nf +Name: \fBtextBackground\fR +Class: \fBBackground\fR +Command-Line Switch \fB-textbackground\fR +.fi +.IP +Specifies the background color for the listbox. This allows the background +within the listbox to be different from the normal background color. +.LP +.nf +Name: \fBtextFont\fR +Class: \fBFont\fR +Command-Line Switch: \fB-textfont\fR +.fi +.IP +Specifies the font to be used for text in the listbox. This allows for +the font associated with text internal to the scrolled listbox to be +different than the font for labels. +.LP +.nf +Name: \fBvisibleitems\fR +Class: \fBVisibleItems\fR +Command-Line Switch: \fB-visibleitems\fR +.fi +.IP +Specifies the widthxheight in characters and lines for the listbox. +This option is only administered if the width and height options +are both set to zero, otherwise they take precedence. The default value +is 20x10. With the visibleitems option engaged, geometry constraints +are maintained only on the listbox. The size of the other components such as +labels, margins, and scroll bars, are additive and independent, +effecting the overall size of the scrolled list box. In contrast, +should the width and height options have non zero values, they +are applied to the scrolled list box as a whole. The listbox +is compressed or expanded to maintain the geometry constraints. +.LP +.nf +Name: \fBvscrollMode\fR +Class: \fBScrollMode\fR +Command-Line Switch: \fB-vscrollmode\fR +.fi +.IP +Specifies the the display mode to be used for the vertical +scrollbar: \fBstatic, dynamic,\fR or \fBnone\fR. In static mode, the +scroll bar is displayed at all times. Dynamic mode displays the +scroll bar as required, and none disables the scroll bar display. The +default is static. +.LP +.nf +Name: \fBwidth\fR +Class: \fBWidth\fR +Command-Line Switch: \fB-width\fR +.fi +.IP +Specifies the width of the scrolled list box as an entire unit. +The value may be specified in any of the forms acceptable to +\fBTk_GetPixels\fR. Any additional space needed to display the other +components such as labels, margins, and scrollbars force the listbox +to be compressed. A value of zero along with the same value for +the height causes the value given for the visibleitems option +to be applied which administers geometry constraints in a different +manner. The default width is zero. +.BE + +.SH DESCRIPTION +.PP +The \fBiwidgets::scrolledlistbox\fR command creates +a scrolled listbox with additional options to manage +horizontal and vertical scrollbars. This includes options to control +which scrollbars are displayed and the method, i.e. statically or +dynamically. + +.SH "METHODS" +.PP +The \fBiwidgets::scrolledlistbox\fR command creates a new Tcl command whose +name is \fIpathName\fR. This +command may be used to invoke various +operations on the widget. It has the following general form: +.DS C +\fIpathName option \fR?\fIarg arg ...\fR? +.DE +\fIOption\fR and the \fIarg\fRs +determine the exact behavior of the command. +.PP +Many of the widget commands for a scrolledlistbox take as one argument an +indicator of which entry of the list box to operate on. These +indicators are called \fIindex\fRes and may be specified in +any of the following forms: +.TP 12 +\fInumber\fR +Specifies the element as a numerical index, where 0 corresponds +to the first element in the listbox. +.TP 12 +\fBactive\fR +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 \fBactivate\fR +widget command. +.TP 12 +\fBanchor\fR +Indicates the anchor point for the selection, which is set with the +\fBselection anchor\fR widget command. +.TP 12 +\fBend\fR +Indicates the end of the listbox. +For some commands this means just after the last element; +for other commands it means the last element. +.TP 12 +\fB@\fIx\fB,\fIy\fR +Indicates the element that covers the point in the listbox window +specified by \fIx\fR and \fIy\fR (in pixel coordinates). If no +element covers that point, then the closest element to that +point is used. +.TP 12 +\fIpattern\fR +If the index doesn't satisfy one of the above forms then this +form is used. \fIPattern\fR is pattern-matched against the items in +the list box, in order from the top down, until a matching entry is found. +The rules of \fBTcl_StringMatch\fR are used. +.PP +The following widget commands are possible for scrolledlistbox widgets: + +.SH "ASSOCIATED METHODS" +.LP +.nf +.ta 4c 8c 12c +\fBactivate\fR \fBbbox\fR \fBcurselection\fR \fBdelete\fR +\fBget\fR \fBindex\fR \fBinsert\fR \fBitemconfigure\fR +\fBnearest\fR \fBscan\fR \fBsee\fR \fBselection\fR +\fBsize\fR \fBxview\fR \fByview\fR +.fi +.LP +See the "listbox" manual entry for details on the associated methods. + +.SH "WIDGET-SPECIFIC METHODS" +.TP +\fIpathName \fBcget\fR \fIoption\fR +Returns the current value of the configuration option given +by \fIoption\fR. +\fIOption\fR may have any of the values accepted by the \fBiwidgets::scrolledlistbox\fR +command. +.TP +\fIpathName \fBclear\fR +Clears the listbox of all items. +.TP +\fIpathName\fR \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +Query or modify the configuration options of the widget. +If no \fIoption\fR is specified, returns a list describing all of +the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for +information on the format of this list). If \fIoption\fR is specified +with no \fIvalue\fR, 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 \fIoption\fR is specified). If +one or more \fIoption\-value\fR 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. +\fIOption\fR may have any of the values accepted by the \fBiwidgets::scrolledlistbox\fR +command. +.TP +\fIpathName \fBgetcurselection\fR +Returns the contents of the listbox element indicated by the current +selection indexes. Short cut version of get and curselection command +combination. +.TP +\fIpathName \fBjustify \fIdirection\fR +Justifies the list contents via teh scroll bars in one of four directions: +\fBleft\fR, \fBright\fR, \fBtop\fR, or \fBbottom\fR. +.TP +\fIpathName \fBselecteditemcount\fR +Returns the number of items currently selected in the list. +.TP +\fIpathName \fBsort\fR \fIorder\fR +Sort the current list in any of the forms accepted by Tcl's lsort command. +Also accepts either \fBascending\fR or \fBdescending\fR order. + +.SH "COMPONENTS" +.LP +.nf +Name: \fBlistbox\fR +Class: \fBlistbox\fR +.fi +.IP +The listbox component is the listbox widget. See the "listbox" widget +manual entry for details on the listbox component item. +.LP +.nf +Name: \fBhorizsb\fR +Class: \fBScrollbar\fR +.fi +.IP +The horizsb component is the horizontal scroll bar. See the "scrollbar" +widget manual entry for details on the horizsb component item. +.LP +.nf +Name: \fBvertsb\fR +Class: \fBScrollbar\fR +.fi +.IP +The vertsb component is the vertical scroll bar. See the "scrollbar" widget +manual entry for details on the vertsb component item. +.fi + +.SH EXAMPLE +.DS + package require Iwidgets 4.0 + option add *textBackground white + proc selCmd {} { + puts stdout "[.slb getcurselection]" + } + proc defCmd {} { + puts stdout "Double Click" + return [selCmd] + } + iwidgets::scrolledlistbox .slb -selection single \\ + -vscrollmode static -hscrollmode dynamic -labeltext "List" \\ + -selectioncommand selCmd -dblclickcommand defCmd + pack .slb -padx 10 -pady 10 -fill both -expand yes + .slb insert end {Hello {Out There} World} +.DE +.SH AUTHOR +Mark L. Ulferts +.SH KEYWORDS +scrolledlistbox, listbox, widget |