source: branches/sandbox/tkcon/docs/start.html @ 1142

Last change on this file since 1142 was 931, checked in by toby, 12 years ago

include rest of files
File size: 13.5 KB
Line 
1<HTML>
2<HEAD>
3<TITLE>tkcon: Getting Started</TITLE>
4<LINK REL="STYLESHEET" TYPE="text/css" HREF="./style.css">
5</HEAD>
6
7<BODY BGCOLOR=#FFFFFF>
8
9<TABLE WIDTH=100% BORDER=0 CELLSPACING=2 CELLPADDING=0 BGCOLOR=#000000><TR><TD>
10<!-- start header info -->
11<TABLE WIDTH=100% BORDER=0 CELLSPACING=0 CELLPADDING=0 BGCOLOR=#FFFFFF>
12<TR>
13<TH><FONT SIZE=+3>tkcon: Getting Started</FONT></TH>
14<TD align=right>
15<A href="http://tkcon.sourceforge.net/"> 
16<IMG src="http://sourceforge.net/sflogo.php?group_id=11462&type=1" width="88"
17height="31" border="0" alt="SourceForge Logo"></A>
18</TD>
19</TR>
20</TABLE>
21<!-- end header info -->
22
23</TD></TR><TR><TD>
24<!-- start main navigation table -->
25<TABLE BORDER=1 CELLPADDING=2 CELLSPACING=2 BGCOLOR=#CCCCCC width=100%>
26<TR>
27<TH CLASS="hi"><A HREF="index.html" CLASS="hi">Documentation</A></TH>
28<TH><A HREF="purpose.html">Purpose &amp; Features</A></TH>
29<TH><A HREF="limits.html">Limitations</A></TH>
30<TH><A HREF="todo.html">To&nbsp;Do</A></TH>
31<TH><A HREF="license.terms">License</A></TH>
32</TR><TR>
33<TH COLSPAN=2><A HREF="plugin.html">Online Demo</A>
34(requires <A HREF="http://tcl.activestate.com/software/plugin/">Tk plugin</A>)</TH>
35<TH COLSPAN=3><A HREF="nontcl.html">Using TkCon with other Tk Languages</A></TH>
36</TR>
37</TABLE>
38<!-- end main navigation table -->
39</TD></TR><TR><TD>
40<!-- start secondary navigation table -->
41<TABLE BORDER=1 CELLPADDING=2 CELLSPACING=2 BGCOLOR=#BBBBBB width=100%>
42<TR>
43<TH CLASS="hi2"><A HREF="start.html" CLASS="hi2">Getting Started</A></TH>
44<TH><A HREF="bindings.html">Special Bindings</A></TH>
45<TH><A HREF="procs.html">Procedures</A></TH>
46<TH><A HREF="demopic.gif">Screenshot</A></TH>
47</TR>
48<TR>
49<TH><A HREF="dump.html"><CODE>dump</CODE></A></TH>
50<TH><A HREF="tkcon.html"><CODE>tkcon</CODE></A></TH>
51<TH><A HREF="idebug.html"><CODE>idebug</CODE></A></TH>
52<TH><A HREF="observe.html"><CODE>observe</CODE></A></TH>
53</TR>
54</TABLE>
55<!-- end secondary navigation table -->
56</TD></TR><TR><TD BGCOLOR=#FFFFFF>
57<DIV CLASS="indent">
58<H3>Resource File:</H3>
59
60TkCon will search for a resource file in "<CODE>$env(HOME)/.tkconrc</CODE>"
61(Unix), "<CODE>$env(HOME)/tkcon.cfg</CODE>" (Windows) or
62"<CODE>$env(PREF_FOLDER)/tkcon.cfg</CODE>" (Macintosh).  On DOS machines,
63"<CODE>$env(HOME)</CODE>" usually refers to "<CODE>C:\</CODE>".  TkCon
64never sources the "<CODE>~/.wishrc</CODE>" file.  The resource file is
65sourced by each new instance of the console.  An example resource file is
66provided below.
67
68<H3>Command Line Arguments</H3>
69
70Except for <CODE>-rcfile</CODE>, command line arguments are handled after
71the TkCon resource file is sourced, but before the slave interpreter or the
72TkCon user interface is initialized.  <CODE>-rcfile</CODE> is handled right
73before it would be sourced, allowing you to specify any alternate file.
74Command line arguments are passed to each new console and will be evaluated
75by each.  To prevent this from happening, you have to say
76<CODE>tkcon main set argv {}; tkcon main set argc 0</CODE>.
77 <P>
78For these options, any unique substring is allowed.
79
80<DL>
81
82<DT> <CODE>-argv</CODE> (also <CODE>--</CODE>)
83<DD> Causes TkCon to stop evaluating arguments and set the remaining args to
84be argv/argc (with <CODE>--</CODE> prepended).  This carries over for any
85further consoles.  This is meant only for wrapping TkCon around programs
86that require their own arguments.
87
88<DT> <CODE>-color-&lt;color&gt;</CODE> <I>color</I>
89<DD> Sets the requested color type to the specified color for tkcon.
90See the <B>Variables</B> section for the recognized
91<i>&lt;color&gt;</i> names.
92
93<DT> <CODE>-eval</CODE> (also <CODE>-main</CODE> or <CODE>-e</CODE>)
94<DD> A tcl script to eval in each main interpreter.  This is evaluated
95after the resource file is loaded and the slave interpreter is created.
96Multiple <CODE>-eval</CODE> switches will be recognized (in order).
97
98<DT> <CODE>-exec</CODE> <I>slavename</I>
99<DD> Sets the named slave that tkcon operates in.  In general, this is only
100useful to set to "" (empty), indicating to tkcon to avoid the
101multi-interpreter model and operate in the main environment.  When this is
102empty, any further arguments will be only used in the first tkcon console
103and not passed onto further new consoles.  This is useful when using tkcon
104as a console for extended wish executables that don't load there commands
105into slave interpreters.
106
107<DT> <CODE>-font</CODE> <I>font</I>
108<DD> Sets the font that tkcon uses for its text windows.  If this isn't
109a fixed width font, tkcon will override it.
110
111<DT> <CODE>-nontcl</CODE> <I>TCL_BOOLEAN</I>
112<DD> Sets <CODE>::tkcon::OPT(nontcl)</CODE> to <I>TCL_BOOLEAN</I>.  Needed
113when attaching to non-Tcl interpreters.
114
115<DT> <CODE>-package</CODE> <I>package_name</I> (also <CODE>-load</CODE>)
116<DD> Packages to automatically load into the slave interpreters (ie - "Tk").
117
118<DT> <CODE>-rcfile</CODE> <I>filename</I>
119<DD> Specify an alternate tkcon resource file name.
120
121<DT> <CODE>-root</CODE> <I>widgetname</I>
122<DD> Makes the named widget the root name of all consoles (ie - .tkcon).
123
124<DT> <CODE>-slave</CODE> <I>tcl_script</I>
125<DD> A tcl script to eval in each slave interpreter.  This will append
126the one specified in the tkcon resource file, if any.
127
128</DL>
129
130Some examples of tkcon command line startup situations:
131<DL>
132
133<DT> <CODE>megawish tkcon.tcl -exec "" -root .tkcon mainfile.tcl</CODE>
134<DD> Use tkcon as a console for your megawish application.  You can avoid
135starting the line with <CODE>megawish</CODE> if that is the default wish
136that tkcon would use.  The <CODE>-root</CODE> ensures that tkcon will not
137conflict with the
138
139<DT> <CODE>tkcon.tcl -font "Courier 12" -load Tk</CODE>
140<DD> Use the courier font for tkcon and always load Tk in slave
141interpreters at startup.
142
143<DT> <CODE>tkcon.tcl -rcfile ~/.wishrc -color,bg white</CODE>
144<DD> Use the <CODE>~/.wishrc</CODE> file as the resource file, and
145a white background for tkcon's text widgets.
146
147</DL>
148
149<H3>Variables:</H3>
150
151Certain variables in TkCon can be modified to suit your needs.  It's
152easiest to do this in the resource file, but you can do it when time the
153program is running (and some can be changed via the Prefs menu).  All these
154are part of the master interpreter's <code>::tkcon</code> namespace.  The
155modifiable array variables are <CODE>::tkcon::COLOR</CODE> and
156<CODE>::tkcon::OPT</CODE>.  You can call '<CODE>tkcon set
157::tkcon::COLOR</CODE>' when the program is running to check its state.
158Here is an explanation of certain variables you might change or use:
159
160<DL>
161
162<DT> <CODE>::tkcon::COLOR(bg)</CODE>
163<DD> The background color for tkcon text widgets.
164Defaults to the operating system default (determined at startup).
165
166<DT> <CODE>::tkcon::COLOR(blink)</CODE>
167<DD> The background color of the electric brace highlighting, if on.
168Defaults to <font color=#FFFF00>yellow</font>.
169
170<DT> <CODE>::tkcon::COLOR(cursor)</CODE>
171<DD> The background color for the insertion cursor in tkcon.
172Defaults to <font color=#000000>black</font>.
173
174<DT> <CODE>::tkcon::COLOR(disabled)</CODE>
175<DD> The foreground color for disabled menu items.
176Defaults to <font color=#4D4D4D>dark grey</font>.
177
178<DT> <CODE>::tkcon::COLOR(proc)</CODE>
179<DD> The foreground color of a recognized proc, if command highlighting is on.
180Defaults to <font color=#008800>dark green</font>.
181
182<DT> <CODE>::tkcon::COLOR(var)</CODE>
183<DD> The background color of a recognized var, if command highlighting is on.
184Defaults to <font color=#FFC0D0>pink</font>.
185
186<DT> <CODE>::tkcon::COLOR(prompt)</CODE>
187<DD> The foreground color of the prompt as output in the console.
188Defaults to <font color=#8F4433>brown</font>.
189
190<DT> <CODE>::tkcon::COLOR(stdin)</CODE>
191<DD> The foreground color of the stdin for the console.
192Defaults to <font color=#000000>black</font>.
193
194<DT> <CODE>::tkcon::COLOR(stdout)</CODE>
195<DD> The foreground color of the stdout as output in the console.
196Defaults to <font color=#0000FF>blue</font>.
197
198<DT> <CODE>::tkcon::COLOR(stderr)</CODE>
199<DD> The foreground color of stderr as output in the console.
200Defaults to <font color=#FF0000>red</font>.
201 <P>
202
203<DT> <CODE>::tkcon::OPT(autoload)</CODE>
204<DD> Packages to automatically load into the slave interpreter (ie - 'Tk').
205This is a list.  Defaults to {} (none).
206
207<DT> <CODE>::tkcon::OPT(blinktime)</CODE>
208<DD> The amount of time (in millisecs) that braced sections should
209<I>blink</I> for.  Defaults to 500 (.5 secs), must be at least 100.
210
211<DT> <CODE>::tkcon::OPT(blinkrange)</CODE>
212<DD> Whether to blink the entire range for electric brace matching or to
213just blink the actual matching braces (respectively 1 or 0, defaults to 1).
214
215<DT> <CODE>::tkcon::OPT(buffer)</CODE>
216<DD> The size of the console scroll buffer (in lines).
217Defaults to 512.
218
219<DT> <CODE>::tkcon::OPT(calcmode)</CODE>
220<DD> Whether to allow <CODE>expr</CODE> commands to be run at the command
221line without prefixing them with <CODE>expr</CODE> (just a convenience).
222
223<DT> <CODE>::tkcon::OPT(cols)</CODE>
224<DD> Number of columns for the console to start out with.  Defaults to 80.
225
226<DT> <CODE>::tkcon::OPT(dead)</CODE>
227<DD> What to do with dead connected interpreters.  If <CODE>dead</CODE>
228is <i>leave</i>, TkCon automatically exits the dead interpreter.  If
229<CODE>dead</CODE> is <i>ignore</i> then it remains attached waiting for
230the interpreter to reappear.  Otherwise TkCon will prompt you.
231
232<DT> <CODE>::tkcon::OPT(exec)</CODE>
233<DD> This corresponds to the <CODE>-exec</CODE> option above
234
235<DT> <CODE>::tkcon::OPT(font)</CODE>
236<DD> Font to use for tkcon text widgets (also specified with -font).
237Defaults to the system default, or a fixed width equivalent.
238
239<DT> <CODE>::tkcon::OPT(gets)</CODE>
240<DD> Controls whether tkcon will overload the gets command to work with
241tkcon.  The valid values are: <code>congets</code> (the default), which
242will redirect <code>stdin</code> requests to the tkcon window;
243<code>gets</code>, which will pop up a dialog to get input; and {} (empty
244string) which tells tkcon not to overload gets.  This value must be set at
245startup to alter tkcon's behavior.
246
247<DT> <CODE>::tkcon::OPT(history)</CODE>
248<DD> The size of the history list to keep.  Defaults to 48.
249
250<DT> <CODE>::tkcon::OPT(hoterrors)</CODE>
251<DD> Whether hot errors are enabled or not.  When enabled, errors that
252are returned to the console are marked with a link to the error info
253that will pop up in an minimal editor.  This requires more memory because
254each error that occurs will maintain bindings for this feature, as long
255as the error is in the text widget.  Defaults to on.
256
257<DT> <CODE>::tkcon::OPT(library)</CODE>
258<DD> The path to any tcl library directories (these are appended to the
259auto_path when the after the resource file is loaded in).
260
261<DT> <CODE>::tkcon::OPT(lightbrace)</CODE>
262<DD> Whether to use the brace highlighting feature or not
263(respectively 1 or 0, defaults to 1).
264
265<DT> <CODE>::tkcon::OPT(lightcmd)</CODE>
266<DD> Whether to use the command highlighting feature or not
267(respectively 1 or 0, defaults to 1).
268
269<DT> <CODE>::tkcon::OPT(maineval)</CODE>
270<DD> A tcl script to execute in the main interpreter after the slave
271interpreter is created and the user interface is initialized.
272
273<DT> <CODE>::tkcon::OPT(maxmenu)</CODE>
274<DD> A number that specifies the maximum number of packages to show
275vertically in the Interp-&gt;Packages menu before breaking into
276another column.  Defaults to 15.
277
278<DT> <CODE>::tkcon::OPT(nontcl)</CODE>
279<DD> For those who might be using non-Tcl based Tk attachments, set this
280to 1.  It prevents TkCon from trying to evaluate its own Tcl code in an
281attached interpreter.  Also see my <A HREF="nontcl.html">notes for non-Tcl
282based Tk interpreters</A>.
283
284<DT> <CODE>::tkcon::OPT(prompt1)</CODE>
285<DD> Like tcl_prompt1, except it doesn't require you use '<CODE>puts</CODE>'.
286No equivalent for tcl_prompt2 is available (it's unnecessary IMHO).
287<BR>Defaults to {([file tail [pwd]]) [history nextid] % }.
288
289<DT> <CODE>::tkcon::OPT(rows)</CODE>
290<DD> Number of rows for the console to start out with.  Defaults to 20.
291
292<DT> <CODE>::tkcon::OPT(scollypos)</CODE>
293<DD> Y scrollbar position.  Valid values are <CODE>left</CODE> or
294<CODE>right</CODE>.  Defaults to <CODE>left</CODE>.
295
296<DT> <CODE>::tkcon::OPT(showmenu)</CODE>
297<DD> Show the menubar on startup (1 or 0, defaults to 1).
298
299<DT> <CODE>::tkcon::OPT(showmultiple)</CODE>
300<DD> Show multiple matches for path/proc/var name expansion
301(1 or 0, defaults to 1).
302
303<DT> <CODE>::tkcon::OPT(slaveeval)</CODE>
304<DD> A tcl script to execute in each slave interpreter right after it's
305created.  This allows the user to have user defined info always available
306in a slave.  Example:
307<PRE>   set ::tkcon::OPT(slaveeval) {
308                proc foo args { puts $args }
309                lappend auto_path .
310        }</PRE>
311
312<DT> <CODE>::tkcon::OPT(slaveexit)</CODE>
313<DD> Allows the prevention of <CODE>exit</CODE> in slaves from exitting
314the entire application.  If it is equal to <CODE>exit</CODE>, exit will
315exit as usual, otherwise it will just close down that interpreter (and
316any children).  Defaults to <VAR>close</VAR>.
317
318<DT> <CODE>::tkcon::OPT(subhistory)</CODE>
319<DD> Allow history substitution to occur (0 or 1, defaults to 1).  The
320history list is maintained in a single interpreter per TkCon console
321instance.  Thus you have history which can range over a series of attached
322interpreters.
323</DL>
324
325 <P>
326
327An <b>example TkCon resource file</b> might look like:
328
329<PRE style="color: #883333">######################################################
330## My TkCon Resource File
331 
332# Use a fixed default font
333#tkcon font fixed; # valid on unix
334#tkcon font systemfixed; # valid on win
335tkcon font Courier 12; # valid everywhere
336
337# Keep 50 commands in history
338set ::tkcon::OPT(history) 50
339
340# Use a pink prompt
341set ::tkcon::COLOR(prompt) pink
342######################################################</PRE>
343
344 <p>
345</DIV>
346</TD></TR></TABLE>
347
348<HR NOSHADE SIZE=1>
349<ADDRESS><FONT SIZE=2>&copy;
350<A HREF="mailto:jeff.hobbs@acm.org">Jeffrey Hobbs</A></FONT></ADDRESS>
351
352</BODY>
353</HTML>
Note: See TracBrowser for help on using the repository browser.