[ < ] [ > ]   [ << ] [ 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 Contextual Menus for Editing Files  
5.6 Using an External Editor  
5.7 Using the Clipboard  
5.8 Saving Files  
5.9 Remote Files  


[ < ] [ > ]   [ << ] [ 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.

source-editor

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 Speed Column
This column, when visible, is located on the left of the editor. It allows you to view all the highlighted lines in a file, at a glance. For example, all the lines containing compilation errors are displayed in the Speed Column. See 15.1 The Preferences Dialog for information on how to customize the behavior of the Speed Column.

A status bar
Giving information about the file. It is divided in two sections, one on the left and one on the right of the window.

The left section

The first box on the left shows the current subprogram name for languages that support this capability. Currently Ada, C and C++ have this ability. See 15.1 The Preferences Dialog to enable or disable this feature.

The right section

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 current editing mode. This is either Insert or Overwrite and can be changed using the insert keyboard keys by default.

The third 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 fourth 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 fifth 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 Contextual Menus for Source Navigation 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 key manager dialog, See section 15.3 The Key Manager 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 type of information displayed depends on the current state of GPS.

In normal mode, the entity kind and the location of declaration 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. Otherwise, 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 key manager 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.

Current block highlighting
If this preference is enabled, the editor will highlight the current block of code, e.g. the current begin...end block, or loop statement, etc...

The block highlighting will also take into account the changes made in your source code, and will recompute automatically the current block when needed.

This capability is currently implemented for Ada, C and C++ languages.

Block folding
When enabled, the editor will display - icons on the left side, corresponding to the beginning of subprograms. If you click on one of these icons, all the lines corresponding to this subprogram are hidden, except the first one. As for the block highlighting, these icons are recomputed automatically when you modify your sources and are always kept up to date.

This capability is currently implemented for Ada, C and C++ languages.

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 or vi. See section 5.6 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.

In addition, there are several ways to define new key bindings, see 15.4.12 Defining text aliases and 15.4.7 Binding actions to keys.

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.


[ < ] [ > ]   [ << ] [ 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:

open-file

This dialog provides the following areas and capabilities:


[ < ] [ > ]   [ << ] [ 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.

A new view can also be created by keeping the shift key pressed while drag-and-dropping the editor (see 4.7 Moving Windows). This second method is preferred, since you can then specify directly where you want to put the new view. The default when using the menu is that the new view is put on top of the editor itself.

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.

open-from-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.

If you press the down arrow key, the focus will move to the list of completions, so that you can select a file from this list without using the mouse.

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.

This dialog will only show each file once. If you have extended projects in your hierarchy, some files may be redefined in some extending project. In this case, only the files from the extending project are shown, and you cannot have access through this dialog to the overridden files of the extended project. Of course, you can still use the project explorer or the standard File->Open menu to open these files.

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 More
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 window contents, optionally saving it interactively if it has been modified. The Print Command specified in the preferences is used if it is defined. On Unix this command is required; on Windows it is optional.

On Windows, if no command is specified in the preferences the standard Windows print dialog box is displayed. This dialog box allows the user to specify the target printer, the properties of the printer, which pages to print (all, or a specific range of pages), the number of copies to print, and, when more than one copy is specified, whether the pages should be collated. Pressing the Cancel button on the dialog box returns to GPS without printing the window contents; otherwise the specified pages and copies are printed on the selected printer. Each page is printed with a header containing the name of the file (if the window has ever been saved). The page number is printed on the bottom of each page. 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.

Insert File...
Open a file selection dialog and insert the contents of this file in the current source editor, at the current cursor location.

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.

Refill
Refill text on the selection or current line according to the right margin as defined by the column highlight. see section 15.1 The Preferences Dialog.

Fold all blocks
Collapse all the blocks in the current file.

Unfold all blocks
Uncollapse all the blocks in the current file.

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.8 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 framework.

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 test harness. See AUnit documentation for more details.

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

Key shortcuts
Give access to the key manager dialog, to associate commands with special keys. See section 15.3 The Key Manager Dialog.


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

5.5 Contextual Menus for Editing Files

Whenever you ask for a contextual menu (using e.g. the third button on your mouse) on a source file, you will get access to a number of entries, displayed or not depending on the current context.

Menu entries include the following categories:

Source Navigation
See section 6.3 Contextual Menus for Source Navigation.

Edit with external editor
See section 5.6 Using an External Editor.

Dependencies
See section 10.3 Dependency Browser.

Entity browsing
See section 10.4 Entity Browser.

Project explorer
See section 2.5 The Project Explorer.

Version control
See section 12.3 The Version Control Contextual Menu.

Debugger
See section 11.6 Using the Source Editor when Debugging.

Case exceptions
See Handling of case exceptions.


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

5.5.1 Handling of case exceptions

GPS keeps a set of case exceptions that is used by all case insensitive languages. When editing or reformatting a buffer for such a language the case exception dictionary will be checked first. If an exception is found for this word or a substring of the word, it will be used; otherwise the specified casing for keywords or identifiers is used. A substring is defined as a part of the word separated by underscores.

Note that this feature is not activated for entities (keywords or identifiers) for which the casing is set to Unchanged. See see section 15.1 The Preferences Dialog.

A contextual menu named Casing has the following entries:

Lower entity
Set the selected entity in lower case.

Upper entity
Set the selected entity in upper case.

Mixed entity
Set the selected entity in mixed case (set the first letter and letters before an underscore in upper case, all other letters are set to lower case).

Smart Mixed entity
Set the selected entity in smart mixed case. Idem as above except that upper case letters are kept unchanged.

Add exception for entity
Add the current entity into the case exception dictionary.

Remove exception for entity
Remove the current entity from the case exception dictionary.

To add or remove a substring exception into/from the dictionary you need to first select the substring on the editor. In this case the last two contextual menu entries will be:

Add substring exception for str
Add the selected substring into the case substring exception dictionary.

Remove substring exception for str
Remove the selected substring from the case substring exception dictionary.


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

5.6 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 be found in the PATH, and thus is not supported on Windows systems. Under Windows systems, you can use the custom editor instead.

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


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

5.8 Saving Files

After you have finished modifying your files, you need to save them. The basic method to do that is to select the menu File->Save, which saves the currently selected file.

You can also use the menu File->Save As... if you want to save the file with another name, or in another directory.

If you have multiple files to save, another possibility is to use the menu File->Save More->All. This will open a dialog listing all the currently modified editors that need saving. You can then select individually which one should be saved, and click on Save to do the actual saving.

When calling external commands, such as compiling a file, if the Auto save preference is disabled, this same dialog is also used, to make sure that e.g. the compiler will take into account your local changes. If the preference is enabled, the saving is performed automatically.

save-dialog

You can conveniently select or unselect all the files at once by clicking on the title of the first column (labeled Select). This will toggle the selection status of the first line, and have the same status for all other editors.

If you press Cancel instead of Save, no saving will take place, and the action that displayed this dialog is also canceled. Such actions can be for instance starting a compilation command, a VCS operation, or quitting GPS with unsaved files.


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

5.9 Remote Files

GPS has a basic support for working with files on remote hosts. This includes a number of protocols, described below, which allow you to read a file from a remote host, edit it locally, and then save it transparently to the remote machine.

For now, the support for remote files is only available through the GPS shell window. You start editing a remote file by typing a line similar to

 
Editor.edit protocol://user@machine/full/path

where "protocol" should be replaced by the name of the protocol you want to use, "user" is the login name you wish to use on the remote "machine", and "/full/path" is the full path on the remote machine to access the file.

The user name is optional. If it is the same as on the local machine, you can omit the user name as well as the "@" sign.

Likewise, the machine name is optional, if you want to get a file from the local host. This can be used to access files belonging to another user. In this case, you need to specify the "@" sign, but do not insert a machine name right after it.

Remote files can also be used if you want to work with GPS, but the machine on which the files are found isn't supported by GPS.

The following protocols are supported:

ssh
This protocol is based on the ssh command line tool, which must therefore be available in the path. It provides encrypted and secure connections to the remote host. Files are transfered in-line, that is the connection is established the first time you access the remote host, and kept open for all further access.

Although ssh can be setup not to require a password, GPS will automatically detect if a password is asked and open a dialog to query it.

The remote system must be a Unix-like system with support for standard Unix commands like test, echo, rm and ls.

In the sample shell command above, you would replace the word "protocol" with "ssh" to use this protocol.

rsh
This protocol behaves like ssh, except that the connections are not encrypted. However, this protocol is generally available on all Unix machines by default.

It has the same requirements that the ssh protocol. To use it, substitute the word "rsh" to "protocol" in the example above.

telnet
This protocol is based on the standard telnet protocol. It behaves much like the two protocols above, with an unencrypted connection.

To use it, substitute the word "telnet" to "protocol" in the example above.

scp
This protocol is also based on one of the tools of the ssh suite. It provides encrypted connections, and uses a mixture of ssh and scp connections. Various commands like querying the time stamp of a file are executed through a permanent ssh connection, whereas files are downloaded and uploaded through a one-time scp command.

It basically has the same behavior as the ssh protocol, although it might be slightly slower since a new connection has to be established every time a file is fetched from, or written to the remote host. However, it might work better than ssh if the file contains 8 bit characters.

To use it, substitute the word "scp" to "protocol" in the example above.

rsync
Just like scp is based on ssh, this protocol is based on rsh. It depends on the external tool rsync, and uses a mixture of a rsh connection for commands like querying the time stamp of a file, and one-time connections with rsync to transfer the files.

Rsync is specially optimized to transfer only the parts of a file that are different from the one already on the remote host. Therefore, it will generally provide the best performance when writing the file back to the remote host.

If you set up the environment variable RSYNC_RSH to ssh before starting gps, the connection will then be encrypted when transferring the files.

To use this protocol, substitute the word "rsync" to "protocol" in the example above.

ftp
This protocol provides only limited capabilities, but can be used to retrieve or write a file back through an ftp connection, possibly even through an anonymous ftp connection.

To use this protocol, substitute the word "ftp" to "protocol" in the example above.

http
This is the usual http protocol to download documents from the web. It is in particular useful for documentation


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

This document was generated by Mail Server on November, 29 2004 using texi2html