2. Description of the Main Window — GPS 6.0.1 documentation

### Navigation

- index
- modules |
- next |
- previous |
- GPS 6.0.1 documentation »

# 2. Description of the Main Window

The GNAT Programming Studio has one main window, where most of your work will be performed. However, it is also very flexible in how it lets you organize your desktop, which will be discussed in a later section (Multiple Document Interface).

But there are also various other windows that might pop up at various times, and this section documents them.

## 2.1. The Workspace

The whole work space is based on a multiple document interface, Multiple Document Interface. It can contain any number of windows, the most important of which are probably the editors. However, GPS also provides a large number of views that can be added to the workspace. The following sections will list them all.

### 2.1.1. Common features of the views

Some views are part of the default desktop, and thus are visible by default. The other views can always be opened through one of the submenus of the Tools menu, most often Tools ‣ Views.

Some of the view have their own local toolbar that contains shortcuts to the most often used features of the view.

To the right of these local toolbars, there is often a button to open a local settings menu. This menu can contain more actions that can be performed in this view, or various configuration settings that affect the behavior or the display of the view.

Some of the views also have a filter in their local toolbar. These filters can be used to reduce the amount of information that is displayed on the screen, by only leaving those lines that match the filter.

If you click on the left icon of the filter, this will bring up a popup menu to configure the filter:

- The first three entries are used to chose the search algorith (from full text match, to regular expression, to fuzzy matching). These modes are similar to the ones used in the omni-search (The omni-search).
- The next entry is Revert filter. When this is selected, the lines that do not match the filter are displayed, as opposed to the ones that match the filter otherwise. This mode can also be enabled temporarily if you start the filter with the string not:. For instance, a filter in the Locations view that says not:warning will hide all warning messages.
- The last entry Whole word should be used when you only want to match on full words, not on substrings.

### 2.1.2. Common features of the browsers

A number of the views described below are interactive displays called browsers. They represent their information as boxes that can be manipulated with the mouse, and provide the following additional capabilities:

- Scrolling

  When a lot of items are displayed in the canvas, the currently visible area might be too small to display all of them. In this case, scrollbars will be added on the sides, so that you can make other items visible. Scrolling can also be done with the arrow keys.

- Layout

  A basic layout algorithm is used to organize the items. This algorithm is layer oriented: items with no parents are put in the first layer, then their direct children are put in the second layer, and so on. Depending on the type of browser, these layers are organized either vertically or horizontally. This algorithm tries to preserve as much as possible the positions of the items that were moved interactively.

  The Refresh layout button in the local toolbar can be used to recompute the layout of items at any time, even for items that were previously moved interactively.

- Interactive moving of items

  Items can be moved interactively with the mouse. Click and drag the item by clicking on its title bar. The links will still be displayed during the move, so that you can check whether it overlaps any other item. If you are trying to move the item outside of the visible part of the browser, the latter will be scrolled.

- Selecting items

  Items can be selected by clicking on them. Multiple items can be selected by holding the `control` key while clicking in the item. Alternatively, you can click and drag the mouse inside the background of the browser. All the items found in the selection rectangle when the mouse is released will be selected.

  Selected items are drawn with a different title bar color. All items linked to them also use a different title bar color, as well as the links. This is the most convenient way to understand the relationships between items when lots of them are present in the browser.

  Buttons in the local toolbar are provided to remove either the selected items, or on the contrary the ones that are not selected.

- Links

  Items can be linked together, and will remain connected when items are moved. Different types of links exist, see the description of the various browsers.

  The local toolbar provides a button to hide the display of the links. This will keep the canvas more readable, at the cost of losing some information. You can also hide only a subset of the links. Even when the links are hidden, if you select an item then the items linked to it will still be highlighted.

  The local settings menu in browsers has an option straight links which can be toggled if you prefer to have orthogonal links.

- export

  The entire contents of a browser can be exported as a PNG or SVG images using the entry Export to... in the local toolbar.

- Zooming

  Several different zoom levels are available. The local toolbar provides multiple buttons to change the zoom level: zoom in, zoom out and zoom. The latter is used to select directly the zoom level you want.

  This zooming capability is generally useful when lots of items are displayed in the browser, to get a more general view of the layout and the relationships between the items.

- Hyper-links

  Some of the items will contain hyper links, displayed in blue by default, and underlined. Clicking on these will generally display new items.

- contextual menus

  Right-clicking on items will bring a contextual menu with actions that can be performed on that item. These actions are specific to the kind of item you clicked on.

- Grid

  By default, a grid (small dots) is displayed in the background of the browsers. Using the local settings menu, it is possible to hide the grid (Draw grid) and to force items to align on the grid (Align on grid).

#### 2.1.2.1. Icons for source language entities

Entities in the source code are presented with representative icons within the various GPS views (the Outline and Project views, for example). These icons indicate both the language categories of the entities, such as packages and methods, as well as compile-time visibility. In addition, the icons distinguish entity declarations from other entities. The same icons are used for all programming languages supported by the viewers, with language-specific interpretations for both compile-time visibility and recognizing declarations.

There are five language categories used for all supported languages:

- The package category’s icon is a square.

- The subprogram category’s icon is a circle.

- The type category’s icon is a triangle.

- The variable category’s icon is a dot.

- The generic category’s icon is a diamond.

