Tk_ConfigureValue man page on BSDOS

Man page or keyword search:  
man Server   6284 pages
apropos Keyword Search (all sections)
Output format
BSDOS logo
[printable version]



Tk_ConfigureWidget(3) Tk Library Procedures Tk_ConfigureWidget(3)

_________________________________________________________________

NAME
       Tk_ConfigureWidget,  Tk_Offset,	Tk_ConfigureInfo, Tk_Con-
       figureValue,  Tk_FreeOptions   -	  process   configuration
       options for widgets

SYNOPSIS
       #include <tk.h>

       int
       Tk_ConfigureWidget(interp, tkwin, specs, argc, argv, widgRec, flags)

       int
       Tk_Offset(type, field)

       int
       Tk_ConfigureInfo(interp, tkwin, specs, widgRec, argvName, flags)

       int

       Tk_FreeOptions(specs, widgRec, display, flags)

ARGUMENTS
       Tcl_Interp      *interp	  (in)	    Interpreter	  to  use
					    for	 returning  error
					    messages.

       Tk_Window       tkwin	  (in)	    Window used to repre-
					    sent  widget  (needed
					    to	   set	  up	X
					    resources).

       Tk_ConfigSpec   *specs	  (in)	    Pointer   to    table
					    specifying legal con-
					    figuration	  options
					    for this widget.

       int	       argc	  (in)	    Number  of	arguments
					    in argv.

       char	       **argv	  (in)	    Command-line  options
					    for	 configuring wid-
					    get.

       char	       *widgRec	  (in/out)  Points   to	   widget
					    record     structure.
					    Fields in this struc-
					    ture  get modified by
					    Tk_ConfigureWidget to
					    hold    configuration
					    information.

       int	       flags	  (in)	    If non-zero, then  it

Tk			       4.1				1

Tk_ConfigureWidget(3) Tk Library Procedures Tk_ConfigureWidget(3)

					    specifies	an  OR-ed
					    combination of  flags
					    that control the pro-
					    cessing of configura-
					    tion     information.
					    TK_CONFIG_ARGV_ONLY
					    causes   the   option
					    database and defaults
					    to	be  ignored,  and
					    flag   bits	  TK_CON-
					    FIG_USER_BIT      and
					    higher  are	 used  to
					    selectively	  disable
					    entries in specs.

       type name       type	  (in)	    The name of the  type
					    of a widget record.

       field name      field	  (in)	    The	 name  of a field
					    in	records	 of  type
					    type.

       char	       *argvName  (in)	    The	 name used on Tcl
					    command   lines    to
					    refer to a particular
					    option   (e.g.   when
					    creating  a widget or
					    invoking the  config-
					    ure	 widget command).
					    If	 non-NULL,   then
					    information	       is
					    returned   only   for
					    this    option.    If
					    NULL,  then	 informa-
					    tion  is returned for
					    all		available
					    options.

       Display	       *display	  (in)	    Display    containing
					    widget  whose  record
					    is	  being	   freed;
					    needed  in	order  to
					    free up resources.
_________________________________________________________________

DESCRIPTION
       Tk_ConfigureWidget  is called to configure various aspects
       of a widget, such as colors, fonts, border width, etc.  It
       is  intended  as	 a  convenience	 procedure  to reduce the
       amount of code that must be written in  individual  widget
       managers to handle configuration information.  It is typi-
       cally invoked when widgets are created, and again when the
       configure  command  is  invoked	for  a	widget.	 Although
       intended primarily for widgets, Tk_ConfigureWidget can  be

Tk			       4.1				2

