<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!-- Define an entity for your application if it is not part of KDE
       CVS -->
  <!ENTITY kmyapplication "<application>KShutDown</application>">
  <!ENTITY kappname "&kmyapplication;">
  <!ENTITY package "kde-module"><!-- kdebase, kdeadmin, etc.  Leave
                                     this unchanged if your
                                     application is not maintained in KDE CVS -->
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE"> <!-- ONLY If you are writing non-English
                                     original documentation, change
                                     the language here -->
  <!-- Do not define any other entities; instead, use the entities
       from entities/general.entities and $LANG/user.entities. -->

	<!ENTITY filefaqen SYSTEM "faq-en.docbook">
	<!ENTITY filefaqcs SYSTEM "faq-cs.docbook">
]>

<!--
Remember:
- in XML, the case of the <tags> and attributes is relevant ;
- also, quote all attributes.
-->

<!-- The language must NOT be changed here. -->
<!-- If you are writing original documentation in a language other -->
<!-- than English, change the language above ONLY, not here -->
<book lang="&language;">

<!-- This header contains all of the meta-information for the document such
as Authors, publish date, the abstract, and Keywords -->
<bookinfo>
<title>The &kmyapplication; Handbook</title>
<authorgroup>
	<author>
<!-- This is just put in as an example.  For real documentation, please
     define a general entity in entities/contributor.entities, e.g.
