The Base Item

The Base Item

Synopsis


#include <ccc.h>


                    CcItem;
                    CcItemClass;
void                cc_item_class_add_view_data         (gpointer item_class,
                                                         gsize view_data_size);
gpointer            cc_item_get_view_data               (CcItem const*self,
                                                         CcView const*view,
                                                         GType type);
CcItem*             cc_item_new                         (void);
void                cc_item_append                      (CcItem *self,
                                                         CcItem *child);
void                cc_item_dirty                       (CcItem *self,
                                                         CcView const*view,
                                                         CcDRect dirty_region);
gdouble             cc_item_distance                    (CcItem *self,
                                                         CcView const*view,
                                                         gdouble x,
                                                         gdouble y,
                                                         CcItem **found);
void                cc_item_insert                      (CcItem *self,
                                                         CcItem *child,
                                                         gint position);
void                cc_item_remove                      (CcItem *self,
                                                         CcItem *child);
void                cc_item_render                      (CcItem *self,
                                                         CcView *view,
                                                         cairo_t *cr);
void                cc_item_set_grid_aligned            (CcItem *self,
                                                         gboolean grid_aligned);
void                cc_item_lower                       (CcItem *child,
                                                         CcItem *parent);
void                cc_item_lower_to_bottom             (CcItem *child,
                                                         CcItem *parent);
void                cc_item_raise                       (CcItem *child,
                                                         CcItem *parent);
void                cc_item_raise_to_top                (CcItem *child,
                                                         CcItem *parent);
void                cc_item_set_position                (CcItem *child,
                                                         CcItem *parent,
                                                         gint position);
enum                CcItemFlags;
#define             CC_ITEM_FLAGS                       (i)
#define             CC_ITEM_DISPOSED                    (i)
#define             CC_ITEM_GRID_ALIGNED                (i)
#define             CC_ITEM_SET_FLAGS                   (i,m)
#define             CC_ITEM_UNSET_FLAGS                 (i,m)
#define             CC_ITEM_CAN_FOCUS                   (i)
void                (*CcItemFunc)                       (CcItem *item,
                                                         CcView *view,
                                                         gpointer data);
void                cc_item_add_view                    (CcItem *self,
                                                         CcView *view);
void                cc_item_bounds_changed              (CcItem *self,
                                                         CcView const*view);
GType               cc_item_flags_get_type              (void);
void                cc_item_foreach_view                (CcItem *self,
                                                         CcItemFunc func,
                                                         gpointer data);
CcDRectconst*       cc_item_get_all_bounds              (CcItem const*self,
                                                         CcView const*view);
void                cc_item_grab_focus                  (CcItem *self,
                                                         CcView *view);
gboolean            cc_item_is_child_of                 (CcItem const*child,
                                                         CcItem const*parent);
void                cc_item_remove_view                 (CcItem *self,
                                                         CcView *view);
void                cc_item_update_bounds               (CcItem *self,
                                                         gpointer data);
void                cc_item_update_bounds_for_view      (CcItem *self,
                                                         CcView *view);

Object Hierarchy


  GObject
   +----GInitiallyUnowned
         +----CcItem
               +----CcCamera
               +----CcShape
               +----CcPixbuf
               +----CcSimpleItem

Implemented Interfaces

CcItem implements CcItemView.

Signals


  "all-bounds-changed"                             
  "button-press-event"                             : Run Last
  "button-release-event"                           : Run Last
  "dirty"                                          
  "enter-notify-event"                             : Run Last
  "event"                                          : Run Last
  "focus"                                          : Run Last
  "focus-enter"                                    : Run Last
  "focus-leave"                                    : Run Last
  "item-added"                                     : Run Last
  "item-removed"                                   : Run Last
  "key-press-event"                                : Run Last
  "key-release-event"                              : Run Last
  "leave-notify-event"                             : Run Last
  "motion-notify-event"                            : Run Last
  "view-register"                                  : Run First
  "view-unregister"                                : Run Last

Description

Details

CcItem

typedef struct _CcItem CcItem;


CcItemClass

