Added KDE3 version of pykdeextensions

git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/libraries/pykdeextensions@1097589 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 874 insertions, 0 deletions

diff --git a/doc/en/index.docbook b/doc/en/index.docbook
new file mode 100644
index 0000000..bd663b8
--- /dev/null
+++ b/doc/en/index.docbook
@@ -0,0 +1,874 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+  <!ENTITY appname "<application>PyKDE Extensions</application>">
+  <!ENTITY kappname "&appname;"><!-- Do *not* replace kappname-->
+  <!ENTITY package "kde-module"><!-- kdebase, kdeadmin, etc -->
+  <!ENTITY % addindex "IGNORE">
+  <!ENTITY % English "INCLUDE"><!-- change language only here -->
+  
+  
+  <!-- Do not define any other entities; instead, use the entities
+       from kde-genent.entities and $LANG/user.entities. -->
+]>
+
+<!-- ................................................................ -->
+<!-- The language must NOT be changed here. -->
+
+<book lang="&language;">
+
+<bookinfo>
+<title>The &appname; Handbook</title>
+
+<authorgroup>
+<author>
+<firstname>Simon</firstname>
+<othername></othername>
+<surname>Edwards</surname>
+<affiliation>
+<address><email>simon@simonzone.com</email></address>
+</affiliation>
+</author>
+</authorgroup>
+
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+
+<copyright>
+<year>2005</year>
+<holder>Simon Edwards</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-09-19</date>
+<releaseinfo>0.4</releaseinfo>
+
+<!-- Abstract about this handbook -->
+
+<abstract>
+<para>
+&appname; is a collection of software and Python packages to support the
+creation and installation of KDE applications.
+</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>PyKDE Extensions</keyword>
+<keyword>python</keyword>
+<keyword>PyKDE</keyword>
+</keywordset>
+
+</bookinfo>
+
+<chapter id="introduction">
+<title>Introduction</title>
+
+<para>
+&appname; is a collection of software and Python packages to support the
+creation and installation of KDE applications.
+</para>
+
+</chapter>
+
+<!-- distutils -->
+<chapter id="distutils">
+<title>Installation &amp; Distutils support</title>
+
+<para>
+C++ projects on KDE traditionally use 
+<ulink url="http://www.gnu.org/software/autoconf/">autoconf</ulink>,
+<ulink url="http://www.gnu.org/software/automake/">automake</ulink>
+and <ulink url="http://www.gnu.org/software/libtool/">libtool</ulink>
+to handle the building and installation. These tools 
+and difficult to use, even for experianced developers.
+</para>
+
+<para>
+Fortunately Python has a its own system for building and installing
+modules and software. <ulink url="http://docs.python.org/lib/module-distutils.html">Distutils</ulink>
+is a standard Python package and comes with every Python installation.
+&appname; builds on Distutils with extensions tailored for handling KDE
+programs.
+</para>
+
+<para>
+A typical KDE program comes not only with the program itself but also
+extra files such as a manual written in <ulink url="http://i18n.kde.org/doc/markup/">Docbook
+format</ulink>, <ulink url="http://i18n.kde.org/translation-howto/">translation files</ulink>,
+icons, images and other auxiliary data files. &appname; provides support for
+handling all these other files types.
+</para>
+
+<sect1 id="distutils-using">
+<title>Using Distutils with KDE programs</title>
+<para>
+It is advised that you first read the standard
+<ulink url="http://docs.python.org/lib/module-distutils.html">Distutils documentation</ulink>
+to learn about how it works. &appname; adds some KDE specific extensions which are documented
+below.
+</para>
+
+<para>
+Distutils is based around writing a <filename>setup.py</filename> file which
+then uses the distutils package
+To use the KDE extensions, the first thing you need to do in your <filename>setup.py
+</filename> file is include the <symbol>kdedistutils</symbol> package.
+<programlisting>
+#!/usr/bin/env python
+# Setup.py file for MyKDEApplication
+
+import kdedistutils
+</programlisting>
+
+You need to call the <symbol>setup()</symbol> function from <symbol>kdedistutils</symbol>
+with all of the configuration information about your application, much like the standard
+<symbol>setup()</symbol> from <symbol>distutils</symbol>.
+
+<programlisting>
+kdedistutils.setup(name="pykdeextensions",
+    version="0.1.0",
+    author="Simon Edwards",
+    author_email="simon@simonzone.com",
+    url="http://www.simonzone.com/software/pykdeextensions/",
+    min_kde_version = "3.0.0",
+    min_qt_version = "3.0.0",
+    license = "LGPL" )
+</programlisting>
+
+<symbol>min_kde_version</symbol> and <symbol>min_qt_version</symbol> specify
+the minimum versions of the Qt library and KDE needed to install and run
+the software. These requirements are checked during install.
+</para>
+
+<para>
+The other arguments shown here are standard <symbol>distutils.setup()</symbol>
+arguments.
+</para>
+
+</sect1>
+
+<sect1 id="distutils-files">
+<title>Application data files</title>
+<para>
+Each KDE application as a data directory of it's own for storing any extra
+data files it may need to run.
+</para>
+
+<para>
+Data files are specified using the the <symbol>application_data</symbol>
+argument for <symbol>setup()</symbol>. <symbol>application_data</symbol>
+is a list of files to install.
+<programlisting>
+    application_data = ['extracode.py', ('pics', ['pics/warning.png'])]
+</programlisting>
+You can simply specify the name of each file as a string and they will be
+installed directly in the application data directory. Or you can use a tuple
+containing the name of the sub-directory under the application data directory
+to install into, and as the second tuple item, the list of files to install
+into the given sub-directory.
+</para>
+
+<para>
+Since most large Python programs are broken up into multiple source files
+it is recommended that all of the Python files that comprise your
+application be installed into the application directory. This helps eliminate
+problems with the Python module path and the interpreter not being able
+find the correct file to <symbol>import</symbol>.
+</para>
+
+<para>
+Even with all of the python files in the Application data directory, it is
+still desirable to have your application's "executables" available in KDE's
+<filename>bin</filename> directory. &appname; provides an easy way for creating
+symbolic links from the "bin" directory to scripts in the application
+directory.
+<programlisting>
+    executable_links = [('myapplication','myapplication.py'), ('myapplicationgui','myapplicationgui.py')]
+</programlisting>
+This example specifies an executable symbolic link <filename>myapplication
+</filename> that points to the <filename>myapplication.py</filename> script
+in the application data directory.
+</para>
+
+</sect1>
+
+<sect1 id="distutils-uninstall">
+<title>Uninstall command</title>
+<para>
+Standard Distutils does not feature an uninstall command. &appname; does 
+and it can be easily invoked with:
+<screen>
+python setup.py uninstall
+</screen>
+It is quite basic. The <symbol>install</symbol> writes the list of files
+it installed to the file <filename>install_log.txt</filename>. The
+<symbol>uninstall</symbol> command simply reads this file and removes the
+files and directories that are listed within.
+</para>
+</sect1>
+
+</chapter>
+
+<chapter id="distutils-docbook">
+<title>Manuals &amp; Docbook files</title>
+<para>
+Docbook is an XML based file format for writing manuals and books.
+More information about using Docbook to write manuals and documentation using
+Docbook is <ulink url="http://i18n.kde.org/doc/markup/">here</ulink>.
+Manuals are written in the Docbook format, but need to be converted
+into HTML when installed and made available for the KDE Help Center.
+</para>
+
+<para>
+Docbooks files and images are usually organised under a
+<filename>doc</filename> directory which is then further divided by two
+letter language code. For example <filename>doc/en</filename>,
+<filename>doc/nl</filename>, en <filename>doc/fr</filename>.
+The Docbook files themselves are named <filename>index.docbook</filename>
+</para>
+
+<para>
+By using the <symbol>docbooks</symbol> argument to <symbol>setup()</symbol>
+in your <filename>setup.py</filename>, you can specify the directories
+containing docbook files. You also need to specify the language used in
+that directory.
+<programlisting>
+    docbooks = [ ('doc/en','en'), ('doc/nl','nl'), ('doc/fr','fr') ]
+</programlisting>
+The argument to <symbol>docbooks</symbol> is a list of tuples. The first item
+of a tuple is the relative path to a docbook directory. The second item is
+the two letter language code.
+</para>
+
+<para>
+Docbook files specified this way will automatically be converted to HTML
+during install.
+</para>
+
+</chapter>
+
+<!-- Qt-designer -->
+<chapter id="using-qtdesigner">
+<title>Run-time integration with Qt-Designer</title>
+<para>
+Qt-Designer is a graphical application used for designing user interfaces.
+It creates <literal role="extension">.ui</literal> files. These files need
+to be converted into Python classes before they can be used in a Python
+application. This can be manually done using the <command>pyuic</command>
+command from the shell. But it is a lot more convenient to let &appname;
+to this automatically for you. All you need to do is import the
+<symbol>qtdesigner</symbol> or <symbol>kdedesigner</symbol> module, depending
+on whether your application is pure Qt or uses KDE, and then you can import
+your user interface files as though they were normal Python files.
+
+<programlisting>
+#!/usr/bin/env python
+from kdeui import *
+
+import kdedesigner     # This module lets us import .ui file directly.
+from MyWindow import * # Loads MyWindow.ui
+
+# Subclass the Qt-designer form.
+class MyWindowCode(MyWindow):
+    # Implement extra functionality and methods.
+</programlisting>
+The <symbol>kdedesigner</symbol>/<symbol>qtdesigner</symbol> module converts
+<literal role="extension">.ui</literal> on demand to
+<literal role="extension">.py</literal> files.
+</para>
+
+</chapter>
+
+<!-- Internationalization -->
+<chapter id="i18n">
+<title>Internationalization &amp; translation</title>
+<para>
+i18n (an abbreviation of internationalization) is the process of translating
+the user interface and documentation of a piece of software into another
+language. <ulink url="i18n.kde.org">i18n.kde.org</ulink> is the central 
+information point for the effort to translate KDE software into other
+languages.
+</para>
+
+<para>
+Translation of the user interface an application is done using
+<literal role="extension">.pot</literal> files and
+<literal role="extension">.po</literal> files.
+A <literal role="extension">.pot</literal> file, is generated from the source
+code of the program itself, and contains all of the strings / fragments of text,
+that are used in the program.
+</para>
+
+<para>
+Before a string in a program is include in the <literal role="extension">.pot
+</literal> file, it needs to be marked with the <function>i18n()</function>.
+
+<programlisting>
+#!/usr/bin/env python
+from kdecode import *
+
+        ...
+        mylabel = QLabel(i18n("Select new directory:"))
+        ...
+</programlisting>
+The <function>i18n()</function> is part of the <symbol>kdecode</symbol> package
+and needs to be imported.
+</para>
+
+<para>
+&appname; provides support for generating <literal role="extension">.pot</literal>
+files and managing and updating <literal role="extension">.po</literal> files.
+</para>
+
+<para>
+By using the <symbol>i18n</symbol> argument to <symbol>setup()</symbol>
+in your <filename>setup.py</filename>, you can specify the directory
+that should contain the <literal role="extension">.pot</literal> and
+<literal role="extension">.po</literal> files. The argument for
+<symbol>i18n</symbol> is a tuple. The first item is the relative path
+to the directory where the translation files should be stored. The 
+second item is a list of directories that should be scanned for Python source
+files containing translatable strings.
+<programlisting>
+    i18n = ('po',['.','mymodule'])
+</programlisting>
+
+</para>
+
+<para>
+Once your <filename>setup.py</filename> is configured, use this command in the
+shell to generate the <literal role="extension">.pot</literal> file.
+<screen>
+python setup.py update_messages
+</screen>
+This command also updates any already existing <literal role="extension">.po</literal>
+files with any new messages.
+</para>
+
+<para>
+&appname; also handles installing translation files and converting
+<literal role="extension">.po</literal> files into the special binary format
+needed by the application at runtime.
+</para>
+
+</chapter>
+
+<!-- Kcontrol modules -->
+<chapter id="kcontrol-modules">
+<title>KDE Control Center Modules</title>
+<para>
+&appname; can also help create modules for the KDE Control Center. 
+C++ glue code is needed when writing in module in Python. Fortunately
+&appname; can generate this glue for you automatically.
+</para>
+<para>
+The best way to start learning about creating modules is to read the 
+<ulink url="http://developer.kde.org/documentation/other/kcm_howto.html">KConfig
+Module HOWTO</ulink>. It is written for C++, but the concepts are the same for
+Python.
+</para>
+<para>
+In your <filename>setup.py</filename> file you can specify the list of kcontrol
+modules that need to be installed. 
+<programlisting>
+    kcontrol_modules = [ ('src/kcontrol_module.desktop','kcontrol_module.py')] )
+</programlisting>
+This is just a list of tuples. The first item is name of the
+<literal role="extension">.desktop</literal> file that you've made for your
+module. The second item is the name of the Python program to run when the
+user views the module in kcontrol. This program is expected to be in 
+the application's data files directory.
+</para>
+<para>
+The <ulink url="http://developer.kde.org/documentation/standards/kde/kcontrol_style/index.html">
+KControl Module Guidelines</ulink> provides useful information about how to
+design a KControl module that fits into the rest of KDE.
+</para>
+
+<tip>
+<para>
+&appname; typically installs the <literal role="extension">.desktop</literal>
+file into the <filename>/usr/share/applications/kde/</filename> directory.
+This is normally enough to make the module appear in the KDE Control Center.
+But for some distributions, most notably <ulink url="http://www.mandriva.com/">
+Mandriva</ulink> but probably others too, this isn't enough. Mandriva in
+particular uses the <ulink url="http://alioth.debian.org/projects/menu/">
+Debian menu system</ulink> for managing the K menu and also for KControl
+modules. In order to get a module to appear in the kcontrol it is best
+to createa a <literal role="extension">.menu</literal> file and copy
+it into <filename>/usr/lib/menu</filename>, and then use <command>update-menus
+</command> as root to update all of the menus and the list of kcontrol
+modules.
+</para>
+</tip>
+
+<note>
+<para>
+Right now there is no support for "module-testing" or "X-KDE-Test-Module=true"
+features in <literal role="extension">.desktop</literal> files.
+</para>
+</note>
+</chapter>
+
+<!-- KIO-Slaves -->
+<chapter id="kioslaves">
+<title>KIO Slaves</title>
+<para>
+&appname; can be used for the creation of kio-slaves. &appname; handles the C++
+glue code needed for making kioslaves in Python.
+<ulink url="http://developer.kde.org/documentation/library/kdeqt/kde3arch/nettransparency.html">developer.kde.org</ulink>
+has some documentation about KIO-slaves aimed at C++ programmers.
+</para>
+<para>
+In your <filename>setup.py</filename> file you can specify the list of kioslaves
+that need to be installed. 
+<programlisting>
+    kioslaves = [ ('src/kioslave.protocol','kioslave.py')] )
+</programlisting>
+This is just a list of tuples. The first item is name of the
+<literal role="extension">.protocol</literal> file that you've made for your
+kio-slave. The second item is the name of the Python program to run when the
+user views the module in kcontrol. This program is expected to be in 
+the application's data files directory.
+</para>
+</chapter>
+
+<!-- Application templates -->
+<chapter id="application-templates">
+<title>Application templates</title>
+
+<para>
+The <filename>app_templates</filename> directory contains a number of
+application templates. An <quote>application template</quote> is just a collection of files
+in a directory structure that should be copied and used as starting point 
+when developing a new application. An application template typically contains
+default documentation files, icons, source file and <filename>setup.py
+</filename> file which can later be modified.
+</para>
+
+<para>
+Every application template has a number of files in common. They are
+described below.
+
+<variablelist>
+<varlistentry>
+    <term><filename>AUTHORS</filename></term>
+    <listitem><para>Lists the authors of this software.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+    <term><filename>ChangeLog</filename></term>
+    <listitem><para>An itemised log or list of changes to the software.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+    <term><filename>COPYING</filename></term>
+    <listitem><para>A copy of the GNU GPL, explaining the terms under which this
+    software may be distributed. This file does not need to be changed.
+    </para></listitem>
+</varlistentry>
+
+<varlistentry>
+    <term><filename>INSTALL</filename></term>
+    <listitem><para>Instructions for installing the software.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+    <term><filename>MANIFEST.in</filename></term>
+    <listitem><para></para></listitem>
+</varlistentry>
+
+<varlistentry>
+    <term><filename>NEWS</filename></term>
+    <listitem><para>News about what is new in the current version of this software.
+    </para></listitem>
+</varlistentry>
+
+<varlistentry>
+    <term><filename>README</filename></term>
+    <listitem><para>Important instructions and information that the user should
+    read first.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+    <term><filename>setup.py</filename></term>
+    <listitem><para>.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+    <term><filename>TODO</filename></term>
+    <listitem><para>List of features and work that may be available in a future
+    version of the software.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+    <term><filename>po/</filename></term>
+    <listitem><para>This directory is initially empty. It is used for
+    <literal role="extension">.pot</literal> and <literal role="extension">.po
+    </literal> translation files.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+    <term><filename>doc/</filename></term>
+    <listitem><para>This directory is initially empty. It is used for holding the
+    directores for the different langauge version of the manual.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+    <term><filename>doc/en</filename></term>
+    <listitem><para>This directory for the english version of the manual.
+    </para></listitem>
+</varlistentry>
+
+<varlistentry>
+    <term><filename>doc/en/index.docbook</filename></term>
+    <listitem><para>The english manual in docbook format. The default is a template
+    which can then be filled in.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+    <term><filename>src</filename></term>
+    <listitem><para>This directory containing the source code for the software.
+    The default contents of this directory depends on the particular
+    application template.</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+</para>
+
+<sect1 id="app-template-simple">
+<title>Simple KDE utility template</title>
+<para>
+The <filename>kdeutility</filename> application template is a simple utility
+that uses an interface designed in Qt-Designer. It doesn't have a menubar 
+or toolbar.
+</para>
+</sect1>
+
+<sect1 id="app-template-application">
+<title>KDE application template</title>
+<para>
+The <filename>kdeapp</filename> application template is an application with
+menubar, toolbar and separated document and view classes. The menubar and toolbars
+are defined using XML.
+</para>
+</sect1>
+
+<sect1 id="app-template-kcontrol">
+<title>Kcontrol Module Application Template</title>
+<para>
+The <filename>kcontrol_module</filename> application template is a simple
+module for the KDE Control Center. The module can also be run as a separate
+application outside of KControl to ease development and debugging.
+</para>
+</sect1>
+
+<sect1 id="app-template-kioslave">
+<title>KIO-slave Application Template</title>
+<para>
+The <filename>kioslave</filename> application template is a simple
+KIO-slave that implements a simple RAM disk. Once installed it can be 
+accessed using kioslave:/ in konqueror. It is initially empty. Files and
+directories can be made and deposited. <filename>kioslave.py</filename>
+contains more information and comments.
+</para>
+<note>
+<para>
+Note that the KIO subsystem usually creates multiple running instances
+of a kio-slave backend. For the application template, files and directories
+are specific to each particular backend instance. When using konqueror the
+same instance will be used, but if you try to access kioslave:/ from a
+different process a new (empty!) instance will be craeted. This can be
+confusing! Be aware.
+</para>
+</note>
+</sect1>
+
+</chapter>
+
+<!--
+<chapter id="commands">
+<title>Command Reference</title>
+<sect1 id="appname-mainwindow">
+<title>The main &appname; window</title>
+</sect1>
+</chapter>
+
+<chapter id="developers">
+<title>Developer's Guide to &appname;</title>
+
+
+<para>
+Programming &appname; plugins is a joy to behold. Just read through the next
+66 pages of API's to learn how!
+</para>
+
+
+<refentry id="re-1007-unmanagechildren-1">
+<refmeta>
+<refentrytitle>XtUnmanageChildren</refentrytitle>
+<refmiscinfo>Xt - Geometry Management</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>XtUnmanageChildren
+</refname>
+<refpurpose>remove a list of children from a parent widget's managed
+list.
+<indexterm id="ix-1007-unmanagechildren-1"><primary>widgets</primary><secondary>removing</secondary></indexterm>
+<indexterm id="ix-1007-unmanagechildren-2"><primary>XtUnmanageChildren</primary></indexterm> 
+</refpurpose>
+
+</refnamediv>
+<refsynopsisdiv>
+<refsynopsisdivinfo>
+<date>4 March 1996</date>
+</refsynopsisdivinfo>
+<synopsis>
+void XtUnmanageChildren(<replaceable class="parameter">children</replaceable>, <replaceable class="parameter">num_children</replaceable>)
+    WidgetList <replaceable class="parameter">children</replaceable>;
+    Cardinal <replaceable class="parameter">num_children</replaceable>;
+</synopsis>
+
+<refsect2 id="r2-1007-unmanagechildren-1">
+<title>Inputs</title>
+<variablelist>
+<varlistentry>
+<term><replaceable class="parameter">children</replaceable>
+</term>
+<listitem>
+<para>Specifies an array of child widgets. Each child must be of
+class RectObj or any subclass thereof.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><replaceable class="parameter">num_children</replaceable>
+</term>
+<listitem>
+<para>Specifies the number of elements in <replaceable class="parameter">children</replaceable>.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</refsect2></refsynopsisdiv>
+
+<refsect1 id="r1-1007-unmanagechildren-1">
+<title>Description
+</title>
+<para><function>XtUnmanageChildren()</function> unmaps the specified widgets
+and removes them from their parent's geometry management.
+The widgets will disappear from the screen, and (depending
+on its parent) may no longer have screen space allocated for
+them.
+</para>
+<para>Each of the widgets in the <replaceable class="parameter">children</replaceable> array must have
+the same parent.
+</para>
+<para>See the &ldquo;Algorithm&rdquo; section below for full details of the
+widget unmanagement procedure.
+</para>
+</refsect1>
+
+<refsect1 id="r1-1007-unmanagechildren-2">
+<title>Usage</title>
+<para>Unmanaging widgets is the usual method for temporarily
+making them invisible.  They can be re-managed with
+<function>XtManageChildren()</function>.
+</para>
+<para>You can unmap a widget, but leave it under geometry
+management by calling <function>XtUnmapWidget()</function>.  You can
+destroy a widget's window without destroying the widget by
+calling <function>XtUnrealizeWidget()</function>.  You can destroy a
+widget completely with <function>XtDestroyWidget()</function>.
+</para>
+<para>If you are only going to unmanage a single widget, it is
+more convenient to call <function>XtUnmanageChild()</function>.  It is
+often more convenient to call <function>XtUnmanageChild()</function>
+several times than it is to declare and initialize an array
+of widgets to pass to <function>XtUnmanageChildren()</function>.  Calling
+<function>XtUnmanageChildren()</function> is more efficient, however,
+because it only calls the parent's <function>change_managed()</function>
+method once.
+</para>
+</refsect1>
+
+<refsect1 id="r1-1007-unmanagechildren-3">
+<title>Algorithm
+</title>
+<para><function>XtUnmanageChildren()</function> performs the following:
+</para>
+<variablelist>
+<varlistentry>
+<term>-
+</term>
+<listitem>
+<para>Ignores the child if it already is unmanaged or is being
+destroyed.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>-
+</term>
+<listitem>
+<para>Otherwise, if the child is realized, it makes it nonvisible
+by unmapping it.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+<para>
+</para>
+</refsect1>
+
+<refsect1 id="r1-1007-unmanagechildren-4">
+<title>Structures</title>
+<para>The <type>WidgetList</type> type is simply an array of widgets:
+</para>
+<screen id="sc-1007-unmanagechildren-1">typedef Widget *WidgetList;
+</screen>
+</refsect1>
+</refentry>
+
+</chapter>
+
+<chapter id="faq">
+<title>Questions and Answers</title>
+
+
+&reporting.bugs;
+&updating.documentation;
+
+<qandaset id="faqlist">
+<qandaentry>
+<question>
+<para>My Mouse doesn't work. How do I quit &appname;?</para>
+</question>
+<answer>
+<para>You silly goose! Check out the <link linkend="commands">Commands
+Section</link> for the answer.</para>
+</answer>
+</qandaentry>
+<qandaentry>
+<question>
+<para>Why can't I twiddle my documents?</para>
+</question>
+<answer>
+<para>You can only twiddle your documents if you have the foobar.lib
+installed.</para>
+</answer>
+</qandaentry>
+</qandaset>
+</chapter>
+-->
+<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>
+&appname;
+</para>
+<para>
+Program copyright 2005 Simon Edwards <email>simon@simonzone.com</email>
+</para>
+<para>
+Contributors:
+<itemizedlist>
+<listitem><para>Konqui the KDE Dragon <email>konqui@kde.org</email></para>
+</listitem>
+<listitem><para>Tux the Linux Penguin <email>tux@linux.org</email></para>
+</listitem>
+</itemizedlist>
+</para>
+
+<para>
+Documentation copyright 2005 Simon Edwards <email>simon@simonzone.com</email>
+</para>
+
+<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+
+&underFDL;               <!-- FDL: do not remove -->
+</chapter>
+<!--
+<appendix id="installation">
+<title>Installation</title>
+
+<sect1 id="getting-appname">
+<title>How to obtain &appname;</title>
+
+&install.intro.documentation;
+
+</sect1>
+
+<sect1 id="requirements">
+<title>Requirements</title>
+
+<para>
+In order to successfully use &appname;, you need &kde; 1.1. Foobar.lib is
+required in order to support the advanced &appname; features. &appname; uses
+about 5 megs of memory to run, but this may vary depending on your
+platform and configuration.
+</para>
+
+<para>
+All required libraries as well as &appname; itself can be found
+on <ulink url="ftp://ftp.appname.org">The &appname; home page</ulink>.
+</para>
+
+<para>
+You can find a list of changes at <ulink
+url="http://apps.kde.org/appname">http://apps.kde.org/appname</ulink>.
+</para>
+</sect1>
+
+<sect1 id="compilation">
+<title>Compilation and Installation</title>
+
+&install.compile.documentation;
+
+</sect1>
+
+<sect1 id="configuration">
+<title>Configuration</title>
+
+<para>Don't forget to tell your system to start the <filename>dtd</filename>
+dicer-toaster daemon first, or &appname; won't work !</para>
+
+</sect1>
+
+</appendix>
+-->
+&documentation.index;
+</book>
+
+<!--
+Local Variables:
+mode: sgml
+sgml-minimize-attributes:nil
+sgml-general-insert-case:lower
+sgml-indent-step:0
+sgml-indent-data:nil
+End:
+
+vim:tabstop=2:shiftwidth=2:expandtab 
+-->
+