URL
https://opencores.org/ocsvn/or1k/or1k/trunk
Subversion Repositories or1k
[/] [or1k/] [trunk/] [insight/] [tix/] [man/] [DItem.html] - Rev 1774
Go to most recent revision | Compare with Previous | Blame | View Log
<TITLE>Tix Display Items</TITLE> <Center><H2>Tix Display Items</H2></Center><hr> </pre><HR> </pre><H3>DESCRIPTION</H3> The Tix <B>Display Items</B></I> and <B>Display Types</B></I> are devised to solve a general problem: many Tix widgets (both existing and planned ones) display many items of many types simutaneously. <P> 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. <P> In these examples, the display items in different widgets are only different in how they are arranged by the <B>host widget</B></I>. 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. <P> 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. <P> The appearance of a display item is controlled by a set of <I>attributes</I></B>. It is observed that each the attributes usually fall into one of two categroies: "<I>individual</I></B>" or "<I>collective</I></B>". 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 <B>display style</B></I>. 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 change only the display style object than to modify all the text items one by one. <P> The attributes of the a display item are thus stored in two places: it has a set of <B>item options</B></I> to store its individual attributes. Each display item is also associated with a <I>display style</I></B>, which specifies the collective attributes of all items associated with itself. <P> 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 <B>display styles</B></I> 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". </pre><H3>DISPLAY ITEM TYPES AND OPTIONS</H3> Currently there are three types of display items: <B>text</B></I>, <B>imagetext</B></I> and <B>window</B></I>. </pre><H3>IMAGETEXT ITEMS</H3> Display items of the type <B>imagetext</B></I> are used to display an image together with a text string. Imagetext items support the following options: <P> <B>ITEM OPTIONS</B></I> <P> <UL> <P> <pre><code><code><code> Name: <B>bitmap</B></I> Class: <B>Bitmap</B></I> Switch: <B>-bitmap</B></I> </code></code></code></pre> <UL> Specifies the bitmap to display in the item. </UL> <P> <pre><code><code><code> Name: <B>image</B></I> Class: <B>Image</B></I> Switch: <B>-image</B></I> </code></code></code></pre> <UL> Specifies the image to display in the item. When both the <B>-bitmap</B></I> and <B>-image</B></I> options are specified, only the image will be displayed. </UL> <P> <pre><code><code><code> Name: <B>imageTextStyle</B></I> Class: <B>ImageTextStyle</B></I> Switch: <B>-style</B></I> </code></code></code></pre> <UL> Specifies the display style to use for this item. Must be the name of a <B>imagetext</B></I> display style that has already be created by the <B>tixDisplayStyle(n)</B></I> command. </UL> <P> <pre><code><code><code> Name: <B>showImage</B></I> Class: <B>ShowImage</B></I> Switch: <B>-showimage</B></I> </code></code></code></pre> <UL> A Boolean value that specifies whether the image/bitmap should be displayed. </UL> <P> <pre><code><code><code> Name: <B>showText</B></I> Class: <B>ShowText</B></I> Switch: <B>-showtext</B></I> </code></code></code></pre> <UL> A Boolean value that specifies whether the text string should be displayed. </UL> <P> <pre><code><code><code> Name: <B>text</B></I> Class: <B>Text</B></I> Switch: <B>-text</B></I> </code></code></code></pre> <UL> Specifies the text string to display in the item. </UL> <P> <pre><code><code><code> Name: <B>underline</B></I> Class: <B>Underline</B></I> Switch: <B>-underline</B></I> </code></code></code></pre> <UL> 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. </UL> </UL> <P> <B>STYLE OPTIONS</B></I> <P> The style information of <B>imagetext</B></I> items are stored in the <B>imagetext</B></I> display style. The following options are supported: <UL> <P> <B>STANDARD OPTIONS</B></I> <P> \fC <pre><code><code><code> activeBackground activeForeground anchor background disabledBackground disabledForeground foreground font justify padX padY selectBackground selectForeground wrapLength </code></code></code></pre> </B></I> <P> See the <B>options(n)</B></I> manual entry for details on the standard options. <P> <P> <B>STYLE-SPECIFIC OPTIONS</B></I> <P> <P> <pre><code><code><code> Name: <B>gap</B></I> Class: <B>Gap</B></I> Switch: <B>-gap</B></I> </code></code></code></pre> <UL> Specifies the distance between the bitmap/image and the text string, in number of pixels. </UL> </UL> </pre><H3>TEXT ITEMS</H3> Display items of the type <B>text</B></I> are used to display a text string in a widget. Text items support the following options: <P> <B>ITEM OPTIONS</B></I> <P> <UL> <P> <pre><code><code><code> Name: <B>textStyle</B></I> Class: <B>TextStyle</B></I> Switch: <B>-style</B></I> </code></code></code></pre> <UL> Specifies the display style to use for this text item. Must be the name of a <B>text</B></I> display style that has already be created by the <B>tixDisplayStyle(n)</B></I> command. </UL> <P> <pre><code><code><code> Name: <B>text</B></I> Class: <B>Text</B></I> Switch: <B>-text</B></I> </code></code></code></pre> <UL> Specifies the text string to display in the item. </UL> <P> <pre><code><code><code> Name: <B>underline</B></I> Class: <B>Underline</B></I> Switch: <B>-underline</B></I> </code></code></code></pre> <UL> 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. </UL> </UL> <B>STYLE OPTIONS</B></I> <P> <UL> <P> <B>STANDARD OPTIONS</B></I> <P> \fC <pre><code><code><code> activeBackground activeForeground anchor background disabledBackground disabledForeground foreground font justify padX padY selectBackground selectForeground wrapLength </code></code></code></pre> </B></I> <P> See the <B>options(n)</B></I> manual entry for details on the standard options. <P> </UL> </pre><H3>WINDOW ITEMS</H3> Display items of the type <B>window</B></I> are used to display a sub-window in a widget. <B>Window</B></I> items support the following options: <P> <B>ITEM OPTIONS</B></I> <P> <UL> <P> <pre><code><code><code> Name: <B>windowStyle</B></I> Class: <B>WindowStyle</B></I> Switch: <B>-style</B></I> </code></code></code></pre> <UL> Specifies the display style to use for this window item. Must be the name of a <B>window</B></I> display style that has already be created by the <B>tixDisplayStyle(n)</B></I> command. </UL> <P> <pre><code><code><code> Name: <B>window</B></I> Class: <B>Window</B></I> Switch: <B>-window</B></I> Alias: <B>-widget</B></I> </code></code></code></pre> <UL> Specifies the sub-window to display in the item. </UL> </UL> <B>STYLE OPTIONS</B></I> <P> <UL> <B>STANDARD OPTIONS</B></I> <P> \fC <pre><code><code><code> anchor padX padY <P> </code></code></code></pre> See the <B>options(n)</B></I> manual entry for details on the standard options. <P> </UL> </pre><H3>CREATING DISPLAY ITEMS</H3> 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 <B>item</B></I> 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: <P> \fC <pre><code><code><code> tixHList .h -columns 3 .h add foo .h item create foo 2 -itemtype imagetext -text Hello -image image1 </code></code></code></pre> <P> </B></I> The <B>item create</B></I> command of the HList widget accepts a variable number of arguments. The special argument <B>-itemtype</B></I> 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 <I>option-value</I></B> pairs. <P> 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 <B>item configure</B></I>, <B>item cget</B></I> and <B>item delete</B></I> for accessing the display items. </pre><H3>CREATING AND MANIPULATING DISPLAY STYLES</H3> Display styles are created by the command <B>tixDisplayStyle</B></I>: </pre><H3>SYNOPSIS</H3> <B>tixDisplayStyle<I> <I>itemType</I></B> ?<I>-stylename name</I></B>? ?<I>-refwindow pathName</I></B>? ?<I>options value ...</I></B>? <P> <I>itemType</I></B> must be one of the existing display items types such as <B>text</B></I>, <B>imagetext</B></I>, <B>window</B></I> or any new types added by the user. Additional arguments can be given in one or more <I>option-value</I></B> pairs. <I>option</I></B> can be any of the valid option for this display style or any of the following: <P> <UL> <DL> <DT> <B>-stylename <I>name</I></B> </I></B> <DD> Specifies a name for this style. If unspecified, then a default name will be chosen for this style. </DL> <DL> <DT> <B>-refwindow <I>pathName</I></B> </I></B> <DD> 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 <B>-disablebackground</B></I> and <B>-disabledforeground</B></I> options of a <B>text</B></I> display style via the option database: \fC </DL> <pre><code><code><code> option add *table.list*disabledForeground blue option add *table.list*disabledBackground darkgray tixDisplayStyle text -refwindow .table.list -fg red </code></code></code></pre> </B></I> 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. </pre><H3>STYLE COMMAND</H3> <P> The <B>tixDisplayStyle</B></I> 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: <pre> <I>styleName option </I></B>?<I>arg arg ...</I></B>? <P> </pre> <I>styleName</I></B> is the name of the command. <I>Option</I></B> and the <I>arg</I></B>s determine the exact behavior of the command. The following commands are possible: <DL> <DT> <I>styleName <B>cget</B></I> <I>option</I></B> </I></B> <DD> Returns the current value of the configuration option given by <I>option</I></B>. <I>Option</I></B> may have any of the valid options of this display style. </DL> <DL> <DT> <I>styleName <B>configure</B></I> ?<I>option</I></B>? <I>?value option value ...</I></B>? </I></B> <DD> Query or modify the configuration options of the display style. If no <I>option</I></B> is specified, returns a list describing all of the available options for <I>styleName</I></B> (see <B>Tk_ConfigureInfo</B></I> for information on the format of this list). If <I>option</I></B> is specified with no <I>value</I></B>, 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 <I>option</I></B> is specified). If one or more <I>option-value</I></B> 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. <I>Option</I></B> may have any of the valid options of this display style. </DL> <DL> <DT> <I>styleName <B>delete</B></I> </I></B> <DD> Destroy this display style object. </DL> </pre><H3>EXAMPLE</H3> 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 <B>text</B></I> styles. Also, the anchor and font of the second column is chosen so that the income data is aligned properly. <P> \fC <pre><code><code><code> 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 } </code></code></code></pre> <P> </B></I> <hr><i>Last modified Sun Jan 19 22:34:21 EST 1997 </i> --- <i>Serial 853731297</i>
Go to most recent revision | Compare with Previous | Blame | View Log