path: root/doc/kshutdown/index.docbook

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
<!ENTITY kmyapplication "<application>KShutDown</application>">
<!ENTITY kappname "&kmyapplication;">
<!ENTITY package "kde-module">
<!ENTITY % addindex "IGNORE">
<!ENTITY % English "INCLUDE">
]>

<book lang="&language;">

<bookinfo>
	<title>The &kmyapplication; Handbook</title>
	<authorgroup>
		<author>
			<personname>
				<firstname>Konrad</firstname>
				<surname>Twardowski</surname>
			</personname>
			<email>[email protected]</email>
		</author>
	</authorgroup>
	<copyright>
		<year>2005</year>
		<holder>Konrad Twardowski</holder>
	</copyright>
	<legalnotice>&FDLNotice;</legalnotice>
	<date>2006-04-22</date>
	<releaseinfo>1.09.00</releaseinfo><!-- sync. with KShutDown version -->
	<abstract>
		<para>&kmyapplication; is an advanced shut down utility for &kde;.</para>
	</abstract>
	<keywordset>
		<keyword>TDE</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>

<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 Session (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, user commands)</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>Visual and sound notifications</para></listitem>
			<listitem><para><link linkend="kiosk">&kde; Kiosk support</link></para></listitem>
		</itemizedlist>
	</para>
</chapter><!-- introduction -->

<chapter id="using-kapp">
	<title>Using &kmyapplication;</title>
	<sect1 id="using-mainwindow">
		<title>Main Window</title>
		<itemizedlist>
			<listitem><para>Use the first combo box to select an action (turn off computer, extras, etc).</para></listitem>
			<listitem><para>Use the second combo box to select a delay type (no delay, time from now, etc).</para></listitem>
			<listitem><para>Click the <guibutton>Start</guibutton> button to activate the selected action. The action will be executed at the selected time.</para></listitem>
			<listitem><para>Click the <guibutton>Stop</guibutton> button or press <keycap>Esc</keycap> key to cancel an active action.</para></listitem>
		</itemizedlist>
		<screenshot>
			<screeninfo>&kmyapplication; main window</screeninfo>
			<mediaobject>
				<imageobject>
					<imagedata fileref="mainwindow.png" format="PNG"/>
				</imageobject>
				<textobject>
					<phrase>Main window</phrase>
				</textobject>
			</mediaobject>
		</screenshot>
	</sect1>
	<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 Actions (no delay!)</para></listitem>
			<listitem><para>Right mouse button - show context menu</para></listitem>
		</itemizedlist>
	</sect1>
</chapter><!-- using-kapp -->

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

A Shut Down Utility for TDE

Generic options:
  --help                    Show help about options
  --help-qt                 Show Qt specific options
  --help-kde                Show TDE 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
  -e, --extra &lt;file&gt;        Execute "Extras" command (.desktop file)
  --confirm                 Confirm command line action
  --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><!-- command-line -->

<chapter id="kiosk">
	<title>Kiosk</title>
	<para>
		&kde; 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 a "kshutdown_" string.</para>
	</note>
<example>
<title>Example kshutdownrc file with restrictions</title>
<programlisting>
[TDE Action Restrictions][$i]
# [$i] - user cannot override this group
# false - feature is disabled
# true - feature is enabled
# by default all features are enabled

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

# Disables the "Restart Computer" action
kshutdown_action_reboot=true

# Disables the "Lock Session" action
kshutdown_action_lockscreen=true

# Disables the "End Current Session" action
kshutdown_action_logout=true

# Disables the "Extras" action
kshutdown_action_extras=true

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

# Disables the "Select a time" combo box,
# and the command line "time" argument
kshutdown_tab_time=true

# Disables the "Statistics" dialog
kshutdown_tab_stats=true
</programlisting>
</example>
</chapter><!-- kiosk -->

<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>
			<listitem><para>Run <command>dcop kshutdown MMainWindow hide</command> to hide the main window.</para></listitem>
			<listitem><para>Run <command>dcop kshutdown MMainWindow show</command> to restore the main window.</para></listitem>
		</orderedlist>
	</sect1>
	<sect1 id="dcop-func">
		<title>Functions</title>
		<sect2 id="dcop-func-cancel">
			<title>ASYNC cancel()</title>
			<para>Cancels the active 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 the current user and ends the session.</para>
		</sect2>
		<sect2 id="dcop-func-config">
			<title>ASYNC configure()</title>
			<para>[Since 0.6] Shows the settings dialog.</para>
		</sect2>
		<sect2 id="dcop-func-status">
			<title>QString getStatusInfo()</title>
			<para>Returns a &kmyapplication; status information.</para>
		</sect2>
		<sect2 id="dcop-func-makeinvisible">
			<title>ASYNC makeInvisible()</title>
			<para>[Since 0.9 Beta] Hiddes the main window and its system tray icon.</para>
		</sect2>
		<sect2 id="dcop-func-makevisible">
			<title>ASYNC makeVisible()</title>
			<para>[Since 0.6] 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 the 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>
	</sect1>
</chapter><!-- dcop -->

<chapter id="credits">
	<title>Credits and License</title>
	<para>&kmyapplication;</para>
	<para>
		Program Copyright 2005 Konrad Twardowski
		<email>[email protected]</email>
	</para>
	<para>
		Documentation Copyright &copy; 2005 Konrad Twardowski
		<email>[email protected]</email>
	</para>
	<para>Czech FAQ Copyright &copy; Robert Kratky</para>
	<para>See <guimenuitem>Help | About &kmyapplication;</guimenuitem> for more credits.</para>
	&underFDL;<!-- FDL: do not remove -->
	&underGPL;<!-- GPL License -->
</chapter><!-- credits -->

&documentation.index;

</book>