2. Description of the Main Window

The GNAT Programming Studio has one main window, which is where you perform most of your work. However, GPS is very flexible and lets you organize your desktop many different ways, as discussed in a later section (Multiple Document Interface).

There are also other windows that might pop up at various times, documented in this section.

2.1. The Workspace

The overall workspace is based on a multiple document interface (see Multiple Document Interface) and can contain any number of windows, the most important of which are usually the editors. However, GPS also provides a large number of views that you can add to the workspace. The sections below list them.

2.1.1. Common features of the views

Some views are part of the default desktop and are visible by default. Open the other views through one of the submenus of the Tools menu, most often Tools ‣ Views.

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

There is often a button to the right of these local toolbars that opens a local settings menu. This menu either contains more actions you can perform in that view or various configuration settings allowing you to change the behavior or display of the view.

Some views also have a filter in their local toolbar. You can use these filters to reduce the amount of information displayed on the screen by only displaying those lines matching the filter.

If you click on the left icon of the filter, GPS brings up a popup menu to allow you to configure the filter:

  • Use the first three entries to chose the search algorithm (full text match, regular expression, or fuzzy matching). These modes are similar to the ones used in the omni-search (see The omni-search).
  • The next entry is Invert filter. When you select this option, lines that do not match the filter are displayed, instead of the default behavior of displaying ones that match the filter. You can also enable this mode temporarily by beginning the filter with the string not:. For example, a filter in the Locations view saying not:warning hides all warning messages.
  • Select the last entry, Whole word, when you only want to match full words, not substrings.

2.1.2. Common features of browsers

GPS presents a view of information using an interactive display called a “browser”, which shows a canvas containing boxes you can manipulate. Browsers provide the following additional capabilities:

  • Links

    Boxes can be linked together and remain linked when they are moved. The are different types of links; see the description of the various browsers for more details.

    Hide links using a button on the local toolbar. This keeps the canvas more readable at the cost of losing information. You can also hide only a subset of links. Even when links are hidden, if you select a box, boxes linked to it are still highlighted.

  • Scrolling

    When many boxes are displayed, the currently visible area may be too small for all of them. When that happens, GPS adds scrollbars. You can also scroll using the arrow keys, or by dragging the background while pressing the left mouse button.

  • Layout

    GPS organizes the boxes in a browser using a simple layout algorithm, which is layer oriented: items with no parents are put in the first layer, 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. If you move boxes, this algorithm tries to preserve their relative positions as much as possible.

    Use the Refresh layout button in the local toolbar to recompute the layout at any time, including that of boxes you moved.

  • Moving boxes

    Move boxes with the mouse. Drag the box by clicking on its title bar. The box’s links are still displayed during the move, so you can see whether it overlaps any other box. If you try to move the box outside the visible part of the browser, it is scrolled.

  • Selecting boxes

    Select a box by clicking it.

    The title bar of selected boxes is a different color. All boxes linked to them also use a different title bar color and so do the links. This is the most convenient way to visualize the relationships between boxes when many are present in the browser.

    Use buttons in the local toolbar to either remove the selected boxes or remove the boxes that are not selected.

  • Zooming

    GPS provides several different zoom levels. Use the zoom in, zoom out, and zoom buttons in the local toolbar to change the level and use the latter to explicitly select the level you want.

    You can also press the alt key and use the mouse wheel to zoom in or out.

    This capability is generally useful when many boxes are displayed in the browser to allow you to get an overview of the layout and the relationships between the boxes.

  • export

    Export the entire contents of a browser as a PNG or SVG image using the Export to... button in the local toolbar.

  • Hyper-links

    Some boxes contain hyper links, displayed in blue by default, and underlined. Clicking on these generally displays new boxes.

  • Contextual menus

    Right-clicking on boxes displays a contextual menu with actions you can perform on that box. These actions are specific to the kind of box you clicked.

  • Grid

    By default, GPS displays a grid (small dots) on the canvas. Use the local settings menu to hide the grid (uncheck Draw grid) or 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 represented by icons within the various GPS views (for example, the Outline and Project views). These icons indicate both the semantic category of the entity within the language, such as packages and methods, as well as compile-time visibility. The icons also distinguish entity declarations from other entities. The same icons are used for all programming languages supported by GPS, with language-specific interpretations for both compile-time visibility and distinguishing declarations and uses of entities.

