index.docbook

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

<para>
The edit-box above the list of symbols can be used for quick symbol look-ups. Entering text in this box selects the first symbol whose name begins with this text.
</para>

<para>
By default, tags are sorted by to their name in ascending order. Click on a column header to sort the tags according to that column. A triangle to the side of a column name indicates this is the sorting column, and shows the sorting order (ascending or descending.) Once a sorting order is chosen, it becomes the default, and is used for all newly created lists (though not for currently open, unmodified, editor windows.)
</para>

</sect2>

<sect2 id="files-other">
<title>Other File Options</title>

<para>
&kapp;'s <guimenu>File</guimenu> menu includes further options, such as saving, printing and closing files. In addition, specific editors can offer extended features under the <guimenu>Tools</guimenu> menu (e.g., syntax highlighting, indentation, etc.)
</para>

</sect2>

<sect2 id="symbol-completion">
<title>Symbol Completion</title>

<para>
Symbol completion is a convenient feature that enables the user to enter previously declared symbols with fewer key strokes. Since the cross-reference database keeps record of all globally declared symbols, it can be queried for a complete symbol name based on a given prefix.

There are two types of symbol completion: manual and automatic. Manual symbol completion is always available, and can be invoked by the <menuchoice><guimenu>Edit</guimenu><guimenuitem>Complete Symbol</guimenuitem></menuchoice> menu command (or, more conveniently, by pressing <keycombo><keycap>Ctrl</keycap><keycap>Space</keycap></keycombo>). Once a completion request has been issued, &kapp; uses the characters immediately preceding the current cursor position as a prefix, and queries the database for possible completions. These completions are displayed in a list box, which can be browsed using the arrow keys. Pressing <keycap>Enter</keycap> replaces the prefix with the selected symbol. The <keycap>Esc</keycap> key hides the list without completing the symbol.
</para>

<sect3 id="auto-symbol-completion">
<title>Automatic Symbol Completion</title>

<para>
In addition to manual symbol completion, &kapp; can also provide automatic completion based on changes made by the user to the edited source code. Specifically, &kapp; tracks changes to the edited file, and if certain criteria are met, initiates a symbol completion query to the cross-reference database. Once a completion list is displayed, symbol completion behaves in the same way as in the manual case.
</para>

<para>
Automatic symbol completion is configured on a per-project basis. This feature is enabled or disabled via the <guilabel>Use Symbol Auto-Completion</guilabel> check-box in the <guilabel>New Project</guilabel> dialogue (this option can also be changed after a project has been created by invoking the <guilabel>Project Properties</guilabel> dialogue).
</para>

<note>
<para>
For performance reasons, it is highly recommended that automatic symbol completion will be used in conjunction with the inverted-index option.
</para>
</note>

<para>
As mentioned before, &kapp; uses several parameters to decide whether automatic symbol completion should be initiated. These parameters can be configured by clicking on the <guibutton>Options...</guibutton> button in the <guilabel>New Project</guilabel> dialogue (or, later, in the <guilabel>Project Properties</guilabel> dialogue). Clicking this button invokes the <guilabel>Auto-Completion Properties</guilabel> dialogue.

<screenshot>
<screeninfo>The auto-completion properties dialogue</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="autocomp_dlg.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The auto-completion properties dialogue</phrase>
</textobject>
</mediaobject>
</screenshot>

<variablelist>
<varlistentry>
<term><guilabel>Minimum Characters</guilabel></term>
<listitem><para>The minimal length of a symbol for which completion is provided.</para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Delay (ms)</guibutton></term>
<listitem><para>Specifies a time interval that should elapse after the last change to the edited text and before the symbol completion query is executed.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Maximum Entries</guilabel></term>
<listitem><para>The symbol completion list will display at most this number of possible completions. If the number of matched symbols in the database is greater, a message will be displayed (and no symbols will be available).</para></listitem>
</varlistentry>
</variablelist>
</para>

<para>
The main purpose of these parameters is to reduce the load on the system caused by frequent queries to the database. The default values have been tested in various scenarios, and are usually adequate.
</para>

</sect3>

</sect2>

</sect1>

<sect1 id="queries">
<title>The Query System</title>

<para>
The most important task of &kapp; is to execute <application>Cscope</application> queries and display their results. Queries are always performed on the cross-reference database of the active project.
</para>
<para>
&kapp; currently supports the following query types:
<itemizedlist>
<listitem><para>Find all references to a symbol</para></listitem>
<listitem><para>Find a symbol's global definition</para></listitem>
<listitem><para>Find all functions called by a given function</para></listitem>
<listitem><para>Find all functions calling a given function</para></listitem>
<listitem><para>Find a text string</para></listitem>
<listitem><para>Find an EGrep pattern (regular expression)</para></listitem>
<listitem><para>Find a file's path by its name</para></listitem>
<listitem><para>Find all files including a given file</para></listitem>
<listitem><para>Display a call-tree for a given function</para></listitem>
</itemizedlist>
A symbol, as referred to in the above list, may be a function, a global variable, a structure, a union or a type definition.
</para>

<para>
The cross-reference database may become obsolete when source files are modified, resulting in inaccurate (or simply wrong) query results. &kapp; has two ways for refreshing the database, manual and automatic. Manual database rebuilds are available through the <menuchoice><guimenu>Cscope</guimenu><guimenuitem>Rebuild Database</guimenuitem></menuchoice> menu command. Selecting this command will instruct Cscope to immediately rebuild the cross-reference database.
</para>

