1Obtaining Help 2============== 3 4Brief balloon-style help can be obtained on most components of this GUI 5by setting balloon help from the Tools menu. With balloon help turned on, 6if the mouse cursor is left on an item that has balloon help for a short 7period of time, a text message (the balloon) will popup giving some short 8information on the particular item. Balloon help is on by default. To make 9the default to be no balloon help, use the TkECLiPSe preference editor. 10 11If a more detailed help file (like this one for the top-level) is available 12for a particular window, it can be obtained by typing Alt-h (Alt key with 13h) within the window. If a menu bar is available in a particular window, 14the help file can also be obtained from the menu. 15 16*Note* functions that are accessed via the right-mouse button can 17alternatively be accessed via control-left mouse button. This is mainly for 18allow one-button mouse users, where the mouse button corresponds to the 19left-mouse button. 20 21Summary of function 22=================== 23 24The toplevel provides a graphical user interface to ECLiPSe's top-level. A 25set of tools are also provided to help the user to develop programs. 26 27If tkeclipse is started from a command line, two command line options are 28available to set the sizes of the stacks: 29 30 -g <size> The maximum size to which the global/trail stack area can 31 grow to. The size is specified in kilobytes (followed by an 32 optional K), in megabytes (followed by M) or in gigabytes 33 (followed by G). 34 35 -l <size> The maximum size to which the global/trail stack area can 36 grow to. The size is specified in kilobytes (followed by an 37 optional K), in megabytes (followed by M) or in gigabytes 38 (followed by G). 39 40The user can also specify various initial settings for the tkeclipse which 41would override the default values. See the initial settings section for 42more. 43 44Errors and warning messages disable scrolling on the output 45window. Scrolling can be re-enabled by left-clicking on the y scroll-bar. 46 47Layout 48====== 49 50The toplevel is divided into the following components (from the top): 51 52A menu bar 53 54A box indicating the current toplevel module, and a query entry box 55 56A set of buttons for controlling the execution of a program, plus an 57indicator of the status of the current query. 58 59A Results window where the result of executing the query is shown. 60 61An Output and Error Messages window where outputs from a program and also 62messages from ECLiPSe are displayed. 63 64Initial Settings 65================ 66 67The user can specify initial settings for various parameters of tkeclipse, 68which will override the predefined defaults. These parameters are divided 69into two types: those specific to the tkeclipse toplevel, and those that 70are used by the development tools (which may also be applicable to the 71toplevel, e.g. balloonhelp). The initial values of these parameters 72can either be specified by using the Preference Editor tool, or they can be 73specified directly: 74 75 a) On Unix: in the files .tkeclipserc (for toplevel parameters) and 76 .tkeclipsetoolsrc (for development tools parameters). The system will 77 first search for these files in the current directory, and then in the 78 user's home directory. 79 80 Each parameter is specified on a separate line in the appropriate 81 file, in the format <parameter> <value> 82 83 84 b) On Windows: these parameters are specified in the Windows registry, 85 under two keys: 86 87 HKEY_CURRENT_USER\\Software\\IC-Parc\\ECLiPSe\\tkeclipserc (for toplevel) 88 HKEY_CURRENT_USER\\Software\\IC-Parc\\ECLiPSe\\tkeclipsetoolsrc (for 89 development tools) 90 91 92 Each parameter is specified as a value under the appropriate key. The 93 name of the value is the parameter, and the type of the value is a 94 string. 95 96The initial settings for the parameters for the tools will be loaded during 97the call to ec_tools_init, so they will be set when the user uses the tools 98in their own application. 99 100The following parameters are currently allowed: 101 102Toplevel: 103--------- 104 105Parameter Possible Value Description 106________________________________________________________________________ 107globalsize positive integer The maximum size to which the 108 global/trail stack area can grow 109 to. The unit is megabytes. 110 Overridden by the -g option. 111 112localsize positive integer The maximum size to which the 113 local/control stack area can grow 114 to. The unit is megabytes. 115 Overridden by the -l option. 116 117initquery string An ECLiPSe query that TkECLiPSe 118 will execute immediately after 119 startup. It can be used to perform 120 user defined initialisations. 121 122default_module string The default toplevel module name 123 (default: eclipse). 124 125default_language string The default language name 126 (default: eclipse_language). 127 128 129See the manual for more detailed description of the memory areas of ECLiPSe. 130 131See the Preference Editor help file for a description of the development 132tools parameters. 133 134 135 136Functionality 137============= 138 139Menu Bar 140-------- 141 142 File Menu 143 144 Change directory - allows to change ECLiPSe's current working 145 directory. 146 147 Compile - allows the user to select an ECLiPSe source file. This 148 file will be compiled and loaded. 149 150 Use module - allows the user to select an ECLiPSe module file 151 (source or precompiled). This will be compiled/loaded and 152 its contents imported into the current toplevel module. 153 154 Edit - allows the user to select a file to edit. The text editor 155 to be used can be specified in the Preference Editor. The 156 default values are the value of the VISUAL environment variable 157 under Unix, or Wordpad under Windows. 158 159 Cross referencer - allows the user to select a source file, runs the 160 cross referencer over it (see library(xref)), and displays the 161 resulting graph in a new window. 162 163 Source checker (lint) - allows the user to select a source file, runs 164 the lint source checker over it (see library(lint)), possibly 165 displaying warnings in the Output window. 166 167 Compile example - like 'Compile', but shows files from the example 168 directory which is distributed with ECLiPSe. 169 170 New module - allows the user to specify a new module that will 171 be created. The new module becomes the current toplevel 172 module. If an existing module is given, then tkeclipse 173 will attempt to erase the module first. Locked module and 174 the default module cannot be erased this way. The user 175 needs to specify the name of the module and can also 176 specify the language that the module will be loaded with. 177 178 Clear toplevel module - allows the user to clear the current 179 toplevel module, i.e. to erase it and start with a fresh, 180 empty module. The language loaded with the module will be 181 eclipse_language. Use `New module' to create a module with 182 a different language. 183 184 Exit - Leave ECLiPSe 185 186 187 Query Menu 188 189 Run - run the query in the Query Entry window (this is the same 190 as clicking the run-button) 191 192 Time Profile - run the query in the Query Entry window with the 193 timing profiler (see lib(profile)). Only the first solution 194 will be computed. 195 196 Port Profile - run the query in the Query Entry window with the 197 port profiler (see lib(port_profile)). Only the first solution 198 will be computed. 199 200 History - pop up the query history window, containing all previous 201 queries in reverse order. 202 203 204 Tools Menu - this offers a set of tools that the user can use for 205 developing ECLiPSe programs. These tools can also be available to user 206 programs which have their own GUI developed via ECLiPSe's new Tcl/Tk 207 interface (see the example programs in the lib_tcl directory). See the 208 tools' respective help files for more details on a specific tool. 209 210 Compile scratch-pad - allows the compilation of short ECLiPSe code. 211 Source Files - this tool provides an interface to the files tracked 212 by ECLiPSe make command. 213 Predicates - this tool provides an interface to obtaining 214 information on predicates that are currently in ECLiPSe. 215 216 Delayed Goals - displays the goals that are currently being delayed 217 during execution. 218 Tracer - a debugging tool that allows the user to trace the 219 execution of a program. 220 Inspector - allows the user to browse and examine ECLiPSe terms. 221 Visualisation Client - launches a Java visualisation client (see 222 the Visualisation Manual for details) 223 224 Global Settings - allows the user to view and change global settings 225 of ECLiPSe. 226 Statistics - display statistical information on ECLiPSe, which are 227 updated at regular intervals. 228 Simple Query - allows the user to run a simple query once (no 229 backtracking) at a different break-level from the main top-level 230 execution. 231 ECLiPSe Help - an interface to ECLiPSe's help/1 predicate to obtain 232 information on ECLiPSe built-ins. 233 234 Preference Editor - See above 235 236 Balloon Help - toggles balloon help. 237 238 239 Help Menu 240 241 Balloon Help - toggles balloon help. 242 243 About this ECLiPSe - shows information on the version of ECLiPSe 244 being run. 245 246 Toplevel Help - this window 247 248 Other help topics 249 250 251 252Current module box 253------------------ 254 255This shows the current module. The user can change to a different module by 256the popdown list from the arrow button on the right of the box. 257 258Query entry box and buttons 259--------------------------- 260 261The user can type in ECLiPSe queries here. A terminating full-stop is not 262necessary. This can be used as in a traditional tty interface, with most 263built-ins available in a tty interface also available, although 264more convenient methods may be available through the GUI, such as 265examining the ECLiPSe global state (via the global settings tool). 266 267A query is executed either by typing return, or by clicking the run 268button. Alternatives can be obtained by clicking the more button. Note that 269clicking on the run button when more alternatives are available will 270re-execute the query. 271 272A history of previous queries can be obtained from either the popdown list 273on the arrow at the right of the box, or by selecting 'History' from the 274Query menu or the query entry context menu. The popdown list contains 275the previous queries with duplicates removed in chronological order 276(oldest first), while the history window shows all the previous queries 277in reverse chronological order. A previous query can then be selected and 278re-executed from either of these lists. The user can also step through the 279previous queries via the up and down arrow keys. Typing the tab key will 280try to complete the query with the most recent matching query from the 281(non-duplicated) history. 282 283The status of the currently executing or just executed query is shown in 284the status box: 285 286 Yes: the query has executed successfully. 287 More: the query has executed successfully, and there is still 288 search-space left to explore which might produce more solutions. The 289 more button would be active. 290 No: the query has failed. 291 Abort: the query has aborted (e.g. with errors). 292 Idle: no query yet, or previous query terminated. 293 Running: the query is currently being executed. Note that if the tracer 294 tool is active, then it is possible for the execution to be stopped at a 295 trace-line in the tracer tool, and continued execution of the query is 296 controlled from the tracer tool in this case. 297 298The make button: runs the make command, which will recompile any 299 files that are tracked by the system and which have been changed 300 since they were compiled (see the Source File tool from the Tools 301 menu for the interface to the file tracking). 302 303The interrupt button: use this button to interrupt an executing query. 304 This will pop up a window that allows to abort or continue the execution. 305 If the debugger is on, it can be forced into creep mode. 306 307 308Results Window 309-------------- 310 311For each query, this window shows the query that is executed, followed by 312the bindings made to the variables in the query after it succeeds. The 313most recent query is shown in blue, with the previous queries shown in 314black. In addition, the status after executing the query is shown after any 315bindings: More/Yes/No/Abort. 316 317The contents of the results window can be copied and pasted onto a different 318window. Select an area to be copied by dragging the left mouse-button, and 319then on Unix systems, the results can be pasted with the middle button. On 320Windows, middle button can only be used to paste to another window of 321tkeclipse. The standard single click to select character, double click to 322select word and triple click to select line under the mouse is available. 323To paste to a window from a different application, the selected 324text must first be copied using control-C and pasted using control-V (or 325Control-/ to select all). 326 327The outputs on the results window and the output and error messages window 328can be matched up by right clicking on the text in one of the windows and 329selecting the `Highlight corresponding' option from the background menu. 330The corresponding sections in both windows will be highlighted in light blue. 331Note also that this highlighting is orthogonal to the normal selection. 332 333The results and output windows can be cleared by right click and selecting 334the `Clear this window' option from the background menu. 335 336 337Output and Error Messages Window 338-------------------------------- 339 340Outputs from the user program (e.g. from write/1 to the standard output) 341are sent to this window. The outputs from the most recent query is shown in 342blue; those from previous queries in black. 343 344Messages from ECLiPSe are also sent to this window, both normal messages, 345and error/warning messages (those sent to the error stream). The error 346messages are shown in red, and warning messages in orange. To alert the 347user that errors/warnings have occurred, the window is positioned to 348display the last of any such messages in the current query, and 349scrolling is disabled until the next query. To re-enable scrolling before 350the next query, left-click on the y-scroll bar. 351 352The contents of the output window can be copied and pasted onto a different 353window. Select an area to be copied by dragging the left mouse-button, and 354then on Unix systems, the results can be pasted with the middle button. On 355Windows, middle button can only be used to paste to another window of 356tkeclipse. To paste to a window from a different application, the selected 357text must first be copied using control-C and pasted using control-V. 358 359The relative sizes of the results window and the output and error messages 360window can be adjusted by dragging their common boundary. 361 362