You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
875 lines
28 KiB
875 lines
28 KiB
<?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"><!-- tdebase, tdeadmin, 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 & 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="pytdeextensions",
|
|
version="0.1.0",
|
|
author="Simon Edwards",
|
|
author_email="simon@simonzone.com",
|
|
url="http://www.simonzone.com/software/pytdeextensions/",
|
|
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 & 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 tdeui 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 & 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/trinityarch/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 “Algorithm” 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
|
|
-->
|
|
|