NAME

OlCallAcceptFocus, OlCanAcceptFocus, OlGetCurrentFocusWidget, OlHasFocus, OlMoveFocus, OlSetInputFocus − manipulates input focus for widgets and gadgets. 

SYNOPSIS

#include <Xol/OpenLook.h>
 . . .

Boolean OlCallAcceptFocus(

Widget w,
Time time);

  . . .
Boolean OlCanAcceptFocus(

Widget w,
Time time);

  . . .
void OlSetInputFocus(

Widget w,
int revert_to,
Time time);

  . . .
Widget OlGetCurrentFocusWidget(

Widget w);

  . . .
Boolean OlHasFocus(

Widget w);

  . . .
Widget OlMoveFocus(

Widget w,
OlVirtualName direction,
Time time);

DESCRIPTION

Each of these utility routines works with widgets or gadgets to manipulate input focus. 

OlCallAcceptFocus

OlCallAcceptFocus sets the focus to a specified widget. If widget w currently is capable of accepting input focus, OlCallAcceptFocus assigns focus to w and it returns TRUE; otherwise, it returns FALSE.  time specifies the X server time of the event that initiated this accept focus request. 

OlCanAcceptFocus

OlCanAcceptFocus tests if a widget can accept focus. If it can, it returns TRUE; otherwise, it returns FALSE. Acceptance of focus is determined by the following:

• The widget is not being destroyed.  • The widget is managed • The widget is mapped when managed (if it’s not a gadget) • The widget is realized, or for a gadget, the gadget’s parent must be realized • The widget and its ancestors are sensitive • A query window attributes is successful and the widget’s window is viewable (i.e., the window and all its ancestor windows are mapped) • The XtNmouseless resource is TRUE or the widget is a shell or text input widget. 

OlSetInputFocus

OlSetInputFocus sets focus to a widget.  Applications should use this routine instead of XSetInputFocus since it also checks for a gadget argument and assigns focus to the gadget’s parent accordingly.  If XtNmouseless is FALSE, OlSetInputFocus returns immediately unless the widget is a text input or shell widget and XtNmouseless is set to FALSE. 

OlGetCurrentFocusWidget

OlGetCurrentFocusWidget returns the id of the widget which currently has focus in the window group of the specified widget.  If no widget in the window group has focus, OlGetCurrentFocusWidget returns NULL. 

OlHasFocus

OlHasFocus returns TRUE if the specified widget has focus.  OlHasFocus just calls OlGetCurrentFocusWidget and compares the result of that call to the supplied widget id. 

OlMoveFocus

OlMoveFocus moves the input focus from one widget to another and returns the id of the new focus widget.  It calls OlCallAcceptFocus to move the input focus.  If OlCallAcceptFocus is unable to move input focus, OlMoveFocus returns NULL.  It will also return NULL if XtNmouseless is set to FALSE and the widget is not a text input widget. 

When moving input focus between widgets contained within an exclusives or non-exclusives widget, valid values for direction are:

Note: For the OL_MULTI directions below, the value of m is the value of the application resource, XtNmultiObjectCount.

OL_IMMEDIATE
Set focus to the next widget that will accept it, starting with w.

OL_MOVERIGHT
Set focus to the widget in the next column (and same row) that will accept it, starting with the first column after w’s column.  If w is located in the extreme right column, focus is set to the widget in the extreme left column of the same row.

OL_MOVELEFT
Set focus to the widget in the previous column (and same row) that will accept it, starting with the first column before w’s column.  If w is located on the extreme left column, focus is set to the widget in the extreme right column of the same row. (The widget columns are searched in reverse order.)

OL_MOVEUP
Set focus to the widget in the next row (and same column) that will accept it, starting with the first row after w’s row.  If w is located in the top row, focus is set to the widget in the bottom row of the same column. (The widget rows are searched in reverse order.)

OL_MOVEDOWN
Set focus to the widget in the previous row (and same column) that will accept it, starting with the first row before w’s row.  If w is located in the bottom row, focus is set to the widget in the top row of the same column.

OL_MULTIRIGHT
Set focus to the widget in the next column (and same row) that will accept it, starting with the first column m columns after w’s column. If m is greater than the number of objects between w and the extreme right column, focus is set to the widget in the extreme left column of the same row.

OL_MULTILEFT
Set focus to the widget in the next column (and same row) that will accept it, starting with the first column m columns before w’s column. If m is greater than the number of objects between w and the extreme left column, focus is set to the widget in the extreme right column of the same row. (The widget columns are searched in reverse order.)

OL_MULTIUP
Set focus to the widget in the next row (and same column) that will accept it, starting with the first row m rows after w’s row. If m is greater than the number of objects between w and the extreme bottom row, focus is set to the widget in the extreme top row of the same column. (The widget rows are searched in reverse order.)

OL_MULTIDOWN
Set focus to the widget in the next row (and same column) that will accept it, starting with the first row m rows before w’s row. If m is greater than the number of objects between w and the extreme bottom row, focus is set to the widget in the extreme bottom row of the same column.

OL_MULTIRIGHT
Set focus to the next object that will accept it, starting with the first object m objects after w.

OL_MULTILEFT
Set focus to the next object that will accept it, starting with the first object m objects before w. (The list is searched in reverse order.)

When moving between widgets in a base window or popup window, valid values for direction are:

OL_IMMEDIATE
Set focus to the next object that will accept it, starting with w.

OL_NEXTFIELD
Set focus to the next object that will accept it, starting with the first object after w.

OL_PREVFIELD
Set focus to the next object that will accept it, starting with the first object before w. (The list is searched in reverse order.)

OL_MOVERIGHT
Behaves like OL_NEXTFIELD direction. 

OL_MOVELEFT
Behaves like OL_PREVFIELD direction. 

OL_MOVEUP
Behaves like OL_PREVFIELD direction. 

OL_MOVEDOWN
Behaves like OL_NEXTFIELD direction. 

Version 3.0.1  —  Last change: June 92