add more spacing

[personal-kdebase.git] / runtime / doc / userguide / programs-and-documents.docbook

<chapter id="programs-and-documents">

<title>Programs and Documents</title>

<sect1 id="programs-launching">

<sect1info>
<author>
<firstname>Robert</firstname>
<surname>Stoffers</surname>
</author>
</sect1info>

<title>Launching Programs</title>

<para>&kde; offers a varying number of ways to launch programs. You may:</para>
        <itemizedlist>
        <listitem>
                <para>Simply select the relevant item in the &kmenu;.</para>
        </listitem>
        <listitem>
                <para>Run the program from &konsole;, or by clicking the &kmenu; and choosing <guimenuitem>Run Program</guimenuitem> (while you still might prefer the quick keyboard shortcut, which is simply <keycombo action="simul">&Alt;<keycap>F2</keycap></keycombo>).</para>
        </listitem>
        <listitem>
                <para>Create a shortcut on the desktop or use &kicker;'s quick launcher.</para>
        </listitem>
</itemizedlist>

<para>The &kmenu; functions much like the Start menu of &Windows;, however
it breaks programs up by what they do. Programs on the &kmenu; are broken
into category menus, such as <guisubmenu>Multimedia</guisubmenu> and
<guisubmenu>Office</guisubmenu>. Under these category menus there are
subcategory menus, such as <guisubmenu>Sound</guisubmenu>,
<guisubmenu>Video</guisubmenu> and <guisubmenu>Graphics</guisubmenu>. Under
the subcategory menus lie program launchers, which, when clicked on, launch
the associated application.</para>

<para>Depending on the program, there may not be a launcher in the &kmenu;.
To search your hard drive for more applications, click the &kmenu;, choose
<guimenuitem>Run Command</guimenuitem> and type
<userinput><command>kappfinder</command></userinput>. In
&kappfinder;, click <guibutton>Scan</guibutton>, and the hard drive will be
searched for programs. Click the checkbox next to each program to be added
to the &kmenu;, and click <guibutton>Apply</guibutton> and
<guibutton>Close</guibutton>. The &kmenu; now will have new program
launchers under the relevant category menus.</para>

<para>Launchers to programs may also be placed on the desktop. To create a
new launcher, <mousebutton>right</mousebutton> click on the desktop, and
choose <menuchoice><guimenu>Create
New</guimenu><guimenuitem>Link to
Application</guimenuitem></menuchoice>. On the &kdesktop; properties dialog
box, type in the name of the program on the <guilabel>General</guilabel>
tab. You may also wish to choose a custom icon by clicking on the gear icon.
Click the <guilabel>Application</guilabel> tab and type a short sentence
about the program in the <guilabel>Description</guilabel> textbox. In the
<guilabel>Command</guilabel> textbox, type the name of the program (case
sensitive), and any command line options you wish to use. Choose
<guibutton>OK</guibutton>, and your new program launcher will be created on
your desktop.  Simply click on the new launcher on the desktop and the
 associated program will run.</para>

<para>To launch a program using &konsole;, click the &kmenu; and choose
<menuchoice><guisubmenu>System</guisubmenu><guisubmenu>Terminals
</guisubmenu><guimenuitem>Konsole</guimenuitem></menuchoice>. Once &konsole;
appears on the screen, simply type the name of the program you wish to
launch (remembering that <application>bash</application>, the command language interpreter that &konsole; uses by default, is case-sensitive) and press
<keycap>Enter</keycap>. If you are unsure about the name of a program, type
the first few letters then press the &Tab; key on your keyboard. By pressing
&Tab;, <application>bash</application> (through &konsole;) will try to guess the name of the program you wish to
launch. If it finds more than one matching program, a list of
 matching programs will be printed on the screen. Type the name of the
 program from the list and press <keycap>Enter</keycap> to launch.</para>

<para>Whichever way you choose, launching a program is a simple affair with
&kde;. From the &kmenu;, to &konsole;, all your programs are just a few
clicks or key-presses away.</para>

<!-- Add links to "further reading" here -->
<itemizedlist>
<title>Related Information</title>
<listitem><para>Check the &kicker; handbook for more information on enabling or disabling the &kmenu;, adding applications to the quick launch, or on organizing the categorization of the applications in the &kmenu;. You can view the &kicker; handbook either via the &khelpcenter; or by using &konqueror;'s KIOslave by typing <userinput>help:/kicker</userinput> in the Location toolbar.</para>
</listitem>
</itemizedlist>



