index.docbook

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

<listitem><para><action>Displays the symbol auto-completion configuration dialogue.</action> This button is only enabled if the symbol auto-completion is selected (see <link linkend="auto-symbol-completion">Automatic Symbol Completion</link> for a description of this dialogue).</para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Create</guibutton></term>
<listitem><para><action>Accepts the values entered in the dialogue, and creates a new project.</action> If any mandatory values were omitted, or not entered correctly, the user is prompted.</para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Cancel</guibutton></term>
<listitem><para><action>Closes the dialogue without creating a new project.</action></para></listitem>
</varlistentry>
</variablelist>
</para>
<para>
Note that this dialogue is intended for creating an empty project only, and has nothing to do with the actual source files of the project. This task is left to the <guilabel>Project Files</guilabel> dialogue.
</para>
</sect2>

<sect2 id="project-files">
<title>Adding and Removing Project Files</title>

<para>
The project's list of source files is maintained by the <guilabel>Project Files</guilabel> dialogue. This dialogue allows the user to add source files to a project, or remove files currently included in it. The dialogue is invoked automatically after a new project has been created, or manually by selecting the <menuchoice><guimenu>Project</guimenu><guimenuitem>Add/Remove Files...</guimenuitem></menuchoice> command from the main menu.
</para>
<screenshot>
<screeninfo>The Project Files dialogue</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="project_files.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The Project Files dialogue</phrase>
</textobject>
</mediaobject>
</screenshot>
<variablelist>
<varlistentry>
<term><guilabel>File Path</guilabel></term>
<listitem><para>Displays a list of all source files included in the project. Note that when adding and removing files, the project itself is not modified until the <guibutton>OK</guibutton> button is clicked.</para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Filter</guibutton></term>
<listitem><para>Hides all files whose path names do not include the text entered in the edit-box to the left of the button. This can simplify the task of finding files in the project. The filter text can be any simplified regular expression (as given to file commands in a shell).</para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Show All</guibutton></term>
<listitem><para>Reveals any files formerly hidden with the <guibutton>Filter</guibutton> button.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Add</guilabel></term>
<listitem><para>All buttons in this group add files to the current project.</para>
<variablelist>
<varlistentry>
<term><guibutton>Files...</guibutton></term>
<listitem><para><action>Adds user-selected files to the current project.</action></para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Directory...</guibutton></term>
<listitem><para><action>Adds all source files in a directory to the current project.</action> Source files are scanned according to the file-types associated with the project. Note that sub-directories are not scanned for files.</para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Tree...</guibutton></term>
<listitem><para><action>Adds all source files in a selected directory and its sub-directories to the current project.</action> Source files are scanned according to the file-types associated with the project.</para></listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Remove</guilabel></term>
<listitem><para>All buttons in this group remove files from the current project.</para>
<variablelist>
<varlistentry>
<term><guibutton>Selected</guibutton></term>
<listitem><para><action>Removes all selected files from the current project.</action> Files can be selected for removal by clicking their path name in the file list. The <keycap>Ctrl</keycap> key can be used to select multiple files, and the <keycap>Shift</keycap> key can be used to select ranges of files.</para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Directory...</guibutton></term>
<listitem><para><action>Removes all source files in a directory from the current project.</action> Note that sub-directories are not included.</para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Tree...</guibutton></term>
<listitem><para><action>Removes all source files in a directory and any of its sub-directories from the current project.</action></para></listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><guibutton>OK</guibutton></term>
<listitem><para><action>Accepts the new list of source files, and updates the project.</action></para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Cancel</guibutton></term>
<listitem><para><action>Closes the dialogue without modifying the list of project files.</action></para></listitem>
</varlistentry>
</variablelist>
<para>
Once the project's file list has changed (either when files are first added to the project, or upon any subsequent modification), &kapp; informs <application>Cscope</application> to rebuild the cross-reference database.
</para>

</sect2>

<sect2 id="project-open">
<title>Opening an Existing Project</title>

<para>
Existing projects can be opened using the <menuchoice><guimenu>Project</guimenu><guimenuitem>Open...</guimenuitem></menuchoice> menu command. Choosing this command invokes the <guilabel>Open Project</guilabel> dialogue, which allows the user to select the project to open.
</para>
<screenshot>
<screeninfo>The Open Project dialogue</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="project_open.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The Open Project dialogue</phrase>
</textobject>
</mediaobject>
</screenshot>

<variablelist>
<varlistentry>
<term><guilabel>Project Path</guilabel></term>
<listitem><para>The full path of the project directory.</para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Find...</guibutton></term>
<listitem><para><action>Launches a file-system browser that helps the user locate the project's directory.</action> This is done by browsing for the project's configuration file (cscope.proj) which resides in the project's directory.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Recent Projects</guilabel></term>
<listitem><para>Displays a list of recently-opened projects. Clicking a list item copies its path to the Project Path edit-box, while double-clicking an item opens the project.</para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Remove</guibutton></term>
<listitem><para><action>Removes an entry from the list of recently-opened projects.</action></para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Open</guibutton></term>
<listitem><para><action>Opens the project whose directory is set in the Project Path edit-box.</action></para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Cancel</guibutton></term>
<listitem><para><action>Closes the dialogue without opening a project.</action></para></listitem>
</varlistentry>
</variablelist>

