## ClutterFlowLayout

ClutterFlowLayout — A reflowing layout manager

## Synopsis

    enum                ClutterFlowOrientation;
    struct              ClutterFlowLayout;
    struct              ClutterFlowLayoutClass;
    ClutterLayoutManager * clutter_flow_layout_new          (ClutterFlowOrientation orientation);
    void                clutter_flow_layout_set_homogeneous (ClutterFlowLayout *layout,
                                                             gboolean homogeneous);
    gboolean            clutter_flow_layout_get_homogeneous (ClutterFlowLayout *layout);
    void                clutter_flow_layout_set_orientation (ClutterFlowLayout *layout,
                                                             ClutterFlowOrientation orientation);
    ClutterFlowOrientation clutter_flow_layout_get_orientation
                                                            (ClutterFlowLayout *layout);
    void                clutter_flow_layout_set_snap_to_grid
                                                            (ClutterFlowLayout *layout,
                                                             gboolean snap_to_grid);
    gboolean            clutter_flow_layout_get_snap_to_grid
                                                            (ClutterFlowLayout *layout);

    void                clutter_flow_layout_set_column_spacing
                                                            (ClutterFlowLayout *layout,
                                                             gfloat spacing);
    gfloat              clutter_flow_layout_get_column_spacing
                                                            (ClutterFlowLayout *layout);
    void                clutter_flow_layout_set_row_spacing (ClutterFlowLayout *layout,
                                                             gfloat spacing);
    gfloat              clutter_flow_layout_get_row_spacing (ClutterFlowLayout *layout);
    void                clutter_flow_layout_set_column_width
                                                            (ClutterFlowLayout *layout,
                                                             gfloat min_width,
                                                             gfloat max_width);
    void                clutter_flow_layout_get_column_width
                                                            (ClutterFlowLayout *layout,
                                                             gfloat *min_width,
                                                             gfloat *max_width);
    void                clutter_flow_layout_set_row_height  (ClutterFlowLayout *layout,
                                                             gfloat min_height,
                                                             gfloat max_height);
    void                clutter_flow_layout_get_row_height  (ClutterFlowLayout *layout,
                                                             gfloat *min_height,
                                                             gfloat *max_height);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----ClutterLayoutManager
                   +----ClutterFlowLayout

## Properties

      "column-spacing"           gfloat                : Read / Write
      "homogeneous"              gboolean              : Read / Write
      "max-column-width"         gfloat                : Read / Write
      "max-row-height"           gfloat                : Read / Write
      "min-column-width"         gfloat                : Read / Write
      "min-row-height"           gfloat                : Read / Write
      "orientation"              ClutterFlowOrientation  : Read / Write / Construct
      "row-spacing"              gfloat                : Read / Write
      "snap-to-grid"             gboolean              : Read / Write

## Description

ClutterFlowLayout is a layout manager which implements the following policy:

- the preferred natural size depends on the value of the "orientation" property; the layout will try to maintain all its children on a single row or column;

- if either the width or the height allocated are smaller than the preferred ones, the layout will wrap; in this case, the preferred height or width, respectively, will take into account the amount of columns and rows;

- each line (either column or row) in reflowing will have the size of the biggest cell on that line; if the "homogeneous" property is set to `FALSE` the actor will be allocated within that area, and if set to `TRUE` instead the actor will be given exactly that area;

- the size of the columns or rows can be controlled for both minimum and maximum; the spacing can also be controlled in both columns and rows.

Figure 5. Horizontal flow layout