These basic icons are enhanced with decorators, when appropriate, to indicate compile-time visibility constraints and to distinguish declarations from completions. For example, the icons for entity declarations have a small ‘S’ decorator added, denoting a ‘spec’.

With respect to compile-time visibility, icons for ‘protected’ and ‘private’ entities appear within an enclosing box indicating a visibility constraint. For entities with ‘protected’ visibility, this enclosing box is colored in gray. ‘Private’ entities are enclosed within a red box. The icons for ‘public’ entities have no such enclosing box. For example, a variable with ‘private’ visibility would be represented by an icon consisting of a dot enclosed within a red box.

These additional decorators are combined when appropriate. For example, the icon corresponding to the ‘private’ declaration of a ‘package’ entity would be a square, as for any package entity, with a small ‘S’ added, all enclosed within a red box.

Language constructs are mapped to the categories in a language-specific manner. For example, C++ namespaces and Ada packages correspond to the package category. C functions and Ada subprograms correspond to the method category, and so on. The generic category is a general category representing other language entities, but note that not all possible language constructs are mapped to categories and icons. (Note also that the generic category does not correspond to Ada generic units or C++ templates.)

The names of the categories should not be interpreted literally in terms of language constructs because the categories are rather general, in order to limit the number used. The variable category includes both constants and variables in Ada, for example. Limiting the number of categories maintains a balance between presentation complexity and the need to support distinct programming languages.

Icons for a given entity may appear more than once within a view. For example, an Ada private type will have both a partial view in the visible part of the enclosing package as well as a full view in the private part of the package. Two triangle icons will therefore appear for the two occurrences of the type name, one with the additional decorator indicating the ‘private’ compile-time visibility.

## 2.2. The Welcome Dialog

When it starts, GPS is looking for a project file to load, so that it knows where to find the sources of your project. This project is in general specified on the command line (via a -P switch). Alternatively, if the current directory only contains one project file, GPS will select it automatically. Finally, if you specify the name of a source file to edit, GPS will load a default project and start the editing immediately. if no project file can be found, GPS displays a welcome dialog, which gives you the following choices:

Create new project from template
  If you select this option and then click the OK button, GPS will launch an assistant to create a project using one of the predefined project templates. This makes it easy to create GtkAda-based applications, or applications using the Ada Web Server, for instance.

Start with default project in directory

> If you select this option and click on the OK button, GPS will first look for a project called `default.gpr` in the current directory and load it if found. Otherwise, it will copy in the current directory the default project found under `<prefix>/share/gps/default.gpr` and load it. GPS will remove this temporary copy when exiting or loading another project, if the copy has not been modified during the session.

> The default project will contain all the Ada source files from the given directory (assuming they use the default GNAT naming scheme `.ads` and `.adb`).

> If the current directory is not writable, GPS will instead load directly `<prefix>/share/gps/readonly.gpr`. In this case, GPS will work in a degraded mode, where some capabilities will not work (such as building and source navigation). This project does not contain any sources.

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 The Project Wizard for more details.

> There are several kinds of wizards, ranging from creating a single project, to creating a set of project that attempt to adapt to an existing directory layout. The list of pages in the wizard will depend on the kind of project you want to create.

> One of the wizard, Project Tree, will try and import a set of sources and object files, and attempt to create one or more project files so that building your application through these project files will put the objects in the same directory they are currently in. If you have not compiled your application when launching this wizard, GPS will create a single project file and all object files will be put in the same object directory. This is the prefered method when importing sources with duplicate file names, since the latter is only authorized in a single project file, not across various project files.

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, click on the OK button to 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; otherwise, it will look for a project file in the current directory and will load it if there is only of them; if no project file was loaded, GPS will start with the default project, as if you had selected Start with default project in directory in the welcome dialog.

> To reset this property, go to the menu Edit ‣ Preferences.

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

## 2.3. The Tip of the Day

This dialog displays short tips on how to make the most efficient use of the GNAT Programming Studio. You can click on the Previous and Next buttons to access all tips, and close the dialog by either clicking on the Close button or pressing the `ESC` key.

You can also disable this dialog by unchecking the Display Tip of the Day on startup check box. If you would like to reenable this dialog, you can go to the Edit ‣ Preferences dialog.

## 2.4. 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 or when using the special `open contextual menu` key on most PC keyboards.

The menu bar gives access to the following items:

- File (The File Menu)

- Edit (The Edit Menu)

- Navigate (The Navigate Menu)

- VCS (The VCS Menu)

- Project (The Project Menu)

- Build (The Build Menu)

- Debug (The Debug Menu)

- Tools (The Tools Menu)

- SPARK

  If the SPARK toolset is installed on your system and available on your PATH, then this menu is available. See Help ‣ SPARK ‣ Reference ‣ Using SPARK with GPS for more details.

- CodePeer

  If the CodePeer toolset is installed on your system and available on your PATH, then this menu is available. See your CodePeer documentation for more details.

- Window (Multiple Document Interface)

- Help

## 2.5. The Tool Bar

The tool bar provides shortcuts via buttons to some typical actions:

- creating a new file
- opening an existing file (see laso the omni-search on the right of the bar)
- saving the current file
- undo / redo last editing
- go to previous or next saved location
- multiple customizable buttons to build, clean or run your project
- when a debugger is started, multiple buttons to stop and continue the debugger, step to the next instruction,...

