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

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.

5.2 Editing Sources

5.2.1 Key bindings

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.

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.

5.4 Menu Items

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

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.

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.

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.

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.