Tk_RestoreSavedOptions man page on OpenServer

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

Tk_SetOptions(3)	     Tk Library Procedures	      Tk_SetOptions(3)

______________________________________________________________________________

NAME
       Tk_CreateOptionTable,  Tk_DeleteOptionTable,  Tk_InitOptions, Tk_SetOp-
       tions, Tk_FreeSavedOptions, Tk_RestoreSavedOptions,  Tk_GetOptionValue,
       Tk_GetOptionInfo,  Tk_FreeConfigOptions, Tk_Offset - process configura-
       tion options

SYNOPSIS
       #include <tk.h>

       Tk_OptionTable
       Tk_CreateOptionTable(interp, templatePtr)

       Tk_DeleteOptionTable(optionTable)

       int
       Tk_InitOptions(interp, recordPtr, optionTable, tkwin)

       int
       Tk_SetOptions(interp, recordPtr, optionTable, objc, objv, tkwin, savePtr, maskPtr)

       Tk_FreeSavedOptions(savedPtr)

       Tk_RestoreSavedOptions(savedPtr)

       Tcl_Obj *
       Tk_GetOptionValue(interp, recordPtr, optionTable, namePtr, tkwin)

       Tcl_Obj *
       Tk_GetOptionInfo(interp, recordPtr, optionTable, namePtr, tkwin)

       Tk_FreeConfigOptions(recordPtr, optionTable, tkwin)

       int
       Tk_Offset(type, field)

ARGUMENTS
       Tcl_Interp	 *interp	 (in)	   A  Tcl  interpreter.	  Most
						   procedures  use  this  only
						   for	returning  error  mes-
						   sages;  if  it is NULL then
						   no	error	messages   are
						   returned.  For Tk_CreateOp-
						   tionTable the value	cannot
						   be	NULL;	it  gives  the
						   interpreter	in  which  the
						   option  table will be used.

       Tk_OptionSpec	 *templatePtr	 (in)	   Points  to  an   array   of
						   static   information	  that
						   describes the configuration
						   options that are supported.
						   Used	    to	   build     a
						   Tk_OptionTable.  The infor-
						   mation pointed to  by  this
						   argument must exist for the
						   lifetime	  of	   the
						   Tk_OptionTable.

       Tk_OptionTable	 optionTable	 (in)	   Token  for an option table.
						   Must have been returned  by
						   a  previous call to Tk_Cre-
						   ateOptionTable.

       char		 *recordPtr	 (in/out)  Points  to	structure   in
						   which  values of configura-
						   tion	 options  are  stored;
						   fields  of  this record are
						   modified by procedures such
						   as  Tk_SetOptions  and read
						   by	procedures   such   as
						   Tk_GetOptionValue.

       Tk_Window	 tkwin		 (in)	   For	  options    such   as
						   TK_OPTION_COLOR, this argu-
						   ment	 indicates  the window
						   in which the option will be
						   used.   If optionTable uses
						   no	      window-dependent
						   options,  then a NULL value
						   may be  supplied  for  this
						   argument.

       int		 objc		 (in)	   Number of values in objv.

       Tcl_Obj		 *CONST objv[]	 (in)	   Command-line	 arguments for
						   setting	   configuring
						   options.

       Tk_SavedOptions	 *savePtr	 (out)	   If  not NULL, the structure
						   pointed to by this argument
						   is  filled  in with the old
						   values of any options  that
						   were	 modified and old val-
						   ues are restored  automati-
						   cally if an error occurs in
						   Tk_SetOptions.

       int		 *maskPtr	 (out)	   If  not  NULL,   the	  word
						   pointed  to	by  maskPtr is
						   filled in with the bit-wise
						   OR  of  the typeMask fields
						   for the options  that  were
						   modified.

       Tk_SavedOptions	 *savedPtr	 (in/out)  Points  to a structure pre-
						   viously   filled   in    by
						   Tk_SetOptions with old val-
						   ues of modified options.

       Tcl_Obj		 *namePtr	 (in)	   The value of this object is
						   the	name  of  a particular
						   option.  If NULL is	passed
						   to	Tk_GetOptionInfo  then
						   information is returned for
						   all	options.   Must not be
						   NULL when Tk_GetOptionValue
						   is called.

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

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

