util/src/TclTk/tk8.6.12/doc/SetAppName.3

   1 '\"
   2 '\" Copyright (c) 1994 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
   4 '\"
   5 '\" See the file "license.terms" for information on usage and redistribution
   6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   7 '\"
   8 .TH Tk_SetAppName 3 4.0 Tk "Tk Library Procedures"
   9 .so man.macros
  10 .BS
  11 .SH NAME
  12 Tk_SetAppName \- Set the name of an application for 'send' commands
  13 .SH SYNOPSIS
  14 .nf
  15 \fB#include <tk.h>\fR
  16 .sp
  17 const char *
  18 \fBTk_SetAppName\fR(\fItkwin, name\fR)
  19 .SH ARGUMENTS
  20 .AS Tk_Window parent
  21 .AP Tk_Window tkwin in
  22 Token for window in application.  Used only to select a particular
  23 application.
  24 .AP "const char" *name in
  25 Name under which to register the application.
  26 .BE
  27 .SH DESCRIPTION
  28 .PP
  29 \fBTk_SetAppName\fR associates a name with a given application and
  30 records that association on the display containing with the application's
  31 main window.
  32 After this procedure has been invoked, other applications on the
  33 display will be able to use the \fBsend\fR command to invoke operations
  34 in the application.
  35 If \fIname\fR is already in use by some other application on the
  36 display, then a new name will be generated by appending
  37 .QW "\fB #2\fR"
  38 to \fIname\fR;  if this name is also in use,
  39 the number will be incremented until an unused name is found.
  40 The return value from the procedure is a pointer to the name actually
  41 used.
  42 .PP
  43 If the application already has a name when \fBTk_SetAppName\fR is
  44 called, then the new name replaces the old name.
  45 .PP
  46 \fBTk_SetAppName\fR also adds a \fBsend\fR command to the application's
  47 interpreter, which can be used to send commands from this application
  48 to others on any of the displays where the application has windows.
  49 .PP
  50 The application's name registration persists until the interpreter is
  51 deleted or the \fBsend\fR command is deleted from \fIinterp\fR, at which
  52 point the name is automatically unregistered and the application
  53 becomes inaccessible via \fBsend\fR.
  54 The application can be made accessible again by calling \fBTk_SetAppName\fR.
  55 .PP
  56 \fBTk_SetAppName\fR is called automatically by \fBTk_Init\fR,
  57 so applications do not normally need to call it explicitly.
  58 .PP
  59 The command \fBtk appname\fR provides Tcl-level access to the
  60 functionality of \fBTk_SetAppName\fR.
  61 .SH KEYWORDS
  62 application, name, register, send command