index.docbook

This a source insight software in Linux. It s is similar to the source insight software for windows.

<listitem><para>The text of this line</para></listitem>
</itemizedlist>
</para>

<para>
By default, results are sorted according to the file name. This can be changed by clicking the column headers of the results list.
</para>

<para>
The entries in a query results page can be used as shortcuts to editing the line in which the symbol or text string were found (or lines in that vicinity.) This is done by either double-clicking a result entry, or by selecting this entry and hitting the <keycap>Enter</keycap> key. As a result, &kapp; will open an editor window displaying the file referred to in the selected entry, and set the cursor to the beginning of the appropriate line.
</para>

<para>
If a query results in a single entry, this entry is automatically selected for display.
</para>

<para>
The results of a query can be refreshed by clicking the <guibutton>Refresh Query</guibutton> button to the right of the query window, or by using the context menu. This command is useful to rerun queries after the database has changed (such as after a <guimenuitem>Rebuild Database</guimenuitem> command had been issued).
</para>

<para>
Query results pages can be closed by either clicking the icon on their tab, by clicking on the <guibutton>Close Query</guibutton> button to the right of the query window, by using the context menu (available by right-clicking the page's tab), or by selecting the <menuchoice><guimenu>Cscope</guimenu><guimenuitem>Close Query</guimenuitem></menuchoice> main-menu command.
</para>

<para>
If the query window is not visible when a query is executed, it is temporarily displayed, and then re-hidden when the user selects an entry for viewing.
</para>

</sect2>

<sect2 id="result-options">
<title>Query Results Options</title>

<para>
Right-clicking a query result in either a query window or a call-tree dialogue displays a context menu. This menu includes several actions that can be used to either extract information or fine tune these results.
</para>

<para>
<variablelist>
<varlistentry>
<term><menuchoice>
<guimenuitem>Copy File</guimenuitem>
</menuchoice></term>
<listitem><para><action>Copies the file path part of a result record to the clipboard</action> (the copy commands are available depending on the position of the mouse cursor).</para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenuitem>Copy Function</guimenuitem>
</menuchoice></term>
<listitem><para><action>Copies the function name part of a result record to the clipboard.</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenuitem>Copy Line</guimenuitem>
</menuchoice></term>
<listitem><para><action>Copies the line number part of a result record.</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenuitem>Copy Text</guimenuitem>
</menuchoice></term>
<listitem><para><action>Copies the function name part of a result record to the clipboard.</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenuitem>Filter...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Displays the Filter Query Results dialogue.</action> See the section <link linkend="filter-results">Filtering Query Results</link> for a detailed description of this option.</para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenuitem>Show All</guimenuitem>
</menuchoice></term>
<listitem><para><action>Displays all query results.</action> This option reverts the effects of any filters previously applied.</para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenuitem>Remove Item</guimenuitem>
</menuchoice></term>
<listitem><para><action>Permanently removes a record from a query results window.</action> This action can only be undone by rerunning the query.</para></listitem>
</varlistentry>
</variablelist>
</para>
</sect2>

<sect2 id="filter-results">
<title>Filtering Query Results</title>

<para>
It is often the case the a query results in an abundance of information. &kapp; allows the user to filter query results in order to show only those results that the user finds interesting, an action referred to as "Filtering". Filtering is done by matching patterns on any of the query record fields (file name, function, line number and line text).
</para>

<para>
The Filter Query Results dialogue is invoked from the query context menu (see <link linkend="result-options">Query Result Options</link>).
<screenshot>
<screeninfo>The Filter Query Results dialogue</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="query_filter.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The Filter Query Results dialogue</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>

<variablelist>
<varlistentry>
<term><guilabel>Search For</guilabel></term>
<listitem><para>Enter the pattern to match in the query result records. This pattern is interpreted based on the Search Type selection.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Search In</guilabel></term>
<listitem><para>The record field in which to look for the search pattern. By default, this is the field over which the context menu was invoked.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Search Type</guilabel></term>
<listitem><para>Defines the way in which the pattern should be interpreted.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Plain Text</guilabel></term>
<listitem><para>Choose this option to treat the pattern as a simple text string to search for.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>RegExp</guilabel></term>
<listitem><para>Choose this option to treat the pattern as a regular expression.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Simplified RegExp</guilabel></term>
<listitem><para>Choose this option to treat the pattern as a simplified regular expression (a-la file expressions in a Unix shell).</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Case Sensitive</guilabel></term>
<listitem><para>Check for a case sensitive search, uncheck for a case insensitive one.</para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>OK</guibutton></term>
<listitem><para><action>Filters the query results based on the given information.</action></para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Cancel</guibutton></term>
<listitem><para><action>Closes the dialogue without filtering the results.</action></para></listitem>
</varlistentry>
</variablelist>

</sect2>

<sect2 id="call-tree-graph">
<title>Displaying Call-Trees and Graphs</title>

<para>
A common task in code analysis is the trace of a call sequence inside a project. To facilitate this task, &kapp; offers two mechanisms for visualising the relationships between different functions in a given code base: the Call-Tree and the Call-Graph. Both of these mechanisms are provided through the <guilabel>Call Graph Dialogue</guilabel> which can be invoked on a function name in a similar way to a regular <application>Cscope</application> query.
</para>

<sect3 id="call-tree">
<title>Call Trees</title>

<para>
The Call-Tree has two modes, "Called Functions" and "Calling Functions". In the first case, the call chain starts with a root function, and goes on to display all the functions it references. The second mode shows all functions calling the root function. In both modes each function in the second level can be further expanded to show functions calling it (or functions it calls). This process can be further applied to functions in the third level, an so on.
</para>

<para>
Both modes use a standard tree widget to display the call chain. Expanding a function to the next level is performed by clicking the plus sign to the left of the function's name. Double-clicking a function (or selecting it and then hitting <keycap>Enter</keycap>) points the editor to the call's actual text. Right-clicking an entry provides a popup-menu with further options, similar to the query results menu (see <link linkend="result-options">Query Result Options</link>).
</para>

<para>
<screenshot>
<screeninfo>A Call-Tree</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="call_tree.png" format="PNG" />
</imageobject>
<textobject>
<phrase>A Call-Tree in "Called Functions" mode</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>

</sect3>

<sect3 id="call-graph">
<title>Call Graphs</title>

<para>
A Call-Tree often misses the true nature of a call sequence, since many such sequences contain loops, that is, functions calling back functions that precede them in the sequence. (Recursive calls provide a natural example for such a state of affairs.) A Call-Graph provides a more accurate description of the relationships between functions by depicting calls using a directed graph. Each node in the graph represents a function and each edge a function call. An edge is directed from the caller to the callee.
</para>

<para>
When a Call-Graph is created, it only displays a single function. Right-clicking on this function opens a popup menu that allows the user to display or hide either the functions called by or calling to this one.
</para>

<para>
<screenshot>
<screeninfo>A Call-Graph</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="call_graph.png" format="PNG" />
</imageobject>
<textobject>
<phrase>A Call-Graph</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>

</sect3>

</sect2>

</sect1>

<sect1 id="position-history">
<title>Position History</title>

<sect2 id="pos-hist-intro">
<title>Introduction</title>

<para>
In its capacity as a source code browser, &kapp; allows the user to quickly browse through different files and lines within these files. While browsing the code, a need often arises to go back to a location visited in the past. To achieve this task, &kapp; sports a sophisticated position history mechanism, which not only allows the user to go back and forth between visited locations, but also to save and restore snapshots of "tours" through the code, as well as other manipulations of the position history. For the sake of both consistency and ease of use, recorded position history is viewed and handled in a way similar to the query results system.
</para>

<note>
<para>
In the context of this section, a "jump" is defined as the action taken by &kapp; after a query result record is selected for viewing (either by the user from a query page or a call-tree window, or automatically).
</para>
</note>

<para>
Position history records appear in pages incorporated into the Query Results window. These pages can be immediately distinguished from query results by their tab labels, which always read "History X" (where X is a unique number that identifies the page). Other than that the two types of pages look very much the same: a history page is composed of a list of records, each comprised of the following fields:
<itemizedlist>
<listitem><para>File</para></listitem>
<listitem><para>Function</para></listitem>
<listitem><para>Line</para></listitem>
<listitem><para>Text</para></listitem>