mutter/clutter/clutter-layout.c

/*
 * Clutter.
 *
 * An OpenGL based 'interactive canvas' library.
 *
 * Authored By Matthew Allum  <mallum@openedhand.com>
 *
 * Copyright (C) 2006 OpenedHand
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * 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 GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 *
 * ClutterLayout: interface to be implemented by actors providing
 *                extended layouts.
 *
 * Author: Emmanuele Bassi <ebassi@openedhand.com>
 */

#include "config.h"

#include "clutter-layout.h"
#include "clutter-main.h"
#include "clutter-private.h"
#include "clutter-units.h"
#include "clutter-debug.h"
#include "clutter-enum-types.h"

#define MAX_TUNE_REQUESTS       3

/**
 * SECTION:clutter-layout
 * @short_description: An interface for implementing layouts
 *
 * #ClutterLayout is an interface that #ClutterActor<!-- -->s might
 * implement to provide complex or extended layouts. The default
 * size allocation of a #ClutterActor inside a #ClutterGroup is to
 * make the group size allocation grow enough to contain the actor.
 * A #ClutterActor implementing the #ClutterLayout interface will
 * be queried for its size when it is added to a #ClutterGroup subclass
 * that honours the #ClutterLayout interface; the resulting size
 * allocation will depend on the #ClutterLayoutFlags that the actor
 * supports.
 *
 * There are various types of layout available for actors implementing
 * the #ClutterLayout interface: %CLUTTER_LAYOUT_WIDTH_FOR_HEIGHT will
 * ask the actor for its width given the height allocated by the
 * container; %CLUTTER_LAYOUT_HEIGHT_FOR_WIDTH will ask the actor for
 * its height given the width allocated by the container. These two
 * layout types are especially useful for labels and unidirectional
 * container types, like vertical and horizontal boxes.
 *
 * Another layout available is %CLUTTER_LAYOUT_NATURAL, which will
 * query the actor for its natural (default) width and height; the
 * container actor will then try to allocate as much as it can,
 * and might resort to scaling the actor to fit the allocation. This
 * layout type is suited for #ClutterTexture<!-- -->s and shapes.
 *
 * Finally, the %CLUTTER_LAYOUT_TUNABLE is an iterative layout. An actor
 * will be queried multiple times until it's satisfied with the size
 * given.
 *
 * A #ClutterGroup subclass that honours the #ClutterLayout interface
 * should check whether an actor is implementing this interface when
 * adding it, by using the %CLUTTER_IS_LAYOUT type check macro. If the
 * actor does implement the interface, the #ClutterGroup should get
 * the supported layouts using clutter_layout_get_layout_flags() and
 * verify which layout is compatible with the group's own layout; for
 * instance, vertical containers should check for actors implementing the
 * %CLUTTER_LAYOUT_WIDTH_FOR_HEIGHT layout management, while horizontal
 * containers should check for actors implementing the
 * %CLUTTER_LAYOUT_HEIGHT_FOR_WIDTH layout management. If the actor
 * satisfies the layout requirements, the container actor should query
 * the actor for a geometry request using the appropriate function and
 * allocate space for the newly added actor accordingly.
 *
 * #ClutterLayout is available since Clutter 0.4
 */

static void
clutter_layout_base_init (gpointer g_iface)
{
  static gboolean initialised = FALSE;

  if (G_UNLIKELY (!initialised))
    {
      initialised = TRUE;

      /**
       * ClutterLayout:layout-flags:
       *
       * The layout types that the #ClutterLayout supports.
       *
       * Since: 0.4
       */
      g_object_interface_install_property (g_iface,
                                           g_param_spec_flags ("layout-flags",
                                                               "Layout Flags",
                                                               "Supported layouts",
                                                               CLUTTER_TYPE_LAYOUT_FLAGS,
                                                               CLUTTER_LAYOUT_NONE,
                                                               CLUTTER_PARAM_READABLE));
  }
}

GType
clutter_layout_get_type (void)
{
  static GType layout_type = 0;

  if (!layout_type)
    {
      GTypeInfo layout_info =
      {
        sizeof (ClutterLayoutIface),
        clutter_layout_base_init,
        NULL,
      };
      
      layout_type = g_type_register_static (G_TYPE_INTERFACE, "ClutterLayout",
                                            &layout_info, 0);
      g_type_interface_add_prerequisite (layout_type, CLUTTER_TYPE_ACTOR);
    }

  return layout_type;
}

/*
 * Public API
 */

/**
 * clutter_layout_get_layout_flags:
 * @layout: a #ClutterLayout
 *
 * Retrieves the supported layout types from the #ClutterLayout
 *
 * Return value: bitwise or of #ClutterLayoutFlags
 *
 * Since: 0.4
 */
ClutterLayoutFlags
clutter_layout_get_layout_flags (ClutterLayout *layout)
{
  g_return_val_if_fail (CLUTTER_IS_LAYOUT (layout), CLUTTER_LAYOUT_NONE);

  if (CLUTTER_LAYOUT_GET_IFACE (layout)->get_layout_flags)
    return CLUTTER_LAYOUT_GET_IFACE (layout)->get_layout_flags (layout);

  return CLUTTER_LAYOUT_NONE;
}

/**
 * clutter_layout_width_for_height:
 * @layout: a #ClutterLayout
 * @width: return location for the width
 * @height: height allocated by the parent
 *
 * Queries a #ClutterLayout actor for its width with a known height.
 *
 * Since: 0.4
 */
