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

FreeBSD Manual Pages

  
 
  

home | help
tixDisplayStyle(n)	     Tix Built-In Commands	    tixDisplayStyle(n)

NAME
       tixDisplayStyle - Create	style object for Tix display items.

SYNOPSIS
       tixDisplayStyle	itemType  ?-stylename name? ?-refwindow	pathName? ?op-
       tions value ...?

DESCRIPTION
       The Tix Display Items mechanism is devised to solve a general  problem:
       many Tix	widgets	(both existing and planned ones) display many items of
       many types simutaneously.

       For example, a hierarchical listbox widget (HList) can display items of
       images,	plain  text and	subwindows in the form of a hierarchy. Another
       widget, the tabular listbox, (TList, currently planned and will be  re-
       leased  in  Tix	4.1) also display items	of the same types, although it
       arranges	the items in a tabular form. Yet another widget,  the  spread-
       sheet  widget,  also  displays  similar types items, but	in yet another
       format.

       In these	examples, the display items in different widgets are only dif-
       ferent  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 can-
       vas 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  at-
       tributes	 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 dis-
       play  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	 fore-
       ground.	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 four	types of display items:	text, image, imagetext
       and window. (TODO: need to document the "image" item)

IMAGETEXT ITEMS
       Display	items  of  the type imagetext are used to display an image to-
       gether with a text string. Imagetext items support  the	following  op-
       tions:

       ITEM OPTIONS

	      [-bitmap bitmap]	Specifies  the	bitmap to display in the item.
	      [-image image] Specifies the image to display in the item.  When
	      both  the	-bitmap	and -image options are specified, only the im-
	      age will be displayed.   [-style imageTextStyle]	Specifies  the
	      display style to use for this item. Must be the name of a	image-
	      text display style that has already be created  by  the  tixDis-
	      playStyle(n)  command.   [-showimage showImage]  A Boolean value
	      that specifies whether the  image/bitmap	should	be  displayed.
	      [-showtext showText]  A Boolean value that specifies whether the
	      text string should be  displayed.	  [-text text]	Specifies  the
	      text  string  to	display	 in  the item.	[-underline 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.

       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 the options(n) manual	entry for details on the standard  op-
	      tions.

	      STYLE-SPECIFIC OPTIONS

	      Name:	      gap
	      Class:	      Gap
	      Switch:	      -gap

		     Specifies	the  distance between the bitmap/image and the
		     text string, in number of pixels.

TEXT ITEMS
       Display items of	the type text are used to display a text string	 in  a
       widget. Text items support the following	options:

       ITEM OPTIONS

	      [-style textStyle]  Specifies  the display style to use for this
	      text item. Must be the name of a text display style that has al-
	      ready    be   created   by   the	 tixDisplayStyle(n)   command.
	      [-text text] Specifies the text string to	display	in  the	 item.
	      [-underline underline]  Specifies	the integer index of a charac-
	      ter to underline in the item.  0 corresponds to the first	 char-
	      acter of the text	displayed in the widget, 1 to the next charac-
	      ter, and so on.
       STYLE OPTIONS

	      STANDARD OPTIONS

	      activeBackground	      activeForeground
	      anchor		      background
	      disabledBackground      disabledForeground
	      foreground	      font
	      justify		      padX
	      padY		      selectBackground
	      selectForeground	      wrapLength

	      See the options(n) manual	entry for details on the standard  op-
	      tions.

WINDOW ITEMS
       Display	items of the type window are used to display a sub-window in a
       widget. Window items support the	following options:

       ITEM OPTIONS

	      [-style windowStyle] Specifies the display style to use for this
	      window item. Must	be the name of a window	display	style that has
	      already be created by the	tixDisplayStyle(n) command.

	      Name:	      window
	      Class:	      Window
	      Switch:	      -window
	      Alias:	      -widget

		     Specifies the sub-window to display in the	item.
       STYLE OPTIONS

	      STANDARD OPTIONS

	      anchor
	      padX		      padY

	      See the options(n) manual	entry for details on the standard  op-
	      tions.

CREATING DISPLAY ITEMS
       Display items do	not exist on their and thus they cannot	be created in-
       dependently of the widgets they reside in. As a rule, display items are
       created	by  special widget commands of their "host" widgets. For exam-
       ple, the	HList widgets has a command item which can be used  to	create
       new  display  items. The	following code creates a new imagetext item at
       the third column	of the entry foo inside	an HList widget:

	tixHList .h -columns 3
	.h add foo
	.h item	create foo 2 -itemtype imagetext -text Hello -image image1

       The item	create command 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 de-
       stroyed using the commands provided by the host	widget.	 For  example,
       the  HList  widget  has	the command item configure, item cget and item
       delete for accessing the	display	items.

CREATING AND MANIPULATING DISPLAY STYLES
       Display styles are created by the command tixDisplayStyle:

       itemType	must be	one of the existing display items types	such as	 text,
       imagetext,  window or any new types added by the	user. Additional argu-
       ments 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 pathName
		     Specifies a window	to use for determine the default  val-
		     ues  of the display type. If unspecified, the main	window
		     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: option add
		     *table.list*disabledForeground  blue  option   add	  *ta-
		     ble.list*disabledBackground darkgray tixDisplayStyle 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 option(n) for	a  de-
	      tailed description of the	option database.

STYLE COMMAND
       The tixDisplayStyle command creates a new Tcl command whose name	is the
       same as the name	of the newly created display style.  This command  may
       be  used	to invoke various operations on	the display style.  It has the
       following general form:
	      styleName	option ?arg arg	...?
       styleName is the	name of	the command. Option and	the args determine the
       exact behavior of the command. The following commands are possible:

       styleName cget option
	      Returns  the  current value of the configuration option given by
	      option. Option may have any of the valid options of this display
	      style.

       styleName configure ?option? ?value option value	...?
	      Query  or	modify the configuration options of the	display	style.
	      If no option is specified, returns a list	describing all of  the
	      available	options	for styleName (see Tk_ConfigureInfo for	infor-
	      mation on	the format of this list). If option is specified  with
	      no  value,  then	the  command returns a list describing the one
	      named option (this list will be identical	to  the	 corresponding
	      sublist  of  the	value returned if no option is specified).  If
	      one or more option-value pairs are specified, then  the  command
	      modifies the given option(s) to have the given value(s); in this
	      case the command returns an empty	string.	Option may have	any of
	      the valid	options	of this	display	style.

       styleName 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 an-
       chor and	font of	the second column is chosen so that the	income data is
       aligned properly.

       set  courier  {courier  14} set h [tixHList .h -columns 2]; pack	$h set
       red  [tixDisplayStyle text -fg #800000] set blue	[tixDisplayStyle  text
       -fg #000080 \
		 -anchor e -font $courier]

       foreach n {{Joe $10,000}	{Peter $20,000}	{Raj $90,000}} {
	   set entry [$h addchild {}]
	   $h  item  create  $entry  0	-itemtype text \		 -text
       [lindex $n 0] -style $red
	   $h item create $entry  1  -itemtype	text  \			 -text
       [lindex $n 1] -style $blue }

KEYWORDS
       display item, display style, imagetext

Tix				      8.0		    tixDisplayStyle(n)

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

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

home | help