![]() |
![]() |
![]() |
Hippo-Canvas Reference Manual | ![]() |
---|---|---|---|---|
#include <hippo/hippo-canvas-box.h> enum HippoPackFlags; int (*HippoCanvasCompareChildFunc) (HippoCanvasItem *child_a, HippoCanvasItem *child_b, void *data); void (*HippoCanvasForeachChildFunc) (HippoCanvasItem *child, void *data); HippoCanvasBox; HippoCanvasItem* hippo_canvas_box_new (void); void hippo_canvas_box_prepend (HippoCanvasBox *box, HippoCanvasItem *child, HippoPackFlags flags); void hippo_canvas_box_append (HippoCanvasBox *box, HippoCanvasItem *child, HippoPackFlags flags); void hippo_canvas_box_move (HippoCanvasBox *box, HippoCanvasItem *child, HippoGravity gravity, int x, int y); void hippo_canvas_box_set_position (HippoCanvasBox *box, HippoCanvasItem *child, int x, int y); void hippo_canvas_box_get_position (HippoCanvasBox *box, HippoCanvasItem *child, int *x, int *y); void hippo_canvas_box_clear (HippoCanvasBox *box); void hippo_canvas_box_remove (HippoCanvasBox *box, HippoCanvasItem *child); void hippo_canvas_box_remove_all (HippoCanvasBox *box); GList* hippo_canvas_box_get_children (HippoCanvasBox *box); gboolean hippo_canvas_box_is_empty (HippoCanvasBox *box); void hippo_canvas_box_foreach (HippoCanvasBox *box, HippoCanvasForeachChildFunc func, void *data); void hippo_canvas_box_reverse (HippoCanvasBox *box); void hippo_canvas_box_sort (HippoCanvasBox *box, HippoCanvasCompareChildFunc compare_func, void *data); void hippo_canvas_box_insert_after (HippoCanvasBox *box, HippoCanvasItem *child, HippoCanvasItem *ref_child, HippoPackFlags flags); void hippo_canvas_box_insert_before (HippoCanvasBox *box, HippoCanvasItem *child, HippoCanvasItem *ref_child, HippoPackFlags flags); void hippo_canvas_box_insert_sorted (HippoCanvasBox *box, HippoCanvasItem *child, HippoPackFlags flags, HippoCanvasCompareChildFunc compare_func, void *data); void hippo_canvas_box_set_child_packing (HippoCanvasBox *box, HippoCanvasItem *child, HippoPackFlags flags); void hippo_canvas_box_get_background_area (HippoCanvasBox *box, HippoRectangle *area); 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); void hippo_canvas_box_set_clickable (HippoCanvasBox *box, gboolean clickable); gboolean hippo_canvas_box_is_clickable (HippoCanvasBox *box); void hippo_canvas_box_set_layout (HippoCanvasBox *box, HippoCanvasLayout *layout); HippoCanvasBoxChild* hippo_canvas_box_find_box_child (HippoCanvasBox *box, HippoCanvasItem *item); GList* hippo_canvas_box_get_layout_children (HippoCanvasBox *box); HippoCanvasBoxChild; HippoCanvasBoxChild* hippo_canvas_box_child_ref (HippoCanvasBoxChild *child); void hippo_canvas_box_child_unref (HippoCanvasBoxChild *child); gpointer hippo_canvas_box_child_get_qdata (HippoCanvasBoxChild *child, GQuark key); void hippo_canvas_box_child_set_qdata (HippoCanvasBoxChild *child, GQuark key, gpointer data, GDestroyNotify notify); void hippo_canvas_box_child_get_width_request (HippoCanvasBoxChild *child, int *min_width_p, int *natural_width_p); void hippo_canvas_box_child_get_height_request (HippoCanvasBoxChild *child, int for_width, int *min_height_p, int *natural_height_p); void hippo_canvas_box_child_allocate (HippoCanvasBoxChild *child, int x, int y, int width, int height, gboolean origin_changed);
GObject +----HippoCanvasBox +----HippoCanvasImage +----HippoCanvasText +----HippoCanvasGradient
HippoCanvasBox implements HippoCanvasItem, HippoCanvasContext and HippoCanvasContainer.
"background-color" guint : Read / Write "background-color-set" gboolean : Read / Write "border" gint : Write "border-bottom" gint : Read / Write "border-color" guint : Read / Write "border-color-set" gboolean : Read / Write "border-left" gint : Read / Write "border-right" gint : Read / Write "border-top" gint : Read / Write "box-height" gint : Read / Write "box-width" gint : Read / Write "color" guint : Read / Write "color-set" gboolean : Read / Write "debug-name" gchar* : Read / Write "font" gchar* : Read / Write "font-desc" PangoFontDescription* : Read / Write "orientation" HippoOrientation : Read / Write "padding" gint : Write "padding-bottom" gint : Read / Write "padding-left" gint : Read / Write "padding-right" gint : Read / Write "padding-top" gint : Read / Write "spacing" gint : Read / Write "tooltip" gchar* : Read / Write "xalign" HippoItemAlignment : Read / Write "yalign" HippoItemAlignment : Read / Write
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;
int (*HippoCanvasCompareChildFunc) (HippoCanvasItem *child_a, HippoCanvasItem *child_b, void *data);
|
|
|
|
|
|
Returns : |
void (*HippoCanvasForeachChildFunc) (HippoCanvasItem *child, void *data);
|
|
|
void hippo_canvas_box_prepend (HippoCanvasBox *box, HippoCanvasItem *child, HippoPackFlags flags);
See hippo_canvas_box_append()
for all the details.
|
the canvas box |
|
the child to prepend |
|
flags for how to layout the child |
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.
|
the canvas box |
|
the child to append |
|
flags for how to layout the child |
void hippo_canvas_box_move (HippoCanvasBox *box, HippoCanvasItem *child, HippoGravity gravity, int x, int y);
|
|
|
|
|
|
|
|
|
void hippo_canvas_box_set_position (HippoCanvasBox *box, HippoCanvasItem *child, int x, int y);
|
|
|
|
|
|
|
void hippo_canvas_box_get_position (HippoCanvasBox *box, HippoCanvasItem *child, int *x, int *y);
|
|
|
|
|
|
|
void hippo_canvas_box_clear (HippoCanvasBox *box);
Removes all children from the box and calls hippo_canvas_item_destroy()
on them.
|
the canvas box |
void hippo_canvas_box_remove (HippoCanvasBox *box, HippoCanvasItem *child);
|
|
|
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.
|
the canvas box |
GList* hippo_canvas_box_get_children (HippoCanvasBox *box);
|
|
Returns : |
gboolean hippo_canvas_box_is_empty (HippoCanvasBox *box);
|
|
Returns : |
void hippo_canvas_box_foreach (HippoCanvasBox *box, HippoCanvasForeachChildFunc func, void *data);
|
|
|
|
|
void hippo_canvas_box_sort (HippoCanvasBox *box, HippoCanvasCompareChildFunc compare_func, void *data);
|
|
|
|
|
void hippo_canvas_box_insert_after (HippoCanvasBox *box, HippoCanvasItem *child, HippoCanvasItem *ref_child, HippoPackFlags flags);
|
|
|
|
|
|
|
void hippo_canvas_box_insert_before (HippoCanvasBox *box, HippoCanvasItem *child, HippoCanvasItem *ref_child, HippoPackFlags flags);
|
|
|
|
|
|
|
void hippo_canvas_box_insert_sorted (HippoCanvasBox *box, HippoCanvasItem *child, HippoPackFlags flags, HippoCanvasCompareChildFunc compare_func, void *data);
|
|
|
|
|
|
|
|
|
void hippo_canvas_box_set_child_packing (HippoCanvasBox *box, HippoCanvasItem *child, HippoPackFlags flags);
|
|
|
|
|
void hippo_canvas_box_get_background_area (HippoCanvasBox *box, HippoRectangle *area);
|
|
|
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.
|
|
|
width of the content of your item (text, image, children, whatever) |
|
height of the content |
|
output the X origin where you should put your content |
|
output the Y origin where you should put your content |
|
output the width of your content (may exceed the passed-in width/height if alignment mode is HIPPO_ALIGNMENT_FILL for example) |
|
output the height of your content |
void hippo_canvas_box_set_clickable (HippoCanvasBox *box, gboolean clickable);
|
|
|
gboolean hippo_canvas_box_is_clickable (HippoCanvasBox *box);
|
|
Returns : |
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.
|
a HippoCanvasBox |
|
the layout manager to set on the box or NULL to use the
default box layout manager.
|
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.
|
a HippoCanvasBox |
|
the canvas item to find the child object for |
Returns : |
The HippoCanvasBoxChild for the child item, or NULL if the
item is not a child of the box. No reference is added to the returned
item.
|
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.
|
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.)
|
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.
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.
|
a HippoCanvasBoxChild |
Returns : |
void hippo_canvas_box_child_unref (HippoCanvasBoxChild *child);
|
gpointer hippo_canvas_box_child_get_qdata (HippoCanvasBoxChild *child, GQuark key);
Retrieves data previously stored with hippo_canvas_box_child_set_qdata()
|
a HippoCanvasBoxChild |
|
a GQuark identifying the data to retrieve |
Returns : |
the data previously stored, or NULL if data was not
previously stored for the given key.
|
void hippo_canvas_box_child_set_qdata (HippoCanvasBoxChild *child, GQuark key, gpointer data, GDestroyNotify notify);
Associates data with a HippoCanvasBoxChild object
|
a HippoCanvasBoxChild |
|
a GQuark identifying the data to store |
|
the data to store |
|
a function to call when the data is replaced or the box child is freed |
void hippo_canvas_box_child_get_width_request (HippoCanvasBoxChild *child, int *min_width_p, int *natural_width_p);
|
|
|
|
|
void hippo_canvas_box_child_get_height_request (HippoCanvasBoxChild *child, int for_width, int *min_height_p, int *natural_height_p);
|
|
|
|
|
|
|
void hippo_canvas_box_child_allocate (HippoCanvasBoxChild *child, int x, int y, int width, int height, gboolean origin_changed);
|
|
|
|
|
|
|
|
|
|
|
"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.
This property is ignored if the background-color-set property is FALSE
.
Default value: 4294967040
"background-color-set"
property"background-color-set" gboolean : Read / Write
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.
Default value: FALSE
"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
"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
"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
"border-color-set"
property"border-color-set" gboolean : Read / Write
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.
Default value: FALSE
"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
"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
"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
"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
"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
"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
"color-set"
property"color-set" gboolean : Read / Write
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.
Default value: FALSE
"debug-name"
property"debug-name" gchar* : Read / Write
If set, debug-spew detailed information about size negotiation, prefixed with this name
Default value: NULL
"font"
property"font" gchar* : Read / Write
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.
Default value: NULL
"font-desc"
property"font-desc" PangoFontDescription* : Read / Write
The font to use for text in the item, overriding any font from the style. The font will not be inherited by child items.
"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
"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
"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
"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
"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
"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
"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
"tooltip"
property"tooltip" gchar* : Read / Write
A string to display as a tooltip on this canvas item.
Default value: NULL
"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
"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
"hovering-changed"
signalvoid user_function (HippoCanvasBox *hippocanvasbox, gboolean arg1, gpointer user_data) : Run Last
|
the object which received the signal. |
|
|
|
user data set when the signal handler was connected. |