When GPS is performing background actions, like loading the cross-reference information, compiling or indeed all actions involving external processes, a progress bar is displayed in the toolbar. This shows when the current task(s) will be completed. A small interrupt button can be clicked on to interrupt all background tasks. Clicking on the progress bar will open the Tasks view (The Task Manager).

## 2.6. The omni-search

The final item in the toolbar is the omni-search. This is a search field that will search the text you type in various contexts in GPS, like filenames (for convenient access to the source files), the entities referenced in your application, your code,...

There are various ways to use the omni-search:

- The simplest is of course to click in it, and type the pattern you are interested in. GPS will immediately start searching in the background for possible matching open windows, file names, entities, GPS actions, bookmarks, and source files. For each context, GPS only displays the five matches with the highest score.

  For each context, GPS tells you how many matches there. You can click on the name of the context to only search in that context. So for instance, if GPS tells you there are 20 file names matching your search (but only displaying the five first ones), you can click on file names to view all 20 names, and exclude the results from all the other contexts.

  If you click again on the context, GPS is back to displaying the results in all contexts.

- If you are searching in a specific context, the above requires too many clicks. GPS defines a number of actions to which you can bind key shortcuts via the Edit ‣ Key Shortcuts dialog. These actions are found in Search category, and are called Global Search in context:. GPS includes a menu for two of them by default: File ‣ Open From Project... will search amongst filenames, wheras Navigate ‣ Goto Entity... will search amonst all entities defined in your project.

Each context displays its results sligthly differently, and clicking on a result will have different effects depending on a context. For instance, clicking on a file name will open the corresponding file, whereas clicking on an entity will jump to its declaration, and clicking on a bookmark while show the source file it is in.

Pressing `enter` at any point will select the top item in the list of search results, which is in general faster than clicking on it.

It is possible that you have no interest in some of the search contexts. You can chose to disable some of them by clicking on the Settings icon at the bottom-right corner of the completion popup. The resulting dialog shows you the list of all contexts that are searched, and clicking on any of the checkboxes next to the names will enable to disable the context. Note that this list is only displayed when you have accessed the omni-search by clicking directly into it. If you accessed it via `shift-F3` or the equivalent menu File ‣ Open From Project..., then only a subset of the settings will be displayed.

Still in this settings dialog, you can also reorder the context. This influences both the order in which they are searched and the order in which they are displayed. We recommend keeping the Sources context last, because it is the slowest, and while GPS is searching it, it would not be able to search the other faster contexts.

In the settings dialog, you can chose whether to display a Preview for the matches. This preview is displayed when you use the `down arrow` key to select some of the search results. In general, it will display the corresponding source file, or the details for the matching GPS action or bookmark.

The settings dialog also allows you to select the number of results that should be displayed for each context when multiple contexts are displayed, or the size of the search field (which depends on how big your screen and the GPS window are).

One of the search context looks at file names, and is convenient for quickly opening files. By default, it will look at all files found in any of the source directories of your project, even if those files are not explicit sources of the project (for instance because they do not match the naming scheme for any of the languages used by the project). This is often convenient because you can easily open support files like Makefiles or documentation, but it can also sometimes get in the way if the source directories include too many irrelevant files. The Include all files from source dirs setting can be used to control this behavior.

GPS proposes various algorithms to do the search:

- Full Text simply checks whether the text you typed appears exactly as is in the context (be it a file name, the contents of a file, the name of an entity,...)

- Regular Expression assumes the text you typed is a valid regular expression, and searches for it. If this isn’t a valid regexp, it tries to search for the exact text.

- Fuzzy Match will try to find each of the characters you typed, in that order, but possibly with extra characters in between. This is likely to be the fastest way to search, but it might requires a bit of getting used to. For instance, the text ‘mypks’ will match the file name ‘MY_PacKage.adS’ because the letters shown in upper cases match the text.

  When searching in the source files, the algorithm is changed slightly, since otherwise there would obviously be too many matches. In that context, GPS only allows a few approximations between the text you typed and the text it tries to match (one or two extra characters or missing characters, for instance).

You can select the algorithm you wish to use by changing it at the bottom of the popup window that contains the search results.

Once it has found a match, GPS assigns it a score, so that it can order the results in the most meaningful way for you. Scoring is based on a number of criteria:

- length of the match

  For instance, when searching file names, it is more likely that by typing ‘foo’ you intended to match ‘foo.ads’ rather than ‘the_long_foo.ads’.

- the grouping of characters in match

  As we have seen, when doing a fuzzy match, GPS allows extra characters in between the ones you typed. But the closer the ones you typed are in the match result, the more likely it is this is what you were looking for.

- when was the item last selected

  If you recently selected an item (like a file name), GPS assumes you are more likely to want it again, and will raise its score appropriately.

## 2.7. 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.

Its local toolbar contains buttons to Clear the contents of the window, as well as to Save and Load from files.

In general the output of the compilation is displayed in the Messages window, but will also be parsed and displayed more conveniently in the Locations window (The Locations view).

When a compilation finishes, GPS also displays the total elapsed time. If the process ended with errors, GPS will display the total progress (as is also displayed in the progress bar in the GPS toolbar), which is convenient to see how many files were compiled successfully.

