/usr/share/doc/gnat-gps/html/The-Data-Window.html

<html lang="en">
<head>
<title>The Data Window - 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="Debugging.html#Debugging" title="Debugging">
<link rel="prev" href="The-Call-Stack-Window.html#The-Call-Stack-Window" title="The Call Stack Window">
<link rel="next" href="The-Breakpoint-Editor.html#The-Breakpoint-Editor" title="The Breakpoint Editor">
<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-Data-Window"></a>
<p>
Next:&nbsp;<a rel="next" accesskey="n" href="The-Breakpoint-Editor.html#The-Breakpoint-Editor">The Breakpoint Editor</a>,
Previous:&nbsp;<a rel="previous" accesskey="p" href="The-Call-Stack-Window.html#The-Call-Stack-Window">The Call Stack Window</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="Debugging.html#Debugging">Debugging</a>
<hr>
</div>

<h3 class="section">11.3 The Data Window</h3>

<p><a name="index-data-500"></a><a name="index-data-window-501"></a><!--  -->

<!--  -->
<h4 class="subsection">11.3.1 Description</h4>

<!--  -->
<p class="noindent">The Data Window is the area in which various information about the debugged
process can be displayed. This includes the value of selected variables, the
current contents of the registeres, the local variables, <small class="dots">...</small>

   <p><a name="index-Data-Window-502"></a>This window is not open by default when you start the debugger. It will be
created automatically when needed (e.g. when using the Debug constextual menu
to display a variable). You can also force its display through the menu
<code>Debug-&gt;Data-&gt;Data Window</code>.

   <p>However, if you save the desktop through the menu
<code>File-&gt;Save More-&gt;Desktop</code> while the data window is open, it will be
automatically reopen the next time the desktop is loaded, for instance when
restarting GPS.

   <p>The contents of the data window is preserved by default whenever you close it. 
Thus, if you reopen the data window either during the same debugger session,
or automatically when you start a debugger on the same executable, it will
display the same items again. This behavior is controlled by the
<code>Preserve State on Exit</code> preference.

   <p><a name="index-menu-503"></a><a name="index-contextual-menu-504"></a>   The data window contains all the graphic boxes that can be accessed
   using the <i>Data-&gt;Display</i> menu items, or the data window
   <i>Display Expression...</i> contextual menu, or the source window
   <i>Display</i> contextual menu items, or finally the
   <i>graph</i> command in the debugger console.

   <p>For each of these commands, a box is displayed in the data window
   with the following information:

   <p><a name="index-screen-shot-505"></a><img src="canvas.jpg" alt="canvas.jpg">

     <ul>
   <li>A title bar containing:
<a name="index-title-bar-506"></a>
          <ul>
     <li>The number of this expression: this is a positive number starting
       from 1 and incremented for each new box displayed. It represents the
       internal identifier of the box.

          <li>The name of the expression: this is the expression or variable
       specified when creating the box.

          <li>An icon representing either a flash light, or a lock. 
<a name="index-icon-507"></a>       This is a click-able icon that will change the state of the box from
       automatically updated (the flash light icon) to frozen (the lock
       icon). 
       When frozen, the value is grayed, and will not change until you change
       the state. When updated, the value of the box will be recomputed each
       time an execution command is sent to the debugger (e.g step, next).

          <li>An icon representing an 'X'. 
<a name="index-icon-508"></a>       You can click on this icon to close/delete any box. 
     </ul>

     <li>A main area. 
     The main area will display the data value hierarchically
     in a language-sensitive manner. The canvas knows about data structures
     of various languages (e.g <code>C</code>, <code>Ada</code>, <code>C++</code>) and will
     organize them accordingly. 
     For example, each field of a record/struct/class, or each item of an
     array will be displayed separately. For each subcomponent, a thin box
     is displayed to distinguish it from the other components. 
   </ul>

   <p><a name="index-contextual-menu-509"></a>   A contextual menu, that takes into account the current component selected
   by the mouse, gives access to the following capabilities:
     <dl>
     <dt><b>Close </b><i>component</i><dd>Closes the selected item.

     <br><dt><b>Hide all </b><i>component</i><dd><a name="index-hide-510"></a>Hides all subcomponents of the selected item. To select a particular field
or item in a record/array, move your mouse over the name of this
component, not over the box containing the values for this item.

     <br><dt><b>Show all </b><i>component</i><dd><a name="index-show-511"></a>Shows all subcomponents of the selected item.

     <br><dt><b>Clone </b><i>component</i><dd><a name="index-clone-512"></a>Clones the selected component into a new, independent item.

     <br><dt><b>View memory at address of </b><i>component</i><dd><a name="index-memory-view-513"></a>Brings up the memory view dialog and explore memory at the address of the
component.

     <br><dt><b>Set value of </b><i>component</i><dd>Sets the value of a selected component. This will open an entry box
where you can enter the new value of a variable/component. Note that
GDB does not perform any type or range checking on the value entered.

     <br><dt><b>Update Value</b><dd><a name="index-update-value-514"></a>Refreshes the value displayed in the selected item.

     <br><dt><b>Show Value</b><dd><a name="index-show-value-515"></a>Shows only the value of the item.

     <br><dt><b>Show Type</b><dd><a name="index-show-type-516"></a>Shows only the type of each field for the item.

     <br><dt><b>Show Value+Type</b><dd>Shows both the value and the type of the item.

     <!-- ??? Should have screen shot with value + type -->
     <br><dt><b>Auto refresh</b><dd><a name="index-auto-refresh-517"></a>Enables or disables the automatic refreshing of the item upon program execution