Tk_ConfigureWidget(3) Tk Library Procedures Tk_ConfigureWidget(3)

       used in other situations where argc-argv information is to
       be used to fill in a record structure, such as configuring
       graphical  elements  for	 a  canvas widget or entries of a
       menu.

       Tk_ConfigureWidget processes a table specifying	the  con-
       figuration  options  that are supported (specs) and a col-
       lection of command-line arguments (argc and argv) to  fill
       in  fields  of  a  record  (widgRec).   It uses the option
       database and defaults specified in specs to fill in fields
       of  widgRec  that  are  not specified in argv.  Tk_Config-
       ureWidget normally returns the value TCL_OK; in this  case
       it  does	 not  modify  interp.	If  an	error occurs then
       TCL_ERROR is returned and Tk_ConfigureWidget will leave an
       error  message in interp->result in the standard Tcl fash-
       ion.  In the event of an error return, some of the  fields
       of  widgRec  could already have been set, if configuration
       information for them was successfully processed before the
       error  occurred.	  The other fields will be set to reason-
       able initial values so that Tk_FreeOptions can  be  called
       for cleanup.

       The  specs  array  specifies  the  kinds	 of configuration
       options expected by the widget.	Each of its entries spec-
       ifies  one  configuration  option  and  has  the following
       structure:
	      typedef struct {
		int type;
		char *argvName;
		char *dbName;
		char *dbClass;
		char *defValue;
		int offset;
		int specFlags;
		Tk_CustomOption *customPtr;
	      } Tk_ConfigSpec;
       The type field indicates what type of configuration option
       this  is	 (e.g.	TK_CONFIG_COLOR	 for  a	 color	value, or
       TK_CONFIG_INT for an integer value).  The type field indi-
       cates  how  to  use  the value of the option (more on this
       below).	The argvName field is a string such as	``-font''
       or  ``-bg'', which is compared with the values in argv (if
       argvName is NULL it means this is a  grouped  entry;   see
       GROUPED ENTRIES below).	The dbName and dbClass fields are
       used to look up a value for  this  option  in  the  option
       database.   The	defValue  field specifies a default value
       for this configuration option if no value is specified  in
       either  argv  or	 the  option  database.	 Offset indicates
       where in widgRec to store information about  this  option,
       and  specFlags  contains additional information to control
       the processing of this  configuration  option  (see  FLAGS
       below).	 The  last field, customPtr, is only used if type
       is TK_CONFIG_CUSTOM;  see CUSTOM OPTION TYPES below.

Tk			       4.1				3

Tk_ConfigureWidget(3) Tk Library Procedures Tk_ConfigureWidget(3)

       Tk_ConfigureWidget first processes argv to see  which  (if
       any) configuration options are specified there.	Argv must
       contain an even number of fields;  the first of each  pair
       of  fields  must match the argvName of some entry in specs
       (unique abbreviations  are  acceptable),	 and  the  second
       field  of  the pair contains the value for that configura-
       tion option.  If there are entries in spec for which there
       were  no matching entries in argv, Tk_ConfigureWidget uses
       the dbName and dbClass fields of the specs entry to  probe
       the option database;  if a value is found, then it is used
       as the value for the option.   Finally,	if  no	entry  is
       found  in  the  option database, the defValue field of the
       specs entry is used as the  value  for  the  configuration
       option.	 If  the  defValue  is	NULL,  or  if the TK_CON-
       FIG_DONT_SET_DEFAULT bit is set in flags, then there is no
       default	value  and this specs entry will be ignored if no
       value is specified in argv or the option database.

       Once a string value has been determined for  a  configura-
       tion  option,  Tk_ConfigureWidget  translates  the  string
       value into a more useful form, such as a color if type  is
       TK_CONFIG_COLOR	or  an	integer if type is TK_CONFIG_INT.
       This value is then stored in the record pointed to by wid-
       gRec.  This record is assumed to contain information rele-
       vant to the manager of the  widget;   its  exact	 type  is
       unknown	to  Tk_ConfigureWidget.	 The offset field of each
       specs entry indicates where in widgRec to store the infor-
       mation  about  this  configuration option.  You should use
       the Tk_Offset macro to generate offset values  (see  below
       for  a  description of Tk_Offset).  The location indicated
       by widgRec and offset will be referred to  as  the  ``tar-
       get'' in the descriptions below.

       The  type  field of each entry in specs determines what to
       do with the string value	 of  that  configuration  option.
       The  legal values for type, and the corresponding actions,
       are:

       TK_CONFIG_ACTIVE_CURSOR
	      The value must be an  ASCII  string  identifying	a
	      cursor in a form suitable for passing to Tk_GetCur-
	      sor.  The value is  converted  to	 a  Tk_Cursor  by
	      calling  Tk_GetCursor  and  the result is stored in
	      the target.  In addition, the resulting  cursor  is
	      made  the	 active	 cursor for tkwin by calling XDe-
	      fineCursor.  If TK_CONFIG_NULL_OK is  specified  in
	      specFlags then the value may be an empty string, in
	      which case the target  and  tkwin's  active  cursor
	      will  be set to None.  If the previous value of the
	      target wasn't None, then it is freed by passing  it
	      to Tk_FreeCursor.

       TK_CONFIG_ANCHOR
	      The  value  must	be an ASCII string identifying an

