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 gen­
       eral 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  dis­
       play  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  usu­
       ally  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.  Sec­
       ond,  when  it  becomes  necessary  to change a collective
       attribute, such as changing all the text items' foreground

       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 associ­
       ated 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 col­
       lective 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

              Command-Line Name:-bitmap
              Database Name:  bitmap
              Database Class: Bitmap

                     Specifies the bitmap to display in the item.

              Command-Line Name:-image
              Database Name:  image
              Database Class: Image

                     Specifies the image to display in the  item.
                     When both the -bitmap and -image options are
                     specified, only the image will be displayed.

              Command-Line Name:-style
              Database Name:  imageTextStyle
              Database Class: ImageTextStyle

                     Specifies  the display style to use for this

                     play  style  that  has already be created by
                     the tixDisplayStyle(n) command.

              Command-Line Name:-showimage
              Database Name:  showImage
              Database Class: ShowImage

                     A Boolean value that specifies  whether  the
                     image/bitmap should be displayed.

              Command-Line Name:-showtext
              Database Name:  showText
              Database Class: ShowText

                     A  Boolean  value that specifies whether the
                     text string should be displayed.

              Command-Line Name:-text
              Database Name:  text
              Database Class: Text

                     Specifies the text string to display in  the
                     item.

              Command-Line Name:-underline
              Database Name:  underline
              Database Class: 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  sup­
       ported:

              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.


              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

              Command-Line Name:-style
              Database Name:  textStyle
              Database Class: TextStyle

                     Specifies the display style to use for  this
                     text  item.  Must be the name of a text dis­
                     play style that has already  be  created  by
                     the tixDisplayStyle(n) command.

              Command-Line Name:-text
              Database Name:  text
              Database Class: Text

                     Specifies  the text string to display in the
                     item.

              Command-Line Name:-underline
              Database Name:  underline
              Database Class: 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

              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

              Command-Line Name:-style
              Database Name:  windowStyle
              Database Class: 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.

              Command-Line Name:-window or -widget
              Database Name:  window
              Database Class: Window

                     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  com­
       mands of their "host" widgets. For example, the HList wid­
       gets 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

       variable number of arguments. The special argument  -item­
       type  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 con­
       figured 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 unspeci­
                     fied, 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  dis­
                     play 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

       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


Man(1) output converted with man2html