void
clutter_layout_width_for_height (ClutterLayout *layout,
                                 gint          *width,
                                 gint           height)
{
  ClutterLayoutFlags layout_type;

  g_return_if_fail (CLUTTER_IS_LAYOUT (layout));

  layout_type = clutter_layout_get_layout_flags (layout);
  if (layout_type & CLUTTER_LAYOUT_WIDTH_FOR_HEIGHT)
    {
      ClutterUnit u_width, u_height;

      u_height = CLUTTER_UNITS_FROM_INT (height);
      CLUTTER_LAYOUT_GET_IFACE (layout)->width_for_height (layout,
                                                           &u_width,
                                                           u_height);
      
      if (width)
        *width = CLUTTER_UNITS_TO_INT (u_width);
    }
  else
    {
      g_warning ("Actor queried for width with a given height, but "
                 "actors of type `%s' do not support width-for-height "
                 "layouts.",
                 g_type_name (G_OBJECT_TYPE (layout)));

      if (width)
        *width = -1;
    }
}

/**
 * clutter_layout_height_for_width:
 * @layout: a #ClutterLayout
 * @width: width allocated by the parent
 * @height: return location for the height
 *
 * Queries a #ClutterLayout actor for its height with a known width.
 *
 * Since: 0.4
 */
void
clutter_layout_height_for_width (ClutterLayout *layout,
                                 gint           width,
                                 gint          *height)
{
  ClutterLayoutFlags layout_type;

  g_return_if_fail (CLUTTER_IS_LAYOUT (layout));

  layout_type = clutter_layout_get_layout_flags (layout);
  if (layout_type & CLUTTER_LAYOUT_HEIGHT_FOR_WIDTH)
    {
      ClutterUnit u_width, u_height;

      u_width = CLUTTER_UNITS_FROM_INT (width);
      CLUTTER_LAYOUT_GET_IFACE (layout)->height_for_width (layout,
                                                           u_width,
                                                           &u_height);
      
      if (height)
        *height = CLUTTER_UNITS_TO_INT (u_height);
    }
  else
    {
      g_warning ("Actor queried for height with a given width, but "
                 "actors of type `%s' do not support height-for-width "
                 "layouts.",
                 g_type_name (G_OBJECT_TYPE (layout)));

      if (height)
        *height = -1;
    }
}

/**
 * clutter_layout_natural_request:
 * @layout: a #ClutterLayout
 * @width: return location for the natural width
 * @height: return location for the natural height
 *
 * Queries a #ClutterLayout actor for its natural (default) width
 * and height.
 *
 * Since: 0.4
 */
void
clutter_layout_natural_request (ClutterLayout *layout,
                                gint          *width,
                                gint          *height)
{
  ClutterLayoutFlags layout_type;

  g_return_if_fail (CLUTTER_IS_LAYOUT (layout));

  layout_type = clutter_layout_get_layout_flags (layout);
  if (layout_type & CLUTTER_LAYOUT_NATURAL)
    {
      ClutterUnit u_width, u_height;

      CLUTTER_LAYOUT_GET_IFACE (layout)->natural_request (layout,
                                                          &u_width,
                                                          &u_height);
    
      if (width)
        *width = CLUTTER_UNITS_TO_INT (u_width);

      if (height)
        *height = CLUTTER_UNITS_TO_INT (u_height);
    }
  else
    {
      g_warning ("Actor queried for natural size, but actors of type `%s' "
                 "do not support natural-size layouts.",
                 g_type_name (G_OBJECT_TYPE (layout)));

      if (width)
        *width = -1;
      if (height)
        *height = -1;
    }
}

/**
 * clutter_layout_tune_request:
 * @layout: a #ClutterLayout
 * @given_width: width allocated by the parent
 * @given_height: height allocated by the parent
 * @width: return location for the new width
 * @height: return location for the new height
 *
 * Iteratively queries a #ClutterLayout actor until it finds
 * its desired size, given a width and height tuple.
 *
 * Since: 0.4
 */
void
clutter_layout_tune_request (ClutterLayout *layout,
                             gint           given_width,
                             gint           given_height,
                             gint          *width,
                             gint          *height)
{
  ClutterLayoutFlags layout_type;
  gint tries;
  ClutterUnit try_width, try_height;
  ClutterUnit new_width, new_height;

  g_return_if_fail (CLUTTER_IS_LAYOUT (layout));

  layout_type = clutter_layout_get_layout_flags (layout);
  if ((layout_type & CLUTTER_LAYOUT_TUNABLE) == 0)
    {
      g_warning ("Actor queried for tunable size size but actors of "
                 "type `%s' do not support tunable layouts.",
                 g_type_name (G_OBJECT_TYPE (layout)));
      
      if (width)
        *width = -1;

      if (height)
        *height = -1;

      return;
    }

  tries = 0;
  try_width = CLUTTER_UNITS_FROM_INT (given_width);
  try_height = CLUTTER_UNITS_FROM_INT (given_height);
  new_width = new_height = 0;

  do
    {
      gboolean res;

      res = CLUTTER_LAYOUT_GET_IFACE (layout)->tune_request (layout,
                                                             try_width,
                                                             try_height,
                                                             &new_width,
                                                             &new_height);

      if (res)
        break;

      if (new_width)
        try_width = new_width;

      if (new_height)
        try_height = new_height;

      new_width = new_height = 0;

      tries += 1;
    }
  while (tries <= MAX_TUNE_REQUESTS);

  if (width)
    *width = CLUTTER_UNITS_TO_INT (new_width);

  if (height)
    *height = CLUTTER_UNITS_TO_INT (new_height);
}