Getting around
==============
The GANGA GUI is designed with component windows that can be undocked from the main window to allow you to customise its layout according to your needs. The GANGA GUI is made up of several components:
   - Menubar_
   - Toolbar_
   - Monitoring_
   - `Job Builder`_
   - Scriptor_
   - Log_

.. TIP:: 
   Tooltips will appear when you move the mouse pointer over most widgets. This is a great way to understand what they are and how to use them. You may have to move the mouse over the headers of list widgets to see their associated tooltips.

Menubar
-------
Menu items are divided into job actions (Job), logical folder management actions (Folders), GUI management and configuration actions (View) and application assistance (Help).

.. figure:: menubar_pic_1.jpg

   Figure 3-1-1: Job-related actions. 

.. figure:: menubar_pic_2.jpg

   Figure 3-1-2: Logical Folder management actions.

.. figure:: menubar_pic_3.jpg

   Figure 3-1-3: GUI management and configuration actions.

Toolbar
-------
The toolbar provides quick access to job-related actions and also allows basic GUI component management (i.e. dock, undock and hide actions)

.. figure:: toolbar.jpg

   Figure 3-2-1: Description of the various buttons and icons in the toolbar.

Monitoring
----------
The *monitoring* panel provides a centralised view of all existing GANGA jobs. It provides information on individual jobs and checks for changes in the monitored fields for all jobs in transient states (i.e. *submitted* and *running* job states). Together with the menubar and toolbar, the *monitoring* panel constitutes the GANGA GUI main window.

The *monitoring* panel also has the *logical job folders* panel attached on its left (click on |Toggle logical job folders| button to reveal *logical folders* panel) and the job details description panel attached on its right (click on |Toggle job details| button to reveal *job details* panel) .

.. figure:: monitoring_pic_1.jpg

   Figure 3-3-1: A typical view of the monitoring panel with logical job folder organiser (left) and job details (right).

.. _`subjob notes`:

.. Note::
   Jobs (when defined and submitted with specialised Splitters_) can contain one or more subjobs. These jobs (also known as *master jobs*) will be displayed in the *monitoring* panel as job entries that can be expanded. When expanded, its subjobs are displayed accordingly. As there may be many (possibly several thousand) subjobs for a single master job, monitoring of subjobs is only enabled for visible subjobs (i.e. when the corresponding master job is expanded). This helps to reduce the performance impact of subjob monitoring when it is not required.

Customising headers
"""""""""""""""""""
To change the headers in the *monitoring* panel, simply *right-click* within the *monitoring* panel display widget and select *Modify headers* from the context-sensitive menu. A list of possible headers will appear in a pop-up window. Simply select headers you are interested in and click *OK*. Job *id* and *status* are mandatory fields and so cannot be changed. You can also change the displayed text of a particular header by *left-clicking* once on a particular text in the *Displayed Text* column.

.. figure:: monitoring_pic_2.jpg

   Figure 3-3-2: Select fields to display in the monitoring panel. Displayed text can be changed as well.

.. TIP::
   In the monitoring panel, the arrangement of header fields can be changed by simply *left-click and hold* on to a particular header and *drag* it to the desired position.

.. TIP::
   *Left-clicking* on a particular header will sort the list of jobs in that particular order (e.g. clicking on *status* will sort according to status). Clicking again will reverse that order.

Logical job folders
"""""""""""""""""""
Logical job folders help to organise jobs into logical collections. Nested folders can be created if it is deemed useful. Existing jobs can be freely added and removed from logical folders as such actions have no bearing on the actual jobs themselves. *Right-clicking* on logical folders and jobs will reveal a context-sensitive menu of appropriate actions. Figure 3-3-3 shows the various actions that can be initiated on a logical folder. Jobs and logical folders can be moved around by mean of the *drag and drop* facility; jobs can be dragged from the *monitoring* panel and dropped onto a logical folder.

.. figure:: monitoring_pic_3.jpg
   
   Figure 3-3-3: Logical job folder - A job management feature.