typedef struct {
	GInitiallyUnownedClass base_class;

	/* vtable */
	gdouble (*distance)             (CcItem         * self,
					 CcView const   * view,
				         gdouble          x,
				         gdouble          y,
				         CcItem         **found);
	void    (*notify_child_bounds)  (CcItem         * self,
				         CcItem         * child,
					 CcView         * view,
				         CcDRect const  * all_bounds);
	void    (*render)               (CcItem         * self,
		                         CcView         * view,
			                 cairo_t        * cr);
	void    (*update_bounds)        (CcItem         * self,
					 CcView const   * view,
					 gpointer         user_data);

	/* signals */
	gboolean (*button_press_event)  (CcItem          * self,
					 CcView          * view,
					 GdkEventButton  * event);
	gboolean (*button_release_event)(CcItem          * self,
					 CcView          * view,
					 GdkEventButton  * event);
	gboolean (*enter_notify_event)  (CcItem          * self,
					 CcView          * view,
					 GdkEventCrossing* event);
	gboolean (*event)               (CcItem          * self,
					 CcView          * view,
					 GdkEvent        * event);
	gboolean (*focus)		(CcItem          * self,
					 CcView	         * view,
					 GtkDirectionType  dir);
	gboolean (*focus_enter)         (CcItem          * self,
					 CcView          * view,
					 GdkEventFocus   * event);
	gboolean (*focus_leave)         (CcItem          * self,
					 CcView          * view,
					 GdkEventFocus   * focus);
	gboolean (*key_press_event)     (CcItem          * item,
					 CcView          * view,
					 GdkEventKey     * event);
	gboolean (*key_release_event)   (CcItem          * item,
					 CcView          * view,
					 GdkEventKey     * event);
	gboolean (*leave_notify_event)  (CcItem          * self,
					 CcView          * view,
					 GdkEventCrossing* event);
	gboolean (*motion_notify_event) (CcItem          * self,
					 CcView          * view,
					 GdkEventMotion  * event);

	void     (*item_added)          (CcItem          * self,
					 gint              position,
					 CcItem          * child);
	void     (*item_removed)        (CcItem          * self,
					 gint              position,
					 CcItem          * child);

	void     (*view_register)       (CcItem          * self,
					 CcView          * view);
	void     (*view_unregister)     (CcItem          * self,
					 CcView          * view);
} CcItemClass;


cc_item_class_add_view_data ()

void                cc_item_class_add_view_data         (gpointer item_class,
                                                         gsize view_data_size);

Registers the size of view data for a certain item class. See also the section called “View-Specific Data”.

item_class : a CcItemClass
view_data_size : the size to be allocated for the view data

cc_item_get_view_data ()

gpointer            cc_item_get_view_data               (CcItem const*self,
                                                         CcView const*view,
                                                         GType type);

Get a pointer to the view data for view in self. See also the section called “View-Specific Data”.

self : a CcItem
view : a CcView
type : the GType of self which should be searched for the view
Returns : a pointer to the requested memory.

cc_item_new ()

CcItem*             cc_item_new                         (void);

Create a new CcItem that can be used to group several items together.

Returns : a new CcItem.

cc_item_append ()

void                cc_item_append                      (CcItem *self,
                                                         CcItem *child);

Insert an item at the end of this item. A CcItem can serve as a container for several items.

self : a CcItem
child : another CcItem

cc_item_dirty ()

void                cc_item_dirty                       (CcItem *self,
                                                         CcView const*view,
                                                         CcDRect dirty_region);

Let emit a signal to tell view that it needs to be redrawn.

self : a CcItem
view : a CcView
dirty_region : the region that needs to be redrawn

cc_item_distance ()

gdouble             cc_item_distance                    (CcItem *self,
                                                         CcView const*view,
                                                         gdouble x,
                                                         gdouble y,
                                                         CcItem **found);

Calculates the distance from self to (x,y). If (x,y) is within self or one of its children found is set to the matching element.

self : a CcItem
view : a CcView
x : the x coordinate to query for
y : the y coordinate to query for
found : the return location for a found CcItem
Returns : the distance between self (or one of its children) to (x,y).

cc_item_insert ()

void                cc_item_insert                      (CcItem *self,
                                                         CcItem *child,
                                                         gint position);

Inserts child at position into self.

self : a CcItem
child : another CcItem
position : the position to insert the child at (0 means at the bottom, bigger numbers mean higher layers, -1 means top layer)

cc_item_remove ()

void                cc_item_remove                      (CcItem *self,
                                                         CcItem *child);

Removes child from self. Does nothing if child was not a child of self or if child is a child of one of self's children.

self : a CcItem
child : another CcItem

cc_item_render ()