These five language categories are used for all supported languages:

  • The package category’s icon is a square.

    _images/square_x.png
  • The subprogram category’s icon is a circle.

    _images/circle_x.png
  • The type category’s icon is a triangle.

    _images/triangle_x.png
  • The variable category’s icon is a dot.

    _images/dot_x.png
  • The generic category’s icon is a diamond.

    _images/diamond_x.png

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

Icons for ‘protected’ and ‘private’ entities appear within an enclosing box indicating a compile-time visibility constraint. For entities with ‘protected’ visibility, the enclosing box is gray. ‘Private’ entities are enclosed by a red box. Icons for ‘public’ entities have no enclosing box. For example, a variable with ‘private’ visibility is represented by an icon consisting of a dot enclosed by a red box. These additional decorations 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 by a red box.

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

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

Icons for a given entity may appear more than once within a view. For example, an Ada private type has both a partial view in the visible part of the enclosing package and a full view in the private part of the package. A triangle icon will appear for each of the two occurrences of the type name, one with the additional decoration indicating ‘private’ visibility.

2.2. The Welcome Dialog

_images/welcome.png

When GPS starts, it looks for a project file to load so it knows where to find the sources of your project. This project is often specified on the command line (via a -P switch). If not, and the current directory contains only one project file, GPS selects it automatically. Finally, if you specify the name of a source file to edit, GPS loads a default project. If GPS cannot find a project file, it displays a welcome dialog, giving you the following choices:

  • Create new project from template

    Selecting this choice and the clicking OK button launches 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 example.

  • Start with default project in directory

    Selecting this choice and clicking the OK button causes GPS to look for a project called default.gpr in the current directory and load it if found. Otherwise, it copies the default project <prefix>/share/gps/default.gpr into the current directory and loads it. GPS removs this temporary copy when exiting or loading another project if you have not modified the copy.

    The default project contains all the Ada source files from the specified directory (assuming they use the default GNAT naming scheme .ads and .adb).

    If the current directory is not writable, GPS instead loads <prefix>/share/gps/readonly.gpr. In this case, GPS runs in a limited mode, where some capabilities (such as building and source navigation) are not available. This project will not contain any sources.

  • Create new project with wizard

    Selecting this choice and clicking the OK button starts a wizard allowing you to specify most of the properties for a new project. Once the project is created, GPS saves it and loads 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 depends on the kind of project you want to create.

    One of the wizards, Project Tree, tries to 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 puts the objects in the same directory they are currently in. If you have not compiled your application when launching this wizard, GPS creates a single project file that puts all object files in the same directory. This is the prefered method when importing sources with duplicate file names, since the latter is only allowed in a single project file, not across multiple project files.

  • Open existing project

    Select an existing project by clicking on the Browse button or 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 will not be shown in future sessions. In this case, GPS behaves as follows: it first looks for a -P switch on the command line and loads the corresponding project if so; otherwise, it looks for a project file in the current directory and loads it if there is only one; if no project file was loaded, GPS starts 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 Edit ‣ Preferences menu.

  • Quit

    If you click on this button, GPS terminates immediately.

2.3. The Tip of the Day

_images/tip-of-the-day.png

This dialog displays short tips on making the most efficient use of the GNAT Programming Studio. Click on the Previous and Next buttons to access all tips or close the dialog by either clicking on the Close button or pressing the ESC key.

Disable this dialog by unchecking the Display Tip of the Day on startup check box. To reenable this dialog, go to the Edit ‣ Preferences menu.

2.4. The Menu Bar

_images/menubar.png

