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()