Using the development tools in applications

## 4.2 Using the development tools in applications

- Using the Development tools in the Tcl/Tk Embedding Interface
- Using the Remote Development Tools

The user can develop their own ECLiPSe applications using the development tools independent of the TkECLiPSe toplevel. There are two ways to do this, depending on if the user is also using the embedding Tcl/Tk interface (see the Embedding and Interfacing Manual) to provide a graphical front end:

- The user is using the embedding Tcl/Tk interface, and is thus developing a graphical front end in Tk. In this case the user can use the development tools via the embedding interface. This is described in section 4.2.1.
- The user is not using the embedding Tcl/Tk interface. In this case the user can use the development tools remotely, by using the remote_tools library. This is described in section 4.2.2.

### 4.2.1 Using the Development tools in the Tcl/Tk Embedding Interface

The development tool suite was designed to be independent of the TkECLiPSe top-level so that they can be used in a user's application. In effect, the user can replace the TkECLiPSe top-level with their own alternative top-level. Two simple examples in which this is done are provided in the `lib_tcl` library as `example.tcl` and `example1.tcl`. In addition, `tkeclipse` itself, in the file `tkeclipse.pl`, can be seen as a more complex example usage of the interface.
In order to use the Tcl/Tk interface, the system must be initialised as described in the Embedding manual. In addition, the user's Tcl code should probably also be provided as a package using Tcl's package facility, in order to allow the program to run in a different directory. See the Embedding manual and the example programs for more details on the initialisation needed.
The user should most likely provide a connection for the output stream of ECLiPSe so that output from ECLiPSe will go somewhere in the GUI. In addition, especially during the development, it is also useful to connect the error stream to some window so that errors (such as ECLiPSe compilation errors) are seen by the user. This can be done using the `ec_queue_connect` Tcl command described in the embedding manual.
Output from ECLiPSe need not be sent to a Tk window directly. The Tcl/Tk code which receives the output can operate on it before displaying it. It is intended that all such graphical operations should be performed on the Tcl side, rather than having some primitives provided on the ECLiPSe side.
The user can also provide balloon-help to his/her own application. The balloon help package is part of the Megawidget developed by Jeffrey Hobbs and used in TkECLiPSe. In order to define a balloon help for a particular widget, the following Tcl code is needed:

    balloonhelp <path> <text>

where `<path>` is the pathname of the widget, and `<text>` is the text that the user wants to display in the balloon.

### 4.2.2 Using the Remote Development Tools

The user can also use the development tools via the remote_tools library. In this case, the development tools are run as a separate program from the ECLiPSe session, and is attached to it via the Tcl/Tk remote interface (see the Embedding and Interfacing Manual). This allows any ECLiPSe session to use the development tools, as long as there is the capability for graphical display.
The main purpose for the remote_tools library is to allow the user to use the development tools in situations where (s)he cannot use the Tcl/Tk embedding interface, e.g. if ECLiPSe is already embedded into another programming language, or if the user needs to use the tty interface for ECLiPSe.

> Figure 4.3: Remote Development Tools Toplevel (left: ECLiPSe active; right: remote tools active)

Once attached to an ECLiPSe session, the remote development tools has its own window as shown in Figure 4.3. The Tools menu is the same as in TkECLiPSe, providing access to the same suite of development tools. The main body of the window consists of one button and a status indicator. The indicator shows wheather the tools can be used or not (the tools cannot be used when the ECLiPSe is active), and the button is used to pass control explicitly to ECLiPSe.
The ECLiPSe session and the development tools are two separate processes (and in fact they can be running on different machines) that are connected to each other via the remote Tcl/Tk interface. The interactions of the two processes are synchronised in that there is a thread-like flow of control between them: only one process can be `active' at any time. The interaction is similar to the standard interaction between a debugger and the program being debugged – debugging commands can only be issued while the execution of the program is suspended. In the same way, the user can only interact with the remote tools window when execution in the ECLiPSe session is suspended. The toplevel window of the remote tools has an indicator showing which side has control (see Figure 4.3). To allow ECLiPSe to resume execution, control is transferred back from the remote tools to ECLiPSe. This can either be done automatically from the tools (e.g. when one of the debug buttons is pressed in the tracer tool), or control can be transferred explicitly back to ECLiPSe via the “Resume ECLiPSe” button on the remote tools window.

#### Starting Remote Tools

To use the remote tools, the user must first load the remote_tools library with `lib(remote_tools)`. After loading the library, the user can start the remote tools by starting the development tools as a separate program and then manually attach the program to the ECLiPSe session. This allows the development tools to be run on a different machine from the ECLiPSe session. In this case, the user initiates the attachment in ECLiPSe with attach_tools/0:

    [eclipse 2]: attach_tools.
    Socket created at address holborn.icparc.ic.ac.uk/22849

ECLiPSe prints the host and port address it expects the remote tools to attach to, and execution is now suspended waiting for the remote tools to attach. This is done by running the tktools program, which is located with the other ECLiPSe executables. As stated, this program can be run on a different machine from the ECLiPSe session, as long as the two are connected via a network such as the internet. A connection window is then displayed as shown:
The same `host' and `port' fields as printed by the ECLiPSe session should be entered. The default `host' field is `localhost'. This will work if the remote tools are ran on the same machine as the ECLiPSe session. Otherwise the full name of the `host' as given by attach_tools/0 needs to be entered:
Typing return in the `port' field will start the attachment, and with success, the remote tools window (see Figure 4.3) will be displayed. The attach_tools/0 predicate will also return.
The user is not able to immediately interact directly with the remote tools, as the ECLiPSe session is initially given control. The user can use the ECLiPSe session as normal, with the additional availability of the development tools. For example, the display matrix predicates can be used as in TkECLiPSe. Also, the tracer tool replaces the previous tracing facilities of the ECLiPSe session (this would typically be the command-line debugger).
The tools can be triggered by events in the ECLiPSe session as described above. In order to use the tools in a more interactive way, control should be handed over to the remote tools. This can be done by calling the tools/0 predicate. When the remote tools have control, the user can now interactively select development tools from the Tools menu.
The remote_tools library provides several predicates to facilitate the use of the remote development tools:

tools
  Explicitly hands over control to the remote development tools. The tools window can then be used interactively. Execution on the ECLiPSe session is suspended until the remote tools allows ECLiPSe to resume, at which point the predicate succeeds. The predicate will abort if the development tools is disconnected from the ECLiPSe session.
attached(?ControlStream)
  Checks if the remote development tools have been attached to this ECLiPSe session or not. If attached, the predicate succeeds and unifies ControlStream with the stream name of the control stream. If not attached, th predicate fails.

Once attached, the remote development tools should be connected until the user quits the session. Although it is possible to disconnect the tools from the ECLiPSe session (from the File menu in the development tools window). This is not recommended, as there would not be any debugging facilities available after the disconnection – the original tracer would not be restored.
It is possible to attach the remote development tools to any ECLiPSe session, including one that is using the embedding Tcl/Tk interface (and indeed, to TkECLiPSe itself). However, using the tools via the embedding interface is usually the better option if available, because the tools are more tightly coupled to ECLiPSe in this case. This means that the communications between ECLiPSe and the tools are more efficient (and hence something like the display matrix would perform more efficiently).