"SfR Fresh" - the SfR Freeware/Shareware Archive

Member "q-7.11/modules/tk/README-Tk" of archive q-7.11.tar.gz:

    1 
    2 Q-Tk
    3 ====
    4 
    5 This module provides a basic interface between Q and Tcl/Tk. The operations of
    6 this module allow you to execute arbitrary commands in the Tcl interpreter,
    7 set and retrieve variable values in the interpreter, and invoke Q callbacks
    8 from Tcl/Tk.
    9 
   10 A recent version of Tcl/Tk is required (8.0 or later should do). You can get
   11 this from http://www.tcl.tk. Both releases in source form and binary releases
   12 for Windows and various Unix systems are provided there.
   13 
   14 The "stub" script is in tk.q, tk.c contains the actual C code for the
   15 module. A description of the available functions can be found in tk.q. A very
   16 basic example can be found in tk_test.q; a slightly more advanced example of a
   17 tiny but complete Q-Tk application is in tk_examp.q. For a really substantial
   18 Q-Tk program take a look at the graphed script in the Q-Graph package,
   19 available from the Q homepage.
   20 
   21 *** IMPORTANT ***
   22 
   23 When starting a new interpreter, the Tcl/Tk initialization code looks for some
   24 initialization files which it executes before anything else happens. Usually
   25 these files will be found without any further ado, but if that does not happen
   26 automatically, you must set the TCL_LIBRARY and TK_LIBRARY environment
   27 variables to point to the Tcl and Tk library directories on your system. For
   28 instance, using Tcl/Tk 8.4 under Unix, you might set these variables as
   29 follows (assuming Tcl/Tk is installed under /usr):
   30 
   31 (sh:)  export TCL_LIBRARY=/usr/lib/tcl8.4; export TK_LIBRARY=/usr/lib/tk8.4
   32 (csh:) setenv TCL_LIBRARY /usr/lib/tcl8.4; setenv TK_LIBRARY /usr/lib/tk8.4
   33 
   34 Under Windows, with Tcl/Tk installed under c:/tcl (these settings are also
   35 taken care of automagically by the Qpad application):
   36 
   37 set TCL_LIBRARY=c:/tcl/lib/tcl8.4
   38 set TK_LIBRARY=c:/tcl/lib/tk8.4
   39 
   40 Similar initializations may be required when using optional Tcl/Tk extension
   41 packages such as Tix (http://tix.mne.com).
   42 
   43 
   44 USAGE
   45 =====
   46 
   47 You can submit a command to the Tcl/Tk interpreter with `tk CMD' where CMD is
   48 a string. This also starts a new instance of the Tcl/Tk interpreter if it is
   49 not already running. To stop the Tcl/Tk interpreter, you can use the `tk_quit'
   50 function. Interpreters are local to the thread in which they are started. Thus
   51 in a multithreaded script you can have multiple interpreters running in
   52 different threads. (For this to work, your Tcl/Tk version must have been built
   53 with thread support. Otherwise only one interpreter in the main thread is
   54 allowed.)
   55 
   56 Simple dialogs can be created directly using Tk's `tk_messageBox' and
   57 `tk_dialog' functions. For instance:
   58 
   59 tk "tk_dialog .warning \"Warning\" \"Are you sure?\" warning 0 Yes No Cancel"
   60 
   61 Other kinds of common dialogs are available; see the Tcl/Tk manual for
   62 information.
   63 
   64 For more elaborate applications you probably have to explicitly create some
   65 widgets and provide a main loop which takes care of events and callbacks. For
   66 this purpose, the Tcl command `q' can be used to return a "callback message"
   67 from the Tcl interpreter to the calling Q script. The Q-Tk module maintains
   68 such messages in a private queue. You can access callback messages in FIFO
   69 fashion, using the `tk_reads' function which returns the oldest message as a
   70 string. There are also two convenience functions, tk_read = val tk_reads, and
   71 tk_readq = valq tk_reads, which are useful when the callback messages denote Q
   72 expressions which are to be evaluated immediately or returned as a quoted
   73 expression, respectively. All these functions, as well as the `tk_check' and
   74 `tk_ready' functions discussed below, also process pending events in the
   75 Tcl/Tk interpreter s.t. the display is updated when Tk commands or user
   76 actions change the state of the application.
   77 
   78 The Tcl/Tk interpreter keeps running until either `tk_quit' is called, or the
   79 main window is destroyed or closed. You can check whether the interpreter is
   80 currently running using the `tk_ready' function. A basic main loop, which
   81 repeatedly evaluates callback messages and processes events until the
   82 interpreter is exited, may look as follows:
   83 
   84 main_loop		= tk_read || main_loop if tk_ready;
   85 			= () otherwise;
   86 
   87 This is appropriate if the whole state of the application is kept in the Tcl
   88 interpreter. Otherwise you might wish to invoke the loop with some initial
   89 STATE value on which the callback functions operate. In this case you can
   90 change the definition of main_loop to something like the following:
   91 
   92 main_loop STATE		= main_loop (tk_read STATE) if tk_ready;
   93 			= STATE otherwise;
   94 
   95 In any case, the loop terminates as soon as the Tcl/Tk interpreter is exited,
   96 which can happen, e.g., in response to a callback which invokes the `tk_quit'
   97 function, Tcl code which destroys the main window (`destroy .'), or when the
   98 user closes the main window from the window manager.
   99 
  100 Note that the `tk_read' functions are blocking, i.e., they wait until a
  101 callback message becomes available. Sometimes you will also want to check
  102 beforehand whether there are any messages, which can be done with the
  103 `tk_check' function. This is useful, e.g., to implement any kind of background
  104 processing when the application is currently idle:
  105 
  106 main_loop STATE		= STATE if not tk_ready;
  107 			= main_loop (tk_read STATE) if tk_check;
  108 			= main_loop (idle STATE) otherwise;
  109 
  110 Alternatively, you can also do background processing using the Tcl
  111 interpreter's own facilities, i.e., the Tcl `after' command.
  112 
  113 Q-Tk also allows your script to set and retrieve variable values in the Tcl
  114 interpreter with the tk_set and tk_get functions. This is useful, e.g., to
  115 change the variables associated with entry and button widgets, and to retrieve
  116 the current values from the application. Note that all values are passed as
  117 strings, since this is really the only data type Tcl/Tk knows.
  118 
  119 
  120 TIPS AND TRICKS
  121 ==== === ======
  122 
  123 (1) Errors in Tcl/Tk commands can be handled by giving an appropriate
  124 definition of the `tk_error' function, which is invoked with an error message
  125 as its single argument. For instance, the following implementation of
  126 `tk_error' prints the error message and halts evaluation:
  127 
  128 tk_error MSG		= writes ("! Tk Error: "++MSG++"\n") || halt;
  129 
  130 If no definition for this function is provided, then errors cause a literal
  131 `tk_error MSG' expression to be returned as the result of the `tk'
  132 function. You can then check for such results to take an appropriate action.
  133 
  134 (2) The Tcl/Tk interpreter, when started, displays a default main window,
  135 which is required by most Tk applications. If this is not desired (e.g., if
  136 only the basic Tcl commands are needed), you can hide this window using a `tk
  137 "wm withdraw ."' command. To redisplay the window when it is needed, use the
  138 `tk "wm deiconify ."' command. It is also common practice to use `wm withdraw'
  139 and `wm deiconify' while creating the widgets of an application, in order to
  140 reduce "flickering".
  141 
  142 (3) The `tk' function can become rather tedious when coding larger Tk
  143 applications. Usually, you will prefer to put the commands making up your
  144 application into a separate Tcl/Tk script, and then invoke this script from
  145 your Q script using the Tcl `source' command, e.g.:
  146 
  147 ==> tk "source myapp.tcl"
  148 
  149 This is also the method to use for running existing Tk applications, e.g., if
  150 you create the interface using some interface builder like vtcl
  151 (http://vtcl.sourceforge.net).
  152 
  153 (4) The Tcl `package' command allows you to load additional extensions into
  154 the Tcl/Tk interpreter at runtime. For instance, if you want to work with the
  155 extra widgets provided by the Tix extension (see http://tix.mne.com), you can
  156 load the corresponding package as follows:
  157 
  158 ==> tk "package require Tix"
  159 
  160 (5) The Tcl `exit' procedure, just as in tclsh or wish, causes exit from the
  161 the current process. Since the Tcl/Tk interpreter hosted by the Q-Tk module
  162 runs as part of the Q interpreter process, and not as a separate child
  163 process, `tk "exit"' will exit from the Q interpreter and take you back to the
  164 shell. If you'd like `exit' to only exit the Tcl/Tk interpreter, without
  165 exiting Q, you can redefine the `exit' procedure, e.g., as follows:
  166 
  167 ==> tk "proc exit { {returnCode 0} } { q tk_quit }"
  168 
  169 (Of course, the `tk_quit' call will only take effect next time you use
  170 `tk_read', but presumably that will be done by your application's main loop.)
  171 
  172 If you want to do something with the exit code provided by `exit', you will
  173 have to provide an appropriate callback function, e.g.:
  174 
  175 ==> tk "proc exit { {returnCode 0} } { q quit_cb $returnCode }"
  176 
  177 An implementation of `quit_cb' might then look as follows:
  178 
  179 quit_cb 0  = writes "Application exited normally.\n" || tk_quit;
  180 quit_cb N  = writes ("Application exited with exit code "++str N++".\n") ||
  181              tk_quit otherwise;
  182 
  183 (6) If you need dialogs beyond the standard kinds of message boxes and common
  184 dialogs, you will have to do these yourself using a secondary toplevel. The
  185 dialog toplevel is just like the main window but will only be shown when the
  186 application needs it. You can construct both non-modal and modal dialogs this
  187 way, the latter can be implemented using Tk's `grab' command. An example can
  188 be found in the Q-Graph package on the Q homepage.
  189 
  190 (7) The latest version of this module also supports synchronous callbacks from
  191 the Tcl interpreter via the special `qval' command. This is the recommended
  192 method when the main loop of the application is actually executed in the Tcl
  193 interpreter, as is the case for some Tcl extensions like Gnocl
  194 (http://www.dr-baum.net/gnocl/). The arguments of `qval' take the same form as
  195 with the `q' command described above. They should form a valid Q expression
  196 which is parsed and evaluated in the Q interpreter. Such callbacks may also
  197 return a string value to the Tcl interpreter. There also is a second new Tcl
  198 command, `qtrace', which works like `qval' but also prints messages as the
  199 evaluation of the callback starts and end, which is _very_ useful for
  200 debugging purposes. ;-) The `qtrace' command also accepts a Tcl boolean value
  201 (any of 0, 1, true, false, yes, no, on, off are recognized) which causes it to
  202 switch on or off the automatic tracing of all calls to the qval command.
  203 
  204 
  205 Well, I hope this suffices to get you started. Please also see tk_examp.q for
  206 a tiny, but complete example Tk application. Furthermore, the tix.q example
  207 illustrates some of the additional bits of Tk code discussed above, including
  208 the method to run a Tix script with Q-Tk.
  209 
  210 
  211 Enjoy! :)
  212 
  213 January 23 2006
  214 Albert Graef
  215 ag@muwiinfa.geschichte.uni-mainz.de, Dr.Graef@t-online.de
  216 http://www.musikwissenschaft.uni-mainz.de/~ag