<chapter id="settings">
<title>Settings and Logs</title>

<sect1 id="settings-shortcuts">
<title>Shortcuts</title>
<para>You can create custom shortcut keys to make working in &kst; more efficient. To modify the shortcut keys, select <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Shortcuts...</guimenuitem></menuchoice>. The following dialog will be displayed.
</para>
<screenshot>
<screeninfo>Configure Shortcuts Window</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="Screenshot-kst-settings-shortcuts.png" format="PNG" />
</imageobject>
<textobject>
<phrase>Configure Shortcuts Window</phrase>
</textobject>
</mediaobject>
</screenshot>
<para>
A list of available actions and their associated shortcuts are shown in the dialog. Each action is
allowed two shortcuts&mdash;a primary shortcut and an alternate shortcut. Either shortcut can be used at any time.
To define or change a shortcut for an action, simply highlight the appropriate row in the shortcut list.
Under <guilabel>Shortcut for Selected Action</guilabel>, there are three choices:
<variablelist>
<varlistentry>
<term><guilabel>None</guilabel></term>
<listitem>
<para>
Select this option to disable any shortcut keys for the selected action.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Default</guilabel></term>
<listitem>
<para>
Select this option to use the default shortcut key(s) for the selected action.
Note that not all actions have default shortcuts defined.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Custom</guilabel></term>
<listitem>
<para>
Select this option to define a custom shortcut for the selected action.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>

<para>
If you select the <guilabel>Custom</guilabel> option, double click on a shortcut, or press the key-shaped button then the Define Shortcut dialog will appear.
</para>
<screenshot>
<screeninfo>Define Shortcut Window</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="Screenshot-kst-settings-defineshortcut.png" format="PNG" />
</imageobject>
<textobject>
<phrase>Define Shortcut Window</phrase>
</textobject>
</mediaobject>
</screenshot>
<para>
To define a key combination, select <guilabel>Primary</guilabel> or <guilabel>Alternate</guilabel>.  If you
wish to define a key <emphasis>sequence</emphasis>, check the <guilabel>Multi-key</guilabel> option.  Now enter
the key combination or sequence to be used for this action.  Click <guibutton>OK</guibutton> when you are done.
</para>

<note>
<para>
The action associated with a multi-key shortcut is performed as soon as only one action matches the
keys pressed so far. For example, if a multi-key shortcut of
<keycombo action="seq"><keycap>A</keycap><keycap>B</keycap><keycap>C</keycap></keycombo>
 is defined, and no
other multi-key shortcuts are defined, the action associated with the shortcut will be performed as soon as
<keycap>A</keycap> is pressed.
</para>
</note>
</sect1>

<sect1 id="settings-globalsettings">
<title>Global Settings</title>
<para>&kst;'s global settings can be accessed by selecting the <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &kst;...</guimenuitem></menuchoice>. The following dialog will be displayed.
</para>
<screenshot>
<screeninfo>&kst; Settings Window</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="Screenshot-kst-settings-globalsettings-general.png" format="PNG" />
</imageobject>
<textobject>
<phrase>&kst; Settings Window</phrase>
</textobject>
</mediaobject>
</screenshot>

<para>There are three available tabs. <link linkend="settings-globalsettings-general">General</link>, <link linkend="settings-globalsettings-datasources">Data Sources</link>, and <link linkend="settings-globalsettings-email">E-Mail</link>.
</para>

<sect2 id="settings-globalsettings-general">
<title>General</title>

<para>
The "General tab" contains most of &kst;'s global settings.
</para>

