Provided by: perl-tk_804.031-1build1_amd64 bug

NAME

       Tk::DItem - Tix Display Items

SYNOPSIS

DESCRIPTION

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

       For example, a hierarchical listbox widget (see Tk::HList) can display items of images,
       plain text and subwindows in the form of a hierarchy. Another widget, the tabular listbox
       widget (see Tk::TList) also displays items of the same types, although it arranges the
       items in a tabular form. Yet another widget, the spreadsheet widget (see Tk::TixGrid),
       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 three types of display items: text, imagetext and window.

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:

   Imagetext Item Options
       Name:     bitmap
       Class:    Bitmap
       Switch:   -bitmap
           Specifies the bitmap to display in the item.

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

       Name:     imageTextStyle
       Class:    ImageTextStyle
       Switch:   -style
           Specifies the display style to use for this item. Must be the name of a imagetext
           display style that has already be created with ItemStyle.

       Name:     showImage
       Class:    ShowImage
       Switch:   -showimage
           A Boolean value that specifies whether the image/bitmap should be displayed.

       Name:     showText
       Class:    ShowText
       Switch:   -showtext
           A Boolean value that specifies whether the text string should be displayed.

       Name:     text
       Class:    Text
       Switch:   -text
           Specifies the text string to display in the item.

       Name:     underline
       Class:    Underline
       Switch:   -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.

   Imagetext 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 Tk::options for details of 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.

       Name:     textAnchor
       Class:    TextAnchor
       Switch:   -textanchor
           The anchor position on the image to which text part is attached.  This is a perl/Tk
           addition. Defaults to e for compatibility with standard Tix. The interesting cases are

           n       Text is centred above the image.

           s       Text is centred below the image

           e       Text is centred to right of the image.

           w       Text is centred to left of the image.

           c       Text is centred over the image.

           The sw, se, ne, and b<nw> cases look rather odd.

           To get items to line up correctly it will usually be necessary to specify -anchor as
           well. e.g. with default e then anchoring item as a whole w lines images up down left
           with text stuck to right side.

TEXT ITEMS

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

   Text Item Options
       Name:     textStyle
       Class:    TextStyle
       Switch:   -style
           Specifies the display style to use for this text item. Must be the name of a text
           display style that has already be created with ItemStyle.

       Name:     text
       Class:    Text
       Switch:   -text
           Specifies the text string to display in the item.

       Name:     underline
       Class:    Underline
       Switch:   -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.

   Text Style Options
       STANDARD OPTIONS

       -activebackground   -activeforeground -anchor   -background
       -disabledbackground -disabledforeground -foreground    -font -justify  -padx
       -pady     -selectbackground -selectforeground   -wraplength

       See Tk::options for details of 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:

   Window Item Options
       Name:     windowStyle
       Class:    WindowStyle
       Switch:   -style
           Specifies the display style to use for this window item. Must be the name of a window
           display style that has already be created with the ItemStyle method.

       Name:     window
       Class:    Window
       Switch:   -window
       Alias:    -widget
           Specifies the sub-window to display in the item.

   Window Style Options
       STYLE STANDARD OPTIONS

       -anchor   -padx     -pady

       See Tk::options for details of 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 methods of their
       ``host'' widgets. For example, the HList widgets has a method item which can be used to
       create new display items. The following code creates a new text item at the third column
       of the entry foo inside an HList widget:

        my $hlist = $parent->HList(-columns=>3);
        $hlist->add('foo');
        $hlist->itemCreate('foo', 2, -itemtype=>'text', -text=>'Hello');

       The itemCreate method 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
       methods provided by the host widget. For example, the HList widget has the methods
       itemConfigure, itemCget and itemDelete for accessing the display items.

CREATING AND MANIPULATING ITEM STYLES

       Item styles are created with ItemStyle:

SYNOPSIS

          $widget->ItemStyle(itemType ?,-stylename=>name? ?,-refwindow=>pathName?
       ?,option=>value, ...>?);

       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 => $otherwidget
           Specifies a window to use for determine the default values of the display type. If
           unspecified, the $widget 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:

             $widget->optionAdd('*table.list*disabledForeground' => 'blue');
             $widget->optionAdd('*table.list*disabledBackground' => 'darkgray');
             $widget->ItemStyle('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
           Tk::option for a detailed description of the option database.

STYLE METHODS

       The ItemStyle method creates an object.  This object supports the configure and cget
       methods described in Tk::options which can be used to enquire and modify the options
       described above.

       The following additional methods are available for item styles:

       $style->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.

          use strict;
          use Tk;
          use Tk::HList;
          use Tk::ItemStyle;

          my $mw = MainWindow->new();

          my $hlist = $mw->HList(-columns=>2)->pack;

          my $red  = $hlist->ItemStyle('text', -foreground=>'#800000');
          my $blue = $hlist->ItemStyle('text', -foreground=>'#000080', -anchor=>'e');

          my $e;
          foreach ([Joe => '$10,000'], [Peter => '$20,000'],
                   [Raj => '$90,000'],  [Zinh => '$0']) {
              $e = $hlist->addchild("");
              $hlist->itemCreate($e, 0, -itemtype=>'text',
                       -text=>$_->[0], -style=>$red );
              $hlist->itemCreate($e, 1, -itemtype=>'text',
                       -text=>$_->[1], -style=>$blue);
          }

          Tk::MainLoop;

SEE ALSO

       Tk::HList Tk::TixGrid Tk::TList

KEYWORDS

       display item, display style, item style