head	1.11;
access;
symbols
	core-8-5-9:1.9
	core-8-5-8:1.9
	macosx-cocoa-merge:1.11
	macosx-cocoa-premerge:1.11
	macosx-carbon-freeze:1.11
	core-8-5-7:1.9
	core-8-5-6:1.9
	core-8-6-b1:1.10
	core-8-6-a3:1.10
	core-8-5-5:1.9
	core-8-6-a2:1.10
	core-8-5-4:1.9
	core-8-5-3:1.9
	core-8-6-a1:1.9
	core-8-4-19:1.3
	core-8-5-branch:1.9.0.2
	core-8-5-2:1.9
	core-8-4-18:1.3
	core-8-5-1:1.9
	core-8-4-17:1.3
	core-8-5-0:1.9
	core-8-5-b3:1.8
	core-8-5-b2:1.7
	core-8-4-16:1.3
	core-8-5-b1:1.5
	core-stablilizer-merge:1.5
	core-stabilizer-branch:1.5.0.2
	core-stabilizer-merge:1.9
	core-8-4-15:1.3
	core-8-5-a6:1.5
	core-8-5-a5:1.4
	core-8-4-14:1.3
	core-8-5-a4:1.4
	core-8-4-13:1.3
	core-8-4-12:1.3
	core-8-4-11:1.3
	core-8-5-a3:1.4
	core-8-4-10:1.3
	core-8-4-9-branch:1.3.0.6
	core-8-5-a2:1.4
	core-8-4-9:1.3
	core-8-4-8:1.3
	core-8-4-7:1.3
	core-8-5-a1:1.3
	core-8-4-6:1.3
	core-8-4-5:1.3
	mistachkin-dev-branch:1.3.0.4
	core-8-4-4:1.3
	core-8-4-3:1.3
	core-8-4-branch:1.3.0.2
	core-8-4-2:1.3
	core-8-4-1:1.3
	core-8-3-5:1.2
	core-8-4-0:1.3
	macosx-8-4-merge-2002-08-31-trunk:1.3
	macosx-8-4-premerge-2002-08-31-branch:1.2.24.1
	macosx-8-4-premerge-2002-08-31-trunk:1.3
	macosx-8-4-merge-2002-08-30-branch:1.2.24.1
	macosx-8-4-merge-2002-08-30-trunk:1.3
	macosx-8-4-merge-2002-08-20-branch:1.2.24.1
	macosx-8-4-merge-2002-08-20-trunk:1.3
	core-8-4-b2:1.3
	core-8-4-b1:1.3
	macosx-premerge-6-9-02:1.2.24.1
	core-8-4-a4:1.3
	core-8-3-4:1.2
	macosx-8-4-branch:1.2.0.24
	macosx-8-4-branchpoint:1.2
	core-8-4-a3:1.2
	core-8-3-3:1.2
	dgp-privates-into-namespace:1.2.0.22
	tclpro-1-5-0:1.2
	core-8-4-win-speedup:1.2.0.20
	core-8-4-a2:1.2
	tclpro-1-4-1:1.2
	tclpro-1-4-0:1.2
	core-8-3-2:1.2
	ajuba-ajuba2-2-1-base:1.2
	ajuba-ajuba2-2-0:1.2
	core-8-4-a1:1.2
	core-8-3-1-branch:1.2.0.18
	core-8-3-1:1.2
	scriptics-sc-2-0-b5:1.2
	scriptics-sc-2-0-fixed:1.2
	scriptics-sc-2-0-b2:1.2
	scriptics-sc-2-0-b1:1.2
	core-8-3-0:1.2
	core-8-3-b2:1.2
	core-8-3-b1:1.2
	scriptics-sc-1-1:1.2
	scriptics-sc-1-1-b1:1.2
	core-8-2-3:1.2
	scriptics-sc-1-1-branch:1.2.0.16
	scriptics-sc-1-1-base:1.2
	scriptics-sc-1-0:1.2
	scriptics-sc-1-0-branch:1.2.0.14
	scriptics-sc-1-0-base:1.2
	core-8-2-2:1.2
	core-8-2-1:1.2
	scriptics-bc-1-0-b1:1.2
	core-8-2-1-branch:1.2.0.12
	scriptics-tclpro-1-3-0:1.2
	core-8-2-0:1.2
	core-8-2-b3-branch:1.2.0.10
	core-8-2-b3-base:1.2
	scriptics-tclpro-1-3-b4:1.2
	core-8-2-b2:1.2
	scriptics-tclpro-1-3-b3:1.2
	core-8-2-b1:1.2
	scriptics-tclpro-1-3-b2:1.2
	merge-to-mainline-5/21/99:1.2
	scriptics-tclpro-1-3-b2-branch:1.2.0.8
	core-8-1-1:1.2
	scriptics-tclpro-1-3-b1:1.2
	core-8-1-1-base:1.2
	core-8-1-0:1.2
	merge-to-mainline-4-29-99:1.2
	merge-to-mainline-4-23-99:1.2
	core-8-1-branch-old:1.1.0.4
	core-8-0-6-branch:1.2.0.6
	core-8-0-6-base:1.2
	core-8-0-5:1.2
	core-8-1-b3:1.1.4.1
	core-8-1-b2:1.1.4.1
	dev-8-1-stubs-branch:1.1.4.1.0.2
	dev-stubs-branch:1.2.0.4
	scriptics-tclpro-1-2:1.2
	scriptics-tclpro-1-2-b2:1.2
	core-8-1-merge-2/10/99:1.2
	core-8-0-5-branch:1.2.0.2
	core-8-0-5-base:1.2
	scriptics-tclpro-1-2-b1:1.2
	scriptics-tclpro-1-2-a1:1.2
	core-8-1-b1:1.1.4.1
	core-8-0-4:1.2
	core-8-1-a2:1.1
	core-8-0-2:1.1
	core-8-0-3:1.2;