<variablelist>
<varlistentry>
<term>
<guilabel>Plot update timer:</guilabel>
</term>
<listitem>
<para>
The period of &kst;'s updates. These will check, for example, for changes in the data files associated with curves and update the plots accordingly.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<guilabel>Base font size:</guilabel>
</term>
<listitem>
<para>
The base font size for newly created plots.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<guilabel>Minimum font size:</guilabel>
</term>
<listitem>
<para>
The smallest font size which will be allowed in newly created plots (even if they are squeezed for space).
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<guilabel>Default plot colors:</guilabel>
</term>
<listitem>
<para>
The default foreground and background colours for plots.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<guilabel>Curve color sequence:</guilabel>
</term>
<listitem>
<para>
The colours to cycle through as new curves are added to a plot. This should have high contrast so that the curves can be differentiated easily.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<guilabel>Default Plot Grid Lines</guilabel>
</term>
<listitem>
<para>
See the <link linkend="view-types-plot-appearance-coloursandlineweights">Colour and Line Weights</link> section for <link linkend="view-types-plot">Plots</link>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<guilabel>Default X Axis</guilabel>
</term>
<listitem>
<para>
See the <link linkend="view-types-plot-xyaxis-scale">X/Y Axis Scale</link> section for <link linkend="view-types-plot">Plots</link>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<guilabel>Default Line Weight</guilabel>
</term>
<listitem>
<para>
See the <link linkend="view-types-plot-appearance-coloursandlineweights">Colour and Line Weights</link> section for <link linkend="view-types-plot">Plots</link>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<guilabel>Offset from UTC: / Timezone:</guilabel>
</term>
<listitem>
<para>
This allows &kst; to calculate the local time for data given in UTC.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<guilabel>Prompt before closing windows</guilabel>
</term>
<listitem>
<para>
&kst; will require confirmation before closing a window (and deleting the plots which it contains!).
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<guilabel>Show QuickStart dialog on startup</guilabel>
</term>
<listitem>
<para>
Enable if you would like the QuickStart Dialog (see <link linkend="intro-gettingstarted-importingdata">Getting Started - Importing Data</link> for a screenshot) to appear every time &kst; starts up.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<guilabel>Apply tied zoom globally</guilabel>
</term>
<listitem>
<para>
If this setting is enabled, tied zoom is applied to all windows, rather than just the current one.
</para>
</listitem>
</varlistentry>
</variablelist>

</sect2>

<sect2 id="settings-globalsettings-datasources">
<title>Data Sources</title>
<para>
This pane allows you to choose the default options for &kst;'s data sources. An explanation of the options available for the set of data sources included with &kst; can be found in the <link linkend="data-sources">Data Sources</link> documentation.
</para>
</sect2>

<sect2 id="settings-globalsettings-email">
<title>E-Mail</title>
<para>
&kst; can send e-mails for debugging and logging purposes. In this tab, you give &kst; the settings for the SMTP server which you would like to use to send mail.
</para>

<screenshot>
<screeninfo>&kst; Settings Window</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="Screenshot-kst-settings-globalsettings-email.png" format="PNG" />
</imageobject>
<textobject>
<phrase>&kst; Settings Window</phrase>
</textobject>
</mediaobject>
</screenshot>
</sect2>
</sect1>

<sect1 id="settings-debuglog">
<title>The Debug Dialog</title>
<para>The Debug Dialog contains the &kst; message log, and information about loaded data sources. To access the debug dialog, select <menuchoice><guimenu>Help</guimenu><guimenuitem>Debug &kst;...</guimenuitem></menuchoice> 
</para>

<screenshot>
<screeninfo>&kst; Debug Dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="Screenshot-kst-settings-debugdialog-log.png" format="PNG" />
</imageobject>
<textobject>
<phrase>&kst; Debug Dialog</phrase>
</textobject>
</mediaobject>
</screenshot>

<para>The Build Information tab contains the &kst; version number. The Data Sources tab contains a list of the data sources loaded in &kst; and the files which they are being used to read. The Log tab contains a list of messages which &kst; has recorded, and can be useful for debugging. If an error message has been posted, but not read, then &kst; will notify you by placing an excited stop sign in the lower right corner of the main window. 
</para>

<screenshot>
<screeninfo>Error notifier</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="Screenshot-kst-settings-debugdialog-notifier.png" format="PNG" />
</imageobject>
<textobject>
<phrase>Error notifier</phrase>
</textobject>
</mediaobject>
</screenshot>

<para>
The following lists the different messages that can appear in the debug log, with
brief explanations and suggested actions (where appropriate).
</para>

<informaltable>
<tgroup cols="3">
<thead>
<row>
<entry>Type</entry>
<entry>Message</entry>
<entry>Explanation/Suggested Action</entry>
</row>
</thead>
<tbody>
<row>
<entry>Unknown</entry>
<entry>Kst Extension %1 loaded</entry>
<entry>None.</entry>
</row>

<row>
<entry>Unknown</entry>
<entry>Error trying to load Kst extension %1.  Code=%2, \"%3\"</entry>
<entry>Make sure extension exists, meets the requirements for a &kst; extension,
and is in the correct location.</entry>
</row>

<row>
<entry>Unknown</entry>
<entry>Unable to find required vector [%1] for data object %2.</entry>
<entry>Ensure the indicated vector exists in the Data Manager.
  If so, try recreating the data object.</entry>
</row>

