DItem(3) User Contributed Perl Documentation DItem(3)
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
perl v5.18.0 2010-05-29 DItem(3)
perl-Tk 804.030_502 - Generated Mon Aug 12 16:48:22 CDT 2013