DESCRIPTION
       These  procedures  handle  most of the details of parsing configuration
       options such as those for Tk widgets.   Given  a	 description  of  what
       options are supported, these procedures handle all the details of pars-
       ing options and storing their values into a C structure associated with
       the  widget  or object. The procedures were designed primarily for wid-
       gets in Tk, but they can also be used for other kinds of	 objects  that
       have configuration options.  In the rest of this manual page ``widget''
       will be used to refer to the object whose options are being managed; in
       practice	 the  object  may not actually be a widget.  The term ``widget
       record'' is used to refer to the C-level structure in which information
       about a particular widget or object is stored.

       Note:  the  easiest way to learn how to use these procedures is to look
       at a working example.  In Tk, the simplest example  is  the  code  that
       implements the button family of widgets, which is an tkButton.c.	 Other
       examples are in tkSquare.c and tkMenu.c.

       In order to use these procedures, the code that implements  the	widget
       must contain a static array of Tk_OptionSpec structures. This is a tem-
       plate that describes the various options supported  by  that  class  of
       widget; there is a separate template for each kind of widget.  The tem-
       plate contains information such as the name of each option,  its	 type,
       its  default  value, and where the value of the option is stored in the
       widget record.  See TEMPLATES below for more detail.

       In order to process configuration options efficiently, the static  tem-
       plate  must  be augmented with additional information that is available
       only at	runtime.   The	procedure  Tk_CreateOptionTable	 creates  this
       dynamic	information  from  the	template  and returns a Tk_OptionTable
       token that describes both the static and dynamic information.   All  of
       the  other  procedures,	such  as  Tk_SetOptions, take a Tk_OptionTable
       token as argument.  Typically, Tk_CreateOptionTable is called the first
       time  that  a widget of a particular class is created and the resulting
       Tk_OptionTable is used in the future for all widgets of that class.   A
       Tk_OptionTable  may  be used only in a single interpreter, given by the
       interp argument to Tk_CreateOptionTable.	 When an option	 table	is  no
       longer  needed Tk_DeleteOptionTable should be called to free all of its
       resources.  All of the option tables for a Tcl  interpreter  are	 freed
       automatically if the interpreter is deleted.

       Tk_InitOptions  is  invoked  when  a  new  widget is created to set the
       default values for all of the widget's configuration options.   Tk_Ini-
       tOptions	 is  passed  a	token  for an option table (optionTable) and a
       pointer to a widget record (recordPtr), which is the C  structure  that
       holds  information  about this widget. Tk_InitOptions uses the informa-
       tion in the option table to choose  an  appropriate  default  for  each
       option,	then  it  stores  the  default	value directly into the widget
       record, overwriting any information that was  already  present  in  the
       widget  record.	 Tk_InitOptions	 normally returns TCL_OK.  If an error
       occurred while setting the default  values  (e.g.,  because  a  default
       value was erroneous) then TCL_ERROR is returned and an error message is
       left in interp's result if interp isn't NULL.

       Tk_SetOptions is invoked	 to  modify  configuration  options  based  on
       information  specified in a Tcl command.	 The command might be one that
       creates a new widget, or a command that modifies options on an existing
       widget.	 The  objc and objv arguments describe the values of the argu-
       ments from the Tcl command.   Objv  must	 contain  an  even  number  of
       objects:	 the first object of each pair gives the name of an option and
       the second object gives the new value for that  option.	 Tk_SetOptions
       looks  up  each	name  in optionTable, checks that the new value of the
       option conforms to the type in optionTable, and stores the value of the
       option  into  the widget record given by recordPtr.  Tk_SetOptions nor-
       mally returns TCL_OK.  If an error occurred (such as an unknown	option
       name  or	 an  illegal  option  value) then TCL_ERROR is returned and an
       error message is left in interp's result if interp isn't NULL.

       Tk_SetOptions has two additional features.  First, if the maskPtr argu-
       ment  isn't  NULL  then it points to an integer value that is filled in
       with information about the options that were modified.  For each option
       in  the	template  passed  to  Tk_CreateOptionTable there is a typeMask
       field.  The bits of this field are defined by the code that  implements
       the widget; for example, each bit might correspond to a particular con-
       figuration option.  Alternatively, bits	might  be  used	 functionally.
       For  example,  one  bit	might  be used for redisplay: all options that
       affect the widget's display, such that changing the option requires the
       widget  to  be redisplayed, might have that bit set.  Another bit might
       indicate that the geometry of the widget must be recomputed, and so on.
       Tk_SetOptions  OR's  together  the typeMask fields from all the options
       that were modified and returns this value at *maskPtr; the  caller  can
       then  use  this information to optimize itself so that, for example, it
       doesn't redisplay the widget if the modified options don't  affect  the
       widget's appearance.

       The  second  additional	feature	 of Tk_SetOptions has to do with error
       recovery.  If an error occurs while processing  configuration  options,
       this feature makes it possible to restore all the configuration options
       to their previous values.  Errors can  occur  either  while  processing
       options	in  Tk_SetOptions  or  later in the caller.  In many cases the
       caller does additional  processing  after  Tk_SetOptions	 returns;  for
       example,	 it might use an option value to set a trace on a variable and
       may detect an error if the variable is an array instead	of  a  scalar.
       Error  recovery	is  enabled  by	 passing  in  a non-NULL value for the
       savePtr argument to Tk_SetOptions; this	should	be  a  pointer	to  an
       uninitialized   Tk_SavedOptions	 structure   on	 the  caller's	stack.
       Tk_SetOptions overwrites the  structure	pointed	 to  by	 savePtr  with
       information  about the old values of any options modified by the proce-
       dure.  If Tk_SetOptions	returns	 successfully,	the  caller  uses  the
       structure  in  one of two ways.	If the caller completes its processing
       of the new options without any errors, then it must pass the  structure
       to  Tk_FreeSavedOptions	so  that  the old values can be freed.	If the
       caller detects an error in its processing of the new options,  then  it
       should  pass  the  structure to Tk_RestoreSavedOptions, which will copy
       the old values back into the widget record and free the new values.  If
       Tk_SetOptions  detects  an  error  then	it  automatically restores any
       options that had already been modified and leaves *savePtr in an	 empty
       state:	the   caller  need  not	 call  either  Tk_FreeSavedOptions  or
       Tk_RestoreSavedOptions.	If the savePtr argument	 to  Tk_SetOptions  is
       NULL then Tk_SetOptions frees each old option value immediately when it
       sets a new value for the option.	 In this case, if an error  occurs  in
       the  third  option,  the old values for the first two options cannot be
       restored.

       Tk_GetOptionValue returns the current value of a	 configuration	option
       for  a particular widget.  The namePtr argument contains the name of an
       option; Tk_GetOptionValue uses optionTable to  lookup  the  option  and
       extract	its value from the widget record pointed to by recordPtr, then
       it returns an object containing that value.  If an error occurs	(e.g.,
       because	namePtr contains an unknown option name) then NULL is returned
       and an error message is left in interp's result unless interp is	 NULL.

       Tk_GetOptionInfo	 returns  information about configuration options in a
       form suitable for configure widget commands.  If the  namePtr  argument
       is not NULL, it points to an object that gives the name of a configura-
       tion option; Tk_GetOptionInfo returns an object containing a list  with
       five  elements,	which  are  the name of the option, the name and class
       used for the option in the option database, the default value  for  the
       option,	and the current value for the option.  If the namePtr argument
       is NULL, then Tk_GetOptionInfo returns information about all options in
       the  form  of a list of lists; each sublist describes one option.  Syn-
       onym options are handled differently depending on  whether  namePtr  is
       NULL:  if  namePtr is NULL then the sublist for each synonym option has
       only two elements, which are the name of the option and the name of the
       other option that it refers to; if namePtr is non-NULL and names a syn-
       onym option then the object returned is the five-element list  for  the
       other  option  that  the	 synonym refers to.  If an error occurs (e.g.,
       because namePtr contains an unknown option name) then NULL is  returned
       and  an error message is left in interp's result unless interp is NULL.

       Tk_FreeConfigOptions must be invoked when  a  widget  is	 deleted.   It
       frees  all  of  the  resources associated with any of the configuration
       options defined in recordPtr by optionTable.

       The Tk_Offset macro is provided as a safe way of generating the objOff-
       set  and internalOffset values for entries in Tk_OptionSpec structures.
       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.