<row>
<entry>Unknown</entry>
<entry>Unable to find required scalar [%1] for data object %2.</entry>
<entry>Ensure that the indicated scalar exists (try searching in
<guimenuitem>View Scalars</guimenuitem> of the <guimenu>Data</guimenu> menu.</entry>
</row>

<row>
<entry>Unknown</entry>
<entry>Error loading data-source plugin [%1]: %2</entry>
<entry>A datasource reader (&kde; plugin) could not be loaded.
Make sure the data-source reader meets requirements described in
<link linkend="supportingadditionalfileformatscreatingdatasource">Creating Datasource Readers</link>
and is compiled correctly.
If it is a built-in datasource reader, try recompiling and installing it again from the source package.</entry>
</row>

<row>
<entry>Unknown</entry>
<entry>Scanning for data-source plugins.</entry>
<entry>&kst; is scanning for datasource readers. No action required.</entry>
</row>

<row>
<entry>Unknown</entry>
<entry>No data in file %1</entry>
<entry>Make sure file is supported by one of the datasource readers, and that the data is
formatted correctly and is not corrupt.</entry>
</row>

<row>
<entry>Unknown</entry>
<entry>Unsupported element <quote>%1</quote> in file %2</entry>
<entry>Ensure that the file is not corrupt, and meets the specifications for the
file format.</entry>
</row>

<row>
<entry>Unknown</entry>
<entry>Unable to find X vector for %2: [%1]</entry>
<entry>???</entry>
</row>

<row>
<entry>Unknown</entry>
<entry>Unable to find Y vector for %2: [%1]</entry>
<entry>???</entry>
</row>
<row>
<entry>Unknown</entry>
<entry>Undefined justification %1 in label \"%2\"</entry>
<entry>This should not happen.  Most likely it is the result of a bug.</entry>
</row>

<row>
<entry>Unknown</entry>
<entry>Internal error: No X scale type checked in %1.</entry>
<entry>None.</entry>
</row>

<row>
<entry>Unknown</entry>
<entry>Internal error: No Y scale type checked in %1.</entry>
<entry>None.</entry>
</row>

<row>
<entry>Unknown</entry>
<entry>Unable to load plugin %1 for \"%2\"</entry>
<entry>Make sure that the plugin meets the requirements described in
<link linkend="creatingplugins">Creating Additional Plugins</link>.  In particular,
make sure the shared object and <filename>*.xml</filename> file are in the same directory.
If the plugin is a built-in plugin, try re-installing the plugin from the source
package.
</entry>
</row>

<row>
<entry>Unknown</entry>
<entry>Input vector [%1] for plugin %2 not found.  Unable to continue.</entry>
<entry>Ensure that the <filename>*.xml</filename> file for the plugin
specifies all the inputs correctly and in the correct order.  Check the source
code for the shared object to ensure that it is using the correct arrays from the
input array.  Also ensure that
the specified input vector still exists (check in the Data Manager).</entry>
</row>

<row>
<entry>Unknown</entry>
<entry>Output vector [%1] for plugin %2 not found.  Unable to continue.</entry>
<entry>Ensure that the <filename>*.xml</filename> file for the plugin
specifies all the outputs correctly and in the correct order. Check the source
code for the shared object to ensure that it is outputting the correct arrays
in the output array. </entry>
</row>

<row>
<entry>Unknown</entry>
<entry>Data file for vector %1 was not opened.</entry>
<entry>???</entry>
</row>

<row>
<entry>Unknown</entry>
<entry>Error parsing XML file <quote>%1</quote>; skipping.</entry>
<entry>Check the XML file to make sure it has correct syntax and form for the
intended use.  If is an XML file for a plugin, check
<link linkend="creatingplugins">Creating Additional Plugins</link>
for more information.
</entry>
</row>

<row>
<entry>Unknown</entry>
<entry>Detected disappearance of <quote>%1</quote>.</entry>
<entry>None.</entry>
</row>

<row>
<entry>Unknown</entry>
<entry>Could not parse xml file <quote>%1</quote>.</entry>
<entry>Check the XML file to make sure it has correct syntax and form for the
intended use.  If is an XML file for a plugin, check
<link linkend="creatingplugins">Creating Additional Plugins</link>
for more information.</entry>
</row>

<row>
<entry>Unknown</entry>
<entry>Could not find library <quote>%1</quote> while loading plugin.</entry>
<entry>Make sure the library exists and is in the correct location. If this is a built-in plugin,
try recompiling and installing the plugin again.</entry>
</row>

<row>
<entry>Unknown</entry>
<entry>Could not find symbol <quote>%1</quote> in plugin %2.</entry>
<entry>A required C symbol could not be found in the plugin.
Make sure the plugin meets the requirements described in
<link linkend="creatingplugins">Creating Additional Plugins</link>.  If this is a built-in plugin,
try recompiling and re-installing the plugin.</entry>
</row>

<row>
<entry>Unknown</entry>
<entry>The %1 font was not found and was replaced by the %2 font; as a
result, some labels may not display correctly."</entry>
<entry>If this causes problems, install the missing font.</entry>
</row>

</tbody>
</tgroup>
</informaltable>

</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" "chapter")
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
