Using the GNAT Programming System: Editing Files

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 5. Editing Files

> 5.1 General Information |  |
> 5.2 Editing Sources |  |
> 5.3 The File Selector |  |
> 5.4 Menu Items |  |
> 5.5 Using an External Editor |  |
> 5.6 Using the Clipboard |  |

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 5.1 General Information

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

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

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

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

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

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

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

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

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

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

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

  Saved
    The file has been saved and not modified since.

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

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

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

Automatic indentation
  When enabled, lines are automatically indented each time you press the `Enter` key, or by pressing the indentation key. The indentation key is `Ctrl-Tab` by default, and can be changed in the preferences dialog, See section 15.1 The Preferences Dialog.

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

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

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

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

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

  You can disable the automatic pop up of tool tips in the Editor section of the preferences dialog. See section 15.1 The Preferences Dialog.

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

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

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

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

Current line highlighting
  You can configure the editor to highlight the current line with a certain color. See section 15.1 The Preferences Dialog.
Auto save
  You can configure the editor to periodically save modified files. See autosave delay for a full description of this capability.

GPS also integrates with existing third party editors such as `Emacs`. See section 5.5 Using an External Editor.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 5.2 Editing Sources

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 5.2.1 Key bindings

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

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

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

Common key bindings

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

  `Ctrl-x / Shift-delete`
    Cut to clipboard

  `Ctrl-c / Ctrl-insert`
    Copy to clipboard

  `Ctrl-v / Shift-insert`
    Paste from clipboard

  `Ctrl-s`
    Save file to disk

  `Ctrl-z`
    Undo previous insertion/deletion

  `Ctrl-r`
    Redo previous insertion/deletion

  `Insert`
    Toggle overwrite mode

  `Ctrl-a`
    Select the whole file

  `Home / Ctrl-Pgup`
    Go to the beginning of the line

  `End / Ctrl-Pgdown`
    Go to the end of the line

  `Ctrl-Home`
    Go to the beginning of the file

  `Ctrl-End`
    Go to the end of the file

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

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

  `Ctrl-delete`
    Delete end of the current word.

  `Ctrl-backspace`
    Delete beginning of the current word.

Emacs key bindings
  The following key bindings are activated if you select the Emacs key theme in the preferences dialog (See section 15.1 The Preferences Dialog.), and may override common keys (e.g. `Ctrl-a`).

  `Ctrl-b`
    Move the cursor one character on the left

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

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

  `Ctrl-a`
    Go to the beginning of the line

  `Ctrl-e`
    Go to the end of the line

  `Ctrl-d`
    Delete the next character

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

  `Alt-\`
    Delete all space characters around the cursor.

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

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

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

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

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

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 5.3 The File Selector

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

This dialog provides the following areas and capabilities:

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

  left arrow
    go back in the list of directories visited

  right arrow
    go forward

  up arrow
    go to parent directory

  refresh
    refresh the contents of the directory

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

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

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

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

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

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

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 5.4 Menu Items

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 5.4.1 The File Menu

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

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

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

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

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

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

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

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

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

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

Save
  Save the current source editor if needed.

Save As...
  Same current file under a different name, using the file selector dialog. See section 5.3 The File Selector.

Save...
  Give access to extra save capabilities.

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

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

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

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

Messages
  This sub menu gives access to functionalities related to the Messages window. See section 2.6 The Messages Window.

  Clear
    Clear the contents of the Messages window.

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

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

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

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

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 5.4.2 The Edit Menu

Undo
  Undo previous insertion/deletion in the current editor.

Redo
  Redo previous insertion/deletion in the current editor.

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

Copy
  Copy the current selection to the clipboard.

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

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

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

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

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

Pretty Print
  Pretty print the current source editor by calling the external tool `gnatpp`. It is possible to specify `gnatpp` switches in the switch editor. See section 7.7 The Switches Editor.

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

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

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

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

Preferences
  Give access to the preferences dialog. See section 15.1 The Preferences Dialog.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 5.5 Using an External Editor

GPS is fully integrated with a number of external editors, in particular `Emacs` and `vi`. The choice of the default external editor is done in the preferences. See section 15.1 The Preferences Dialog. The following values are recognized:

`gnuclient`
  This is the recommended client. It is based on Emacs, but needs an extra package to be installed. This is the only client that provides a full integration in GPS, since any extended lisp command can be sent to the Emacs server.

  By default, gnuclient will open a new Emacs frame for every file that is opened. You might want to add the following code to your ``.emacs'` file (create one if needed) so that the same Emacs frame is reused every time:

         (setq gnuserv-frame (car (frame-list)))

  See http://www.hpl.hp.co.uk/people/ange/gnuserv/ for more information.

`emacsclient`
  This is a program that is always available if you have installed Emacs. As opposed to starting a new Emacs every time, it will reuse an existing Emacs session. It is then extremely fast to open a file.

`emacs`
  This client will start a new Emacs session every time a file needs to be opened. You should use `emacsclient` instead, since it is much faster, and makes it easier to copy and paste between multiple files. Basically, the only reason to use this external editor is if your system doesn't support `emacsclient`.

`vim`
  `Vim` is a vi-like editor that provides a number of enhancements, for instance syntax highlighting for all the languages supported by GPS. Selecting this external editor will start an xterm (or command window, depending on your system) with a running vim process editing the file.

  Note that one limitation of this editor is that if GPS needs to open the same file a second time, it will open a new editor, instead of reusing the existing one.

  To enable this capability, the xterm executable must found in the PATH, and thus is not currently supported on Windows systems.

`vi`
  This editor works exactly like vim, but uses the standard `vi` command instead of `vim`.

`custom`
  You can specify any external editor by choosing this item. The full command line used to call the editor can be specified in the preferences (see custom editor command).

`none`
  No external editor is used, and the contextual menus simply won't appear.

In the cases that require an Emacs server, GPS will try several solutions if no already running server was found. It will first try to spawn the glide environment distributed with GNAT. If not found in the PATH, it will then start a standard Emacs. The project file currently used in GPS will be set appropriately the first time Emacs is spawned. This means that if you load a new project in GPS, or modify the paths of the current project, you should kill any running Emacs, so that a new one is spawned by GPS with the appropriate project.

Alternatively, you can reload explicitly the project from Emacs itself by using the menu `Project->Load`

In the preferences, there are three settings that allow you to select the external editor (if left to an empty string, GPS will automatically select the first editor available on your system), to specify the custom editor command, in case you've selector this item, and whether this editor should always be used every time you double-click on a file, or whether you need to explicitly select the contextual menu to open the external editor.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 5.6 Using the Clipboard

This section concerns X-Window users who are used to cutting and pasting with the middle mouse button. In the GPS text editor, as in many recent X applications, the GPS clipboard is set by explicit cut/copy/paste actions, either through menu items or keyboard shortcuts, and the primary clipboard (i.e. the "middle button" clipboard) is set by the current selection.

Therefore, copy/paste between GPS and other X applications using the primary clipboard will still work, provided that there is some text currently selected. The GPS clipboard, when set, will override the primary clipboard.

See http://www.freedesktop.org/standards/clipboards.txt for more information.

[ << ] | [ >> ] |  |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated by Mail Server on June, 15 2003 using texi2html