/usr/share/doc/gnat-gps/html/The-Project-View.html

<html lang="en">
<head>
<title>The Project View - Using the GNAT Programming Studio</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="Using the GNAT Programming Studio">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Description-of-the-Main-Windows.html#Description-of-the-Main-Windows" title="Description of the Main Windows">
<link rel="prev" href="The-Work-Space.html#The-Work-Space" title="The Work Space">
<link rel="next" href="The-File-View.html#The-File-View" title="The File View">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
Copyright (C) 2002-2010 AdaCore.

This document is free; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or
(at your option) any later version.

This document is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, see `http://www.gnu.org/licenses/'.-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
  pre.display { font-family:inherit }
  pre.format  { font-family:inherit }
  pre.smalldisplay { font-family:inherit; font-size:smaller }
  pre.smallformat  { font-family:inherit; font-size:smaller }
  pre.smallexample { font-size:smaller }
  pre.smalllisp    { font-size:smaller }
  span.sc    { font-variant:small-caps }
  span.roman { font-family:serif; font-weight:normal; } 
  span.sansserif { font-family:sans-serif; font-weight:normal; } 
pre.smallexample {background-color:rgb(240,240,240);
                     font-family: courier new,courier,fixed;
                     font-size: 14px;
                     margin: 0px 40px 0px 40px;
                     border-width: 1px 2px 2px 1px;
                     border-top-style: dotted;
                     border-left-style: dotted;
                     border-right-style: solid;
                     border-bottom-style: solid;
                     border-color: black;}
   code             {color:black;
                     font-family: courier new,courier,fixed;
                     font-size: 14px;}
   body             {font-family: arial,helvetica,sans-serif;
                     font-size: 16px;
                     max-width: 800px;
                     text-align: justify}
   samp             {font-family: courier new,courier,fixed;
                     font-size: 14px}
                    
--></style>
</head>
<body>
<div class="node">
<a name="The-Project-View"></a>
<p>
Next:&nbsp;<a rel="next" accesskey="n" href="The-File-View.html#The-File-View">The File View</a>,
Previous:&nbsp;<a rel="previous" accesskey="p" href="The-Work-Space.html#The-Work-Space">The Work Space</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="Description-of-the-Main-Windows.html#Description-of-the-Main-Windows">Description of the Main Windows</a>
<hr>
</div>

<h3 class="section">2.6 The Project View</h3>

<p><a name="index-project-view-23"></a><a name="index-project-view-24"></a><a name="index-project-25"></a><!--  -->

<p class="noindent">The project view provides a representation of the various components of your
project hierarchy, as listed below. 
It is displayed by default on the left side of the main window, and can
be selected by using the <code>Project-&gt;Project View</code> or
<code>Tools-&gt;Views-&gt;Project</code> menu items.

   <p><a name="index-drag_002dn_002ddrop-26"></a>Under Windows, it is possible to drop files (coming e.g. from the Explorer)
in the project view with the following behavior: a project file dropped
will be loaded; any other file will be opened in a new source editor.

   <p><a name="index-screen-shot-27"></a><img src="project-view.jpg" alt="project-view.jpg">

   <p><a name="index-interactive-search-28"></a>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. The default key
to start an interactive search is &lt;control-f&gt;. 
<a name="Interactive-Search"></a>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 &lt;up&gt; and &lt;down&gt; keys to navigate through
all the items matching the current text.

   <p>The various components that are displayed are:

     <dl>
<dt><b>projects</b><dd><a name="index-project-view-29"></a>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.

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

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

     <p>The <code>Project View</code> 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.

     <p>A given project might appear multiple times in the
<code>Project View</code>, if it is imported by several other projects.

     <p>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.

     <p><a name="index-Show-flat-view-30"></a>This display is activated through the contextual menu entry
<code>Show flat view</code>, which acts as a switch between the two displays.

     <p>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.

     <br><dt><b>directories</b><dd><a name="index-directory-31"></a><a name="index-Windows-32"></a>The files inside a project can be organized into several physical
directories on the disk. These directories are displayed under each
project node in the <code>Project View</code>

     <p><a name="index-Show-absolute-paths-33"></a>You can chose whether you want to see the absolute path names for the
directories or paths relative to the location of the project. This is done
through the <code>Show absolute paths</code> contextual menu.

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

     <p><a name="index-Show-hidden-directories-34"></a>The contextual menu entry <code>Show hidden directories</code> can be used to filter
the directories considered as hidden. This can be used to not display the
version control directories like <samp><span class="file">CVS</span></samp> or <samp><span class="file">.svn</span></samp> for example.

     <br><dt><b>files</b><dd><a name="index-file-35"></a><a name="index-file-view-36"></a>The source files themselves are stored 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
follow its naming scheme) are actually visible. 
For more information on supported languages, See <a href="Supported-Languages.html#Supported-Languages">Supported Languages</a>.

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

     <p>If you left click on a file and keep the button pressed, you can drop it
anywhere in GPS to open an editor at that location.

     <br><dt><b>entities</b><dd><a name="index-entity-37"></a>If you open the node for a source file, the file is parsed by one of the
fast parsers integrated in GPS so that all entities declared in
the project can be shown. These entities are grouped into various
categories, which depend on the language. Typical categories include
subprograms, packages, types, variables, tasks, <small class="dots">...</small>

   </dl>

   <p>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.

   <p>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 &lt;shift&gt; at the same time, and the file is already edited,
a new view of the existing editor is created instead.

<!-- ??? Following is currently disabled -->
<!-- Moving the mouse over the different components displayed on the -->
<!-- project view will open tooltips with some more information -->
<!-- depending on the type of component: -->
<!-- @table @b -->
<!-- @item projects -->
<!-- The tooltip contains the project full pathname. -->
<!-- @item directories -->
<!-- The tooltip contains the directory full pathname and the project name in -->
<!-- which it is defined. -->
<!-- @item files -->
<!-- The tooltip contains the base filename and the project name in -->
<!-- which it is defined. -->
<!-- @item entities -->
<!-- The tooltip contains the entity name and parameters for routines followed -->
<!-- by the location in the form filename:line where it is declared. -->
<!-- @end table -->
   <p><a name="index-search-38"></a><a name="index-find-39"></a>If you open the search dialog through the <code>Navigate-&gt;Find or Replace...</code>
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.

   <p><a name="index-view-40"></a><a name="index-locate-in-project-view-41"></a>A contextual menu, named <code>Locate in Project View</code>, is also provided when
inside a source editor. 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 <code>Dependency Browser</code>.

<h4 class="subsection">2.6.1 The configuration variables</h4>

<p><a name="index-configuration-variable-42"></a><a name="index-project-variable-43"></a><a name="index-variable-44"></a>
<a name="index-GNAT-45"></a><a name="index-project-file-46"></a><a name="index-project-47"></a>As described in the GNAT User's Guide, the project files can be
configured through external variables (typically environment
variables). This means that e.g. the exact list of source files, or the
exact switches to use to compile the application can be changed when
the value of these external variables is changed.

   <p>GPS provides a simple access to these variables, through a window
called the <code>Scenario View</code>. These variables are called
<code>Configuration Variables</code>, since they provide various scenarios for
the same set of project files.

   <p><a name="index-screen-shot-48"></a><img src="scenario-view.jpg" alt="scenario-view.jpg">

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

   <p><a name="index-project-view-49"></a>New variables can be added through the contextual menu
<code>Project-&gt;Add Configuration Variable</code> in the <code>Project View</code>. 
The list of possible values for a variable can be changed by clicking on the
button on the left of the variable's name.

   <p>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.

<h4 class="subsection">2.6.2 Icons for source language entities</h4>

<p><a name="index-icons-for-source-language-entities-50"></a>
Entities in the source code are presented with representative icons
within the various GPS views (the <em>Outline</em>, <em>Project</em>,
and <em>Entity</em> 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.

   <p>There are five language categories used for all supported languages:
<em>package</em>, <em>subprogram</em>, <em>type</em>, <em>variable</em>, and
<em>generic</em>.  The icons
corresponding to these language categories are as follows.

     <ul>
<li>The <em>package</em> category's icon is a square.

     <div class="block-image"><img src="square_x.png" alt="square_x.png"></div>

     <li>The <em>subprogram</em> category's icon is a circle.

     <div class="block-image"><img src="circle_x.png" alt="circle_x.png"></div>

     <li>The <em>type</em> category's icon is a triangle.

     <div class="block-image"><img src="triangle_x.png" alt="triangle_x.png"></div>

     <li>The <em>variable</em> category's icon is a dot.

     <div class="block-image"><img src="dot_x.png" alt="dot_x.png"></div>

     <li>The <em>generic</em> category's  icon is a diamond.

     <div class="block-image"><img src="diamond_x.png" alt="diamond_x.png"></div>
</ul>

<p class="noindent">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 &ldquo;S&rdquo; decorator added, denoting a &ldquo;spec&rdquo;.

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

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

   <p>Language constructs are mapped to the categories in a language-specific
manner.  For example, C++ namespaces and Ada packages correspond to the
<em>package</em> category.  C functions and Ada subprograms correspond to the
<em>method</em> category, and so on.  The <em>generic</em> 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 <em>generic</em> category does not correspond to Ada generic
units or C++ templates.)

   <p>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 <em>variable</em> 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.

   <p>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 &ldquo;private&rdquo; compile-time visibility.

<!--  -->
   </body></html>
gnat-gps-doc 5.0-6 / usr / share / doc / gnat-gps / html / The-Project-View.html