TEMPLATES
       The array of Tk_OptionSpec structures  passed  to  Tk_CreateOptionTable
       via  its	 templatePtr argument describes the configuration options sup-
       ported by a particular class of widgets.	 Each structure specifies  one
       configuration option and has the following fields:
	      typedef struct {
		Tk_OptionType type;
		char *optionName;
		char *dbName;
		char *dbClass;
		char *defValue;
		int objOffset;
		int internalOffset;
		int flags;
		ClientData clientData;
		int typeMask;
	      } Tk_OptionSpec;
       The  type  field	 indicates  what  kind of configuration option this is
       (e.g. TK_OPTION_COLOR for a color value, or TK_OPTION_INT for an	 inte-
       ger  value).   Type  determines	how  the value of the option is parsed
       (more on this below).  The optionName field is a string such  as	 -font
       or  -bg;	 it is the name used for the option in Tcl commands and passed
       to procedures via the  objc  or	namePtr	 arguments.   The  dbName  and
       dbClass	fields	are  used by Tk_InitOptions to look up a default value
       for this option in the option database; if  dbName  is  NULL  then  the
       option  database	 is  not  used by Tk_InitOptions for this option.  The
       defValue field specifies a default value for this configuration	option
       if  no  value  is  specified in the option database.  The objOffset and
       internalOffset fields indicate where to store the value of this	option
       in  widget  records  (more on this below); values for the objOffset and
       internalOffset fields should always be  generated  with	the  Tk_Offset
       macro.	The flags field contains additional information to control the
       processing of  this  configuration  option  (see	 below	for  details).
       ClientData  provides  additional	 type-specific	data needed by certain
       types.  For instance, for TK_OPTION_COLOR types, clientData is a string
       giving  the  default  value  to	use  on	 monochrome displays.  See the
       descriptions of the different types below for details.  The last field,
       typeMask,  is  used  by Tk_SetOptions to return information about which
       options were modified; see the description of Tk_SetOptions  above  for
       details.

       When Tk_InitOptions and Tk_SetOptions store the value of an option into
       the widget record, they can do it  in  either  of  two  ways.   If  the
       objOffset  field of the Tk_OptionSpec is greater than or equal to zero,
       then the value of the option is stored as a (Tcl_Obj *) at the location
       in  the	widget record given by objOffset.  If the internalOffset field
       of the Tk_OptionSpec is greater than or equal to zero, then  the	 value
       of  the	option is stored in a type-specific internal form at the loca-
       tion in the widget record given by internalOffset.  For example, if the
       option's	 type  is  TK_OPTION_INT then the internal form is an integer.
       If the objOffset or internalOffset field is negative then the value  is
       not  stored  in that form.  At least one of the offsets must be greater
       than or equal to zero.

       The flags field consists of one or more bits ORed together.  At present
       only a single flag is supported: TK_OPTION_NULL_OK.  If this bit is set
       for an option then an empty string will be accepted as  the  value  for
       the  option  and	 the resulting internal form will be a NULL pointer, a
       zero value, or None, depending on the type of the option.  If the  flag
       is not set then empty strings will result in errors.  TK_OPTION_NULL_OK
       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 par-
       ent's cursor.  Not all option types support the TK_OPTION_NULL_OK flag;
       for  those that do, there is an explicit indication of that fact in the
       descriptions below.

       The type field of each Tk_OptionSpec structure determines how to	 parse
       the  value  of that configuration option. The legal value for type, and
       the corresponding actions, are described below.	If the type requires a
       tkwin  value  to be passed into procedures like Tk_SetOptions, or if it
       uses the clientData field of the Tk_OptionSpec, then  it	 is  indicated
       explicitly;  if	not  mentioned,	 the  type  requires neither tkwin nor
       clientData.

       TK_OPTION_ANCHOR
	      The value must be a standard anchor position such as ne or  cen-
	      ter.   The  internal  form  is  a	 Tk_Anchor value like the ones
	      returned by Tk_GetAnchorFromObj.

       TK_OPTION_BITMAP
	      The value must be a standard Tk bitmap name. The	internal  form
	      is  a  Pixmap token like the ones returned by Tk_AllocBitmapFro-
	      mObj.  This option type requires tkwin to be supplied to	proce-
	      dures    such    as   Tk_SetOptions,   and   it	supports   the
	      TK_OPTION_NULL_OK flag.

       TK_OPTION_BOOLEAN
	      The value must be a standard boolean value such as true  or  no.
	      The internal form is an integer with value 0 or 1.

       TK_OPTION_BORDER
	      The  value must be a standard color name such as red or #ff8080.
	      The internal form is a Tk_3DBorder token like the ones  returned
	      by  Tk_Alloc3DBorderFromObj.  This option type requires tkwin to
	      be supplied to procedures such as Tk_SetOptions, and it supports
	      the TK_OPTION_NULL_OK flag.

       TK_OPTION_COLOR
	      The  value must be a standard color name such as red or #ff8080.
	      The internal form is an (XColor *) token like the ones  returned
	      by  Tk_AllocColorFromObj.	 This option type requires tkwin to be
	      supplied to procedures such as Tk_SetOptions,  and  it  supports
	      the TK_OPTION_NULL_OK flag.

       TK_OPTION_CURSOR
	      The  value must be a standard cursor name such as cross or @foo.
	      The internal form is a Tk_Cursor token like the ones returned by
	      Tk_AllocCursorFromObj.   This  option  type requires tkwin to be
	      supplied to procedures  such  as	Tk_SetOptions,	and  when  the
	      option  is  set  the cursor for the window is changed by calling
	      XDefineCursor.	This   option	type   also    supports	   the
	      TK_OPTION_NULL_OK flag.

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

       TK_OPTION_DOUBLE
	      The string value must be a floating-point number in  the	format
	      accepted	by  strtol.   The  internal  form is a C double value.
	      This option type supports the TK_OPTION_NULL_OK flag; if a  NULL
	      value is set, the internal representation is set to zero.

       TK_OPTION_END
	      Marks  the  end  of the template.	 There must be a Tk_OptionSpec
	      structure with type TK_OPTION_END at the end of  each  template.
	      If  the  clientData  field of this structure isn't NULL, then it
	      points to an  additional	array  of  Tk_OptionSpec's,  which  is
	      itself terminated by another TK_OPTION_END entry.	 Templates may
	      be chained  arbitrarily  deeply.	 This  feature	allows	common
	      options to be shared by several widget classes.

       TK_OPTION_FONT
	      The  value  must	be a standard font name such as Times 16.  The
	      internal form is a Tk_Font handle	 like  the  ones  returned  by
	      Tk_AllocFontFromObj.  This option type requires tkwin to be sup-
	      plied to procedures such as Tk_SetOptions, and it	 supports  the
	      TK_OPTION_NULL_OK flag.

       TK_OPTION_INT
	      The  string  value  must be an integer in the format accepted by
	      strtol (e.g. 0 and 0x prefixes may be used to specify  octal  or
	      hexadecimal  numbers,  respectively).   The internal form is a C
	      int value.

       TK_OPTION_JUSTIFY
	      The value must be a standard justification value such  as	 left.
	      The  internal  form  is a Tk_Justify like the values returned by
	      Tk_GetJustifyFromObj.

       TK_OPTION_PIXELS
	      The value must specify a screen distance such as 2i or 6.4.  The
	      internal	form  is an integer value giving a distance in pixels,
	      like the values returned by Tk_GetPixelsFromObj.	Note:  if  the
	      objOffset	 field	isn't used then information about the original
	      value of this option will be lost.   See	OBJOFFSET  VS.	INTER-
	      NALOFFSET	 below	for  details.	This  option type supports the
	      TK_OPTION_NULL_OK flag; if a NULL value  is  set,	 the  internal
	      representation is set to zero.

       TK_OPTION_RELIEF
	      The  value must be standard relief such as raised.  The internal
	      form is an integer relief value such as TK_RELIEF_RAISED.	  This
	      option  type  supports  the TK_OPTION_NULL_OK flag; if the empty
	      string is specified as the value for  the	 option,  the  integer
	      relief value is set to TK_RELIEF_NULL.

       TK_OPTION_STRING
	      The  value  may  be any string.  The internal form is a (char *)
	      pointer that points to  a	 dynamically  allocated	 copy  of  the
	      value.  This option type supports the TK_OPTION_NULL_OK flag.

       TK_OPTION_STRING_TABLE
	      For  this	 type,	clientData is a pointer to an array of strings
	      suitable for passing to Tcl_GetIndexFromObj.  The value must  be
	      one of the strings in the table, or a unique abbreviation of one
	      of the strings.  The internal form  is  an  integer  giving  the
	      index  into  the	table  of the matching string, like the return
	      value from Tcl_GetStringFromObj.

       TK_OPTION_SYNONYM
	      This type is used to provide alternative	names  for  an	option
	      (for  example,  -bg is often used as a synonym for -background).
	      The clientData field is a (char *) pointer that gives  the  name
	      of  another  option  in  the  same  table.  Whenever the synonym
	      option is used, the information from the other  option  will  be
	      used instead.

       TK_OPTION_WINDOW
	      The  value  must	be a window path name.	The internal form is a
	      Tk_Window token for the window.  This option type requires tkwin
	      to  be supplied to procedures such as Tk_SetOptions (in order to
	      identify the application), and it supports the TK_OPTION_NULL_OK
	      flag.