GPS provides a standard menu bar giving access to all operations. However, it is usually easier to access a feature using the various contextual menus provided throughout GPS: these give direct access to the most relevant actions in the current context (for example, a project, directory, file, or entity). Contextual menus pop up when you click the right mouse button or use the special open contextual menu key on most keyboards.

You can access the following entries from the menu bar:

2.5. The Tool Bar

_images/toolbar.png

The tool bar provides shortcuts to some common actions:

  • Create a new file
  • Open an existing file (see also the omni-search on the right of the bar)
  • Save the current file
  • Undo or redo last editing
  • Go to previous or next saved location
  • Multiple customizable buttons to build, clean, or run your project
  • multiple buttons to stop and continue the debugger, step to the next instruction, and other similar actions when a debugger is running.

When GPS is performing background actions, such as loading cross-reference information or all actions involving external processes (including compiling), it displays a progress bar in the toolbar showing when the current task(s) will be completed. Click on the small interrupt button to interrupt all background tasks. Clicking on the progress bar opens the Tasks view (see The Task Manager).

2.7. The Messages view

_images/messages.png

The Messages view, which is readonly, displays information and feedback about operations, including build output, information about processes launched, and error messages.

Its local toolbar contains buttons to Clear the contents of the window, as well as Save and Load from files. The latter operation also parses those messages into the Locations window.

The actual output of the compilation is displayed in the Messages view but is also parsed and many of its messages are displayed more conveniently in the Locations view (se The Locations View). When a compilation finishes, GPS displays the total elapsed time.

You cannot close the Messages view because it might contain important messages. If GPS closed it, you can reopen it with the Tools ‣ Views ‣ Messages menu.

2.8. The Locations View

_images/locations-view.png

GPS uses the Location view, which is also readonly, to display a list of locations in source files (for example, when performing a global search or displaying compilation results).

It displays a hierarchy of categories, each of which contain files, each, in turn, containing messages at specific locations. The category describes the type of messages (for example, search or build results). If the full text of a message is too large to be completely shown in the window, placing the mouse over it pops up a tooltip window with the full text.

Each message in this window corresponds to a line in a source editor. This line has been highlighted and has a mark on its left side. Clicking on a message brings up an editor pointing to that line.

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

  • Clear removes all entries from the view and, depending on your settings, may also close the view.
  • Remove removes the currently selected category, file or message as well as the corresponding highlighting in the source editor.
  • Save saves the contents of the view to a text file for later reference. You cannot load this file back into the Locations view, but you can load it into the Messages view. However, if you plan to reload it later, it is better to save and reload the contents of the Messages view instead.
  • Expand All and Collapse All shows or hides all messages in the view.
  • a filter to selectively show or hide some messages. Filtering is done on the text of the message itself (the filter is either text or a regular expression). You can also reverse the filter. For example, typing warning in the filter field and reversing the filter hides warning messages

The local settings menu contains the following entries:

  • Sort by subcategory

    Toggle the sorting of messages by sub-categories. This is useful for separating warnings from errors in build results. The error messages appear first. The default is to sort the message by their location.

  • Sort files alphabetically

    Sort messages by filenames (sorted alphabetically). The default does not sort by filenames to make it easier to manipulate Locations view while the compilation is proceeding. (If sorted, the messages might be reordered while you are trying to click on them).

  • Jump to first location

    Every time a new category is created, for example, as a result of a compilation or search operation, the first message in that category is automatically selected and the corresponding editor opened.

  • Warp around on next/previous

    Controls the behavior of the Previous tag and Next tag menus (see below).

  • Auto close locations

    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. Be careful, because the loaded contents might not apply the next time. For example, the source files have changed, or build errors have been fixed. So you should not select this option if those conditions might apply.

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

You can also 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

_images/project-view.png _images/project-view-flat.png

The project view displays a representation of the various components of your project. By default, it is displayed on the left side of the workspace. Select it using the Project ‣ Project View or Tools ‣ Views ‣ Project menus.

