layout: Add BoxLayout, a single line layout manager

The BoxLayout layout manager implements a layout policy for arranging
children on a single line, either alongside the X axis or alongside the
Y axis.

layout: Report the correct size of FlowLayout

FlowLayout should compute the correct height for the assigned width when
in horizontal flow, and the correct width for the assigned height when
in vertical flow. This means pre-computing the number of lines inside
the get_preferred_width() and get_preferred_height(). We can then cache
the computed column width and row height, cache them inside the layout
and then use them when allocating the children.

layout: Resizing the stage resizes the FlowLayout box

Add some user interaction to verify the dynamic reflowing.

layout: Use the get_request_mode() getter in BinLayout

Instead of using g_object_get(child, "request-mode", ...).

layout: Change the request-mode along with the orientation

When changing the orientation of a FlowLayout, the associated
container should also change its request mode. A horizontally
flowing layout has a height depending on the width, since it
will reflow vertically; similarly, a vertically reflowing layout
will have a width depending on the height.

actor: Add set_request_mode() method

We should not require the use g_object_set()/_get() for accessing
the :request-mode property. A proper accessors pair should be
preferred.

[layout] Remove FlowLayout:wrap

The :wrap property is not implemented, and mostly useless: the
FlowLayout is a reflowing grid. This means that if it receives
less than the preferred width or height in the flow direction
then it should always reflow.

[layout] Rename BinLayout and FlowLayout interactive tests

The BinLayout and FlowLayout interactive tests should be named more
explicitly.

[layout] Skip invisible children in FlowLayout

Skip hidden actors when computing the preferred size and when
allocating.

[layout] Clean up and document FlowLayout

[layout] Snap children of FlowLayout to column/row

Use the column and row size to align each child; with :homogeneous
set to TRUE, or with children with the same size, the FlowLayout
will behave like a reflowing grid.

[layout] Add :homogeneous to FlowLayout

[layout] Initial implementation of FlowLayout

FlowLayout is a layout manager that arranges its children in a
reflowing line; the orientation controls the major axis for the
layout: horizontal, for reflow on the Y axis, and vertical, for
reflow on the X axis.

[layout] Use FixedLayout inside Group

The Group actor should use the FixedLayout layout manager object
to avoid duplicating code.

[layout] Update FixedLayout

The behaviour of ClutterGroup has been fixed with regards to the
preferred size request; the fixed layout manager should use the
same behaviour.

[layout] Typo and whitespace fixes

[layout, box] Add Box:color

Allow setting the background color of a ClutterBox

[layout, docs] Clean up BinLayout documentation

Documentation and code style fixes for BinLayout.

[layout, tests] Use variants for child packing in Box

There are three potential variants to add a child inside a Box
with a BinLayout:

  - clutter_box_pack(), a variadic argument function which
    allows passing arbitrary LayoutMeta properties and values;

  - clutter_bin_layout_add(), which uses the backpointer to
    the container from the LayoutManager and sets the layout
    properties directly without GValue (de)marshalling

  - clutter_container_add_actor() and
    clutter_bin_layout_set_alignment(), similar to the
    clutter_bin_layout_add() function above, but split in two

The test-box interactive test should exercise all three variants.

[layout] Store and use the container inside BinLayout

The BinLayout should store a pointer to the Container that it is
using it as the layout manager.

This allows us to fix the API and drop the additional Container
arguments from set_alignment() and get_alignment().

This also allows us to add a ClutterBinLayout::add() method which
adds an actor and sets the alignment policies without dealing with
variadic arguments functions and GValue (de)marshalling.

[layout] Set a back pointer to Box inside the layout

Use the LayoutManager API to set a back pointer to the Box actor
inside the LayoutManager used by the box.

This also allows us to replace the LayoutManager on a Box, since
the LayoutManager will be able to replace all the metadata if
needed.

[layout] Replace stale LayoutMeta

If a LayoutMeta references a different container and/or layout manager
then we should simply replace it and discard the previous one.