</sect1>

&programs-controlling;

<sect1 id="programs-save-open">

<sect1info>
<author>
<personname>
<firstname>Christian</firstname>
<surname>Weickhmann</surname>
</personname>
<email>christian.weickhmann@gmx.de</email>
</author>
</sect1info>


<title>Opening and Saving Files</title>
<!-- TODO: Convert this whole thing to an image with callouts. It -->
<!-- should be much nicer that way. -->


<para>&kde; provides a unified way to open or save files via the file
dialog. In almost every &kde; program you will find a
<menuchoice><guimenu>File</guimenu><guimenuitem>Open</guimenuitem>
</menuchoice> and <menuchoice><guimenu>File</guimenu>
<guimenuitem>Save</guimenuitem></menuchoice> (and/or <guimenuitem>Save
As...</guimenuitem>) entry.</para>

<sect2 id="file-dialog">
<title>The File Dialog</title>

<!--
<screenshot> 
<screeninfo>The &kde; <quote>Open File</quote> dialog</screeninfo> 
<mediaobject> 
<imageobject> 
<imagedata fileref="open-file-dialog.png" format="PNG"/> </imageobject> 
<textobject> 
<phrase>The &kde; <quote>Open File</quote> dialog</phrase> 
</textobject> 
<caption> 
<para>The &kde; <quote>Open File</quote> dialog</para> 
</caption> 
</mediaobject> 
</screenshot> 
-->
<screenshot>
<mediaobjectco>
<imageobjectco>
<areaspec units="calspair">
<area id="navigation-area-co" coords="1 1"/>
<area id="icon-view-co" coords="1 1"/>
<area id="bottom-area-co" coords="1 1"/>
<area id="quick-access-co" coords="1 1"/>
<area id="preview-area-co" coords="1 1"/>
</areaspec>
<imageobject>
<imagedata fileref="open-file-dialog.png" format="PNG"/>
</imageobject>
</imageobjectco>
</mediaobjectco>
</screenshot>

<!-- ====================================================================== 

<calloutlist>

<callout arearefs="pt-first-channel-1"><para>This is called the <interface>Input Line</interface>.  To send a message to everyone in the channel, type the message here and press &Enter;.
 Your message, as well as everyone else's messages appear in the channel scroll above.
 Each message is preceded by the time and user's &nickname;.</para></callout>


</calloutlist>


 ====================================================================== -->
<para>This dialog consists of between three and five areas. The
top area is where you find the navigation and configuration functions. The
main area (in the middle) is where all your files are being displayed as
icons. This is called an icon view. The bottom area is where you can edit
filename or filter expressions and say <guibutton>Save</guibutton> or
<guibutton>Open</guibutton>.</para>

<para>In addition to that you can add two even more sophisticated areas:
the <link linkend="quick-access">Quick Access Navigation Panel</link> and
the <link linkend="preview-area">Preview Panel</link>.</para>

<calloutlist>

<callout arearefs="navigation-area-co">

<para>Next to the three navigation buttons (one directory
<guiicon>up</guiicon>, <guiicon>back</guiicon> and
<guiicon>forward</guiicon>) and the <guiicon>new folder</guiicon> button
there is the <guiicon>bookmarks</guiicon> menu. Here you can mark any folder
you visit often to find it quickly. The <guiicon>wrench</guiicon> icon holds
the different functions to sort your files by name, date or size and to
enable the two extra panels mentioned above. Next to it you can type the
directory and choose (on the very right side) the encoding.</para>
</callout>


<callout arearefs="icon-view-co">

<para>You'll find the icon view in the middle of the dialog. You will find
most of the navigation functions in the context menu by clicking on the
items or the background with the <mousebutton>right</mousebutton> mouse
button.</para>

</callout>

<callout arearefs="bottom-area-co">


<para>The bottom of the dialog consists of the address field holding the
file name you chose or typed in and the maybe most powerful tool: The
filter. Here you can make the icon view display only items that match the
criteria you define. Try filtering files whose names contain
<quote>air</quote> by typing <userinput>*air*</userinput> into the filter
field.</para>

</callout>

<callout arearefs="quick-access-co">

<anchor id="quick-access"/>