On Windows, you can drop files (for example, from Windows Explorer) into the project view. If you drop a project file, GPS loads it and it replaces the current project; if you drop a source file, GPS opens it in a new editor.

This search opens a small window at the bottom of the view where you can interactively type names. The first matching name in the tree is selected when you type it. Use the up and down keys to navigate through all the items matching the current text.

The various components displayed in the project view are:

projects

Each source file you are working with is part of a project. Projects are a way to record the switches to use for the various tools as well as a number of other properties such as 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 for details on how projects are loaded in GPS).

The Project view displays this project hierarchy: the top node is the root project of your application (usually where the source file that contains the main subprogram will be located). A node is displayed for each imported project and recursively for other imported projects. If a project is imported by several projects, it may appear multiple times in the view,

If you edited the project manually and used the limited with construct to create cycles in the project dependencies, the cycle will expand infinitely. For example, if project a imports project b, which in turn imports project a through a limited with clause, then expanding the node for a shows b. In turn, expanding the node for b shows a node for a, and so on.

An icon with a pen mark is displayed if the project was modified but not saved yet. You can save it at any time by right-clicking the icon. GPS either reminds you to save it before any compilation or saves it automatically, depending on your preference settings.

GPS provides 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. You may find this display useful for deep project hierarchies, where it can make it easier to find projects. Activate this display using the local settings menu to the right of the Project view toolbar.

directories

The files in a project are organized into several directories on disk. These directories are displayed under each project node in the Project view

You chose whether to see the absolute path names for the directories or paths relative to the location of the project by using the local settings menu Show absolute paths of the Project view. In all cases, the tooltip displayed when the mouse hovers over a file or directory shows the full path.

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

Use the local setting Show hidden directories to select the directories to be considered hidden. Use this to hide version control directories such as CVS or .svn.

files

Source files are displayed under the node corresponding to the directory containing the file. Only the source files actually belonging to the project (i.e. are written in a language supported by that project and follow its naming scheme) are visible. For more information on supported languages, see Supported Languages. A file might appear multiple times in the Project view if the project it belongs to is imported by several other projects.

You can drag a file into GPS. This opens a new editor if the file is not already being edited or moves to the existing editor otherwise. If you press shift while dragging the file and it is already being edited, GPS creates a new view of the existing editor.

entities

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

Double-clicking on a file or clicking on any entity opens an editor or display showing, respectively, the first line in the file or the line on which the entity is defined.

If you open the search dialog via the Navigate ‣ Find or Replace... menu, you can search for anything in the Project view, either a file or an entity. Searching for an entity can be slow if you have many files and/or large files.

GPS also provides a contextual menu, called Locate in Project View, in source editors. This automatically searches for the first entry in this file in the Project view. This contextual menu is also available in other modules, for example when selecting a file in the Dependency browser.

The local toolbar of the Project view contains a button to reload the project. Use this when you have created or removed source files from other applications and want to let GPS know there might have been changes 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, such as the tool switches or 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 a project node, a contextual menu appears which contains, among others, the following entries that you can use to understand or modify your project:

  • Show projects imported by...

  • Show projects depending on...

    Open a new window, the Project browser, which displays graphically the relationships between each project in the hierarchy (see The Project Browser).

  • Project ‣ Properties

    Opens a new dialog to interactively edit the attributes of the project (such as tool switches and naming schemes) and is similar to the local toolbar button.

  • Project ‣ Save project...

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

    Any time you modify one or more projects, the contents of the project view is automatically refreshed, but 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, a pen mark on top of the standard icon:

    _images/project-modified.jpg
  • Project ‣ Edit source file

    Loads the project file into an editor so you can edit it. Use this if you need to access some features of the project files that are not accessible graphically (such as rename statements and variables).

  • Project ‣ Dependencies

    Opens the dependencies editor for the selected project (se The Project Dependencies Editor).

  • Project ‣ Add scenario variable

    Adds new scenario variables to the project (see Scenarios and Configuration Variables). Howver, you may find it more convenient to use the Scenario view for this purpose.