[layout] Allow taking a back pointer to the Container

The LayoutManager implementation might opt to take a back pointer
to the Container that is using the layout instance; this allows
direct access to the container itself from within the implementation.

[layout] Rename Box::add to Box::pack

Since ClutterBox is a ClutterContainer we should avoid naming
collisions between methods.

[layout, docs] Document FixedLayout

[layout] Implement ClutterBox::add

The ClutterBox::add method is a simple wrapper around the Container
add_actor() method and the LayoutManager layout properties API. It
allows adding an actor to a Box and setting the layout properties in
one call.

If the LayoutManager used by the Box does not support layout properties
then the add() method short-circuits out.

Along with the varargs version of the method there's also a vector-based
variant, for language bindings to use.

[layout] Add LayoutMeta

Instead of overloading ClutterChildMeta with both container and layout
metadata and delegate to every LayoutManager implementation to keep a
backpointer to the layout manager instance, we can simply subclass
ChildMeta into LayoutMeta and presto! everything works out pretty well
for everyone.

[layout, docs] Add layout managers sections

Add LayoutManager and its subclasses, and the Box actor to the
gtk-doc machinery needed to generate the API reference.

[layout] Add layers to BinLayout

Each actor managed by a BinLayout policy should reside inside its
own "layer", with horizontal and vertical alignment. The :x-align
and :y-align properties of the BinLayout are the default alignment
policies, which are copied to each new "layer" when it is created.

The set_alignment() and get_alignment() methods of BinLayout can
be changed to operate on a specific "layer".

The whole machinery uses the new ChildMeta support inside the
LayoutManager base abstract class.

[layout] Bind the layout ChildMeta inside Box

The ClutterBox container actor should add and remove ChildMeta to
each actor that has been added and removed to the list of children,
respectively.

[layout] Bind ChildMeta to LayoutManager

The ChildMeta object is a storage for child-container properties,
that is properties that exist only when an actor is inside a specific
container. The LayoutManager delegate class should also have
layout-specific properties -- so, for this job, we can "recycle"
ChildMeta as the storage.

[layout] Document BinLayout

[layout] Notify of alignment changes in BinLayout

Emit the ::layout-changed when the BinLayout alignment policies change.

This will result in a queue_relayout() on the containers using the
BinLayout layout manager.

[layout] Update Box

* Use ::layout-changed to queue a relayout when the layout changes

* Destroy the Box children when destroying the Box

* Allow getting the layout manager from the Box

[layout] Add LayoutManager::layout-changed signal

If a sub-class of LayoutManager wishes to implement a parametrized
layout policy it also needs a way to notify the container using the
layout manager that the layout has changed. We cannot do it directly
and automatically from the LayoutManager because a) it has no back
link to the actor that it is using it and b) it can be attached to
multiple actors.

This is a job for <cue raising dramatic music> signals!

By adding ClutterLayoutManager::layout-changed (and its relative
emitted function) we can notify actors using the layout manager that
the layout parameters have been changed, and thus they should queue
a relayout.

[tests] Add a Box interactive test

[layout] Add BinLayout

A BinLayout is a simple layout manager that allocates a single cell,
providing alignment on both the horizontal and vertical axis.

If the container associated to the BinLayout has more than one child,
the preferred size returned by the layout manager will be as big as
the maximum of the children preferred sizes; the allocation will be
applied to all children - but it will still depend on each child
preferred size and the BinLayout horizontal and vertical alignment
properties.

The supported alignment properties are:

  * center: align the child by centering it
  * start: align the child at the top or left border of the layout
  * end: align the child at the bottom or right border of the layout
  * fill: expand the child to fill the size of the layout
  * fixed: let the child position itself

[layout] Add Fixed layout manager

The FixedLayout layout manager object implements the same layout
policy of ClutterGroup.

[layout] Make LayoutManager a floating object

