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

FreeBSD Manual Pages

  
 
  

home | help
Tk_ConfigureWidget(3)	     Tk	Library	Procedures	 Tk_ConfigureWidget(3)

______________________________________________________________________________

NAME
       Tk_ConfigureWidget, Tk_ConfigureInfo, Tk_ConfigureValue,	Tk_FreeOptions
       - process configuration options for widgets

SYNOPSIS
       #include	<tk.h>

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

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

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

       Tk_FreeOptions(specs, widgRec, display, flags)

ARGUMENTS
       Tcl_Interp *interp (in)	   Interpreter to use for returning error mes-
				   sages.

       Tk_Window tkwin (in)	   Window  used	to represent widget (needed to
				   set up X resources).

       const Tk_ConfigSpec *specs (in)
				   Pointer to table specifying legal  configu-
				   ration options for this widget.

       int argc	(in)		   Number of arguments in argv.

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

       char *widgRec (in/out)	   Points to widget record structure.	Fields
				   in  this  structure get modified by Tk_Con-
				   figureWidget	to hold	configuration informa-
				   tion.

       int flags (in)		   If  non-zero,  then	it  specifies an OR-ed
				   combination of flags	that control the  pro-
				   cessing   of	  configuration	  information.
				   TK_CONFIG_ARGV_ONLY causes the option data-
				   base	 and  defaults to be ignored, and flag
				   bits	TK_CONFIG_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.

       const 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  configure	widget
				   command).  If non-NULL, then	information is
				   returned only for this  option.   If	 NULL,
				   then	information is returned	for all	avail-
				   able	options.

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