The Messages window can not be closed, because it might contain important messages at any time. However, it might happen that it has been closed anyway, and in this case it can be reopened with the Tools ‣ Views ‣ Messages menu.

## 2.8. The Locations view

The Location window is used whenever GPS needs to display a list of locations in the source files (typically, when performing a global search, or displaying compilation results).

The Locations shows a hierarchy of categories, which contain files, which contain messages at specific locations. The category describes the type of messages (search results, build results,...). Clicking on a location item will bring up a file editor at the requested place.

Placing the mouse over an item automatically pop up a tooltip window with full text of the message if this text can’t be completely shown in the window.

In general, each message in this window is associated with a special full line highlighting in the corresponding source editor, as well as a mark on the left side of editors to visually navigate between these locations.

The Locations view provides a local toolbar with the following buttons:

- Clear will remove all entries from the window. Depending on your settings, this might also close the window.
- Remove will remove the currently selected category, file or message. This of course removes the corresponding highlighting in the source editor.
- Save can be used to save the contents of the window to a text file, for later reference. This text file can not be imported by GPS into the locations view later. If you want to reload the contents of the locations (in the case of build errors, for instance), it is better to save and load the contents of the Messages window.
- Expand All and Collapse All can be used to quickly show or hide all messages in this window.
- a filter that can be used to show or hide some of the messages. Filtering is done on the text of the message itself (either as a text or as a regular expression). It can also be reversed, so that for instance typing warning in the filter field and reversing the filter will hide warning messages

The local settings menu contains the following entries:

- Sort by subcategory Toggle the sorting of the entries by sub-categories. This is useful, for example, for separating the warnings from the errors in the build results. The error messages will appear first. The default is to sort the message by their location.
- Sort files alphabetically Force files to be sorted alphabetically. The default is that files are not sorted, which makes manipulation of the Locations window easier before all messages are added to it (otherwise the nodes might be switched while you are trying to click on them).
- Jump to first location: Every time a new category is created, as a result of a compilation or a search operation for example, the first entry of that category is automatically selected, and the corresponding editor opened.
- Warp around on next/previous controls the behavior of the guilabel:Previous tag and Next tag menus (see below).
- Auto close locations will automatically close this window when it becomes empty.
- Save locations on exit controls whether GPS should save and restore the contents of this window between sessions. The loaded contents might not apply the next time, because for instance the source files have changed, or build errors have been fixed, so it might be an inconvenience to automatically reload the messages.

To navigate through the locations with the keyboard, GPS provides two menus: Navigate ‣ Previous Tag and Navigate ‣ Next Tag. Depending on your settings, they might wrap around after reaching the first or last message.

It is also possible to bind key shortcuts to these menus via the Edit ‣ Key Shortcuts menu.

In some cases, a wrench icon will be visible on the left of a compilation message. See Code Fixing for more information on how to take advantage of this icon.

## 2.9. The Project view

The project view provides a representation of the various components of your project, as listed below. It is displayed by default on the left side of the workspace, and can be selected by using the Project ‣ Project View or Tools ‣ Views ‣ Project menu items.

On Windows, it is possible to drop files (coming for instance from the Windows Explorer) directly in the project view. If you drop a project file, it will be loaded by GPS and replace the current project; if you drop a source file, it is opened in a new editor.

The project view, as well as the file and outline view provide an interactive search capability allowing you to quickly search in the information currently displayed. Just start typing the text to search when the view has the focus. Note however, that the contents of the Project view is computed lazily, so not all files are known to this search capability.

This will open a small window at the bottom of the view where you can interactively type names. The first matching name in the tree will be selected while you type it. You can then also use the `up` and `down` keys to navigate through all the items matching the current text.

The various components that are displayed are:

projects

> 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 like the naming schemes for the sources. They can be organized into a project hierarchy, where a root project can import other projects, each with their own set of sources (see The Welcome Dialog on how projects are loaded in GPS).

> The Project view displays this project hierarchy: the top node 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 view, if it is imported by several other projects.

> Likewise, if you have edited the project manually and have used the `limited with` construct to have cycles in the project dependencies, the cycle will expand infinitely. For instance, if project `a` imports project `b`, which in turns imports project `a` through a `limited with` clause, then expanding the node for `a` will show `b`. In turn, expanding the node for `b` will show a node for `a`, and so on.

> A special icon with a pen 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, or save it automatically, if the corresponding preference is saved.

> There exists a second display for this project view, which lists all projects with no hierarchy: all projects appear only once in the view, at the top level. This display might be useful for deep project hierarchies, to make it easier to find projects in the project view. This display is activated through the local settings menu to the right of the Project view toolbar.

directories

> The files in a project are organized into several physical directories on the disk. These directories are displayed under each project node 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 using the local settings menu Show absolute paths of the Project view. In all cases, the tooltip that is displayed when the mouse hovers a file or directory will show the full path.

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

> The local setting Show hidden directories can be used to filter the directories considered as hidden. This can be used to hide the version control directories like `CVS` or `.svn` for example.

files

> The source files themselves are contained in the directories, and displayed under the corresponding nodes. Note that only the source files that actually belong to the project (i.e. are written in a language supported by that project and that follow its naming scheme) are actually visible. For more information on supported languages, see Supported Languages.

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

