enum HippoPackFlags

typedef enum
{
    HIPPO_PACK_EXPAND = 1,  /**< This is equivalent to both EXPAND and FILL for GtkBox,
                             * the way you'd get FILL=false is to set the alignment
                             * on the child item
                             */
    HIPPO_PACK_END = 2,
    HIPPO_PACK_FIXED = 4,   /**< Like position: absolute or GtkFixed */
    HIPPO_PACK_IF_FITS = 8, /**< Can hide this child to make space if allocation is too small
                             * for the child's width request. 
                             * Include child width in box's natural width but not box's request.
                             * (doesn't work in vertical boxes for now)
                             */
    /* Floated children: only works with vertical box, and cannot be used in combination
     * with HIPPO_PACK_EXPAND or HIPPO_PACK_END
     */
    HIPPO_PACK_FLOAT_LEFT = 16,   /* Float to the left */
    HIPPO_PACK_FLOAT_RIGHT = 32,  /* Float to the right */
    HIPPO_PACK_CLEAR_LEFT = 64,   /* Pack below left-floated children */
    HIPPO_PACK_CLEAR_RIGHT = 128, /* Pack below right-floated children */
    HIPPO_PACK_CLEAR_BOTH = 192   /* Pack below left-and right floated children */
} HippoPackFlags;

enum HippoCascadeMode

typedef enum {
    HIPPO_CASCADE_MODE_NONE,
    HIPPO_CASCADE_MODE_INHERIT
} HippoCascadeMode;

HippoCanvasCompareChildFunc ()

int                 (*HippoCanvasCompareChildFunc)      (HippoCanvasItem *child_a,
                                                         HippoCanvasItem *child_b,
                                                         void *data);

HippoCanvasForeachChildFunc ()

void                (*HippoCanvasForeachChildFunc)      (HippoCanvasItem *child,
                                                         void *data);

HippoCanvasBox

typedef struct _HippoCanvasBox HippoCanvasBox;

hippo_canvas_box_new ()

HippoCanvasItem*    hippo_canvas_box_new                (void);

hippo_canvas_box_prepend ()

void                hippo_canvas_box_prepend            (HippoCanvasBox *box,
                                                         HippoCanvasItem *child,
                                                         HippoPackFlags flags);

See hippo_canvas_box_append() for all the details.

hippo_canvas_box_append ()

void                hippo_canvas_box_append             (HippoCanvasBox *box,
                                                         HippoCanvasItem *child,
                                                         HippoPackFlags flags);

Adds a child item to the box. HIPPO_PACK_END means the child should be added at the end of the box while normally the child would be added at the start of the box. This is just like the "pack end" concept in GtkBox. HIPPO_PACK_FIXED means the child is not included in the layout algorithm, you have to set its position manually with hippo_canvas_box_set_position(). HIPPO_PACK_IF_FITS means the child is "all or nothing"; if there isn't room to give all children their natural width, then the "if fits" children can be dropped. Dropping some children is often nicer than having all the children squished or forcing the entire box to be too big.

If you are familiar with GTK+ widget layout, note that GtkMisc functionality (alignment and padding) are incorporated into the items themselves in the form of the alignment and border/padding properties. GtkFixed functionality is part of HippoCanvasBox because children can be packed HIPPO_PACK_FIXED. HippoCanvasBox has an orientation property, rather than two subclasses for horizontal and vertical. And HIPPO_PACK_IF_FITS is not available in GTK+ because it requires the "natural size" vs. "minimum size" distinction that GTK+ lacks.

hippo_canvas_box_move ()

void                hippo_canvas_box_move               (HippoCanvasBox *box,
                                                         HippoCanvasItem *child,
                                                         HippoGravity gravity,
                                                         int x,
                                                         int y);

hippo_canvas_box_set_position ()

void                hippo_canvas_box_set_position       (HippoCanvasBox *box,
                                                         HippoCanvasItem *child,
                                                         int x,
                                                         int y);

hippo_canvas_box_get_position ()

void                hippo_canvas_box_get_position       (HippoCanvasBox *box,
                                                         HippoCanvasItem *child,
                                                         int *x,
                                                         int *y);

hippo_canvas_box_clear ()

void                hippo_canvas_box_clear              (HippoCanvasBox *box);

Removes all children from the box and calls hippo_canvas_item_destroy() on them.

hippo_canvas_box_remove ()

void                hippo_canvas_box_remove             (HippoCanvasBox *box,
                                                         HippoCanvasItem *child);

hippo_canvas_box_remove_all ()

void                hippo_canvas_box_remove_all         (HippoCanvasBox *box);