locks; strict;
comment	@# @;


1.11
date	2009.05.04.09.12.33;	author dkf;	state Exp;
branches;
next	1.10;

1.10
date	2008.06.30.22.57.01;	author dkf;	state Exp;
branches;
next	1.9;

1.9
date	2007.12.13.15.23.43;	author dgp;	state Exp;
branches;
next	1.8;

1.8
date	2007.10.29.16.04.13;	author dkf;	state Exp;
branches;
next	1.7;

1.7
date	2007.10.26.20.13.23;	author dgp;	state Exp;
branches;
next	1.6;

1.6
date	2007.10.24.14.32.57;	author dkf;	state Exp;
branches;
next	1.5;

1.5
date	2007.01.05.00.00.48;	author nijtmans;	state Exp;
branches
	1.5.2.1;
next	1.4;

1.4
date	2004.03.25.12.12.35;	author vincentdarley;	state Exp;
branches;
next	1.3;

1.3
date	2002.01.25.21.09.36;	author dgp;	state Exp;
branches;
next	1.2;

1.2
date	98.09.14.18.22.52;	author stanton;	state Exp;
branches
	1.2.20.1
	1.2.24.1;
next	1.1;

1.1
date	98.04.01.09.40.10;	author rjohnson;	state Exp;
branches
	1.1.4.1;
next	;

1.1.4.1
date	98.09.30.02.16.04;	author stanton;	state Exp;
branches;
next	;

1.2.20.1
date	2002.04.02.20.57.53;	author hobbs;	state Exp;
branches;
next	;

1.2.24.1
date	2002.02.05.02.25.14;	author wolfsuit;	state Exp;
branches;
next	;

1.5.2.1
date	2007.11.01.16.37.13;	author dgp;	state Exp;
branches;
next	;


desc
@@


1.11
log
@Purge mention of interp->result. [Bug 2431507]
@
text
@'\"
'\" Copyright (c) 1990 The Regents of the University of California.
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @@(#) $Id: Name.3,v 1.10 2008/06/30 22:57:01 dkf Exp $
'\" 
.so man.macros
.TH Tk_Name 3 "" Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_Name, Tk_PathName, Tk_NameToWindow \- convert between names and window tokens
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
Tk_Uid
\fBTk_Name\fR(\fItkwin\fR)
.sp
char *
\fBTk_PathName\fR(\fItkwin\fR)
.sp
Tk_Window
\fBTk_NameToWindow\fR(\fIinterp, pathName, tkwin\fR)
.SH ARGUMENTS
.AS Tcl_Interp *pathName
.AP Tk_Window tkwin in
Token for window.
.AP Tcl_Interp *interp out
Interpreter to use for error reporting.
.AP "const char" *pathName in
Character string containing path name of window.
.BE
.SH DESCRIPTION
.PP
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 \fBbind\fR, expect path names as
arguments.
.PP
The \fBTk_Name\fR macro returns a window's
short name, which is the same as the \fIname\fR argument
passed to \fBTk_CreateWindow\fR 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
\fBTk_GetUid\fR for details).
.PP
The \fBTk_PathName\fR macro returns a hierarchical name for \fItkwin\fR.
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
.QW . ;
its children have names like
.QW .a
and
.QW .b ;
their children have names like
.QW .a.aa
and
.QW .b.bb ;
and so on.  A window is considered to be a child of
another window for naming purposes if the second window was named
as the first window's \fIparent\fR 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
usually be a window within the application.
.PP
The procedure \fBTk_NameToWindow\fR returns the token for a window
given its path name (the \fIpathName\fR argument) and another window
belonging to the same main window (\fItkwin\fR).  It normally
returns a token for the named window, but if no such window exists
\fBTk_NameToWindow\fR leaves an error message in interpreter
\fIinterp\fR's result
and returns NULL.  The \fItkwin\fR argument to \fBTk_NameToWindow\fR
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.  Normally
\fItkwin\fR is the main window of the desired hierarchy, but this
need not be the case:  any window in the desired hierarchy may be used.
.SH KEYWORDS
name, path name, token, window
@