> You can also drag a file anywhere into GPS. This will open a new editor if the file is not already edited, or move the existing editor otherwise. If you press `shift` at the same time, and the file is already edited, a new view of the existing editor is created instead.

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 file 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 a 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 or Replace... menu, you have the possibility to search for anything in the Project view, either a file or an entity. Note that searching for an entity can be slow if you have lots of files, and/or big files.

A contextual menu, named Locate in Project View, is also provided in source editors. This will automatically search for the first entry for this file in the Project view. This contextual menu is also available in other modules, e.g. when selecting a file in the Dependency Browser.

The local toolbar of the Project view contains a convenient button to reload the project. This is useful when you have created or removed source files from other applications, and want to let GPS know that there might have been changed on the file system that impact the contents of the current project.

It also includes a button to graphically edit the attributes of the selected project, like the tool switches, the naming schemes,... It behaves similarly to the Project ‣ Edit Project Properties menu. See The Project Properties Editor for more information.

If you right click on a project node, a contextual menu appears which contains, among others, the following entries that are useful to understand or modify your project:

- Show projects imported by...

- Show projects depending on... These two menus will open a new window, the Project browser, which displays graphically the relationships between each project in the hierarchy (see The Project Browser).

- Project ‣ Properties This menu opens a new dialog to interactively edit the attributes of the project (tool switches, naming schemes,...) and is similar to the local toolbar button.

- Project ‣ Save project... This item can be selected to save a single project in the hierarchy after it was modified. Modified but unsaved projects in the hierarchy have a special icon (a pen mark is drawn on top of the standard icon). If you would rather save all the modified projects in a single step, use the menu bar item Project ‣ Save All.

  Any time one or several projects are modified, the contents of the project view is automatically refreshed. No project is automatically saved. This provides a simple way to temporarily test new values for the project attributes. Unsaved modified projects are shown with a special icon in the project view, displaying a pen mark on top of the standard icon:

- Project ‣ Edit source file This menu will load the project file into an editor, so that you can manually edit it. This should be used if you need to access some features of the project files that are not accessible graphically (renames statements, variables, ...).

- Project ‣ Dependencies This menu opens the dependencies editor for the selected project (The Project Dependencies Editor).

- Project ‣ Add scenario variable This menu item should be used to add new scenario variables to the project (see Scenarios and Configuration Variables). It mighe be more convenient in general to use the Scenario view for that purpose.

## 2.10. The Scenario view

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 used 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 window called the Scenario View. These variables are called Scenario Variables, since they provide various scenarios for the same set of project files.

Each such variable is listed on its own line, along with its current value. You can change the current value by clicking on it, and then selecting the new value among the valid ones that pop up. GPS does not remember the current value from one session to the next. Instead, the variables’ initial values come from the project files themselves (where a default value can be specified) or from the environment in which GPS is started, just as is the case when spawning command line tools like gprbuild.

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.

New scenario variables can be created by selecting the + icon in the local toolbar of the Scenario view. You can also edit the list of possible values for a variable by clicking on the edit button in that toolbar, and of course delete an existing variable by clicking on the - button.

Note that any of these changes impacts the actual project file (`.gpr`), so you might not want to do that if the project file was written manually (the impacts can be significant).

The first line in the Scenario view is the current mode. This impacts various aspects of the build, including compiler switches and object directories (see The Build Mode). As for scenario variables, the mode can be changed by clicking on the value and selecting a new value in the popup window.

If you are not using build modes and want to save some space on the screen, you can use the local settings menu Show build modes to disable the display.

## 2.11. The Files View

In addition to the Project view, GPS also provides a Files view through the Tools ‣ Views ‣ Files menu.

In this view, directories are displayed exactly as they are organized physically on the disk (including Windows drives). Each source file can also be explored as described in The Project view. Drag and drop of files is also possible from the files view, to conveniently open a file.

By default, the Files view will display all the files that exist on the disk. Filters can be set through the local settings menu to restrict the display to the files and directories that belong to the project (use the Show files from project only menu).

## 2.12. The Windows view

The Windows view displays the currently opened windows. It is opened through the Tools ‣ Views ‣ Windows menu.

In the contextual menu, you can configure the display in one of two ways:

- Sorted alphabetically
- Organized by notebooks, as in the GPS window itself. This view is mostly useful if you have lots of opened windows.

You can also choose, through the contextual menu, whether only the source editors should be visible, or whether all windows should be displayed.

This view allows you to quickly select and focus on a particular window, by clicking on the corresponding line with the left mouse button. If you click and leave the mouse button pressed, this starts a drag and drop operation so that you can also move the window to some other place in the desktop (see the description of the Multiple Document Interface)

Multiple windows can be selected by clicking with the mouse while pressing the control or shift keys. The Window view provides a contextual menu to easily close all selected windows at once, which is a very fast way to cleanup your desktop after you have finished working on a task.

## 2.13. The Outline view

The Outline view, which you can choose to activate through the Tools ‣ Views ‣ Outline menu, shows the contents of the current file.

The exact semantics depends on the language you are seeing. For Ada, C and C++ files, this is the list of entities that are declared at the global level in your current file (Ada packages, C++ classes, subprograms, Ada types, ...).

The contents of this view is refreshed every time the current editor is modified.

Clicking on any entity in this view will automatically jump to the right line in the file (either to the spec or the body).

