tixDisplayStyle(n)					       Tix Built-In Commands						tixDisplayStyle(n)

NAME

       tixDisplayStyle - Create style object for Tix display items.

SYNOPSIS

       tixDisplayStyle itemType ?-stylename name? ?-refwindow pathName? ?options value ...?

DESCRIPTION

       The Tix Display Items mechanism is devised to solve a general problem: many Tix widgets (both existing and planned ones) display many items
       of many types simutaneously.

       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.

       In  these  examples, the display items in different widgets are only different in how they are arranged by the host widget. 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.

       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.

       The appearance of a display item is controlled by a set of attributes. It is observed that each the attributes usually fall into one of two
       categroies:  "individual"  or "collective". For example, the text items inside a HList widget may all display a different text string; how-
       ever, 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 display style. 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.

       The attributes of the a display item are thus stored in two places: it has a set of item options to store its individual  attributes.  Each
       display item is also associated with a display style, which specifies the collective attributes of all items associated with itself.

       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 display styles can be used. For example, suppose you want to display  two  col-
       umns  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".

DISPLAY ITEM TYPES AND OPTIONS

       Currently there are four types of display items: text, image, imagetext and window. (TODO: need to document the "image" item)

IMAGETEXT ITEMS

       Display	items  of  the	type  imagetext  are  used  to display an image together with a text string. Imagetext items support the following
       options:

       ITEM OPTIONS

	      [-bitmap bitmap] Specifies the bitmap to display in the item.  [-image image] Specifies the image to display in the item. When  both
	      the -bitmap and -image options are specified, only the image will be displayed.  [-style imageTextStyle] Specifies the display style
	      to use for this item. Must be the name of a imagetext display style that has already be created by the  tixDisplayStyle(n)  command.
	      [-showimage showImage]  A Boolean value that specifies whether the image/bitmap should be displayed.  [-showtext showText] A Boolean
	      value that specifies whether the text string should be displayed.  [-text text] Specifies the text string to display  in	the  item.
	      [-underline underline] 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.

       STYLE OPTIONS

       The style information of imagetext items are stored in the imagetext display style. The following options are supported:

	      STANDARD OPTIONS

	      activeBackground	      activeForeground
	      anchor		      background
	      disabledBackground      disabledForeground
	      foreground	      font
	      justify		      padX
	      padY		      selectBackground
	      selectForeground	      wrapLength

	      See the options(n) manual entry for details on the standard options.

	      STYLE-SPECIFIC OPTIONS

	      Name:	      gap
	      Class:	      Gap
	      Switch:	      -gap

		     Specifies the distance between the bitmap/image and the text string, in number of pixels.

TEXT ITEMS

       Display items of the type text are used to display a text string in a widget. Text items support the following options:

       ITEM OPTIONS

	      [-style textStyle] Specifies the display style to use for this text item. Must be the name of a text display style that has  already
	      be  created  by  the tixDisplayStyle(n) command.	[-text text] Specifies the text string to display in the item.	[-underline under-
	      line] Specifies the integer index of a character to underline in the item.  0 corresponds to the first character of  the	text  dis-
	      played in the widget, 1 to the next character, and so on.
       STYLE OPTIONS

	      STANDARD OPTIONS

	      activeBackground	      activeForeground
	      anchor		      background
	      disabledBackground      disabledForeground
	      foreground	      font
	      justify		      padX
	      padY		      selectBackground
	      selectForeground	      wrapLength

	      See the options(n) manual entry for details on the standard options.

WINDOW ITEMS

       Display items of the type window are used to display a sub-window in a widget. Window items support the following options:

       ITEM OPTIONS

	      [-style windowStyle]  Specifies  the  display style to use for this window item. Must be the name of a window display style that has
	      already be created by the tixDisplayStyle(n) command.

	      Name:	      window
	      Class:	      Window
	      Switch:	      -window
	      Alias:	      -widget

		     Specifies the sub-window to display in the item.
       STYLE OPTIONS

	      STANDARD OPTIONS

	      anchor
	      padX		      padY

	      See the options(n) manual entry for details on the standard options.

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 item which can be used to cre-
       ate new display items. The following code creates a new imagetext item at the third column of the entry foo inside an HList widget:

	tixHList .h -columns 3
	.h add foo
	.h item create foo 2 -itemtype imagetext -text Hello -image image1

       The item create command of the HList widget accepts a variable number of arguments. The special argument -itemtype 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 option-value pairs.

       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 item configure, item cget and item delete for accessing the display items.

CREATING AND MANIPULATING DISPLAY STYLES

       Display styles are created by the command tixDisplayStyle:

       itemType must be one of the existing display items types such as text, imagetext, window or any new types added	by  the  user.	Additional
       arguments  can  be given in one or more option-value pairs. option can be any of the valid option for this display style or any of the fol-
       lowing:

	      -stylename name
		     Specifies a name for this style. If unspecified, then a default name will be chosen for this style.

	      -refwindow pathName
		     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 -disablebackground
		     and -disabledforeground options of a text display style via the option database:  option  add  *table.list*disabledForeground
		     blue option add *table.list*disabledBackground darkgray tixDisplayStyle text -refwindow .table.list -fg red

	      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.

STYLE COMMAND

       The tixDisplayStyle 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:
	      styleName option ?arg arg ...?
       styleName is the name of the command. Option and the args determine the exact behavior of the command. The following commands are possible:

       styleName cget option
	      Returns  the  current  value  of	the configuration option given by option. Option may have any of the valid options of this display
	      style.

       styleName configure ?option? ?value option value ...?
	      Query or modify the configuration options of the display style.  If no option is specified, returns a list  describing  all  of  the
	      available  options  for  styleName (see Tk_ConfigureInfo for information on the format of this list). If option is specified with no
	      value, 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 option is specified).  If one or more option-value 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. Option may have any of the valid options	of
	      this display style.

       styleName delete
	      Destroy this display style object.

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 text styles. Also, the anchor and font of the second column is chosen  so  that  the  income
       data is aligned properly.

       set courier {courier 14} set h [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}} {
	   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 }

KEYWORDS

       display item, display style, imagetext

Tix									8.0							tixDisplayStyle(n)