This is gps.info, produced by makeinfo version 4.0 from gps.texi.


File: gps.info,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)

Using the GNAT Programming System
*********************************

   Using the GNAT Programming System

   GPS, the GNAT Programming System

   Version 1.2.2

   Date: 2003/06/11 09:15:34

   Copyright (C) 2001-2003, ACT Europe.  This document may be copied,
in whole or in part, in any form or by any means, as is or with
alterations, provided that (1) alterations are clearly marked as
alterations and (2) this copyright notice is included unmodified in any
copy.

* Menu:

* Introduction::
* Description of the Main Windows::
* Integrated Help::
* Multiple Document Interface::
* Editing Files::
* Source Navigation::
* Project Handling::
* Searching and Replacing::
* Compilation/Build::
* Source Browsing::
* Debugging::
* Version Control System::
* Tools::
* Working in a Cross Environment::
* Customizing and Extending GPS::
* Environment::


 --- The Detailed Node Listing ---

Description of the main windows
* The Welcome Dialog::
* The Menu Bar::
* The Tool Bar::
* The Work Space::
* The Project Explorer::
* The Messages Window::
* The Shell Window::
* The Locations Tree::
* The Status Line::

Integrated Help
* The Help Menu::
* Adding New Help Files::

Multiple Document Interface
* Selecting Windows::
* Closing Windows::
* Maximized and Iconified Windows::
* Docked Windows::
* Floating Windows::
* Moving Windows::

Editing Files
* General Information::
* Editing Sources::
* The File Selector::
* Menu Items::
* Using an External Editor::
* Using the Clipboard::

Source Navigation
* Support for Cross References::
* The Navigate Menu::
* Source Navigation Contextual Menus::

Project Handling
* Description of the Projects::
* Scenarios and Configuration Variables::
* The Project Explorer (Editing Projects)::
* The Project Menu::
* The Project Wizard::
* The Project Properties Editor::
* The Switches Editor::
* The Project Browser::

Searching and Replacing

Compilation/Build
* The Build Menu::
* Integrating existing build procedures with the GPS build system::

Source Browsing
* General Issues::
* Call Graph::
* Dependency Browser::
* Entity Browser::

Debugging
* The Debug Menu::
* The Call Stack Window::
* The Data Window::
* The Breakpoint Editor::
* The Memory Window::
* Using the Source Editor when Debugging::
* The Debugger Console::

Version Control System
* The VCS Explorer::
* The VCS Menu::
* The Version Control Contextual Menu::

Tools
* The Tools Menu::
* Visual Comparison::
* Code Fixing::

Working in a Cross Environment
* Customizing your Projects::
* Debugger Issues::

Customizing and Extending GPS
* The Preferences Dialog::
* Customizing the Menu and Tool Bar::
* Adding Support for New Languages::
* Defining Text Aliases::
* Defining New Styles and Key Bindings::
* Scripting GPS::

Environment
* Command Line Options::
* Environment Variables::
* Files::
* Reporting Suggestions and Bugs::
* Solving Problems::


File: gps.info,  Node: Introduction,  Next: Description of the Main Windows,  Prev: Top,  Up: Top

Introduction
************

GPS is a complete integrated development environment that gives access
to a wide range of tools and integrates them smoothly.

   GPS gives access to built-in file editing; HTML based help system;
complete compile/build/run cycle; intelligent source navigation;
project management; general graph technology giving access to many
different browsers such as source dependency, project dependency, call
graphs, etc...; fully integrated visual debugger, based on the GVD
technology, and enhanced for inclusion in GPS; generic version control
system, providing access to CVS, ClearCase, and possibly others in the
future; many other tools such as a visual comparison, automatic
generation of files, source reformatting.

   GPS is fully customizable, providing several levels of
customizations: a first level, available through the preferences dialog;
a second level, which allows you to customize your menu items, tool bar
and key bindings; a third level, which allows you to automate
processing through scripts; and a fourth level, which allows any kind
of very specific or tight integration, due to the open nature of GPS,
and to its architecture.  See *Note Customizing and Extending GPS:: for
more details.

   GPS also integrates with existing editors such as Emacs and Vi, see
*Note Using an External Editor::.


File: gps.info,  Node: Description of the Main Windows,  Next: Integrated Help,  Prev: Introduction,  Up: Top

Description of the Main Windows
*******************************

* Menu:

* The Welcome Dialog::
* The Menu Bar::
* The Tool Bar::
* The Work Space::
* The Project Explorer::
* The Messages Window::
* The Shell Window::
* The Locations Tree::
* The Execution Window::
* The Status Line::


File: gps.info,  Node: The Welcome Dialog,  Next: The Menu Bar,  Up: Description of the Main Windows

The Welcome Dialog
==================

When starting GPS, a welcome dialog is displayed by default, giving the
following choices:

Start with default project in directory
     If you select this option and click on the `OK' button, GPS will
     create a default internal project with the following properties:

     The project supports Ada files only, using the default GNAT
     naming scheme: `.ads' for spec files, `.adb' for body files.

     A single source directory corresponding to the current directory.
      The current directory can be set by modifying the text entry on
     clicking   on the `Browse' button. All the Ada files found in this
     directory   will be considered as part of the default project.

     The object directory where the object and executable files will
     be put, corresponding also to the current directory.

Create new project with wizard
     Selecting this option and clicking on the `OK' button will start a
     wizard allowing you to specify most of the properties for a new
     project. Once the project is created, GPS will save it and load it
     automatically.  See *Note The Project Wizard:: for more details on
     the project wizard.