The local settings menu contains multiple check boxes that alter the display of the outline view:

- Show profiles indicates whether the list of parameters of the subprograms should be displayed. This is in particular useful for languages that allow overriding of entities.
- Show types, Show objects, Show tasks, entries and protected types controls the display of specific categories of entities.
- Show specifications indicates whether GPS should display a line for the specification (declaration) of entities, in addition to the location of their bodies.
- Sort alphabetically controls the order in which the entities are displayed (either alphabetically or in the same order as in the source file)
- Flat View controls whether the entities are always displayed at the top level of the outline view. When this is disabled, nested subprograms are displayed below the subprogram in the scope of which they are declared.
- Group spec and body can be enabled to display up to two icons on each line (one for the spec, one for the body in case both occur in the file). You can then click directly on one or the other icon to go directly to that location. If you click on the name of the entity you are first taken to its declaration, unless this is already the current location in the editor in which case you are moved to the body.
- Dynamic link with editor: If this option is set, the current subprogram will be selected in the outline view every time the cursor position changes in the current editor. This option requires some computation for GPS, and you might want to avoid the slow down by disabling it.

## 2.14. The Clipboard view

GPS has an advanced mechanism for handling copy/paste operations.

When you select the menus Edit ‣ Copy or Edit ‣ Cut, GPS adds the current selection to the clipboard. As opposed to what lots of applications do, it doesn’t discard the previous contents of the clipboard, but save it for future usage. It saves a number of entries this way, up to 10 by default. This value is configurable through the Clipboard Size preference.

When you select the menu Edit ‣ Paste, GPS will paste the last entry made in the clipboard at the current location in the editor. If you immediately select Edit ‣ Paste Previous, this newly inserted text will be removed, and GPS will instead insert the second to last entry added to the clipboard. You can keep selecting the same menu to get access to older entries.

This is a very powerful mechanism, since it means you can copy several distinct lines from a place in an editor, move to an other editor and paste all these separate lines, without having to go back and forth between the two editors.

The Clipboard view provides a graphical mean of seeing what is currently stored in the clipboard. It can be opened via Tools ‣ Views ‣ Clipboard.

It appears as a list of lines, each of which is associated with one level of the clipboard. The text that shows in these lines is the first line of the selection at that level that contains non blank characters. Leading characters are discarded. [...] is prepended or appended in case the selection has been truncated.

If you bring the mouse over a line in the Clipboard view, a tooltip will pop up showing the entire selection corresponding to the line by opposition to the possibly truncated one.

In addition, one of the lines has an arrow on its left. This indicates the line that will be pasted when you select the menu Edit ‣ Paste. If you select instead the menu Edit ‣ Paste Previous, then the line below that one will be inserted instead.

If you double-click on any of these lines, GPS will insert the corresponding text in the current editor, and make the line you clicked on the current line, so that selecting Edit ‣ Paste or the equivalent shortcut will now insert that line.

The local toolbar in the clipboard view provides two buttons:

- Append To Previous. If you select this button, the select line will

    be append to the one below, and removed from the clipboard. This means that selection Edit ‣ Paste will in fact paste the two entries at the same time. This is in particular useful when you want to copy lines from separate places in the initial file, merge them, and then paste them together one or more times later on, through a single operation.

- Remove. If you select this button, the selected line is removed from the clipboard.

The Clipboard View content is preserved between GPS sessions. As an exception, huge entries are removed and replaced with an entry saying “[Big entry has been removed]”.

## 2.15. The Call trees view and Callgraph browser

These two views play a similar role. They display the same information about entities, but in two different ways: the callgraph view displays the information in a tree, easily navigable and perhaps easier to manipulate when lots of entities are involved; the callgraph browser displays the information as graphical boxes that can be manipulated on the screen, and is best suited to generate a diagram that can be later exported to your own documents.

These views are used to display the information about what subprograms are called by a given entity, and, opposite, what entities are calling a given entity.

Some references might be reported with an additional ” (dispatching)” text. In such a case, this indicates that the call to the entity is not explicit in the sources, but could occur through dynamic dispatching. This of course depends on what arguments are passed to the caller at run time, and it is possible that the subprogram is in fact never dispatched to.

### 2.15.1. Call Trees

The Call trees are displayed when you select one of the contextual menus <entity> calls and <entity> is called by. Every time you select one of these menus, a new view is opened to display that entity.

Whenever you expand a node from the tree by clicking on the small expander arrow on the left of the line, further callgraph information is computed for the selected entity, which makes it very easy to get information for a full callgraph tree.

Closing and expanding a node again will recompute the callgraph for the entity.

On the right side of the main tree, a list displays the locations of calls for the selected entity. Clicking on entries in this list opens editors showing the corresponding location.

The Calltree supports keyboard navigation: `Up` and `Down` keys navigate between listed locations, `Left` collapses the current level, `Right` expands the current level, and `Return` jumps to the currently selected location.

The contents of the calltree is not restored the next time GPS is restarted, because its contents might be misleading if the sources have changed in-between, and GPS would be wasting time loading the information again.

The local toolbar provides the following buttons:

- Clear Remove all entries from the Callgraph View.
- Remove entity Remove the selected entity from the Callgraph View.
- Collapse all Collapse all the entities in the Callgraph View.

### 2.15.2. Callgraph browser