Tk			       4.1				4

Tk_ConfigureWidget(3) Tk Library Procedures Tk_ConfigureWidget(3)

	      anchor  point  in	 one  of  the  ways  accepted  by
	      Tk_GetAnchor.    The   string  is	 converted  to	a
	      Tk_Anchor by calling Tk_GetAnchor and the result is
	      stored in the target.

       TK_CONFIG_BITMAP
	      The  value  must	be  an ASCII string identifying a
	      bitmap in a form suitable for  passing  to  Tk_Get-
	      Bitmap.	The  value  is	converted  to a Pixmap by
	      calling Tk_GetBitmap and the result  is  stored  in
	      the  target.   If TK_CONFIG_NULL_OK is specified in
	      specFlags then the value may be an empty string, in
	      which  case the target is set to None.  If the pre-
	      vious value of the target wasn't None, then  it  is
	      freed by passing it to Tk_FreeBitmap.

       TK_CONFIG_BOOLEAN
	      The  value  must	be  an	ASCII string specifying a
	      boolean  value.	Any  of	 the   values	``true'',
	      ``yes'',	``on'',	 or  ``1'', or an abbreviation of
	      one of these values, means true; any of the  values
	      ``false'',  ``no'', ``off'', or ``0'', or an abbre-
	      viation of one of these values, means  false.   The
	      target is expected to be an integer;  for true val-
	      ues it will be set to 1 and  for	false  values  it
	      will be set to 0.

       TK_CONFIG_BORDER
	      The  value  must	be  an ASCII string identifying a
	      border color in a	 form  suitable	 for  passing  to
	      Tk_Get3DBorder.	 The  value  is	 converted  to	a
	      (Tk_3DBorder *) by calling Tk_Get3DBorder	 and  the
	      result   is  stored  in  the  target.   If  TK_CON-
	      FIG_NULL_OK is  specified	 in  specFlags	then  the
	      value  may  be  an  empty string, in which case the
	      target will be set to NULL.  If the previous  value
	      of  the  target  wasn't  NULL,  then it is freed by
	      passing it to Tk_Free3DBorder.

       TK_CONFIG_CAP_STYLE
	      The value must be an ASCII string identifying a cap
	      style  in	 one  of  the ways accepted by Tk_GetCap-
	      Style.  The string is converted to an integer value
	      corresponding  to	 the cap style by calling Tk_Get-
	      CapStyle and the result is stored in the target.

       TK_CONFIG_COLOR
	      The value must be an  ASCII  string  identifying	a
	      color  in	 a  form  suitable for passing to Tk_Get-
	      Color.  The value is converted to an (XColor *)  by
	      calling Tk_GetColor and the result is stored in the
	      target.	If  TK_CONFIG_NULL_OK  is  specified   in
	      specFlags then the value may be an empty string, in
	      which case the target will be set to None.  If  the