A layout manager instance makes only sense if it's owned by a
container. For this reason, it should have a floating reference
instead of a full reference on construction; this allows constructing
Boxes like:

  box = clutter_box_new (clutter_fixed_layout_new ());

without leaking the layout manager instance.

[box] Add ClutterBox

ClutterBox is an actor with no layout management. It relies on
a ClutterLayoutManager to perform size requisition and allocation
of its children.

[layout] Add initial implementation of LayoutManager

The LayoutManager class is an abstract proxy for the size requesition
and size allocation process in ClutterActor.

A ClutterLayoutManager sub-class must implement get_preferred_width(),
get_preferred_height() and allocate(); a ClutterContainer using the
LayoutManager API will then proxy the corresponding Actor virtual
functions to the LayoutManager instance. This allows having a generic
"blank" ClutterActor sub-class, implementing the ClutterContainer
interface, which leaves only the layout management implementation to
the application developers.

build: Clean up main Makefile.am

build: Move marshallers and enum types rules out

The rules to create signal marshallers and enumeration GTypes are
usually copied and pasted all over different projects, though they
are pretty generic and, given a little bit of parametrization, can
be put in separate Makefile.am files and included whenever needed.

docs: Allow XInclude fallback for the annotation glossary

docs: Make StageManager a public class

The StageManager API is useful to track the stages of an application.
It will also be useful when we land the modules API.

stage/manager: Set :default-stage as read-only

The StageManager:default-stage property should be read-only, since
the default stage is owned by Clutter itself.

stage/manager: Deprecate set_default_stage()

The set_default_stage() method of StageManager should not be used
by application code; technically, nothing in Clutter uses it, and
StageManager's API is not considered public anyway.

[actor] Unset the IN_DESTRUCTION flag when leaving ::destroy()

The IN_DESTRUCTION flag is set around the unrealization and disposal of
the actor in clutter_actor_destroy() but is never unset (it's set twice
instead).

Reviewed-by: Emmanuele Bassi <ebassi@linux.intel.com>

text: Make the :text property not set the :use-markup one

Currently, setting the :text property has the side-effect of
setting the :use-markup property to FALSE. This prevents
constructing a Text actor, or setting its properties, like:

  g_object_set (text,
                "use-markup", TRUE,
                "text", some_string,
                NULL);

as the ordering becomes important. Unfortunately, the ordering
of the properties cannot be enforced with ClutterScript or
with language bindings.

The documentation of the clutter_text_set_text() method should
be expanded to properly specify that the set_text() method will
change the :use-markup property to FALSE as a side effect.

docs: Add the "clipping" section to the COGL API reference

All the clip-related API in COGL is missing from the API reference
because the cogl-clipping section is not included inside the main
index file.

[units] Ensure we don't have ponies

The documentation states we should not parse ponies. Even with those
with exclamation marks.

Reviewed-by: Emmanuele Bassi <ebassi@linux.intel.com>

[path] Add GValue transform functions from and to G_TYPE_STRING

Transform functions allow the use of g_value_transform() to cast
GValues. It's very handy to have casts to and from G_TYPE_STRING as it
allows generic serialization and parsing of GTypes.

Reviewed-by: Emmanuele Bassi <ebassi@linux.intel.com>

[units] Add support for centimeters

The only tricky part of the patch is to remember that 1cm is 10mm.

Reviewed-by: Emmanuele Bassi <ebassi@linux.intel.com>

[units] Be more strict in the grammar we are parsing

Current parsing of units has a number of shortcomings:
  * a number followed by trailing space (without any unit specified) was
    not recognized,
  * "5 emeralds" was parsed as 5em,
  * the way we parse the digits after the separator makes us lose
    precision for no good reason (5.0 is parsed as 5.00010014...f which
    makes g_assert_cmpfloat() fail)

Let's define a stricter grammar we can recognize and try to do so. The
description is in EBNF form, removing the optional <> which is a pain
when having to write DocBook, and using '' for the terminal symbols.

