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

       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-&gt;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