The callgraph shows graphically the relationship between subprogram callers and callees. A link between two items indicate that one of them is calling the other.

A special handling is provided for renaming entities (in Ada): if a subprogram is a renaming of another one, both items will be displayed in the browser, with a special hashed link between the two. Since the renaming subprogram doesn’t have a proper body, you will then need to ask for the subprograms called by the renamed to get the list.

In this browser, clicking on the right arrow in the title bar will display all the entities that are called by the selected item.

Clicking on the left arrow will display all the entities that call the selected item (i.e. its callers).

This browser is generally opened by right-clicking on the name of an entity in source editors or Project view, and selecting one of Browsers ‣ <entity> calls, Browsers ‣ <entity> calls (recursive) or Browsers ‣ <entity> is called by.

All boxes in this browser list several information: the location of their declaration, and the list of all their references in the other entities currently displayed in the browser. If you close the box for an entity that calls them, the matching references are also hidden, to keep the contents of the browser simpler.

If you right-click on the title of one of the entity boxes, you will get the same contextual menu as when you click on the name of an entity in an editor, with the additional items:

- Go To Spec Selecting this item will open a source editor that displays the declaration of the entity.
- Go To Body Selecting this item will open a source editor that displays the body of the entity.
- Locate in Project View Selecting this menu entry will move the focus to the project view, and select the first node representing the file in which the entity is declared. This makes it easier to see which other entities are declared in the same file.

See also Common features of the browsers for more capabilities of the GPS browsers.

## 2.16. The Bookmarks view

Bookmarks are a convenient way to remember places in your code or in your environment so that you can go back to them at any point in the future. These bookmarks are saved automatically whenever they are modified, and restored when GPS is reloaded, so that they exist across GPS sessions.

Bookmarks will automatically remember the exact location in an editor, not in terms of line/column, but in terms of which word they point to. If you modify the file through GPS, the bookmark will be automatically updated to keep refering to the same place. Likewise if you close and reopen the file. However, when the file is modified outside of GPS, the bookmark will not be aware of that change, and will thus reference another place in the file.

The menu Edit ‣ Create Bookmark allows you to create a bookmark at the current location (either in the editor, or the browser for instance).

All the bookmarks you have created will be visible in the Tools ‣ Views ‣ Bookmarks window. Clicking on the line will immediately open an editor with the cursor at that position.

In the Bookmarks window, the local toolbar provides three buttons to act on the bookmarks:

- Create is similar to the Edit ‣ Create Bookmark and will create a bookmark at the current location. After pressing this button, you can immediately start typing a custom name for the new bookmark (or just press `enter` to keep the default name, which is based on the name of the enclosing subprogram).
- Rename can be used to rename the currently selected bookmark. Editing is inline, so you can immediately start typing the new name and press `enter` when done.
- Remove is used to delete the selected bookmark.

## 2.17. The Shell and Python Windows

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

The menu Tools ‣ Consoles ‣ GPS Shell can be used to open the shell console. The GPS shell is a custom language that was mostly used when GPS did not have python support, and is obsolete at this point.

The menu Tools ‣ Consoles ‣ Python opens the python console. Python is the preferred language to customize your GPS (and many more details will be provided in later sections of this documentation). The console is mostly useful for testing interactive commands before you use them in your own scripts.

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

In both these consoles, GPS provides a history of previously typed commands. You can use the `up` and `down` keys to navigate through the history of commands.

## 2.18. The OS shell window

An OS shell window is also available in GPS, providing a simple access to the underlying OS shell as defined by the `SHELL` or `COMSPEC` environment variables.

This console is opened via the Tools ‣ Consoles ‣ OS Shell menu. This menu is available only if the plug-in `shell.py` was loaded in GPS (which is the default).

This console behaves like the standard shell on your system, including support for ANSI sequences (and thus color output). For instance, it has been used to run vi within GPS.

Check the documentation of that plug-in, which lists a few settings that might be useful.

## 2.19. 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. It must be closed explictly.

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.

## 2.20. The Task Manager

The Task Manager window lists all the currently running GPS operations that run in the background, such as builds, searches or VCS commands.

For each of these tasks, the Task Manager shows the status of the task, and the current progress. The execution of theses tasks can be suspended by clicking on the smalle pause button next to the task. The tasks can also be killed by clicking on the interrupt button.

The Task Manager is opened by double clicking on the progress bar in the main toolbar, or using the Tools ‣ Views ‣ Tasks menu, and can be put anywhere in your desktop.

When exiting GPS, if there are tasks running in the Task Manager, a window will display those tasks. You can force the exit at any time by pressing the confirmation button, which will kill all remaining tasks, or continue working in GPS by pressing the Cancel button.

## 2.21. The Project Browser

The project browser shows the dependencies between all the projects in the project hierarchy. Two items in this browser will be linked if one of them imports the other.

It is accessed through the contextual menu in the Project view, by selecting the Show projects imported by... item, when right-clicking on a project node.

Clicking on the left arrow in the title bar of the items will display all the projects that import that project. Similarly, clicking on the right arrow will display all the projects that are imported by that project.

The contextual menu obtained by right-clicking on a project item contains several items. Most of them are added by the project editor, and gives direct access to editing the properties of the project, adding dependencies...

Some new items are added to the menu:

