Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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
       A A A $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.24.1			  2013-11-15			      DItem(3)

NAME | SYNOPSIS | DESCRIPTION | DISPLAY ITEM TYPES AND OPTIONS | IMAGETEXT ITEMS | TEXT ITEMS | WINDOW ITEMS | CREATING DISPLAY ITEMS | CREATING AND MANIPULATING ITEM STYLES | SYNOPSIS | STYLE METHODS | EXAMPLE | SEE ALSO | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Tk::DItem&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help