<para>The Quick Access Panel (activate it by typing the
<keycap>F9</keycap> key on your keyboard or through the wrench icon on top
of the dialog) provides configurable shortcuts  to frequently used
locations on your hard drive or even on the Internet. There are several
preconfigured locations such as your home directory. Try right clicking on
any item to configure it or to empty space to add a new entry. You will be
shown a context menu. Here you can choose the icon size and to add, modify
or rename any entry. Choose <guimenuitem>Add Entry</guimenuitem> and you
will see a window containing anything you need: Type your description, enter
the location (or choose it via the dialog opening by clicking on the
folder symbol), choose a symbol from a vast variety in the symbol dialog
opening when you click on the predefined icon (usually a simple folder
symbol).</para>

</callout>

<callout arearefs="preview-area-co">

<anchor id="preview-area"/>
<para>The Preview area (activate it by typing the <keycap>F11</keycap>
key on your keyboard or via the wrench icon on top of the dialog)
makes it easy to preview almost any file on your filesystem. Images
will be displayed as thumbnails. Usually also sound files (such as
MP3, Ogg or Wave-Files), text files (among them raw text, PDF and
&HTML;) and even video files (MPG, AVI and so on) will be
previewed.</para>

<note><para>Note that large files might take a long time to be previewed
(&eg; scaled down if they are large images). You can disable automatic
previews by unselecting <guilabel>Automatic Preview</guilabel> below the
preview. You can still preview individual files: just click <guibutton>Preview</guibutton>. You can also disable previews for files above a certain
size. Go to &kcontrolcenter;,  choose <menuchoice><guilabel>KDE
components</guilabel><guilabel>File manager</guilabel></menuchoice>, go to
the <guilabel>Preview and Metafiles</guilabel> tab and change the
<guilabel>Maximum Filesize</guilabel> value.</para></note>

</callout>
</calloutlist>

<!-- Add links to "further reading" here -->
<!--<itemizedlist>
<title>Related Information</title>
<listitem><para>to be written</para>
</listitem>
</itemizedlist>-->


 </sect2>


</sect1>

<sect1 id="configuring-programs">
<sect1info>
<authorgroup>
<author>
&Philip.Rodrigues;
</author>
</authorgroup>
</sect1info>

<title>Configuring Programs</title>

<sect2 id="configure-kapp">
<title>Application Configuration</title>
<!-- FIXME: Make a more friendly title -->
<indexterm><primary>Configuration</primary></indexterm>
<indexterm><primary>Customization</primary></indexterm>

<para>&kde; applications are intended to be as useful and usable as
possible <quote>out of the box</quote>, but they also offer a wide
range of options which you can change to make &kde; work for you. As
well as the settings which affect the whole of &kde; (see <xref
linkend="control-center"/>), each application has a set of
configuration options, which you can access using the menu option
<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure
<replaceable>Application</replaceable></guimenuitem>
</menuchoice>. This is the same for all &kde; applications, which
makes it easy to find the configuration dialog for an
application.</para>

<!-- TODO: Screenie of a typical config dialog -->

<para>On the left of the configuration dialog is a list of
sections. Clicking on one of these sections displays the configuration
page for that section on the right-hand side of the dialog. You can
change these options to fit your preferences.</para>

<para>When you have made the changes you want, you can click on
<guibutton>OK</guibutton> to save your changes and close the
configuration dialog. If you want to see the effect of your changes,
but not close the configuration dialog, click on the
<guibutton>Apply</guibutton> button. This is useful if you aren't sure
about the change you've made, and might want to change back, because
the dialog is still open, ready for you to do so.</para>

<para>If you decide that you don't want to keep the changes you've
made, just click <guibutton>Cancel</guibutton> to close the dialog
without saving your changes.</para>

</sect2>

<sect2 id="configure-shortcuts">
<title>Configuring Keyboard Shortcuts</title>

<indexterm><primary>Shortcuts</primary></indexterm>
<indexterm><primary>Keybindings</primary></indexterm>