All the entries in the local settings menu can be manipulated via python extensions, which might be useful when writing your own plugins. Here are examples on how to do that:

# The 'Show flat view" local setting
GPS.Preference('explorer-show-flat-view').set(True)

# The 'Show absolute paths" local setting
GPS.Preference('explorer-show-absolute-paths').set(True)

# The 'Show hidden directories' local setting
GPS.Preference('explorer-show-hidden-directories').set(True)

# The 'Show empty directories' local setting
GPS.Preference('explorer-show-empty-directories').set(True)

# The 'Projects before directories' local setting
GPS.Preference('explorer-show-projects-first').set(True)

# The 'Show object directories' local setting
GPS.Preference('explorer-show-object-dirs').set(True)

# The 'Show runtime files' local setting
GPS.Preference('explorer-show-runtime').set(True)

# The 'Group by directories' local setting
GPS.Preference('explorer-show-directories').set(True)

2.10. The Scenario view

_images/scenario-view.png _images/scenario-view-nobuild.png

As described in the GNAT User’s Guide, project files can be configured through external variables (typically environment variables). This means 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 view 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. Change the current value by clicking on it and selecting the new value among the ones that pop up.

Across sessions, GPS will remember the values you set for scenario variables. On startup, the initial values for the scenario variables comes, in decreasing order of priority:

  • from the -X command line arguments;
  • from existing environment variables;
  • from the value you set in a previous GPS session;
  • from the default set in the project file;
  • or else defaults to the first valid value for this variable

Whenever you change the value of any variable, GPS automatically recomputes the project and dynamically changes the list of source files and directories to reflect the new status of the project. Starting a new compilation at that point uses the new switches, and all aspects of GPS are immediately changed to reflect the new setup.

Create new scenario variables by selecting the + icon in the local toolbar of the Scenario view. Edit the list of possible values for a variable by clicking on the edit button in that toolbar. Delete a variable by clicking on the - button.

Each of these changes impacts the actual project file (.gpr), so you might not want to make them if you wrote the project file manually since the impact 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). Like scenario variables, change the mode 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, use the local settings menu Show build modes to disable the display.

2.11. The Files View

_images/file-view.png

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 on the disk (including Windows drives). You can also explore each source file explored as described in The Project view. You can also drop files into the Files view to conveniently open a file.

By default, the Files view displays all files on disk. You can set filters through the local settings menu to restrict the display to the files and directories belonging to the project (use the Show files from project only menu).

2.12. The Windows view

_images/windows-view1.png _images/windows-view2.png

The Windows view displays the currently opened windows. Open it via 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 particularly useful if you have many windows open.

You can also choose, through the local configuration menu, whether only 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 the corresponding line. If you leave the button pressed, you can drag the window to another place on the desktop (see the description of the Multiple Document Interface)

Select multiple windows by clicking while pressing the control or shift keys. You can then click in on the first button in the local toolbar to close all selected windows at once, which is a fast way to clean up your desktop after you have finished working on a task.

2.13. The Outline view

_images/outline-view1.png _images/outline-view2.png _images/outline-view3.png

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

Exactly what is displayed depends on the language of the file. For Ada, C and C++ files, this view displays the list of entities declared at the global level in your current file (such as Ada packages, C++ classes, subprograms, and Ada types). This view is refreshed whenever the current editor is modified.

Clicking on any entity in this view automatically jumps to the corresponding line in the file (the spec or the body).

The local settings menu contains multiple check boxes you can use to alter how the outline view is displayed:

  • Show profiles

    Indicates whether the list of parameters of the subprograms should be displayed. This is particularly useful for languages allowing overriding of entities.

  • Show types, Show objects, Show tasks, entries, and protected types

    Controls the display of the specified categories of entities.

  • Show specifications

    Indicates whether GPS displays 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 disabled, nested subprograms are displayed below the subprogram in which they are declared.

  • Group spec and body

    Displays up to two icons on each line (one for the spec and one for the body if both occur in the file). Click on one of the icons to go directly to that location. If you click on the name of the entity, you are taken to its declaration unless it is already the current location in the editor, in which case you are taken to its body.

  • Dynamic link with editor

    Causes the current subprogram to be selected in the outline view each time the cursor position changes in the current editor. This option will slow down GPS.