1.10
log
@Minor doc updates (removing out of date changebars, improving typedef formatting,
 etc.)
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: Name.3,v 1.9 2007/12/13 15:23:43 dgp Exp $
d53 1
a53 2
The \fBTk_PathName\fR macro returns a
hierarchical name for \fItkwin\fR.
d78 2
a79 1
\fBTk_NameToWindow\fR leaves an error message in \fIinterp->result\fR
@


1.9
log
@merge stable branch onto HEAD
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: Name.3,v 1.5.2.1 2007/11/01 16:37:13 dgp Exp $
a35 1

a86 1

@


1.8
log
@Lots more GOOBE stuff. Now works with 'make html'!
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: Name.3,v 1.7 2007/10/26 20:13:23 dgp Exp $
@


1.7
log
@        * doc/*.1:              Revert doc changes that broke
        * doc/*.3:              `make html` so we can get the release
        * doc/*.n:              out the door.
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: Name.3,v 1.5 2007/01/05 00:00:48 nijtmans Exp $
d58 11
a68 3
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 a child of
@


1.6
log
@Lots of improvements to look and feel of manual pages
@
text
@d58 3
a60 11
an application has the path name
.QW . ;
its children have names like
.QW .a
and
.QW .b ;
their children have names like
.QW .a.aa
and
.QW .b.bb ;
and so on.  A window is considered to be a child of
@


1.5
log
@various "const" additions, in line with TIP #27
fix bug #1627732
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: Name.3,v 1.4 2004/03/25 12:12:35 vincentdarley Exp $
d58 11
a68 3
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 a child of
@


1.5.2.1
log
@merge updates from HEAD
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: Name.3,v 1.5 2007/01/05 00:00:48 nijtmans Exp $
d58 3
a60 11
an application has the path name
.QW . ;
its children have names like
.QW .a
and
.QW .b ;
their children have names like
.QW .a.aa
and
.QW .b.bb ;
and so on.  A window is considered to be a child of
@


1.4
log
@Fix typos in documentation
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: Name.3,v 1.3 2002/01/25 21:09:36 dgp Exp $
d33 1
a33 1
.AP "CONST char" *pathName in
@


1.3
log
@	* Updated callers of Tcl_SplitList and Tcl_Merge.
	* Updated callers of Tcl_GetStringResult.
	  Rewrote PrintScrollFractions to ScrollFractions to stop scribbling
	  directly on interp->result.
	* Updated callers of Tcl_GetVar, Tcl_GetVar2
	* Updated callers of Tcl_SplitPath, Tcl_JoinPath, and
	  Tcl_TranslateFileName.
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: Name.3,v 1.2 1998/09/14 18:22:52 stanton Exp $
d60 1
a60 1
``.b.bb''; and so on.  A window is considered to be be a child of
@


1.2
log
@Replaced SCCS strings, fixed binary files
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id$
d33 1
a33 1
.AP char *pathName in
@


1.2.20.1
log
@sync with head
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: Name.3,v 1.3 2002/01/25 21:09:36 dgp Exp $
d33 1
a33 1
.AP "CONST char" *pathName in
@


1.2.24.1
log
@Merge with current TOT
Added support for the wm stackorder command
Fixed crash when selecting Menu items in the Application menu that we didn't
put there.
Added first bits of the use of CG for low-level drawing.  The line-drawing works,
the rest doesn't yet.  You have to set the file static useCGDrawing to 1 and
rebuild to activate this code.
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: Name.3,v 1.2 1998/09/14 18:22:52 stanton Exp $
d33 1
a33 1
.AP "CONST char" *pathName in
@


1.1
log
@Initial revision
@
text
@d8 1
a8 1
'\" SCCS: @@(#) Name.3 1.14 97/01/29 08:50:09
@


1.1.4.1
log
@Merged 8.0.3 changes into 8.1
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: Name.3,v 1.2 1998/09/14 18:22:52 stanton Exp $
@


