hpux man page for set_values

set_values()															      set_values()

Name
  set_values - Object class method for handling resource changes.

Synopsis
  typedef Boolean (*XtSetValuesFunc)(Widget, Widget, Widget, ArgList,
  Cardinal *);
	 Widget current;
	 Widget request;
	 Widget set;
	 ArgList args;
	 Cardinal *num_args;

Inputs
  current   Specifies a copy of the widget made by XtSetValues() before any resources are changed or any set_values() methods are called.

  request   Specifies  a  copy	of the widget made by XtSetValues() after the resources are changed as requested, but before any set_values()
	    methods are called.

  set	    Specifies the actual widget with resources set and as modified by any superclass methods that have been called by XtSetValues().

  args	    Specifies the argument list passed to XtSetValues().

  num_args  Specifies the number of arguments in the args.

Returns
  True if the resource changes require the widget to be redrawn; False otherwise.

Description
  The set_values() method is registered on the set_values field of the Object, RectObj, or Core class part structure.  It is called by XtSet-
  Values()  to do any processing necessary when the values of widget resources are changed.  This method is chained in superclass-to-subclass
  order.

  The set argument is the widget that has had its resources set, and has been passed to the superclass set_values() methods.  Any changes  to
  resource or non-resource fields should be made to this widget.

  The  current argument is a copy of the widget that was made by XtSetValues() before any of the resource values were changed as requested in
  the argument list.  The set_values() method can compare the resource fields of set and current  to  determine  which	resources  have  been
  changed.

  The  request	argument  is  a  copy of the widget made after the resource values were set, but before XtSetValues() called any set_values()
  methods.  A set_values() method can compare fields in request, set, and current to determine whether a field was set from the argument list
  (i.e.,  at  the request of the programmer) or whether it was modified by a superclass set_values() method.  A set_values() method may over-
  ride values set by a superclass, but shouldn't change values that are explicitly requested in a call	to  XtSetValues().   See  the  "Back-
  ground" section below for more information.

  The  args  and  num_args  arguments  are the argument list that was passed to XtSetValues() (or the variable-length argument list passed to
  XtVaSetValues() transformed into an ArgList).  They can be used to set subpart resources with XtSetSubvalues(), to set values on  privately
  created children widgets, or to set any other resources that do not appear on the resource list of the widget class.	The args and num_args
  arguments were added to this method in Release 4.  Prior to Release 4, subpart and other resources had to be set in  the  set_values_hook()
  method, which is now obsolete.

  The  set_values()  method  returns  True  if	the widget needs to be redrawn in response to the resources changes, and False otherwise.  It
  should not do any redisplay itself; if any of the set_values() methods returns True, XtSetValues() will generate an Expose  event  for  the
  window by calling XClearArea(), and the widget's expose() method will be called.

  A  programmer  may  call  XtSetValues()  to  set  a  widget's geometry fields directly.  A set_values() method may also set these fields in
  response to other resource changes (if a label widget's label changes, for example, it may change its width).  Note that this is one of the
  few  times  that  a widget is allowed to directly set its own geometry fields.  The other times are in the initialize() and (obsolete) ini-
  tialize_hook() methods, and the (also obsolete) set_values_hook() method.  A set_value() method may directly set its geometry  fields,  but
  should  not do any processing based on those new values; the widget's parent must approve them first.  If any of a widget's geometry fields
  have changed after all the set_values() methods have been called, XtSetValues() will call XtMakeGeometryRequest() to actually  request  the
  geometry change from the widget's parent.  If the request is denied, XtSetValues() will reset the geometry fields to their original values.
  If the request is successful and the widget's size has changed, it will invoke the widget's resize() method.	Most widgets will receive  an
  Expose event after they are resized, and so a change to geometry fields alone is not reason enough for set_values() to return True.

  The set_values() method must not assume that the widget is realized.

  The  set_values()  method is chained in superclass-to-subclass order and cannot be inherited.  If a widget has no resources, or needs to do
  no recalculation when those resources change, it does not need a set_values() method and can specify NULL for the set_values field  of  the
  class part structure.

  See  XtSetValues(1)  for full details on the resource-setting process.  See Constraint set_values(4) for information about handling changes
  to Constraint resources.  See the "Background" section below for information about overriding values set by a superclass.

Usage
  A typical set_values() method will compare the fields of set and current for most resources defined by the class.  If a resource value  has
  changed, it will take whatever actions are appropriate.  Some common tasks of the set_values() method are:

  o  Copies resources that are passed by reference.  If a resource that was copied in the initialize() method has changed, the old value must
     be freed, and the new value copied.  String resources are typically copied by a widget so that the programmer may modify  or  free  them
     after setting them in the widget.	If this freeing and copying are done in separate procedures, the procedure to free the value can usu-
     ally be shared with the destroy() method and the procedure to copy the value can usually be shared with the initialize() method.

  o  Recomputes derived fields when the resources they are derived from have changed.  If the XtNforeground or XtNfont resource of  a  widget
     has  changed,  for  example,  it  will  probably  have to free its current shared GC and allocate a new one.  Note that resources may be
     derived from other resources.  If a widget's width can be specified through either the XtNwidth  or  the  XtNcolumns  resource,  then  a
     change  to  either  of  these resources should cause a change to the other (and if both are changed, one should take clearly defined and
     documented precedence).  If the code to calculate the values of derived fields is placed in separate procedures (code to  allocate  GCs,
     for example) those procedures can usually be shared with the initialize() method.

  o  Checks  modified resources for consistency and reasonableness.  If inconsistent or unreasonable resources are found, their values should
     be set to something valid, and a warning message should be issued.

  o  Restores the value of resource that are not allowed to be changed.  Some widgets do not allow changes to some of  their  resources.   If
     these  values  are  changed in the set_values() method, they should be reset (i.e., the set field restored from the current field) and a
     warning message should be issued.

  o  Overrides derived fields calculated by superclasses, if necessary.  If the XtNcolumns resource of a widget has changed, for  example,  a
     superclass  may have one way of deriving XtNwidth from it, and a subclass may have a different way (the subclass may have different mar-
     gins, for example).  See the "Background" section below, for further discussion about overriding values set by a superclass.

  o  Uses args and num_args to set the value of resources that do not appear in the class resource list.  These may be subpart resources (set
     with XtSetSubvalues()) or resources of children objects or widgets (set with XtSetValues()) which the widget wants to export as its own.
     (See get_values_hook(4) for a discussion and examples of widgets that export resources of child widgets or subparts.)

  o  Checks for changes to the sensitivity state of the widget.  XtSetSensitive() uses XtSetValues() to set the sensitive and ancestor_sensi-
     tive  fields  of a widget.  A widget class that displays itself differently when insensitive should check for sensitivity changes in its
     set_values() method.  See XtSetSensitive(1) for more information on widget sensitivity.

  o  Keeps track of whether the widget needs to be redrawn.  A common technique in set_values() methods is to initialize a needs_redraw vari-
     able  to  False,  and  then  set  it  to True if any resources are changed that would require the widget to be redrawn.  This value then
     becomes the return value of the method.  A widget will commonly need to be redrawn  if  colors,  fonts,  or  other  GC  components  have
     changed;  if its sensitivity state has changed; or if a resource that specifies data to be displayed (the XtNlabel resource of the Label
     widget, for example) has changed.

Example
  The following procedure is the set_values() method, slightly edited, from the Xaw List widget.  Note that it frees and reallocates its  GCs
  if  the  foreground,	background, or font have changed.  If any of a large number of resources have changed that would affect the layout or
  size of the list, it calls an internal procedure that will calculate internal layout information and set new values for the widget's geome-
  try fields.  Finally, it checks whether it has been made insensitive and if so, turns off its highlighting.

  Note	that  this  procedure (and most existing set_values() methods) names the set argument new.  "new" is a reserved word in C++, and your
  code will be more portable if you avoid using it in C.

     /* ARGSUSED */
     static Boolean SetValues(current, request, new, args, num_args)
     Widget current, request, new;
     ArgList args;
     Cardinal *num_args;
     {
	 ListWidget cl = (ListWidget) current;
	 ListWidget rl = (ListWidget) request;
	 ListWidget nl = (ListWidget) new;
	 Boolean redraw = FALSE;

	 if ((cl->list.foreground != rl->list.foreground)
	     (cl->core.background_pixel != rl->core.background_pixel)
	     (cl->list.font != rl->list.font) ) {
	     XGCValues values;
	     XGetGCValues(XtDisplay(current), cl->list.graygc, GCTile, &values);
	     XmuReleaseStippledPixmap(XtScreen(current), values.tile);
	     XtReleaseGC(current, cl->list.graygc);
	     XtReleaseGC(current, cl->list.revgc);
	     XtReleaseGC(current, cl->list.normgc);
	     GetGCs(new);
	     redraw = TRUE;
	 }

	 /* Reset row height. */
	 if ((cl->list.row_space != rl->list.row_space)
	     (cl->list.font != rl->list.font))
	     nl->list.row_height = nl->list.font->max_bounds.ascent
				 + nl->list.font->max_bounds.descent
				 + nl->list.row_space;

	 if ((cl->core.width != rl->core.width)
	     (cl->core.height != rl->core.height)
	     (cl->list.internal_width != rl->list.internal_width)
	     (cl->list.internal_height != rl->list.internal_height)
	     (cl->list.column_space != rl->list.column_space)
	     (cl->list.row_space != rl->list.row_space)
	     (cl->list.default_cols != rl->list.default_cols)
	     (	(cl->list.force_cols != rl->list.force_cols) &&
		(rl->list.force_cols != rl->list.ncols) )
	     (cl->list.vertical_cols != rl->list.vertical_cols)
	     (cl->list.longest != rl->list.longest)
	     (cl->list.nitems != rl->list.nitems)
	     (cl->list.font != rl->list.font)
	     (cl->list.list != rl->list.list)			     ) {

	   ResetList(new, TRUE, TRUE);
	   redraw = TRUE;
	 }

	 if (cl->list.list != rl->list.list)
	     nl->list.is_highlighted = nl->list.highlight = NO_HIGHLIGHT;

	 if ((cl->core.sensitive != rl->core.sensitive)
	     (cl->core.ancestor_sensitive != rl->core.ancestor_sensitive)) {
	     nl->list.highlight = NO_HIGHLIGHT;
	     redraw = TRUE;
	 }

	 if (!XtIsRealized(current))
	   return(FALSE);

	 return(redraw);
     }

Background
  Like the initialize() method, set_values() mostly deals only with the fields defined in the subclass, but it has to resolve conflicts  with
  its superclass, especially conflicts over width and height.

  Sometimes  a subclass may want to overwrite values filled in by its superclass.  In particular, size calculations of a superclass are often
  incorrect for a subclass and, in this case, the subclass must modify or recalculate fields declared and computed by its superclass.

  As an example, a subclass can visually surround its superclass display.  In this case, the width and height calculated  by  the  superclass
  set_values()	method	are too small and need to be incremented by the size of the surround.  The subclass needs to know if its superclass's
  size was calculated by the superclass or was specified explicitly.  All widgets must place themselves  into  whatever  size  is  explicitly
  given, but they should compute a reasonable size if no size is requested.  How does a subclass know the difference between a specified size
  and a size computed by a superclass?

  The request and set parameters provide the necessary information.  The request widget is a  copy  of	the  widget,  updated  as  originally
  requested.  The set widget starts with the values in the request, but it has additionally been updated by all superclass set_values() meth-
  ods called so far.  A subclass set_values() method can compare these two to resolve any potential conflicts.	The set_values() method  need
  not  refer  to  the  request	widget unless it must resolve conflicts between the current and set widgets.  Any changes the widget needs to
  make, including geometry changes, should be made in the set widget.

  In the above example, the subclass with the visual surround can see if the width and height in the request widget differ from the width and
  height  in  the  set	widget.  If so, it means that a superclass has modified these fields (which means that the programmer did not request
  them specifically) and the subclass can add its surround size to the width and height fields in the set widget.   If	the  fields  are  the
  same, the subclass must make do with the specified size.

  There  is  a	twist,	however,  on this problem of not overriding resources explicitly requested by the user.  If the programmer sets a new
  label on a Label widget, for example, the widget is allowed to change its size as needed to accommodate the label.  If the programmer  sets
  a new label and a new width at the same time, however, the new width should take precedence, regardless of the size of the label.  The dif-
  ficulty arises in the case that the programmer requests a particular width which happens to be the current width.  He is expecting  to  get
  exactly  that  width, but the set_values() method may not detect that that resource has changed, and will resize the widget as required for
  the new label.  The only general way out of this situation is to check each element of args to see if the any of  the  resources  that  are
  being set are named XtNwidth.

See Also
  XtSetValues(1),
  Core(3),
  Constraint set_values(4), set_values_almost(4), set_values_hook(4).

Xt - Intrinsics Methods 													      set_values()