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 simul
taneously.

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 list
box 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::Tix
Grid), 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
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 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 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 under
line in the text string in the item. 0 corresponds to
the first character of the text displayed in the wid
get, 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 sup ported:
STANDARD OPTIONS
-activebackground -activeforeground -anchor -back ground -disabledbackground -disabledforeground -fore ground -font -justify -padx -pady -selectback ground -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 under
line in the item. 0 corresponds to the first charac
ter of the text displayed in the widget, 1 to the next
character, and so on.
Text Style Options
STANDARD OPTIONS
-activebackground -activeforeground -anchor -back ground -disabledbackground -disabledforeground -fore ground -font -justify -padx -pady -selectback ground -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 vari able 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 con
figured 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 $wid_
   get will be used. Default values for the display types
   can be set via the options database. The following
   example sets the -disablebackground and -disabledfore
   ground 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 cus
   tomization. See Tk::option for a detailed description
   of the option database.

STYLE METHODS

The ItemStyle method creates an object. This object sup ports 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', -fore; ground=>'#800000');
my $blue = $hlist->ItemStyle('text', -fore; ground=>'#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;

KEYWORDS

display item, display style, item style

docs.sk

komplexný repozitár dokumentácie

V sekcií