2.14. The Clipboard view

_images/clipboard.png

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

When you click the Edit ‣ Copy or Edit ‣ Cut menu, GPS adds the current selection to the clipboard. However, unlike many applications, GPS does not discard the previous contents of the clipboard, but instead saves it for future use. By default, up to 10 entries are saved, but you can change that number using the Clipboard Size preference.

When you select the Edit ‣ Paste menu, GPS pastes the last entry added to the clipboard at the current location in the editor. If you then immediately select Edit ‣ Paste Previous, this newly inserted text is removed and GPS instead inserts the second to last entry. You can keep selecting the same menu to insert progressively older entries.

This mechanism allows you to copy several noncontiguous lines from one place in an editor, switch to another editor, and paste all those lines without having to go back and forth between the two editors.

The Clipboard view graphically displays what is currently stored in the clipboard. Open it via the Tools ‣ Views ‣ Clipboard menu.

That view displays a list of entries, each of which is associated with one level of the clipboard. The text displayed for each entry is its first line containing non blank characters with leading characters omitted. GPS prepends or appends [...] if the entry is truncated. If you hover over an entry, a tooltip pops up displaying all lines in the entry.

In addition, one entry has an arrow on its left. This indicates the entry to be pasted if you select the Edit ‣ Paste menu. If you instead select the Edit ‣ Paste Previous menu, the entry below that is inserted instead.

If you double-click any of these entries, GPS inserts the corresponding text in the current editor and makes the entry you click current, so selecting Edit ‣ Paste or the equivalent shortcut will insert that same entry again.

The local toolbar in the clipboard view provides two buttons:

  • Append To Previous.

    The selected entry is appended to the one below and removed from the clipboard so that selecting Edit ‣ Paste pastes the two entries simultaneously. Use this when you want to copy lines from separate places in a file, merge them, and paste them together one or more times later, using a single operation.

  • Remove.

    The selected entry is removed from the clipboard.

The Clipboard view content is preserved between GPS sessions. However very large 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 similar roles in that they display the same information about entities, but in two different ways: the Call tree view displays the information in a tree, easily navigable and perhaps easier to manipulate when lots of entities are involved, and the Callgraph browser displays the information as graphical boxes that you can manipulate on the screen. The latter is best suited to generate a diagram that you can later export to your own documents.

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

Some references are displayed with an additional “(dispatching)” text, which indicates the call to the entity is not explicit in the sources but could potentially occur through dynamic dispatching. (This depends on what arguments are passed to the caller at run time; it is possible the subprogram is in fact never called.)

2.15.1. Call Trees

_images/calltree.png

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.

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, making it very easy to get the information contained in a full callgraph tree. Closing and expanding a node again recomputes the callgraph for the entity.

The right side of the main tree contains a list displays the locations of calls for the selected entity. Click on a entry in this list to open an editor showing the corresponding location.

The Call tree 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 when GPS is restarted because its contents might be misleading if the sources have changed.

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

_images/callgraph.png

The Callgraph browser graphically displays the relationship between subprogram callers and callees. A link between two items indicates one of them is calling the other.

GPS provides special handling for renamed entities (in Ada): if a subprogram is a renaming of another, both items are displayed in the browser with a special hashed link between the two. Since the renamed subprogram does not have a proper body, you need to ask for the subprograms called by the renamed entity to get the list.

In this browser, clicking on the right arrow in the title bar displays all the entities called by the selected item. Clicking on the left arrow displays all the entities that call the selected item (i.e. its callers).