The image shows a ClutterFlowLayout with the "orientation" propert set to `CLUTTER_FLOW_HORIZONTAL`.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    135
    136
    137
    138
    139
    140
    141
    142
    143
    144
    145
    146
    147
    148
    149
    150
    151
    152
    153
    154
    155
    156
    157
    158
    159
    160
    161
    162
    163
    164

    #include <stdlib.h>
    #include <gmodule.h>
    #include <cairo.h>
    #include <clutter/clutter.h>

    #define N_RECTS         20

    static gboolean is_homogeneous = FALSE;
    static gboolean vertical       = FALSE;
    static gboolean random_size    = FALSE;
    static gboolean fixed_size     = FALSE;
    static gboolean snap_to_grid   = TRUE;

    static gint     n_rects        = N_RECTS;
    static gint     x_spacing      = 0;
    static gint     y_spacing      = 0;

    static GOptionEntry entries[] = {
      {
        "random-size", 'r',
        0,
        G_OPTION_ARG_NONE,
        &random_size,
        "Randomly size the rectangles", NULL
      },
      {
        "num-rects", 'n',
        0,
        G_OPTION_ARG_INT,
        &n_rects,
        "Number of rectangles", "RECTS"
      },
      {
        "vertical", 'v',
        0,
        G_OPTION_ARG_NONE,
        &vertical,
        "Set vertical orientation", NULL
      },
      {
        "homogeneous", 'h',
        0,
        G_OPTION_ARG_NONE,
        &is_homogeneous,
        "Whether the layout should be homogeneous", NULL
      },
      {
        "x-spacing", 0,
        0,
        G_OPTION_ARG_INT,
        &x_spacing,
        "Horizontal spacing between elements", "PX"
      },
      {
        "y-spacing", 0,
        0,
        G_OPTION_ARG_INT,
        &y_spacing,
        "Vertical spacing between elements", "PX"
      },
      {
        "fixed-size", 'f',
        0,
        G_OPTION_ARG_NONE,
        &fixed_size,
        "Fix the layout size", NULL
      },
      {
        "no-snap-to-grid", 's',
        G_OPTION_FLAG_REVERSE,
        G_OPTION_ARG_NONE,
        &snap_to_grid,
        "Don't snap elements to grid", NULL
      },
      { NULL }
    };

    int
    main (int argc, char *argv[])
    {
      ClutterActor *stage, *box;
      ClutterLayoutManager *layout;
      GError *error;
      gint i;

      error = NULL;
      if (clutter_init_with_args (&argc, &argv,
                                  NULL,
                                  entries,
                                  NULL,
                                  &error) != CLUTTER_INIT_SUCCESS)
        {
          g_print ("Unable to run flow-layout: %s", error->message);
          g_error_free (error);

          return EXIT_FAILURE;
        }

      stage = clutter_stage_new ();
      clutter_actor_set_background_color (stage, CLUTTER_COLOR_LightSkyBlue);
      clutter_stage_set_title (CLUTTER_STAGE (stage), "Flow Layout");
      clutter_stage_set_user_resizable (CLUTTER_STAGE (stage), TRUE);
      g_signal_connect (stage, "destroy", G_CALLBACK (clutter_main_quit), NULL);

      layout = clutter_flow_layout_new (vertical ? CLUTTER_FLOW_VERTICAL
                                                 : CLUTTER_FLOW_HORIZONTAL);
      clutter_flow_layout_set_homogeneous (CLUTTER_FLOW_LAYOUT (layout),
                                           is_homogeneous);
      clutter_flow_layout_set_column_spacing (CLUTTER_FLOW_LAYOUT (layout),
                                              x_spacing);
      clutter_flow_layout_set_row_spacing (CLUTTER_FLOW_LAYOUT (layout),
                                           y_spacing);
      clutter_flow_layout_set_snap_to_grid (CLUTTER_FLOW_LAYOUT (layout),
                                            snap_to_grid);

      box = clutter_actor_new ();
      clutter_actor_set_layout_manager (box, layout);
      clutter_actor_set_background_color (box, CLUTTER_COLOR_Aluminium2);
      clutter_actor_add_child (stage, box);

      if (!fixed_size)
        clutter_actor_add_constraint (box, clutter_bind_constraint_new (stage, CLUTTER_BIND_SIZE, 0.0));

      clutter_actor_set_position (box, 0, 0);
      clutter_actor_set_name (box, "box");

      for (i = 0; i < n_rects; i++)
        {
          ClutterColor color = CLUTTER_COLOR_INIT (255, 255, 255, 255);
          gfloat width, height;
          ClutterActor *rect;
          gchar *name;

          name = g_strdup_printf ("rect%02d", i);

          clutter_color_from_hls (&color,
                                  360.0 / n_rects * i,
                                  0.5,
                                  0.8);
          rect = clutter_actor_new ();
          clutter_actor_set_background_color (rect, &color);

          if (random_size)
            {
              width = g_random_int_range (50, 100);
              height = g_random_int_range (50, 100);
            }
          else
            width = height = 50.f;

          clutter_actor_set_size (rect, width, height);
          clutter_actor_set_name (rect, name);

          clutter_actor_add_child (box, rect);

          g_free (name);
        }

      clutter_actor_show (stage);

      clutter_main ();

      return EXIT_SUCCESS;
    }

