ApCoCoA-1:HowTo:Install and Work with the Eclipse GUI

Introduction

This HowTo shows you how to get started with the new Eclipse Graphical User Interface (GUI) for (Ap)CoCoA.

Currently, the new GUI is still in an alpha state, which means there might be annoying bugs or the look and feel will change in the near future with new releases.

If this doesn't frighten you, you are more than welcome to

• follow the steps below and install the new GUI
• find and report any bugs
• request any feature you miss
• even contribute by developing new features yourself.

Prerequisites

• A current Java runtime environment (Java 5 JRE recommended)
• Eclipse If you are new to Eclipse, the variety of different packages to choose may be confusing. However, for using ApCoCoA it does not matter which package you choose and we therefore recommend to choose the smallest one (which currently is the Eclipse IDE for C/C++ Developers)
• ApCoCoA

Installation

Installing and Running Eclipse

After you download one of the Eclipse packages (e.g. the Eclipse IDE for C/C++ Developers), unpack the downloaded package go to the newly created folder eclipse and start the eclipse executable. That's all. After starting Eclipse, you will be asked to provide a workspace directory. This is where all your projects and ApCoCoA files will be stored. If unsure, just take the suggested default value. If you start Eclipse for the first time, you are presented with the welcome screen, which you just can close.

If you downloaded the Eclipse IDE for C/C++ Developers you now see the C/C++ perspective (a perspective is a special collection of ) which is the starting point for this tutorial.

Installing the Plugin

One of the really nice things in Eclipse is the ease of installing and updating plugins, i.e. extensions of the Eclipse platform that add new features and functionality, as the GUI plugin does. To install the ApCoCoA GUI plugin, follow these steps.

• In the menu bar, click Help > Software Updates ... > Tab Available Software
• Next, klick Add Site...
• Enter the URL http://www.apcocoa.org/updatesite/
  
• Then check Apcocoa GUI ...
• ... and click Install...
• Eclipse then looks up the plugins that have to be installed and presents you with a review and confirm page. Click Next
  
• Accept the license agreement and klick Finish.
  
• Next you will be asked to restart the Eclipse platform which is recommended.
• Finally, you should see some new additions in the menu and tool bars.
  
  

You are now ready to set up and use ApCoCoA with Eclipse.

First Steps

Configure Eclipse

In the current alpha release, neither ApCoCoA executables are not packed with the Eclipse plugin yet. The plugin does also not check for installed ApCoCoA executables. Therefore, the paths have to be configured manually as follows.

• Go to Window > Preferences > ApCoCoA Preferences
• Set paths to the ApCoCoA command line executable and ApCoCoA Server or BBF Server and click OK,<br/
  
  
• Verify the settings by starting ApCoCoA, clicking on the (Re)start ApCoCoA Process button . In the console view you can see now the ApCoCoA greeting message.
  
  

Create a new Project

All work done within Eclipse is organized into projects. To create a new project

• Go to File > New > Project ...
  
  
• In the Project Wizard, select Project in the General category and click Next.
• Name the project GUI Tutorial and click Finish.

In the Project Explorer on the left side you can see now the newly created project, moreover, Eclipse created a new folder in the workspace directory.

Create and use an (interactive) Editor Window

To enter (Ap)CoCoA commands and programs, you need an editor window. Within the (Ap)CoCoA QT-GUI, there are two kinds of editor windows or, more specific, editor tabs: a) the interactive default editor tab, where you enter commands but usually do not edit programs (since the window is cleared after sending its content to (Ap)CoCoA); and (b) the "persistent" editor tabs, where you edit your programs. The interactive behavior is mimicked in Eclipse if you create a special "file" with the name interactive.aco:

• Right-click on the GUI Tutorial project and select New > File.
• Create a new file named interactive.aco, click Finish.
• Type a sample command in the new editor window and send it to ApCoCoA, typing Ctrl+Enter.
• The editor windows content is then added to the history and the editor is cleared. As in the CoCoA QT-GUI, you can navigate through the histroy with Alt+Left and Alt+Right.
• Note that the content of interactive editors is not saved to disk!

 Tip: If you are uncomfortable with the key bindings, you can simply change them in the General Preferences (Window > Preferences > General > Keys).

To create a "normal" editor window, create a file with the extension .aco. Files with this extension are associated to ApCoCoA editors with all their features (syntax coloring, sending content to the ApCoCoA process via Enter+Enter,...).

Getting Help

To access the ApCoCoA Help go to Help > Help Contents. On the left side you find the ApCoCoA Handbook.

Further Topics

Working with the ApCoCoA / BBF Server

To start the ApCoCoA Server, click on the button Start ApCoCoA Server .

Since there is initially only one console view that would be shared by both the server and the cocoa process it is more convenient to

• pin the ApCoCoA console
• open a second console view
• rearrange the two console views (see below).

Adjust the Appearance

In Eclipse, it is possible to rearrange the visual components in (almost) any way you like via drag & drop.