Removes all children from the box without destroying them. You probably want hipppo_canvas_box_clear() instead unless you have a particular reason to preserve the children. The explicit destroy added by hipppo_canvas_box_clear() will make your application more robust against memory leaks.

hippo_canvas_box_get_children ()

GList*              hippo_canvas_box_get_children       (HippoCanvasBox *box);

hippo_canvas_box_is_empty ()

gboolean            hippo_canvas_box_is_empty           (HippoCanvasBox *box);

hippo_canvas_box_foreach ()

void                hippo_canvas_box_foreach            (HippoCanvasBox *box,
                                                         HippoCanvasForeachChildFunc func,
                                                         void *data);

hippo_canvas_box_reverse ()

void                hippo_canvas_box_reverse            (HippoCanvasBox *box);

hippo_canvas_box_sort ()

void                hippo_canvas_box_sort               (HippoCanvasBox *box,
                                                         HippoCanvasCompareChildFunc compare_func,
                                                         void *data);

hippo_canvas_box_insert_after ()

void                hippo_canvas_box_insert_after       (HippoCanvasBox *box,
                                                         HippoCanvasItem *child,
                                                         HippoCanvasItem *ref_child,
                                                         HippoPackFlags flags);

hippo_canvas_box_insert_before ()

void                hippo_canvas_box_insert_before      (HippoCanvasBox *box,
                                                         HippoCanvasItem *child,
                                                         HippoCanvasItem *ref_child,
                                                         HippoPackFlags flags);

hippo_canvas_box_insert_sorted ()

void                hippo_canvas_box_insert_sorted      (HippoCanvasBox *box,
                                                         HippoCanvasItem *child,
                                                         HippoPackFlags flags,
                                                         HippoCanvasCompareChildFunc compare_func,
                                                         void *data);

hippo_canvas_box_set_child_packing ()

void                hippo_canvas_box_set_child_packing  (HippoCanvasBox *box,
                                                         HippoCanvasItem *child,
                                                         HippoPackFlags flags);

hippo_canvas_box_get_background_area ()

void                hippo_canvas_box_get_background_area
                                                        (HippoCanvasBox *box,
                                                         HippoRectangle *area);

hippo_canvas_box_align ()

void                hippo_canvas_box_align              (HippoCanvasBox *box,
                                                         int content_width,
                                                         int content_height,
                                                         int *x_p,
                                                         int *y_p,
                                                         int *width_p,
                                                         int *height_p);

This is a "protected" method intended for use by HippoCanvasBox subclasses (basically all items are box subclasses right now). Pass in a size request, and have it converted to the right place to actually draw, with padding/border removed and alignment performed. In other words this sorts out the padding, border, and xalign/yalign properties for you.

hippo_canvas_box_set_clickable ()

void                hippo_canvas_box_set_clickable      (HippoCanvasBox *box,
                                                         gboolean clickable);

hippo_canvas_box_is_clickable ()

gboolean            hippo_canvas_box_is_clickable       (HippoCanvasBox *box);

hippo_canvas_box_set_layout ()

void                hippo_canvas_box_set_layout         (HippoCanvasBox *box,
                                                         HippoCanvasLayout *layout);

Sets the layout manager to use for the box. A layout manager provides an alternate method of laying out the children of a box. Once you set a layout manager for the box, you will typically want to add children to the box using the methods of the layout manager, rather than the methods of the box, so that you can specify packing options that are specific to the layout manager.

hippo_canvas_box_find_box_child ()

HippoCanvasBoxChild* hippo_canvas_box_find_box_child    (HippoCanvasBox *box,
                                                         HippoCanvasItem *item);

Locates the HippoCanvasBoxChild object for an item that is a child of the box.

hippo_canvas_box_get_layout_children ()

GList*              hippo_canvas_box_get_layout_children
                                                        (HippoCanvasBox *box);

Return the list of children that a layout manager should manage. As compared to hippo_canvas_box_get_children() this list omits widgets that are not visible, positioned at a fixed position, or not geometry managed for some other reason. It also returns a list of HippoCanvasBoxChild rather than a list of HippoCanvasItem.

If you are implementing a layout manager that iterates over the box's child list directly (to save creating the list, say), you should check the 'in_layout' property of each child before laying it out.

HippoCanvasBoxChild

typedef struct {
    HippoCanvasItem *item;

    /* If this is false, layout managers should ignore this item */
    guint            in_layout : 1;

    guint            expand : 1;
    guint            end : 1;
    guint            fixed : 1;
    guint            if_fits : 1;
    guint            float_left : 1;
    guint            float_right : 1;
    guint            clear_left : 1;
    guint            clear_right : 1;
    guint            visible : 1;
} HippoCanvasBoxChild;