Tk			       4.1				5

Tk_ConfigureWidget(3) Tk Library Procedures Tk_ConfigureWidget(3)

	      previous	value  of the target wasn't NULL, then it
	      is freed by passing it to Tk_FreeColor.

       TK_CONFIG_CURSOR
	      This option is identical to TK_CONFIG_ACTIVE_CURSOR
	      except  that  the new cursor is not made the active
	      one for tkwin.

       TK_CONFIG_CUSTOM
	      This  option  allows  applications  to  define  new
	      option  types.   The  customPtr  field of the entry
	      points to a structure defining the new option type.
	      See  the	section	 CUSTOM	 OPTION	 TYPES	below for
	      details.

       TK_CONFIG_DOUBLE
	      The value must be an ASCII floating-point number in
	      the  format accepted by strtol.  The string is con-
	      verted to a double value, and the value  is  stored
	      in the target.

       TK_CONFIG_END
	      Marks  the  end  of  the	table.	The last entry in
	      specs must have this type;  all of its other fields
	      are  ignored and it will never match any arguments.

       TK_CONFIG_FONT
	      The value must be an  ASCII  string  identifying	a
	      font  in	a  form	 suitable  for passing to Tk_Get-
	      FontStruct.   The	 value	 is   converted	  to   an
	      (XFontStruct *) by calling Tk_GetFontStruct and the
	      result  is  stored  in  the  target.   If	  TK_CON-
	      FIG_NULL_OK  is  specified  in  specFlags	 then the
	      value may be an empty string,  in	 which	case  the
	      target  will be set to NULL.  If the previous value
	      of the target wasn't NULL,  then	it  is	freed  by
	      passing it to Tk_FreeFontStruct.

       TK_CONFIG_INT
	      The  value  must	be an ASCII integer string in the
	      format accepted by strtol (e.g.  ``0''  and  ``0x''
	      prefixes	may be used to specify octal or hexadeci-
	      mal numbers, respectively).   The	 string	 is  con-
	      verted  to  an  integer  value  and  the integer is
	      stored in the target.

       TK_CONFIG_JOIN_STYLE
	      The value must be an  ASCII  string  identifying	a
	      join   style   in	 one  of  the  ways  accepted  by
	      Tk_GetJoinStyle.	The string  is	converted  to  an
	      integer  value  corresponding  to the join style by
	      calling Tk_GetJoinStyle and the result is stored in
	      the target.

Tk			       4.1				6

Tk_ConfigureWidget(3) Tk Library Procedures Tk_ConfigureWidget(3)

       TK_CONFIG_JUSTIFY
	      The  value  must	be  an ASCII string identifying a
	      justification method in one of the ways accepted by
	      Tk_GetJustify.	The  string  is	 converted  to	a
	      Tk_Justify by calling Tk_GetJustify and the  result
	      is stored in the target.

       TK_CONFIG_MM
	      The  value must specify a screen distance in one of
	      the forms acceptable to Tk_GetScreenMM.  The string
	      is  converted  to	 double-precision  floating-point
	      distance in millimeters and the value is stored  in
	      the target.

       TK_CONFIG_PIXELS
	      The  value  must specify screen units in one of the
	      forms acceptable to Tk_GetPixels.	  The  string  is
	      converted	 to an integer distance in pixels and the
	      value is stored in the target.

       TK_CONFIG_RELIEF
	      The value must be an  ASCII  string  identifying	a
	      relief  in a form suitable for passing to Tk_GetRe-
	      lief.  The value is converted to an integer  relief
	      value  by	 calling  Tk_GetRelief	and the result is
	      stored in the target.

       TK_CONFIG_STRING
	      A copy of the value is made  by  allocating  memory
	      space  with  malloc  and copying the value into the
	      dynamically-allocated space.  A pointer to the  new
	      string   is  stored  in  the  target.   If  TK_CON-
	      FIG_NULL_OK is  specified	 in  specFlags	then  the
	      value  may  be  an  empty string, in which case the
	      target will be set to NULL.  If the previous  value
	      of  the  target  wasn't  NULL,  then it is freed by
	      passing it to free.

       TK_CONFIG_SYNONYM
	      This type value identifies special entries in specs
	      that  are	 synonyms  for other entries.  If an argv
	      value matches the argvName of  a	TK_CONFIG_SYNONYM
	      entry,  the  entry  isn't	 used  directly. Instead,
	      Tk_ConfigureWidget searches specs for another entry
	      whose  argvName  is the same as the dbName field in
	      the TK_CONFIG_SYNONYM entry;   this  new	entry  is
	      used  just  as if its argvName had matched the argv
	      value.  The synonym mechanism allows multiple  argv
	      values  to  be  used  for	 a  single  configuration
	      option, such as ``-background'' and ``-bg''.

       TK_CONFIG_UID
	      The value is translated to a Tk_Uid (by passing  it
	      to  Tk_GetUid).	The  resulting value is stored in

