1#---------------------------------------------------------------------------- 2# help_gui w 3# 4# Create a top-level window that displays info for On GUI.. help item. 5# Maurice LeBrun, IFS 6# Adapted from mkStyles.tcl from widget demo. 7# 8# Arguments: 9# w - Name to use for new top-level window. 10#---------------------------------------------------------------------------- 11 12proc help_gui {{w .help_gui}} { 13 catch {destroy $w} 14 toplevel $w 15 dpos $w 16 wm title $w "Help on GUI" 17 wm iconname $w "help_gui" 18 normal_text_setup $w 19 20 insertWithTags $w.t {\ 21 The PLPLOT/TK user interface is constructed from TK widgets, using Tcl 22as a (dynamic) specification language. The Tcl scripts provided with PLPLOT 23control the layout of the user interface, initialization of the widgets, and 24some of the binding of actions to events. Widgets, on the other hand, are 25all coded in C for speed. 26 27 The fundamental addition to PLPLOT to allow it to use Tcl/TK effectively 28has been the creation of a PLPLOT widget, called a "plframe". It was 29originally based on the TK frame widget but has many enhancements, as well 30as close ties to the underlying graphics library. The plframe widget can 31be created, mapped, and destroyed basically just like a TK frame widget. 32In addition, it supports numerous widget commands. 33 34 The default PLPLOT/TK interface looks like a window with a top-level 35menu bar, containing any number of frames devoted to plotting. These child 36windows contain a bar with an end-of-plot indicator, a "Plot" menu, a forward 37page button (also a back page button when plrender is being used), and a 38region for issuing status or prompt messages (initially containing the main 39window name of the application). Scrollbars appear to the right and bottom 40of the plframe when in zoom mode. The actual plframe has no decoration, but 41interacts with all of the surrounding widgets. The plframe and surrounding 42widgets should be considered as one entity. 43 44 There are several ways in which the plframe widget can be utilized, but 45the most usual is via selection of the TK driver when running an 46application linked to PLPLOT. The structure of the code then can be 47illustrated as follows: 48 49 50 Parent process Communication Child process 51 channel 52 53 User-code 54 | plserver 55 plplot TK driver | 56 Tcl interpreter <------- TK send -------> Tcl interpreter 57 | | 58 data writer -------- named pipe- -----> plframe widget 59 data reader 60 | 61 child X window 62 63 64 The user-code and the renderer (called } normal 65 insertWithTags $w.t {plserver} bold 66 insertWithTags $w.t {) form a client/server 67relationship, and are separate processes. Under typical usage, where the 68user-code starts first, it forks (vfork on systems that support it) and execs 69the renderer. Tcl/TK communication (via X properties) is used between their 70embedded interpreters to send commands back and forth. An extended version 71of Tcl called Tcl-DP allows sockets to be used for this, and the model will 72eventually be extended to allow the user code and the renderer to be running 73on different machines. The existence of an interpreter in each process 74(actually each plplot stream that uses the TK driver) allows for a very easy 75and robust method of sending commands between processes. The data goes 76through via an alternate channel for maximum speed. 77 78Also supported are some alternate configurations: 79 80(a) the server creates widgets, then launches applications passing the 81 name of the plframe widget to plot to. You could launch multiple 82 codes, with each plotting into a specific widget. 83 84(b) the server creates widgets, then calls functions to do the actual 85 plotting. This is in fact the easiest configuration since all the 86 work is done in one process, but has the disadvantage that the 87 user interface goes "dead" while the calculation is proceeding. 88 89 By offloading the GUI-building code into a simple script language, it 90becomes easy to build menus, buttons, scrollbars, etc. All of these are 91configurable by the user, as well as the ability to map events (such as 92button presses) to functions calls in your own program. Note: the 93alternate configurations as well as the customization options are not yet 94fully tested. 95 96 Most of the currently supported operations of the PLPLOT/TK user 97interface are self-explanatory, and can be understood with a bit of 98experimentation. Better documentation will eventually follow. Some 99points to remember: 100 101 1. When the plframe widget is created, it grabs the input focus to 102allow easy advancement to the next plot by hitting <Return> (note: TK focus 103doesn't behave quite the same as under other X toolkits). However it is 104possible for it to lose the focus by bringing up help windows and such. If 105the user interface seems to be responsive, try moving the mouse cursor into 106the window you want to receive the input. Most widgets (including plframe) 107will grab the focus when you move the cursor into their window. 108 109 2. There are sometimes keyboard-based shortcuts. The ``OK'' button 110at the bottom of most dialogs can typically be selected by hitting <Return>. 111You can move between multiple input entries in a dialog by hitting <Tab>. 112The text widgets used in the help entries can be scrolled by using the 113up and down arrow keys, page up or page down keys, space, backspace, and 114delete keys. 115 116 3. A good way to customize the resources (fonts, colors, etc) used 117in the interface is to copy the plconfig.tcl file, modify it according to 118taste, then put it into a directory where it will be found at startup. Also 119a tclIndex file must be created for it (``plserver -mkidx'' will do this) and 120put in the same directory. The Tcl interpreter searches directories for 121commands in the following order: 122 123 user-specified directory(s) (set by -auto_load argument) 124 Current directory 125 ${PLPLOT_DIR}/tcl 126 ${HOME}/tcl 127 INSTALL_DIR/tcl 128 129where HOME and PLPLOT_DIR are environmentals, and INSTALL_DIR is 130set during installation (typically /usr/local/plplot). 131 132I'll probably think of more later.. 133} normal 134 $w.t configure -state disabled 135 $w.t mark set insert 0.0 136} 137