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)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=Tk_ConfigureWidget.tk86&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help