| 1 | '\" |
|---|
| 2 | '\" Copyright (c) 1993 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: AppInit.3,v 1.9 2007/12/13 15:22:30 dgp Exp $ |
|---|
| 9 | '\" |
|---|
| 10 | .so man.macros |
|---|
| 11 | .TH Tcl_AppInit 3 7.0 Tcl "Tcl Library Procedures" |
|---|
| 12 | .BS |
|---|
| 13 | .SH NAME |
|---|
| 14 | Tcl_AppInit \- perform application-specific initialization |
|---|
| 15 | .SH SYNOPSIS |
|---|
| 16 | .nf |
|---|
| 17 | \fB#include <tcl.h>\fR |
|---|
| 18 | .sp |
|---|
| 19 | int |
|---|
| 20 | \fBTcl_AppInit\fR(\fIinterp\fR) |
|---|
| 21 | .SH ARGUMENTS |
|---|
| 22 | .AS Tcl_Interp *interp |
|---|
| 23 | .AP Tcl_Interp *interp in |
|---|
| 24 | Interpreter for the application. |
|---|
| 25 | .BE |
|---|
| 26 | |
|---|
| 27 | .SH DESCRIPTION |
|---|
| 28 | .PP |
|---|
| 29 | \fBTcl_AppInit\fR is a |
|---|
| 30 | .QW hook |
|---|
| 31 | procedure that is invoked by |
|---|
| 32 | the main programs for Tcl applications such as \fBtclsh\fR and \fBwish\fR. |
|---|
| 33 | Its purpose is to allow new Tcl applications to be created without |
|---|
| 34 | modifying the main programs provided as part of Tcl and Tk. |
|---|
| 35 | To create a new application you write a new version of |
|---|
| 36 | \fBTcl_AppInit\fR to replace the default version provided by Tcl, |
|---|
| 37 | then link your new \fBTcl_AppInit\fR with the Tcl library. |
|---|
| 38 | .PP |
|---|
| 39 | \fBTcl_AppInit\fR is invoked by \fBTcl_Main\fR and \fBTk_Main\fR |
|---|
| 40 | after their own initialization and before entering the main loop |
|---|
| 41 | to process commands. |
|---|
| 42 | Here are some examples of things that \fBTcl_AppInit\fR might do: |
|---|
| 43 | .IP [1] |
|---|
| 44 | Call initialization procedures for various packages used by |
|---|
| 45 | the application. |
|---|
| 46 | Each initialization procedure adds new commands to \fIinterp\fR |
|---|
| 47 | for its package and performs other package-specific initialization. |
|---|
| 48 | .IP [2] |
|---|
| 49 | Process command-line arguments, which can be accessed from the |
|---|
| 50 | Tcl variables \fBargv\fR and \fBargv0\fR in \fIinterp\fR. |
|---|
| 51 | .IP [3] |
|---|
| 52 | Invoke a startup script to initialize the application. |
|---|
| 53 | .LP |
|---|
| 54 | \fBTcl_AppInit\fR returns \fBTCL_OK\fR or \fBTCL_ERROR\fR. |
|---|
| 55 | If it returns \fBTCL_ERROR\fR then it must leave an error message in |
|---|
| 56 | for the interpreter's result; otherwise the result is ignored. |
|---|
| 57 | .PP |
|---|
| 58 | In addition to \fBTcl_AppInit\fR, your application should also contain |
|---|
| 59 | a procedure \fBmain\fR that calls \fBTcl_Main\fR as follows: |
|---|
| 60 | .CS |
|---|
| 61 | Tcl_Main(argc, argv, Tcl_AppInit); |
|---|
| 62 | .CE |
|---|
| 63 | The third argument to \fBTcl_Main\fR gives the address of the |
|---|
| 64 | application-specific initialization procedure to invoke. |
|---|
| 65 | This means that you do not have to use the name \fBTcl_AppInit\fR |
|---|
| 66 | for the procedure, but in practice the name is nearly always |
|---|
| 67 | \fBTcl_AppInit\fR (in versions before Tcl 7.4 the name \fBTcl_AppInit\fR |
|---|
| 68 | was implicit; there was no way to specify the procedure explicitly). |
|---|
| 69 | The best way to get started is to make a copy of the file |
|---|
| 70 | \fBtclAppInit.c\fR from the Tcl library or source directory. |
|---|
| 71 | It already contains a \fBmain\fR procedure and a template for |
|---|
| 72 | \fBTcl_AppInit\fR that you can modify for your application. |
|---|
| 73 | |
|---|
| 74 | .SH KEYWORDS |
|---|
| 75 | application, argument, command, initialization, interpreter |
|---|