void                cc_item_render                      (CcItem *self,
                                                         CcView *view,
                                                         cairo_t *cr);

Renders self to cr which is supposed to be a cairo context of view as the transformation matrix of view will be used for rendering.

self : a CcItem
view : a Ccview
cr : a cairo context (cairo_t)

cc_item_set_grid_aligned ()

void                cc_item_set_grid_aligned            (CcItem *self,
                                                         gboolean grid_aligned);

Sets self to be rendered grid-aligned if grid_aligned is TRUE, sets it to be allowed to render fuzzyly if FALSE.

self : a CcItem
grid_aligned : a gboolean

cc_item_lower ()

void                cc_item_lower                       (CcItem *child,
                                                         CcItem *parent);

Lowers child by one level.

child : a CcItem
parent : another CcItem, parent of child

cc_item_lower_to_bottom ()

void                cc_item_lower_to_bottom             (CcItem *child,
                                                         CcItem *parent);

Lowers child to be displayed behind all the other children of parent.

child : a CcItem
parent : another CcItem, parent of child

cc_item_raise ()

void                cc_item_raise                       (CcItem *child,
                                                         CcItem *parent);

Raises child by one level.

child : a CcItem
parent : another CcItem, parent of child

cc_item_raise_to_top ()

void                cc_item_raise_to_top                (CcItem *child,
                                                         CcItem *parent);

Raises an child to the top. It will be displayed over all of the other children of parent.

child : a CcItem
parent : another CcItem, parent of child

cc_item_set_position ()

void                cc_item_set_position                (CcItem *child,
                                                         CcItem *parent,
                                                         gint position);

Changes the position of child relative to parent.

child : a CcItem
parent : another CcItem, parent of child
position : the new position of the CcItem (0 means at the bottom, bigger numbers mean higher layers, -1 means top layer)

enum CcItemFlags

typedef enum {
	CC_CAN_FOCUS          = 1 << 1,
	CC_DISPOSED           = 1 << 2,
	CC_GRID_ALIGNED       = 1 << 3,
} CcItemFlags;

CC_CAN_FOCUS
CC_DISPOSED specifies whether dispose has already been run on an item.
CC_GRID_ALIGNED specifies whether an item should be rendered to match an existing grid.

CC_ITEM_FLAGS()

#define CC_ITEM_FLAGS(i)         (CC_ITEM(i)->flags)

Get the flags which are set on the CcItem i.

i : a CcItem

CC_ITEM_DISPOSED()

#define CC_ITEM_DISPOSED(i)           ((CC_ITEM_FLAGS(i) & CC_DISPOSED) != 0)

Queries the CcItem i whether it has the CC_DISPOSED flag set. This is very useful in the dispose handler for the GObject derived types. This flag gets set automatically if you chain up your dispose calls correctly.

i : a CcItem

CC_ITEM_GRID_ALIGNED()

#define CC_ITEM_GRID_ALIGNED(i)       ((CC_ITEM_FLAGS(i) & CC_GRID_ALIGNED) != 0)

Queries the CcItem i whether it has the CC_GRID_ALIGNED flag set.

i : a CcItem

CC_ITEM_SET_FLAGS()

#define CC_ITEM_SET_FLAGS(i,m)   G_STMT_START{ (CC_ITEM_FLAGS(i) |=  (m)); }G_STMT_END

Sets on i the CcItemFlags that have been specified in m.

i : a CcItem
m : a CcItemFlags mask

CC_ITEM_UNSET_FLAGS()

#define CC_ITEM_UNSET_FLAGS(i,m) G_STMT_START{ (CC_ITEM_FLAGS(i) &= ~(m)); }G_STMT_END

Unsets from i the CcItemFlags that have been specified in m.

i : a CcItem
m : a CcItemFlags mask

CC_ITEM_CAN_FOCUS()

#define CC_ITEM_CAN_FOCUS(i)          ((CC_ITEM_FLAGS(i) & CC_CAN_FOCUS) != 0)

i :

CcItemFunc ()

void                (*CcItemFunc)                       (CcItem *item,
                                                         CcView *view,
                                                         gpointer data);

item :
view :
data :

cc_item_add_view ()

void                cc_item_add_view                    (CcItem *self,
                                                         CcView *view);

Registers a view at the item. The item and its children can now set up data for this view.

This function should not be called by application code. Use cc_item_view_register() instead.

self : a CcItem
view : a CcView

cc_item_bounds_changed ()

