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

FreeBSD Manual Pages

  
 
  

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

NAME
       tixTList	- Create and manipulate	Tix Tabular List widgets

SYNOPSIS
       tixTList	   pathName   ?options?	   -background	  -borderWidth	 -cur-
       sor   -foreground -font	   -height   -highlightColor  -highlightThick-
       ness	  -relief   -selectBackground	-selectForeground -xScrollCom-
       mand	-yScrollCommand	    -width

WIDGET-SPECIFIC	OPTIONS
       [-browsecmd browsecmd] Specifies	a TCL command to be executed when  the
       user  browses  through the entries in the TList widget.	[-command com-
       mand] Specifies the TCL command to be executed when the user invokes  a
       list  entry in the TList	widget.	Normally the user invokes a list entry
       by double-clicking it or	pressing the Return  key.   [-foreground fore-
       ground]	Specifies  the	default	foreground color for the list entries.
       [-height	height]	Specifies the desired height for the window in	number
       of characters.  [-itemtype itemType] Specifies the default type of dis-
       play item for this TList	widget.	When you call the insert  widget  com-
       mands,  display items of	this type will be created if the -itemtype op-
       tion is not specified .	[-orient orient] Specifies the order of	 tabu-
       larizing	 the list entries. When	set to "vertical", the entries are ar-
       ranged in a column, from	top to bottom. If the entries cannot  be  con-
       tained in one column, the remaining entries will	go to the next column,
       and so on. When set to "horizontal", the	entries	are arranged in	a row,
       from  left to right. If the entries cannot be contained in one row, the
       remaining entries will go to the	next row, and so on.  [-padx padX] The
       default	horizontal padding for list entries.  [-padx padY] The default
       vertical	 padding  for  list  entries.	[-selectbackground selectBack-
       ground]	Specifies  the background color	for the	selected list entries.
       [-selectborderwidth selectBorderWidth] Specifies	a  non-negative	 value
       indicating  the	width of the 3-D border	to draw	around selected	items.
       The value may have any of the forms acceptable to Tk_GetPixels.	 [-se-
       lectforeground selectForeground]	Specifies the foreground color for the
       selected	list entries.  [-selectmode selectMode]	Specifies one of  sev-
       eral  styles  for  manipulating the selection.  The value of the	option
       may be arbitrary, but the default bindings expect it to be either  sin-
       gle,  browse,  multiple,	 or  extended;	the  default  value is single.
       [-sizecmd sizeCmd] Specifies a TCL script to  be	 called	 whenever  the
       TList  widget changes its size. This command can	be useful to implement
       "user scroll bars  when	needed"	 features.   [-state state]  Specifies
       whether	the  TList  command  should react to user actions. When	set to
       "normal", the TList reacts to user actions in the normal	way. When  set
       to  "disabled",	the TList can only be scrolled,	but its	entries	cannot
       be selected or activated.  [-width width] Specifies the	desired	 width
       for the window in characters.

DESCRIPTION
       The  tixTList command creates a new window (given by the	pathName argu-
       ment) and makes it into a TList widget.	Additional options,  described
       above,  may  be specified on the	command	line or	in the option database
       to configure aspects of the TList widget	such as	its cursor and relief.

       The TList widget	can be used to display data in a tabular  format.  The
       list  entries  of  a  TList widget are similar to the entries in	the Tk
       listbox widget. The main	differences are	(1) the	TList widget can  dis-
       play  the  list entries in a two	dimensional format and (2) you can use
       graphical images	as well	as multiple colors and fonts for the list  en-
       tries.

       Each  list entry	is identified by an index, which can be	in the follow-
       ing forms:

	      number An	integer	that indicates the position of	the  entry  in
		     the  list.	0 means	the first position, 1 means the	second
		     position, and so on.

	      end    Indicates the end of the listbox. For some	commands  this
		     means  just  after	 the last entry; for other commands it
		     means the last entry.

	      @x,y   Indicates the element that	covers the point in the	 list-
		     box  window  specified by x and y (in pixel coordinates).
		     If	no element covers that point, then the closest element
		     to	that point is used.