Open this browser by right-clicking on the name of an entity in a source editor or Project view and selecting one of the Browsers ‣ <entity> calls, Browsers ‣ <entity> calls (recursive), or Browsers ‣ <entity> is called by menus.

All boxes in this browser display the location of their declaration and the list of all 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.

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

  • Go To Spec

    Open a source editor displaying the declaration of the entity.

  • Go To Body

    Open a source editor displaying the body of the entity.

  • Locate in Project View

    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 browsers for more capabilities of the GPS browsers.

2.16. The Bookmarks view

_images/bookmarks.png

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

Bookmarks automatically remember the exact location in an editor, not in terms of line and column, but in terms of which character they point to. If you modify the file through GPS, the bookmark is automatically updated so it refers to the same place. However, if the file is modified outside of GPS, it will not be aware of that change and the bookmark may reference a different place in the file.

Use the Edit ‣ Create Bookmark menu to create a bookmark at the current location (either in the editor or the browser).

All bookmarks you created are visible in the Tools ‣ Views ‣ Bookmarks view. Clicking on the bookmark opens an editor with the cursor at that position.

The local toolbar of the Bookmarks view provides three buttons to act on bookmarks:

  • Create

    Similar to the Edit ‣ Create Bookmark menu. Creates a bookmark at the current location. After pressing that button, you can type a custom name for the bookmark or just press enter to keep the default name, which is based on the name of the enclosing subprogram.

  • Rename

    Renames the currently-selected bookmark.

  • Remove

    Deletes the selected bookmark.

2.17. The Python Console

_images/shell-window.png _images/python-window.png

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

