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

    From KDE UserBase Wiki
    (Created page with "Category:Entwicklung/de")
    (Updating to match new version of source page)
    (7 intermediate revisions by the same user not shown)
    Line 11: Line 11:
    Um mit Projekte zu arbeiten besitzt '''KDevelop''' das Konzept der ''Werkzeuge''. Ein Werkzeug bietet eine bestimmte ''Ansicht'' auf den Quelltext, oder eine Aktion die damit durchgeführt werden kann. Werkzeuge werden durch einen Button am Rand des Fensters repräsentiert (in vertikalem Text auf dem linken und rechtenRand, oder horizontal am unteren Rand). Wenn Sie darauf klicken, expandieren sie in einem Unterfenster eine ''Ansicht'' im Hauptfenster. Wenn Sie auf den Button erneut klicken, verschwendet das Unterfenster wieder.  
    Um mit Projekte zu arbeiten besitzt '''KDevelop''' das Konzept der ''Werkzeuge''. Ein Werkzeug bietet eine bestimmte ''Ansicht'' auf den Quelltext, oder eine Aktion die damit durchgeführt werden kann. Werkzeuge werden durch einen Button am Rand des Fensters repräsentiert (in vertikalem Text auf dem linken und rechtenRand, oder horizontal am unteren Rand). Wenn Sie darauf klicken, expandieren sie in einem Unterfenster eine ''Ansicht'' im Hauptfenster. Wenn Sie auf den Button erneut klicken, verschwendet das Unterfenster wieder.  


    {{Um ein Unterfenster zu verbergen, können Sie auch auf <menuchoice>x</menuchoice> oben rechts im Unterfenster klicken. Dies entfernt in '''KDevelop''' 4.2.x auch den Button, der das Werkzeug repräsentiert. Dies war jedoch der Weg, um das Unterfenster zurück zu bekommen. Weiter unten steht, wie der Button zurück auf den Perimeter gelangt; es handelt sich um den selben Weg, mit dem man irgendeinen Werkzeugbutton hinzufügen kann. Dies ist als Fehler gemeldet wurden unter [http://bugs.kde.org/show_bug.cgi?id=270018 bug 270018]}}  
    {{Note|1=To make a subwindow disappear, you can also click at the <menuchoice>x</menuchoice> at the top right of the subwindow.}}  


    Das obenstehende Bild zeigt eine Selektion von Werkzeugen, ausgerichtet am rechten und linken Rand. In dem Bild ist das '''Klassen'''-Werkzeug geöffent auf der Linken Seite und das '''Snippets'''-Werkzeug auf der rechten Seite, gemeinsam mit einem Editor für eine Quelltextdatei in der Mitte. In der Praxis werden Sie die meiste Zeit damit verbringen, nur den Editor und vielleicht das '''Klassen'''- oder '''Code-Browser'''-Werkzeug offen zu haben. Andere Werkzeuge werden vermutlich nur temporär offen sein, wenn Sie das Werkzeug benutzen, so dass Sie die meiste Zeit mehr Platz für den Editor haben.
    The picture above shows a particular selection of tools, aligned on the left and right margins; in the picture, the <menuchoice>Classes</menuchoice> tool is open on the left and the <menuchoice>Snippets</menuchoice> 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 <menuchoice>Classes</menuchoice> or <menuchoice>Code Browser</menuchoice> 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.


    Wenn Sie '''KDevelop''' zum ersten mal ausführen, sollten Sie bereits den <menuchoice>Projekte</menuchoice> Werkzeugbutton sehen. Klick Sie darauf: es öffnet sich ein Unterfenster das alle Projekte, die Sie zur Sitzung hinzugefügt haben unten und eine Dateisystemansicht der Verzeichnisse ihrer Projekte oben zeigt.
    Wenn Sie '''KDevelop''' zum ersten mal ausführen, sollten Sie bereits den <menuchoice>Projekte</menuchoice> Werkzeugbutton sehen. Klick Sie darauf: es öffnet sich ein Unterfenster das alle Projekte, die Sie zur Sitzung hinzugefügt haben unten und eine Dateisystemansicht der Verzeichnisse ihrer Projekte oben zeigt.


    Es gibt viele andere Werkzeuge die Sie mit '''KDevelop''' nutzen können. Nicht alle sind anfangs durch Buttons an der Seite repräsentiert. Um Werkzeugbuttons hinzuzufügen, gehen Sie auf den <menuchoice>Fenster -> Werkzeugansicht hinzufügen</menuchoice> Menüeintrag. Es folgen einige Beispiele, die Sie möglicherweise nützlich finden:
    There are many [[Special:myLanguage/KDevelop4/Manual/Tool_list|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 -> Add tool view</menuchoice> menu entry. Here are some that you will likely find useful:


    * '''Klassen''': Eine Komplette Liste aller Klasse die in dem Projekt oder der Sitzung definiert ist, sowie deren Funktionen und Variablen. Das Klicken auf irgendein Objekt öffnet ein Quelltexteditorfenster in dem das Objekt, auf das sie geklickt haben, geöffnet ist.
    * '''Klassen''': Eine Komplette Liste aller Klasse die in dem Projekt oder der Sitzung definiert ist, sowie deren Funktionen und Variablen. Das Klicken auf irgendein Objekt öffnet ein Quelltexteditorfenster in dem das Objekt, auf das sie geklickt haben, geöffnet ist.
    Line 37: Line 37:


    * '''Konsole''': Öffnet ein Kommandozeilenfenster in '''KDevelop'''s Hauptfenster, für Kommandos die Sie eventuell eingeben wollen (beispielsweise <code>./configure</code>).
    * '''Konsole''': Öffnet ein Kommandozeilenfenster in '''KDevelop'''s Hauptfenster, für Kommandos die Sie eventuell eingeben wollen (beispielsweise <code>./configure</code>).
    Eine Komplette Liste von Werkzeugen und Ansichten ist unter [[Special:myLanguage/KDevelop4/Manual/Tool list|hier]].


    Für die meisten Programmierer ist vertikaler Platz das Wichtigste. Um vertikalen Platz zu gewinnen, können Sie ihre Werkzeugansichten am rechten und linken Rand des Fensters verschieben: um dies zu tun, klicken Sie auf das Symbol des Werkzeugs mit der rechten Maustaste und wählen Sie eine neue Position für das Werkzeug.
    Für die meisten Programmierer ist vertikaler Platz das Wichtigste. Um vertikalen Platz zu gewinnen, können Sie ihre Werkzeugansichten am rechten und linken Rand des Fensters verschieben: um dies zu tun, klicken Sie auf das Symbol des Werkzeugs mit der rechten Maustaste und wählen Sie eine neue Position für das Werkzeug.
    Line 60: Line 58:
    Die Dynamik macht den Tooltip noch nützlicher: Sie können auf den Container klicken, um Informationen über den Kontext, in dem die Variable deklariert ist, zu erhalten (beispielsweise über den Namensraum <code>System</code>, was dort deklariert, definiert oder benutzt ist und wie es dokumentiert ist), und Sie können auf die blauen Links klicken, um den Cursor auf die Position der Deklaration des Symbols zu setzen (beispielsweise in <code>utilities.h</code>, Zeile 289). Außerdem können Sie sich eine Liste von Stellen, an denen das Symbol in der aktuellen Datei, im gesamten Projekt oder der derzeitigen Sitzung genutzt wird. Letzteres ist oft nützlich wenn Sie herausfinden wollen wie eine Funktion in einer großen Quelltextmenge verwendet wird.
    Die Dynamik macht den Tooltip noch nützlicher: Sie können auf den Container klicken, um Informationen über den Kontext, in dem die Variable deklariert ist, zu erhalten (beispielsweise über den Namensraum <code>System</code>, was dort deklariert, definiert oder benutzt ist und wie es dokumentiert ist), und Sie können auf die blauen Links klicken, um den Cursor auf die Position der Deklaration des Symbols zu setzen (beispielsweise in <code>utilities.h</code>, Zeile 289). Außerdem können Sie sich eine Liste von Stellen, an denen das Symbol in der aktuellen Datei, im gesamten Projekt oder der derzeitigen Sitzung genutzt wird. Letzteres ist oft nützlich wenn Sie herausfinden wollen wie eine Funktion in einer großen Quelltextmenge verwendet wird.


    {{Note|1=Die Information im Tooltip ist fließend. Sie hängt davon ab, ob Sie die <keycap>Alt</keycap>-Taste drücken oder ob Sie mi der Maus auf einem Objekt sind. Wenn Sie es dauerhaft öffnen wollen, dann platzieren Sie es in der '''Quelltext Browser"' Ansicht in einem der Unterfenster. Beispielsweise ist hier der Cursor auf der selben Funktion wie im obigen Beispiel, und die Werkzeugansicht auf der linken Seite repräsentiert die selben Informationen wie im vorherigen Tooltip.<!--}}-->
    {{Note|1=The information in a tooltip is fleeting &mdash; it depends on you holding the <keycap>Alt</keycap> key down or hovering your mouse. If you want a more permanent place for it, open the <menuchoice>Code Browser</menuchoice> tool view in one of the sub-windows. For example, here the cursor is on the same function as in the example above, and the tool view on the left presents the same kind of information as in the tooltip before:<!--}}-->


    [[Image:kdevelop-15.png|thumb|500px|center]]
    [[Image:kdevelop-15.png|thumb|500px|center]]
    Line 80: Line 78:
    ==== Projekt- und Sitzungsberichtsinformationen ====
    ==== Projekt- und Sitzungsberichtsinformationen ====


    Es gibt viele Wege um an Informationen über ein gesamtes Projekt (oder über alle Projekte einer Sitzung) zu erhalten. Diese Art von Informationen wird typischerweise durch verschiedene Ansichten angeboten. Beispielsweise bietet die '''Klassen'''-Ansicht eine Baumstruktur aller Klassen und umgebenden Namensräume für alle Projekte in einer Sitzung, gemeinsam mit den Funktionen und Variablen von jeder dieser Klassen:
    There are many ways to obtain information about an entire project (or, in fact, about all projects in a session). This sort of information is typically provided through various tool views. For example, the <menuchoice>Classes</menuchoice> tool view provides a tree structure of all classes and surrounding namespaces for all projects in a session, together with the member functions and variables of each of these classes:


    [[Image:kdevelop-17.png|thumb|600px|center]]
    [[Image:kdevelop-17.png|thumb|600px|center]]
    Line 86: Line 84:
    Wenn Sie mit der Maus einen Eintrag anwählen, werden Ihnen Informationen über den Eintrag, den Ort seiner Deklaration und Definition und seine Benutzungen angezeigt. Ein Doppelklick auf den Eintrag in dieser Baumansicht öffnet ein Editorfenster an der Stelle, an der das Symbol deklariert und definiert ist.
    Wenn Sie mit der Maus einen Eintrag anwählen, werden Ihnen Informationen über den Eintrag, den Ort seiner Deklaration und Definition und seine Benutzungen angezeigt. Ein Doppelklick auf den Eintrag in dieser Baumansicht öffnet ein Editorfenster an der Stelle, an der das Symbol deklariert und definiert ist.


    Außerdem gibt es noch andere Arte, auf globale Informationen zu schauen. Beispielsweise liefert das '''Dokumente''' Werkzeug eine Sicht auf alle Dateitypen und andere Dokumente, die das Projekt beinhaltet:
    But there are other ways of looking at global information. For example, the <menuchoice>Documents</menuchoice> tool provides a view of a project in terms of the kinds of files or other documents this project is comprised of:


    [[Image:kdevelop-18.png|thumb|600px|center]]
    [[Image:kdevelop-18.png|thumb|600px|center]]
    ==== Rainbow color highlighting explained ====
    '''KDevelop''' uses a variety of colors to highlight different objects in source code. If you know what the different colors mean, you can very quickly extract a lot of information from source code just by looking at the colors, without reading a single character. The highlighting rules are as follows:
    * Objects of type Class / Struct, Enum (the values and the type), (global) functions, and class members each have their own color assigned (classes are green, enums are dark red, and members are dark yellow or violet, (global) functions are always violet).
    * All global variables are colored in dark green.
    * Identifiers which are typedefs for another type are colored in teal.
    * All declarations and definitions of objects are in bold.
    * If a member is accessed from within the context where it is defined (base or derived class) it appears in yellow, otherwise it appears in violet.
    * If a member is private or protected, it gets colored in a slightly darker color when used.
    * For variables local to a function body scope, rainbow colors are picked based on a hash of the identifier. This includes the parameters to the function. An identifier always will have the same color within its scope (but the same identifier will get a different color if it represents a different object, i.e. if it is redefined in a more nested scope), and you will usually get the same color for the same identifier name in different scopes. Thus, if you have multiple functions taking parameters with the same names, the arguments will all look the same color-wise.
    * Identifiers for which '''KDevelop''' could not determine the corresponding declaration are colored in white. This can sometimes be caused by missing <code>#include</code> directives.
    * In addition to that coloring, the normal editor syntax highlighting will be applied, as known from '''Kate'''. '''KDevelop's''' semantic highlighting will always override the editor highlighting if there is a conflict.
    {{Note| Rainbow coloring of local variables can be turned off in <menuchoice>Settings...->Configure KDevelop...->Language Support->Local colorization intensity</menuchoice> by setting the slider control to its minimum value. Similarly colorization or global variables, global functions, classes, structs, enums, and class members can be turned off in <menuchoice>Settings...->Configure KDevelop...->Language Support->Global colorization intensity</menuchoice> }}
    <span id="Navigating in source code"></span>
    <span id="Navigating in source code"></span>
    === Navigieren im Quelltext ===
    === Navigieren im Quelltext ===
    Line 104: Line 126:
    Im Dateibereich bietet '''KDevelop''' viele verschiedene mögliche Wege um durch Quelltext zu navigieren. Beispielsweise:
    Im Dateibereich bietet '''KDevelop''' viele verschiedene mögliche Wege um durch Quelltext zu navigieren. Beispielsweise:


    * '''Outline'''': Sie können ein Outline darüber, was in der aktuellen Datei ist, auf drei Wegen erhalten:
    * '''Outline''': You can get an outline of what's in the current file in at least three different ways:
    ** Klicken Sie in die <menuchoice>Outline</menuchoice> Textbox oben rechts im Hauptfenster, oder drücken Sie <keycap>Strg + Alt + N</keycap>. Anschließend öffnet sich ein Dropdownmenü das alle Funktionen und Klassendeklarationen auflistet. [[Image:kdevelop-19.png|thumb|600px|center]] Sie können dann selektieren, zu welchem Sie springen, oder, falls es viele sind, Text, der in den Namen vorkommen könnte, zu tippen beginnen. In diesem Fall wird die Liste beim Schreiben kleiner und kleiner, da Namen entfernt werden, die zu dem bereits getippten nicht passen.
    ** Clicking into the <menuchoice>Outline</menuchoice> textbox at the top right of the main window, or hitting <keycap>Alt + Ctrl + N</keycap> opens a drop-down menu that lists all function and class declarations: [[Image:kdevelop-19.png|thumb|600px|center]] You can then just select which one to jump to, or &mdash; if there are a lot &mdash; start typing any text that may appear in the names shown; in that case, as you keep typing, the list becomes smaller and smaller as names are removed that don't match the text already typed until you are ready to select one of the choices.
    ** Positionieren des Cursor im Dateibereich (beispielsweise außerhalb einer Funktions- oder Klassendeklaration oder Definition) und Geöffnethaben des '''Quelltext Browser''' Werkzeugs: [[Image:kdevelop-16.png|thumb|600px|center]] Dies zeigt ihnen auch eine Outline davon, was in der aktuellen Datei passiert, und erlaubt Ihnen, zu selektieren, wo Sie hinspringen wollen.
    ** Positioning the cursor at file scope (i.e. outside any function or class declarations or definitions) and having the <menuchoice>Code Browser</menuchoice> tool open: [[Image:kdevelop-16.png|thumb|600px|center]] This also provides you an outline of what is happening in the current file, and allows you to select where you want to jump to.
    ** Wenn Sie mit der Maus über einen Tab für eine offene Datei fahren, erhalten Sie auch eine Outline dieser Datei in dem Tab.
    ** Hovering the mouse over the tab for one of the open files also yields an outline of the file in that tab.


    * Quelltextdateien sind in einer Liste als Funktionsdeklarationen und -definitionen organisiert. Das Drücken von <keycap>Strg + Alt + PgUp</keycap> und <keycap>Strg + Alt + PgDown</keycap> springt zur vorhergehenden oder zur nächsten Funktionsdefinition in dieser Datei
    * Quelltextdateien sind in einer Liste als Funktionsdeklarationen und -definitionen organisiert. Das Drücken von <keycap>Strg + Alt + PgUp</keycap> und <keycap>Strg + Alt + PgDown</keycap> springt zur vorhergehenden oder zur nächsten Funktionsdefinition in dieser Datei
    Line 133: Line 155:
    * '''Previous/Next use''': Placing the cursor on the name of a local variable and selecting <menuchoice>Navigation -> Next use</menuchoice> (or hitting <keycap>Meta + Shift + Right</keycap>) transports you to the next use of this variable in the code. (Note that this doesn't just search for the next occurrence of the variable name but in fact takes into account that variables with the same name but in different scopes are different.) The same works for the use of function names. Selecting <menuchoice>Navigation -> Previous use</menuchoice> (or hitting <keycap>Meta + Shift + Left</keycap>) transports you to the previous use of a symbol.
    * '''Previous/Next use''': Placing the cursor on the name of a local variable and selecting <menuchoice>Navigation -> Next use</menuchoice> (or hitting <keycap>Meta + Shift + Right</keycap>) transports you to the next use of this variable in the code. (Note that this doesn't just search for the next occurrence of the variable name but in fact takes into account that variables with the same name but in different scopes are different.) The same works for the use of function names. Selecting <menuchoice>Navigation -> Previous use</menuchoice> (or hitting <keycap>Meta + Shift + Left</keycap>) transports you to the previous use of a symbol.


    {{Note|1=To see the list of all uses of a name through which these commands cycle, place the cursor onto it and open the '''Code Browser''' tool view or press and hold the <keycap>Alt</keycap> button. This is explained in more detail in the section on [[Special:myLanguage/KDevelop4/Manual/Working_with_source_code#File_scope_information|Exploring code]].}}
    {{Note|1=To see the list of all uses of a name through which these commands cycle, place the cursor onto it and open the <menuchoice>Code Browser</menuchoice> tool view or press and hold the <keycap>Alt</keycap> button. This is explained in more detail in the section on [[Special:myLanguage/KDevelop4/Manual/Working_with_source_code#File_scope_information|Exploring code]].}}


    * The '''context list''': Web browsers have this feature where you can go backward and forward in the list of most recently visited web pages. '''KDevelop''' has the same kind of features, except that instead of web pages you visit ''contexts''. A context is the current location of the cursor, and you change it by navigating away from it using anything but cursor commands &mdash; for example, by clicking on a location provided by a tooltip, in the '''Code Browser''' tool view, one of the options given in the <menuchoice>Navigation</menuchoice> menu, or any other navigation command. Using the <menuchoice>Navigation -> Previous Visited Context</menuchoice> (<keycap>Meta + Left</keycap>) and <menuchoice>Navigation -> Next Visited Context</menuchoice> (<keycap>Meta + Right</keycap>) transports you along this list of visited contexts just like the <menuchoice>back</menuchoice> and <menuchoice>forward</menuchoice> buttons of a browser transports you to the previous or next webpage in the list of visited pages.
    {{Note|Some shortcuts might be used already by your window manager (e.g. <keycap>Meta + Left</keycap> is used by LXDE/Openbox); you can either change the key combination for the shortcut in kdevelop <menuchoice>Settings...->Configure Shortcuts</menuchoice> or in the window manager config (e.g. .config/openbox/lubuntu-rc.xml)}}


    * Finally, there are tool views that allow you to navigate to different places in your code base. For example, the '''Classes''' tool provides you with a list of all namespaces and classes in all projects of the current session, and allows you to expand it to see member functions and variables of each of these classes: [[Image:kdevelop-17.png|thumb|500px|center]] Double-clicking on an item (or going through the context menu using the right mouse button) allows you to jump to the location of the declaration of the item. Other tools allow similar things; for example, the '''Projects''' tool view provides a list of files that are part of a session: [[Image:kdevelop-13.png|thumb|500px|center]] Again, double-clicking on a file opens it.
    * The '''context list''': Web browsers have this feature where you can go backward and forward in the list of most recently visited web pages. '''KDevelop''' has the same kind of features, except that instead of web pages you visit ''contexts''. A context is the current location of the cursor, and you change it by navigating away from it using anything but cursor commands &mdash; for example, by clicking on a location provided by a tooltip, in the <menuchoice>Code Browser</menuchoice> tool view, one of the options given in the <menuchoice>Navigation</menuchoice> menu, or any other navigation command. Using the <menuchoice>Navigation -> Previous Visited Context</menuchoice> (<keycap>Meta + Left</keycap>) and <menuchoice>Navigation -> Next Visited Context</menuchoice> (<keycap>Meta + Right</keycap>) transports you along this list of visited contexts just like the <menuchoice>back</menuchoice> and <menuchoice>forward</menuchoice> buttons of a browser transports you to the previous or next webpage in the list of visited pages.
     
    * Finally, there are tool views that allow you to navigate to different places in your code base. For example, the '''Classes''' tool provides you with a list of all namespaces and classes in all projects of the current session, and allows you to expand it to see member functions and variables of each of these classes: [[Image:kdevelop-17.png|thumb|500px|center]] Double-clicking on an item (or going through the context menu using the right mouse button) allows you to jump to the location of the declaration of the item. Other tools allow similar things; for example, the <menuchoice>Projects</menuchoice> tool view provides a list of files that are part of a session: [[Image:kdevelop-13.png|thumb|500px|center]] Again, double-clicking on a file opens it.




    Line 183: Line 207:
    ==== Adding new classes and implementing member functions ====
    ==== Adding new classes and implementing member functions ====


    '''KDevelop''' has a wizard for adding new classes. To add a new class, select <menuchoice>Code -> Create New Class</menuchoice> to get the following dialog box:
    '''KDevelop''' has an assistant for adding new classes. The procedure is described in [[Special:myLanguage/KDevelop4/Manual/Code generation with templates#Creating a new class|Creating a new class]].  A simple C++ class can be created by choosing the Basic C++ template from the <tt>Class</tt> category. In the assistant, we can choose some predefined member functions, for example an empty constructor, a copy constructor and a destructor.
     
    [[Image:kdevelop-27.png|thumb|400px|center]]
     
    Here, we have entered the new class's name <code>Bus</code> (you can also enter here which other classes this class should be derived from). The next page of the dialog allows us to select the standard member functions we will need:


    [[Image:kdevelop-28.png|thumb|400px|center]]
    After completing the assistant, the new files are created and opened in the editor. The header file already has include guards and the new class has all the member functions we selected. The next two steps would be to document the class and its member functions and to implement them. We will discuss aids for documenting classes and functions below. To implement the special functions already added, simply go to the <menuchoice>bus.cpp</menuchoice> tab where the skeleton of functions are already provided:
     
    Here, we want a default constructor, a copy constructor, and a destructor. After the following pages of the dialog that allow you to select a license header and the location for the new files, '''KDevelop''' will generate two new tabs with the header and source files:
     
    [[Image:kdevelop-29.png|thumb|500px|center]]
     
     
    The header file already has include guards and the new class has all the member functions we selected. The next two steps would be to document the class and its member functions and to implement them. We will discuss aids for documenting classes and functions below. To implement the special functions already added, simply go to the <menuchoice>bus.cpp</menuchoice> tab where the skeleton of functions are already provided:


    [[Image:kdevelop-30.png|thumb|500px|center]]
    [[Image:kdevelop-30.png|thumb|500px|center]]
    Line 227: Line 240:


    [[Image:kdevelop-37.png|thumb|500px|center]]
    [[Image:kdevelop-37.png|thumb|500px|center]]
    {{Note|1=The fact that the tooltip shows the same function twice is fixed in '''KDevelop''' 4.2.2 and later.}}
    {{Note|1=In the example, accepting one of the choices the auto-completion tool offers yields the correct signature but unfortunately deletes the <code>inline</code> marker already written. This has been reported as [https://bugs.kde.org/show_bug.cgi?id=274244 KDevelop Bug 274245].}}


    ==== Documenting declarations ====
    ==== Documenting declarations ====


    Good code is well documented, both at the level of the implementation of algorithms within in functions as well as at the level of the interface &mdash; i.e., classes, (member and global) functions, and (member or global) variables need to be documented to explain their intent, possible values of arguments, pre- and postconditions, etc. As far as documenting the interface is concerned, [http://www.doxygen.org doxygen] has become the de facto standard for formatting comments that can then be extracted and displayed on searchable webpages.
    Good code is well documented, both at the level of the implementation of algorithms within functions, as well as at the level of the interface &mdash; i.e., classes, (member and global) functions, and (member or global) variables need to be documented to explain their intent, possible values of arguments, pre- and postconditions, etc. As far as documenting the interface is concerned, [http://www.doxygen.org doxygen] has become the de facto standard for formatting comments that can then be extracted and displayed on searchable webpages.


    '''KDevelop''' supports this style of comments by providing a short cut to generate the framework of comments that document a class or member function. For example, assume you have already written this code:
    '''KDevelop''' supports this style of comments by providing a short cut to generate the framework of comments that document a class or member function. For example, assume you have already written this code:
    Line 293: Line 301:
    </syntaxhighlight>}}
    </syntaxhighlight>}}


    Rather than typing this kind of text over and over again (with all the concomitant typos one introduces), the '''Snippets''' tool of '''KDevelop''' can help here. To this end, open the tool view (see [[Special:myLanguage/KDevelop4/Manual/Working with source code#Tools and views|Tools and views]] if the corresponding button isn't already on the perimeter of your window). Then click on the "Add repository" button (a slight misnomer &mdash; it allows you to create a named collection of snippets for source codes of a particular kind, e.g. C++ sources) and create an empty repository. Then click {{Plus}} to add a snippet, to get a dialog like the following:
    Rather than typing this kind of text over and over again (with all the concomitant typos one introduces), the <menuchoice>Snippets</menuchoice> tool of '''KDevelop''' can help here. To this end, open the tool view (see [[Special:myLanguage/KDevelop4/Manual/Working with source code#Tools and views|Tools and views]] if the corresponding button isn't already on the perimeter of your window). Or, go to <menuchoice>Window -> Tool views</menuchoice> in the top menubar, and turn on <menuchoice>Snippets</menuchoice>. Then click on the <menuchoice>Add repository</menuchoice>button (a slight misnomer &mdash; it allows you to create a named collection of snippets for source codes of a particular kind, e.g. C++ sources) and create an empty repository. Then click {{Plus}} to add a snippet, to get a dialog like the following:


    [[Image:kdevelop-40.png|thumb|500px|center]]
    [[Image:kdevelop-40.png|thumb|500px|center]]


    {{Note|1=The name of a snippet may not have spaces or other special characters because it must look like a normal function or variable name (for reasons that will become clear in the next paragraph). If the name of the snippet does contain spaces, the <menuchoice>OK</menuchoice> button will become inactive without any further explanation. This has been reported as [https://bugs.kde.org/show_bug.cgi?id=274299 KDevelop bug 274299].}}
    {{Note|1=The name of a snippet may not have spaces or other special characters because it must look like a normal function or variable name (for reasons that will become clear in the next paragraph). If the name of the snippet does contain spaces, the <menuchoice>OK</menuchoice> button will become inactive without any further explanation. This has been fixed in recent versions of KDevelop (see [https://bugs.kde.org/show_bug.cgi?id=274299 KDevelop bug 274299]).}}


    To use a snippet so defined, when you are editing code, you can just type the name of the snippet like you would any other function or variable name. This name will become available for auto-completion &mdash; which means that there is no harm in using a long and descriptive name for a snippet such as the one above &mdash; and when you accept the suggestion of the auto-completion tooltip (for example by just hitting <keycap>Enter</keycap>), the already entered part of the snippets' name will be replaced by the full expansion of the snippet and will be properly indented:
    To use a snippet so defined, when you are editing code, you can just type the name of the snippet like you would any other function or variable name. This name will become available for auto-completion &mdash; which means that there is no harm in using a long and descriptive name for a snippet such as the one above &mdash; and when you accept the suggestion of the auto-completion tooltip (for example by just hitting <keycap>Enter</keycap>), the already entered part of the snippets' name will be replaced by the full expansion of the snippet and will be properly indented:
    Line 303: Line 311:
    [[Image:kdevelop-41.png|thumb|500px|center]]
    [[Image:kdevelop-41.png|thumb|500px|center]]


    Note that for this to work, the '''Snippets''' tool view need not be open or visible: you only ever need the tool view to define new snippets. An alternative, if less convenient, way to expand a snippet is to simply click on it in the respective tool view.
    Note that for this to work, the <menuchoice>Snippets</menuchoice> tool view need not be open or visible: you only ever need the tool view to define new snippets. An alternative, if less convenient, way to expand a snippet is to simply click on it in the respective tool view.


    {{Note|1=Snippets are much more powerful than just explained. For a full description of what you can do with them, see the [[Special:myLanguage/KDevelop4/Manual/Tool_list/Snippets|detailed documentation of the Snippets tool]].}}<span id="Modes and working sets"></span>
    {{Note|1=Snippets are much more powerful than just explained. For a full description of what you can do with them, see the [[Special:myLanguage/KDevelop4/Manual/Tool_list/Snippets|detailed documentation of the Snippets tool]].}}<span id="Modes and working sets"></span>
    Line 428: Line 436:


    {{Prevnext2
    {{Prevnext2
    | prevpage=Special:MyLanguage/KDevelop4/Manual/Sessions_and_projects | nextpage=Special:MyLanguage/KDevelop4/Manual/Building_(compiling)_projects_with_custom_Makefiles
    | prevpage=Special:MyLanguage/KDevelop4/Manual/Sessions_and_projects | nextpage=Special:MyLanguage/KDevelop4/Manual/Code_generation_with_templates
    | prevtext=Sessions and projects | nexttext=Building (compiling) projects with custom Makefiles
    | prevtext=Sessions and projects | nexttext=Code generation with templates
    | index=Special:MyLanguage/KDevelop4/Manual | indextext=Back to menu
    | index=Special:MyLanguage/KDevelop4/Manual | indextext=Back to menu
    }}
    }}


    [[Category:Entwicklung/de]]
    [[Category:Entwicklung/de]]

    Revision as of 05:00, 18 April 2018

    Mit Quelltext arbeiten

    Neben dem Debuggen ist das Lesen und Schreiben von Quelltext das, womit man bei der Softwareentwicklung am meisten Zeit verbringt. An dieser Stelle bietet Kdevelop sehr viele verschiedene Wege um Quelltext anzuschauen und das Quelltextschreiben produktiver zu machen. Wie in den folgenden Abschnitten beschriebenwird, ist KDevelop nicht nur ein Quelltexteditor. Es ist vielmehr ein Quelltextmanagementsystem, das Ihnen verschiedene Blicke auf die extrahierten Informationen aus den Dateien gibt, die in den Quelltext ihrer Sitzung bilden.

    Werkzeuge und Ansichten

    Um mit Projekte zu arbeiten besitzt KDevelop das Konzept der Werkzeuge. Ein Werkzeug bietet eine bestimmte Ansicht auf den Quelltext, oder eine Aktion die damit durchgeführt werden kann. Werkzeuge werden durch einen Button am Rand des Fensters repräsentiert (in vertikalem Text auf dem linken und rechtenRand, oder horizontal am unteren Rand). Wenn Sie darauf klicken, expandieren sie in einem Unterfenster eine Ansicht im Hauptfenster. Wenn Sie auf den Button erneut klicken, verschwendet das Unterfenster wieder.

    Note

    To make a subwindow disappear, you can also click at the x at the top right of the subwindow.


    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.

    Wenn Sie KDevelop zum ersten mal ausführen, sollten Sie bereits den Projekte Werkzeugbutton sehen. Klick Sie darauf: es öffnet sich ein Unterfenster das alle Projekte, die Sie zur Sitzung hinzugefügt haben unten und eine Dateisystemansicht der Verzeichnisse ihrer Projekte oben zeigt.

    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:

    • Klassen: Eine Komplette Liste aller Klasse die in dem Projekt oder der Sitzung definiert ist, sowie deren Funktionen und Variablen. Das Klicken auf irgendein Objekt öffnet ein Quelltexteditorfenster in dem das Objekt, auf das sie geklickt haben, geöffnet ist.
    • Dokumente: Liste der zuletzt besuchten Dateien, geordnet nach Typ (beispielsweise Quelltextdatei, Patchdatei, einfache Textdokumente)
    • Quelltext Browser: Abhängig von der derzeitigen Cursorposition in einer Datei zeigt dieses Werkzeug Dinge, die sich darauf beziehen. Beispielsweise, wenn Sie auf einer #include Zeile sind, dann zeigt es Informationen über die Datei, die Sie einbingen, beispielsweise die Klassen, die in der Datei deklariert werden. Wenn Sie in einer leeren Zeile sind, zeigt es Klassen und Funktionen die in der aktuellen Datei deklariert und definiert sind (alle als Verweise: Klicken auf die Verweise bringt Sie zu dem Punkt, an dem die Deklaration oder die Definition wirklich ist). Wenn Sie in einer Funktionsdefinition sind, dann zeigt der Quelltext Browser, wo die Deklaration ist und eine Liste, wo die Funktion benutzt ist.
    • Dateisystem: Zeigt eine Baumansicht des Dateisystems.
    • Dokumentation: Erlaubt Ihnen, Handbücher und andere Hilfedokumente zu durchsuchen.
    • Textbausteine: Dies bietet Textsequenzen an, die man die man wieder und wieder benutzt und die man nicht jedes mal neu schreiben will. In dem Projekt, von dem das Bild oben erstellt wurde, wird der folgende Code häufig geschrieben:
    for (typename Triangulation< dim>::active_cell_iterator cell
         = triangulation.begin_active();
       cell != triangulation.end();
       ++cell)


    Dies ist eine seltsam aussehender Ausdruck, aber er sieht beinahe so aus wie die Schleife, die man jedes mal benötigen würde. Dies macht es zu einem guten Kandidat für einen Textbaustein.

    • Konsole: Öffnet ein Kommandozeilenfenster in KDevelops Hauptfenster, für Kommandos die Sie eventuell eingeben wollen (beispielsweise ./configure).

    Für die meisten Programmierer ist vertikaler Platz das Wichtigste. Um vertikalen Platz zu gewinnen, können Sie ihre Werkzeugansichten am rechten und linken Rand des Fensters verschieben: um dies zu tun, klicken Sie auf das Symbol des Werkzeugs mit der rechten Maustaste und wählen Sie eine neue Position für das Werkzeug.

    Quelltext erforschen

    Lokale Informationen

    KDevelop' versteht Quelltext, und deswegen ist es wirklich gut beim Bereitstellen von Informationen über Variablen und Funtionen die im Programm vorkommen. Beispielsweise sehen Sie hier ein Beispiel vom Arbeiten mit einem Quelltextteil, und dem platzieren der Maus über dem Symbol cell in Zeile 1316 (wenn Sie tastaturorientiert arbeiten, können Sie denselben Effekt erreichen wenn sie die Alt-Taste für eine Zeit betätigen):

    KDevelop zeigt Ihnen einen Tooltip der den Typ der Variable beinhaltet (hier: DoFHandler<dim>active_cell_iterator), wo die Variable deklariert ist (der container der hier die umgebende Funktion get_maximal_velocity ist, weil es eine lokale Variable ist), was es ist (eine Variable, keine Funktion, keine Klasse und keine Namensraum) und wo die Variable deklariert ist (in Zeile 1314, nur ein paar Zeilen über dem Code).

    In dem aktuellen Kontext hatte das Symbol, auf dem die Maus platziert war, keine assoziierte Dokumentation. Im selben Beispiel würde das Platzieren der Maus auf get_this_mpi_process in Zeile 1318 das folgende Ergebnis liefern:

    Hier hat KDevelop eine cross-referenzierte Deklaration von einer völlig unterschiedlichen Datei (utilities.h, das sogar in einem verschiedenen Projekt in derselben Sitzung ist), zusammen mit dem doxygen-Stil Kommentar das die Deklaration begleitet.

    Die Dynamik macht den Tooltip noch nützlicher: Sie können auf den Container klicken, um Informationen über den Kontext, in dem die Variable deklariert ist, zu erhalten (beispielsweise über den Namensraum System, was dort deklariert, definiert oder benutzt ist und wie es dokumentiert ist), und Sie können auf die blauen Links klicken, um den Cursor auf die Position der Deklaration des Symbols zu setzen (beispielsweise in utilities.h, Zeile 289). Außerdem können Sie sich eine Liste von Stellen, an denen das Symbol in der aktuellen Datei, im gesamten Projekt oder der derzeitigen Sitzung genutzt wird. Letzteres ist oft nützlich wenn Sie herausfinden wollen wie eine Funktion in einer großen Quelltextmenge verwendet wird.

    Note

    The information in a tooltip is fleeting — it depends on you holding the Alt key down or hovering your mouse. If you want a more permanent place for it, open the Code Browser tool view in one of the sub-windows. For example, here the cursor is on the same function as in the example above, and the tool view on the left presents the same kind of information as in the tooltip before:
    Das Bewegen des Cursors auf der rechten Seite verändert die Informationen, die auf der linken Seite gezeigt werden. Weiterhin können Sie auf den Aktuelle Ansicht sperren-Button oben rechts im Unterfenster klicken, um die aktuellen Informationen beizubehalten. Dadurch machen Sie die Informationen unabhängig von der Cursorbewegung, so dass sie während der Cursorbewegung die Informationen im Quelltext Browser anschauen können.


    Note

    Diese Art von Informationen ist an vielen anderen orten in KDevelop verfügbar, nicht nur im Quelltexteditor. Beispielsweise liefert das Drücken der Alt-Taste in der Komplettierungsliste (beispielsweise beim Schnellöffnen) auch Kontextinformationen über das aktuelle Symbol.


    Dateibereichsinformationen

    Die nächste Stufe ist, Informationen über die gesamte Quelltextdatei einzuholen, an der Sie gerade arbeiten. Um dies zu tun, positionieren Sie den Cursor im Dateibereich der aktuellen Datei und schauen Sie, was der Quelltext Browser anzeigt:

    Hier wird eine Liste von Namensräumen, Klassen und Funktionen die in der aktuellen Datei deklariert oder definiert werden angezeigt. So wird Ihnen ein Überblick darüber gegeben, was in dieser Datei passiert, und eine Möglichkeit, direkt zu irgendeiner von diesen Deklarationen und Definitionen zu springen, ohne hoch und runter in der Datei zu scrollen oder nach einem Symbol zu suchen.

    Note

    The information shown for file scope is the same as presented in the "Outline" mode discussed below for navigating source code; the difference is that outline mode is only a temporary tooltip.


    Projekt- und Sitzungsberichtsinformationen

    There are many ways to obtain information about an entire project (or, in fact, about all projects in a session). This sort of information is typically provided through various tool views. For example, the Classes tool view provides a tree structure of all classes and surrounding namespaces for all projects in a session, together with the member functions and variables of each of these classes:

    Wenn Sie mit der Maus einen Eintrag anwählen, werden Ihnen Informationen über den Eintrag, den Ort seiner Deklaration und Definition und seine Benutzungen angezeigt. Ein Doppelklick auf den Eintrag in dieser Baumansicht öffnet ein Editorfenster an der Stelle, an der das Symbol deklariert und definiert ist.

    But there are other ways of looking at global information. For example, the Documents tool provides a view of a project in terms of the kinds of files or other documents this project is comprised of:

    Rainbow color highlighting explained

    KDevelop uses a variety of colors to highlight different objects in source code. If you know what the different colors mean, you can very quickly extract a lot of information from source code just by looking at the colors, without reading a single character. The highlighting rules are as follows:

    • Objects of type Class / Struct, Enum (the values and the type), (global) functions, and class members each have their own color assigned (classes are green, enums are dark red, and members are dark yellow or violet, (global) functions are always violet).
    • All global variables are colored in dark green.
    • Identifiers which are typedefs for another type are colored in teal.
    • All declarations and definitions of objects are in bold.
    • If a member is accessed from within the context where it is defined (base or derived class) it appears in yellow, otherwise it appears in violet.
    • If a member is private or protected, it gets colored in a slightly darker color when used.
    • For variables local to a function body scope, rainbow colors are picked based on a hash of the identifier. This includes the parameters to the function. An identifier always will have the same color within its scope (but the same identifier will get a different color if it represents a different object, i.e. if it is redefined in a more nested scope), and you will usually get the same color for the same identifier name in different scopes. Thus, if you have multiple functions taking parameters with the same names, the arguments will all look the same color-wise.
    • Identifiers for which KDevelop could not determine the corresponding declaration are colored in white. This can sometimes be caused by missing #include directives.
    • In addition to that coloring, the normal editor syntax highlighting will be applied, as known from Kate. KDevelop's semantic highlighting will always override the editor highlighting if there is a conflict.

    Note

    Rainbow coloring of local variables can be turned off in Settings...->Configure KDevelop...->Language Support->Local colorization intensity by setting the slider control to its minimum value. Similarly colorization or global variables, global functions, classes, structs, enums, and class members can be turned off in Settings...->Configure KDevelop...->Language Support->Global colorization intensity

    Navigieren im Quelltext

    In dem letzten Abschnitt wurde das anschauen von Quelltext beschrieben, das heißt das Gewinnen von Informationen über Symbole, Dateien und Projekte. Der nächste Schritt ist in dem Quelltexten herumzuspringen, das heißt darin zu navigieren. Es gibt verschiedene Stufen, auf denen dies möglich ist: lokal, in einer Datei und in einem Projekt.

    Note

    Viele dieser Arten, durch Quelltext zu navigieren, sind verfügbar unter dem Navigieren-Menü im KDevelop Hauptfenster.


    Lokale Navigation

    KDevelop ist viel mehr als ein Editor, aber es ist auch ein Quelltexteditor. Deshalb können Sie den Cursor hoch, runter, links und rechts in einer Quelltextdatei bewegen, die PageUp und die PageDown-Taste benutzen und andere Kommandos die Sie von einem Editor gewohnt sind.

    Navigation im Dateibereich und Outlinemodus

    Im Dateibereich bietet KDevelop viele verschiedene mögliche Wege um durch Quelltext zu navigieren. Beispielsweise:

    • Outline: You can get an outline of what's in the current file in at least three different ways:
      • Clicking into the Outline textbox at the top right of the main window, or hitting Alt + Ctrl + N opens a drop-down menu that lists all function and class declarations:
        You can then just select which one to jump to, or — if there are a lot — start typing any text that may appear in the names shown; in that case, as you keep typing, the list becomes smaller and smaller as names are removed that don't match the text already typed until you are ready to select one of the choices.
      • Positioning the cursor at file scope (i.e. outside any function or class declarations or definitions) and having the Code Browser tool open:
        This also provides you an outline of what is happening in the current file, and allows you to select where you want to jump to.
      • Hovering the mouse over the tab for one of the open files also yields an outline of the file in that tab.
    • Quelltextdateien sind in einer Liste als Funktionsdeklarationen und -definitionen organisiert. Das Drücken von Strg + Alt + PgUp und Strg + Alt + PgDown springt zur vorhergehenden oder zur nächsten Funktionsdefinition in dieser Datei

    Navigation im Projekt- und Sitzungsbereich: Semantische Navigation

    As mentioned in other places, KDevelop does not usually consider individual source files but rather looks at projects as a whole (or, rather, at all projects that are part of the current session). As a consequence, it offers many possibilities for navigating through entire projects. Some of these are derived from what we have already discussed in the section on Exploring source code while others are genuinely different. The common theme is that these navigation features are based on a semantic understanding of the code, i.e. they offer you something that requires parsing entire projects and connecting data. The following list shows some ways how to navigate through source code that is scattered throughout a potentially very large number of files:

    • As seen in the section on Exploring source code, you can get a tooltip explaining individual namespace, class, function or variable names by hovering your mouse over it or keeping the Alt key pressed for a while. Here is an example:
      Clicking on the links for the declaration of a symbol or expanding the list of uses allows you to jump to these locations, if necessary opening the respective file and placing the cursor at the corresponding location. A similar effect can be achieved by using the Code Browser tool view also discussed previously.
    • Quick open: A very powerful way of jumping to other files or locations is to use the various quick open methods in KDevelop. There are four versions of these:
      • Quick open class (Navigate -> Quick open class or Alt + Ctrl + C): You will get a list of all classes in this session. Start typing (a part of) the name of a class and the list will continue to whittle down to only those that actually match what you've typed so far. If the list is short enough, select an element using the up and down keys and KDevelop will get you to the place where the class is declared.
      • Quick open function (Navigate -> Quick open function or Alt + Ctrl + M): You will get a list of all (member) functions that are part of the projects in the current session, and you can select from it in the same way as above. Note that this list may include both function declarations and definitions.
      • Quick open file (Navigate -> Quick open file or Alt + Ctrl + O): You will get a list of all files that are part of the projects in the current session, and you can select from it in the same way as above.
      • Universal quick open (Navigate -> Quick open or Alt + Ctrl + Q): If you forget which key combination is bound to which of the above commands, this is the universal swiss army knife — it simply presents you with a combined list of all files, functions, classes, and other things from which you can select.
    • Jump to declaration/definition: When implementing a (member) function, one often needs to switch back to the point where a function is declared, for example to keep the list of function arguments synchronised between declaration and definition, or to update the documentation. To do so, place the cursor onto the function name and select Navigation -> Jump to declaration (or hit Ctrl + .) to get to the place where the function is declared. There are multiple ways to get back to the original place:
      • Selecting Navigation -> Jump to definition (or hitting Ctrl + ,).
      • Selecting Navigation -> Previous visited context (or hit Meta + Left), as described below.

    Note

    Jumping to the declaration of a symbol is something that does not only work when placing the cursor on the name of the function you are currently implementing. Rather, it also works for other symbols: Putting the cursor on a (local, global, or member) variable and jumping to its declaration also transports you to its location of declaration. Similarly, you can place the cursor on the name of a class, for example in a variable of function declaration, and jump to the location of its declaration.


    • Switch between declaration/definition: In the example above, to jump to the site of the declaration of the current function, you need to first place the cursor on the function name. To avoid this step, you can select Navigation -> Switch definition/declaration (or hit Shift + Ctrl + C) to jump to the declaration of the function within which the cursor currently is. Selecting the same menu entry a second time transports you back to the place where the function is defined.
    • Previous/Next use: Placing the cursor on the name of a local variable and selecting Navigation -> Next use (or hitting Meta + Shift + Right) transports you to the next use of this variable in the code. (Note that this doesn't just search for the next occurrence of the variable name but in fact takes into account that variables with the same name but in different scopes are different.) The same works for the use of function names. Selecting Navigation -> Previous use (or hitting Meta + Shift + Left) transports you to the previous use of a symbol.

    Note

    To see the list of all uses of a name through which these commands cycle, place the cursor onto it and open the Code Browser tool view or press and hold the Alt button. This is explained in more detail in the section on Exploring code.


    Note

    Some shortcuts might be used already by your window manager (e.g. Meta + Left is used by LXDE/Openbox); you can either change the key combination for the shortcut in kdevelop Settings...->Configure Shortcuts or in the window manager config (e.g. .config/openbox/lubuntu-rc.xml)


    • The context list: Web browsers have this feature where you can go backward and forward in the list of most recently visited web pages. KDevelop has the same kind of features, except that instead of web pages you visit contexts. A context is the current location of the cursor, and you change it by navigating away from it using anything but cursor commands — for example, by clicking on a location provided by a tooltip, in the Code Browser tool view, one of the options given in the Navigation menu, or any other navigation command. Using the Navigation -> Previous Visited Context (Meta + Left) and Navigation -> Next Visited Context (Meta + Right) transports you along this list of visited contexts just like the back and forward buttons of a browser transports you to the previous or next webpage in the list of visited pages.
    • Finally, there are tool views that allow you to navigate to different places in your code base. For example, the Classes tool provides you with a list of all namespaces and classes in all projects of the current session, and allows you to expand it to see member functions and variables of each of these classes:
      Double-clicking on an item (or going through the context menu using the right mouse button) allows you to jump to the location of the declaration of the item. Other tools allow similar things; for example, the Projects tool view provides a list of files that are part of a session:
      Again, double-clicking on a file opens it.


    Quelltext schreiben

    Weil KDevelop den Quelltext ihres Projektes versteht, kann es dabei helfen, mehr Quelltext zu schreiben. Das Folgende zeigt, in welcher Weise es das tun kann.

    Autovervollständigung

    Probably the most useful of all features in writing new code is auto-completion. Consider, for example, the following piece of code:

    class Car {
      // ...
      public:
        std::string get_color () const;
    };
    
    void foo() 
    {
      Car my_ride;
      // ...do something with this variable...
      std::string color = my_ride.ge
    

    In the last line, KDevelop will remember that the variable my_ride is of type Car, and will automatically offer to complete the name of the member function ge as get_color. In fact, all you have to do is to keep typing until the auto-completion feature has reduced the number of matches to one, and then hit the Enter key:

    Note that you can click on the tool-tip to get more information about the function apart from its return type and whether it is public:

    Auto-completion can save you a lot of typing if your project uses long variable and function names; furthermore, it avoids mis-spelling names (and the resulting compiler errors) and it makes it much simpler to remember the exact names of functions; for example, if all of your getters start with get_, then the auto-completion feature will be able to only present you a list of possible getters when you have typed the first four letters, likely reminding you in the process which of the functions is the correct one. Note that for auto-completion to work, neither the declaration of the Car class nor of the my_ride variable need to be in the same file as where you are currently writing code. KDevelop simply has to know that these classes and variables are connected, i.e. the files in which these connections are made need to be part of the project you are currently working on.

    Note

    KDevelop doesn't always know when to assist you in completing code. If the auto-completion tooltip doesn't automatically open, hit Ctrl + Space to open a list of completions manually. In general, in order for auto-completion to work, KDevelop needs to parse your source files. This happens in the background for all files that are part of the projects of the current session after you start KDevelop, as well as while after you stop typing for a fraction of a second (the delay can be configured).


    Note

    KDevelop only parses files that it considers source code, as determined by the MIME-type of the file. This type isn't set before the first time a file is saved; consequently, creating a new file and starting to write code in it will not trigger parsing for auto-completion until after it is saved for the first time.


    Note

    As in the previous note, for auto-completion to work, KDevelop must be able to find declarations in header files. For this, it searches in a number of default paths. If it doesn't automatically find a header file, it will underline the name of a header file in red; in that case, right click on it to tell KDevelop explicitly where to find these files and the information they provide.


    Note

    Configuring auto-completion is discussed in this section of this manual.


    Adding new classes and implementing member functions

    KDevelop has an assistant for adding new classes. The procedure is described in Creating a new class. A simple C++ class can be created by choosing the Basic C++ template from the Class category. In the assistant, we can choose some predefined member functions, for example an empty constructor, a copy constructor and a destructor.

    After completing the assistant, the new files are created and opened in the editor. The header file already has include guards and the new class has all the member functions we selected. The next two steps would be to document the class and its member functions and to implement them. We will discuss aids for documenting classes and functions below. To implement the special functions already added, simply go to the bus.cpp tab where the skeleton of functions are already provided:

    To add new member functions, go back to the bus.h tab and add the name of a function. For example, let us add this:

    Note how I have already started with the implementation. However, in many coding styles, the function shouldn't be implemented in the header file but rather in the corresponding .cpp file. To this end, locate the cursor on the name of the function and select Code -> Move to source or hit Ctrl + Alt + S. This remove the code between curly braces from the header file (and replaces it by a semicolon as necessary to terminate the function declaration) and moves it into the source file:

    Note how I have just started typing and that I meant to imply that the students variable should probably be a member variable of class Bus but that I haven't yet added it. Note also how KDevelop underlines it to make clear that it doesn't know anything about the variable. But this problem can be solved: Clicking on the variable name yields the following tooltip:

    (The same can be achieved by right clicking on it and selecting Solve: Declare As.) Let me select "3 - private unsigned int" (either by mouse, or by hitting Alt + 3) and then see how it comes out in the header file:

    It is worth noting that KDevelop extracts the type of the variable to be declared from the expression used to initialize it. For example, if we had written the addition in the following rather dubious way, it would had suggested to declare the variable as type double:

    As a final point: The method using Code -> Move to source does not always insert the new member function where you may want it. For example, you may want it to be marked as inline and place it at the bottom of the header file. In a case like this, write the declaration and the start writing the definition of the function like this:

    KDevelop automatically offers all possible completions of what might come here. Selecting one of the two add_students entries yields the following code that already fills in the complete argument list:

    Documenting declarations

    Good code is well documented, both at the level of the implementation of algorithms within functions, as well as at the level of the interface — i.e., classes, (member and global) functions, and (member or global) variables need to be documented to explain their intent, possible values of arguments, pre- and postconditions, etc. As far as documenting the interface is concerned, doxygen has become the de facto standard for formatting comments that can then be extracted and displayed on searchable webpages.

    KDevelop supports this style of comments by providing a short cut to generate the framework of comments that document a class or member function. For example, assume you have already written this code:

    class Car {
      public:
        std::string get_color () const;
    };
    

    You now want to add documentation to both the class and the member function. To this end, move the cursor onto the first line and select Code -> Document Declaration or hit Alt + Shift + D. KDevelop will respond with the following:

    The cursor is already in the grayed out area for you to fill in the short description (after the doxygen keyword @brief) of this class. You can then continue to add documentation to this comment that gives a more detailed overview of what the class does:

    While the editor is inside the comment, the comment text is highlighted in green (the highlighting disappears once you move the cursor out of the comment). When you get to the end of a line, hit Enter and KDevelop will automatically start a new line that starts with an asterisk and place the cursor one character indented.

    Now let's document the member function, again by putting the cursor on the line of the declaration and selecting Code -> Document Declaration or hitting Alt + Shift + D:

    Again, KDevelop automatically generates the skeleton of a comment, including documentation for the function itself, as well as its return type. In the current case, the name of the function is pretty much self-explanatory, but oftentimes function arguments may not be and should be documented individually. To illustrate this, let's consider a slightly more interesting function and the comment KDevelop automatically generates:

    Here, the suggested comment already contains all the Doxygen fields for the individual parameters, for example.

    Renaming variables, functions and classes

    Sometimes, one wants to rename a function, class or variable. For example, let's say we already have this:

    We then realize that we're unhappy with the name remove_students and would have rather called it, say, throw_out_students. We could do a search-replace for the name, but this has two drawbacks:

    • The function may be used in more than one file.
    • We really only want to rename this function and not touch functions that may have the same name but are declared in other classes or namespaces.

    Both these problems can be solved by moving the cursor on any of the occurrences of the name of the function and selecting Code -> Rename declaration (or right clicking on the name and selecting Rename Bus::remove_students). This brings up a dialog box where you can enter the new name of the function and where you can also see all the places where the function is actually used:

    Code snippets

    Most projects have pieces of code that one frequently has to write in source code. Examples are: for compiler writers, a loop over all instructions; for user interface writers, checks that user input is valid and if not to open an error box; in the project of the author of these lines, it would be code of the kind

    for (typename Triangulation<dim,spacedim>::active_cell_iterator
           cell = triangulation.begin_active();
         cell != triangulation.end(); ++cell)
      ... do something with the cell ...
    

    Rather than typing this kind of text over and over again (with all the concomitant typos one introduces), the Snippets tool of KDevelop can help here. To this end, open the tool view (see Tools and views if the corresponding button isn't already on the perimeter of your window). Or, go to Window -> Tool views in the top menubar, and turn on Snippets. Then click on the Add repositorybutton (a slight misnomer — it allows you to create a named collection of snippets for source codes of a particular kind, e.g. C++ sources) and create an empty repository. Then click to add a snippet, to get a dialog like the following:

    Note

    The name of a snippet may not have spaces or other special characters because it must look like a normal function or variable name (for reasons that will become clear in the next paragraph). If the name of the snippet does contain spaces, the OK button will become inactive without any further explanation. This has been fixed in recent versions of KDevelop (see KDevelop bug 274299).


    To use a snippet so defined, when you are editing code, you can just type the name of the snippet like you would any other function or variable name. This name will become available for auto-completion — which means that there is no harm in using a long and descriptive name for a snippet such as the one above — and when you accept the suggestion of the auto-completion tooltip (for example by just hitting Enter), the already entered part of the snippets' name will be replaced by the full expansion of the snippet and will be properly indented:

    Note that for this to work, the Snippets tool view need not be open or visible: you only ever need the tool view to define new snippets. An alternative, if less convenient, way to expand a snippet is to simply click on it in the respective tool view.

    Note

    Snippets are much more powerful than just explained. For a full description of what you can do with them, see the detailed documentation of the Snippets tool.

    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 and documents. Furthermore, each such working set is associated with a current session, i.e. we have the relationship shown above. 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 below. 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 shows you which files are currently open in this working set (here: the step-32.cc and step-1.cc files). Clicking on the red minus sign closes the tab for the corresponding file. Maybe more importantly, clicking on the correspondingly named button allows you to close the entire working set at once (i.e. to close all currently open files). The point about closing a working set, however, is that it doesn't just close all files, it actually saves the working set and opens a new, still empty one. You can see this here:

    Note the two symbols to the left of the three mode tabs (the heart and the unidentifiable symbol to its left). Each of these two symbols represents a saved working set, in addition to the currently open working set. If you hover your mouse over the heart symbol, you'll get something like this:

    It shows you that the corresponding working set contains two files and their corresponding project names: Makefile and changes.h. Clicking Load will close and save the current working set (which as shown here has the files tria.h and tria.cc open) and instead open the selected working set. You can also permanently delete a working set, which removes it from the set of saved working sets.

    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")