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


Man(1) output converted with man2html