diff options
Diffstat (limited to 'iwidgets/doc/selectionbox.n')
| -rw-r--r-- | iwidgets/doc/selectionbox.n | 302 |
1 files changed, 302 insertions, 0 deletions
diff --git a/iwidgets/doc/selectionbox.n b/iwidgets/doc/selectionbox.n new file mode 100644 index 00000000000..9d687208bcc --- /dev/null +++ b/iwidgets/doc/selectionbox.n @@ -0,0 +1,302 @@ +'\" +'\" 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. +'\" +'\" @(#) selectionbox.n 1.21 94/12/17 16:04:44 +'\" +.so man.macros +.HS iwidgets::selectionbox iwid +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +iwidgets::selectionbox \- Create and manipulate a selection box widget +.SH SYNOPSIS +\fBiwidgets::selectionbox\fI \fIpathName \fR?\fIoptions\fR? +.SH "INHERITANCE" +itk::Widget <- iwidgets::Selectionbox +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +\fB +activeBackground background borderWidth cursor +exportSelection foreground highlightColor highlightThickness +insertBackground insertBorderWidth insertOffTime insertOnTime +insertWidth relief repeatDelay repeatInterval +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 +\fBtextBackground\fR \fBtextFont\fR +.fi +.LP +See the "entryfield" widget class manual entry for details on the above +associated options. +.LP +.nf +.ta 4c 8c 12c +\fBlabelFont\fR \fBlabelMargin\fR +.fi +.LP +See the "labeledwidget" class 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 class manual entry for details on the above +associated options. +.LP +.nf +.ta 4c 8c 12c +\fBdblClickCommand\fR \fBhscrollMode\fR \fBsbWidth\fR \fBscrollMargin\fR +\fBtextBackground\fR \fBtextFont\fR \fBvscrollMode\fR +.fi +.LP +See the "scrolledlistbox" widget class manual entry for details on the above +associated options. + +.SH "WIDGET-SPECIFIC OPTIONS" +.LP +.nf +Name: \fBchildSitePos\fR +Class: \fBPosition\fR +Command-Line Switch: \fB-childsitepos\fR +.fi +.IP +Specifies the position of the child site in the selection box: \fBn\fR, +\fBs\fR, \fBe\fR, \fBw\fR, or \fB\fR. The default is center +.LP +.nf +Name: \fBheight\fR +Class: \fBHeight\fR +Command-Line Switch: \fB-height\fR +.fi +.IP +Specifies the height of the selection box. The value may be specified in +any of the forms acceptable to Tk_GetPixels. The default is 320 pixels. +.LP +.nf +Name: \fBitemsCommand\fR +Class: \fBCommand\fR +Command-Line Switch: \fB-itemscommand\fR +.fi +.IP +Specifies a command to be evaluated following selection of an item. +.LP +.nf +Name: \fBitemsLabel\fR +Class: \fBText\fR +Command-Line Switch: \fB-itemslabel\fR +.fi +.IP +Specifies the text of the label for the items list. The default is "List". +.LP +.nf +Name: \fBitemsLabelPos\fR +Class: \fBPosition\fR +Command-Line Switch: \fB-itemslabelpos\fR +.fi +.IP +Specifies the position of the label along the side of the items +list: \fBn\fR, \fBne\fR, \fBe\fR, \fBse\fR, \fBs\fR, \fBsw\fR, \fBw\fR, +or \fBnw\fR. The default is nw. +.LP +.nf +Name: \fBitemsOn\fR +Class: \fBItemsOn\fR +Command-Line Switch: \fB-itemson\fR +.fi +.IP +Specifies whether or not to display the items list in any +of the forms acceptable to \fBTcl_GetBoolean\fR. The default is true. +.LP +.nf +Name: \fBmargin\fR +Class: \fBMargin\fR +Command-Line Switch: \fB-margin\fR +.fi +.IP +Specifies distance between the items list and selection entry in any of +the forms acceptable to \fBTk_GetPixels\fR. The default is 7 pixels. +.LP +.nf +Name: \fBselectionCommand\fR +Class: \fBCommand\fR +Command-Line Switch: \fB-selectioncommand\fR +.fi +.IP +Specifies a Tcl procedure to be associated with a return key press event +in the selection entry field. +.LP +.nf +Name: \fBselectionLabel\fR +Class: \fBText\fR +Command-Line Switch: \fB-selectionlabel\fR +.fi +.IP +Specifies the text of the label for the selection entry field. The default +is "Selection". +.LP +.nf +Name: \fBselectionLabelPos\fR +Class: \fBPosition\fR +Command-Line Switch: \fB-selectionlabelpos\fR +.fi +.IP +Specifies the position of the label along the side of the selection: +\fBn\fR, \fBne\fR, \fBe\fR, \fBse\fR, \fBs\fR, \fBsw\fR, \fBw\fR, +or \fBnw\fR. The default is nw. +.LP +.nf +Name: \fBselectionOn\fR +Class: \fBSelectionOn\fR +Command-Line Switch: \fB-selectionon\fR +.fi +.IP +Specifies whether or not to display the selection entry in any +of the forms acceptable to \fBTcl_GetBoolean\fR. The default is true. +.LP +.nf +Name: \fBwidth\fR +Class: \fBWidth\fR +Command-Line Switch: \fB-width\fR +.fi +.IP +Specifies the width of the selection box. The value may be specified in +any of the forms acceptable to Tk_GetPixels. The default is 260 pixels. +.LP +.BE + +.SH DESCRIPTION +.PP +The \fBiwidgets::selectionbox\fR command creates a scrolled list of items and +a selection entry field. The user may choose any of the items displayed +in the scrolled list of alternatives and the selection field will be +filled with the choice. The user is also free to enter a new value in +the selection entry field. Both the list and entry areas have labels. +A child site is also provided in which the user may create other widgets +to be used in conjunction with the selection box. + +.SH "METHODS" +.PP +The \fBiwidgets::selectionbox\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. + +.SH "ASSOCIATED METHODS" +.LP +.nf +.ta 4c 8c 12c +\fBcurselection\fR \fBdelete\fR \fBindex\fR \fBnearest\fR +\fBscan\fR \fBselection\fR \fBsize\fR +.fi +.LP +See the "listbox" widget class 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::selectionbox\fR +command. +.TP +\fIpathName \fBchildsite\fR +Returns the child site widget path name. +.TP +\fIpathName \fBclear\fR \fIcomponent\fR +Delete the contents of either the selection entry widget or +items list. The \fIcomponent\fR argument may be either \fBitems\fR +or \fBselection\fR. +.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::selectionbox\fR +command. +.TP +\fIpathName \fBget\fR +Returns the current value of the selection entry widget. +.TP +\fIpathName \fBinsert\fR \fIcomponent\fR \fIargs\fR +Insert element(s) into either the selection entry widget or +items list. The \fIcomponent\fR argument may be either \fBitems\fR +or \fBselection\fR. The \fIargs\fR follow the rules of either an entry +or list widget depending on the \fIcomponent\fR value. +.TP +\fIpathName \fBselectitem\fR +Replace the selection entry field contents with the currently +selected items value. + +.SH "COMPONENTS" +.LP +.nf +Name: \fBchildsite\fR +Class: \fBFrame\fR +.fi +.IP +The childsite component is the user child site for the selection box. See +the "frame" widget manual entry for details on the childsite component item. +.LP +.nf +Name: \fBitems\fR +Class: \fBScrolledlistbox\fR +.fi +.IP +The items component provides the scrolled list box of items for the selection +box. See the "scrolledlistbox" widget manual entry for details on the +items component item. +.LP +.nf +Name: \fBselection\fR +Class: \fBEntryfield\fR +.fi +.IP +The selection component provides the entry field in the selection box for +display of the selected item in the items component. See the "entryfield" +widget manual entry for details on the selection component item. +.fi + +.SH EXAMPLE +.DS + package require Iwidgets 4.0 + option add *textBackground white + + iwidgets::selectionbox .sb -items {Hello {Out There} World} + pack .sb -padx 10 -pady 10 -fill both -expand yes + + set cs [label [.sb childsite].label -text "Child Site"] + pack $cs -fill x -padx 10 -pady 10 + + .sb insert items 2 {Cruel Cruel} + + .sb selection set 1 +.DE +.SH AUTHOR +Mark L. Ulferts +.SH KEYWORDS +selectionbox, widget |