Searching
"""""""""
When the number of jobs increase, it becomes useful to be able to search for particular jobs. The *monitoring* panel includes just such a search facility that will search for jobs with details (currently displayed in the *monitoring* panel) that contain the specified string. 

.. figure:: monitoring_pic_4.jpg
   
   Figure 3-3-4: Search facility locates strings in the monitoring panel.


Job Builder
-----------
The job builder is designed to assist in the GANGA job building process. Various attributes of a GANGA job are presented in a nested (tree) list reinforcing the relationship between the various attributes and ensuring that all attributes can be easily accessed.

The job builder is a *dockable* window which is initially hidden. It becomes visible when a new job is created (i.e. using the |New Job| button in the toolbar or menu bar).

.. figure:: jobbuilder_pic_1.jpg

   Figure 3-4-1: GANGA job builder

.. TIP::
   To undock windows (i.e. Job Builder, Scriptor and Log windows), *double-click* on the docked window's left vertical border (the left border of each docked window looks slightly different/thicker). To do the reverse (i.e. to dock a floating window), simply *double-click* on the window's title bar (i.e. it's top edge).


The job builder window consists of a top row of multi-function tool buttons (i.e. left-clicking and holding these buttons will reveal a menu of additional functions). Tool buttons with more than one function are typically denoted by ellipsis-trailing text on the tool button (e.g. *New...*, *Save...*).

.. figure:: jobbuilder_pic_2.jpg

   Figure 3-4-2: Job builder tool buttons.

The |Kill|, |Remove| and |Submit| tool buttons are single function buttons that perform *kill*, *remove* and *submit* actions on the job concerned respectively.

Clicking on the |New...| tool button creates a new job. Clicking and holding the tool button reveals an additional menu that allows the creation of a new job based on existing Templates_.  

.. figure:: jobbuilder_pic_3.jpg

   Figure 3-4-3: The New... multifunction tool button.

Clicking on the |Save...| tool button saves the job currently being built. Clicking and holding the tool button reveals an additional menu that allows the creation of a copy of the current job and the saving of the current job as a template.

.. figure:: jobbuilder_pic_4.jpg

   Figure 3-4-4: The Save... multifunction tool button.

Templates
"""""""""
Job templates are designed to store jobs of particular interest which will typically be used to create other similar jobs. Templates can be removed by navigating to *Job > Remove Template* and selecting a template.

.. figure:: jobbuilder_pic_5.jpg

   Figure 3-4-5: Naming a new job template.

Splitters
"""""""""
Jobs may be split into smaller fragments to take advantage of distributed system backends (e.g. LCG, LSF). This can be easily achieved by filling in the *splitter* attribute of a job. To select a suitable splitter, click on the *splitter* attribute to highlight it. You will be presented with a selection of available splitters. Say we select the *ExeSplitter* (a simple splitter created for the sole purpose of illustrating the splitting mechanism and not for normal use). *ExeSplitter* has a single configurable attribute *apps*. Navigating to *apps*, we see that a selection of applications can be added to the list using the *Add* button. Six individually configurable applications have been added to the *apps* list in the example shown in Figure 3-4-6 below.

.. figure:: splitter_pic_1.jpg

   Figure 3-4-6: Creating a job that will split into several subjobs.

When this job is submitted, the new job entry in the *monitoring* panel will be made expandable. Expanding this *master* job will revealing it's subjobs. Once subjobs are revealed, they will be monitored as well i.e. their status will be checked and updated. See `subjob notes`_.

.. figure:: splitter_pic_2.jpg

   Figure 3-4-7: Master job with several subjobs running.


Scriptor
--------
The scriptor is a convenience tool which includes the *favourites* script store (top-left section), scripting panel with execute button (top-right section) and the interactive Python session (lower-half section).

.. figure:: scriptor_pic_1.jpg

   Figure 3-5-1: Scriptor - favourites script store (with context-sensitive menu), scripting panel and interactive Python session.

The *favourites* script store is a store for code snippets designed for quick and easy access. Choose a script from the *favourites* script store by simply *clicking* on it and its contents will be displayed in the scriptor window (right of script store). 

*Right-clicking* in the script store will reveal a list of possible actions (see Figure 3-5-1 above):

   | *Exec*
   |    Execute the selected script.
   | *New*
   |    Create an empty entry in the script store.
   | *Clone*
   |    Make a copy of an existing script.
   | *Remove*
   |    Delete the currently selected script store entry.
   | *Import*
   |    Load a script from an existing file.
   | *Export*
   |    Save a selected script to disk.

.. TIP:: 
   Descriptions can be added to existing scripts in the script store by *left-clicking* on the *Description* column of a particular script and entering the desired text.

The scripting panel is essentially a scratch pad for GANGA/Python commands allowing you to conveniently create and execute (using the *Execute* button) snippets of code within the same GANGA session (i.e. all jobs you create, modify or remove will be reflected in the *monitoring* panel). This is useful for anything from the occasional experimentation to customised bulk job submissions not catered for by existing Splitters_.

The interactive Python session window is an emulated Python shell. It is in this shell that scripts edited in the scripting panel are executed. Use the interactive Python session as you would with a normal Python shell. 

.. NOTE::
   You will not be able to exit from the interactive Python shell.


Log
---
The log window displays all log messages that would normally be displayed on the console from which GANGA was executed.


.. |Toggle job details| image:: Forward.png
.. |Toggle logical job folders| image:: Back.png
.. |New Job| image:: Write.png
.. |Kill| image:: ToolBtn_Kill.jpg
.. |Remove| image:: ToolBtn_Remove.jpg
.. |Submit| image:: ToolBtn_Submit.jpg
.. |New...| image:: ToolBtn_NewJob.jpg
.. |Save...| image:: ToolBtn_Save.jpg