DESCRIPTION
       Note: Tk_ConfigureWidget	should be replaced with	the new	Tcl_Obj	 based
       API Tk_SetOptions.  The old interface is	retained for backward compati-
       bility.

       Tk_ConfigureWidget is called to configure various aspects of a  widget,
       such  as	 colors, fonts,	border width, etc.  It is intended as a	conve-
       nience procedure	to reduce the amount of	code that must be  written  in
       individual  widget managers to handle configuration information.	 It is
       typically invoked when widgets are created, and again when the  config-
       ure  command  is	invoked	for a widget.  Although	intended primarily for
       widgets,	Tk_ConfigureWidget can be 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 configuration op-
       tions that are supported	(specs)	and a collection of command-line argu-
       ments (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_ConfigureWidget 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 interpreter interp's result in	 the  standard
       Tcl  fashion.   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 reasonable	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 specifies one configuration	option
       and has the following structure:
	      typedef struct {
		  int type;
		  const	char *argvName;
		  const	char *dbName;
		  const	char *dbClass;
		  const	char *defValue;
		  int offset;
		  int specFlags;
		  const	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	 inte-
       ger  value).   The type field indicates how to use the value of the op-
       tion (more on this below).  The argvName	field  is  a  string  such  as
       "-font"	or  "-bg", which is compared with the values in	argv (if argv-
       Name is NULL it means this is a grouped entry;  see GROUPED ENTRIES be-
       low).   The  dbName  and	dbClass	fields are used	to look	up a value for
       this option in the option database.  The	defValue field specifies a de-
       fault  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 addi-
       tional information to control the processing of this configuration  op-
       tion  (see  FLAGS  below).   The	last field, customPtr, is only used if
       type is TK_CONFIG_CUSTOM;  see CUSTOM OPTION TYPES below.

       Tk_ConfigureWidget first	processes argv to see which (if	any)  configu-
       ration  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 sec-
       ond field of the	pair contains the value	for that configuration 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_CONFIG_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 spec-
       ified in	argv or	the option database.

       Once  a	string	value  has been	determined for a configuration 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
       widgRec.	 This record is	assumed	to contain information relevant	to the
       manager of the widget;  its exact type is unknown  to  Tk_ConfigureWid-
       get.   The  offset field	of each	specs entry indicates where in widgRec
       to store	the information	about this configuration option.   You	should
       use  the	Tk_Offset macro	to generate offset values (see below for a de-
       scription of Tk_Offset).	 The location indicated	by widgRec and	offset
       will be referred	to as the "target" 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_GetCursor.  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  ac-
	      tive  cursor  for	 tkwin	by  calling XDefineCursor.  If TK_CON-
	      FIG_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  was
	      not None,	then it	is freed by passing it to Tk_FreeCursor.

       TK_CONFIG_ANCHOR
	      The value	must be	an ASCII string	identifying an anchor point in
	      one of the ways accepted by Tk_GetAnchor.	 The  string  is  con-
	      verted  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_GetBitmap.  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 previous value of the target was not 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 abbrevia-
	      tion of one of these values,  means  true;  any  of  the	values
	      "false", "no", "off", or "0", or an abbreviation of one of these
	      values, means false.  The	target is expected to be  an  integer;
	      for true values 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_CONFIG_NULL_OK is	speci-
	      fied 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 was not 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_GetCapStyle.  The string is converted
	      to  an  integer  value corresponding to the cap style by calling
	      Tk_GetCapStyle 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_GetColor.  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 previous value of the	target was not
	      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 converted 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_GetFont.  The value is	converted to a
	      Tk_Font by calling Tk_GetFont 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 NULL.  If	the previous value of the target was not NULL,
	      then it is freed by passing it to	Tk_FreeFont.

       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 hexadecimal numbers, respectively).  The	string is con-
	      verted to	an integer value and the integer is stored in the tar-
	      get.

       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 con-
	      verted to	an integer value corresponding to the  join  style  by
	      calling Tk_GetJoinStyle and the result is	stored in the target.

       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 ac-
	      ceptable	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 accept-
	      able 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_GetRelief.  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
	      Tcl_Alloc	 and  copying the value	into the dynamically-allocated
	      space.  A	pointer	to the new string 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
	      NULL.  If	the previous value of the target was not NULL, then it
	      is freed by passing it to	Tcl_Free.

       TK_CONFIG_SYNONYM
	      This type	value identifies special entries  in  specs  that  are
	      synonyms	for other entries.  If an argv value matches the argv-
	      Name of a	TK_CONFIG_SYNONYM entry, the entry  is	not  used  di-
	      rectly.  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  al-
	      lows  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_Ge-
	      tUid).  The resulting value is stored in the target.  If TK_CON-
	      FIG_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 translated 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_CON-
       FIG_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,  db-
       Class, and defValue fields).  The value will be processed several times
       (one for	each entry in the group), generating  multiple	different  re-
       sources and modifying multiple targets within widgRec.  Each of the en-
       tries 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 pre-
       cedes 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_CON-
       FIG_ARGV_ONLY  bit  set	(i.e., flags | TK_CONFIG_ARGV_ONLY != 0), then
       the option database and defValue	fields are not used.  In this case, if
       an  entry in specs does not match a field in argv then nothing happens:
       the corresponding target	is not modified.  This feature is useful  when
       the  goal is to modify certain configuration options while leaving oth-
       ers 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 considered	if the
	      display for tkwin	has more than one 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 considered	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 de-
	      scriptions 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	is not 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 en-
	      try should only be used  for  returning  the  default  value  in
	      Tk_ConfigureInfo.	  In  calls  to	 Tk_ConfigureWidget no default
	      will be supplied for entries with	this flag set;	it is  assumed
	      that the caller has already supplied a default value in the tar-
	      get 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 be-
	      fore calling Tk_ConfigureWidget.

       TK_CONFIG_OPTION_SPECIFIED
	      This bit is deprecated. It used to be set	and cleared by Tk_Con-
	      figureWidget so that callers  could  detect  what	 entries  were
	      specified	 in argv, but it was removed because it	was inherently
	      thread-unsafe. Code that wishes  to  detect  what	 options  were
	      specified	should use Tk_SetOptions instead.

       The  TK_CONFIG_MONO_ONLY	 and  TK_CONFIG_COLOR_ONLY flags are typically
       used to specify different default values	for monochrome and color  dis-
       plays.	This is	done by	creating two entries in	specs that are identi-
       cal 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	should
       have  the value TK_CONFIG_COLOR_ONLY in its specFlags and the appropri-
       ate defValue for	color displays.

       Third, it is possible to	use flags and  specFlags  together  to	selec-
       tively  disable	some  entries.	This feature is	not needed very	often.
       It is useful in cases where several similar kinds of widgets are	imple-
       mented in one place.  It	allows a single	specs table to be created with
       all the configuration options for all the widget	types.	When  process-
       ing  a  particular widget type, only entries relevant to	that type will
       be used.	 This effect is	achieved by setting 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_ConfigureWidget.  If a specs  table  is	 being
       used  for  N different widget 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_ConfigureWidget, 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 generating the	offset
       values for entries in Tk_ConfigSpec structures.	 It  takes  two	 argu-
       ments:	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 win-
       dow  (tkwin),  a	table describing the configuration options for a class
       of widgets (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 window.  The string is	placed in interpreter interp's
       result.	Under normal circumstances it returns TCL_OK;  if an error oc-
       curs  then  it returns TCL_ERROR	and the	interpreter's result will con-
       tain an error message.

       If argvName is NULL, then the value left	in the interpreter's 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 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	contain	 five  values:	 argv-
       Name,  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 indi-
       cates a single option, and information is returned only	for  that  op-
       tion.   The  string  placed  in the interpreter's result	will be	a list
       containing two or five values as	described above;  this will be identi-
       cal to the corresponding	sublist	that would have	been returned if argv-
       Name had	been NULL.

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

TK_CONFIGUREVALUE
       Tk_ConfigureValue  takes	arguments similar to Tk_ConfigureInfo; 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 re-
       turned in interpreter interp's result and TCL_OK	is  normally  returned
       as  the	procedure'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 the interpreter's result.	This procedure
       is typically called to implement	cget widget 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  does not	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	 addi-
       tional configuration types by writing procedures	to parse and print op-
       tions of	the a type and creating	a structure pointing to	 those	proce-
       dures:
	      typedef struct Tk_CustomOption {
		  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 const 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 pro-
       cedures	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.

       The  parseProc  procedure  is  invoked by Tk_ConfigureWidget to parse a
       string and store	the resulting value in the widget record.  The client-
       Data  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_Config-
       ureWidget.  The value argument is a string describing the value for the
       option;	it could have been specified explicitly	in the call to Tk_Con-
       figureWidget 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  argument  to  Tk_ConfigureWidget;
       it  points to the start of the widget record to modify.	The last argu-
       ment, 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 widget 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 interpreter interp's 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_Op-
       tionParseProc  procedures.   The	printProc procedure should examine the
       option whose value is stored at offset in widgRec, produce a string de-
       scribing	 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	memory;	 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	 argu-
       ment.

       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_ConfigSpec	 entries whose type fields are TK_CON-
       FIG_CUSTOM and whose customPtr  fields  point  to  the  Tk_CustomOption
       structure.

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 im-
       plementation 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.

SEE ALSO
       Tk_SetOptions(3)

KEYWORDS
       anchor, bitmap, boolean,	border,	cap style,  color,  configuration  op-
       tions, cursor, custom, double, font, integer, join style, justify, mil-
       limeters, pixels, relief, synonym, uid

Tk				      4.1		 Tk_ConfigureWidget(3)

NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | GROUPED ENTRIES | FLAGS | TK_OFFSET | TK_CONFIGUREINFO | TK_CONFIGUREVALUE | TK_FREEOPTIONS | CUSTOM OPTION TYPES | EXAMPLES | SEE ALSO | KEYWORDS

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

home | help