Open existing project
     You can select an existing project by clicking on the `Browse'
     button, or by using a previously loaded project listed in the
     combo box. When a project is selected, clicking on the `OK' button
     will load this project and open the main window.

Always show this dialog when GPS starts
     If unset, the welcome dialog won't be shown in future sessions.
     In this case, GPS will behave as follows: it will first look for a
     `-P' switch on the command line, and load the corresponding
     project if present.  Then, it will look for a project file in the
     current directory and will load the first project file found.

     If no project file can be found in the current directory, GPS will
     start with the default project.

     To reset this property, go to the menu `Edit->Preferences'.  *Note
     The Preferences Dialog::.

Quit
     If you click on this button, GPS will terminate immediately.

   When you specify a -P switch on the command line, or if there is
only one project file in the current directory, GPS will start
immediately with the project file specified, instead of displaying the
welcome dialog.

   In addition, if you specify source files on the command line, GPS
will also start immediately, using the default project if no project is
specified.


File: gps.info,  Node: The Menu Bar,  Next: The Tool Bar,  Prev: The Welcome Dialog,  Up: Description of the Main Windows

The Menu Bar
============

This is a standard menu bar that gives access to all the global
functionalities of GPS. It is usually easier to access a given
functionality using the various contextual menus provided throughout
GPS: these menus give direct access to the most relevant actions given
the current context (e.g. a project, a directory, a file, an entity,
...). Contextual menus pop up when the right mouse button is clicked.

   The menu bar gives access to the following items:

File
     *Note The File Menu::.

Edit
     *Note The Edit Menu::.

Navigate
     *Note The Navigate Menu::.

VCS
     *Note The VCS Menu::.

Project
     *Note The Project Menu::.

Build
     *Note The Build Menu::.

Debug
     *Note The Debug Menu::.

Tools
     *Note The Tools Menu::.

Window
     *Note Multiple Document Interface::.

Help
     *Note The Help Menu::.


File: gps.info,  Node: The Tool Bar,  Next: The Work Space,  Prev: The Menu Bar,  Up: Description of the Main Windows

The Tool Bar
============

The tool bar provides shortcuts via buttons to some typical actions:
creating a new file, opening a file, saving the current file; undo/redo
last editing; cut to clipboard, copy to clipboard, paste from clipboard;
go to previous/next location; start/continue the debugging session,
step/next execution, finish current procedure.

   The icon on the far right of the tool bar will be animated to
indicate that an action (e.g. a build or a search) is going on in
background.


File: gps.info,  Node: The Work Space,  Next: The Project Explorer,  Prev: The Tool Bar,  Up: Description of the Main Windows

The Work Space
==============

   The whole work space is based on a multiple document interface,
*Note Multiple Document Interface::.


File: gps.info,  Node: The Project Explorer,  Next: The Messages Window,  Prev: The Work Space,  Up: Description of the Main Windows

The Project Explorer
====================

The project explorer is composed of multiple views which can be accessed
by default by clicking on the corresponding pages, or if they are not
shown by using the `Project' menu items.

The explorer views
------------------

The explorer views are initially displayed on the left side of the GPS
window. Their goal is to show a full view of the various components of
your projects. These various components are presented below.

   The following screen shot displays the two pages side-by-side: on the
left, the `Project View', and on the right the `File View'.

   Each view provides an interactive search capability allowing you to
quickly search in the information currently displayed. The default key
to start an interactive search is <Ctrl-i>. See *Note Interactive
Search:: for more details.

   The various components that are displayed in these explorers are the
following:

projects
     As mentioned before, all the sources you are working with are put
     under control of projects. These projects are a way to store the
     switches to use for the various tools, as well as a number of
     other properties.

     They can be organized into a project hierarchy, where a root
     project can import other projects, with their own set of sources.

     Initially, a default project is created, that includes all the
     sources in the current directory.

     The `Project View' page of the explorer displays this project
     hierarchy: the top node in this view is the root project of your
     application (generally, this is where the source file that contains
     the main subprogram will be located). Then a node is displayed for
     each imported project, and recursively for their own imported
     projects.

     A given project might appear multiple times in the `Project View',
     if it is imported by several other projects.

     There exists a second display for this project view, which lists
     all projects with no hierarchy: all projects appear only once in
     the explorer, at the top level. This display might be useful for
     deep project hierarchies, to make it easier to find projects in
     the explorer.

     This display is activated through the contextual menu entry `Show
     flat view', which acts as a switch between the two displays.

     A special icon with an exclamation mark is displayed if the project
     was modified, but not saved yet. You can choose to save it at any
     time by right-clicking on it. GPS will remind you to save it
     before any compilation.

directories
     The files inside a project can be organized into several physical
     directories on the disk. These directories are displayed under each
     project node in the `Project View', or directly mimicking their
     physical organization on the disk (including Windows drives) in the
     `File View'.

     In the `Project View', you can chose whether you want to see the
     absolute path names for the directories or paths relative to the
     location of the project. This is done through the `Show absolute
     paths' contextual menu.

     Special nodes are created for object and executables directories.
     No files are shown for these.

files
     The source files themselves are stored in the directories, and
     displayed under the corresponding nodes. Note that in the `Project
     View', only the source files that actually belong to the project
     (i.e. are written in a language supported by that project and
     follow its naming scheme) are actually visible.

     The `File View' will display all the files that actually exist on
     the disk. Filters can be set through the contextual menu to only
     show the files and directories that belong to the project
     hierarchy. See the menu `Show files from project only'.

     A given file might appear multiple times in the `Project View', if
     the project it belongs to is imported by several other projects.

entities
     If you open the node for a source file, the file is parsed by one
     of the fast parsers integrated in GPS so that all entities
     declared in the project can be shown. These entities are grouped
     into various categories, which depend on the language. Typical
     categories include subprograms, packages, types, variables,
     tasks,...

   Double-clicking on an file, or simple clicking on any entity will
open a source editor and display respectively the first line in this
file or the line on which the entity is defined.

   If you open the search dialog through the `Navigate->Find...' menu,