STORAGE MANAGEMENT ISSUES
       If a field of a widget record has its offset stored in the objOffset or
       internalOffset field of a Tk_OptionSpec structure then  the  procedures
       described  here	will handle all of the storage allocation and resource
       management issues associated with the field.   When  the	 value	of  an
       option is changed, Tk_SetOptions (or Tk_FreeSavedOptions) will automat-
       ically free any resources  associated  with  the	 old  value,  such  as
       Tk_Fonts for TK_OPTION_FONT options or dynamically allocated memory for
       TK_OPTION_STRING options.  For an option stored as an object using  the
       objOffset field of a Tk_OptionSpec, the widget record shares the object
       pointed to by the objv value from the call to Tk_SetOptions.  The  ref-
       erence  count  for  this	 object is incremented when a pointer to it is
       stored in the widget record and decremented when the  option  is	 modi-
       fied.   When  the  widget  is  deleted  Tk_FreeConfigOptions  should be
       invoked; it will free the resources associated  with  all  options  and
       decrement reference counts for any objects.

       However, the widget code is responsible for storing NULL or None in all
       pointer and token  fields  before  invoking  Tk_InitOptions.   This  is
       needed  to  allow proper cleanup in the rare case where an error occurs
       in Tk_InitOptions.

OBJOFFSET VS. INTERNALOFFSET
       In most cases it is simplest to	use  the  internalOffset  field	 of  a
       Tk_OptionSpec  structure	 and  not the objOffset field.	This makes the
       internal form of the value immediately available to the widget code  so
       the  value  doesn't have to be extracted from an object each time it is
       used.  However, there are two cases where the objOffset field  is  use-
       ful.   The  first  case is for TK_OPTION_PIXELS options.	 In this case,
       the internal form is an integer pixel value that is valid  only	for  a
       particular screen.  If the value of the option is retrieved, it will be
       returned as a simple number.  For example, after the command .b config-
       ure -borderwidth 2m, the command .b configure -borderwidth might return
       7, which is the integer pixel  value  corresponding  to	2m.   Unfortu-
       nately,	this  loses  the  original screen-independent value.  Thus for
       TK_OPTION_PIXELS options it is better to use the objOffset  field.   In
       this  case  the	original value of the option is retained in the object
       and can be returned when the option is retrieved.  In most cases it  is
       convenient  to  use the internalOffset field field as well, so that the
       integer value is immediately available  for  use	 in  the  widget  code
       (alternatively,	Tk_GetPixelsFromObj can be used to extract the integer
       value from the object whenever it is needed).   Note:  the  problem  of
       losing  information  on	retrievals  exists  only  for TK_OPTION_PIXELS
       options.

       The second reason to use the objOffset field is in order	 to  implement
       new types of options not supported by these procedures.	To implement a
       new type of option, you can use TK_OPTION_STRING as  the	 type  in  the
       Tk_OptionSpec  structure and set the objOffset field but not the inter-
       nalOffset field.	 Then, after calling Tk_SetOptions, convert the object
       to internal form yourself.