Last step, add more ClutterUnits unit test to get a better coverage of
the grammar we want to parse.

Reviewed-by: Emmanuele Bassi <ebassi@linux.intel.com>

color: Measure the string just once when parsing

Instead of measuring the color hexadecimal string for each case, just
measure it once and then use a switch() to go to the right case.

[color] allow alpha to be omitted when converting to color from string

Parse #rgb and #rrggbb in addition to forms with the alpha channel
specified. This allows conversion of colour strings from documents such as
CSS where the alpha channel is not specified when using '#' notation.

This patch also adds the relevant conformance test.

[clutter-id-pool] Also warn if the ID refers to a deleted actor

We should also warn if the glReadPixels happens to generate an ID that
is within the range of the ID array but no longer points to an
existing actor.

[clutter-id-pool] Fix the check for out-of-range IDs

If id == the length of the array then it is also invalid and could
cause a crash.

Revert "[color] allow alpha to omitted when converting from strings"

This reverts commit eb8daac4b0726c1d9925bbbaeed7a8f39007da21.

The original commit was incorrect and pushed accidentally.

[color] add a note to the documentation to specify the values of the alpha

The alpha channel is fully opaque at 255 and fully transparent at 0.

[color] allow alpha to omitted when converting from strings

Parse #rgb and #rrggbb in addition to forms with the alpha channel
specified. This allows conversion of colour strings from documents such as
CSS where the alpha channel is not specified when using '#' notation.

[path] MOVE_TO and LINE_TO only use a pair of coordinates

The documentation of ClutterPathNode had a small typo and stated that
they use 2 pairs of coordinates.

[debug] Guard the use of gdk_pixbuf for pick debugging by #ifdef USE_GDKPIXBUF

