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