hpux man page for xtsetsensitive

XtSetSensitive()														  XtSetSensitive()

Name
  XtSetSensitive - set the sensitivity state of a widget.

Synopsis
  void XtSetSensitive(w, sensitive)
	 Widget w;
	 Boolean sensitive;

Inputs
  w	    Specifies the widget.

  sensitive Specifies whether the widget should receive keyboard, pointer, and focus events.

Description
  XtSetSensitive()  sets  the  sensitivity  state of w.  If sensitive is False, then w and all of its descendants will become insensitive and
  will not have any KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify, EnterNotify, LeaveNotify,  FocusIn,  or  FocusOut  events
  dispatched	       to	    them.	     If 	  sensitive	      is	  True, 	 and	      if	  w's
  XtNancestorSensitive resource is also True, then w and its children will be made sensitive again, except for any children that have explic-
  itly been made insensitive by calling XtSetSensitive() or by setting their XtNsensitive resource.

  See  the  "Background"  section below for more details on the algorithm followed by XtSetSensitive() and on how the sensitivity of a widget
  affects the sensitivity of its descendants.

Usage
  Many widgets will display themselves differently when they are insensitive.  A common approach is to draw themselves through a stipple mask
  so  that  they appear grayed-out.  XtSetSensitive() uses XtSetValues() when it sets the XtNsensitive and XtNancestorSensitive resources, so
  widgets can check for changes to these resources in their set_values() method and take the appropriate action.

  In an application, it is good style to make any widget insensitive if it does not currently make sense for the user to select it.   A  menu
  item labeled "Delete Selected Items", for example, should be insensitive if there are not any currently selected items.  A button that pops
  up a modal dialog box should be made insensitive while that dialog box is popped up, so that the user cannot attempt to pop it up again.

  You can test the sensitivity state of a widget by calling XtIsSensitive().

  Note that you can also set the sensitivity of a widget by setting the XtNsensitive resource directly.  It is better to  use  XtSetSensitive
  because this handles composite widgets correctly.  If you want a non-composite widget to be insensitive when it is created, you can specify
  False for XtNsensitive from a resource file or an argument list.  You can query the value of the  XtNancestorSensitive  resource,  but  you
  should never set it.

  Popup  shells  will  have  their  XtNancestorSensitive resource set to False if their parent was insensitive when they were created.	Since
  XtSetSensitive() on the parent will not modify the resource in the popup child, you should either be sure that you only create popup shells
  as children of sensitive widgets, or that you include a line like the following in your app-defaults file:

     *TransientShell.ancestorSensitive: True

Background
  Widget  sensitivity  is  controlled by the sensitive and ancestor_sensitive fields in the Core instance record.  XtNsensitive and XtNances-
  torSensitive are the resource names for these fields.  A widget can be insensitive because its sensitive field is False or because  one  of
  its ancestors is insensitive.  A widget can, but does not need to, distinguish these two cases visually.

  XtSetSensitive()	  first        calls	    XtSetValues()	 on	  the	    current	  widget       to	set	  the
  XtNsensitive resource to the value specified by sensitive.  If sensitive is False and the widget is a subclass  of  Composite,  XtSetSensi-
  tive()  recursively  propagates  the	new  value down the children tree by calling XtSetValues() on each child to set ancestor_sensitive to
  False.  If sensitive is True and the widget is a subclass of Composite and the widget's ancestor_sensitive field is True, then  XtSetSensi-
  tive()  sets	the  ancestor_sensitive  of each child to True and then recursively calls XtSetValues() on each normal descendant that is now
  sensitive to set ancestor_sensitive to True.

  XtSetSensitive() ensures that if a parent has either sensitive or ancestor_sensitive set to False, then all children	have  ancestor_sensi-
  tive set to False.

See Also
  XtGetValues(1), XtIsSensitive(1), XtSetValues(1).

Xt - Resource Management													  XtSetSensitive()