<para>
When a project is closed, it saves session information, such as source files being edited and the contents of locked queries. The session is restored when a project is opened.
</para>
<para>
After the project has been opened, &kapp; will invoke <application>Cscope</application>, which, in turn, will check whether any files have been modified since the last time the project had been closed. If any files have been changed, <application>Cscope</application> will rebuild the cross-reference database.
</para>

</sect2>

<sect2 id="project-prop">
<title>Changing Project Properties</title>

<para>
The properties of an open project can be changed by choosing the <menuchoice><guimenu>Project</guimenu><guimenuitem>Properties...</guimenuitem></menuchoice> menu command. This command invokes the <guilabel>Project Properties</guilabel> dialogue, which is similar to the <guilabel>New Project</guilabel> dialogue, except that the name and path of the project cannot be changed.
</para>

<para>
See the <link linkend="project-create">New Project dialogue</link> for a description of the available project options.
</para>

</sect2>

<sect2 id="projects-temp">
<title>Temporary Projects</title>

<para>
Temporary projects are created when a user opens a cscope.out file directly. This option is useful for working on projects created by some other <application>Cscope</application> front-end (<application>Cscope</application>'s ncurses interface, Vi, Emacs, etc.), or simply using <application>Cscope</application>'s <option>-b</option> command-line parameter.
</para>

<para>
To open a database file, use the <menuchoice><guimenu>Project</guimenu><guimenuitem>Open Cscope.out...</guimenuitem></menuchoice> menu command. If the file is a valid <application>Cscope</application> cross-reference database, &kapp; will invoke <application>Cscope</application> using this file, and will be ready to accept queries on the database. Cscope.out files can also be opened through the command line, which means that you can simply drag a Cscope.out file, and drop it over &kapp;'s programme icon.
</para>

<para>
Note, however, that most project management options provided by &kapp; will not be available for temporary projects: the file list for the project will be empty, users will not be able to add or remove files, and the project properties dialogue will not be available. You will also need to rebuild the database manually when making any changes. &kapp;'s rebuild command assumes the database has been updated, and only re-runs <application>Cscope</application>.
</para>

</sect2>

</sect1>

<sect1 id="editing">
<title>Editing Source Files</title>

<sect2 id="editor">
<title>The Editor</title>

<para>
&kapp; does not provide its own editor. Instead, it utilises KDE's KTextEditor infrastructure to embed the system's default editor. This means that any editor that supports the KTextEditor interface (e.g., &kate;, <application>KVim</application>) can be used with &kapp;. The editor is defined in KDE's control centre.
In any matter related to operating or configuring the editor, please refer to the manual of the editor itself.
</para>

</sect2>

<sect2 id="open-file">
<title>Opening Files for Editing</title>

<para>
Files are usually opened for editing as a part of a project. However, &kapp; enables the user to edit an occasional file that is not related to the project, through the <menuchoice><guimenu>File</guimenu><guimenuitem>Open...</guimenuitem></menuchoice> menu command. Note, however, that query results on files outside a project are meaningless.
</para>

<para>
Once a project has been opened, the list of all project files appears in the file list, to the right of the editing area. Each file entry in the list shows the file's type, its name, and its full path. Files are opened by either double-clicking their entry in the list, or by selecting the entry, and hitting the <keycap>Enter</keycap> key. The edit-box above the list can be used to quickly search for a file. Typing in this box selects the first list entry whose file name begins with the entered text.
</para>

<para>
Files can also be opened through the file tree, which shares its location with the project's file list (using a tabbed-window.) The file tree displays all files in the system, starting with a specific root directory. A root directory for the file tree is set on a per-project basis by using the <guibutton>Set Root...</guibutton> button. The file tree also sports a <guibutton>Find File...</guibutton> button for launching the file search <application>Cscope</application> query.
</para>

<note>
<para>
To decrease the loading time of projects, files and directories are only added to the tree when their parent directory is expanded. Therefore directories will not be marked as expandable by default, even if they are not empty.
</para>
</note>

<para>
For each file opened, &kapp; creates a separate editor window, inside the editing area. Each editor is associated with a tab, displaying the name of the edited file. Thus &kapp; provides a convenient multi-editor environment. You can switch between open files by selecting their respective tabs, or by using the <guimenu>Window</guimenu> menu.
</para>

<para>
To work on a new file, the user first needs to create it using the <menuchoice><guimenu>File</guimenu><guimenuitem>New...</guimenuitem></menuchoice> menu command. This opens an empty editor, that is not associated with a file name or path. Upon saving the work in this new editor, &kapp; will prompt the user for a file name and directory. Note that this does not add the file to the project. The user still needs to invoke the <guilabel>Project Files</guilabel> dialogue and add the new file to an open project.
</para>

</sect2>

<sect2 id="file-tags">
<title>File Tags</title>

<para>
In addition to being a front-end to <application>Cscope</application>, &kapp; also uses <application>Ctags</application> to display a list of symbols defined in the current file. Each editor window is added a list of these symbols to its left. This list displays the name of a symbol, its type (as a graphic shape), and the line where it is defined. Double-clicking a symbol, or selecting it and hitting the <keycap>Enter</keycap> key, sets the cursor to the beginning of this symbol's definition line. The list of symbols is refreshed whenever a file is saved.
</para>