mutter/doc/reference/clutter/clutter-docs.sgml

<?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>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>


  <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-child-meta.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 Framework</title>

    <partintro>
      <para>Clutter has a fully extensible animation framework
      providing support for explicit and implicit animations of
      single actors as well as groups of actors.</para>
    </partintro>

    <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>

  <index role="0.8">
    <title>Index of new symbols in 0.8</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>