diff options
Diffstat (limited to 'tix/man/DItem.n')
| -rw-r--r-- | tix/man/DItem.n | 542 |
1 files changed, 542 insertions, 0 deletions
diff --git a/tix/man/DItem.n b/tix/man/DItem.n new file mode 100644 index 00000000000..0dd1220e822 --- /dev/null +++ b/tix/man/DItem.n @@ -0,0 +1,542 @@ +'\" +'\" 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 distrobution are in the file +'\" license.tcl. +.so man.macros +'---------------------------------------------------------------------- +.HS tixItemType tix 4.0 +.BS +' +' +'---------------------------------------------------------------------- +.SH NAME +Tix Display Items +' +.BE +' +.SH DESCRIPTION +' +The Tix \fBDisplay Items\fR and \fBDisplay Types\fR are devised to +solve a general problem: many Tix widgets (both existing and planned +ones) display many items of many types simutaneously. +' +.PP +' +For example, a hierarchical listbox widget (HList) can display items +of images, plain text and subwindows in the form of a +hierarchy. Another widget, the tabular listbox, (TList, currently +planned and will be released in Tix 4.1) also display items of the +same types, although it arranges the items in a tabular form. Yet +another widget, the spreadsheet widget, also displays similar types +items, but in yet another format. +' +.PP +' +In these examples, the display items in different widgets are only +different in how they are arranged by the \fBhost widget\fR. In Tix, +display items are clearly separated from the host widgets. The +advantage is two-fold: first, the creation and configuration of +display items become uniform across different host widgets. Second, +new display item types can be added without the need to modify the +existing host widgets. +' +.PP +' +In a way, Tix display items are similar to the items inside Tk +the canvas widget. However, unlike the Tix display items, the canvas +items are not independent of the canvas widget; this makes it +impossible to use the canvas items inside other types of TK widgets. +' +.PP +' +The appearance of a display item is controlled by a set of +\fIattributes\fR. It is observed that each the attributes usually fall +into one of two categroies: "\fIindividual\fR" or +"\fIcollective\fR". For example, the text items inside a HList widget +may all display a different text string; however, in most cases, the +text items share the same color, font and spacing. Instead of keeping +a duplicated version of the same attributes inside each display item, +it will be advantageous to put the collective attributes in a +special object called a \fBdisplay style\fR. First, there is the space +concern: a host widget may have many thousands of items; keeping +dupilcated attributes will be very wasteful. Second, when it becomes +necessary to change a collective attribute, such as changing all the +text items' foreground color to red, it will be more efficient to +change only the display style object than to modify all the text +items one by one. +' +.PP +' +The attributes of the a display item are thus stored in two places: it +has a set of \fBitem options\fR to store its individual attributes. Each +display item is also associated with a \fIdisplay style\fR, which specifies +the collective attributes of all items associated with itself. +' +.PP +' +The division between the individual and collective attributes are +fixed and cannot be changed. Thus, when it becomes necessary for some +items to differ in their collective attributes, two or more \fBdisplay +styles\fR can be used. For example, suppose you want to display two +columns of text items inside an HList widget, one column in red and +the other in blue. You can create a TextStyle object called "red", +which defines a red foreground, and another called "blue", which +defines a blue foreground. You can then associate all text items of +the first column to "red" and the second column to "blue". +' +.SH DISPLAY ITEM TYPES AND OPTIONS +' +Currently there are three types of display items: \fBtext\fR, +\fBimagetext\fR and \fBwindow\fR. +' +'---------------------------------------------------------------------- +' ImageText +'---------------------------------------------------------------------- +.SH IMAGETEXT ITEMS +' +Display items of the type \fBimagetext\fR are used to display an image +together with a text string. Imagetext items support the following options: +' +.PP +\fBITEM OPTIONS\fR +.PP +.RS +'----------BEGIN +.LP +.nf +Name: \fBbitmap\fR +Class: \fBBitmap\fR +Switch: \fB\-bitmap\fR +.fi +.IP +Specifies the bitmap to display in the item. +'----------END +' +'----------BEGIN +.LP +.nf +Name: \fBimage\fR +Class: \fBImage\fR +Switch: \fB\-image\fR +.fi +.IP +Specifies the image to display in the item. When both the +\fB\-bitmap\fR and \fB\-image\fR options are specified, only the image +will be displayed. +'----------END +' +'----------BEGIN +.LP +.nf +Name: \fBimageTextStyle\fR +Class: \fBImageTextStyle\fR +Switch: \fB\-style\fR +.fi +.IP +Specifies the display style to use for this item. Must be the +name of a \fBimagetext\fR display style that has already be created by +the \fBtixDisplayStyle(n)\fR command. +'----------END +' +'----------BEGIN +.LP +.nf +Name: \fBshowImage\fR +Class: \fBShowImage\fR +Switch: \fB\-showimage\fR +.fi +.IP +A Boolean value that specifies whether the image/bitmap should be +displayed. +'----------END +' +'----------BEGIN +.LP +.nf +Name: \fBshowText\fR +Class: \fBShowText\fR +Switch: \fB\-showtext\fR +.fi +.IP +A Boolean value that specifies whether the text string should be +displayed. +'----------END +' +'----------BEGIN +.LP +.nf +Name: \fBtext\fR +Class: \fBText\fR +Switch: \fB\-text\fR +.fi +.IP +Specifies the text string to display in the item. +'----------END +' +'----------BEGIN +.LP +.nf +Name: \fBunderline\fR +Class: \fBUnderline\fR +Switch: \fB\-underline\fR +.fi +.IP +Specifies the integer index of a character to underline in the text +string in the item. 0 corresponds to the first character of the text +displayed in the widget, 1 to the next character, and so on. +'----------END +.RE +' +.PP +\fBSTYLE OPTIONS\fR +' +.PP +The style information of \fBimagetext\fR items are stored in the +\fBimagetext\fR display style. The following options are supported: +' +.RS +' +.PP +\fBSTANDARD OPTIONS\fR +' +.PP +\fC +.ta 6c +.nf +activeBackground activeForeground +anchor background +disabledBackground disabledForeground +foreground font +justify padX +padY selectBackground +selectForeground wrapLength +.fi +\fR +.ta 4c +.PP +See the \fBoptions(n)\fR manual entry for details on the standard +options. +.PP +' +.PP +\fBSTYLE-SPECIFIC OPTIONS\fR +.PP +'----------BEGIN +.LP +.nf +Name: \fBgap\fR +Class: \fBGap\fR +Switch: \fB\-gap\fR +' +.fi +.IP +Specifies the distance between the bitmap/image and the text string, +in number of pixels. +'----------END +' +.RE +' +'********************************************************************** +' +' text +' +'********************************************************************** +.SH TEXT ITEMS +' +Display items of the type \fBtext\fR are used to display a text string +in a widget. Text items support the following options: +' +.PP +\fBITEM OPTIONS\fR +.PP +.RS +'----------BEGIN +.LP +.nf +Name: \fBtextStyle\fR +Class: \fBTextStyle\fR +Switch: \fB\-style\fR +.fi +.IP +Specifies the display style to use for this text item. Must be the +name of a \fBtext\fR display style that has already be created by the +\fBtixDisplayStyle(n)\fR command. +'----------END +' +'----------BEGIN +.LP +.nf +Name: \fBtext\fR +Class: \fBText\fR +Switch: \fB\-text\fR +.fi +.IP +Specifies the text string to display in the item. +'----------END +' +'----------BEGIN +.LP +.nf +Name: \fBunderline\fR +Class: \fBUnderline\fR +Switch: \fB\-underline\fR +.fi +.IP +Specifies the integer index of a character to underline in the item. +0 corresponds to the first character of the text displayed in the +widget, 1 to the next character, and so on. +'----------END +.RE +' +\fBSTYLE OPTIONS\fR +.PP +.RS +.PP +\fBSTANDARD OPTIONS\fR +' +.PP +\fC +.ta 6c +.nf +activeBackground activeForeground +anchor background +disabledBackground disabledForeground +foreground font +justify padX +padY selectBackground +selectForeground wrapLength +.fi +\fR +.ta 4c +.PP +See the \fBoptions(n)\fR manual entry for details on the standard +options. +' +' +.PP +.RE +'********************************************************************** +' +' Window +' +'********************************************************************** +.SH WINDOW ITEMS +' +Display items of the type \fBwindow\fR are used to display a +sub-window in a widget. \fBWindow\fR items support the following +options: +' +.PP +\fBITEM OPTIONS\fR +.PP +.RS +'----------BEGIN +.LP +.nf +Name: \fBwindowStyle\fR +Class: \fBWindowStyle\fR +Switch: \fB\-style\fR +.fi +.IP +Specifies the display style to use for this window item. Must be the +name of a \fBwindow\fR display style that has already be created by +the \fBtixDisplayStyle(n)\fR command. +'----------END +' +'----------BEGIN +.LP +.nf +Name: \fBwindow\fR +Class: \fBWindow\fR +Switch: \fB\-window\fR +Alias: \fB\-widget\fR +.fi +.IP +Specifies the sub-window to display in the item. +'----------END +' +.RE +' +\fBSTYLE OPTIONS\fR +.PP +.RS +\fBSTANDARD OPTIONS\fR +' +.PP +\fC +.ta 6c +.nf +anchor +padX padY +.PP +.fi +.ta 4c +See the \fBoptions(n)\fR manual entry for details on the standard +options. +' +.PP +.RE +' +'********************************************************************** +' +.SH CREATING DISPLAY ITEMS +' +' +Display items do not exist on their and thus they cannot be created +independently of the widgets they reside in. As a rule, display items +are created by special widget commands of their "host" widgets. For +example, the HList widgets has a command \fBitem\fR which can be used +to create new display items. The following code creates a new imagetext +item at the third column of the entry foo inside an HList widget: +' +.PP +\fC +.nf + tixHList .h -columns 3 + .h add foo + .h item create foo 2 \-itemtype imagetext \-text Hello \-image image1 +.fi +.PP +\fR +' +The \fBitem create\fR command of the HList widget accepts a variable +number of arguments. The special argument \fB\-itemtype\fR specifies +which type of display item to create. Options that are valid for this +type of display items can then be specified by one or more +\fIoption\-value\fR pairs. +' +.PP +' +After the display item is created, they can then be configured or +destroyed using the commands provided by the host widget. For example, +the HList widget has the command \fBitem configure\fR, \fBitem cget\fR +and \fBitem delete\fR for accessing the display items. +' +'********************************************************************** +' +.SH CREATING AND MANIPULATING DISPLAY STYLES +' +' +Display styles are created by the command \fBtixDisplayStyle\fR: +' +.SH SYNOPSIS +\fBtixDisplayStyle\fI \fIitemType\fR ?\fI\-stylename name\fR? ?\fI\-refwindow pathName\fR? ?\fIoptions value ...\fR? +' +' +.PP +\fIitemType\fR must be one of the existing display items types such as +\fBtext\fR, \fBimagetext\fR, \fBwindow\fR or any new types added by +the user. Additional arguments can be given in one or more +\fIoption\-value\fR pairs. \fIoption\fR can be any of the valid option +for this display style or any of the following: +.PP +.RS +' +.TP +\fB\-stylename \fIname\fR +' +Specifies a name for this style. If unspecified, then a default name +will be chosen for this style. +' +.TP +\fB\-refwindow \fIpathName\fR +' +Specifies a window to use for determine the default values of the +display type. If unspecified, the main window will be used. Default +values for the display types can be set via the options database. The +following example sets the \fB\-disablebackground\fR and +\fB\-disabledforeground\fR options of a \fBtext\fR display style via +the option database: +\fC +.nf +option add *table.list*disabledForeground blue +option add *table.list*disabledBackground darkgray +tixDisplayStyle text -refwindow .table.list -fg red +.fi +\fR +' +By using the option database to set the options of the display styles, +we can advoid hard-coding the option values and give the user more +flexibility in customization. See option(n) for a detailed description +of the option database. +' +.SH STYLE COMMAND +.PP +The \fBtixDisplayStyle\fR command creates a new Tcl command whose name is the +same as the name of the newly created display style. This command +may be used to invoke various operations on the display style. It has the +following general form: +' +' +.DS C +' +\fIstyleName option \fR?\fIarg arg ...\fR? +.PP +.DE +' +\fIstyleName\fR is the name of the command. \fIOption\fR and the +\fIarg\fRs determine the exact behavior of the command. The following +commands are possible: +' +.TP +\fIstyleName \fBcget\fR \fIoption\fR +' +Returns the current value of the configuration option given by +\fIoption\fR. \fIOption\fR may have any of the valid options of this +display style. +' +.TP +' +\fIstyleName \fBconfigure\fR ?\fIoption\fR? \fI?value option value ...\fR? +' +Query or modify the configuration options of the display style. If no +\fIoption\fR is specified, returns a list describing all of the +available options for \fIstyleName\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 option(s) to have the given value(s); in this case +the command returns an empty string. \fIOption\fR may have any of the +valid options of this display style. +' +.TP +\fIstyleName \fBdelete\fR +' +Destroy this display style object. +' +.SH EXAMPLE +' +The following example creates two columns of data in a HList +widget. The first column is in red and the second column in blue. The +colors of the columns are controlled by two different \fBtext\fR +styles. Also, the anchor and font of the second column is chosen so +that the income data is aligned properly. +' +.PP +\fC +.nf +set courier -*-courier-medium-r-*-*-14-*-*-*-*-*-*-* +tixHList .h -columns 2; pack .h +set red [tixDisplayStyle text -fg #800000] +set blue [tixDisplayStyle text -fg #000080 -anchor e -font $courier] + +foreach n {{Joe $10,000} {Peter $20,000} {Raj $90,000} {Zinh $0}} { + set entry [.h addchild {}] + .h item create $entry 0 -itemtype text \\ + -text [lindex $n 0] -style $red + .h item create $entry 1 -itemtype text \\ + -text [lindex $n 1] -style $blue +} +.fi +.PP +\fR + |