DISPLAY	ITEMS
       Each  list  entry in an TList widget is associated with a display item.
       The display item	determines what	visual information should be displayed
       for  this  list entry. Please see the tixDisplayStyle manual page for a
       list of all display items.

       When a list entry is created by the insert command,  the	 type  of  its
       display item is determined by the -itemtype option passed to these com-
       mands. If the -itemtype is omitted, then	by default the type  specified
       by this TList widget's -itemtype	option is used.

WIDGET COMMAND
       The  tixTList  command creates a	new Tcl	command	whose name is the same
       as the path name	of the TList widget's window.	This  command  may  be
       used  to	invoke various operations on the widget.  It has the following
       general form:
	      pathName option ?arg arg ...?
       PathName	is the name of the command, which is the  same	as  the	 TList
       widget's	 path  name.  Option and the args determine the	exact behavior
       of the command.	The following commands are possible for	TList widgets:

       pathName	anchor set index
	      Sets the anchor to the list entry	identified by index.  The  an-
	      chor  is	the  end of the	selection that is fixed	while dragging
	      out a selection with the mouse.

       pathName	anchor clear
	      Removes the anchor, if any, from this TList  widget.  This  only
	      removes  the surrounding highlights of the anchor	entry and does
	      not affect its selection status.

       pathName	cget option
	      Returns the current value	of the configuration option  given  by
	      option.  Option  may  have  any  of  the	values accepted	by the
	      tixTList command.

       pathName	configure ?option? ?value option value ...?
	      Query or modify the configuration	options	of the widget.	If  no
	      option is	specified, returns a list describing all of the	avail-
	      able options for pathName	(see Tk_ConfigureInfo for  information
	      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	widget option(s) to have the given value(s);  in  this
	      case  the	 command returns an empty string.  Option may have any
	      of the values accepted by	the tixTList command.

       pathName	delete from ?to?
	      Deletes one or more list entries between the two entries	speci-
	      fied by the indices from and to. If to is	not specified, deletes
	      the single entry specified by from.

       pathName	dragsite set index
	      Sets the dragsite	to the list entry  identified  by  index.  The
	      dragsite	is  used to indicate the source	of a drag-and-drop ac-
	      tion. Currently drag-and-drop functionality has not been	imple-
	      mented in	Tix yet.

       pathName	dragsite clear
	      Remove  the  dragsite,  if any, from the this TList widget. This
	      only removes the surrounding highlights of  the  dragsite	 entry
	      and does not affect its selection	status.

       pathName	dropsite set index
	      Sets  the	 dropsite  to  the list	entry identified by index. The
	      dropsite is used to indicate the target of a  grag-and-drop  ac-
	      tion.  Currently drag-and-drop functionality has not been	imple-
	      mented in	Tix yet.

       pathName	dropsite clear
	      Remove the dropsite, if any, from	the this  TList	 widget.  This
	      only  removes  the  surrounding highlights of the	dropsite entry
	      and does not affect its selection	status.

       pathName	entrycget index	option
	      Returns the current value	of the configuration option  given  by
	      option for the entry indentfied by index.	Option may have	any of
	      the values accepted by the insert	widget command.

       pathName	entryconfigure index ?option? ?value option value ...?
	      Query or modify the configuration	options	of the list entry  in-
	      dentfied by index. If no option is specified, returns a list de-
	      scribing all of the available options for	index (see  Tk_Config-
	      ureInfo  for  information	on the format of this list). If	option
	      is specified with	no value, then the command returns a list  de-
	      scribing	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.  Op-
	      tion may have any	of the values accepted by  the	insert	widget
	      command.	The  exact  set	of options depends on the value	of the
	      -itemtype	option passed to the the insert	 widget	 command  when
	      this list	entry is created.

       pathName	insert index ?option value ...?
	      Creates a	new list entry at the position indicated by index. The
	      following	configuration options can be given  to	configure  the
	      list entry:

	      -itemtype	type
		     Specifies	the type of display item to be display for the
		     new list entry. type must be a valid display  item	 type.
		     Currently the available display item types	are image, im-
		     agetext, text, and	window.	If this	option is  not	speci-
		     fied,  then  by  default the type specified by this TList
		     widget's -itemtype	option is used.

	      -state Specifies whether this entry can be selected  or  invoked
		     by	the user.  Must	be either normal or disabled.
       The  insert  widget command accepts additional configuration options to
       configure the display item associated with this list entry. The set  of
       additional  configuration  options  depends  on the type	of the display
       item given by the -itemtype option. Please see the tixDisplayStyle man-
       ual  page  for a	list of	the configuration options for each of the dis-
       play item types.

       pathName	info option arg	...
	      Query information	about the TList	widget.	option can be  one  of
	      the following:

	      pathName info anchor index
		     ; Returns the index of the	current	anchor,	if any,	of the
		     TList widget. If the anchor is not	set, returns the empty
		     string.

	      pathName info dragsite index
		     Returns the index of the current dragsite,	if any,	of the
		     TList widget. If the dragsite is  not  set,  returns  the
		     empty string.

	      pathName info dropsite index
		     Returns the index of the current dropsite,	if any,	of the
		     TList widget. If the dropsite is  not  set,  returns  the
		     empty string.

	      pathName info selection
		     Returns  a	list of	selected elements in the TList widget.
		     If	no entries are selectd,	returns	an empty string.

       pathName	nearest	x y
	      Given an (x,y) coordinate	within the TList window, this  command
	      returns  the  index of the TList element nearest to that coordi-
	      nate.

       pathName	see index
	      Adjust the view in the TList so that the entry given by index is
	      visible. If the entry is already visible then the	command	has no
	      effect; if the entry is near one edge of	the  window  then  the
	      TList scrolls to bring the element into view at the edge;	other-
	      wise the TList widget scrolls to center the entry.

       pathName	selection option arg ...
	      This command is used to adjust the selection within a TList wid-
	      get. It has several forms, depending on option:

	      pathName selection clear ?from? ?to?
		     When  no  extra arguments are given, deselects all	of the
		     list entrie(s) in this TList widget. When	only  from  is
		     given,  only  the	list entry identified by from is dese-
		     lected. When both from and	to are given, deselects	all of
		     the  list	entrie(s)  between between from	and to,	inclu-
		     sive, without affecting the selection  state  of  entries
		     outside that range.

	      pathName selection includes index
		     Returns  1	 if  the list entry indicated by index is cur-
		     rently selected; returns 0	otherwise.

	      pathName selection set from ?to?
		     Selects all of the	list entrie(s)	between	 between  from
		     and  to, inclusive, without affecting the selection state
		     of	entries	outside	that range. When only from  is	given,
		     only the list entry identified by from is selected.

       pathName	xview args
	      This command is used to query and	change the horizontal position
	      of the information in the	widget's window. It can	 take  any  of
	      the following forms:

	      pathName xview
		     Returns  a	list containing	two elements.  Each element is
		     a real fraction between 0 and 1; together	they  describe
		     the  horizontal  span that	is visible in the window.  For
		     example, if the first element is .2 and the  second  ele-
		     ment  is  .6, 20% of the TList entry is off-screen	to the
		     left, the middle 40% is visible in	the window, and	40% of
		     the  entry	is off-screen to the right. These are the same
		     values passed to scrollbars via the  -xscrollcommand  op-
		     tion.

	      pathName xview index
		     Adjusts  the  view	 in  the window	so that	the list entry
		     identified	by index is aligned to the left	 edge  of  the
		     window.

	      pathName xview moveto fraction
		     Adjusts  the  view	 in the	window so that fraction	of the
		     total width of the	TList is off-screen to the left. frac-
		     tion must be a fraction between 0 and 1.

	      pathName xview scroll number what
		     This  command shifts the view in the window left or right
		     according to number and what. Number must be an  integer.
		     What  must	be either units	or pages or an abbreviation of
		     one of these. If what is units, the view adjusts left  or
		     right by number character units (the width	of the 0 char-
		     acter) on the display; if it is pages then	the  view  ad-
		     justs  by	number	screenfuls. If number is negative then
		     characters	farther	to the left become visible; if	it  is
		     positive then characters farther to the right become vis-
		     ible.

       pathName	yview ?args?
	      This command is used to query and	change the  vertical  position
	      of  the  entries	in the widget's	window.	It can take any	of the
	      following	forms:

	      pathName yview
		     Returns a list containing two elements, both of which are
		     real  fractions between 0 and 1.  The first element gives
		     the position of the list element at the top of  the  win-
		     dow,  relative  to	 the TList as a	whole (0.5 means it is
		     halfway through the TList,	for example).  The second ele-
		     ment  gives the position of the list entry	just after the
		     last one in the window, relative to the TList as a	whole.
		     These  are	 the  same values passed to scrollbars via the
		     -yscrollcommand option.

	      pathName yview index
		     Adjusts the view in the window so	that  the  list	 entry
		     given by index is displayed at the	top of the window.

	      pathName yview moveto fraction
		     Adjusts  the  view	 in  the window	so that	the list entry
		     given by fraction appears at the top of the window. Frac-
		     tion is a fraction	between	0 and 1; 0 indicates the first
		     entry in the TList, 0.33 indicates	 the  entry  one-third
		     the way through the TList,	and so on.

	      pathName yview scroll number what
		     This command adjust the view in the window	up or down ac-
		     cording to	number and what.  Number must be  an  integer.
		     What  must	 be  either units or pages.  If	what is	units,
		     the view adjusts up or down by number  lines;  if	it  is
		     pages  then  the  view  adjusts by	number screenfuls.  If
		     number is negative	then earlier entries  become  visible;
		     if	it is positive then later entries become visible.

BINDINGS
       [1]    If  the  -selectmode  is "browse", when the user drags the mouse
	      pointer over the list entries, the entry under the pointer  will
	      be  highlighted and the -browsecmd procedure will	be called with
	      one parameter, the index of the highlighted entry. Only one  en-
	      try can be highlighted at	a time.	The -command procedure will be
	      called when the user double-clicks on a list entry.

       [2]    If the -selectmode is "single", the entries will only  be	 high-
	      lighted by mouse <ButtonRelease-1> events. When a	new list entry
	      is highlighted, the -browsecmd procedure will be called with one
	      parameter	 indicating  the  highlighted list entry. The -command
	      procedure	will be	called when the	user double-clicks on  a  list
	      entry.

       [3]    If  the -selectmode is "multiple", when the user drags the mouse
	      pointer over the list entries, all the entries under the pointer
	      will  be	highlighted. However, only a contiguous	region of list
	      entries can be selected. When the	highlighted area  is  changed,
	      the -browsecmd procedure will be called with an undefined	param-
	      eter. It is the responsibility of	the  -browsecmd	 procedure  to
	      find out the exact highlighted selection in the TList. The -com-
	      mand procedure will be called when the user double-clicks	 on  a
	      list entry.

       [4]    If  the -selectmode is "extended", when the user drags the mouse
	      pointer over the list entries, all the entries under the pointer
	      will  be	highlighted.  The user can also	make disjointed	selec-
	      tions using <Control-ButtonPress-1>. When	the  highlighted  area
	      is  changed, the -browsecmd procedure will be called with	an un-
	      defined parameter. It is the responsibility  of  the  -browsecmd
	      procedure	 to  find  out	the exact highlighted selection	in the
	      TList. The -command procedure will be called when	the user  dou-
	      ble-clicks on a list entry.

EXAMPLE
       This  example  demonstrates how to use an TList to store	a list of num-
       bers:

       set image [tix getimage folder] set t [tixTList .t -orient vertical] $t
       insert  end  -itemtype  imagetext -image	$image -text one $t insert end
       -itemtype imagetext -image $image -text two $t insert end -itemtype im-
       agetext	-image	$image	-text  three $t	insert end -itemtype imagetext
       -image $image -text four	$t insert end -itemtype	imagetext -image  $im-
       age  -text  five	 $t insert end -itemtype imagetext -image $image -text
       six pack	$t -expand yes -fill both

KEYWORDS
       Tix(n), Tabular Listbox,	Display	Items

Tix				      4.0			   tixTList(n)

NAME | SYNOPSIS | WIDGET-SPECIFIC OPTIONS | DESCRIPTION | DISPLAY ITEMS | WIDGET COMMAND | BINDINGS | EXAMPLE | KEYWORDS

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

home | help