- Locate in Project View

  Selecting this menu will switch the focus to the Project view, and highlight the first project node found that matches the project in the browser item. This is a convenient way to get information like the list of directories or source files for that project.

- Show projects imported by...

  This menu plays the same role as the right arrow in the title bar, and display all the projects in the hierarchy that are imported directly by the selected projecto

- Show projects imported by ... (recursively)

  This menu will display all the dependencies recursively for the project (i.e. the projects it imports directly, the projects that are imported by them, and so on).

- Show projects importing...

  This item plays the same role as the left arrow in the title bar, and displays all the projects that directly import the selected project.

See also Common features of the browsers for more capabilities of the GPS browsers.

## 2.22. The Dependency Browser

The dependency browser shows the dependencies between source files. Each item in the browser represents one source file.

In this browser, clicking on the right arrow in the title bar will display the list of files that the selected file depends on. A file depend on another one if it explicitly imports it (`with` statement in Ada, or `#include` in C/C++). Implicit dependencies are currently not displayed in this browser, since the information is accessible by opening the other direct dependencies.

Clicking on the left arrow in the title bar will display the list of files that depend on the selected file.

This browser is accessible through the contextual menu in the Project view, by selecting one of the following items:

- Show dependencies for ...

  This has the same effect as clicking on the right arrow for a file already in the browser, and will display the direct dependencies for that file.

- Show files depending on ...

  This has the same effect as clicking on the left arrow for a file already in the browser, and will display the list of files that directly depend on that file.

The background contextual menu in the browser adds a few entries to the standard menu:

- Open file...

  This menu entry will display an external dialog in which you can select the name of a file to analyze.

- Recompute dependencies

  This menu entry will check that all links displays in the dependency browser are still valid. If not, they are removed. The arrows in the title bar are also reset if necessary, in case new dependencies were added for the files.

  The browser is not refreshed automatically, since there are lots of cases where the dependencies might change (editing source files, changing the project hierarchy or the value of the scenario variables, ...)

  It also recomputes the layout of the graph, and will change the current position of the boxes.

- Show system files

  This menu entry indicates whether standard system files (runtime files for instance in the case of Ada) are displayed in the browser. By default, these files will only be displayed if you explicitly select them through the Open file menu, or the contextual menu in the project view.

- Show implicit dependencies

  This menu entry indicates whether implicit dependencies should also be displayed for the files. Implicit dependencies are files that are required to compile the selected file, but that are not explicitly imported through a `with` or `#include` statement. For instance, the body of generics in Ada is an implicit dependency. Any time one of the implicit dependencies is modified, the selected file should be recompiled as well.

The contextual menu available by right clicking on an item also adds a number of entries:

- Analyze other file

  This will open a new item in the browser, displaying the complement file for the selected one. In Ada, this would be the body if you clicked on a spec file, or the opposite. In C, it depends on the naming conventions you specified in the project properties, but you would generally go from a `.h` file to a `.c` file and back.

- Show dependencies for ...

  These play the same role as in the project view contextual menu

See also Common features of the browsers for more capabilities of the GPS browsers.

## 2.23. The Elaboration Circularities browser

GPS can detect elaboration cycles reported by build processes, and construct a visual representation of elaboration dependencies, in an Elaboration Cycles browser.

This visual representation represents program units as items in the browsers, and direct dependencies between program units as links. All units involved in a dependency cycle caused by the presence of a pragma Elaborate_All (whether explicit or implicit) are also presented in the browser and connected by links with labels “body” and “with”.

The preference Browsers ‣ Show elaboration cycles controls whether to automatically create a graph from cycles listed in build output.

See also Common features of the browsers for more capabilities of the GPS browsers.

## 2.24. The Entity Browser

The entity browser displays static information about any source entity. The exact content of the items depend on the type of the item. For instance:

- `Ada record / C struct`

  The list of fields, each as an hyper link, is displayed. Clicking on one of the fields will open a new item for the type.

- `Ada tagged type / C++ class`

  The list of attributes and methods is displayed. They are also click-able hyper-links.

- `Subprograms`

  The list of parameters is displayed

- `Packages`

  The list of all the entities declared in that package is displayed

- and more...

This browser is accessible through the contextual menu Browsers ‣ Examine entity in the project view and source editor, when clicking on an entity.

Most information in the items are clickable (by default, they appear as underlined blue text). Clicking on one of these hyper links will open a new item in the entity browser for the selected entity.

This browser can display the parent entities for an item. For instance, for a C++ class or Ada tagged type, this would be the types it derives from. This is accessible by clicking on the up arrow in the title bar of the item.

Likewise, children entities (for instance types that derive from the item) can be displayed by clicking on the down arrow in the title bar.

An extra button appear in the title bar for the C++ class or Ada tagged types, which toggles whether the inherited methods (or primitive operations in Ada) should be displayed. By default, only the new methods, or the ones that override an inherited one, are displayed. The parent’s methods are not shown, unless you click on this title bar button.

See also Common features of the browsers for more capabilities of the GPS browsers.

## 2.25. The File Selector

The file selector is a dialog used to select a file. On Windows, the default is to use the standard file selection widget. On 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, click on OK to confirm, or click on Cancel at any time to cancel and close the file selection.

### Navigation

- index
- modules |
- next |
- previous |
- GPS 6.0.1 documentation »