HippoCanvasBoxChild holds data associated with an item that has been added to a canvas box. It is used by implementations of HippoCanvasLayout when implementing methods like get_width_request and size_allocate.

The life-cycle of a HippoCanvasBoxChild is effectively until the item is removed from its parent. If a reference is held beyond that point, calling methods on the box child is safe, but the methods will have no effect, and defaults results will be returned.

hippo_canvas_box_child_ref ()

HippoCanvasBoxChild* hippo_canvas_box_child_ref         (HippoCanvasBoxChild *child);

Release a reference previously added to a HippoCanvasBoxChild. If ther are no more outstanding references to the box child (including references held by the parent box), the child and associated data will be freed.

hippo_canvas_box_child_unref ()

void                hippo_canvas_box_child_unref        (HippoCanvasBoxChild *child);

hippo_canvas_box_child_get_qdata ()

gpointer            hippo_canvas_box_child_get_qdata    (HippoCanvasBoxChild *child,
                                                         GQuark key);

Retrieves data previously stored with hippo_canvas_box_child_set_qdata()

hippo_canvas_box_child_set_qdata ()

void                hippo_canvas_box_child_set_qdata    (HippoCanvasBoxChild *child,
                                                         GQuark key,
                                                         gpointer data,
                                                         GDestroyNotify notify);

Associates data with a HippoCanvasBoxChild object

hippo_canvas_box_child_get_width_request ()

void                hippo_canvas_box_child_get_width_request
                                                        (HippoCanvasBoxChild *child,
                                                         int *min_width_p,
                                                         int *natural_width_p);

hippo_canvas_box_child_get_height_request ()

void                hippo_canvas_box_child_get_height_request
                                                        (HippoCanvasBoxChild *child,
                                                         int for_width,
                                                         int *min_height_p,
                                                         int *natural_height_p);

hippo_canvas_box_child_allocate ()

void                hippo_canvas_box_child_allocate     (HippoCanvasBoxChild *child,
                                                         int x,
                                                         int y,
                                                         int width,
                                                         int height,
                                                         gboolean origin_changed);

The "background-color" property

  "background-color"         guint                 : Read / Write

Sets an RGBA background color (pack the color into 32-bit unsigned int, just type "0xff0000ff" for example for opaque red). The background color covers the padding but not the border of the box.

Default value: 4294967040

The "border" property

  "border"                   gint                  : Write

Write-only convenience property to set border-top, border-bottom, border-left, and border-right all at once.

Allowed values: [0,255]

Default value: 0

The "border-bottom" property

  "border-bottom"            gint                  : Read / Write

Space outside the background color, on the bottom edge. Contrast with the padding, which is inside the background color.

Allowed values: [0,255]

Default value: 0

The "border-color" property

  "border-color"             guint                 : Read / Write

Sets an RGBA border color (pack the color into 32-bit unsigned int, just type "0xff0000ff" for example for opaque red). The border color covers the border of the box; you have to set the border to a nonzero size with the border property.

Frequently, the border is transparent and just used for spacing.

Default value: 4294967040

The "border-left" property

  "border-left"              gint                  : Read / Write

Space outside the background color, on the left edge. Contrast with the padding, which is inside the background color.

Allowed values: [0,255]

Default value: 0

The "border-right" property

  "border-right"             gint                  : Read / Write

Space outside the background color, on the right edge. Contrast with the padding, which is inside the background color.

Allowed values: [0,255]

Default value: 0

The "border-top" property

  "border-top"               gint                  : Read / Write

Space outside the background color, on the top edge. Contrast with the padding, which is inside the background color.

Allowed values: [0,255]

Default value: 0

The "box-height" property

  "box-height"               gint                  : Read / Write

This forces both the natural and minimum height (for the entire box, including border and padding). It should probably be deprecated in favor of separate natural-height and min-height properties, and potentially those properties should not include the border and/or padding. Feel free to analyze and then resolve the issue and send us a patch!

Allowed values: >= -1

Default value: -1

The "box-width" property

  "box-width"                gint                  : Read / Write

This forces both the natural and minimum width (for the entire box, including border and padding). It should probably be deprecated in favor of separate natural-width and min-width properties, and potentially those properties should not include the border and/or padding. Feel free to analyze and then resolve the issue and send us a patch!

Allowed values: >= -1

Default value: -1

The "color" property

  "color"                    guint                 : Read / Write

This property only matters if the subclass of HippoCanvasBox you are using supports it. Specifically text items use this color for the text color.

The value is an RGBA color, i.e. a 32-bit unsigned int, "0xff0000ff" for example for opaque red.

This property is ignored if the color-set property is FALSE.

