brl/mutter
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

2008-06-26 Emmanuele Bassi <ebassi@openedhand.com>

Browse Source 
* clutter/clutter-overview.xml: Split the overview into its own
	file, so we gtk-doc can linkify all class names.

	* clutter/building-clutter.xml: Split the building instructions
	into its own file, for better maintainability.

	* clutter/clutter-animation.xml:
	* clutter/creating-behaviours.xml:
	* clutter/subclassing-ClutterActor.xml: Rename from SGML to XML;
	these were not SGML files anyway, but templates.

	* clutter/clutter-docs.sgml: Use XInclude instead of the ugly
	entities hack.

	* clutter/Makefile.am: Update the build.
This commit is contained in:
Emmanuele Bassi 2008-06-26 09:02:58 +00:00
parent 93fda92651
commit e7a7307b49
8 changed files with 323 additions and 303 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
doc/reference/ChangeLog
View File

@ -1,3 +1,21 @@
2008-06-26 Emmanuele Bassi <ebassi@openedhand.com>
* clutter/clutter-overview.xml: Split the overview into its own
file, so we gtk-doc can linkify all class names.
* clutter/building-clutter.xml: Split the building instructions
into its own file, for better maintainability.
* clutter/clutter-animation.xml:
* clutter/creating-behaviours.xml:
* clutter/subclassing-ClutterActor.xml: Rename from SGML to XML;
these were not SGML files anyway, but templates.
* clutter/clutter-docs.sgml: Use XInclude instead of the ugly
entities hack.
* clutter/Makefile.am: Update the build.
2008-06-25 Emmanuele Bassi <ebassi@openedhand.com>
* clutter/clutter-sections.txt: Add missing symbols.

18
doc/reference/clutter/Makefile.am
View File

@ -97,18 +97,22 @@ HTML_IMAGES=\
# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
content_files= \
subclassing-ClutterActor.sgml \
clutter-animation.sgml \
creating-your-own-behaviours.sgml \
version.xml
version.xml \
subclassing-ClutterActor.xml \
clutter-animation.xml \
creating-behaviours.xml \
clutter-overview.xml \
building-clutter.xml
# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
# These files must be listed here *and* in content_files
# e.g. expand_content_files=running.sgml
expand_content_files= \
subclassing-ClutterActor.sgml \
clutter-animation.sgml \
creating-your-own-behaviours.sgml
subclassing-ClutterActor.xml \
clutter-animation.xml \
creating-behaviours.xml \
clutter-overview.xml \
building-clutter.xml
# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
# Only needed if you are using gtkdoc-scangobj to dynamically query widget

236
doc/reference/clutter/building-clutter.xml Normal file
View File

@ -0,0 +1,236 @@
<part id="building-clutter">
<partinfo>
<author>
<firstname>Emmanuele</firstname>
<surname>Bassi</surname>
<affiliation>
<address>
<email>ebassi@openedhand.com</email>
</address>
</affiliation>
</author>
</partinfo>
<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>Backend Windowing System Library</term>
<listitem>
<para>GLX, EGL (1.1), SDL, Cocoa (OS X) and WGL (Windows)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Graphics Rendering </term>
<listitem>
<para>Open GL (1.4+) 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>For developing an application with Clutter, the recommended
way of installing it using the <ulink href="http://www.macports.org/">MacPorts</ulink>
project, by simply invoking:</para>
<informalexample><programlisting>
$ sudo port install clutter
</programlisting></informalexample>
<para>on a terminal, after installing and updating MacPorts.</para>
<para>For developing Clutter itself, the recommended way of building
it 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. It is recommended
to also install the X11 development files, even though Clutter
does not strictly depend on them.
</para>
<para>
The Clutter Quartz backend is built by passing the
<literal>--with-flavour=osx</literal> command line argument
to the configure script. If not passed, the GLX backend will
be built. By default, the Quartz backend depends on CoreGraphics
in order to load images into textures, but it can also depend
on GDK-Pixbuf or an internal, highly experimental PNG and JPEG
loader.
</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>

0
doc/reference/clutter/clutter-animation.sgml → doc/reference/clutter/clutter-animation.xml
View File

301
doc/reference/clutter/clutter-docs.sgml
View File

@ -2,9 +2,6 @@
<!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">
@ -40,297 +37,9 @@
</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>For developing an application with Clutter, the recommended
way of installing it using the <ulink href="http://www.macports.org/">MacPorts</ulink>
project, by simply invoking:</para>
<informalexample><programlisting>
$ sudo port install clutter
</programlisting></informalexample>
<para>on a terminal, after installing and updating MacPorts.</para>
<para>For developing Clutter itself, the recommended way of building
it 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. It is recommended
to also install the X11 development files, even though Clutter
does not strictly depend on them.
</para>
<para>
The Clutter Quartz backend is built by passing the
<literal>--with-flavour=osx</literal> command line argument
to the configure script. If not passed, the GLX backend will
be built. By default, the Quartz backend depends on CoreGraphics
in order to load images into textures, but it can also depend
on GDK-Pixbuf or an internal, highly experimental PNG and JPEG
loader.
</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>
<xi:include href="xml/clutter-overview.xml"/>
<xi:include href="xml/building-clutter.xml"/>
<part id="clutterbase">
<title>Clutter Core Reference</title>
@ -453,11 +162,11 @@
developing with Clutter.</para>
</partintro>
&clutter-SubclassingActor;
<xi:include href="subclassing-ClutterActor.xml"/>
&clutter-animation;
<xi:include href="clutter-animation.xml"/>
&creating-your-own-behaviours;
<xi:include href="creating-behaviours.xml"/>
</part>

53
doc/reference/clutter/clutter-overview.xml Normal file
View File

@ -0,0 +1,53 @@
<part id="clutter-overview">
<partinfo>
<author>
<firstname>Emmanuele</firstname>
<surname>Bassi</surname>
<affiliation>
<address>
<email>ebassi@openedhand.com</email>
</address>
</affiliation>
</author>
</partinfo>
<title>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.</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
<ulink type="http" url="http://json.org">JSON</ulink>, #ClutterShader - a
class for applying GPU shaders to actors, #ClutterModel - a utility class
for MVC list type implementations, and fixed point math utilities.</para>
</partintro>
</part>

0
doc/reference/clutter/creating-your-own-behaviours.sgml → doc/reference/clutter/creating-behaviours.xml
View File

0
doc/reference/clutter/subclassing-ClutterActor.sgml → doc/reference/clutter/subclassing-ClutterActor.xml
View File