KDevelop4/Manual/Working with source code: Difference between revisions

From KDE Wiki Sandbox
m (Fix formatting, add category)
Line 1: Line 1:
== Working with source code ==
== Working with source code ==


Besides debugging, reading through and writing source code is what you will spend the most time with when developing software. To this end, KDevelop offers you many many different ways to explore source codes and to make writing it more productive. As discussed in more detail in the following sections, KDevelop is not just a source editor — rather, it is a source management system that gives you different views of extracted information on the files that collectively make up your session's source code.
Besides debugging, reading through and writing source code is what you will spend the most time with when developing software. To this end, '''KDevelop''' offers you many many different ways to explore source codes and to make writing it more productive. As discussed in more detail in the following sections, '''KDevelop''' is not just a source editor — rather, it is a source management system that gives you different views of extracted information on the files that collectively make up your session's source code.


=== Tools and views ===
=== Tools and views ===
Line 7: Line 7:
[[Image:kdevelop-7.png|thumb|500px|right]]
[[Image:kdevelop-7.png|thumb|500px|right]]


In order to work with projects, KDevelop has the concept of '''tools'''. A tool
In order to work with projects, '''KDevelop''' has the concept of '''tools'''. A tool
provides a particular view of the source, or an action that can be taken with
provides a particular view of the source, or an action that can be taken with
it. Tools are represented by buttons around the perimeter of your window (in
it. Tools are represented by buttons around the perimeter of your window (in
Line 14: Line 14:
main window; if you click on the tool button again, the subwindow disappears
main window; if you click on the tool button again, the subwindow disappears
again.  
again.  
{{Note|1=To make a subwindow disappear, you can also click at the "x" at the top right of the subwindow; however, at least with KDevelop 4.2.x, this also removes the button representing the tool from the perimeter, which was your way of getting the subwindow back. See below for how to get the button back onto the perimeter in the same way as getting any tool's button there. This behavior has been reported as [http://bugs.kde.org/show_bug.cgi?id=270018 bug 270018])}}  
{{Note|1=To make a subwindow disappear, you can also click at the "x" at the top right of the subwindow; however, at least with '''KDevelop''' 4.2.x, this also removes the button representing the tool from the perimeter, which was your way of getting the subwindow back. See below for how to get the button back onto the perimeter in the same way as getting any tool's button there. This behavior has been reported as [http://bugs.kde.org/show_bug.cgi?id=270018 bug 270018])}}  
The picture above shows a particular selection of tools, aligned on the left and right margins; in the picture, the "Classes" tool is open on the left and the "Snippets" tool on the right, along with an editor for a source file in the middle. In practice, most of the time you will probably only have the editor and maybe the "Classes" or "Code Browser" tool open at the left. Other tool view will likely only be open temporarily as you use the tool, leaving more space for the editor most of the time.
The picture above shows a particular selection of tools, aligned on the left and right margins; in the picture, the "Classes" tool is open on the left and the "Snippets" tool on the right, along with an editor for a source file in the middle. In practice, most of the time you will probably only have the editor and maybe the "Classes" or "Code Browser" tool open at the left. Other tool view will likely only be open temporarily as you use the tool, leaving more space for the editor most of the time.


When you run KDevelop the first time, you should already have the "Projects"
When you run '''KDevelop''' the first time, you should already have the "Projects"
tool button. Click on it: it will open a subwindow that shows the projects you
tool button. Click on it: it will open a subwindow that shows the projects you
have added to the session at the bottom, and a file system view of the
have added to the session at the bottom, and a file system view of the
directories of your projects at the top.
directories of your projects at the top.


There are many other tools you can use with KDevelop, not all of which are
There are many other tools you can use with '''KDevelop''', not all of which are
initially present as buttons on the perimeter. To add some, go to the <menuchoice>Windows
initially present as buttons on the perimeter. To add some, go to the <menuchoice>Windows -> Add tool view</menuchoice> menu entry. Here are some that you will likely find useful (a complete discussion of all tools can be found elsewhere in this manual):
> Add tool view</menuchoice> menu entry. Here are some that you will likely find useful (a complete discussion of all tools can be found elsewhere in this manual):


* '''Classes''': A complete list of all classes that are defined in one of the projects or your session with all of their member functions and variables. Clicking on any of the members opens a source editor window at the location of the item you clicked on.
* '''Classes''': A complete list of all classes that are defined in one of the projects or your session with all of their member functions and variables. Clicking on any of the members opens a source editor window at the location of the item you clicked on.
Line 32: Line 31:
* '''Documentation''': Allows you to search for man pages and other help documents.
* '''Documentation''': Allows you to search for man pages and other help documents.
* '''Snippets''': This provides sequences of text that one uses over an over and doesn't want to write every time. For example, in the project from which the picture above was created, there is a frequent need to write code like <code>for (typename Triangulation&lt;dim&gt;::active_cell_iterator cell = triangulation.begin_active(); cell != triangulation.end(); ++cell)</code>. This is an awkward expression but it will look almost exactly like this everytime you need such a loop &mdash; which would make it a good candidate for a snippet.
* '''Snippets''': This provides sequences of text that one uses over an over and doesn't want to write every time. For example, in the project from which the picture above was created, there is a frequent need to write code like <code>for (typename Triangulation&lt;dim&gt;::active_cell_iterator cell = triangulation.begin_active(); cell != triangulation.end(); ++cell)</code>. This is an awkward expression but it will look almost exactly like this everytime you need such a loop &mdash; which would make it a good candidate for a snippet.
* '''Konsole''': Opens a command line window inside KDevelop's main window, for the occasional command you may want to enter (e.g. to run <code>./configure</code>).
* '''Konsole''': Opens a command line window inside '''KDevelop's''' main window, for the occasional command you may want to enter (e.g. to run <code>./configure</code>).


For many programmers, vertical screen space is the most important. To this end, you can arrange your
For many programmers, vertical screen space is the most important. To this end, you can arrange your
Line 40: Line 39:


[[Image:kdevelop4_noworkingset.png|thumb|300px|right]]
[[Image:kdevelop4_noworkingset.png|thumb|300px|right]]
If you've gotten this far, take a look at the upper right of the KDevelop main window: As shown in the picture, you will see that there are three '''modes''' KDevelop can be in: '''Code''' (the mode we discuss in the current chapter on working with source code), '''Debug''' (see [[KDevelop4/Manual/Debugging programs|Debugging programs]]) and '''Review''' (see [[KDevelop4/Manual/Working with version control systems|Working with version control systems]]).  
If you've gotten this far, take a look at the upper right of the '''KDevelop''' main window: As shown in the picture, you will see that there are three '''modes''' '''KDevelop''' can be in: <menuchoice>Code</menuchoice> (the mode we discuss in the current chapter on working with source code), <menuchoice>Debug</menuchoice> (see [[Special:myLanguage/KDevelop4/Manual/Debugging programs|Debugging programs]]) and <menuchoice>Review</menuchoice> (see [[Special:myLanguage/KDevelop4/Manual/Working with version control systems|Working with version control systems]]).  


[[image:kdevelop4_sessionsprojectsworkingsets.png|thumb|250px|right]]
[[image:kdevelop4_sessionsprojectsworkingsets.png|thumb|250px|right]]
Each mode has its own set of tools that are stacked around the perimeter, and each mode also has a '''working set''' of currently open files. Furthermore, each such working set is associated with a current session, i.e. we have the relationship shown at the right. Note that the files in the working set come from the same session, but they may come from different projects that are part of the same session.
Each mode has its own set of tools that are stacked around the perimeter, and each mode also has a '''working set''' of currently open files. Furthermore, each such working set is associated with a current session, i.e. we have the relationship shown at the right. Note that the files in the working set come from the same session, but they may come from different projects that are part of the same session.


If you open KDevelop the first time, the working set is empty &mdash; there are no open files. But as you open files for
If you open '''KDevelop''' the first time, the working set is empty &mdash; there are no open files. But as you open files for
editing (or debugging, or reviewing in the other modes) your working set grows. The fact that your working set is non-empty is indicated by a symbol in the tab, as shown on the right. You will notice that whenever you close KDevelop and later start it again, the working set is saved and restored, i.e. you get the same set of open files.
editing (or debugging, or reviewing in the other modes) your working set grows. The fact that your working set is non-empty is indicated by a symbol in the tab, as shown on the right. You will notice that whenever you close '''KDevelop''' and later start it again, the working set is saved and restored, i.e. you get the same set of open files.


[[Image:kdevelop4_workingsettooltip.png|thumb|300px|right]]
[[Image:kdevelop4_workingsettooltip.png|thumb|300px|right]]
Line 54: Line 53:
=== Some useful keyboard shortcuts ===
=== Some useful keyboard shortcuts ===


KDevelop's editor follows the standard keyboard shortcuts for all usual editing operations. However, it also supports a number of more advanced operations when editing source code, some of which are bound to particular key combinations. The following are frequently particularly helpful:
'''KDevelop's''' editor follows the standard keyboard shortcuts for all usual editing operations. However, it also supports a number of more advanced operations when editing source code, some of which are bound to particular key combinations. The following are frequently particularly helpful:


{| border="1" cellspacing="0"
{| border="1" cellspacing="0"
!colspan="2"  style="background-color:#ffff99;" | Jumping around in code
!colspan="2"  style="background-color:#ffff99;" | Jumping around in code
|-
|-
|      Ctrl-Alt-O
|      <keycap>Ctrl+Alt+O</keycap>
| Quick open file: enter part of a filename and select among all the files in the current session's projects' directory trees that match the string; the file will then be opened
| Quick open file: enter part of a filename and select among all the files in the current session's projects' directory trees that match the string; the file will then be opened
|-
|-
|      Ctrl-Alt-C
|      <keycap>Ctrl+Alt+C</keycap>
| Quick open class: enter part of a class name and select among all class names that match; the cursor will then jump to the class declaration
| Quick open class: enter part of a class name and select among all class names that match; the cursor will then jump to the class declaration
|-
|-
|      Ctrl-Alt-M
|      <keycap>Ctrl+Alt+M</keycap>
| Quick open function: enter part of a (member) function name and select among all names that match; note that the list shows both declarations and definitions and the cursor will then jump to the selected item
| Quick open function: enter part of a (member) function name and select among all names that match; note that the list shows both declarations and definitions and the cursor will then jump to the selected item
|-
|-
|      Ctrl-Alt-Q
|      <keycap>Ctrl+Alt+Q</keycap>
| Universal quick open: type anything (file name, class name, function name) and get a list of anything that matches to select from
| Universal quick open: type anything (file name, class name, function name) and get a list of anything that matches to select from
|-
|-
| Ctrl-Alt-N
| <keycap>Ctrl+Alt+N</keycap>
|Outline: Provide a list of all things that are happening in this file, e.g. class declarations and function definitions
|Outline: Provide a list of all things that are happening in this file, e.g. class declarations and function definitions
|-
|-
| Ctrl-,
| <keycap>Ctrl+,</keycap>
|Jump to definition of a function if the cursor is currently on a function declaration
|Jump to definition of a function if the cursor is currently on a function declaration
|-
|-
| Ctrl-.
| <keycap>Ctrl+.</keycap>
|Jump to declaration of a function or variable if the cursor is currently in a function definition
|Jump to declaration of a function or variable if the cursor is currently in a function definition
|-
|-
| Ctrl-Alt-PageDown
| <keycap>Ctrl+Alt+PageDown</keycap>
|Jump to next function
|Jump to next function
|-
|-
| Ctrl-Alt-PageUp
| <keycap>Ctrl+Alt+PageUp</keycap>
|Jump to previous function
|Jump to previous function
|-
|-
| Ctrl-G
| <keycap>Ctrl+G</keycap>
|Goto line
|Goto line
|-
|-
!colspan="2"  style="background-color:#ffff99;" | Searching and replacing
!colspan="2"  style="background-color:#ffff99;" | Searching and replacing
|-
|-
| Ctrl-F
| <keycap>Ctrl+F</keycap>
|Find
|Find
|-
|-
| F3
| <keycap>F3</keycap>
|Find next
|Find next
|-
|-
| Ctrl-R
| <keycap>Ctrl+R</keycap>
|Replace
|Replace
|-
|-
| Ctrl-Alt-F
| <keycap>Ctrl+Alt+F</keycap>
|Find-Replace in multiple files
|Find-Replace in multiple files
|-
|-
!colspan="2"  style="background-color:#ffff99;" | Other things
!colspan="2"  style="background-color:#ffff99;" | Other things
|-
|-
| Ctrl-_
| <keycap>Ctrl+_</keycap>
|Collapse one level: remove this block from view, for example if you want to focus on the bigger picture within a function
|Collapse one level: remove this block from view, for example if you want to focus on the bigger picture within a function
|-
|-
| Ctrl-+
| <keycap>Ctrl++</keycap>
|Expand one level: undo the collapsing
|Expand one level: undo the collapsing
|-
|-
| Ctrl-D
| <keycap>Ctrl+D</keycap>
|Comment out selected text or current line
|Comment out selected text or current line
|-
|-
| Ctrl-Shift-D
| <keycap>Ctrl+Shift-D</keycap>
|Comment in selected text or current line
|Comment in selected text or current line
|-
|-
| Alt-Shift-D     
| <keycap>Alt-Shift-D</keycap>      
|Document the current function. If the cursor is on a function or class declaration then hitting this key will create a doxygen-style comment pre-populated with a listing of all parameters, return values, etc.
|Document the current function. If the cursor is on a function or class declaration then hitting this key will create a doxygen-style comment pre-populated with a listing of all parameters, return values, etc.
|-
|-
| Ctrl-T
| <keycap>Ctrl+T</keycap>
|Transpose the current and the previous character
|Transpose the current and the previous character
|-
|-
| Ctrl-K
| <keycap>Ctrl+K</keycap>
|Delete the current line (note: this is not just emacs' "delete from here to the end of the line")
|Delete the current line (note: this is not just emacs' "delete from here to the end of the line")
|}
|}
[[Category:Development]]

Revision as of 17:30, 17 May 2011

Working with source code

Besides debugging, reading through and writing source code is what you will spend the most time with when developing software. To this end, KDevelop offers you many many different ways to explore source codes and to make writing it more productive. As discussed in more detail in the following sections, KDevelop is not just a source editor — rather, it is a source management system that gives you different views of extracted information on the files that collectively make up your session's source code.

Tools and views

In order to work with projects, KDevelop has the concept of tools. A tool provides a particular view of the source, or an action that can be taken with it. Tools are represented by buttons around the perimeter of your window (in vertical text along the left and right margins, or horizontally along the bottom margin). If you click on them, they expand to a subwindow — a view — within the main window; if you click on the tool button again, the subwindow disappears again.

Note
To make a subwindow disappear, you can also click at the "x" at the top right of the subwindow; however, at least with KDevelop 4.2.x, this also removes the button representing the tool from the perimeter, which was your way of getting the subwindow back. See below for how to get the button back onto the perimeter in the same way as getting any tool's button there. This behavior has been reported as bug 270018)

The picture above shows a particular selection of tools, aligned on the left and right margins; in the picture, the "Classes" tool is open on the left and the "Snippets" tool on the right, along with an editor for a source file in the middle. In practice, most of the time you will probably only have the editor and maybe the "Classes" or "Code Browser" tool open at the left. Other tool view will likely only be open temporarily as you use the tool, leaving more space for the editor most of the time.

When you run KDevelop the first time, you should already have the "Projects" tool button. Click on it: it will open a subwindow that shows the projects you have added to the session at the bottom, and a file system view of the directories of your projects at the top.

There are many other tools you can use with KDevelop, not all of which are initially present as buttons on the perimeter. To add some, go to the Windows -> Add tool view menu entry. Here are some that you will likely find useful (a complete discussion of all tools can be found elsewhere in this manual):

  • Classes: A complete list of all classes that are defined in one of the projects or your session with all of their member functions and variables. Clicking on any of the members opens a source editor window at the location of the item you clicked on.
  • Documents: Lists some of the more recently visited files, by kind (e.g. source files, patch files, plain text documents).
  • Code Browser: Depending on your cursor position in a file, this tool shows things that are related. For example, if you are on an #include line, it shows information about the file you are including such as what classes are declared in that file; if you are on an empty line at file scope, it shows the classes and functions declared and defined in the current file (all as links: clicking on them brings you to the point in the file where the declaration or definition actually is); if you are in a function definition, it shows where the declaration is and offers a list of places where the function is used.
  • File system: Shows you a tree view of the file system.
  • Documentation: Allows you to search for man pages and other help documents.
  • Snippets: This provides sequences of text that one uses over an over and doesn't want to write every time. For example, in the project from which the picture above was created, there is a frequent need to write code like for (typename Triangulation<dim>::active_cell_iterator cell = triangulation.begin_active(); cell != triangulation.end(); ++cell). This is an awkward expression but it will look almost exactly like this everytime you need such a loop — which would make it a good candidate for a snippet.
  • Konsole: Opens a command line window inside KDevelop's main window, for the occasional command you may want to enter (e.g. to run ./configure).

For many programmers, vertical screen space is the most important. To this end, you can arrange your tool views at the left and right margin of the window: to move a tool, click on its symbol with the right mouse button and select a new position for it.

Modes and working sets

If you've gotten this far, take a look at the upper right of the KDevelop main window: As shown in the picture, you will see that there are three modes KDevelop can be in: Code (the mode we discuss in the current chapter on working with source code), Debug (see Debugging programs) and Review (see Working with version control systems).

Each mode has its own set of tools that are stacked around the perimeter, and each mode also has a working set of currently open files. Furthermore, each such working set is associated with a current session, i.e. we have the relationship shown at the right. Note that the files in the working set come from the same session, but they may come from different projects that are part of the same session.

If you open KDevelop the first time, the working set is empty — there are no open files. But as you open files for editing (or debugging, or reviewing in the other modes) your working set grows. The fact that your working set is non-empty is indicated by a symbol in the tab, as shown on the right. You will notice that whenever you close KDevelop and later start it again, the working set is saved and restored, i.e. you get the same set of open files.

If you hover your mouse over the symbol for the working set, you get a tooltip that allows you to close the entire working set at once (i.e. to close all currently open files), or to add certain documents (i.e. to open them in a tab of their own).

Some useful keyboard shortcuts

KDevelop's editor follows the standard keyboard shortcuts for all usual editing operations. However, it also supports a number of more advanced operations when editing source code, some of which are bound to particular key combinations. The following are frequently particularly helpful:

Jumping around in code
Ctrl+Alt+O Quick open file: enter part of a filename and select among all the files in the current session's projects' directory trees that match the string; the file will then be opened
Ctrl+Alt+C Quick open class: enter part of a class name and select among all class names that match; the cursor will then jump to the class declaration
Ctrl+Alt+M Quick open function: enter part of a (member) function name and select among all names that match; note that the list shows both declarations and definitions and the cursor will then jump to the selected item
Ctrl+Alt+Q Universal quick open: type anything (file name, class name, function name) and get a list of anything that matches to select from
Ctrl+Alt+N Outline: Provide a list of all things that are happening in this file, e.g. class declarations and function definitions
Ctrl+, Jump to definition of a function if the cursor is currently on a function declaration
Ctrl+. Jump to declaration of a function or variable if the cursor is currently in a function definition
Ctrl+Alt+PageDown Jump to next function
Ctrl+Alt+PageUp Jump to previous function
Ctrl+G Goto line
Searching and replacing
Ctrl+F Find
F3 Find next
Ctrl+R Replace
Ctrl+Alt+F Find-Replace in multiple files
Other things
Ctrl+_ Collapse one level: remove this block from view, for example if you want to focus on the bigger picture within a function
Ctrl++ Expand one level: undo the collapsing
Ctrl+D Comment out selected text or current line
Ctrl+Shift-D Comment in selected text or current line
Alt-Shift-D Document the current function. If the cursor is on a function or class declaration then hitting this key will create a doxygen-style comment pre-populated with a listing of all parameters, return values, etc.
Ctrl+T Transpose the current and the previous character
Ctrl+K Delete the current line (note: this is not just emacs' "delete from here to the end of the line")