CUSTOM OPTION TYPES
       Applications  can  extend  the  built-in configuration types with addi-
       tional configuration types by writing procedures to parse, print, free,
       and  restore saved copies of the type and creating a structure pointing
       to those procedures:
	      typedef struct Tk_ObjCustomOption {
		char *name;
		Tk_CustomOptionSetProc *setProc;
		Tk_CustomOptionGetProc *getProc;
		Tk_CustomOptionRestoreProc *restoreProc;
		Tk_CustomOptionFreeProc *freeProc;
		ClientData clientData;
	      } Tk_ObjCustomOption;

	      typedef int Tk_CustomOptionSetProc(
		ClientData clientData,
		Tcl_Interp *interp,
		Tk_Window tkwin,
		Tcl_Obj **valuePtr,
		char *recordPtr,
		int internalOffset,
		char *saveInternalPtr,
		int flags);

	      typedef Tcl_Obj *Tk_CustomOptionGetProc(
		ClientData clientData,
		Tk_Window tkwin,
		char *recordPtr,
		int internalOffset);

	      typedef void Tk_CustomOptionRestoreProc(
		ClientData clientData,
		Tk_Window tkwin,
		char *internalPtr,
		char *saveInternalPtr);

	      typedef void Tk_CustomOptionFreeProc(
		ClientData clientData,
		Tk_Window tkwin,
		char *internalPtr);

       The Tk_ObjCustomOption structure contains six fields: a	name  for  the
       custom  option  type; pointers to the four procedures; and a clientData
       value to be passed to those procedures  when  they  are	invoked.   The
       clientData value typically points to a structure containing information
       that is needed by the procedures when they  are	parsing	 and  printing
       options.	  RestoreProc  and  freeProc  may  be NULL, indicating that no
       function should be called for those operations.

       The setProc procedure is invoked by Tk_SetOptions to convert a  Tcl_Obj
       into  an	 internal  representation and store the resulting value in the
       widget record.  The arguments are:

	      clientData
		     A copy of the clientData field in the  Tk_ObjCustomOption
		     structure.

	      interp A pointer to a Tcl interpreter, used for error reporting.

	      Tkwin  A copy of the tkwin argument to Tk_SetOptions

	      valuePtr
		     A pointer to a reference to a Tcl_Obj describing the  new
		     value  for	 the  option;  it  could  have	been specified
		     explicitly in the call to Tk_SetOptions or it could  come
		     from  the option database or a default.  If the objOffset
		     for the option  is	 non-negative  (the  option  value  is
		     stored  as	 a  (Tcl_Obj  *)  in  the  widget record), the
		     Tcl_Obj pointer referenced by  valuePtr  is  the  pointer
		     that  will	 be  stored  at	 the objOffset for the option.
		     SetProc may modify the value if necessary;	 for  example,
		     setProc  may  change  the	value  to  NULL to support the
		     TK_OPTION_NULL_OK flag.

	      recordPtr
		     A pointer to the start of the widget record to modify.

	      internalOffset
		     Offset in bytes from the start of the  widget  record  to
		     the  location  where  the	internal representation of the
		     option value is to be placed.

	      saveInternalPtr
		     A pointer	to  storage  allocated	in  a  Tk_SavedOptions
		     structure for the internal representation of the original
		     option value.  Before  setting  the  option  to  its  new
		     value, setProc should set the value referenced by saveIn-
		     ternalPtr to the original value of the option in order to
		     support Tk_RestoreSavedOptions.

	      flags  A	copy of the flags field in the Tk_OptionSpec structure
		     for the option

       SetProc returns a standard Tcl result:  TCL_OK to  indicate  successful
       processing,  or	TCL_ERROR to indicate a failure of any kind.  An error
       message may be left in the Tcl interpreter given by interp in the  case
       of an error.

       The getProc procedure is invoked by Tk_GetOptionValue and Tk_GetOption-
       Info to retrieve a Tcl_Obj representation of the	 internal  representa-
       tion of an option.  The clientData argument is a copy of the clientData
       field in the Tk_ObjCustomOption structure.  Tkwin  is  a	 copy  of  the
       tkwin  argument to Tk_GetOptionValue or Tk_GetOptionInfo.  RecordPtr is
       a pointer to the beginning of the widget record to query.  InternalOff-
       set  is	the offset in bytes from the beginning of the widget record to
       the location where the internal representation of the option  value  is
       stored.	 GetProc  must	return a pointer to a Tcl_Obj representing the
       value of the option.

       The restoreProc	procedure  is  invoked	by  Tk_RestoreSavedOptions  to
       restore	a  previously saved internal representation of a custom option
       value.  The clientData argument is a copy of the	 clientData  field  in
       the  Tk_ObjCustomOption	structure.  Tkwin is a copy of the tkwin argu-
       ment  to	 Tk_GetOptionValue  or	Tk_GetOptionInfo.   InternalPtr	 is  a
       pointer	to  the	 location  where internal representation of the option
       value is stored.	 SaveInternalPtr is a  pointer	to  the	 saved	value.
       RestoreProc  must copy the value from saveInternalPtr to internalPtr to
       restore the value.  RestoreProc need not	 free  any  memory  associated
       with either internalPtr or saveInternalPtr; freeProc will be invoked to
       free that memory if necessary.  RestoreProc has no return value.

       The freeProc procedure is invoked by Tk_SetOptions and  Tk_FreeSavedOp-
       tions  to free any storage allocated for the internal representation of
       a custom option.	 The clientData argument is a copy of  the  clientData
       field  in  the  Tk_ObjCustomOption  structure.	Tkwin is a copy of the
       tkwin argument to Tk_GetOptionValue or  Tk_GetOptionInfo.   InternalPtr
       is  a  pointer to the location where the internal representation of the
       option value is stored.	The freeProc must free any storage  associated
       with the option.	 FreeProc has no return value.

KEYWORDS
       anchor,	bitmap,	 boolean, border, color, configuration option, cursor,
       double, font, integer, justify, pixels, relief, screen  distance,  syn-
       onym

Tk				      8.1		      Tk_SetOptions(3)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server OpenServer

List of man pages available for OpenServer

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