Default value: 255

The "color-cascade" property

  "color-cascade"            HippoCascadeMode      : Read / Write

If the color-set property is FALSE, this property determines whether the item inherits its foreground color property from its containing canvas item, or whether the item uses a default color which may depend on the canvas item type.

Default value: HIPPO_CASCADE_MODE_INHERIT

The "color-set" property

  "color-set"                gboolean              : Read / Write

Determines whether the color property is used, or whether a default color is used according to the color-cascade property. This flag gets set automatically if you write to the color property.

Default value: FALSE

The "debug-name" property

  "debug-name"               gchararray            : Read / Write

If set, debug-spew detailed information about size negotiation, prefixed with this name

Default value: NULL

The "font" property

  "font"                     gchararray            : Read / Write

The font to use as a Pango font description string. Only matters for text items, or for boxes that contain text items. If a box contains text items, and the child items have the font-cascade property set to HIPPO_CASCADE_MODE_INHERIT, then the child items will use the font from the containing box unless they have explicitly set their own font.

This property is just a way to set the font-desc property, using a string instead of a PangoFontDescription object.

Default value: NULL

The "font-cascade" property

  "font-cascade"             HippoCascadeMode      : Read / Write

If the font-desc property is NULL, this property determines whether the item inherits its font property from its containing canvas item, or whether the item uses a default font.

Default value: HIPPO_CASCADE_MODE_INHERIT

The "font-desc" property

  "font-desc"                PangoFontDescription  : Read / Write

The font to use for text in the item and its children. Children will inherit this font if their font-cascade is set to HIPPO_CASCADE_MODE_INHERIT and they don't set a font themselves.

If the font description is NULL then the font will be inherited or a default will be used, according to the font-cascade property.

The "orientation" property

  "orientation"              HippoOrientation      : Read / Write

A box can stack items vertically HIPPO_ORIENTATION_VERTICAL, like GtkVBox, or put them in a horizontal row, HIPPO_ORIENTATION_HORIZONTAL, like GtkHBox.

Default value: HIPPO_ORIENTATION_VERTICAL

The "padding" property

  "padding"                  gint                  : Write

Write-only convenience property to set padding-top, padding-bottom, padding-left, and padding-right all at once.

Allowed values: [0,255]

Default value: 0

The "padding-bottom" property

  "padding-bottom"           gint                  : Read / Write

Space inside the background color, on the bottom edge. Contrast with the border, which is outside the background color.

Allowed values: [0,255]

Default value: 0

The "padding-left" property

  "padding-left"             gint                  : Read / Write

Space inside the background color, on the left edge. Contrast with the border, which is outside the background color.

Allowed values: [0,255]

Default value: 0

The "padding-right" property

  "padding-right"            gint                  : Read / Write

Space inside the background color, on the right edge. Contrast with the border, which is outside the background color.

Allowed values: [0,255]

Default value: 0

The "padding-top" property

  "padding-top"              gint                  : Read / Write

Space inside the background color, on the top edge. Contrast with the border, which is outside the background color.

Allowed values: [0,255]

Default value: 0

The "spacing" property

  "spacing"                  gint                  : Read / Write

The spacing is a gap to leave between all child items in the box. If you want a gap in only one place, try setting a transparent border on one side of the child, rather than setting the spacing.

Allowed values: [0,255]

Default value: 0

The "tooltip" property

  "tooltip"                  gchararray            : Read / Write

A string to display as a tooltip on this canvas item.

Default value: NULL

The "xalign" property

  "xalign"                   HippoItemAlignment    : Read / Write

Remember that most canvas items, including text and image items, derive from HippoCanvasBox. The alignment properties determine whether the "content" of the box - which may be the child items, image, text, or other main point of the canvas item you're using - will be aligned start (left/top), aligned center, aligned end (right/bottom), or stretched to fill the whole box.

Alignment only matters if the box gets extra space (more space than the natural size of the item).

Default value: HIPPO_ALIGNMENT_FILL

The "yalign" property

  "yalign"                   HippoItemAlignment    : Read / Write

Remember that most canvas items, including text and image items, derive from HippoCanvasBox. The alignment properties determine whether the "content" of the box - which may be the child items, image, text, or other main point of the canvas item you're using - will be aligned start (left/top), aligned center, aligned end (right/bottom), or stretched to fill the whole box.

Alignment only matters if the box gets extra space (more space than the natural size of the item).

Default value: HIPPO_ALIGNMENT_FILL

The "hovering-changed" signal

void                user_function                      (HippoCanvasBox *hippocanvasbox,
                                                        gboolean        arg1,
                                                        gpointer        user_data)           : Run Last