query_system.docbook

linux下的sourceinsight

</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>
Tracing a sequence of calls in the code base is a common task in code analysis. To facilitate this task, &kapp; offers two mechanisms for visualising the relationships between different functions in a project: 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>
<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>

<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. This menu consists of the following entries:

<variablelist>
<varlistentry>
<term><menuchoice>
<guimenu>Called Functions</guimenu>
<guimenuitem>Show</guimenuitem>
</menuchoice></term>
<listitem><para>Shows all functions called by this one.</para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>Called Functions</guimenu>
<guimenuitem>List/Filter...</guimenuitem>
</menuchoice></term>
<listitem><para>Displays a detailed list of called functions. This list can also be used to select which calling functions to show.</para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>Called Functions</guimenu>
<guimenuitem>Hide</guimenuitem>
</menuchoice></term>
<listitem><para>Removes any functions called by this one. This will also remove any unconnected graph components resulting from the removal of the corresponding nodes.</para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>Calling Functions</guimenu>
<guimenuitem>Show</guimenuitem>
</menuchoice></term>
<listitem><para>Shows all functions calling this one.</para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>Calling Functions</guimenu>
<guimenuitem>List/Filter...</guimenuitem>
</menuchoice></term>
<listitem><para>Displays a detailed list of calling functions. This list can also be used to select which calling functions to show.</para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>Calling Functions</guimenu>
<guimenuitem>Hide</guimenuitem>
</menuchoice></term>
<listitem><para>Removes any functions calling this one. This will also remove any unconnected graph components resulting from the removal of the corresponding nodes.</para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>This Function</guimenu>
<guimenuitem>Find Definition</guimenuitem>
</menuchoice></term>
<listitem><para>Queries the database for the definition of the selected function.</para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>This Function</guimenu>
<guimenuitem>Remove</guimenuitem>
</menuchoice></term>
<listitem><para>Deletes the selected node from the graph.</para></listitem>
</varlistentry>
</variablelist>
</para>

<para>
Another popup menu is displayed when an arrow head is right-clicked:

<variablelist>
<varlistentry>
<term><menuchoice>
<guimenuitem>Open Call</guimenuitem>
</menuchoice></term>
<listitem><para>Opens an editor page at the location of the call represented by this edge.</para></listitem>
</varlistentry>
</variablelist>
</para>

</sect3>

</sect2>

</sect1>