The menu Tools ‣ Consoles ‣ Python opens the python console. Python is the preferred language to customize GPS (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.

Both consoles provide a history of previously typed commands. Use the up and down keys to navigate through the command history.

2.18. The OS Shell Console

_images/os_shell-window.png

GPS also provides an OS shell console, providing a access to the underlying OS shell (as defined by the SHELL or COMSPEC environment variables).

Open this console via the Tools ‣ Consoles ‣ OS Shell menu, which is available only if the plug-in shell.py was loaded in GPS (the default). Check the documentation of that plug-in, which lists a few settings that might be useful.

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

2.19. The Execution window

When a program is launched using the Build ‣ Run menu, GPS creates a new execution window allowing input and output for the program. To allow post-mortem analysis and copy/pasting, GPS does not close execution windows when the program terminates; you must close them manually. If you try to close the execution window while the program is still running, GPS displays a dialog window asking if you want to kill it.

2.20. The Task Manager

_images/task-manager.png

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

For each task, the Task Manager displays its status and current progress. Suspend the execution of a task by clicking the small pause button next to the task. Or kill a task by clicking the interrupt button.

Open the Task Manager by double clicking on the progress bar in the main toolbar or using the Tools ‣ Views ‣ Tasks menu. You can move it placed anywhere on your desktop.

_images/task-manager-exit.png

If there are tasks running when exiting GPS, it displays a window showing those tasks. You can kills all remaining tasks and exit by pressing the confirmation button or continue working in GPS by pressing the Cancel button.

2.21. The Project Browser

_images/project-browser.png

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

Access it through the contextual menu in the Project view by selecting the Show projects imported by... menu when right-clicking on a project node.

Click on the left arrow in the title bar of a project to display all projects that import that project. Click on the right arrow to display all projects imported by that project.

Right-clicking on a project brings up a menu containing several items. Most are added by the project editor and provide direct access to such features as editing the properties of the project, adding dependencies.

Some items in the menu are specific to the Project Browser:

  • Locate in Project View

    Switch the focus to the Project view and highlight the first project node matching the project. This is a convenient way to get information such as the list of directories or source files for a project.

  • Show projects imported by...

    Like the right arrow in the title bar, displays all the projects in the hierarchy that are directly imported by the selected project.

  • Show projects imported by ... (recursively)

    Display all dependencies recursively for the project (i.e., the projects it imports directly and the projects they import).

  • Show projects importing...

    Like the left arrow in the title bar, display all the projects that directly import the selected project.

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

2.22. The Dependency Browser

_images/dependency-browser.png

The dependency browser displays dependencies between source files. Each item in the browser represents one source file. Click on the right arrow in the title bar to display the list of files the selected file depends on. A file depends on another if it explicitly imports it (with statement in Ada, or #include in C/C++). Implicit dependencies are currently not displayed in this browser since you can access that information by opening the direct dependencies. Click on the left arrow in the title bar to 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 entries:

  • Show dependencies for ...

    Like clicking on the right arrow for a file already in the browser, displays the direct dependencies for that file.

  • Show files depending on ...

    Like clicking on the left arrow for a file already in the browser, displays 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...

    Display an external dialog where you can select the name of a file to analyze.

  • Recompute dependencies

    Check that all links displays in the dependency browser are still valid. Any that not are removed. The arrows in the title bar are also reset if new dependencies were added for the files. Also recompute the layout of the graph and changes the current position of the boxes. However, the browser is not refreshed automatically, since there are many cases where the dependencies might change.

  • Show system files

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

  • Show implicit dependencies

    Indicates whether implicit dependencies should also be displayed for files. Implicit dependencies are ones required to compile the selected file but not explicitly imported through a with or #include statement. For example, the body of a generic in Ada is an implicit dependency. Whenever an implicit dependency is modified, the selected file should be recompiled as well.

The contextual menu available by right clicking on an item also contain these entries:

  • Analyze other file

    Open a new item in the browser, displaying the files associated with the selected one. In Ada, this is the body if you clicked on a spec file, or vice versa. In C, it depends on the naming conventions you specified in the project properties, but it generally goes from a .h file to a .c file and back.

  • Show dependencies for ...

    These have the same function as in the project view contextual menu

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

2.23. The Elaboration Circularities browser

_images/elaboration-graph.png

GPS detects elaboration cycles reported by build processes and constructs a visual representation of elaboration dependencies in an Elaboration Cycles browser.

This visual representation depicts program units as items in the browser 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 and connected by links labeled “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 browsers for more capabilities of GPS browsers.

2.24. The Entity browser

_images/entity-browser.png

The Entity browser displays static information about any source entity. What is displayed for each entity depends on the type of the entity, but are normally other entities. For example:

  • Ada record / C struct

    The list of fields is displayed.

  • Ada tagged type / C++ class

    The list of attributes and methods is displayed.

  • Subprograms

    The list of parameters is displayed

  • Packages

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

Access this browser via the Browsers ‣ Examine entity contextual menu in the project view and source editor when clicking on an entity.

Most entities displayed are clickable (by default, they appear as underlined blue text). Clicking on one opens a new item in the entity browser for the selected entity.

You can display the parent entities for an entity. For example, in a C++ class or Ada tagged type, this is the type it derives from. Display the parent by clicking on the up arrow in the title bar of the entity.

Similarly, you can display child entities (for example, types that derive from the item) by clicking on the down arrow in the title bar.

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

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

2.25. The File Selector

_images/open-file.png

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 provides the following contents:

  • A tool bar on the top consists of five buttons:
    • 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. Modify the current directory by modifying the text entry and pressing Enter or by clicking on the right arrow and choosing a previous directory in the pop down list displayed.
  • A directory tree. 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 next directory, + and - to expand and collapse the current directory, and backspace to select the parent directory.
  • A filter area. Depending on the context, one of several filters are available to select only a subset of files to display. The filter All files is always available and displays all files in the selected directory.
  • A file list. This area lists the files contained in the selected directory. If you specified a filter, only the matching files are displayed. Depending on the context, the list of files may include additional information about the files such as the type of file or its size.
  • A file name area. This area displays the name of the current file, if any. You can also type a file or directory name, with file completion provided by the Tab key.
  • A button bar with the OK and Cancel buttons. When you have selected the desired file, click OK to confirm or click Cancel at any time to cancel the file selection.