void                cc_item_bounds_changed              (CcItem *self,
                                                         CcView const*view);

self :
view :

cc_item_flags_get_type ()

GType               cc_item_flags_get_type              (void);

Returns :

cc_item_foreach_view ()

void                cc_item_foreach_view                (CcItem *self,
                                                         CcItemFunc func,
                                                         gpointer data);

self :
func :
data :

cc_item_get_all_bounds ()

CcDRectconst*       cc_item_get_all_bounds              (CcItem const*self,
                                                         CcView const*view);

Get the bounds of self as it would e displayed by view (including all of its children).

self : a CcItem
view : a CcView
Returns : the bounds of the item, may be NULL (in this case the item is not tied visible area).

cc_item_grab_focus ()

void                cc_item_grab_focus                  (CcItem *self,
                                                         CcView *view);

self :
view :

cc_item_is_child_of ()

gboolean            cc_item_is_child_of                 (CcItem const*child,
                                                         CcItem const*parent);

Find out whether child is a child of parent.

child : a CcItem
parent : another CcItem
Returns : TRUE is child is a child of parent.

cc_item_remove_view ()

void                cc_item_remove_view                 (CcItem *self,
                                                         CcView *view);

Unregisters a view at the item. The item and the children can now free data kept for this view.

This function should not be called by application code. Use cc_item_view_unregister() instead.

self : a CcItem
view : a CcView

cc_item_update_bounds ()

void                cc_item_update_bounds               (CcItem *self,
                                                         gpointer data);

self :
data :

cc_item_update_bounds_for_view ()

void                cc_item_update_bounds_for_view      (CcItem *self,
                                                         CcView *view);

self :
view :

Signal Details

The "all-bounds-changed" signal

void                user_function                      (CcItem  *self,
                                                        CcView  *view,
                                                        CcDRect *box,
                                                        gpointer user_data)

This signal gets emitted when the total bounding box of an item changed. See also Bounds Handling.

self : a Ccitem
view : the CcView belonging to this event
box : a CcDRect specifying the new bounding box
user_data : user data set when the signal handler was connected.

The "button-press-event" signal

gboolean            user_function                      (CcItem         *self,
                                                        CcView         *view,
                                                        GdkEventButton *event,
                                                        gpointer        user_data)      : Run Last

This signal gets emitted when a mouse button got pressed on top of an element.

self : a CcItem
view : the CcView which emitted this event
event : a GdkEventButton with coordinates translated to canvas coordinates.
user_data : user data set when the signal handler was connected.
Returns : TRUE to stop other signal handlers from being called.

The "button-release-event" signal

gboolean            user_function                      (CcItem         *self,
                                                        CcView         *view,
                                                        GdkEventButton *event,
                                                        gpointer        user_data)      : Run Last

This signal gets emitted when a mouse button got released on top of an item.

self : a CcItem
view : the CcView which emitted this event
event : a GdkEventButton with coordinates translated to canvas coordinates
user_data : user data set when the signal handler was connected.
Returns : TRUE to stop other signal handlers from being called.

The "dirty" signal

void                user_function                      (CcItem  *self,
                                                        CcView  *dirty_region,
                                                        CcDRect *arg2,
                                                        gpointer user_data)

This signal gets emitted when an item changes. It's used to request redraws of the affected items.

self : a CcItem
dirty_region : a CcDRect that specifies the dirty region
user_data : user data set when the signal handler was connected.

The "enter-notify-event" signal

gboolean            user_function                      (CcItem           *self,
                                                        CcView           *view,
                                                        GdkEventCrossing *event,
                                                        gpointer          user_data)      : Run Last

This signal gets emitted when the mouse pointer enters an item.

self : a CcItem
view : the CcView which emitted this event
event : a GdkEventCrossing with x and y coordinates translated into canvas coordinates
user_data : user data set when the signal handler was connected.
Returns : TRUE to stop other signal handlers from being invoked.

The "event" signal

gboolean            user_function                      (CcItem   *self,
                                                        CcView   *view,
                                                        GdkEvent *event,
                                                        gpointer  user_data)      : Run Last

This signal catches all events before they are distributes into more specified signals.

self : a CcItem
view : the CcView which emitted this event
event : the event that got emitted (with canvas coordinates)
user_data : user data set when the signal handler was connected.
Returns : TRUE to stop other signal handlers from being called.

The "focus" signal