<para>
Automatic database rebuilds are enabled per-project, an option controlled by the <guilabel>Project Properties</guilabel> dialogue. Since a database rebuild may be a time and resource-consuming operation, &kapp; does not invoke this procedure after every change to the source code. Instead, changes to the code initiate a timer (whose value is determined by the user in the <guilabel>Project Properties</guilabel> dialogue). Once this timer elapses, &kapp; instructs Cscope to rebuild the database. Code modifications that occur while the timer is running reset its value.
</para>

<para>
A project's database is also updated whenever that project is opened.
</para>

<sect2 id="query-run">
<title>Running a Query</title>

<para>
A query can be started in one of three ways:
<orderedlist>
<listitem><para>The main menu</para></listitem>
<listitem><para>Keyboard shortcuts</para></listitem>
<listitem><para>The editor's context-menu</para></listitem>
</orderedlist>
</para>

<para>
To start a query from the main menu, select the desired query type from the <guimenu>Cscope</guimenu> menu. This will display a dialogue box prompting you for the query's text. The text to enter depends upon the query's type.
<screenshot>
<screeninfo>The query dialogue</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="query_dlg.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The query dialogue</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>

<variablelist>
<varlistentry>
<term><guilabel>Type</guilabel></term>
<listitem><para>The type of query to perform. This value defaults to the requested type, by can be changed by selecting a different entry in the list.</para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Symbol</guibutton></term>
<listitem><para>Enter the symbol to query in this box. The default value is the symbol currently under the editor's cursor (if any).</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Search for a Sub-String</guilabel></term>
<listitem><para>Mark this check-box to treat the entered text as part of a symbol (will query all symbols containing the entered text as a sub-string).</para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>OK</guibutton></term>
<listitem><para><action>Runs the query.</action></para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Hint</guibutton></term>
<listitem><para><action>Provides a list of possible matches to the entered symbol.</action></para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Cancel</guibutton></term>
<listitem><para><action>Closes the dialogue without running the query.</action></para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Suggested Symbols</guilabel></term>
<listitem><para>A list of known symbols matching the text in the symbol box.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Hint Options</guilabel></term>
<listitem><para>These buttons affect the way text in the symbol box is matched to fill the suggested symbols list.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Symbols Beginning With...</guilabel></term>
<listitem><para>Choose this option to match symbols starting with the given text.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Symbols Containing...</guilabel></term>
<listitem><para>Choose this option to match symbols containing the given text.</para></listitem>
</varlistentry>
</variablelist>

<para>
Any text selected in the editor when a query is requested will be automatically copied to the query dialogue. If no text is selected, KScope attempts to guess the requested symbol from the current location of the cursor.
</para>

<para>
Each menu item is associated with a keyboard shortcut. These shortcuts follow the convention of using the <keycap>Ctrl</keycap> key, together with the numeric query index used by <application>Cscope</application> (this should allow experienced <application>Cscope</application> users to get quickly acquainted with &kapp;). For example, use <keycombo><keycap>Ctrl</keycap><keycap>1</keycap></keycombo> to look-up a symbol's definition. The call-tree is an exception to this convention (as it is not a native <application>Cscope</application> query). See the <link linkend="commands">Command Reference</link> for a complete listing of all menu and shortcut options.
</para>

<note>
<para>
The EGrep query is invoked using <keycombo><keycap>Ctrl</keycap><keycap>5</keycap></keycombo>, as <keycombo><keycap>Ctrl</keycap><keycap>6</keycap></keycombo> is already used by &kate;.
</para>
</note>

<para>
The third way of starting a query is by right-clicking inside an editor window. This invokes the context-menu, that displays the same options as in the <guimenu>Cscope</guimenu> section of the main menu. Using a context-menu is easy when combined with a symbol selection in the editor: position the text cursor inside a symbol, and then right click to display the context-menu.
</para>

<para>
A query may take some time to complete, depending on its type and the size of the project. &kapp; displays a progress indicator during long queries. If <application>Cscope</application>'s <option>-v</option> command line option is used, this progress indication is accurate, and displays the percentage of files already searched in. In case this option was omitted (e.g., if working with a version of <application>Cscope</application> prior to 15.5), &kapp; will present a dummy progress bar, used simply to indicate that a query is running, and that &kapp; has not frozen. Please refer to the section <link linkend="configuration">Configuring &kapp;</link> for more information.
</para>

</sect2>

<sect2 id="query-window">
<title>The Query Results Window</title>

<para>
When a query has terminated, its output is displayed in the query window, at the bottom of &kapp;'s main window. This window can manage several result pages simultaneously, with each page holding the results of a different query. Each page is associated with a tab that displays a summary of the query that generated these results. This tab is used to bring the results page forward, and is also associated with several page operations through a close button and a context menu.
</para>

<para>
By default, query results are displayed in the currently active page, overriding any prior contents. To keep a results page unchanged, the page needs to be "locked". Locked query pages are never overridden. The contents of these pages are also saved when the project is closed, and are restored when the project is reopened. To lock a project, either click the <guibutton>Lock/Unlock Query</guibutton> toggle button to the right of the query window, or use the context menu (available by right-clicking the page's tab.) The same methods can also be used to unlock a query.
</para>

<para>
New query pages can also be created explicitly, by using either the <guibutton>New Query</guibutton> button to the right of the query window, or the context menu available by right-clicking the tab area of the query window.
</para>

<para>
Each entry in a query results page represents a symbol or text string that complies to the search criteria. The entry is composed of four sections:
<itemizedlist>
<listitem><para>The path of the file in which the symbol or string were found</para></listitem>
<listitem><para>The name of the function containing the symbol or text string</para></listitem>
<listitem><para>The line number in this file</para></listitem>