tk/doc/Tk_Init.3

   1 '\"
   2 '\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
   3 '\"
   4 '\" See the file "license.terms" for information on usage and redistribution
   5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   6 '\"
   7 '\" RCS: @(#) $Id$
   8 '\"
   9 .so man.macros
  10 .TH Tk_Init 3 8.0 Tk "Tk Library Procedures"
  11 .BS
  12 .SH NAME
  13 Tk_Init, Tk_SafeInit \- add Tk to an interpreter and make a new Tk application.
  14 .SH SYNOPSIS
  15 .nf
  16 \fB#include <tk.h>\fR
  17 .sp
  18 int
  19 \fBTk_Init\fR(\fIinterp\fR)
  20 .sp
  21 int
  22 \fBTk_SafeInit\fR(\fIinterp\fR)
  23 .SH ARGUMENTS
  24 .AP Tcl_Interp *interp in
  25 Interpreter in which to load Tk.  Tk should not already be loaded
  26 in this interpreter.
  27 .BE
  28
  29 .SH DESCRIPTION
  30 .PP
  31 \fBTk_Init\fR is the package initialization procedure for Tk.
  32 It is normally invoked by the \fBTcl_AppInit\fR procedure
  33 for an application or by the \fBload\fR command.
  34 \fBTk_Init\fR adds all of Tk's commands to \fIinterp\fR
  35 and creates a new Tk application, including its main window.
  36 If the initialization is successful \fBTk_Init\fR returns
  37 \fBTCL_OK\fR;  if there is an error it returns \fBTCL_ERROR\fR.
  38 \fBTk_Init\fR also leaves a result or error message
  39 in \fIinterp->result\fR.
  40 .PP
  41 If there is a variable \fBargv\fR in \fIinterp\fR, \fBTk_Init\fR
  42 treats the contents of this variable as a list of options for the
  43 new Tk application.
  44 The options may have any of the forms documented for the
  45 \fBwish\fR application (in fact, \fBwish\fR uses Tk_Init to process
  46 its command-line arguments).
  47 .PP
  48 \fBTk_SafeInit\fR is identical to \fBTk_Init\fR except that it removes
  49 all Tk commands that are considered unsafe.  Those commands and the
  50 reasons for their exclusion are:
  51 .TP
  52 \fBbell\fR
  53 Continuous ringing of the bell is a nuisance.
  54 .TP
  55 \fBclipboard\fR
  56 A malicious script could replace the contents of the clipboard with
  57 the string \fB"rm -r *"\fR and lead to surprises when the contents of
  58 the clipboard are pasted.
  59 .TP
  60 \fBgrab\fR
  61 Grab can be used to block the user from using any other applications.
  62 .TP
  63 \fBmenu\fR
  64 Menus can be used to cover the entire screen and to steal input from
  65 the user.
  66 .TP
  67 \fBselection\fR
  68 See clipboard.
  69 .TP
  70 \fBsend\fR
  71 Send can be used to cause unsafe interpreters to execute commands.
  72 .TP
  73 \fBtk\fR
  74 The tk command recreates the send command, which is unsafe.
  75 .TP
  76 \fBtkwait\fR
  77 Tkwait can block the containing process forever
  78 .TP
  79 \fBtoplevel\fR
  80 Toplevels can be used to cover the entire screen and to steal input
  81 from the user.
  82 .TP
  83 \fBwm\fR
  84 If toplevels are ever allowed, wm can be used to remove decorations,
  85 move windows around, etc.
  86
  87 .SH KEYWORDS
  88 safe, application, initialization, load, main window