HippoCanvasBox

HippoCanvasBox

Functions

Properties

guint background-color Read / Write
gboolean background-color-set Read / Write
gint border Write
gint border-bottom Read / Write
guint border-color Read / Write
gboolean border-color-set Read / Write
gint border-left Read / Write
gint border-right Read / Write
gint border-top Read / Write
gint box-height Read / Write
gint box-width Read / Write
guint color Read / Write
gboolean color-set Read / Write
gchar * debug-name Read / Write
gchar * font Read / Write
PangoFontDescription * font-desc Read / Write
HippoOrientation orientation Read / Write
gint padding Write
gint padding-bottom Read / Write
gint padding-left Read / Write
gint padding-right Read / Write
gint padding-top Read / Write
gint spacing Read / Write
gchar * tooltip Read / Write
HippoItemAlignment xalign Read / Write
HippoItemAlignment yalign Read / Write

Signals

void hovering-changed Run Last

Types and Values

Object Hierarchy

    GObject
    ╰── HippoCanvasBox
        ├── HippoCanvasImage
        ├── HippoCanvasText
        ╰── HippoCanvasGradient

Implemented Interfaces

HippoCanvasBox implements HippoCanvasItem, HippoCanvasContext and HippoCanvasContainer.

Includes

#include <hippo/hippo-canvas-box.h>

Description

Functions

HippoCanvasCompareChildFunc ()

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


HippoCanvasForeachChildFunc ()

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


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.

Parameters

box

the canvas box

 

child

the child to prepend

 

flags

flags for how to layout the child

 

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.

Parameters

box

the canvas box

 

child

the child to append

 

flags

flags for how to layout the child

 

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.

Parameters

box

the canvas box

 

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.

Parameters

box

the canvas box

 

hippo_canvas_box_get_children ()

GList *
hippo_canvas_box_get_children (HippoCanvasBox *box);

Returns

.

[element-type CanvasBoxChild*][transfer container]


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.

Parameters

content_width

width of the content of your item (text, image, children, whatever)

 

content_height

height of the content

 

x_p

output the X origin where you should put your content

 

y_p

output the Y origin where you should put your content

 

width_p

output the width of your content (may exceed the passed-in width/height if alignment mode is HIPPO_ALIGNMENT_FILL for example)

 

height_p

output the height of your content

 

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.

Parameters

box

a HippoCanvasBox

 

layout

the layout manager to set on the box or NULL to use the default box layout manager.

 

hippo_canvas_box_find_box_child ()

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


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.

Parameters

box

a HippoCanvasBox

 

Returns

a list of HippoCanvasBoxChild. The list should be freed with g_list_free(), but the members don't have to be freed. (No reference count is added to them.).

[element-type CanvasBoxChild*][transfer container]


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.

Parameters

child

a HippoCanvasBoxChild

 

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

Parameters

child

a HippoCanvasBoxChild

 

key

a GQuark identifying the data to retrieve

 

Returns

the data previously stored, or NULL if data was not previously stored for the given key.


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

Parameters

child

a HippoCanvasBoxChild

 

key

a GQuark identifying the data to store

 

data

the data to store

 

notify

a function to call when the data is replaced or the box child is freed

 

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

Types and Values

enum HippoPackFlags

Members

HIPPO_PACK_EXPAND

   

HIPPO_PACK_END

   

HIPPO_PACK_FIXED

   

HIPPO_PACK_IF_FITS

   

HIPPO_PACK_FLOAT_LEFT

   

HIPPO_PACK_FLOAT_RIGHT

   

HIPPO_PACK_CLEAR_LEFT

   

HIPPO_PACK_CLEAR_RIGHT

   

HIPPO_PACK_CLEAR_BOTH

   

struct HippoCanvasBox

struct HippoCanvasBox;


struct HippoCanvasBoxChild

struct HippoCanvasBoxChild {
    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 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.

Property Details

The “background-color” property

  “background-color”         guint

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.

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

Flags: Read / Write

Default value: 4294967040


The “background-color-set” property

  “background-color-set”     gboolean

Determines whether the background-color property is used, or whether the color is determined from the item's style. This flag gets set automatically if you write to the background-color property.

Flags: Read / Write

Default value: FALSE


The “border” property

  “border”                   gint

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

Flags: Write

Allowed values: [0,255]

Default value: 0


The “border-bottom” property

  “border-bottom”            gint

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

Flags: Read / Write

Allowed values: [0,255]

Default value: 0


The “border-color” property

  “border-color”             guint

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.

Flags: Read / Write

Default value: 4294967040


The “border-color-set” property

  “border-color-set”         gboolean

Determines whether the border-color property is used, or whether the color is determined from the item's style. This flag gets set automatically if you write to the border-color property.

Flags: Read / Write

Default value: FALSE


The “border-left” property

  “border-left”              gint

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

Flags: Read / Write

Allowed values: [0,255]

Default value: 0


The “border-right” property

  “border-right”             gint

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

Flags: Read / Write

Allowed values: [0,255]

Default value: 0


The “border-top” property

  “border-top”               gint

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

Flags: Read / Write

Allowed values: [0,255]

Default value: 0


The “box-height” property

  “box-height”               gint

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!

Flags: Read / Write

Allowed values: >= -1

Default value: -1


The “box-width” property

  “box-width”                gint

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!

Flags: Read / Write

Allowed values: >= -1

Default value: -1


The “color” property

  “color”                    guint

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.

Flags: Read / Write

Default value: 255


The “color-set” property

  “color-set”                gboolean

Determines whether the color property is used, or whether the color is determined from the item's style. This flag gets set automatically if you write to the color property.

Flags: Read / Write

Default value: FALSE


The “debug-name” property

  “debug-name”               gchar *

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

Flags: Read / Write

Default value: NULL


The “font” property

  “font”                     gchar *

The font to use as a Pango font description string. Only matters for text items, or for boxes that contain text items, overriding any font from the item's style. The font will not be inherited by child items.

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

Flags: Read / Write

Default value: NULL


The “font-desc” property

  “font-desc”                PangoFontDescription *

The font to use for text in the item, overriding any font from the style. The font will not be inherited by child items.

Flags: Read / Write


The “orientation” property

  “orientation”              HippoOrientation

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

Flags: Read / Write

Default value: HIPPO_ORIENTATION_VERTICAL


The “padding” property

  “padding”                  gint

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

Flags: Write

Allowed values: [0,255]

Default value: 0


The “padding-bottom” property

  “padding-bottom”           gint

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

Flags: Read / Write

Allowed values: [0,255]

Default value: 0


The “padding-left” property

  “padding-left”             gint

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

Flags: Read / Write

Allowed values: [0,255]

Default value: 0


The “padding-right” property

  “padding-right”            gint

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

Flags: Read / Write

Allowed values: [0,255]

Default value: 0


The “padding-top” property

  “padding-top”              gint

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

Flags: Read / Write

Allowed values: [0,255]

Default value: 0


The “spacing” property

  “spacing”                  gint

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.

Flags: Read / Write

Allowed values: [0,255]

Default value: 0


The “tooltip” property

  “tooltip”                  gchar *

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

Flags: Read / Write

Default value: NULL


The “xalign” property

  “xalign”                   HippoItemAlignment

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

Flags: Read / Write

Default value: HIPPO_ALIGNMENT_FILL


The “yalign” property

  “yalign”                   HippoItemAlignment

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

Flags: Read / Write

Default value: HIPPO_ALIGNMENT_FILL

Signal Details

The “hovering-changed” signal

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

Parameters

hippocanvasbox

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last