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

#include <Xol/OpenLook.h>
 . . .
Boolean OlCanAcceptFocus(

Widget w,
Time time);

#include <Xol/OpenLook.h>
 . . .
Boolean OlSetInputFocus(

Widget w);

#include <Xol/OpenLook.h>
 . . .
Boolean OlGetCurrentFocusWidget(

Widget w);

#include <Xol/OpenLook.h>
 . . .
Boolean OlHasFocus(

Widget w);

#include <Xol/OpenLook.h>
 . . .
Boolean OlGetCurrentFocusWidget(

Widget w);

DESCRIPTION

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

OlCallAcceptFocus

If widget w currently is capable of accepting input focus, focus is assigned to w and the function returns TRUE; otherwise, FALSE is returned.  Time specifies the X server time of the event that initiated this accept focus request. 

OlCanAcceptFocus

If the widget can accept focus, TRUE is returned; otherwise, FALSE is returned.  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)

Otherwise, FALSE is returned. 

OlSetInputFocus

OlSetInputFocus sets focus to a widget.  Applications should use this routine instead of XSetInputFocus since this routine checks the current focus model and before setting focus. 

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, NULL is returned. 

OlHasFocus

This function is simply a convenience function that calls OlGetCurrentFocusWidget and compares the result of that call to the supplied widget id. 

OlMoveFocus

This function moves the input focus from one widget to another and returns the id of the new focus widget.  The routine OlCallAcceptFocus is used to move the input focus.  If the function is unable to move input focus, NULL is returned. 

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.

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.

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

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.

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. 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. 

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

OL_MULTIUP Behaves like OL_MULTILEFTdirection. 

OL_MULTIDOWN Behaves like OL_MULTIRIGHT direction. 

Version 3.0  —  19 July 91