112 lines
4.8 KiB
Plaintext
112 lines
4.8 KiB
Plaintext
|
'\"
|
||
|
|
'\" Copyright (c) 1990-1994 The Regents of the University of California.
|
||
|
|
'\" Copyright (c) 1994-1995 Sun Microsystems, Inc.
|
||
|
|
'\"
|
||
|
|
'\" See the file "license.terms" for information on usage and redistribution
|
||
|
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||
|
|
'\"
|
||
|
|
'\" @(#) focus.n 1.19 95/08/12 17:35:07
|
||
|
|
'\"
|
||
|
|
.so STk-man.macros
|
||
|
|
.TH focus n 3.1 STk "Tk Built-In Commands"
|
||
|
|
.BS
|
||
|
|
'\" Note: do not modify the .SH NAME line immediately below!
|
||
|
|
.SH NAME
|
||
|
|
focus \- Manage the input focus
|
||
|
|
.SH SYNOPSIS
|
||
|
|
(\fBfocus\fR)
|
||
|
|
.sp
|
||
|
|
(\fBfocus \fIwindow\fR)
|
||
|
|
.sp
|
||
|
|
(\fBfocus \fIoption\fR ?\fIarg arg ...\fR?)
|
||
|
|
.BE
|
||
|
|
|
||
|
|
.SH DESCRIPTION
|
||
|
|
.PP
|
||
|
|
The \fBfocus\fR procedure is used to manage the Tk input focus.
|
||
|
|
At any given time, one window on each display is designated as
|
||
|
|
the \fIfocus window\fR; any key press or key release events for the
|
||
|
|
display are sent to that window.
|
||
|
|
It is normally up to the window manager to redirect the focus among the
|
||
|
|
top-level windows of a display. For example, some window managers
|
||
|
|
automatically set the input focus to a top-level window whenever
|
||
|
|
the mouse enters it; others redirect the input focus only when
|
||
|
|
the user clicks on a window.
|
||
|
|
Usually the window manager will set the focus
|
||
|
|
only to top-level windows, leaving it up to the application to
|
||
|
|
redirect the focus among the children of the top-level.
|
||
|
|
.PP
|
||
|
|
Tk remembers one focus window for each top-level (the most recent
|
||
|
|
descendant of that top-level to receive the focus); when the window
|
||
|
|
manager gives the focus
|
||
|
|
to a top-level, Tk automatically redirects it to the remembered
|
||
|
|
window. Within a top-level Tk uses an \fIexplicit\fR focus model
|
||
|
|
by default. Moving the mouse within a top-level does not normally
|
||
|
|
change the focus; the focus changes only when a widget
|
||
|
|
decides explicitly to claim the focus (e.g., because of a button
|
||
|
|
click), or when the user types a key such as Tab that moves the
|
||
|
|
focus.
|
||
|
|
.PP
|
||
|
|
The STk procedure \fBTk:focus-follows-mouse\fR may be invoked to
|
||
|
|
create an \fIimplicit\fR focus model: it reconfigures Tk so that
|
||
|
|
the focus is set to a window whenever the mouse enters it.
|
||
|
|
The STk procedures \fBTk:focus-next\fR and \fB Tk:focus-prev\fR
|
||
|
|
implement a focus order among the windows of a top-level; they
|
||
|
|
are used in the default bindings for Tab and Shift-Tab, among other
|
||
|
|
things.
|
||
|
|
.PP
|
||
|
|
The \fBfocus\fR procedure can take any of the following forms:
|
||
|
|
.TP
|
||
|
|
(\fBfocus\fR)
|
||
|
|
Returns the path name of the focus window on the display containing
|
||
|
|
the application's main window, or \fB#f\fR if no window in
|
||
|
|
this application has the focus on that display. Note: it is
|
||
|
|
better to specify the display explicitly using \fB:displayof\fR
|
||
|
|
(see below) so that the code will work in applications using multiple
|
||
|
|
displays.
|
||
|
|
.TP
|
||
|
|
(\fBfocus \fIwindow\fR)
|
||
|
|
If the application currently has the input focus on \fIwindow\fR's
|
||
|
|
display, this procedure resets the input focus for \fIwindow\fR's display
|
||
|
|
to \fIwindow\fR and returns an empty string.
|
||
|
|
If the application doesn't currently have the input focus on
|
||
|
|
\fIwindow\fR's display, \fIwindow\fR will be remembered as the focus
|
||
|
|
for its top-level; the next time the focus arrives at the top-level,
|
||
|
|
Tk will redirect it to \fIwindow\fR.
|
||
|
|
If \fIwindow\fR is an empty string then the procedure does nothing.
|
||
|
|
.TP
|
||
|
|
(\fBfocus :displayof\fR \fIwindow\fR)
|
||
|
|
Returns the name of the focus window on the display containing \fIwindow\fR.
|
||
|
|
If the focus window for \fIwindow\fR's display isn't in this
|
||
|
|
application, the return value is an empty list.
|
||
|
|
.TP
|
||
|
|
(\fBfocus :force \fIwindow\fR)
|
||
|
|
Sets the focus of \fIwindow\fR's display to \fIwindow\fR, even if
|
||
|
|
the application doesn't currently have the input focus for the display.
|
||
|
|
This procedure should be used sparingly, if at all.
|
||
|
|
In normal usage, an application should not claim the focus for
|
||
|
|
itself; instead, it should wait for the window manager to give it
|
||
|
|
the focus.
|
||
|
|
If \fIwindow\fR is an empty string then the procedure does nothing.
|
||
|
|
.TP
|
||
|
|
(\fBfocus :lastfor\fR \fIwindow\fR)
|
||
|
|
Returns the name of the most recent window to have the input focus
|
||
|
|
among all the windows in the same top-level as \fIwindow\fR.
|
||
|
|
If no window in that top-level has ever had the input focus, or
|
||
|
|
if the most recent focus window has been deleted, then the name
|
||
|
|
of the top-level is returned. The return value is the window that
|
||
|
|
will receive the input focus the next time the window manager gives
|
||
|
|
the focus to the top-level.
|
||
|
|
|
||
|
|
.SH "QUIRKS"
|
||
|
|
.PP
|
||
|
|
When an internal window receives the input focus, Tk doesn't actually
|
||
|
|
set the X focus to that window; as far as X is concerned, the focus
|
||
|
|
will stay on the top-level window containing the window with the focus.
|
||
|
|
However, Tk generates FocusIn and FocusOut events just as if the X
|
||
|
|
focus were on the internal window. This approach gets around a
|
||
|
|
number of problems that would occur if the X focus were actually moved;
|
||
|
|
the fact that the X focus is on the top-level is invisible unless
|
||
|
|
you use C code to query the X server directly.
|
||
|
|
.SH SEE ALSO
|
||
|
|
grab
|