gdk is an optional clutter dependency, so the pick buffer debugging option
needs some guards so we don't break, for example, the OSX builds.  This also
adds a comment for the bit fiddling done on the pick colors used to ensure
the pick colors are more distinguished while debugging.  (we swap the
nibbles of each color component so that pick buffers don't just look black.)

[sdl] Update the SDL backend to the new StageWindow API

The SDL backend remains experimental and not meant for public
consumption, but at least it compiles and runs successfully.

[eglx] Create a StageWindow, not an Actor

The Backend should create a StageWindow instance, not an Actor.

[ClutterGroup] Don't take into account the left edges when calculating the size

ClutterGroup previously calculated the size as the distance from the
left edge of the leftmost child to the right edge of the rightmost
child except if there were any chidren left of the origin then the
left edge would be zero.

However the group is always allocated its size relative to its
origin so if all of the children are to the right of the origin then
the preferred size would not be large enough to reach the rightmost
child.

    origin
    ┼──────────┐
    │Group     │
    │ ┌────────┼─┐
    │ │Child   │ │
    │ │        │ │
    └─┼────────┘ │
      │          │
      └──────────┘
       group size
      ╟──────────╢

This patch makes it so the size is always just the rightmost edge.

    origin
    ┼────────────┐
    │Group       │
    │ ┌──────────┤
    │ │Child     │
    │ │          │
    │ │          │
    │ │          │
    └─┴──────────┘
      group size
    ╟────────────╢

Fixes bug:

  http://bugzilla.openedhand.com/show_bug.cgi?id=1825

[eglx] Update the EGLX Stage to the new StageWindow API

Move the ::realize and ::unrealize implementations over to the
StageWindow instead of using Actor.

Fix string parsing when no unit is given

The check should really be on the character pointed by str. Added the
corresponding test case.

clutter_value_get_unit() has not be renamed

Since the Great Rework of ClutterUnits, functions have been using
'units' not 'unit' in their name. clutter_value_get_unit() is a left
over from a dark age, its declaration and documentation have been
updated but not the symbol itself.

Merge branch 'stage-window-object'

* stage-window-object:
  [x11] Fix Stage user-initiated resize
  [x11] Remove a useless forced paint
  [stage] Rework the Stage implementation class

Clarify the IdPool warning

Instead of having an assertion failure with a message of dubious
usefulness, we should probably use a more verbose warning explaining
what is the problem and what might be the cause.

[x11] Fix Stage user-initiated resize

The user-initiated resize is conflicting with the allocated size. This
happens because we change the size of the stage's X Window behind the
back of the size allocation machinery.

Instead, we should change the size of the actor whenever we receive a
ConfigureNotify event to reflect the new size of the actor.

[x11] Remove a useless forced paint

We force the redraw before mapping, in the hope that when a composited
window manager maps the window it will have its contents ready; that is
not going to work: the solution for this problem requires the implementation
of a protocol for compositors, and not a hack.

Moreover, painting before mapping will cause a paint with the wrong
GL viewport size, which is the wrong thing to do on GLX.

[docs] Update the "Subclassing Actor" chapter

The chapter on how to subclass ClutterActor inside the API reference for
Clutter is still using ClutterUnit and referencing to concepts that have
been changed since the document was written.

[cogl-debug] avoid warnings when using COGL_NOTE with unbraced else clauses

When not building a debug build the compiler was warning about empty
else clauses with no braces due to code like:
  if (blah)
do_foo();
  else
COGL_NOTE (DRAW, "a-wibble");

This simply ensures that even for non debug builds COGL_NOTE will expand to
a single statement.

[cogl-vertex-buffer] fix n_components validation for GL's builtin attributes

glVertexPointer expects positions with 2, 3 or 4 components, glColorPointer
expects colors with 3 or 4 components and glNormalPointer expects normals
with three components so when adding vertex buffer atributes with the names
"gl_Vertex", "gl_Color" or "gl_Normal" we assert these constraints and print
an explanation to the developer if not met.

This also fixes the previosly incorrect constraint that gl_Normal attributes
must have n_components == 1; thanks to Cat Sidhe for reporting this:

Bug: http://bugzilla.openedhand.com/show_bug.cgi?id=1819

[debug] Adds a dump-pick-buffers CLUTTER_DEBUG option

Now if you export CLUTTER_DEBUG=dump-pick-buffers clutter will write out a
png, e.g.  pick-buffer-00000.png, each time _clutter_to_pick() is called.
It's a rather crude way to debug the picking (realtime visualization in a
second stage would probably be nicer) but it we've used this approach
successfully numerous times when debugging Clutter picking issues so it
makes sense to have a debug option for it.

[container] Remove the unused 'object' variable in destroy_child_meta

Since commit b2f958a61 this variable is no longer used so it was
causing compiler warnings.

[tests] Remove test-entry.c since we don't have a ClutterEntry any more

Removes an unused interactive unit test for the old ClutterEntry actor we
used to have.

[backend-egl] fix clutter_backend_egl_get_visual_info to not use Xalloc

It looks like the intention was to duplicate an XVisualInfo in such a way
that the pointer could be returned and then later freed using XFree.  But
Xalloc isn't an Xlib counterpart to XFree; Xlib doesn't provide a general
purpose malloc wrapper afik.  By shuffling things about a bit, it was
possible to avoid the need for this hack.

Add a few annotations on Cogl primitives functions

By default, float * is considered as an out argument by gobject
introspection which is wrong for quite a few Cogl symbols. Start adding
annotations to fix that for the ones in the "Primitives" gtk-doc
section.

[container] cast actor to gobject before calling g_object_set_qdata

A minor compiler warning fix: in destroy_child_meta we weren't casting the
first argument to g_object_set_qdata to a gobject.

[container] unset the child meta qdata on the child, not the container

In the default implementation of container::destroy_child_meta Set child
meta qdata to NULL on the child and not the container, since the child
is the object that owns the data.

[container] set the child meta qdata on the child, not the container

Set child meta qdata on the child and not the container, since the child is
the object that owns the data.

[cogl] Remove CoglContext->journal_vbo{,_len}

