| '\" |
| '\" Copyright (c) 1991-1994 The Regents of the University of California. |
| '\" Copyright (c) 1994-1996 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: wish.1,v 1.2 1998/09/14 18:23:01 stanton Exp $ |
| '\" |
| '\" The definitions below are for supplemental macros used in Tcl/Tk |
| '\" manual entries. |
| '\" |
| '\" .AP type name in/out ?indent? |
| '\" Start paragraph describing an argument to a library procedure. |
| '\" type is type of argument (int, etc.), in/out is either "in", "out", |
| '\" or "in/out" to describe whether procedure reads or modifies arg, |
| '\" and indent is equivalent to second arg of .IP (shouldn't ever be |
| '\" needed; use .AS below instead) |
| '\" |
| '\" .AS ?type? ?name? |
| '\" Give maximum sizes of arguments for setting tab stops. Type and |
| '\" name are examples of largest possible arguments that will be passed |
| '\" to .AP later. If args are omitted, default tab stops are used. |
| '\" |
| '\" .BS |
| '\" Start box enclosure. From here until next .BE, everything will be |
| '\" enclosed in one large box. |
| '\" |
| '\" .BE |
| '\" End of box enclosure. |
| '\" |
| '\" .CS |
| '\" Begin code excerpt. |
| '\" |
| '\" .CE |
| '\" End code excerpt. |
| '\" |
| '\" .VS ?version? ?br? |
| '\" Begin vertical sidebar, for use in marking newly-changed parts |
| '\" of man pages. The first argument is ignored and used for recording |
| '\" the version when the .VS was added, so that the sidebars can be |
| '\" found and removed when they reach a certain age. If another argument |
| '\" is present, then a line break is forced before starting the sidebar. |
| '\" |
| '\" .VE |
| '\" End of vertical sidebar. |
| '\" |
| '\" .DS |
| '\" Begin an indented unfilled display. |
| '\" |
| '\" .DE |
| '\" End of indented unfilled display. |
| '\" |
| '\" .SO |
| '\" Start of list of standard options for a Tk widget. The |
| '\" options follow on successive lines, in four columns separated |
| '\" by tabs. |
| '\" |
| '\" .SE |
| '\" End of list of standard options for a Tk widget. |
| '\" |
| '\" .OP cmdName dbName dbClass |
| '\" Start of description of a specific option. cmdName gives the |
| '\" option's name as specified in the class command, dbName gives |
| '\" the option's name in the option database, and dbClass gives |
| '\" the option's class in the option database. |
| '\" |
| '\" .UL arg1 arg2 |
| '\" Print arg1 underlined, then print arg2 normally. |
| '\" |
| '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $ |
| '\" |
| '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. |
| .if t .wh -1.3i ^B |
| .nr ^l \n(.l |
| .ad b |
| '\" # Start an argument description |
| .de AP |
| .ie !"\\$4"" .TP \\$4 |
| .el \{\ |
| . ie !"\\$2"" .TP \\n()Cu |
| . el .TP 15 |
| .\} |
| .ta \\n()Au \\n()Bu |
| .ie !"\\$3"" \{\ |
| \&\\$1 \\fI\\$2\\fP (\\$3) |
| .\".b |
| .\} |
| .el \{\ |
| .br |
| .ie !"\\$2"" \{\ |
| \&\\$1 \\fI\\$2\\fP |
| .\} |
| .el \{\ |
| \&\\fI\\$1\\fP |
| .\} |
| .\} |
| .. |
| '\" # define tabbing values for .AP |
| .de AS |
| .nr )A 10n |
| .if !"\\$1"" .nr )A \\w'\\$1'u+3n |
| .nr )B \\n()Au+15n |
| .\" |
| .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n |
| .nr )C \\n()Bu+\\w'(in/out)'u+2n |
| .. |
| .AS Tcl_Interp Tcl_CreateInterp in/out |
| '\" # BS - start boxed text |
| '\" # ^y = starting y location |
| '\" # ^b = 1 |
| .de BS |
| .br |
| .mk ^y |
| .nr ^b 1u |
| .if n .nf |
| .if n .ti 0 |
| .if n \l'\\n(.lu\(ul' |
| .if n .fi |
| .. |
| '\" # BE - end boxed text (draw box now) |
| .de BE |
| .nf |
| .ti 0 |
| .mk ^t |
| .ie n \l'\\n(^lu\(ul' |
| .el \{\ |
| .\" Draw four-sided box normally, but don't draw top of |
| .\" box if the box started on an earlier page. |
| .ie !\\n(^b-1 \{\ |
| \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' |
| .\} |
| .el \}\ |
| \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' |
| .\} |
| .\} |
| .fi |
| .br |
| .nr ^b 0 |
| .. |
| '\" # VS - start vertical sidebar |
| '\" # ^Y = starting y location |
| '\" # ^v = 1 (for troff; for nroff this doesn't matter) |
| .de VS |
| .if !"\\$2"" .br |
| .mk ^Y |
| .ie n 'mc \s12\(br\s0 |
| .el .nr ^v 1u |
| .. |
| '\" # VE - end of vertical sidebar |
| .de VE |
| .ie n 'mc |
| .el \{\ |
| .ev 2 |
| .nf |
| .ti 0 |
| .mk ^t |
| \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' |
| .sp -1 |
| .fi |
| .ev |
| .\} |
| .nr ^v 0 |
| .. |
| '\" # Special macro to handle page bottom: finish off current |
| '\" # box/sidebar if in box/sidebar mode, then invoked standard |
| '\" # page bottom macro. |
| .de ^B |
| .ev 2 |
| 'ti 0 |
| 'nf |
| .mk ^t |
| .if \\n(^b \{\ |
| .\" Draw three-sided box if this is the box's first page, |
| .\" draw two sides but no top otherwise. |
| .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c |
| .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c |
| .\} |
| .if \\n(^v \{\ |
| .nr ^x \\n(^tu+1v-\\n(^Yu |
| \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c |
| .\} |
| .bp |
| 'fi |
| .ev |
| .if \\n(^b \{\ |
| .mk ^y |
| .nr ^b 2 |
| .\} |
| .if \\n(^v \{\ |
| .mk ^Y |
| .\} |
| .. |
| '\" # DS - begin display |
| .de DS |
| .RS |
| .nf |
| .sp |
| .. |
| '\" # DE - end display |
| .de DE |
| .fi |
| .RE |
| .sp |
| .. |
| '\" # SO - start of list of standard options |
| .de SO |
| .SH "STANDARD OPTIONS" |
| .LP |
| .nf |
| .ta 5.5c 11c |
| .ft B |
| .. |
| '\" # SE - end of list of standard options |
| .de SE |
| .fi |
| .ft R |
| .LP |
| See the \\fBoptions\\fR manual entry for details on the standard options. |
| .. |
| '\" # OP - start of full description for a single option |
| .de OP |
| .LP |
| .nf |
| .ta 4c |
| Command-Line Name: \\fB\\$1\\fR |
| Database Name: \\fB\\$2\\fR |
| Database Class: \\fB\\$3\\fR |
| .fi |
| .IP |
| .. |
| '\" # CS - begin code excerpt |
| .de CS |
| .RS |
| .nf |
| .ta .25i .5i .75i 1i |
| .. |
| '\" # CE - end code excerpt |
| .de CE |
| .fi |
| .RE |
| .. |
| .de UL |
| \\$1\l'|0\(ul'\\$2 |
| .. |
| .TH wish 1 8.0 Tk "Tk Applications" |
| .BS |
| '\" Note: do not modify the .SH NAME line immediately below! |
| .SH NAME |
| wish \- Simple windowing shell |
| .SH SYNOPSIS |
| \fBwish\fR ?\fIfileName arg arg ...\fR? |
| .SH OPTIONS |
| .IP "\fB\-colormap \fInew\fR" 20 |
| Specifies that the window should have a new private colormap instead of |
| using the default colormap for the screen. |
| .IP "\fB\-display \fIdisplay\fR" 20 |
| Display (and screen) on which to display window. |
| .IP "\fB\-geometry \fIgeometry\fR" 20 |
| Initial geometry to use for window. If this option is specified, its |
| value is stored in the \fBgeometry\fR global variable of the application's |
| Tcl interpreter. |
| .IP "\fB\-name \fIname\fR" 20 |
| Use \fIname\fR as the title to be displayed in the window, and |
| as the name of the interpreter for \fBsend\fR commands. |
| .IP "\fB\-sync\fR" 20 |
| Execute all X server commands synchronously, so that errors |
| are reported immediately. This will result in much slower |
| execution, but it is useful for debugging. |
| .VS 8.0 br |
| .IP "\fB\-use\fR \fIid\fR" 20 |
| Specifies that the main window for the application is to be embedded in |
| the window whose identifier is \fIid\fR, instead of being created as an |
| independent toplevel window. \fIId\fR must be specified in the same |
| way as the value for the \fB\-use\fR option for toplevel widgets (i.e. |
| it has a form like that returned by the \fBwinfo id\fR command). |
| .VE |
| .IP "\fB\-visual \fIvisual\fR" 20 |
| Specifies the visual to use for the window. |
| \fIVisual\fR may have any of the forms supported by the \fBTk_GetVisual\fR |
| procedure. |
| .IP "\fB\-\|\-\fR" 20 |
| Pass all remaining arguments through to the script's \fBargv\fR |
| variable without interpreting them. |
| This provides a mechanism for passing arguments such as \fB\-name\fR |
| to a script instead of having \fBwish\fR interpret them. |
| .BE |
| |
| .SH DESCRIPTION |
| .PP |
| \fBWish\fR is a simple program consisting of the Tcl command |
| language, the Tk toolkit, and a main program that reads commands |
| from standard input or from a file. |
| It creates a main window and then processes Tcl commands. |
| If \fBwish\fR is invoked with no arguments, or with a first argument |
| that starts with ``\-'', then it reads Tcl commands interactively from |
| standard input. |
| It will continue processing commands until all windows have been |
| deleted or until end-of-file is reached on standard input. |
| If there exists a file \fB.wishrc\fR in the home directory of |
| the user, \fBwish\fR evaluates the file as a Tcl script |
| just before reading the first command from standard input. |
| .PP |
| If \fBwish\fR is invoked with an initial \fIfileName\fR argument, then |
| \fIfileName\fR is treated as the name of a script file. |
| \fBWish\fR will evaluate the script in \fIfileName\fR (which |
| presumably creates a user interface), then it will respond to events |
| until all windows have been deleted. |
| Commands will not be read from standard input. |
| There is no automatic evaluation of \fB.wishrc\fR in this |
| case, but the script file can always \fBsource\fR it if desired. |
| |
| .SH "OPTIONS" |
| .PP |
| \fBWish\fR automatically processes all of the command-line options |
| described in the \fBOPTIONS\fR summary above. |
| Any other command-line arguments besides these are passed through |
| to the application using the \fBargc\fR and \fBargv\fR variables |
| described later. |
| |
| .SH "APPLICATION NAME AND CLASS" |
| .PP |
| The name of the application, which is used for purposes such as |
| \fBsend\fR commands, is taken from the \fB\-name\fR option, |
| if it is specified; otherwise it is taken from \fIfileName\fR, |
| if it is specified, or from the command name by which |
| \fBwish\fR was invoked. In the last two cases, if the name contains a ``/'' |
| character, then only the characters after the last slash are used |
| as the application name. |
| .PP |
| The class of the application, which is used for purposes such as |
| specifying options with a \fBRESOURCE_MANAGER\fR property or .Xdefaults |
| file, is the same as its name except that the first letter is |
| capitalized. |
| |
| .SH "VARIABLES" |
| .PP |
| \fBWish\fR sets the following Tcl variables: |
| .TP 15 |
| \fBargc\fR |
| Contains a count of the number of \fIarg\fR arguments (0 if none), |
| not including the options described above. |
| .TP 15 |
| \fBargv\fR |
| Contains a Tcl list whose elements are the \fIarg\fR arguments |
| that follow a \fB\-\|\-\fR option or don't match any of the |
| options described in OPTIONS above, in order, or an empty string |
| if there are no such arguments. |
| .TP 15 |
| \fBargv0\fR |
| Contains \fIfileName\fR if it was specified. |
| Otherwise, contains the name by which \fBwish\fR was invoked. |
| .TP 15 |
| \fBgeometry\fR |
| If the \fB\-geometry\fR option is specified, \fBwish\fR copies its |
| value into this variable. If the variable still exists after |
| \fIfileName\fR has been evaluated, \fBwish\fR uses the value of |
| the variable in a \fBwm geometry\fR command to set the main |
| window's geometry. |
| .TP 15 |
| \fBtcl_interactive\fR |
| Contains 1 if \fBwish\fR is reading commands interactively (\fIfileName\fR |
| was not specified and standard input is a terminal-like |
| device), 0 otherwise. |
| |
| .SH "SCRIPT FILES" |
| .PP |
| If you create a Tcl script in a file whose first line is |
| .CS |
| \fB#!/usr/local/bin/wish\fR |
| .CE |
| then you can invoke the script file directly from your shell if |
| you mark it as executable. |
| This assumes that \fBwish\fR has been installed in the default |
| location in /usr/local/bin; if it's installed somewhere else |
| then you'll have to modify the above line to match. |
| Many UNIX systems do not allow the \fB#!\fR line to exceed about |
| 30 characters in length, so be sure that the \fBwish\fR executable |
| can be accessed with a short file name. |
| .PP |
| An even better approach is to start your script files with the |
| following three lines: |
| .CS |
| \fB#!/bin/sh |
| # the next line restarts using wish \e |
| exec wish "$0" "$@"\fR |
| .CE |
| This approach has three advantages over the approach in the previous |
| paragraph. First, the location of the \fBwish\fR binary doesn't have |
| to be hard-wired into the script: it can be anywhere in your shell |
| search path. Second, it gets around the 30-character file name limit |
| in the previous approach. |
| Third, this approach will work even if \fBwish\fR is |
| itself a shell script (this is done on some systems in order to |
| handle multiple architectures or operating systems: the \fBwish\fR |
| script selects one of several binaries to run). The three lines |
| cause both \fBsh\fR and \fBwish\fR to process the script, but the |
| \fBexec\fR is only executed by \fBsh\fR. |
| \fBsh\fR processes the script first; it treats the second |
| line as a comment and executes the third line. |
| The \fBexec\fR statement cause the shell to stop processing and |
| instead to start up \fBwish\fR to reprocess the entire script. |
| When \fBwish\fR starts up, it treats all three lines as comments, |
| since the backslash at the end of the second line causes the third |
| line to be treated as part of the comment on the second line. |
| |
| .SH PROMPTS |
| .PP |
| When \fBwish\fR is invoked interactively it normally prompts for each |
| command with ``\fB% \fR''. You can change the prompt by setting the |
| variables \fBtcl_prompt1\fR and \fBtcl_prompt2\fR. If variable |
| \fBtcl_prompt1\fR exists then it must consist of a Tcl script |
| to output a prompt; instead of outputting a prompt \fBwish\fR |
| will evaluate the script in \fBtcl_prompt1\fR. |
| The variable \fBtcl_prompt2\fR is used in a similar way when |
| a newline is typed but the current command isn't yet complete; |
| if \fBtcl_prompt2\fR isn't set then no prompt is output for |
| incomplete commands. |
| |
| .SH KEYWORDS |
| shell, toolkit |