Tk			       4.1				7

Tk_ConfigureWidget(3) Tk Library Procedures Tk_ConfigureWidget(3)

	      the target.  If TK_CONFIG_NULL_OK is  specified  in
	      specFlags and the value is an empty string then the
	      target will be set to NULL.

       TK_CONFIG_WINDOW
	      The value must be a window path name.  It is trans-
	      lated  to a Tk_Window token and the token is stored
	      in the target.

GROUPED ENTRIES
       In some cases it is useful to generate multiple	resources
       from  a	single configuration value.  For example, a color
       name might be used both to generate the	background  color
       for a widget (using TK_CONFIG_COLOR) and to generate a 3-D
       border to draw around the widget (using TK_CONFIG_BORDER).
       In  cases like this it is possible to specify that several
       consecutive entries in specs are to be treated as a group.
       The  first  entry  is used to determine a value (using its
       argvName, dbName,  dbClass,  and	 defValue  fields).   The
       value  will be processed several times (one for each entry
       in the group), generating multiple different resources and
       modifying  multiple  targets  within widgRec.  Each of the
       entries after the first must have  a  NULL  value  in  its
       argvName	 field;	  this	indicates that the entry is to be
       grouped with the entry that precedes it.	  Only	the  type
       and offset fields are used from these follow-on entries.

FLAGS
       The flags argument passed to Tk_ConfigureWidget is used in
       conjunction with the specFlags fields in	 the  entries  of
       specs to provide additional control over the processing of
       configuration options.  These values  are  used	in  three
       different ways as described below.

       First, if the flags argument to Tk_ConfigureWidget has the
       TK_CONFIG_ARGV_ONLY  bit	 set  (i.e.,  flags   |	  TK_CON-
       FIG_ARGV_ONLY != 0), then the option database and defValue
       fields are not used.  In this case, if an entry	in  specs
       doesn't	match  a  field in argv then nothing happens: the
       corresponding target isn't modified.  This feature is use-
       ful  when  the  goal  is	 to  modify certain configuration
       options while leaving others in their current state,  such
       as when a configure widget command is being processed.

       Second,	the  specFlags	field of an entry in specs may be
       used to	control	 the  processing  of  that  entry.   Each
       specFlags  field	 may  consists of an OR-ed combination of
       the following values:

       TK_CONFIG_COLOR_ONLY
	      If this bit is set then the entry will only be con-
	      sidered  if the display for tkwin has more than one

Tk			       4.1				8

