Initial commit of OpenSPARC T2 design and verification files.

[OpenSPARC-T2-DV] / tools / perl-5.8.0 / man / man3 / Tk::DItem.3

.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "DITEM 1"
.TH DITEM 1 "2000-12-30" "perl v5.8.0" "User Contributed Perl Documentation"
.SH "NAME"
Tk::DItem \- Tix Display Items
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The Tix \fBDisplay Items\fR and \fBDisplay Types\fR are devised to
solve a general problem: many Tix widgets (both existing and planned
ones) display many items of many types simultaneously.
.PP
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.
.PP
In these examples, the display items in different widgets are only
different in how they are arranged by the \fBhost widget\fR. 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.
.PP
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 \s-1TK\s0 widgets.
.PP
The appearance of a display item is controlled by a set of
\&\fIattributes\fR. It is observed that each the attributes usually fall
into one of two categroies: ``\fIindividual\fR'' or
``\fIcollective\fR''. 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 \fBdisplay style\fR. 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.
.PP
The attributes of the a display item are thus stored in two places: it
has a set of \fBitem options\fR to store its individual attributes. Each
display item is also associated with a \fIdisplay style\fR, which specifies
the collective attributes of all items associated with itself.
.PP
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 \fBdisplay styles\fR
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''
.SH "DISPLAY ITEM TYPES AND OPTIONS"
.IX Header "DISPLAY ITEM TYPES AND OPTIONS"
Currently there are three types of display items: \fBtext\fR,
\&\fBimagetext\fR and \fIwindow\fR.
.SH "IMAGETEXT ITEMS"
.IX Header "IMAGETEXT ITEMS"
Display items of the type \fBimagetext\fR are used to display an image
together with a text string. Imagetext items support the following options:
.Sh "Imagetext Item Options"
.IX Subsection "Imagetext Item Options"
.IP "Name:	\fBbitmap\fR" 4
.IX Item "Name:	bitmap"
.PD 0
.IP "Class:	\fBBitmap\fR" 4
.IX Item "Class:	Bitmap"
.IP "Switch:	\fB\-bitmap\fR" 4
.IX Item "Switch:	-bitmap"
.PD
Specifies the bitmap to display in the item.
.IP "Name:	\fBimage\fR" 4
.IX Item "Name:	image"
.PD 0
.IP "Class:	\fBImage\fR" 4
.IX Item "Class:	Image"
.IP "Switch:	\fB\-image\fR" 4
.IX Item "Switch:	-image"
.PD
Specifies the image to display in the item. When both the
\&\fB\-bitmap\fR and \fB\-image\fR options are specified, only the image
will be displayed.
.IP "Name:	\fBimageTextStyle\fR" 4
.IX Item "Name:	imageTextStyle"
.PD 0
.IP "Class:	\fBImageTextStyle\fR" 4
.IX Item "Class:	ImageTextStyle"
.IP "Switch:	\fB\-style\fR" 4
.IX Item "Switch:	-style"
.PD
Specifies the display style to use for this item. Must be the
name of a \fBimagetext\fR display style that has already be created with
\&\fBItemStyle\fR.
.IP "Name:	\fBshowImage\fR" 4
.IX Item "Name:	showImage"
.PD 0
.IP "Class:	\fBShowImage\fR" 4
.IX Item "Class:	ShowImage"
.IP "Switch:	\fB\-showimage\fR" 4
.IX Item "Switch:	-showimage"
.PD
A Boolean value that specifies whether the image/bitmap should be
displayed.
.IP "Name:	\fBshowText\fR" 4
.IX Item "Name:	showText"
.PD 0
.IP "Class:	\fBShowText\fR" 4
.IX Item "Class:	ShowText"
.IP "Switch:	\fB\-showtext\fR" 4
.IX Item "Switch:	-showtext"
.PD
A Boolean value that specifies whether the text string should be
displayed.
.IP "Name:	\fBtext\fR" 4
.IX Item "Name:	text"
.PD 0
.IP "Class:	\fBText\fR" 4
.IX Item "Class:	Text"
.IP "Switch:	\fB\-text\fR" 4
.IX Item "Switch:	-text"
.PD
Specifies the text string to display in the item.
.IP "Name:	\fBunderline\fR" 4
.IX Item "Name:	underline"
.PD 0
.IP "Class:	\fBUnderline\fR" 4
.IX Item "Class:	Underline"
.IP "Switch:	\fB\-underline\fR" 4
.IX Item "Switch:	-underline"
.PD
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.
.Sh "Imagetext Style Options"
.IX Subsection "Imagetext Style Options"
The style information of \fBimagetext\fR items are stored in the
\&\fBimagetext\fR display style. The following options are supported:
.PP
\&\fB\s-1STANDARD\s0 \s-1OPTIONS\s0\fR
.PP
\&\fB\-activebackground\fR	\fB\-activeforeground\fR
\&\fB\-anchor\fR	\fB\-background\fR
\&\fB\-disabledbackground\fR	\fB\-disabledforeground\fR
\&\fB\-foreground\fR	\fB\-font\fR
\&\fB\-justify\fR	\fB\-padx\fR
\&\fB\-pady\fR	\fB\-selectbackground\fR
\&\fB\-selectforeground\fR	\fB\-wraplength\fR
.PP
See Tk::options for details of the standard options.
.PP
\&\fBSTYLE-SPECIFIC \s-1OPTIONS\s0\fR
.IP "Name:	\fBgap\fR" 4
.IX Item "Name:	gap"
.PD 0
.IP "Class:	\fBGap\fR" 4
.IX Item "Class:	Gap"
.IP "Switch:	\fB\-gap\fR" 4
.IX Item "Switch:	-gap"
.PD
Specifies the distance between the bitmap/image and the text string,
in number of pixels.
.IP "Name:	\fBtextAnchor\fR" 4
.IX Item "Name:	textAnchor"
.PD 0
.IP "Class:	\fBTextAnchor\fR" 4
.IX Item "Class:	TextAnchor"
.IP "Switch:	\fB\-textanchor\fR" 4
.IX Item "Switch:	-textanchor"
.PD
The anchor position on the image to which text part is attached.
This is a perl/Tk addition. Defaults to \fBe\fR for compatibility with standard
Tix. The interesting cases are
.RS 4
.IP "\fBn\fR" 8
.IX Item "n"
Text is centred above the image.
.IP "\fBs\fR" 8
.IX Item "s"
Text is centred below the image
.IP "\fBe\fR" 8
.IX Item "e"
Text is centred to right of the image.
.IP "\fBw\fR" 8
.IX Item "w"
Text is centred to left of the image.
.IP "\fBc\fR" 8
.IX Item "c"
Text is centred over the image.
.RE
.RS 4
.Sp
The \fBsw\fR, \fBse\fR, \fBne\fR, and b<nw> cases look rather odd.
.Sp
To get items to line up correctly it will usually be necessary
to specify \fB\-anchor\fR as well. e.g. with default \fBe\fR then anchoring
item as a whole \fBw\fR lines images up down left with text stuck to right side.
.RE
.SH "TEXT ITEMS"
.IX Header "TEXT ITEMS"
Display items of the type \fBtext\fR are used to display a text string
in a widget. Text items support the following options:
.Sh "Text Item Options"
.IX Subsection "Text Item Options"
.IP "Name:	\fBtextStyle\fR" 4
.IX Item "Name:	textStyle"
.PD 0
.IP "Class:	\fBTextStyle\fR" 4
.IX Item "Class:	TextStyle"
.IP "Switch:	\fB\-style\fR" 4
.IX Item "Switch:	-style"
.PD
Specifies the display style to use for this text item. Must be the
name of a \fBtext\fR display style that has already be created with
\&\fBItemStyle\fR.
.IP "Name:	\fBtext\fR" 4
.IX Item "Name:	text"
.PD 0
.IP "Class:	\fBText\fR" 4
.IX Item "Class:	Text"
.IP "Switch:	\fB\-text\fR" 4
.IX Item "Switch:	-text"
.PD
Specifies the text string to display in the item.
.IP "Name:	\fBunderline\fR" 4
.IX Item "Name:	underline"
.PD 0
.IP "Class:	\fBUnderline\fR" 4
.IX Item "Class:	Underline"
.IP "Switch:	\fB\-underline\fR" 4
.IX Item "Switch:	-underline"
.PD
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.
.Sh "Text Style Options"
.IX Subsection "Text Style Options"
\&\fB\s-1STANDARD\s0 \s-1OPTIONS\s0\fR
.PP
\&\fB\-activebackground\fR	\fB\-activeforeground\fR
\&\fB\-anchor\fR	\fB\-background\fR
\&\fB\-disabledbackground\fR	\fB\-disabledforeground\fR
\&\fB\-foreground\fR	\fB\-font\fR
\&\fB\-justify\fR	\fB\-padx\fR
\&\fB\-pady\fR	\fB\-selectbackground\fR
\&\fB\-selectforeground\fR	\fB\-wraplength\fR
.PP
See Tk::options for details of the standard options.
.SH "WINDOW ITEMS"
.IX Header "WINDOW ITEMS"
Display items of the type \fIwindow\fR are used to display a
sub-window in a widget. \fBWindow\fR items support the following
options:
.Sh "Window Item Options"
.IX Subsection "Window Item Options"
.IP "Name:	\fBwindowStyle\fR" 4
.IX Item "Name:	windowStyle"
.PD 0
.IP "Class:	\fBWindowStyle\fR" 4
.IX Item "Class:	WindowStyle"
.IP "Switch:	\fB\-style\fR" 4
.IX Item "Switch:	-style"
.PD
Specifies the display style to use for this window item. Must be the
name of a \fIwindow\fR display style that has already be created with
the \fBItemStyle\fR method.
.IP "Name:	\fBwindow\fR" 4
.IX Item "Name:	window"
.PD 0
.IP "Class:	\fBWindow\fR" 4
.IX Item "Class:	Window"
.IP "Switch:	\fB\-window\fR" 4
.IX Item "Switch:	-window"
.IP "Alias:	\fB\-widget\fR" 4
.IX Item "Alias:	-widget"
.PD
Specifies the sub-window to display in the item.
.Sh "Window Style Options"
.IX Subsection "Window Style Options"
\&\fB\s-1STYLE\s0 \s-1STANDARD\s0 \s-1OPTIONS\s0\fR
.PP
\&\fB\-anchor\fR	\fB\-padx\fR	\fB\-pady\fR
.PP
See Tk::options for details of the standard options.
.SH "CREATING DISPLAY ITEMS"
.IX Header "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 \fBitem\fR 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:
.PP
.Vb 3
\& my $hlist = $parent->HList(-columns=>3);
\& $hlist->add('foo');
\& $hlist->itemCreate('foo', 2, -itemtype=>'text', -text=>'Hello');
.Ve
.PP
The \fBitemCreate\fR method of the HList widget accepts a variable
number of arguments. The special argument \fB\-itemtype\fR 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
\&\fIoption-value\fR pairs.
.PP
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 \fBitemConfigure\fR, \fBitemCget\fR
and \fBitemDelete\fR for accessing the display items.
.SH "CREATING AND MANIPULATING ITEM STYLES"
.IX Header "CREATING AND MANIPULATING ITEM STYLES"
Item styles are created with \fBItemStyle\fR:
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\ \fI$widget\fR\->\fBItemStyle\fR(\fIitemType\fR ?,\fB\-stylename\fR=>\fIname\fR? ?,\fB\-refwindow\fR=>\fIpathName\fR? ?,\fIoption\fR=>\fIvalue\fR, ...>?);
.PP
\&\fIitemType\fR must be one of the existing display items types such as
\&\fBtext\fR, \fBimagetext\fR, \fBwindow\fR or any new types added by
the user. Additional arguments can be given in one or more
\&\fIoption-value\fR pairs. \fIoption\fR can be any of the valid option
for this display style or any of the following:
.IP "\fB\-stylename\fR => \fIname\fR" 4
.IX Item "-stylename => name"
Specifies a name for this style. If unspecified, then a default name
will be chosen for this style.
.IP "\fB\-refwindow\fR => \fI$otherwidget\fR" 4
.IX Item "-refwindow => $otherwidget"
Specifies a window to use for determine the default values of the
display type. If unspecified, the \fI$widget\fR will be used. Default
values for the display types can be set via the options database. The
following example sets the \fB\-disablebackground\fR and
\&\fB\-disabledforeground\fR options of a \fBtext\fR display style via
the option database:
.Sp
.Vb 3
\&  $widget->optionAdd('*table.list*disabledForeground' => 'blue');
\&  $widget->optionAdd('*table.list*disabledBackground' => 'darkgray');
\&  $widget->ItemStyle('text', -refwindow => $table_list, -fg => 'red');
.Ve
.Sp
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.
.SH "STYLE METHODS"
.IX Header "STYLE METHODS"
The \fBItemStyle\fR method creates an object.
This object supports the \fBconfigure\fR and \fBcget\fR methods
described in Tk::options which can be used to enquire and
modify the options described above.
.PP
The following additional methods are available for item styles:
.IP "\fI$style\fR\->\fBdelete\fR" 4
.IX Item "$style->delete"
Destroy this display style object.
.SH "EXAMPLE"
.IX Header "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 \fBtext\fR
styles. Also, the anchor and font of the second column is chosen so
that the income data is aligned properly.
.PP
.Vb 4
\&   use strict;
\&   use Tk;
\&   use Tk::HList;
\&   use Tk::ItemStyle;
.Ve
.PP
.Vb 1
\&   my $mw = MainWindow->new();
.Ve
.PP
.Vb 1
\&   my $hlist = $mw->HList(-columns=>2)->pack;
.Ve
.PP
.Vb 2
\&   my $red  = $hlist->ItemStyle('text', -foreground=>'#800000');
\&   my $blue = $hlist->ItemStyle('text', -foreground=>'#000080', -anchor=>'e');
.Ve
.PP
.Vb 9
\&   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);
\&   }
.Ve
.PP
.Vb 1
\&   Tk::MainLoop;
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Tk::HList
Tk::TixGrid
Tk::TList
.SH "KEYWORDS"
.IX Header "KEYWORDS"
display item, display style, item style