you have the possibility to search for anything in the explorer, either
a file or an entity. Note that searching for an entity might be a
little slow if you have lots of files.

   A contextual menu, named `Locate in Explorer', is also provided when
inside a source editor. This will automatically search for the first
entry for this file in the explorer. This contextual menu is also
available in other modules, e.g. when selecting a file in the
`Dependency Browser'.

The configuration variables
---------------------------

As described in the GNAT User's Guide, the project files can be
configured through external variables (typically environment
variables). This means that e.g. the exact list of source files, or the
exact switches to use to compile the application can be changed when
the value of these external variables is changed.

   GPS provides a simple access to these variables, through a special
area on top of the `Project View'. These variables are called
`Configuration Variables', since they provide various scenarios for the
same set of project files.

   A combo box is displayed in this area for each environment variable
the project depends on. The current value of the variable can be set
simply by selecting it from the pop-down window that appears when you
click on the arrow on the right of the variable name

   New variables can be added through the contextual menu `Add
Configuration Variable' in the `Project View'. The list of possible
values for a variable can be changed by clicking on the button on the
left of the variable's name.

   Whenever you change the value of one of the variables, the project is
automatically recomputed, and the list of source files or directories
is changed dynamically to reflect the new status of the project.
Starting a new compilation at that point will use the new switches, and
all the aspects of GPS are immediately affected according to the new
setup.


File: gps.info,  Node: The Messages Window,  Next: The Shell Window,  Prev: The Project Explorer,  Up: Description of the Main Windows

The Messages Window
===================

The Messages window is used by GPS to display information and feedback
about operations, such as build output, information about processes
launched, error messages.

   This is a read-only window, which means that only output is
available, no input is possible.

   For an input/output window, see *Note The Execution Window:: and also
*Note The Shell Window::


File: gps.info,  Node: The Shell Window,  Next: The Locations Tree,  Prev: The Messages Window,  Up: Description of the Main Windows

The Shell Window
================

These windows give access to the various scripting languages supported
by GPS, and allow you to type commands such as editing a file or
compiling without using the menu items or the mouse.

   See *Note Scripting GPS:: for more information on using scripting
languages within GPS.

   You can use the <up> and <down> keys to navigate through the history
of commands.


File: gps.info,  Node: The Locations Tree,  Next: The Execution Window,  Prev: The Shell Window,  Up: Description of the Main Windows

The Locations Tree
==================

The Location Tree is filled whenever GPS needs to display a list of
locations in the source files (typically, when performing a global
search, compilation results, and so on).

   The Location Tree shows a hierarchy of categories, which contain
