mutter/doc/reference/clutter-docs.sgml
Neil Roberts dd7ff3e829 2008-03-26 Neil Roberts <neil@o-hand.com>
* clutter/win32/clutter-win32.h: Added gtk-doc documentation for
	the Win32 backend section.

	* clutter/win32/clutter-stage-win32.c
	(clutter_win32_get_stage_window): Fixed punctuation in the
	documentation.

	* README: Added notes about the Win32 backend.

2008-03-26  Neil Roberts  <neil@o-hand.com>

	* clutter-sections.txt: Added a section for the Win32 specific
	API.

	* clutter-docs.sgml: Added comments about the Win32 backend.

	* Makefile.am: Added bits to ignore the headers for the Win32
	backend.
2008-03-26 22:22:32 +00:00

496 lines
16 KiB
XML

<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY version SYSTEM "version.xml">
<!ENTITY clutter-SubclassingActor SYSTEM "xml/subclassing-ClutterActor.sgml">
<!ENTITY clutter-animation SYSTEM "xml/clutter-animation.sgml">
<!ENTITY creating-your-own-behaviours SYSTEM "xml/creating-your-own-behaviours.sgml">
]>
<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
<bookinfo>
<title>Clutter &version; Reference Manual</title>
<releaseinfo>Version &version;</releaseinfo>
<copyright>
<year>2008</year>
<holder>OpenedHand LTD</holder>
</copyright>
<legalnotice>
<para>
Permission is granted to copy, distribute and/or modify this
document under the terms of the <citetitle>GNU Free
Documentation License</citetitle>, Version 1.1 or any later
version published by the Free Software Foundation with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover
Texts. You may obtain a copy of the <citetitle>GNU Free
Documentation License</citetitle> from the Free Software
Foundation by visiting <ulink type="http"
url="http://www.fsf.org">their Web site</ulink> or by writing
to:
<address>
The Free Software Foundation, Inc.,
<street>59 Temple Place</street> - Suite 330,
<city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>,
<country>USA</country>
</address>
</para>
</legalnotice>
</bookinfo>
<part id="clutter">
<title>Clutter Overview</title>
<partintro>
<para>
Clutter is a GObject based library for creating fast, visually
rich, graphical user interfaces.
</para>
<para>
Clutter works by manipulating a scene-graph of 2D surfaces, or 'actors',
inside a 3D space.
</para>
<para>
#ClutterActor is the base class for such surfaces. All
#ClutterActor<!-- -->s can be positioned, scaled and rotated in 3D space.
In addition, other properties can be set, such as 2D clipping, children and
opacity. Tranforms applied to a parent actor also apply to any children.
Actors are also able to receive events.
</para>
<para>
Subclasses of #ClutterActor include #ClutterStage, #ClutterTexture,
#ClutterLabel, #ClutterRectangle, #ClutterEntry and
#ClutterGroup. #ClutterActor<!-- -->s are added to a parent, transformed
and then made visible.
</para>
<para>
#ClutterStage is the top level #ClutterActor - it's the representation
of a window, or framebuffer. It is created automatically when Clutter is
initialised. #ClutterStage is a #ClutterGroup, a class
implementing the #ClutterCointainer interface. Clutter currently
only supports a single stage.
</para>
<para>
#ClutterTimeline<!-- -->s provide the basis for Clutter's animation
utilities. Multiple timelines can be synchronised using #ClutterScore,
and #ClutterBehaviour and #ClutterEffect allow for the creation of
animation effects such as transitions.
</para>
<para>
Clutter further contains a number of utilities, including;
#ClutterScript - for loading 'UI definition' files formatted in
JSON, #ClutterShader - a class for applying GPU shaders to actors,
#ClutterModel - a utility class for MVC list type implementations
and #ClutterFixed - fixed point math utilities.
</para>
</partintro>
</part>
<part id="clutterbuilding">
<title>Building Clutter</title>
<partintro>
<section id='dependencies'>
<title>Clutter Dependencies</title>
<variablelist>
<varlistentry>
<term>GLib</term>
<listitem>
<para>A general-purpose utility library, not specific to
graphical user interfaces. GLib provides many useful data
types, macros, type conversions, string utilities, file
utilities, a main loop abstraction, and so on.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>GObject</term>
<listitem>
<para>The GLib Object System provides the required
implementations of a flexible, extensible and intentionally
easy to map (into other languages) object-oriented framework
for C.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Pango</term>
<listitem>
<para>Pango is a library for laying out and rendering
text, with an emphasis on internationalization.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>GDK-Pixbuf</term>
<listitem>
<para>GDK-Pixbuf is a library for loading and manipulating
various image file formats.</para>
</listitem>
<term>Backend Windowing System Library</term>
<listitem>
<para>GLX, EGL (1.1), SDL, Cocoa (OS X) and WGL (Windows)</para>
</listitem>
<term>Graphics Rendering </term>
<listitem>
<para>Open GL (1.2+) ir Open GL ES (1.1) </para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section id='building-instructions'>
<title>Platform-specific instructions</title>
<section id='building-linux'>
<title>Linux</title>
<para>If you are using Debian or Ubuntu, you can install pre-compiled
binary packages the normal Debian way following the instructions at
<ulink type="http" url="http://debian.o-hand.com/">
http://debian.o-hand.com/</ulink>.
</para>
<para>To build Clutter clutter from sources, get the latest source
archives from <ulink type="http"
url="http://www.clutter-project.org/sources/">
http://www.clutter-project.org/sources/</ulink>. Once you have extracted
the sources from the archive execute the following commands in the
top-level directory:
</para>
<literallayout>
./configure
make
make install
</literallayout>
<para>You can configure the build with number of additional arguments
passed to the configure script, the full list of which can be obtained
by running ./configure --help. The following arguments are specific to
Clutter:
<variablelist>
<varlistentry>
<term>--enable-debug=[no/minimum/yes]</term>
<listitem>
<para>Turns on debugging. Possible values are: yes - all
glib asserts, checks and runtime clutter verbose messages;
minimum - just glib cast checks and runtime clutter verbose
messagaes; no - no glib asserts or checks and no runtime
clutter verbose messages; default=yes.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>--enable-maintainer-flags=[no/yes]</term>
<listitem>
<para>Use strict compiler flags; default=no.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>--enable-gtk-doc</term>
<listitem>
<para>Use gtk-doc to build documentation; default=no.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>--enable-manual=[no/yes]</term>
<listitem>
<para>Build application developers manual; requires jw and
xmlto binaries; default=no.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>--with-flavour=[glx/eglx/eglnative/sdl]</term>
<listitem>
<para>Select the Clutter backend; default=glx.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</section>
<section id='building-windows'>
<title>Windows</title>
<para>
The recommended way of building Clutter for Windows is using the
<ulink type="http" url="http://www.mingw.org/">mingw</ulink> tool
chain. One option is to cross-compile Clutter under Linux -- you
can use the script found in the <filename>build/mingw/</filename>
directory to simplify the process (the script takes care of setting
up the necessary dependencies).
</para>
<para>
If you wish to build Clutter using mingw direcly under Windows, you
can do so the normal *nix way (described above) using the mingw
POSIX shell. Should you prefer to use Microsoft Visual Studio, a
project file for MSVC 2005 is located in the
<filename>build/msvc_2k5/</filename> directory. In either case, you
will need to first install the required dependencies.
</para>
<para>
There are currently two backends that are supported on
Windows. One uses the Win32 and WGL APIs directly and the
other is built on top of SDL. You must choose one of the
backends when running the configure script using the
following argument:
<variablelist>
<varlistentry>
<term>--with-flavour=[win32/sdl]</term>
<listitem>
<para>Select the Clutter backend; default=glx.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</section>
<section id='building-osx'>
<title>OSX</title>
<para>The recommended way of building Clutter on OSX is to use
<ulink href="http://live.gnome.org/Jhbuild">Jhbuild</ulink>,
following the documentation for building the GTK+ stack as shown
<ulink href="http://developer.imendio.com/projects/gtk-macosx/build-instructions">here</ulink>.
</para>
<para>
Jhbuild depends on SVN, which can be installed on OSX by using
the <ulink href="http://www.macports.org/">MacPorts</ulink>
project.
</para>
<para>
XCode should also be installed, either from the OSX installation
disk or downloading it from the Apple website.
</para>
<para>
Due to Clutter's dependency on GDK-Pixbuf, GTK+ for OSX must
also be built. After building GTK+, extract the files from
Clutter's release tar archive or check out the project from
SVN. Clutter OSX backend is built by passing the
<literal>--with-flavour=osx</literal> command line argument
to the configure script.
</para>
<para>
GTK-Doc is not working on OSX, so API reference generation
should also be disabled when building Clutter, by using
the <literal>--disable-docs</literal> and
<literal>--disable-gtk-doc</literal> command line argument
to the configure script.
</para>
</section>
</section>
</partintro>
</part>
<part id="clutterbase">
<title>Clutter Core Reference</title>
<chapter>
<title>Abstract classes and interfaces</title>
<xi:include href="xml/clutter-actor.xml"/>
<xi:include href="xml/clutter-container.xml"/>
<xi:include href="xml/clutter-media.xml"/>
</chapter>
<chapter>
<title>Base actors</title>
<xi:include href="xml/clutter-rectangle.xml"/>
<xi:include href="xml/clutter-texture.xml"/>
<xi:include href="xml/clutter-clone-texture.xml"/>
<xi:include href="xml/clutter-label.xml"/>
<xi:include href="xml/clutter-entry.xml"/>
</chapter>
<chapter>
<title>Container actors</title>
<xi:include href="xml/clutter-group.xml"/>
<xi:include href="xml/clutter-stage.xml"/>
</chapter>
</part>
<part id="clutteranimation">
<title>Clutter Animation Support</title>
<chapter>
<title>Base classes</title>
<xi:include href="xml/clutter-timeline.xml"/>
<xi:include href="xml/clutter-score.xml"/>
<xi:include href="xml/clutter-alpha.xml"/>
<xi:include href="xml/clutter-behaviour.xml"/>
</chapter>
<chapter>
<title>Behaviours</title>
<xi:include href="xml/clutter-behaviour-bspline.xml"/>
<xi:include href="xml/clutter-behaviour-depth.xml"/>
<xi:include href="xml/clutter-behaviour-ellipse.xml"/>
<xi:include href="xml/clutter-behaviour-opacity.xml"/>
<xi:include href="xml/clutter-behaviour-path.xml"/>
<xi:include href="xml/clutter-behaviour-rotate.xml"/>
<xi:include href="xml/clutter-behaviour-scale.xml"/>
</chapter>
<chapter>
<title>Simple effects API</title>
<xi:include href="xml/clutter-effect.xml"/>
</chapter>
</part>
<part>
<title>Clutter Tools</title>
<chapter>
<title>General purpose API</title>
<xi:include href="xml/clutter-color.xml"/>
<xi:include href="xml/clutter-event.xml"/>
<xi:include href="xml/clutter-fixed.xml"/>
<xi:include href="xml/clutter-main.xml"/>
<xi:include href="xml/clutter-shader.xml"/>
<xi:include href="xml/clutter-units.xml"/>
<xi:include href="xml/clutter-util.xml"/>
<xi:include href="xml/clutter-version.xml"/>
</chapter>
<chapter>
<title>User interface definition</title>
<xi:include href="xml/clutter-script.xml"/>
<xi:include href="xml/clutter-scriptable.xml"/>
</chapter>
<chapter>
<title>Generic list model</title>
<xi:include href="xml/clutter-model.xml"/>
<xi:include href="xml/clutter-model-iter.xml"/>
<xi:include href="xml/clutter-list-model.xml"/>
</chapter>
</part>
<part>
<title>Clutter Backends</title>
<partintro>
<para>Clutter is usually compiled against a specific drawing backend.
All backends have a common API for querying the underlying platform,
and some of them might have specific API exposed by Clutter.</para>
</partintro>
<xi:include href="xml/clutter-backend.xml"/>
<xi:include href="xml/clutter-x11.xml"/>
<xi:include href="xml/clutter-win32.xml"/>
</part>
<part>
<title>Additional Documentation</title>
<partintro>
<para>This section contains additional useful documentation for
developing with Clutter.</para>
</partintro>
&clutter-SubclassingActor;
&clutter-animation;
&creating-your-own-behaviours;
</part>
<index>
<title>Index</title>
</index>
<index role="deprecated">
<title>Index of deprecated symbols</title>
</index>
<index role="0.2">
<title>Index of new symbols in 0.2</title>
</index>
<index role="0.4">
<title>Index of new symbols in 0.4</title>
</index>
<index role="0.6">
<title>Index of new symbols in 0.6</title>
</index>
<appendix id="license">
<title>License</title>
<para>
This library is free software; you can redistribute it and/or
modify it under the terms of the <citetitle>GNU Library General
Public License</citetitle> as published by the Free Software
Foundation; either version 2 of the License, or (at your option)
any later version.
</para>
<para>
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
<citetitle>GNU Library General Public License</citetitle> for
more details.
</para>
<para>
You may obtain a copy of the <citetitle>GNU Library General
Public License</citetitle> from the Free Software Foundation by
visiting <ulink type="http" url="http://www.fsf.org">their Web
site</ulink> or by writing to:
<address>
Free Software Foundation, Inc.
<street>59 Temple Place</street> - Suite 330
<city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>
<country>USA</country>
</address>
</para>
</appendix>
</book>