gboolean            user_function                      (CcItem          *self,
                                                        CcView          *view,
                                                        GtkDirectionType dir,
                                                        gpointer         user_data)      : Run Last

This signal gets emitted when a focus event on the view happended to let focus-handling happen.

self : a CcItem
view : a CcView
dir : the focus direction
user_data : user data set when the signal handler was connected.
Returns : TRUE to stop other signal handlers from being called (such as the one which lets the focus leave the canvas view)

The "focus-enter" signal

gboolean            user_function                      (CcItem   *self,
                                                        CcView   *view,
                                                        GdkEvent *event,
                                                        gpointer  user_data)      : Run Last

This signal gets emitted when the focus enters this item.

self : a CcItem
view : a CcView
event : a GdkEventFocus
user_data : user data set when the signal handler was connected.
Returns : TRUE to stop other signal handlers, FALSE to allow their execution.

The "focus-leave" signal

gboolean            user_function                      (CcItem   *self,
                                                        CcView   *view,
                                                        GdkEvent *event,
                                                        gpointer  user_data)      : Run Last

This signal gets emitted when the focus leaves this item.

self : a CcItem
view : a CcView
event : a GdkEventFocus
user_data : user data set when the signal handler was connected.
Returns : TRUE to stop other signal handlers, FALSE to allow their execution.

The "item-added" signal

void                user_function                      (CcItem  *self,
                                                        gint     position,
                                                        CcItem  *child,
                                                        gpointer user_data)      : Run Last

This signal gets emitted when an element is added to another element.

self : a CcItem
position : the new index of the child
child : the child
user_data : user data set when the signal handler was connected.

The "item-removed" signal

void                user_function                      (CcItem  *self,
                                                        gint     position,
                                                        CcItem  *child,
                                                        gpointer user_data)      : Run Last

This signal gets emitted when an element is removed from another element.

self : a CcItem
position : the former index of the child
child : the child
user_data : user data set when the signal handler was connected.

The "key-press-event" signal

gboolean            user_function                      (CcItem      *self,
                                                        CcView      *view,
                                                        GdkEventKey *event,
                                                        gpointer     user_data)      : Run Last

This signal gets emitted when a key gets pressed.

self : a CcItem
view : a CcView
event : a GdkEventKey
user_data : user data set when the signal handler was connected.
Returns : TRUE to stop other signal handlers, FALSE to allow their execution.

The "key-release-event" signal

gboolean            user_function                      (CcItem      *self,
                                                        CcView      *view,
                                                        GdkEventKey *event,
                                                        gpointer     user_data)      : Run Last

This signal gets emitted when a key gets released.

self : a CcItem
view : a CcView
event : a GdkEventKey
user_data : user data set when the signal handler was connected.
Returns : TRUE to stop other signal handlers, FALSE to allow their execution.

The "leave-notify-event" signal

gboolean            user_function                      (CcItem           *self,
                                                        CcView           *view,
                                                        GdkEventCrossing *event,
                                                        gpointer          user_data)      : Run Last

This signal gets emitted when the mouse pointer leaves an element.

self : a CcItem
view : the CcView which emitted this event
event : a GdkEventCrossing
user_data : user data set when the signal handler was connected.
Returns : TRUE to stop other signal handlers from being invoked.

The "motion-notify-event" signal

gboolean            user_function                      (CcItem         *self,
                                                        CcView         *view,
                                                        GdkEventMotion *event,
                                                        gpointer        user_data)      : Run Last

This signal gets emitted when the pointer (mouse cursor) moves while being over this item.

self : a CcItem
view : the CcView which emitted this event
event : the event that got emitted (with canvas coordinates)
user_data : user data set when the signal handler was connected.
Returns : TRUE to stop other signal handlers from being called.

The "view-register" signal

void                user_function                      (CcItem  *self,
                                                        CcView  *view,
                                                        gpointer user_data)      : Run First

Registeres the view for this item. This signal can be used to create view-specific data for the CcItem. Take a look at CcText to see how this can be used.

self : a CcItem
view : a CcView
user_data : user data set when the signal handler was connected.

The "view-unregister" signal

void                user_function                      (CcItem  *self,
                                                        CcView  *view,
                                                        gpointer user_data)      : Run Last

Registeres the view for this item. This signal can be used to create view-specific data for the CcItem. Take a look at CcText to see how this can be used.

self : a CcItem
view : a CcView
user_data : user data set when the signal handler was connected.