files, which contain locations. Clicking on a location item will bring
up a file editor at the requested place. Right-clicking on file or
category items brings up a contextual menu allowing you to remove the
corresponding node from the view.

   To navigate through the next and previous location (also called
`Tag'), you can use the menu items `Navigate->Previous Tag' and
`Navigate->Next Tag', or the corresponding key bindings.

   In some cases, a wrench icon will be associated on the left of a
compilation message. See *Note Code Fixing:: for more information on
how to make advantage of this icon.


File: gps.info,  Node: The Execution Window,  Next: The Status Line,  Prev: The Locations Tree,  Up: Description of the Main Windows

The Execution Window
====================

Each time a program is launched using the menu `Build->Run', a new
execution window is created to provide input and output for this
program.

   In order to allow post mortem analysis and copy/pasting, the
execution windows are not destroyed when the application terminates.

   To close an execution window, click on the cross icon on the top
right corner of the window, or use the menu `File->Close', or the menu
`Window->Close' or the key binding <Ctrl-W>.

   If you close the execution window while the application is still
running, a dialog window is displayed, asking whether you want to kill
the application, or to cancel the close operation.


File: gps.info,  Node: The Status Line,  Prev: The Execution Window,  Up: Description of the Main Windows

The Status Line
===============

The status line is composed of two areas: on the left a status bar and
on the right a progress bar.

   The status bar is used to display temporary information about GPS
operations. Note that most of the information GPS displays can be found
in the `Messages' window.

   The progress bar is used to display information about on going
operations such as builds.


File: gps.info,  Node: Integrated Help,  Next: Multiple Document Interface,  Prev: Description of the Main Windows,  Up: Top

Integrated Help
***************

* Menu:

* The Help Menu::
* Adding New Help Files::

By default when you start GPS, the working area contains a help window
displaying HTML help files. On-line help for the GNAT tools is available
from the `Help' menu item.

   Since HTML pages can contain lots of complex information, resizing
the help window can take some time, making the user interface less
responsive.  It is therefore recommended to close the `Help' window
when not using it. You can reopen this window at any time using the
`Help' menu item.

   For the best use of the integrated help, it is recommended to load
small HTML pages each time instead of long pages which will be slow to
load and display.


File: gps.info,  Node: The Help Menu,  Next: Adding New Help Files,  Up: Integrated Help

The Help Menu
=============

The Help menu item provides the following entries:

Contents
     This opens a special HTML file that contains links for all the
     documentation files currently registered in GPS, *Note Adding New
     Help Files::.

Zoom in
     Increase the size of the font used to display the help file.

Zoom out
     Decrease the size of the font used to display the help file.

Open HTML file...
     Open a file selection dialog to load an HTML file.

About
     Display a dialog giving information about the versions of GPS and
     GNAT used:

   This menu contains a number of additional entries, depending on what
documentation packages were installed on your system. See the next
section to see how to add new help files.

   The help window also provides a contextual menu that gives the
possibility to copy the current selection to the clipboard.


File: gps.info,  Node: Adding New Help Files,  Prev: The Help Menu,  Up: Integrated Help

Adding New Help Files
=====================

GPS will search for the help files in the list of directories set in
the environment variable `GPS_DOC_PATH' (a colon-separated list of
directories on Unix systems, or semicolon-separated list of directories
on Windows systems). If this variable is not set, the default directory
`<prefix>/doc/gps/html' is searched.  If the file cannot be found in
any of these directories, the corresponding menu item will be disabled.

   The environment variable `GPS_DOC_PATH' can either be set by each
user in his own environment, or can be set system-wide by modifying the
small wrapper script `gps' itself on Unix systems.

   The specific list of files shown in the menus is set by reading the
index files in each of the directories in `GPS_DOC_PATH'. These index
files must be called `gps_index.xml', and their format can be see in
the following example:

     <?xml version="1.0"?>
     <index>
        <file>
           <name>file.html</name>
           <descr>Tooltip text</descr>
           <category>name</category>
           <menu>/Help/item</menu>
        </file>
     </index>

   There should be one `<file>' tag per help file. This tag contains
four children tags:

name
     This is the name of the file. It can be either an absolute file
     name, or a file name relative to one of the directories in
     `GPS_DOC_PATH'.

     This name can contain a reference to a specific anchor in the html
     file, using the standard HTML syntax.

            <name>file#anchor</name>

descr
     This is the description for this help file. It appears in a tool
     tip for the menu item.

category
     This is used in the `Help->Contents' menu to organize all the
     documentation files.

menu
     This is the full path to the menu. It behaves like a UNIX path,
     except it reference the various menus, starting from the menu bar
     itself. The first character of this path must be `"/"'. The last
     part of the path is the name of the new menu item. If not set, no
     menu is displayed for this file, although it will still appear in
     the `Help->Contents' menu


File: gps.info,  Node: Multiple Document Interface,  Next: Editing Files,  Prev: Integrated Help,  Up: Top

Multiple Document Interface
***************************

* Menu:

* Selecting Windows::
* Closing Windows::
* Maximized and Iconified Windows::
* Docked Windows::
* Floating Windows::
* Moving Windows::

All the windows that are part of the GPS environment are under control
of what is commonly called a multiple document interface (MDI for
short). This is a common paradigm on windowing systems, where related
windows are put into a bigger window which is itself under control of
the system or the windows manager.

   This means that, by default, no matter how many editors, browsers,
explorers,... windows you have opened, your system will still see only
one window (On Windows systems, the task bar shows only one icon).
However, you can organize the GPS windows exactly the way you want, all
inside the GPS main window.

   For instance, you can choose to iconify some windows which are
temporarily useless to you; you can choose to put some windows on top
of others; you can resize all the windows to the size you want; and so
on.

   This section will show the various capacities that GPS provides to
help you organize your workspace.


File: gps.info,  Node: Selecting Windows,  Next: Closing Windows,  Up: Multiple Document Interface

Selecting Windows
=================

At any time, there is only one selected window in GPS (the active
window). You can select a window either by clicking in its title bar,
which will then get a different color, or by selecting its name in the
menu `Window'.

   Alternatively, windows can be selected with the keyboard. By default,
the selection key is <Alt-Tab>. When you press it, a temporary dialog
is popped-up on the screen, with the name of the window that will be
selected when the key is released. If you press the selection key
multiple times, this will iterate over all the windows currently open
in GPS.

   This interactive selection dialog is associated with a filter,
displayed below the name of the selected window. If you maintain <Alt>
pressed while pressing other keys than <Tab>, this will modify the
current filter. From then on, pressing <Alt-Tab> will only iterate
through those windows that match the filter.

   The filter is matched by any window whose name contains the letter
you have typed. For instance, if you are currently editing the files
`unit1.adb' and `file.adb', pressing <t> will only leave `unit1.adb'
selectable.


File: gps.info,  Node: Closing Windows,  Next: Maximized and Iconified Windows,  Prev: Selecting Windows,  Up: Multiple Document Interface

Closing Windows
===============

Wherever the windows are displayed, they are always closed in the same
manner. In the right side of the title bar of the window, three small
buttons are displayed. The rightmost button is a cross. Clicking on
this button will close the window.

   When a window is closed, the focus is given to the window of the same
part of the MDI (each of the docks or the middle area) that previously
had the focus. Therefore, if you simply open an editor as a result of a
cross-reference query, you can simply close that editor to go back to
where you were before.

   Alternatively, you can also select the window by clicking anywhere in
its title bar, and then select the menu `Window->Close'


File: gps.info,  Node: Maximized and Iconified Windows,  Next: Docked Windows,  Prev: Closing Windows,  Up: Multiple Document Interface

Maximized and Iconified Windows
===============================

The MDI is initially split into three parts: one window to the left,
one to the bottom, and a bigger one that occupies the remaining space.

   The first two will be discussed in *Note Docked Windows::.  The
third area is the one that provides the most flexibility:

maximized windows
     The windows in this area are initially maximized. This means that
     if you have several windows, a notebook will be created, and only
     one window will be visible at any given time. You select the
     window you want to see by clicking on the appropriate tab.

     Note that if there are a lot of windows, two small arrows will
     appear on the right of the tabs. Clicking on these arrows will
     show the remaining tabs.

     You can go back to this maximized state in two ways: either select
     the menu `Window->Maximize All', or click on the middle button on
     the right of the title bar of any window (this button shows two
     small squares, and will toggle between maximized and unmaximized
     states.

unmaximized windows
     As opposed to putting all the windows inside a notebook, GPS can
     also let you organize them freely when they are unmaximized.
     Select the menu `Window->Unmaximize All', or click again in the
     middle button on the right of the title bar.

     In this mode, the windows can be resized freely by clicking on the
     border of any side or in one of their four corners, as usual on
     windowing systems.

     They can also be moved around. As a result, you can choose for
     instance to display several windows side by side, or one on top of
     the others.

     To make it easier to get to these standard organizations, GPS
     provides a few shortcuts through menus:

    `Window->Cascade'
          All the windows will be resized to the same size, and be
          moved one on top of the other, so that the top and left sides
          of all windows are visible. This way, you can easily select
          any window

    `Window->Tile Horizontally'
          All the windows are resized to the same dimensions, and are
          put side by side, from left to right. No window will overlap
          any other.

    `Window->Tile Vertically'
          All the windows are resized to the same dimensions, and are
          put side by side, from top to bottom. No window will overlap
          any other.

Iconified windows
     When the windows are unmaximized, you can also choose to
     temporarily iconify some of them. This is done by clicking on the
     leftmost button in the title bar (the one that shows a single
     line).

     The window will then be resized so that only part of its title bar
     is visible, and none of its actual contents. Icons can still be
     moved around as you want, but they can not be resized. You need to
     first de-iconify the window, by clicking once again on the same
     button.

     When de-iconified, a window will restore the size and position it
     had before it was iconified.


File: gps.info,  Node: Docked Windows,  Next: Floating Windows,  Prev: Maximized and Iconified Windows,  Up: Multiple Document Interface

Docked Windows
==============

As mentioned before, the GPS work space is initially split into three
windows. The one on the left and the one at the bottom are called
docking area.

   They have a different behavior from the central area, since windows
in these areas are necessarily grouped into a notebook. Thus, only one
of them is visible at any given time, and you select the one you want to
see by clicking on its name in the tabs area.

   GPS includes four such areas, one on each side of the main area. Some
visual objects will initially be displayed in one of these docking areas
instead of in the central one, like the project explorer, the message
window,... Although you can not control this initial position, it is
possible to change it later on (*Note Moving Windows::).

   However, you can still choose precisely the dimension you want for
this docking area (either its width for the left and right areas, or
its height for the top and bottom ones).

   Between each docking area and the central one, there is a small
handle (on which a series of dots are drawn), that you can move
interactively with the mouse, to resize the docking areas). By default,
when you move such a handle, a line will appear on top of all other
windows in GPS to show you the new position the docking area will have
when you release the mouse. You can set up a preference (menu
`Edit->Preferences') to indicate that you want the resizing to be
opaque, which might give more intuitive results.

   Note that when a window is docked (i.e. put in a docking area), some
of the buttons in its title bar are grayed out and inactive.

   A simple way to dock a window is to select it, and then select the
menu `Window->Docked'. We will see in *Note Moving Windows:: that there
is a more intuitive way to do the same thing.

   In some cases, GPS will change the color used to draw the title of
the window in the notebook tab. This indicates that the window content
has been updated, but the window wasn't visible. Typically, this is
used to indicate that new messages have been written in the messages or
console window.


File: gps.info,  Node: Floating Windows,  Next: Moving Windows,  Prev: Docked Windows,  Up: Multiple Document Interface

Floating Windows
================

Although the MDI, as described so far, is already extremely flexible,
it is possible that you prefer to have several top-level windows under
direct control of your system or window manager. This would be the case
for instance if you want to benefit from some extra possibilities that
your system might provide (virtual desktops, different window
decoration depending on the window's type, transparent windows,...).

   GPS is fully compatible with this behavior, since windows can also be
floating windows. Any window that is currently embedded in the MDI can
be made floating at any time, simply by selecting the window and then
selecting the menu `Window->Floating'. The window will then be
detached, and can be moved anywhere on your screen, even outside of
GPS's main window.

   There are two ways to put a floating window back under control of
GPS.  The more general method is to select the window through its title
in the menu `Window', and then select `Window->Floating'.

   The second method assumes that the preference Destroy Floats in the
menu `Edit->Preferences' has been set to false. Then, you can simply
close the floating window by clicking in the appropriate title bar
button, and the window will be put back in GPS. If you actually want to
close it, you need to click once again on the cross button in its title
bar.

   A special mode is also available in GPS, where all windows are
floating. The MDI area in the main window becomes invisible. This can
be useful if your system or window manager provides windows-handling
facilities that GPS does and you rely on them. It might also be used if
you want to have windows on various virtual desktops, when your window
manager has this feature.

   This special mode is activated through a preference (menu
`Edit->Preferences'). This preference is entitled All Floating.


File: gps.info,  Node: Moving Windows,  Prev: Floating Windows,  Up: Multiple Document Interface

Moving Windows
==============

As we have seen, the windows' state can be changed at any time, from
maximized to unmaximized to docked and floating and back, in any order.

   In all cases, the changes are done either through the buttons in the
title bar or through the menu `Window'.

   On some systems, a more intuitive method is also provided, based on
the drag-and-drop paradigm. The idea is simply to select a window,
wherever it is, and then, by clicking on it and moving the mouse while
keeping the left button pressed, drop it anywhere else inside GPS.

   Selecting an item so that it can be dragged is done simply by
clicking with the left mouse button in its title bar, and keep the
button pressed while moving the mouse. Although this is the general
scheme, this would work for unmaximized items, since the title bar is
then used to move them around. In that case, you need to press the
<control> key in addition to the left mouse button.

   A third possibility can be used for maximized or docked windows:
click with the left mouse button in the notebook tab that contains their
name. This third option is not available under Windows systems.

   It is important to note that some visual objects in GPS have their
own drag-and-drop support, and will not react when you drop a window on
them. For instance, editors use drag-and-drop for copy-paste
operations. Therefore, dropping a window on them will result in a
failed operation. In that case, it always works to drop the window in
the title bar of another window to adopt the same state.

   Here are the various places where a window can be dropped:

The central area
     The window you are dropping will get the same state as the other
     windows already in this area (maximized or unmaximized).

Docking areas
     The window will immediately be adopted by this dropping area, and a
     new notebook will be created as needed. Once again, since the
     message window has its own handling of drag-and-drop, you can not
     drop items on it. Instead, drop windows on its title bar.

     In some cases, you might want to create a docking area that is not
     currently visible (for instance, it is often useful to put an
     editor in the right docking area, so that two editors can be seen
     side-by-side, one in this area, and one in the central one).

     To achieve this, drop the window on the small handle that surrounds
     the whole GPS window (a black rectangle will appear on the screen
     when your mouse is over that area). If you then drop the item, a
     new docking area will be created.

System window
     Under systems that support it, if you drop a window outside of GPS
     (for instance, on the background of your screen), the window will
     be floated.

Sides of the GPS window
     On each side of the GPS window, a small zone (a few pixels high or
     wide) is set up as a drop-area. If you drop a window on these zone
     (they are briefly highlighted while the mouse stays on them), then
     the window will be added to the dock on that side. If there is no
     dock area on that side, one will be created.

     This is especially useful if you want to put two editor windows
     side by side. Drag one of them on the drop area on the right side.


File: gps.info,  Node: Editing Files,  Next: Source Navigation,  Prev: Multiple Document Interface,  Up: Top

Editing Files
*************

* Menu:

* General Information::
* Editing Sources::
* The File Selector::
* Menu Items::
* Using an External Editor::
* Using the Clipboard::


File: gps.info,  Node: General Information,  Next: Editing Sources,  Up: Editing Files

General Information
===================

Source editing is one of the central parts of GPS, giving in turn access
to many other functionalities, including extended source navigation and
source analyzing tools.

   The integrated source editor provides all the usual capabilities
found in integrated environments, including:

A title bar
     Showing the full name of the file including path information.

Line number information
     This is the left area of the source editor. Line numbers can be
     disabled from the preferences. *Note The Preferences Dialog::.
     Note that this area can also display additional information, such
     as the current line of execution when debugging, or cvs
     annotations.

A scrollbar
     Located on the right of the editor, it allows you to scroll
     through the source file.

A status bar
     Giving information about the file.  If the file is maintained
     under version control, and version control is supported and
     enabled in GPS, the first box on the left will show VCS
     information on the file: the VCS kind (e.g. CVS), followed by the
     revision number, and if available, the status of the file.

     The second box shows the writable state of the file.  You can
     change this state by clicking on the label directly: this will
     switch between writable and read-only.  Note that this will not
     change the permissions of the file on disk, it will only change
     the writable state of the source editor within GPS.

     When trying to save a file which is read only on the disk, GPS
     will ask for confirmation, and if possible, will force saving of
     the file, keeping its read only state.

     The third box shows whether the file has been modified since the
     last save. The three possible states are:

    Unmodified
          The file has not been modified since the file has been loaded
          or saved.

    Modified
          The file has been modified since last load or save. Note that
          if you undo all the editing operations until the last save
          operation, this label will change to Unmodified.

    Saved
          The file has been saved and not modified since.

     The fourth box displays the position of the cursor in the file by
     a line and a column number.

A contextual menu
     Displayed when you right-click on any area of the source editor.
     See in particular *Note Source Navigation Contextual Menus:: for
     more details.

Syntax highlighting
     Based on the programming language associated with the file,
     reserved words and languages constructs such as comments and
     strings are highlighted in different colors and fonts. See *Note
     The Preferences Dialog:: for a list of settings that can be
     customized.

Automatic indentation
     When enabled, lines are automatically indented each time you press
     the <Enter> key, or by pressing the indentation key.  The
     indentation key is <Ctrl-Tab> by default, and can be changed in the
     preferences dialog, *Note The Preferences Dialog::.

     If a set of lines is selected when you press the indentation key,
     this whole set of lines will be indented.

Tooltips
     When you leave the mouse over a word in the source editor, a small
     window will automatically pop up if there are relevant contextual
     information to display about the word.

     The kind of information displayed depends on the current state of
     GPS.

     In normal mode, the kind of entity and where it is declared is
     displayed when this information is available. That is, when the
     cross reference information about the current file has been
     generated. If there is no relevant information, no tooltip is
     displayed.  See *Note Support for Cross References:: for more
     information.

     In debugging mode, the value of the variable under the mouse is
     displayed in the pop up window if the variable is known to the
     debugger, in the right frame, and if the program being debugged is
     in the right state. If one of these conditions is not met, the
     normal mode information is displayed.

     You can disable the automatic pop up of tool tips in the Editor
     section of the preferences dialog. *Note The Preferences Dialog::.

Word completion
     It is useful when editing a file and using often the same words to
     get automatic word completion. This is possible by typing the
     <Ctrl-/> key combination (customizable through the preferences
     dialog) after a partial word: the next possible completion will be
     inserted in the editor. Typing this key again will cycle through
     the list of possible completions.

     Completions are searched in the edited source file, by first
     looking at the closest words and then looking further in the
     source as needed.

Delimiter highlighting
     When the cursor is moved before an opening delimiter or after a
     closing delimiter, then both delimiters will be highlighted. The
     following characters are considered delimiters: ()[]{}.  You can
     disable highlighting of delimiters in the preferences.

     You can also jump to a corresponding delimiter by using the
     <Ctrl-'> key, that can be configured in the preferences. Typing
     twice on this key will move the cursor back to its original
     position.

Current line highlighting
     You can configure the editor to highlight the current line with a
     certain color. *Note The Preferences Dialog::.

Auto save
     You can configure the editor to periodically save modified files.
     See *Note autosave delay:: for a full description of this
     capability.

   GPS also integrates with existing third party editors such as
`Emacs'. *Note Using an External Editor::.


File: gps.info,  Node: Editing Sources,  Next: The File Selector,  Prev: General Information,  Up: Editing Files

Editing Sources
===============

Key bindings
------------

In addition to the standard keys used to navigate in the editor (up,
down, right, left, page up, page down), the integrated editor provides
a number of key bindings allowing easy navigation in the file.

   The key bindings are listed below in two sections: the common key
bindings, always available; the Emacs key bindings, available as an
option.

   In addition, there are several ways to define new key bindings, see
*Note Defining Text Aliases:: and *Note Defining new key bindings::.

Common key bindings

    <Ctrl-Shift->
          Pressing these two keys allow you to enter characters using
          their hexadecimal value. For example, pressing
          <Ctrl-Shift-2-0> will insert a space character (ASCII 32,
          which is 20 in hexadecimal).

    <Ctrl-x / Shift-delete>
          Cut to clipboard

    <Ctrl-c / Ctrl-insert>
          Copy to clipboard

    <Ctrl-v / Shift-insert>
          Paste from clipboard

    <Ctrl-s>
          Save file to disk

    <Ctrl-z>
          Undo previous insertion/deletion

    <Ctrl-r>
          Redo previous insertion/deletion

    <Insert>
          Toggle overwrite mode

    <Ctrl-a>
          Select the whole file

    <Home / Ctrl-Pgup>
          Go to the beginning of the line

    <End / Ctrl-Pgdown>
          Go to the end of the line

    <Ctrl-Home>
          Go to the beginning of the file

    <Ctrl-End>
          Go to the end of the file

    <Ctrl-up>
          Go to the beginning of the line, or to the previous line if
          already at the beginning of the line.

    <Ctrl-down>
          Go to the end of the line, or to the beginning of the next
          line if already at the end of the line.

    <Ctrl-delete>
          Delete end of the current word.

    <Ctrl-backspace>
          Delete beginning of the current word.

Emacs key bindings
     The following key bindings are activated if you select the Emacs
     key theme in the preferences dialog (*Note The Preferences
     Dialog::.), and may override common keys (e.g. <Ctrl-a>).

    <Ctrl-b>
          Move the cursor one character on the left

    <Shift-Alt-b>
          Select the previous word (backward).

    <Shift-Alt-f>
          Select the next word (forward).

    <Ctrl-a>
          Go to the beginning of the line

    <Ctrl-e>
          Go to the end of the line

    <Ctrl-d>
          Delete the next character

    <Ctrl-k>
          Delete the end of the line. If the cursor is already at the
          end of the line, remove the line separator.

    <Alt-\>
          Delete all space characters around the cursor.

    <Alt-space>
          Replace all space characters around the cursor by a single
          space.

    <Alt-<>
          Go to the beginning of the file

    <Alt->>
          Go to the end of the file

    <Shift-Ctrl-p>
          Select from cursor to one line up.

    <Shift-Ctrl-n>
          Select from cursor to one line down.

    <Ctrl-j>
          Join the current and the next lines and leave a single space
          between the two. This is similar to the <J> key in the vi
          editor.  This is a useful extension compared to the default
          Emacs key bindings.


File: gps.info,  Node: The File Selector,  Next: Menu Items,  Prev: Editing Sources,  Up: Editing Files

The File Selector
=================

The file selector is a dialog used to select a file. Under Windows, the
default is to use the standard file selection widget. Under other
platforms, the file selector is a built-in dialog:

This dialog provides the following areas and capabilities:

   * A tool bar on the top composed of five buttons giving access to
     common navigation features:

    left arrow
          go back in the list of directories visited

    right arrow
          go forward

    up arrow
          go to parent directory

    refresh
          refresh the contents of the directory

    home
          go to home directory (value of the HOME environment variable,
          or `/' if   not defined)

   * A list with the current directory and the last directories
     explored.  You can modify the current directory by modifying the
     text entry and hitting <Enter>, or by clicking on the right arrow
     and choose a previous directory in the pop down list displayed.

   * A directory tree. You can open or close directories by clicking on
     the `+' and `-' icons on the left of the directories, or navigate
     using the keyboard keys: <up> and <down> to select the previous or
     the next directory, <+> and <-> to expand and collapse the current
     directory, and <backspace> to select the parent directory.

   * A file list. This area lists the files contained in the selected
     directory. If a filter is selected in the filter area, only the
     relevant files for the given filter are displayed. Depending on
     the context, the list of files may include additional information
     about the files, e.g. the kind of a file, its size, etc...

   * A filter area. Depending on the context, one or several filters are
     available to select only a subset of files to display. The filter
     All files which is always available will display all files in the
     directory selected.

   * A file name area. This area will display the name of the current
     file selected, if any.  You can also type a file or directory name
     directly, and complete the name automatically by using the <Tab>
     key.

   * A button bar with the `OK' and `Cancel' buttons.  When you have
     selected the right file, clock on `OK' to confirm, or click on
     `Cancel' at any time to cancel and close the file selection.



File: gps.info,  Node: Menu Items,  Next: Using an External Editor,  Prev: The File Selector,  Up: Editing Files

Menu Items
==========

The main menus that give access to extended functionalities related to
source editing are described in this section.

The File Menu
-------------

New
     Open a new untitled source editor.  No syntax highlighting is
     performed until the file is saved, since GPS needs to know the
     file name in order to choose the programming language associated
     with a file.

     When you save a new file for the first time, GPS will ask you to
     enter the name of the file. In case you have started typing Ada
     code, GPS will try to guess based on the first main entity in the
     editor and on the current naming scheme, what should be the
     default name of this new file.

New View
     Create a new view of the current editor. The new view shares the
     same contents: if you modify one of the source views, the other
     view is updated at the same time. This is particularly useful when
     you want to display two separate parts of the same file, for
     example a function spec and its body.

Open...
     Open a file selection dialog where you can select a file to edit.
     Under Windows, this is the standard file selector. Under other
     platforms, this is a built-in file selector described in *Note The
     File Selector::.

Open From Project...
     Open a dialog where you can easily and rapidly select a source
     file from your project.

     The first text area allows you to type a file name. You can start
     the beginning of a file name, and use the <Tab> key to complete
     the file name. If there are several possible completions, the
     common prefix will be displayed, and a list of all possible
     completions will be displayed in the second text area.

     You can then either complete the name by typing it, or continue
     hitting the <Tab> key to cycle through the possible completions,
     or click on one of the completions in the list displayed.

     You can also directly access the previous file names typed in this
     dialog by clicking on the down arrow on the right of the first
     text area.

     Once you have made your choice, click on the `OK' button to
     validate.  Clicking on `Cancel' or hitting the <Esc> key will
     cancel the operation and close the dialog.

Recent
     Open a sub menu containing a list of the ten most recent files
     opened in GPS, so that you can reopen them easily.

Save
     Save the current source editor if needed.

Save As...
     Same current file under a different name, using the file selector
     dialog.  *Note The File Selector::.

Save...
     Give access to extra save capabilities.

    All
          Save all items, including projects, etc...

    Desktop
          Save the desktop to a file. The desktop includes information
          about files, graphs, ... and their window size and position
          in GPS. The desktop is saved per top level project.

    Default Desktop
          Save the current desktop as the default desktop. The next
          time you start GPS, if there is no saved desktop associated
          with the chosen project, then this desktop will be used.

Change Directory...
     Open a directory selection dialog that lets you change the current
     working directory.

Messages
     This sub menu gives access to functionalities related to the
     Messages window.  *Note The Messages Window::.

    Clear
          Clear the contents of the Messages window.

    Save As...
          Save the contents of the Messages window to a file. A file
          selector is displayed to choose the name and location of the
          file.

    Load Contents...
          Open a file selector to load the contents of a file in the
          Messages window. Source locations are identified and loaded
          in the Locations Tree.  *Note The Locations Tree::.

Close
     Close the current window. This applies to all GPS windows, not
     only source editors.

Print
     Print the current file by first saving it interactively if needed
     (if it has been modified), and then by launching the command
     defined in the preferences.  *Note Print Command::.

Exit
     Exit GPS after confirmation and if needed, confirmation about
     saving modified windows and editors.

The Edit Menu
-------------

Undo
     Undo previous insertion/deletion in the current editor.

Redo
     Redo previous insertion/deletion in the current editor.

Cut
     Cut the current selection and store it in the clipboard.

Copy
     Copy the current selection to the clipboard.

Paste
     Paste the contents of the clipboard to the current cursor position.

Select All
     Select the whole contents of the current source editor.

Comment Lines
     Comment the current selection or line based on the current
     programming language syntax.

Uncomment Lines
     Remove the comment delimiters from the current selection or line.

Generate Body
     Generate Ada body stub for the current source editor by calling the
     external tool `gnatstub'.

Pretty Print
     Pretty print the current source editor by calling the external tool
     `gnatpp'. It is possible to specify `gnatpp' switches in the
     switch editor. *Note The Switches Editor::.

Unit Testing
     This sub menu gives access to dialogs that make it easy to generate
     AUnit stubs. AUnit is an Ada unit testing frame work.

    New Test Case...
          Create a new test case. See AUnit documentation for more
          details.

    New Test Suite...
          Create a new test suite. See AUnit documentation for more
          details.

    New Test Harness...
          Create a new harness. See AUnit documentation for more
          details.

Preferences
     Give access to the preferences dialog. *Note The Preferences
     Dialog::.

