Name

XtSetKeyboardFocus — redirect keyboard input to a normal descendant of a child widget. 

Synopsis

void XtSetKeyboardFocus(subtree, descendant)

    Widget subtree, descendant;

Arguments

subtreeSpecifies the widget to be considered the root of the subtree for which the keyboard focus is to be set.  (For example, a composite widget that is turning over all keyboard input to one of its children.) 

descendant
Specifies either the normal (non-pop-up) descendant of subtree to which keyboard events are logically directed, or None.  Note that it is not an error to specify None when no keyboard focus was previously set. 

Description

XtSetKeyboardFocus causes XtDispatchEvent to remap keyboard events that occur within subtree and to dispatch them to the specified descendant widget or to an ancestor.  If descendant is not a subclass of Core, it is replaced by its closest windowed ancestor.  (This routine should be used instead of calling the Xlib XSetInputFocus routine whenever possible.) 

When there is no modal cascade, keyboard events can be dispatched to a widget in one of five ways.  Assume the server delivered the event to the window for widget E (due to X keyboard focus, key or keyboard grabs, or pointer position). 

•If neither E nor any of E’s ancestors have redirected the keyboard focus, or if the event activated a grab for E as specified by a call to XtGrabKey with any value of owner_events or if the keyboard is actively grabbed by E with owner_events False via XtGrabKeyboard or XtGrabKey on a previous key press, the event is dispatched to E.  (This is the first way a keyboard event can be dispatched.) 

•Begin with the widget that has redirected the keyboard focus.  This widget can either be the ancestor of E that is closest to the root or E itself, if no such ancestor exists.  Then, if the target of that widget’s focus redirection has in turn redirected the keyboard focus, recursively follow this focus chain to find a widget F that has not redirected focus. 

−If E is the final focus target widget F or a descendant of F, the event is dispatched to E.  (This is the second way a keyboard event can be dispatched.) 

−If E is neither F, an ancestor of F, nor a descendant of F, and if the event activated a grab for E as specified by a call to XtGrabKey for E, then XtUngrabKeyboard is called. 

−If E is an ancestor of F, and if the event is a key press, and if either:

+E has grabbed the key with XtGrabKey and owner_events set to False, or

+E has grabbed the key with XtGrabKey, owner_events set to True, and the coordinates of the event are outside the rectangle specified by E’s geometry, then the event is dispatched to E.  (This is the third way a keyboard event can be dispatched.) 

−Otherwise, define A as the closest common ancestor of E and F.  And in this case:

+If there is an active keyboard grab for any widget via either XtGrabKeyboard or XtGrabKey on a previous key press, or if no widget between F and A (non-inclusive) has grabbed the key and modifier combination with XtGrabKey and any value of owner_events, the event is dispatched to F.  (This is the fourth way a keyboard event can be dispatched.) 

+Otherwise, the event is dispatched to the ancestor of F closest to A that has grabbed the key and modifier combination with XtGrabKey.  (This is the fifth way a keyboard event can be dispatched.) 

When there is a modal cascade, if the final destination widget as identified above is in the active subset of the cascade, the event is dispatched; otherwise, the event is re-mapped to a spring-loaded shell or discarded. 

When subtree or one of its descendants acquires the X keyboard focus, or the pointer moves into the subtree such that keyboard events would now be delivered to subtree, a FocusIn event is generated for descendant if FocusNotify events have been selected by descendant.  Similarly, when subtree loses the X keyboard focus or the keyboard focus for one of its ancestors, a FocusOut event is generated for descendant if FocusNotify events have been selected by descendant. 

Note that every widget has an accept_focus method to allow outside agents to cause a widget to get the keyboard focus.  To call a widget’s accept_focus method, use XtCallAcceptFocus.  The widget returns whether it actually took the focus or not, so that the parent can give the focus to another widget.  Widgets that need to know when they lose the keyboard focus must use the Xlib focus notification mechanism explicitly (typically by specifying translations for FocusIn and FocusOut events).  Widgets that need the keyboard focus can call XSetInputFocus explicitly.  Widgets that never want the keyboard focus should set their accept_focus procedure pointer to NULL. 

See Also

XtAddGrab(1), XtCallAcceptFocus(1), XtDispatchEvent(1),
Composite(3),
accept_focus(4).