<para>Most &kde; applications offer keyboard shortcuts for the main
actions in the application. If you find that you don't like the
default keyboard shortcuts, or that they conflict with the shortcuts
of another application (maybe one that's not part of &kde;), you can
change them with the
<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure
Shortcuts...</guimenuitem>
</menuchoice> menu entry. This brings up the
<guilabel>Configure Shortcuts</guilabel> dialog for the
application. As an example of how to use this dialog, let's add a
shortcut for the <guimenuitem>Send Link Address...</guimenuitem> action to
&konqueror;, so that we can email the locations of interesting pages
to friends just by hitting a key (or two): </para>
<procedure>
<step><para>Open the <guilabel>Configure Shortcuts</guilabel>
dialog in &konqueror;, as described above.</para>
</step>
<step><para>Click on the <guilabel>Send Link Address...</guilabel> item
in the main listbox (it's near the bottom, in the
<guilabel>Konqueror</guilabel> section).</para>
</step>
<step><para>In the <guilabel>Shortcut for Selected
Action</guilabel> panel, select <guilabel>Custom</guilabel>, since we
are going to give this action a keyboard shortcut that we have chosen.</para>
</step>
<step><para>A small shortcut entry dialog pops up. Just hit
<keycombo action="simul">&Ctrl;<keycap>E</keycap>
</keycombo> (or whatever you want to change the shortcut to), and the
dialog disappears. The <quote>key</quote> icon in the
<guilabel>Configure Shortcuts</guilabel> dialog now shows the new
shortcut.</para>
</step>
<step><para>If you made a mistake, or change your mind about what
to use as the shortcut, just click on the key icon showing the current
shortcut. The shortcut entry dialog reappears, and you can press the
key combination for the shortcut you want.</para>
</step>
</procedure>

<!-- TODO: Screenie -->

</sect2>

<sect2 id="configure-notifications">
<title>Configuring Notifications</title>

<indexterm><primary>Notifications</primary></indexterm>
<indexterm><primary>Sounds</primary></indexterm>

<para>Something about
<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Notifications...</guimenuitem>
</menuchoice>.</para>
</sect2>


<sect2 id="configuring-toolbars">
<sect2info>
<author>
<firstname>Adriaan</firstname>
<surname>de Groot</surname>
</author>
</sect2info>
<title>Configuring Toolbars</title>

<para>Nearly every &kde; application has one or more toolbars at the top of
the application window, underneath the menu. The toolbar contains icons
(toolbar buttons) that represent commonly used actions and configuration
settings. The &kmail; window, for instance, has a toolbar that contains
buttons for <guiicon>New Message</guiicon>, <guiicon>Check Mail</guiicon>
and several others. Each of these actions is something you do often, so
that's why they have toolbar buttons as well as menu entries (<guiicon>New
Message</guiicon> is under
<menuchoice><guimenu>Message</guimenu><guimenuitem>New
Message</guimenuitem></menuchoice>, <guiicon>Check Mail</guiicon> is
<menuchoice><guimenu>File</guimenu><guimenuitem>Check
Mail</guimenuitem></menuchoice>).</para>

<para>Not everybody agrees on what actions are commonly used, though, (I
never use the <guiicon>New Message</guiicon> toolbar button or the menu
item, I use the keyboard shortcut <keycombo
action="simul">&Ctrl;<keycap>N</keycap></keycombo>). To ensure that your
screen isn't cluttered with things you don't need, each toolbar can be
customized. Additionally, you can usually customize which toolbars are
displayed and how, as well.</para>

<sect3 id="customizing-toolbar-displays">
<title>Customizing Toolbar Displays</title>

<para>The easiest thing to customize with the toolbars of any given
application is whether they are displayed at all. Most applications have a
<menuchoice><guimenu>Settings</guimenu><guisubmenu>Toolbars</guisubmenu>
</menuchoice> menu where you can select which toolbars are displayed and
which are not. &konqueror; has four toolbars, <interface>Main</interface>,
<interface>Extra</interface>, <interface>Location</interface> and
<interface>Bookmark</interface>. It can be convenient to turn off the
<interface>Bookmark</interface> toolbar to save
screen space. To do so, click on the <guimenu>Settings</guimenu> menu,
choose <guisubmenu>Toolbars</guisubmenu>, and then uncheck the
<guimenuitem>Bookmark Toolbar</guimenuitem> entry (do this just by clicking
on the menu item).</para>

<para>If there is no <guimenu>Settings</guimenu> menu, you can also
<mousebutton>right</mousebutton> click on the toolbar itself, and choose the
<guisubmenu>Toolbars</guisubmenu> sub-menu from the resulting context
menu.</para>