The lifetime of the journal VBO is entirely within the scope of the
cogl_journal_flush function so there is no need to store it globally
in the Cogl context. Instead, upload_vertices_to_vbo just returns the
new VBO. cogl_journal_flush stores this in a local variable and
destroys it before returning.

This also fixes an assertion when using the GLES backend which was
caused by nothing initialising the journal_vbo variable.

[build] Split out the custom silent rules

The silent rules we use for custom targets should be moved into a
separate Makefile.am that gets included from all the others.

[test-cogl-multitexture] Print an error if textures can't be loaded

I just wasted a silly amount time trying to bisect an apparently broken
cogl-test-multitexture until I realized it was just silently failing to load
any textures.

[docs] Fix the comment on version bumps

[gitignore] Add test-preferred-size

[timeline] Account for clock roll backs between frames

If the system clock rolls back between two frames then we need
to account for the change, to avoid stopping the timeline.

The best option, since a roll back can be any arbitrary amount
of milliseconds, is to skip a frame.

Fixes bug:

  http://bugzilla.moblin.org/show_bug.cgi?id=3839

[cogl-fbo] Disable mipmap filters before calling glCheckFramebufferStatusEXT

The framebuffer_object spec isn't clear in defining whether attaching a
texture as a renderbuffer with mipmap filtering enabled while the mipmaps
have not been uploaded should result in an incomplete framebuffer object.
(different drivers make different decisions)

To avoid an error with drivers that do consider this a problem we explicitly
set non mipmapped filters before calling glCheckFramebufferStatusEXT.  The
filters will later be reset when the texture is actually used for rendering
according to the filters set on the corresponding CoglMaterial.

[tests] Add preferred size conformance test unit

This unit verifies that an Actor class will invoke the get_preferred_*
virtual functions unless the caching is in effect; it also verifies
that the cached values are correctly evicted.

[tests] Add initial sizing conformance test suite

The size requisition and allocation mechanisms should be thoroughly
tested to avoid unwanted regressions.

For starters, we can test the explicit size setting and the side
effects of calling clutter_actor_set_size().

[container] Use a 1:1 mapping between child and ChildMeta

Since an actor can only be parented to one container we don't need
the extra complications of maintaining a list of ChildMeta objects
attached to an actor in the default implementation of the Container
interface.

[docs] Clutter's model implementation is called ClutterListModel

It was renamed from ClutterModelDefault to ClutterListModel a while
back. Update the reference to this class in ClutterModel documentation.

[docs] Add fixxref for Cairo symbols

Let gtk-doc resolve the Cairo types and symbols to the installed
Cairo documentation.

[docs] Add a Path migration guide

ClutterBehaviourPath has been changed and ClutterBehaviourBspline has
been removed; now we use ClutterPath everywhere we need to describe a
path. This warrants a chapter in the migration guide.

[text] implement get_property for "use-markup"

[stage] Rework the Stage implementation class

Instead of using ClutterActor for the base class of the Stage
implementation we should extend the StageWindow interface with
the required bits (geometry, realization) and use a simple object
class.

This require a wee bit of changes across Backend, Stage and
StageWindow, even though it's mostly re-shuffling.

First of all, StageWindow should get new virtual functions:

  * geometry:
    - resize()
    - get_geometry()

  * realization
    - realize()
    - unrealize()

This covers all the bits that we use from ClutterActor currently
inside the stage implementations.

The ClutterBackend::create_stage() virtual function should create
a StageWindow, and not an Actor (it should always have been; the
fact that it returned an Actor was a leak of the black magic going
on underneath). Since we never guaranteed ABI compatibility for
the Backend class, this is not a problem.

Internally to ClutterStage we can finally drop the shenanigans of
setting/unsetting actor flags on the implementation: if the realization
succeeds, for instance, we set the REALIZED flag on the Stage and
we're done.

As an initial proof of concept, the X11 and GLX stage implementations
have been ported to the New World Order(tm) and show no regressions.

[docs] Small annotation fixes