summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Tk/DItem.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/DItem.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/DItem.pod439
1 files changed, 439 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/DItem.pod b/Master/tlpkg/tlperl/lib/Tk/DItem.pod
new file mode 100644
index 00000000000..27db79744df
--- /dev/null
+++ b/Master/tlpkg/tlperl/lib/Tk/DItem.pod
@@ -0,0 +1,439 @@
+=head1 NAME
+
+Tk::DItem - Tix Display Items
+
+=for category Tix Extensions
+
+=head1 SYNOPSIS
+
+=head1 DESCRIPTION
+
+The Tix B<Display Items> and B<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 L<Tk::HList>) can display
+items
+of images, plain text and subwindows in the form of a
+hierarchy. Another widget, the tabular listbox widget (see L<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 L<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 B<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
+I<attributes>. It is observed that each the attributes usually fall
+into one of two categroies: ``I<individual>'' or
+``I<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 B<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 B<item options> to store its individual attributes. Each
+display item is also associated with a I<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 B<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''
+
+=head1 DISPLAY ITEM TYPES AND OPTIONS
+
+Currently there are three types of display items: B<text>,
+B<imagetext> and I<window>.
+
+=head1 IMAGETEXT ITEMS
+
+Display items of the type B<imagetext> are used to display an image
+together with a text string. Imagetext items support the following options:
+
+=head2 Imagetext Item Options
+
+=over 4
+
+=item Name: B<bitmap>
+
+=item Class: B<Bitmap>
+
+=item Switch: B<-bitmap>
+
+Specifies the bitmap to display in the item.
+
+=item Name: B<image>
+
+=item Class: B<Image>
+
+=item Switch: B<-image>
+
+Specifies the image to display in the item. When both the
+B<-bitmap> and B<-image> options are specified, only the image
+will be displayed.
+
+=item Name: B<imageTextStyle>
+
+=item Class: B<ImageTextStyle>
+
+=item Switch: B<-style>
+
+Specifies the display style to use for this item. Must be the
+name of a B<imagetext> display style that has already be created with
+B<ItemStyle>.
+
+=item Name: B<showImage>
+
+=item Class: B<ShowImage>
+
+=item Switch: B<-showimage>
+
+A Boolean value that specifies whether the image/bitmap should be
+displayed.
+
+=item Name: B<showText>
+
+=item Class: B<ShowText>
+
+=item Switch: B<-showtext>
+
+A Boolean value that specifies whether the text string should be
+displayed.
+
+=item Name: B<text>
+
+=item Class: B<Text>
+
+=item Switch: B<-text>
+
+Specifies the text string to display in the item.
+
+=item Name: B<underline>
+
+=item Class: B<Underline>
+
+=item Switch: B<-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.
+
+=back
+
+=head2 Imagetext Style Options
+
+The style information of B<imagetext> items are stored in the
+B<imagetext> display style. The following options are supported:
+
+B<STANDARD OPTIONS>
+
+B<-activebackground> B<-activeforeground>
+B<-anchor> B<-background>
+B<-disabledbackground> B<-disabledforeground>
+B<-foreground> B<-font>
+B<-justify> B<-padx>
+B<-pady> B<-selectbackground>
+B<-selectforeground> B<-wraplength>
+
+See L<Tk::options> for details of the standard options.
+
+B<STYLE-SPECIFIC OPTIONS>
+
+=over 4
+
+=item Name: B<gap>
+
+=item Class: B<Gap>
+
+=item Switch: B<-gap>
+
+Specifies the distance between the bitmap/image and the text string,
+in number of pixels.
+
+=item Name: B<textAnchor>
+
+=item Class: B<TextAnchor>
+
+=item Switch: B<-textanchor>
+
+The anchor position on the image to which text part is attached.
+This is a perl/Tk addition. Defaults to B<e> for compatibility with standard
+Tix. The interesting cases are
+
+=over 8
+
+=item B<n>
+
+Text is centred above the image.
+
+=item B<s>
+
+Text is centred below the image
+
+=item B<e>
+
+Text is centred to right of the image.
+
+=item B<w>
+
+Text is centred to left of the image.
+
+=item B<c>
+
+Text is centred over the image.
+
+=back
+
+The B<sw>, B<se>, B<ne>, and b<nw> cases look rather odd.
+
+To get items to line up correctly it will usually be necessary
+to specify B<-anchor> as well. e.g. with default B<e> then anchoring
+item as a whole B<w> lines images up down left with text stuck to right side.
+
+=back
+
+=head1 TEXT ITEMS
+
+Display items of the type B<text> are used to display a text string
+in a widget. Text items support the following options:
+
+=head2 Text Item Options
+
+=over 4
+
+=item Name: B<textStyle>
+
+=item Class: B<TextStyle>
+
+=item Switch: B<-style>
+
+Specifies the display style to use for this text item. Must be the
+name of a B<text> display style that has already be created with
+B<ItemStyle>.
+
+=item Name: B<text>
+
+=item Class: B<Text>
+
+=item Switch: B<-text>
+
+Specifies the text string to display in the item.
+
+=item Name: B<underline>
+
+=item Class: B<Underline>
+
+=item Switch: B<-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.
+
+=back
+
+=head2 Text Style Options
+
+B<STANDARD OPTIONS>
+
+B<-activebackground> B<-activeforeground>
+B<-anchor> B<-background>
+B<-disabledbackground> B<-disabledforeground>
+B<-foreground> B<-font>
+B<-justify> B<-padx>
+B<-pady> B<-selectbackground>
+B<-selectforeground> B<-wraplength>
+
+See L<Tk::options> for details of the standard options.
+
+=head1 WINDOW ITEMS
+
+Display items of the type I<window> are used to display a
+sub-window in a widget. B<Window> items support the following
+options:
+
+=head2 Window Item Options
+
+=over 4
+
+=item Name: B<windowStyle>
+
+=item Class: B<WindowStyle>
+
+=item Switch: B<-style>
+
+Specifies the display style to use for this window item. Must be the
+name of a I<window> display style that has already be created with
+the B<ItemStyle> method.
+
+=item Name: B<window>
+
+=item Class: B<Window>
+
+=item Switch: B<-window>
+
+=item Alias: B<-widget>
+
+Specifies the sub-window to display in the item.
+
+=back
+
+=head2 Window Style Options
+
+B<STYLE STANDARD OPTIONS>
+
+B<-anchor> B<-padx> B<-pady>
+
+See L<Tk::options> for details of the standard options.
+
+=head1 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 B<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 B<itemCreate> method of the HList widget accepts a variable
+number of arguments. The special argument B<-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
+I<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 B<itemConfigure>, B<itemCget>
+and B<itemDelete> for accessing the display items.
+
+=head1 CREATING AND MANIPULATING ITEM STYLES
+
+Item styles are created with B<ItemStyle>:
+
+=head1 SYNOPSIS
+
+S< >I<$widget>-E<gt>B<ItemStyle>(I<itemType> ?,B<-stylename>=E<gt>I<name>? ?,B<-refwindow>=E<gt>I<pathName>? ?,I<option>=E<gt>I<value>, ...>?);
+
+I<itemType> must be one of the existing display items types such as
+B<text>, B<imagetext>, B<window> or any new types added by
+the user. Additional arguments can be given in one or more
+I<option-value> pairs. I<option> can be any of the valid option
+for this display style or any of the following:
+
+=over 4
+
+=item B<-stylename> =E<gt> I<name>
+
+Specifies a name for this style. If unspecified, then a default name
+will be chosen for this style.
+
+=item B<-refwindow> =E<gt> I<$otherwidget>
+
+Specifies a window to use for determine the default values of the
+display type. If unspecified, the I<$widget> will be used. Default
+values for the display types can be set via the options database. The
+following example sets the B<-disablebackground> and
+B<-disabledforeground> options of a B<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 L<Tk::option> for a detailed description
+of the option database.
+
+=back
+
+=head1 STYLE METHODS
+
+The B<ItemStyle> method creates an object.
+This object supports the B<configure> and B<cget> methods
+described in L<Tk::options> which can be used to enquire and
+modify the options described above.
+
+The following additional methods are available for item styles:
+
+=over 4
+
+=item I<$style>-E<gt>B<delete>
+
+Destroy this display style object.
+
+=back
+
+=head1 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 B<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;
+
+=head1 SEE ALSO
+
+L<Tk::HList|Tk::HList>
+L<Tk::TixGrid|Tk::TixGrid>
+L<Tk::TList|Tk::TList>
+
+=head1 KEYWORDS
+
+display item, display style, item style
+
+=cut
+