Tk_ConfigureWidget(3) Tk Library Procedures Tk_ConfigureWidget(3)

	      bit plane.  If the display  is  monochromatic  then
	      this specs entry will be ignored.

       TK_CONFIG_MONO_ONLY
	      If this bit is set then the entry will only be con-
	      sidered if the display for tkwin	has  exactly  one
	      bit  plane.   If	the  display is not monochromatic
	      then this specs entry will be ignored.

       TK_CONFIG_NULL_OK
	      This bit is only relevant for some types of entries
	      (see  the	 descriptions  of the various entry types
	      above).  If this bit is set, it indicates	 that  an
	      empty  string value for the field is acceptable and
	      if it occurs then the target should be set to  NULL
	      or None, depending on the type of the target.  This
	      flag is typically used to allow  a  feature  to  be
	      turned  off  entirely,  e.g.  set a cursor value to
	      None so that a window simply inherits its	 parent's
	      cursor.	If  this bit isn't set then empty strings
	      are processed as strings, which  generally  results
	      in an error.

       TK_CONFIG_DONT_SET_DEFAULT
	      If  this	bit  is	 one,  it means that the defValue
	      field of the entry should only be used for  return-
	      ing  the	default	 value	in  Tk_ConfigureInfo.  In
	      calls to Tk_ConfigureWidget no default will be sup-
	      plied  for  entries  with	 this  flag  set;   it is
	      assumed that the	caller	has  already  supplied	a
	      default  value  in  the target location.	This flag
	      provides a performance  optimization  where  it  is
	      expensive	 to  process  the  default  string:   the
	      client can  compute  the	default	 once,	save  the
	      value,  and  provide  it	before calling Tk_Config-
	      ureWidget.

       TK_CONFIG_OPTION_SPECIFIED
	      This bit is set and cleared by  Tk_ConfigureWidget.
	      Whenever	Tk_ConfigureWidget returns, this bit will
	      be set in all the entries where a value was  speci-
	      fied  in	argv.	It  will  be  zero  in	all other
	      entries.	This bit provides a way	 for  clients  to
	      determine	 which	values actually changed in a call
	      to Tk_ConfigureWidget.

       The TK_CONFIG_MONO_ONLY and TK_CONFIG_COLOR_ONLY flags are
       typically  used	to  specify  different default values for
       monochrome and color displays.  This is done  by	 creating
       two  entries  in specs that are identical except for their
       defValue and specFlags fields.  One entry should have  the
       value TK_CONFIG_MONO_ONLY in its specFlags and the default
       value for monochrome displays in its defValue;  the  other
       entry  entry should have the value TK_CONFIG_COLOR_ONLY in

Tk			       4.1				9

Tk_ConfigureWidget(3) Tk Library Procedures Tk_ConfigureWidget(3)

       its specFlags and the appropriate defValue for color  dis-
       plays.

       Third,  it is possible to use flags and specFlags together
       to selectively disable some entries.  This feature is  not
       needed  very  often.   It is useful in cases where several
       similar kinds of widgets are implemented in one place.  It
       allows  a  single  specs	 table to be created with all the
       configuration options for all the widget types.	When pro-
       cessing a particular widget type, only entries relevant to
       that type will be used.	This effect is achieved	 by  set-
       ting  the  high-order bits (those in positions equal to or
       greater than TK_CONFIG_USER_BIT) in specFlags values or in
       flags.	In  order  for	a particular entry in specs to be
       used, its high-order bits must  match  exactly  the  high-
       order  bits  of the flags value passed to Tk_ConfigureWid-
       get.  If a specs table is being used for N different  wid-
       get  types,  then  N  of the high-order bits will be used.
       Each specs entry will have one of more of those	bits  set
       in  its	specFlags  field to indicate the widget types for
       which this entry is valid.  When calling	 Tk_ConfigureWid-
       get,  flags  will  have	a single one of these bits set to
       select the entries for the desired  widget  type.   For	a
       working	example	 of  this feature, see the code in tkBut-
       ton.c.

