The Base Item

The Base Item —

Synopsis




            CcItem;
            CcItemClass;
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,
                                             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);
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)

Object Hierarchy


  GObject
   +----GInitiallyUnowned
         +----CcItem
               +----CcShape

Implemented Interfaces

CcItem implements

Signals


"all-bounds-changed"
            void        user_function      (CcItem  *ccitem,
                                            CcView  *arg1,
                                            CcDRect *arg2,
                                            gpointer user_data)      : 
"button-press-event"
            gboolean    user_function      (CcItem         *self,
                                            CcView         *view,
                                            GdkEventButton *event,
                                            gpointer        user_data)      : Run last
"button-release-event"
            gboolean    user_function      (CcItem         *self,
                                            CcView         *view,
                                            GdkEventButton *event,
                                            gpointer        user_data)      : Run last
"dirty"     void        user_function      (CcItem  *self,
                                            CcView  *dirty_region,
                                            CcDRect *arg2,
                                            gpointer user_data)         : 
"enter-notify-event"
            gboolean    user_function      (CcItem           *self,
                                            CcView           *view,
                                            GdkEventCrossing *event,
                                            gpointer          user_data)      : Run last
"event"     gboolean    user_function      (CcItem   *self,
                                            CcView   *view,
                                            GdkEvent *event,
                                            gpointer  user_data)      : Run last
"focus"     gboolean    user_function      (CcItem           *self,
                                            CcView           *view,
                                            GtkDirectionType *dir,
                                            gpointer          user_data)      : Run last
"focus-enter"
            gboolean    user_function      (CcItem   *ccitem,
                                            CcView   *arg1,
                                            GdkEvent *event,
                                            gpointer  user_data)      : Run last
"focus-leave"
            gboolean    user_function      (CcItem   *ccitem,
                                            CcView   *arg1,
                                            GdkEvent *event,
                                            gpointer  user_data)      : Run last
"item-added"
            void        user_function      (CcItem  *self,
                                            gint     position,
                                            CcItem  *child,
                                            gpointer user_data)      : Run last
"item-removed"
            void        user_function      (CcItem  *self,
                                            gint     position,
                                            CcItem  *child,
                                            gpointer user_data)      : Run last
"key-press-event"
            gboolean    user_function      (CcItem      *ccitem,
                                            CcView      *arg1,
                                            GdkEventKey *event,
                                            gpointer     user_data)      : Run last
"key-release-event"
            gboolean    user_function      (CcItem      *ccitem,
                                            CcView      *arg1,
                                            GdkEventKey *event,
                                            gpointer     user_data)      : Run last
"leave-notify-event"
            gboolean    user_function      (CcItem           *self,
                                            CcView           *view,
                                            GdkEventCrossing *event,
                                            gpointer          user_data)      : Run last
"motion-notify-event"
            gboolean    user_function      (CcItem         *self,
                                            CcView         *view,
                                            GdkEventMotion *event,
                                            gpointer        user_data)      : Run last
"view-register"
            void        user_function      (CcItem  *self,
                                            CcView  *view,
                                            gpointer user_data)      : Run first
"view-unregister"
            void        user_function      (CcItem  *self,
                                            CcView  *view,
                                            gpointer user_data)      : Run last

Description

Details

CcItem

typedef struct _CcItem CcItem;


CcItemClass

typedef struct {
	GInitiallyUnownedClass base_class;

	/* vtable */
	gdouble (*distance)             (CcItem         * self,
				         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_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 all the views that it needs to be redrawn.

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

cc_item_distance ()

gdouble     cc_item_distance                (CcItem *self,
                                             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
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

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

Signal Details

The "all-bounds-changed" signal

void        user_function                  (CcItem  *ccitem,
                                            CcView  *arg1,
                                            CcDRect *arg2,
                                            gpointer user_data)      : 

ccitem : the object which received the signal.
arg1 :
arg2 :
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   *ccitem,
                                            CcView   *arg1,
                                            GdkEvent *event,
                                            gpointer  user_data)      : Run last

ccitem : the object which received the signal.
arg1 :
event :
user_data : user data set when the signal handler was connected.
Returns :

The "focus-leave" signal

gboolean    user_function                  (CcItem   *ccitem,
                                            CcView   *arg1,
                                            GdkEvent *event,
                                            gpointer  user_data)      : Run last

ccitem : the object which received the signal.
arg1 :
event :
user_data : user data set when the signal handler was connected.
Returns :

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      *ccitem,
                                            CcView      *arg1,
                                            GdkEventKey *event,
                                            gpointer     user_data)      : Run last

ccitem : the object which received the signal.
arg1 :
event :
user_data : user data set when the signal handler was connected.
Returns :

The "key-release-event" signal

gboolean    user_function                  (CcItem      *ccitem,
                                            CcView      *arg1,
                                            GdkEventKey *event,
                                            gpointer     user_data)      : Run last

ccitem : the object which received the signal.
arg1 :
event :
user_data : user data set when the signal handler was connected.
Returns :

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.