(e.g step, next).

   </dl>

   <p><a name="index-contextual-menu-518"></a>   A contextual menu can be accessed in the canvas itself (point the mouse to
   an empty area in the canvas, and click on the right mouse button) with the
   following entries:
     <dl>
     <dt><b>Display Expression...</b><dd><a name="index-display-expression-519"></a>      Open a small dialog letting you specify an arbitrary expression
      in the Data Window. This expression can be a variable name, or a
      more complex expression, following the syntax of the current language and
      underlying debugger. 
      See the documentation of e.g gdb for more details on the syntax. 
      The check button <i>Expression is a subprogram call</i> should be enabled
      if the expression is actually not an expression but rather a debugger
      command (e.g <code>p/x var</code>) or a procedure call in the program being
      debugged (e.g <code>call my_proc</code>).

     <br><dt><b>Align On Grid</b><dd><a name="index-align-520"></a>Enables or disables alignment of items on the grid.

     <br><dt><b>Detect Aliases</b><dd><a name="index-aliases-521"></a>Enables or disables the automatic detection of shared data structures. 
Each time you display an item or dereference a pointer, all
the items already displayed on the canvas are considered and their addresses
are compared with the address of the new item to display. If they match,
(for example if you tried to dereference a pointer to an object already
displayed) instead of creating a new item a link will be displayed.

     <br><dt><b>Zoom in</b><dd><a name="index-zoom-in-522"></a>Redisplays the items in the data window with a bigger font

     <br><dt><b>Zoom out</b><dd><a name="index-zoom-out-523"></a>Displays the items in the data window with smaller fonts and pixmaps. This
can be used when you have several items in the window and you can't see all
of them at the same time (for instance if you are displaying a tree and
want to clearly see its structure).

     <br><dt><b>Zoom</b><dd><a name="index-zoom-524"></a>Allows you to choose the zoom level directly from a menu.

     <br><dt><b>Clear</b><dd><a name="index-clear-525"></a>When this item is selected, all the boxes currently displayed are removed.

   </dl>

<!--  -->
<h4 class="subsection">11.3.2 Manipulating items</h4>

<!--  -->
<h5 class="subsubsection">11.3.2.1 Moving items</h5>

<p class="noindent">All the items on the canvas have some common behavior and can be fully
manipulated with the mouse. 
They can be moved freely anywhere on the canvas, simply by clicking on
them and then dragging the mouse. Note that if you are trying to move
an item outside of the visible area of the data window, the latter will
be scrolled so as to make the new position visible.

   <p>Automatic scrolling is also provided if you move the mouse while dragging
an item near the borders of the data window. As long as the mouse
remains close to the border and the button is pressed on the item,
the data window is scrolled and the item is moved. This provides an
easy way to move an item a long distance from its initial position.

<h5 class="subsubsection">11.3.2.2 Colors</h5>

<p class="noindent">Most of the items are displayed using several colors, each
conveying a special meaning. Here is the meaning assigned to all colors
(note that the exact color can be changed through the preferences
dialog; these are the default colors):

   <p><a name="index-screen-shot-526"></a><img src="colors.jpg" alt="colors.jpg">

     <dl>
<dt><b>black</b><dd>This is the default color used to print the value of variables or
expressions.

     <br><dt><b>blue</b><dd><a name="index-C-527"></a><a name="index-Ada-528"></a>This color is used for C pointers (or Ada access values), i.e. all the variables
and fields that are memory addresses that denote some other value in
memory.

     <p>You can easily dereference these (that is to say see the value pointed to)
by double-clicking on the blue text itself.

     <br><dt><b>red</b><dd>This color is used for variables and fields whose value has changed since
the data window was last displayed. For instance, if you display an array
in the data window and then select the <i>Next</i> button in the tool bar, then
the elements of the array whose value has just changed will appear in red.

     <p><a name="index-menu-529"></a>As another example, if you choose to display the value of local variables in
the data window (<i>Display-&gt;Display Local Variables</i>), then only the
variables whose value has changed are highlighted, the others are left in
black.

   </dl>

<h5 class="subsubsection">11.3.2.3 Icons</h5>

<p><a name="index-icon-530"></a>Several different icons can be used in the display of items. They also
convey special meanings.

     <dl>
<dt><b>trash bin icon</b><dd>This icon indicates that the debugger could not get the value of the
variable or expression. There might be several reasons, for instance the
variable is currently not in scope (and thus does not exist), or it might
have been optimized away by the compiler. In all cases, the display will be
updated as soon as the variable becomes visible again.

     <br><dt><b>package icon</b><dd>This icon indicates that part of a complex structure is currently hidden. 
Manipulating huge items in the data window (for instance if the variable
is an array of hundreds of complex elements) might not be very helpful. As a
result, you can shrink part of the value to save some screen space and make it
easier to visualize the interesting parts of these variables.

     <p>Double-clicking on this icon will expand the hidden part, and clicking on
any sub-rectangle in the display of the variable will hide that part and
replace it with that icon.

     <p>See also the description of the contextual menu to automatically show or hide
all the contents of an item. Note also that one alternative to hiding
subcomponents is to clone them in a separate item (see the contextual menu
again).

   </dl>

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