XtSetSensitive()XtSetSensitive()NameXtSetSensitive - 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.
DescriptionXtSetSensitive() 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 insensi‐
tive. 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 insensi‐
tive 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 XtIsSensi‐
tive().
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 XtSet‐
Sensitive() 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 fol‐
lowing in your app-defaults file:
*TransientShell.ancestorSensitive: True
Background
Widget sensitivity is controlled by the sensitive and ancestor_sensi‐
tive 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, distin‐
guish these two cases visually.
XtSetSensitive() first calls XtSetValues() on the current widget to set
the
XtNsensitive resource to the value specified by sensitive. If sensi‐
tive 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 XtSetSensitive() 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 AlsoXtGetValues(1), XtIsSensitive(1), XtSetValues(1).
Xt - Resource Management XtSetSensitive()