TK_OFFSET
       The Tk_Offset macro is provided as a safe way of	 generat-
       ing  the offset values for entries in Tk_ConfigSpec struc-
       tures.  It takes two arguments:	the name  of  a	 type  of
       record,	and  the  name	of  a  field  in that record.  It
       returns the byte offset of the named field in  records  of
       the given type.

TK_CONFIGUREINFO
       The  Tk_ConfigureInfo  procedure	 may  be  used	to obtain
       information about one or all of the options  for	 a  given
       widget.	 Given	a  token  for  a  window (tkwin), a table
       describing the configuration options for a class	 of  wid-
       gets  (specs), a pointer to a widget record containing the
       current information for a widget	 (widgRec),  and  a  NULL
       argvName	 argument,  Tk_ConfigureInfo  generates	 a string
       describing all of the configuration options for	the  win-
       dow.   The string is placed in interp->result.  Under nor-
       mal circumstances it returns TCL_OK;  if an  error  occurs
       then  it	 returns TCL_ERROR and interp->result contains an
       error message.

       If argvName is NULL, then the value left in interp->result
       by  Tk_ConfigureInfo  consists  of  a  list of one or more
       entries, each of which describes one configuration  option
       (i.e.  one  entry  in specs).  Each entry in the list will

Tk			       4.1			       10

Tk_ConfigureWidget(3) Tk Library Procedures Tk_ConfigureWidget(3)

       contain either two or five values.  If  the  corresponding
       entry  in  specs has type TK_CONFIG_SYNONYM, then the list
       will contain two values:	 the argvName for the  entry  and
       the  dbName  (synonym name).  Otherwise the list will con-
       tain five values:  argvName,  dbName,  dbClass,	defValue,
       and current value.  The current value is computed from the
       appropriate field of widgRec by	calling	 procedures  like
       Tk_NameOfColor.

       If  the argvName argument to Tk_ConfigureInfo is non-NULL,
       then it indicates a  single  option,  and  information  is
       returned	 only  for  that  option.   The	 string placed in
       interp->result will be a list containing two or five  val-
       ues  as	described  above;   this will be identical to the
       corresponding sublist that would	 have  been  returned  if
       argvName had been NULL.

       The flags argument to Tk_ConfigureInfo is used to restrict
       the specs entries to  consider,	just  as  for  Tk_Config-
       ureWidget.

TK_CONFIGUREVALUE
       Tk_ConfigureValue takes arguments similar to Tk_Configure-
       Info; instead of returning  a  list  of	values,	 it  just
       returns	the current value of the option given by argvName
       (argvName must not be NULL).  The  value	 is  returned  in
       interp->result and TCL_OK is normally returned as the pro-
       cedure's result.	 If an error occurs in	Tk_ConfigureValue
       (e.g.,  argvName is not a valid option name), TCL_ERROR is
       returned and an error message is left  in  interp->result.
       This  procedure is typically called to implement cget wid-
       get commands.

TK_FREEOPTIONS
       The Tk_FreeOptions procedure may be invoked during  widget
       cleanup	to  release  all of the resources associated with
       configuration options.  It scans	 through  specs	 and  for
       each  entry  corresponding  to  a  resource  that  must be
       explicitly freed (e.g. those with  type	TK_CONFIG_COLOR),
       it  frees the resource in the widget record.  If the field
       in the widget record doesn't refer to a resource (e.g.  it
       contains	 a  null  pointer)  then no resource is freed for
       that entry.  After freeing a resource, Tk_FreeOptions sets
       the corresponding field of the widget record to null.