<para>The same <guimenu>Toolbar</guimenu> context menu, accessed by
<mousebutton>right</mousebutton> clicking on the toolbar, allows you to
customize other properties of the toolbar:</para>

<itemizedlist>
<listitem>
<para>Its orientation, so that instead of appearing at the top of the
window under the menu bar you can place it on the left, right or bottom of
the window.</para>
</listitem>
<listitem>
<para>Its orientation, so that the toolbar <quote>floats</quote> as a
separate window which you can move independently.</para>
</listitem>
<listitem>
<para>Its orientation, so that the toolbar is squashed into a little flat
grip that you can re-open by double-clicking on it (this is subtly
different from making the toolbar vanish completely, since it it easier to
cause it to re-appear).</para>
</listitem>
<listitem>
<para>The appearance of text alongside, underneath, or instead of the icons
on the toolbar.</para>
</listitem>
<listitem>
<para>The size of the icons (if they are not supplanted by
text).</para>
</listitem>
</itemizedlist>
</sect3>

<sect3 id="customizing-icons-on-toolbar">
<title>Customizing the Icons on the Toolbar</title>

<para>The toolbar is intended for actions that you perform often, so what do
you do if there is some useless icon there, like <guiicon>Cut</guiicon>? Or
what if you really want a <guiicon>cut</guiicon> button on the toolbar, but
the application doesn't give you one? This is where the customize toolbars
dialog comes in &mdash; it give you complete control over the actions that
are available on each toolbar.</para>

<para>Choose <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure
Toolbars</guimenuitem></menuchoice> from the application's menu, or
<guimenuitem>Configure Toolbars</guimenuitem> from the context menu of the
toolbar itself. This displays the configure toolbars dialog, which consists
of a combobox <!-- drop-down box? --> with which you can select
<emphasis>which</emphasis> toolbar to customize, and two lists of items
&mdash; one of the available actions, and one of the actions that are
already in use on the toolbar.</para>

<para>Often there are many many more actions available ( <guiicon>activate
tab #12</guiicon>, for instance) than you would ever want on the toolbar, or
even that you know exist in the application. The customize toolbar dialog
can be a learning experience. You can drag actions from one list box to the
other, rearrange the items on the toolbar <!-- in the list box on the right
..... not sure if I should be LTR-centric -->, or change the icon for a
selected action. This allows you to drag the actions you don't want off of
the toolbar and into the list of available actions; similarly, the actions
you do want can be dragged into the toolbar. Clicking
<guibutton>OK</guibutton> in the dialog immediately updates the toolbar with
your new preferred actions.</para>

<para>There are a few special items that can end up in the listbox for the
current toolbar:</para>

<itemizedlist>
<listitem>
<para>separators, which exist in two flavors:
<itemizedlist>
<listitem><para><guilabel>line separator</guilabel> appears as a line
between two action icons</para>
</listitem>
<listitem><para><guilabel>separator</guilabel> appears as a larger
space between two action icons</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para><guilabel>&lt;Merge&gt;</guilabel>, which is a special item that
allows plugins and other loadable components of the application to insert
their actions into the toolbar as well. It is generally not a good idea to
remove this, since you cannot get it back.</para>
</listitem>
<listitem>
<para><guilabel>ActionList:</guilabel>, these appear in various flavors
(there is a viewmode_toolbar one in &konqueror;) and again these
represent lists of actions that might be inserted by
plugins.</para>
</listitem>
</itemizedlist>

<para>Whenever you click on an action in the list of current actions, a
description of it is shown in the dialog. This description will warn you if
it is a bad idea to remove the action.</para>

<para>If you do not like to drag things around, there are four buttons in
the middle of the dialog which allow you to move the selected action from
one list to the other, and to move a selected current action up or down in
the list. There must be a way to restore the default toolbars in an
application, in order to recover from accidentally deleting an important
action like <guilabel>&lt;Merge&gt;</guilabel>, but I don't know what it
is.</para>

<!-- Add links to "further reading" here -->
<!-- <itemizedlist>
<title>Related Information</title>
<listitem><para>to be written</para>
</listitem>
</itemizedlist>-->


</sect3>
</sect2>

</sect1>

</chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-omittag:nil
sgml-shorttag:nil
sgml-namecase-general:nil
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:0
sgml-indent-data:true
sgml-parent-document:("index.docbook" "book" "sect1")
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->