ClutterFlowLayout is available since Clutter 1.2

## Details

### enum ClutterFlowOrientation

    typedef enum {
     /*< prefix=CLUTTER_FLOW >*/
      CLUTTER_FLOW_HORIZONTAL,
      CLUTTER_FLOW_VERTICAL
    } ClutterFlowOrientation;

The direction of the arrangement of the children inside a ClutterFlowLayout

`CLUTTER_FLOW_HORIZONTAL` | Arrange the children of the flow layout horizontally first
`CLUTTER_FLOW_VERTICAL` | Arrange the children of the flow layout vertically first

Since 1.2

### struct ClutterFlowLayout

    struct ClutterFlowLayout;

The ClutterFlowLayout structure contains only private data and should be accessed using the provided API

Since 1.2

### struct ClutterFlowLayoutClass

    struct ClutterFlowLayoutClass {
    };

The ClutterFlowLayoutClass structure contains only private data and should be accessed using the provided API

Since 1.2

### clutter_flow_layout_new ()

    ClutterLayoutManager * clutter_flow_layout_new          (ClutterFlowOrientation orientation);

Creates a new ClutterFlowLayout with the given `orientation`

`orientation` : | the orientation of the flow layout
Returns : | the newly created ClutterFlowLayout

Since 1.2

### clutter_flow_layout_set_homogeneous ()

    void                clutter_flow_layout_set_homogeneous (ClutterFlowLayout *layout,
                                                             gboolean homogeneous);

Sets whether the `layout` should allocate the same space for each child

`layout` : | a ClutterFlowLayout
`homogeneous` : | whether the layout should be homogeneous or not

Since 1.2

### clutter_flow_layout_get_homogeneous ()

    gboolean            clutter_flow_layout_get_homogeneous (ClutterFlowLayout *layout);

Retrieves whether the `layout` is homogeneous

`layout` : | a ClutterFlowLayout
Returns : | `TRUE` if the ClutterFlowLayout is homogeneous

Since 1.2

### clutter_flow_layout_set_orientation ()

    void                clutter_flow_layout_set_orientation (ClutterFlowLayout *layout,
                                                             ClutterFlowOrientation orientation);

Sets the orientation of the flow layout

The orientation controls the direction used to allocate the children: either horizontally or vertically. The orientation also controls the direction of the overflowing

`layout` : | a ClutterFlowLayout
`orientation` : | the orientation of the layout

Since 1.2

### clutter_flow_layout_get_orientation ()

    ClutterFlowOrientation clutter_flow_layout_get_orientation
                                                            (ClutterFlowLayout *layout);

Retrieves the orientation of the `layout`

`layout` : | a ClutterFlowLayout
Returns : | the orientation of the ClutterFlowLayout

Since 1.2

### clutter_flow_layout_set_snap_to_grid ()

    void                clutter_flow_layout_set_snap_to_grid
                                                            (ClutterFlowLayout *layout,
                                                             gboolean snap_to_grid);

Whether the `layout` should place its children on a grid.

`layout` : | a ClutterFlowLayout
`snap_to_grid` : | `TRUE` if `layout` should place its children on a grid

Since 1.16

### clutter_flow_layout_get_snap_to_grid ()

    gboolean            clutter_flow_layout_get_snap_to_grid
                                                            (ClutterFlowLayout *layout);

Retrieves the value of "snap-to-grid" property

`layout` : | a ClutterFlowLayout
Returns : | `TRUE` if the `layout` is placing its children on a grid

Since 1.16

### clutter_flow_layout_set_column_spacing ()

    void                clutter_flow_layout_set_column_spacing
                                                            (ClutterFlowLayout *layout,
                                                             gfloat spacing);

Sets the space between columns, in pixels

`layout` : | a ClutterFlowLayout
`spacing` : | the space between columns

Since 1.2

### clutter_flow_layout_get_column_spacing ()

    gfloat              clutter_flow_layout_get_column_spacing
                                                            (ClutterFlowLayout *layout);

Retrieves the spacing between columns

`layout` : | a ClutterFlowLayout
Returns : | the spacing between columns of the ClutterFlowLayout, in pixels

Since 1.2

### clutter_flow_layout_set_row_spacing ()

    void                clutter_flow_layout_set_row_spacing (ClutterFlowLayout *layout,
                                                             gfloat spacing);