CUSTOM OPTION TYPES
       Applications  can  extend the built-in configuration types
       with additional configuration types by writing  procedures
       to  parse  and  print options of the a type and creating a
       structure pointing to those procedures:
	      typedef struct Tk_CustomOption {

Tk			       4.1			       11

Tk_ConfigureWidget(3) Tk Library Procedures Tk_ConfigureWidget(3)

		Tk_OptionParseProc *parseProc;
		Tk_OptionPrintProc *printProc;
		ClientData clientData;
	      } Tk_CustomOption;

	      typedef int Tk_OptionParseProc(
		ClientData clientData,
		Tcl_Interp *interp,
		Tk_Window tkwin,
		char *value,
		char *widgRec,
		int offset);

	      typedef char *Tk_OptionPrintProc(
		ClientData clientData,
		Tk_Window tkwin,
		char *widgRec,
		int offset,
		Tcl_FreeProc **freeProcPtr);
       The Tk_CustomOption structure contains three fields, which
       are  pointers to the two procedures and a clientData value
       to be passed to those procedures when  they  are	 invoked.
       The  clientData value typically points to a structure con-
       taining information that is needed by the procedures  when
       they are parsing and printing options.

       The  parseProc  procedure is invoked by Tk_ConfigureWidget
       to parse a string and store the	resulting  value  in  the
       widget  record.	 The clientData argument is a copy of the
       clientData field in the	Tk_CustomOption	 structure.   The
       interp argument points to a Tcl interpreter used for error
       reporting.  Tkwin is a  copy  of	 the  tkwin  argument  to
       Tk_ConfigureWidget.    The  value  argument  is	a  string
       describing the value for the option;  it could  have  been
       specified  explicitly in the call to Tk_ConfigureWidget or
       it could come from  the	option	database  or  a	 default.
       Value  will never be a null pointer but it may point to an
       empty string.  RecordPtr is the same as the widgRec  argu-
       ment to Tk_ConfigureWidget;  it points to the start of the
       widget record to modify.	 The last argument, offset, gives
       the offset in bytes from the start of the widget record to
       the location where the option value is to be placed.   The
       procedure  should translate the string to whatever form is
       appropriate for the option and store the value in the wid-
       get  record.   It should normally return TCL_OK, but if an
       error occurs in translating the string to a value then  it
       should  return  TCL_ERROR  and  store  an error message in
       interp->result.

       The printProc procedure is called by  Tk_ConfigureInfo  to
       produce a string value describing an existing option.  Its
       clientData, tkwin, widgRec, and offset arguments all  have
       the  same  meaning  as  for Tk_OptionParseProc procedures.
       The printProc procedure should examine  the  option  whose

Tk			       4.1			       12

Tk_ConfigureWidget(3) Tk Library Procedures Tk_ConfigureWidget(3)

       value  is  stored  at  offset in widgRec, produce a string
       describing that	option,	 and  return  a	 pointer  to  the
       string.	 If the string is stored in dynamically-allocated
       memory, then the procedure must set  *freeProcPtr  to  the
       address	of  a procedure to call to free the string's mem-
       ory;  Tk_ConfigureInfo will call this procedure when it is
       finished	 with the string.  If the result string is stored
       in static memory then printProc need not do anything  with
       the freeProcPtr argument.

       Once  parseProc	and  printProc	have  been  defined and a
       Tk_CustomOption	structure  has	been  created  for  them,
       options	of  this new type may be manipulated with Tk_Con-
       figSpec entries whose type fields are TK_CONFIG_CUSTOM and
       whose customPtr fields point to the Tk_CustomOption struc-
       ture.

EXAMPLES
       Although the explanation of Tk_ConfigureWidget  is  fairly
       complicated,  its  actual  use  is pretty straightforward.
       The easiest way to get started is to copy the code from an
       existing	 widget.   The	library	 implementation of frames
       (tkFrame.c) has a  simple  configuration	 table,	 and  the
       library	implementation of buttons (tkButton.c) has a much
       more complex table that uses many of the	 fancy	specFlags
       mechanisms.

KEYWORDS
       anchor, bitmap, boolean, border, cap style, color, config-
       uration options, cursor, custom,	 double,  font,	 integer,
       join style, justify, millimeters, pixels, relief, synonym,
       uid

Tk			       4.1			       13

[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server BSDOS

List of man pages available for BSDOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net