Tk_Name(3) Tk Library Procedures Tk_Name(3)_________________________________________________________________NAME
Tk_Name, Tk_PathName, Tk_NameToWindow - convert between
names and window tokens
SYNOPSIS
#include <tk.h>
Tk_Uid
Tk_Name(tkwin)
char *
Tk_PathName(tkwin)
Tk_Window
Tk_NameToWindow(interp, pathName, tkwin)
ARGUMENTS
Tk_Window tkwin (in) Token for window.
Tcl_Interp *interp (out) Interpreter to use for
error reporting.
char *pathName (in) Character string con-
taining path name of
window.
_________________________________________________________________DESCRIPTION
Each window managed by Tk has two names, a short name that
identifies a window among children of the same parent, and
a path name that identifies the window uniquely among all
the windows belonging to the same main window. The path
name is used more often in Tk than the short name; many
commands, like bind, expect path names as arguments.
The Tk_Name macro returns a window's short name, which is
the same as the name argument passed to Tk_CreateWindow
when the window was created. The value is returned as a
Tk_Uid, which may be used just like a string pointer but
also has the properties of a unique identifier (see the
manual entry for Tk_GetUid for details).
The Tk_PathName macro returns a hierarchical name for
tkwin. Path names have a structure similar to file names
in Unix but with dots between elements instead of slashes:
the main window for an application has the path name
``.''; its children have names like ``.a'' and ``.b'';
their children have names like ``.a.aa'' and ``.b.bb'';
and so on. A window is considered to be be a child of
another window for naming purposes if the second window
was named as the first window's parent when the first
Tk 1
Tk_Name(3) Tk Library Procedures Tk_Name(3)
window was created. This is not always the same as the X
window hierarchy. For example, a pop-up is created as a
child of the root window, but its logical parent will usu-
ally be a window within the application.
The procedure Tk_NameToWindow returns the token for a win-
dow given its path name (the pathName argument) and
another window belonging to the same main window (tkwin).
It normally returns a token for the named window, but if
no such window exists Tk_NameToWindow leaves an error mes-
sage in interp->result and returns NULL. The tkwin argu-
ment to Tk_NameToWindow is needed because path names are
only unique within a single application hierarchy. If,
for example, a single process has opened two main windows,
each will have a separate naming hierarchy and the same
path name might appear in each of the hierarchies. Nor-
mally tkwin is the main window of the desired hierarchy,
but this need not be the case: any window in the desired
hierarchy may be used.
KEYWORDS
name, path name, token, window
Tk 2