Sets the spacing between rows, in pixels

`layout` : | a ClutterFlowLayout
`spacing` : | the space between rows

Since 1.2

### clutter_flow_layout_get_row_spacing ()

    gfloat              clutter_flow_layout_get_row_spacing (ClutterFlowLayout *layout);

Retrieves the spacing between rows

`layout` : | a ClutterFlowLayout
Returns : | the spacing between rows of the ClutterFlowLayout, in pixels

Since 1.2

### clutter_flow_layout_set_column_width ()

    void                clutter_flow_layout_set_column_width
                                                            (ClutterFlowLayout *layout,
                                                             gfloat min_width,
                                                             gfloat max_width);

Sets the minimum and maximum widths that a column can have

`layout` : | a ClutterFlowLayout
`min_width` : | minimum width of a column
`max_width` : | maximum width of a column

Since 1.2

### clutter_flow_layout_get_column_width ()

    void                clutter_flow_layout_get_column_width
                                                            (ClutterFlowLayout *layout,
                                                             gfloat *min_width,
                                                             gfloat *max_width);

Retrieves the minimum and maximum column widths

`layout` : | a ClutterFlowLayout
`min_width` : | return location for the minimum column width, or `NULL`. [out]
`max_width` : | return location for the maximum column width, or `NULL`. [out]

Since 1.2

### clutter_flow_layout_set_row_height ()

    void                clutter_flow_layout_set_row_height  (ClutterFlowLayout *layout,
                                                             gfloat min_height,
                                                             gfloat max_height);

Sets the minimum and maximum heights that a row can have

`layout` : | a ClutterFlowLayout
`min_height` : | the minimum height of a row
`max_height` : | the maximum height of a row

Since 1.2

### clutter_flow_layout_get_row_height ()

    void                clutter_flow_layout_get_row_height  (ClutterFlowLayout *layout,
                                                             gfloat *min_height,
                                                             gfloat *max_height);

Retrieves the minimum and maximum row heights

`layout` : | a ClutterFlowLayout
`min_height` : | return location for the minimum row height, or `NULL`. [out]
`max_height` : | return location for the maximum row height, or `NULL`. [out]

Since 1.2

## Property Details

### The `"column-spacing"` property

      "column-spacing"           gfloat                : Read / Write

The spacing between columns, in pixels; the value of this property is honoured by horizontal non-overflowing layouts and by vertical overflowing layouts

Allowed values: >= 0

Default value: 0

Since 1.2

### The `"homogeneous"` property

      "homogeneous"              gboolean              : Read / Write

Whether each child inside the ClutterFlowLayout should receive the same allocation

Default value: FALSE

Since 1.2

### The `"max-column-width"` property

      "max-column-width"         gfloat                : Read / Write

Maximum width for each column in the layout, in pixels. If set to -1 the width will be the maximum child width

Allowed values: >= -1

Default value: -1

Since 1.2

### The `"max-row-height"` property

      "max-row-height"           gfloat                : Read / Write

Maximum height for each row in the layout, in pixels. If set to -1 the width will be the maximum child height

Allowed values: >= -1

Default value: -1

Since 1.2

### The `"min-column-width"` property

      "min-column-width"         gfloat                : Read / Write

Minimum width for each column in the layout, in pixels

Allowed values: >= 0

Default value: 0

Since 1.2

### The `"min-row-height"` property

      "min-row-height"           gfloat                : Read / Write

Minimum height for each row in the layout, in pixels

Allowed values: >= 0

Default value: 0

Since 1.2

### The `"orientation"` property

      "orientation"              ClutterFlowOrientation  : Read / Write / Construct

The orientation of the ClutterFlowLayout. The children of the layout will be layed out following the orientation.

This property also controls the overflowing directions

Default value: CLUTTER_FLOW_HORIZONTAL

Since 1.2

### The `"row-spacing"` property

      "row-spacing"              gfloat                : Read / Write

The spacing between rows, in pixels; the value of this property is honoured by vertical non-overflowing layouts and by horizontal overflowing layouts

Allowed values: >= 0

Default value: 0

Since 1.2

### The `"snap-to-grid"` property

      "snap-to-grid"             gboolean              : Read / Write

Whether the ClutterFlowLayout should arrange its children on a grid

Default value: TRUE

Since 1.16