Provided by: tix-dev_8.4.3-4ubuntu1_amd64 bug

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;
       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 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 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".

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 underline]  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.
       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  create 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 following:

              -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