Tk_CreateFocusHandler — C Library Procedures

NAME

Tk_CreateFocusHandler − arrange for callback when focus enters or leaves window

SYNOPSIS

#include <tk.h>
void
Tk_CreateFocusHandler(tkwin, proc, clientData)

ARGUMENTS

Tk_Windowtkwin(in) Token for window.

Tk_FocusProc∗proc(in) Procedure to invoke whenever tkwin receives or loses the input focus. NULL cancels any previously-existing focus handler.

ClientDataclientData(in) Arbitrary one-word value to pass to proc.

DESCRIPTION

Tk_CreateFocusHandler arranges for a particular procedure (proc) to be invoked whenever the focus enters or leaves a particular window (tkwin). Proc should have arguments and result that match the type Tk_FocusProc:

typedef void Tk_FocusProc(

ClientData clientData,
int gotFocus);

The clientData parameter to proc will be a copy of the clientData argument passed to Tk_CreateFocusHandler. Typically, clientData points to a data structure containing application-specific information about how to react to the change of focus. The gotFocus argument is 1 if tkwin is receiving the focus and 0 if it is losing the focus. Typically, proc will change some visual cue on the display when tkwin gets or loses the focus (e.g. display a caret or vertical bar at the current insert point when tkwin has the focus, and erase it when tkwin loses the focus).

The standard Tk focus mechanism is used to control the calling of focus handlers. The focus is considered to be in window tkwin whenever two conditions hold: (a) the mouse pointer is contained in any top-level window of tkwin’s application; and (b) the most recent call to the focus command for that application specified tkwin’s path name. Thus focus handlers are called when the pointer moves in and out of windows, and also when the focus command is invoked.

There may only be one focus handler declared for a window at a time. If Tk_CreateFocusHandler is called when there already exists a focus handler for tkwin, the existing focus handler is replaced (its proc will not be invoked anymore).

KEYWORDS

focus, window