<!ENTITY George.N.Ugnacious "<personname><firstname>George</firstname><othername>N.</othername><surname>Ugnacious</surname></personname>">
<!ENTITY George.N.Ugnacious.mail "<email>gnu@kde.org</email>">
and use `&George.N.Ugnacious; &George.N.Ugnacious.mail;' in the author element.
 -->
		<personname>
			<firstname>Konrad</firstname>
			<surname>Twardowski</surname>
		</personname>
		<email>kdtonline@poczta.onet.pl</email>
	</author>
</authorgroup>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
<copyright>
	<year>2005</year>
	<holder>Konrad Twardowski</holder>
</copyright>
<!-- Translators: put here the copyright notice of the translation -->
<!-- Put here the FDL notice.  Read the explanation in fdl-notice.docbook
     and in the FDL itself on how to use it. -->
<legalnotice>&FDLNotice;</legalnotice>
<!-- Date and version information of the documentation
Don't forget to include this last date and this last revision number, we
need them for translation coordination !
Please respect the format of the date (YYYY-MM-DD) and of the version
(V.MM.LL), it could be used by automation scripts.
Do NOT change these in the translation. -->

<date>2005-02-05</date>
<releaseinfo>1.06.00</releaseinfo><!-- sync. with KShutDown version -->

<!-- Abstract about this handbook -->

<abstract>
<para>
&kmyapplication; is an advanced shut down utility for &kde;.
</para>
</abstract>

<!-- This is a set of Keywords for indexing by search engines.
Please at least include KDE, the KDE package it is in, the name
 of your application, and a few relevant keywords. -->

<keywordset>
<keyword>KDE</keyword>
<keyword>kshutdown</keyword>
<keyword>shutdown</keyword>
<keyword>shut</keyword>
<keyword>down</keyword>
<keyword>poweroff</keyword>
<keyword>reboot</keyword>
<keyword>lock</keyword>
<keyword>halt</keyword>
<keyword>exit</keyword>
<keyword>logout</keyword>
</keywordset>

</bookinfo>

<!-- The contents of the documentation begin here.  Label
each chapter so with the id attribute. This is necessary for two reasons: it
allows you to easily reference the chapter from other chapters of your
document, and if there is no ID, the name of the generated HTML files will vary
from time to time making it hard to manage for maintainers and for the CVS
system. Any chapter labelled (OPTIONAL) may be left out at the author's
discretion. Other chapters should not be left out in order to maintain a
consistent documentation style across all KDE apps. -->

<!-- INTRO -->
<chapter id="introduction">
<title>Introduction</title>

<para>&kmyapplication; is an advanced shut down utility for &kde;.</para>

<para>
Features:
<itemizedlist>
<listitem><para>Turn Off Computer (logout and halt the system)</para></listitem>
<listitem><para>Restart Computer (logout and reboot the system)</para></listitem>
<listitem><para>Lock Screen (lock the screen using a screen saver)</para></listitem>
<listitem><para>End Current Session (end the current &kde; session and logout the user)</para></listitem>
<listitem><para>Extras (additional, external commands)</para></listitem>
<listitem><para><link linkend="using-wizard">Wizard (a simplified version of &kmyapplication;)</link></para></listitem>
<listitem><para>Time and delay options</para></listitem>
<listitem><para><link linkend="command-line">Command line</link> and <link linkend="dcop">DCOP</link> support</para></listitem>
<listitem><para><link linkend="using-systray">System tray</link></para></listitem>
<listitem><para>Sounds and system notifications</para></listitem>
<listitem><para><link linkend="kiosk">Kiosk support</link></para></listitem>
</itemizedlist>
</para>

</chapter>

<!-- USING X -->
<chapter id="using-kapp">
<title>Using &kmyapplication;</title>

<!-- using main window -->
<sect1 id="using-mainwindow">
<title>Main Window</title>
<itemizedlist>
<listitem><para>Use combo box to select a delay type (now, time from now, delay in seconds, etc).</para></listitem>
<listitem><para>Click <guibutton>Turn Off Computer</guibutton> to shut down the system at the selected time.</para></listitem>
<listitem><para>Click <guibutton>Close</guibutton> button to exit &kmyapplication;.</para></listitem>
<listitem><para>Click <guibutton>Cancel</guibutton> button to cancel an active action.</para></listitem>
<listitem><para>Press <keycap>Esc</keycap> to cancel an active action, or exit &kmyapplication;.</para></listitem>
</itemizedlist>
<!-- png -->
<screenshot>
<screeninfo>&kmyapplication; Main Window</screeninfo>
<mediaobject>
	<imageobject><imagedata fileref="mainwindow.png" format="PNG"/></imageobject>
	<textobject><phrase>Main Window</phrase></textobject>
</mediaobject>
</screenshot>
</sect1>

<!-- using wizard -->
<sect1 id="using-wizard">
<title>Wizard</title>
<anchor id="anchor.using-wizard"/>
<itemizedlist>
<listitem><para>Select an action and click <guibutton>Next</guibutton>. You can also double click the radio button.</para></listitem>
<listitem><para>Select a date/time or "No delay", and click <guibutton>Finish</guibutton> to execute the selected action.</para></listitem>
</itemizedlist>
<!-- png -->
<screenshot>
<screeninfo>Wizard</screeninfo>
<mediaobject>
	<imageobject><imagedata fileref="wizard.png" format="PNG"/></imageobject>
	<textobject><phrase>Wizard</phrase></textobject>
</mediaobject>
</screenshot>
</sect1>

<!-- using system tray -->
<sect1 id="using-systray">
<title>System Tray</title>
<itemizedlist>
<listitem><para>Left mouse button - hide/show main window</para></listitem>
<listitem><para>Middle mouse button - show menu with the Actions (NOTE: no delay!)</para></listitem>
<listitem><para>Right mouse button - show context menu</para></listitem>
</itemizedlist>
<!-- png -->
<screenshot>
<screeninfo>System Tray</screeninfo>
<mediaobject>
	<imageobject><imagedata fileref="systemtray.png" format="PNG"/></imageobject>
	<textobject><phrase>System Tray</phrase></textobject>
</mediaobject>
</screenshot>
</sect1>

</chapter>

<!-- command line -->
<!-- copied from the kshutdown command line help -->
<chapter id="command-line">
<title>Command Line</title>
<programlisting>
Usage: kshutdown [Qt-options] [KDE-options] [options] [time]

Generic options:
--help                    Show help about options
--help-qt                 Show Qt specific options
--help-kde                Show KDE specific options
--help-all                Show all options
--author                  Show author information
-v, --version             Show version information
--license                 Show license information
--                        End of options

Options:
-s, --shutdown            Turn off computer
-h, --halt                Turn off computer
-r, --reboot              Restart computer
-k, --lock                Lock session
-l, --logout              End current session
-w, --wizard              Wizard
--standard                Show standard logout dialog
-c, --cancel              Cancel an active action
--init                    Don't show window at startup
--test                    Enable test mode
--default                 Disable test mode

Arguments:
time                      Time; Examples: 01:30 - absolute time (HH:MM); 10 - number of
                          minutes to wait from now
</programlisting>
</chapter>

<!-- faq -->
<chapter id="faq">
<title>FAQ (OBSOLETE)</title>

&filefaqen;

&filefaqcs;

</chapter>

<!-- kiosk -->
<chapter id="kiosk">
<title>Kiosk</title>
<para>
Kiosk allows you to control some critical features, such as <guibutton>Turn Off Computer</guibutton>
or <guibutton>Restart Computer</guibutton> commands.
To enable restrictions, you need to create a global configuration file - <filename>kshutdownrc</filename> in
your global &kde; directory (<filename>[prefix]/share/config</filename>).
</para>

<note>
<para>In some cases you need to restart &kmyapplication; to see effects.</para>
</note>

<note>
<para>Since version 0.3.1 Beta all KIOSK keys are prefixed with "kshutdown_" string.</para>
</note>

<example>
<title>Example file</title>
<programlisting>
[KDE Action Restrictions][$i]
# [$i] - user cannot override this group
# false - feature is disabled
# true - feature is enabled
# by default all features are enabled

# Disables "Shut Down" action
kshutdown_action_shutdown=true
# kshutdown_action_shutdown=false &lt;- "false" will disable "Shut Down" action

# Disables "Reboot" action
kshutdown_action_reboot=true

# Disables "Lock Screen" action
kshutdown_action_lockscreen=true

# Disables "Logout" action
kshutdown_action_logout=true

# Disables the "Wizard"
kshutdown_action_wizard=true

# Disables "Extras" action
kshutdown_action_extras=true

# Disables "Actions" page in the "Settings" dialog
kshutdown_settings_actions=true

# Disables "Time" tab, and the command line "time" argument
kshutdown_tab_time=true

# Disables "Statistics" tab
kshutdown_tab_stats=true

# Disables "Scheduler" tab and KShutdownIface (DCOP server)
kshutdown_sched=true
</programlisting>
</example>

</chapter>

<!-- dcop -->
<chapter id="dcop">
<title>DCOP API (KShutdownIface)</title>

<sect1 id="dcop-intro">
<title>Introduction</title>
<orderedlist>
<listitem><para>Make sure &kmyapplication; is running.</para></listitem>
<listitem><para>Type <command>kshutdown --init</command> to start &kmyapplication; without displaying its main window.</para></listitem>
<listitem><para>To display all DCOP functions, type <command>dcop kshutdown KShutdownIface</command>.</para></listitem>
</orderedlist>
</sect1>

<sect1 id="dcop-func">
<title>Functions</title>

<sect2 id="dcop-func-cancel">
<title>ASYNC cancel()</title>
<para>Cancels current action.</para>
</sect2>

<sect2 id="dcop-func-shutdown">
<title>bool shutDown(), bool shutdown()</title>
<para>Shuts down the system.</para>
</sect2>

<sect2 id="dcop-func-reboot">
<title>bool reboot()</title>
<para>Reboots the system.</para>
</sect2>

<sect2 id="dcop-func-lock">
<title>bool lockScreen()</title>
<para>Locks the screen using a screen saver.</para>
</sect2>

<sect2 id="dcop-func-logout">
<title>bool logout()</title>
<para>Logouts current user and ends the session.</para>
</sect2>

<sect2 id="dcop-func-config">
<title>ASYNC configure()</title>
<para>Shows the settings dialog.</para>
</sect2>

<sect2 id="dcop-func-status">
<title>QString getStatusInfo()</title>
<para>Returns a &kmyapplication; status information.</para>
<para>NOTE: At this time it returns the main window caption text! Can be used in Karamba themes.</para>
</sect2>

<sect2 id="dcop-func-makevisible">
<title>ASYNC makeVisible()</title>
<para>Shows and raises the main window. The window will be visible on the current desktop.</para>
</sect2>

<sect2 id="dcop-func-test">
<title>ASYNC setTestMode(bool yes)</title>
<para>Enables/disables test mode.</para>
<example>
<title>Enable test mode</title>
<programlisting>dcop kshutdown KShutdownIface setTestMode true</programlisting>
</example>
<example>
<title>Disable test mode</title>
<programlisting>dcop kshutdown KShutdownIface setTestMode false</programlisting>
</example>
</sect2>

<sect2 id="dcop-func-wizard">
<title>ASYNC wizard()</title>
<para>Launches the Wizard.</para>
</sect2>

</sect1>

<sect1 id="dcop-sched">
<title>Scheduler Functions</title>

<para>
External applications can use &kmyapplication; "Scheduler"
to shut down or reboot system without conflicts with other applications
that use "Scheduler" too.
</para>

<para>
General informations:
<itemizedlist>
<listitem><para>The new task will appear in the "Scheduler" tab.</para></listitem>
<listitem><para>User can delete any registered task by clicking on <guibutton>Remove</guibutton> or <guibutton>Remove All</guibutton> button.</para></listitem>
<listitem><para>User can disable "Scheduler".</para></listitem>
<listitem><para>Disabled "Scheduler" discards "activateAction", "registerTask" and "unregisterTask" command.</para></listitem>
</itemizedlist>
</para>

<para>
General usage:
<programlisting>
ON INIT: $ID = registerTask "appName" "taskTescription" ACTION_TO_EXECUTE
..
APP WORK
..
AFTER APP WORK: activateAction $ID
..
ON EXIT: unregisterTask $ID
</programlisting>
</para>

<para>
See <filename>kshutdowndcopapi.cpp</filename> and
<filename>mmainwindow.cpp</filename> to see how to call these functions.
</para>

<sect2 id="dcop-sched-register">
<title>int registerTask(QString name, QString description, int action)</title>
<para>Registers a new KShutDown task.</para>
<para>
This function returns an unique ID that is required, if you want to use "activateAction" or
"unregisterTask" function. Returns an unique ID number if successful; otherwise "0".
</para>
<simplelist>
<member>name - This should be "kapp->dcopClient()->appId()".</member>
<member>description - A description of the task. EXAMPLE: "Shut down after download."</member>
<member>action - An action to execute by "activateAction(int id)" (see below).</member>
</simplelist>
<para>
Possible actions are:
<itemizedlist>
<listitem><para>1 - shut down</para></listitem>
<listitem><para>2 - reboot</para></listitem>
<listitem><para>3 - RESERVED/NOT USED</para></listitem>
<listitem><para>4 - logout</para></listitem>
</itemizedlist>
</para>
</sect2>

<sect2 id="dcop-sched-activate">
<title>bool activateAction(int id)</title>
<para>Executes a &kmyapplication; action.</para>
<simplelist>
<member>id - A task ID returned by the "registerTask" function.</member>
<member>- "activateAction" will automatically unregister the task!</member>
<member>- "Lock screen" action is not supported here!</member>
<member>Returns "1" (TRUE) if successful; otherwise "0" (FALSE).</member>
</simplelist>
</sect2>

<sect2 id="dcop-sched-unregister">
<title>bool unregisterTask(int id)</title>
<para>Unregisters the task previously registered by "registerTask".</para>
<simplelist>
<member>id - A task ID to unregister.</member>
<member>Returns "1" (TRUE) if successful; otherwise "0" (FALSE).</member>
</simplelist>
</sect2>

</sect1>

</chapter>

<!-- CREDITS -->
<chapter id="credits">
<!-- Include credits for the programmers, documentation writers, and
contributors here. The license for your software should then be included below
the credits with a reference to the appropriate license file included in the KDE
distribution. -->
<title>Credits and License</title>
<para>&kmyapplication;</para>
<para>Program Copyright 2005 Konrad Twardowski <email>kdtonline@poczta.onet.pl</email></para>
<para>Documentation Copyright &copy; 2005 Konrad Twardowski <email>kdtonline@poczta.onet.pl</email></para>
<para>Czech FAQ Copyright &copy; Robert Kratky</para>
<para>See <guimenuitem>Help | About &kmyapplication;</guimenuitem> for more credits.</para>
<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
&underFDL;	<!-- FDL: do not remove -->
&underGPL;	<!-- GPL License -->
</chapter>

&documentation.index;
</book>

<!--
Local Variables:
mode: xml
sgml-minimize-attributes:nil
sgml-general-insert-case:lower
sgml-indent-step:0
sgml-indent-data:nil
End:

vim:tabstop=2:shiftwidth=2:expandtab
-->