tk/doc/wish.1

   1 '\"
   2 '\" Copyright (c) 1991-1994 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1996 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 '\" RCS: @(#) $Id$
   9 '\"
  10 .so man.macros
  11 .TH wish 1 8.0 Tk "Tk Applications"
  12 .BS
  13 '\" Note:  do not modify the .SH NAME line immediately below!
  14 .SH NAME
  15 wish \- Simple windowing shell
  16 .SH SYNOPSIS
  17 \fBwish\fR ?\fIfileName arg arg ...\fR?
  18 .SH OPTIONS
  19 .IP "\fB\-colormap \fInew\fR" 20
  20 Specifies that the window should have a new private colormap instead of
  21 using the default colormap for the screen.
  22 .IP "\fB\-display \fIdisplay\fR" 20
  23 Display (and screen) on which to display window.
  24 .IP "\fB\-geometry \fIgeometry\fR" 20
  25 Initial geometry to use for window.  If this option is specified, its
  26 value is stored in the \fBgeometry\fR global variable of the application's
  27 Tcl interpreter.
  28 .IP "\fB\-name \fIname\fR" 20
  29 Use \fIname\fR as the title to be displayed in the window, and
  30 as the name of the interpreter for \fBsend\fR commands.
  31 .IP "\fB\-sync\fR" 20
  32 Execute all X server commands synchronously, so that errors
  33 are reported immediately.  This will result in much slower
  34 execution, but it is useful for debugging.
  35 .VS 8.0 br
  36 .IP "\fB\-use\fR \fIid\fR" 20
  37 Specifies that the main window for the application is to be embedded in
  38 the window whose identifier is \fIid\fR, instead of being created as an
  39 independent toplevel window.  \fIId\fR must be specified in the same
  40 way as the value for the \fB\-use\fR option for toplevel widgets (i.e.
  41 it has a form like that returned by the \fBwinfo id\fR command).
  42 .VE
  43 .IP "\fB\-visual \fIvisual\fR" 20
  44 Specifies the visual to use for the window.
  45 \fIVisual\fR may have any of the forms supported by the \fBTk_GetVisual\fR
  46 procedure.
  47 .IP "\fB\-\|\-\fR" 20
  48 Pass all remaining arguments through to the script's \fBargv\fR
  49 variable without interpreting them.
  50 This provides a mechanism for passing arguments such as \fB\-name\fR
  51 to a script instead of having \fBwish\fR interpret them.
  52 .BE
  53
  54 .SH DESCRIPTION
  55 .PP
  56 \fBWish\fR is a simple program consisting of the Tcl command
  57 language, the Tk toolkit, and a main program that reads commands
  58 from standard input or from a file.
  59 It creates a main window and then processes Tcl commands.
  60 If \fBwish\fR is invoked with no arguments, or with a first argument
  61 that starts with ``\-'', then it reads Tcl commands interactively from
  62 standard input.
  63 It will continue processing commands until all windows have been
  64 deleted or until end-of-file is reached on standard input.
  65 If there exists a file \fB.wishrc\fR in the home directory of
  66 the user, \fBwish\fR evaluates the file as a Tcl script
  67 just before reading the first command from standard input.
  68 .PP
  69 If \fBwish\fR is invoked with an initial \fIfileName\fR argument, then
  70 \fIfileName\fR is treated as the name of a script file.
  71 \fBWish\fR will evaluate the script in \fIfileName\fR (which
  72 presumably creates a user interface), then it will respond to events
  73 until all windows have been deleted.
  74 Commands will not be read from standard input.
  75 There is no automatic evaluation of \fB.wishrc\fR in this
  76 case, but the script file can always \fBsource\fR it if desired.
  77
  78 .SH "OPTIONS"
  79 .PP
  80 \fBWish\fR automatically processes all of the command-line options
  81 described in the \fBOPTIONS\fR summary above.
  82 Any other command-line arguments besides these are passed through
  83 to the application using the \fBargc\fR and \fBargv\fR variables
  84 described later.
  85
  86 .SH "APPLICATION NAME AND CLASS"
  87 .PP
  88 The name of the application, which is used for purposes such as
  89 \fBsend\fR commands, is taken from the \fB\-name\fR option,
  90 if it is specified;  otherwise it is taken from \fIfileName\fR,
  91 if it is specified, or from the command name by which
  92 \fBwish\fR was invoked.  In the last two cases, if the name contains a ``/''
  93 character, then only the characters after the last slash are used
  94 as the application name.
  95 .PP
  96 The class of the application, which is used for purposes such as
  97 specifying options with a \fBRESOURCE_MANAGER\fR property or .Xdefaults
  98 file, is the same as its name except that the first letter is
  99 capitalized.
 100
 101 .SH "VARIABLES"
 102 .PP
 103 \fBWish\fR sets the following Tcl variables:
 104 .TP 15
 105 \fBargc\fR
 106 Contains a count of the number of \fIarg\fR arguments (0 if none),
 107 not including the options described above.
 108 .TP 15
 109 \fBargv\fR
 110 Contains a Tcl list whose elements are the \fIarg\fR arguments
 111 that follow a \fB\-\|\-\fR option or don't match any of the
 112 options described in OPTIONS above, in order, or an empty string
 113 if there are no such arguments.
 114 .TP 15
 115 \fBargv0\fR
 116 Contains \fIfileName\fR if it was specified.
 117 Otherwise, contains the name by which \fBwish\fR was invoked.
 118 .TP 15
 119 \fBgeometry\fR
 120 If the \fB\-geometry\fR option is specified, \fBwish\fR copies its
 121 value into this variable.  If the variable still exists after
 122 \fIfileName\fR has been evaluated, \fBwish\fR uses the value of
 123 the variable in a \fBwm geometry\fR command to set the main
 124 window's geometry.
 125 .TP 15
 126 \fBtcl_interactive\fR
 127 Contains 1 if \fBwish\fR is reading commands interactively (\fIfileName\fR
 128 was not specified and standard input is a terminal-like
 129 device), 0 otherwise.
 130
 131 .SH "SCRIPT FILES"
 132 .PP
 133 If you create a Tcl script in a file whose first line is
 134 .CS
 135 \fB#!/usr/local/bin/wish\fR
 136 .CE
 137 then you can invoke the script file directly from your shell if
 138 you mark it as executable.
 139 This assumes that \fBwish\fR has been installed in the default
 140 location in /usr/local/bin;  if it's installed somewhere else
 141 then you'll have to modify the above line to match.
 142 Many UNIX systems do not allow the \fB#!\fR line to exceed about
 143 30 characters in length, so be sure that the \fBwish\fR executable
 144 can be accessed with a short file name.
 145 .PP
 146 An even better approach is to start your script files with the
 147 following three lines:
 148 .CS
 149 \fB#!/bin/sh
 150 # the next line restarts using wish \e
 151 exec wish "$0" "$@"\fR
 152 .CE
 153 This approach has three advantages over the approach in the previous
 154 paragraph.  First, the location of the \fBwish\fR binary doesn't have
 155 to be hard-wired into the script:  it can be anywhere in your shell
 156 search path.  Second, it gets around the 30-character file name limit
 157 in the previous approach.
 158 Third, this approach will work even if \fBwish\fR is
 159 itself a shell script (this is done on some systems in order to
 160 handle multiple architectures or operating systems:  the \fBwish\fR
 161 script selects one of several binaries to run).  The three lines
 162 cause both \fBsh\fR and \fBwish\fR to process the script, but the
 163 \fBexec\fR is only executed by \fBsh\fR.
 164 \fBsh\fR processes the script first;  it treats the second
 165 line as a comment and executes the third line.
 166 The \fBexec\fR statement cause the shell to stop processing and
 167 instead to start up \fBwish\fR to reprocess the entire script.
 168 When \fBwish\fR starts up, it treats all three lines as comments,
 169 since the backslash at the end of the second line causes the third
 170 line to be treated as part of the comment on the second line.
 171
 172 .SH PROMPTS
 173 .PP
 174 When \fBwish\fR is invoked interactively it normally prompts for each
 175 command with ``\fB% \fR''.  You can change the prompt by setting the
 176 variables \fBtcl_prompt1\fR and \fBtcl_prompt2\fR.  If variable
 177 \fBtcl_prompt1\fR exists then it must consist of a Tcl script
 178 to output a prompt;  instead of outputting a prompt \fBwish\fR
 179 will evaluate the script in \fBtcl_prompt1\fR.
 180 The variable \fBtcl_prompt2\fR is used in a similar way when
 181 a newline is typed but the current command isn't yet complete;
 182 if \fBtcl_prompt2\fR isn't set then no prompt is output for
 183 incomplete commands.
 184
 185 .SH KEYWORDS
 186 shell, toolkit
 187