/usr/share/gtk-doc/html/goocanvas/goocanvas-creating-items.html is in libgoocanvas-dev 0.15-1.1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Creating New Items</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2">
<link rel="start" href="index.html" title="GooCanvas Reference Manual">
<link rel="up" href="ch01.html" title="Introduction">
<link rel="prev" href="goocanvas-coordinates.html" title="Coordinate Spaces and Limits">
<link rel="next" href="goocanvas-wysiwyg.html" title="WYSIWYG Printing">
<meta name="generator" content="GTK-Doc V1.9 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
<link rel="chapter" href="ch01.html" title="Introduction">
<link rel="chapter" href="ch02.html" title="Core Objects">
<link rel="chapter" href="ch03.html" title="Standard Canvas Items">
<link rel="chapter" href="ch04.html" title="Standard Canvas Item Models">
<link rel="chapter" href="ch05.html" title="Miscellaneous">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
<td><a accesskey="p" href="goocanvas-coordinates.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="ch01.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">GooCanvas Reference Manual</th>
<td><a accesskey="n" href="goocanvas-wysiwyg.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr></table>
<div class="refentry" lang="en">
<a name="goocanvas-creating-items"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2><span class="refentrytitle">Creating New Items</span></h2>
<p>Creating New Items — how to create new canvas items.</p>
</td>
<td valign="top" align="right"></td>
</tr></table></div>
<div class="refsect1" lang="en">
<a name="id3050146"></a><h2>How to Create New Canvas Items</h2>
<p>
There are 3 ways to create new canvas items, listed here in increasing
order of complexity:
</p>
<div class="itemizedlist"><ul type="disc">
<li><p>
<a class="link" href="goocanvas-creating-items.html#creating-simple-subclass" title="Creating a Simple Subclass of GooCanvasItemSimple">
Creating a simple subclass of GooCanvasItemSimple.</a>
</p></li>
<li><p>
<a class="link" href="goocanvas-creating-items.html#creating-regular-subclass" title="Creating a Regular Subclass of GooCanvasItemSimple">
Creating a regular subclass of GooCanvasItemSimple.</a>
</p></li>
<li><p>
<a class="link" href="goocanvas-creating-items.html#implementing-interface" title="Implementing the GooCanvasItem Interface">
Implementing the GooCanvasItem interface.</a>
</p></li>
</ul></div>
<p>
These will be discussed in turn below. (It is also possible to create
new container items by subclassing <a class="link" href="GooCanvasGroup.html" title="GooCanvasGroup"><span class="type">GooCanvasGroup</span></a>, but that is not
covered here.)
</p>
<p>
The final part of this section covers
creating item models.
</p>
<div class="refsect2" lang="en">
<a name="creating-simple-subclass"></a><h3>Creating a Simple Subclass of GooCanvasItemSimple</h3>
<p>
For items that consist of a simple graphic element such
as a line, rectangle or circle, it is possible to create a subclass
of <a class="link" href="GooCanvasItemSimple.html" title="GooCanvasItemSimple"><span class="type">GooCanvasItemSimple</span></a> and override just one method,
<code class="function">simple_create_path()</code>. (This method is used for the <a class="link" href="GooCanvasEllipse.html" title="GooCanvasEllipse"><span class="type">GooCanvasEllipse</span></a>
and <a class="link" href="GooCanvasPath.html" title="GooCanvasPath"><span class="type">GooCanvasPath</span></a> items.)
</p>
<p>
The <code class="function">simple_create_path()</code> method should create a path using the given
cairo context. The path will be drawn using the stroke, fill and
other painting properties from <a class="link" href="GooCanvasItemSimple.html" title="GooCanvasItemSimple"><span class="type">GooCanvasItemSimple</span></a>.
</p>
<p>
This example shows the <code class="function">simple_create_path()</code> method for a simple
rectangular item, MyItem:
</p>
<div class="informalexample"><pre class="programlisting">
static void
my_item_simple_create_path (GooCanvasItemSimple *simple,
cairo_t *cr)
{
MyItem *item = (MyItem*) simple;
cairo_rectangle (cr, item->x, item->y, item->width, item->height);
}
</pre></div>
<p>
</p>
<p>
Whenever the item is changed in some way it should call
<a class="link" href="GooCanvasItemSimple.html#goo-canvas-item-simple-changed"><code class="function">goo_canvas_item_simple_changed()</code></a>, passing a boolean value indicating
whether the item's bounds need to be recalculated or if it only needs
to be repainted. The <a class="link" href="GooCanvasItemSimple.html" title="GooCanvasItemSimple"><span class="type">GooCanvasItemSimple</span></a> code will take care of
updating the item and repainting the appropriate parts of the canvas.
</p>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="creating-regular-subclass"></a><h3>Creating a Regular Subclass of GooCanvasItemSimple</h3>
<p>
Most items will need more than a simple line or rectangle, so they
will need to create a subclass of <a class="link" href="GooCanvasItemSimple.html" title="GooCanvasItemSimple"><span class="type">GooCanvasItemSimple</span></a> and override
three methods, <code class="function">simple_update()</code>, <code class="function">simple_paint()</code> and <code class="function">simple_is_item_at()</code>.
</p>
<p>
The <code class="function">simple_update()</code> method should compute the bounds of the item, in the
item's coordinate space, and place them in the bounds member of
<a class="link" href="GooCanvasItemSimple.html#GooCanvasItemSimple-struct"><span class="type">GooCanvasItemSimple</span></a>. Note that the cairo context passed to
this function may have transformations applied to it, so
<a
href="/usr/share/gtk-doc/html/cairo/cairo-Transformations.html#cairo-identity-matrix"
><code class="function">cairo_identity_matrix()</code></a> should be called before using it.
</p>
<p>
The <code class="function">simple_paint()</code> method should paint the item using the given cairo
context. To use the stroke and fill properties from <a class="link" href="GooCanvasItemSimple.html" title="GooCanvasItemSimple"><span class="type">GooCanvasItemSimple</span></a>
to paint parts of the item call <a class="link" href="GooCanvasStyle.html#goo-canvas-style-set-stroke-options"><code class="function">goo_canvas_style_set_stroke_options()</code></a>
and <a class="link" href="GooCanvasStyle.html#goo-canvas-style-set-fill-options"><code class="function">goo_canvas_style_set_fill_options()</code></a> before calling <a
href="/usr/share/gtk-doc/html/cairo/cairo-cairo-t.html#cairo-stroke"
><code class="function">cairo_stroke()</code></a>
and <a
href="/usr/share/gtk-doc/html/cairo/cairo-cairo-t.html#cairo-fill"
><code class="function">cairo_fill()</code></a>. (The item's style can be found in
GOO_CANVAS_ITEM_SIMPLE (item)->simple_data->style).
</p>
<p>
The <code class="function">simple_is_item_at()</code> method should return <a
href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#TRUE:CAPS"
><code class="literal">TRUE</code></a> if the
given coordinate (in the item's coordinate space) is inside the item.
(The is_pointer_event argument can be ignored for most purposes since
the <a class="link" href="GooCanvasItemSimple.html" title="GooCanvasItemSimple"><span class="type">GooCanvasItemSimple</span></a> code will take care of it.)
</p>
<p>
This example code shows the <code class="function">simple_update()</code>, <code class="function">simple_paint()</code> and
<code class="function">simple_is_item_at()</code> methods for a rectangular item (the complete
item's source code can be found in the GooCanvas demo directory, in
demo-item.h and demo-item.c):
</p>
<div class="informalexample"><pre class="programlisting">
static void
goo_demo_item_update (GooCanvasItemSimple *simple,
cairo_t *cr)
{
GooDemoItem *demo_item = (GooDemoItem*) simple;
/* Compute the new bounds. */
simple->bounds.x1 = demo_item->x;
simple->bounds.y1 = demo_item->y;
simple->bounds.x2 = demo_item->x + demo_item->width;
simple->bounds.y2 = demo_item->y + demo_item->height;
}
static void
goo_demo_item_paint (GooCanvasItemSimple *simple,
cairo_t *cr,
const GooCanvasBounds *bounds)
{
GooDemoItem *demo_item = (GooDemoItem*) simple;
cairo_move_to (cr, demo_item->x, demo_item->y);
cairo_line_to (cr, demo_item->x, demo_item->y + demo_item->height);
cairo_line_to (cr, demo_item->x + demo_item->width,
demo_item->y + demo_item->height);
cairo_line_to (cr, demo_item->x + demo_item->width, demo_item->y);
cairo_close_path (cr);
goo_canvas_style_set_fill_options (simple->simple_data->style, cr);
cairo_fill (cr);
}
static gboolean
goo_demo_item_is_item_at (GooCanvasItemSimple *simple,
gdouble x,
gdouble y,
cairo_t *cr,
gboolean is_pointer_event)
{
GooDemoItem *demo_item = (GooDemoItem*) simple;
if (x < demo_item->x || (x > demo_item->x + demo_item->width)
|| y < demo_item->y || (y > demo_item->y + demo_item->height))
return FALSE;
return TRUE;
}
</pre></div>
<p>
</p>
<p>
As with the simple <a class="link" href="GooCanvasItemSimple.html" title="GooCanvasItemSimple"><span class="type">GooCanvasItemSimple</span></a> subclass, the item should
call <a class="link" href="GooCanvasItemSimple.html#goo-canvas-item-simple-changed"><code class="function">goo_canvas_item_simple_changed()</code></a> whenever it is changed, to
ensure that the item's bounds are recomputed and it is repainted
if necessary.
</p>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="implementing-interface"></a><h3>Implementing the GooCanvasItem Interface</h3>
<p>
The most complicated way to create new canvas items is to implement
the <a class="link" href="goocanvas-goocanvasitem.html#GooCanvasItem"><span class="type">GooCanvasItem</span></a> interface directly. This should not be needed in
most cases, but may be desired if the developer wants to avoid the
memory and processor overheads associated with the <a class="link" href="GooCanvasItemSimple.html" title="GooCanvasItemSimple"><span class="type">GooCanvasItemSimple</span></a>
class, or if the developer wants to turn an existing application object
into a canvas item.
</p>
<p>
At a minimum the canvas item must implement these 6 methods:
</p>
<div class="itemizedlist"><ul type="disc">
<li><p>
<code class="function">get_parent()</code> - the item's parent should be returned.
</p></li>
<li><p>
<code class="function">set_parent()</code> - the item's parent should be stored (though it
should not add a reference to the parent).
</p></li>
<li><p>
<code class="function">get_bounds()</code> - returns the bounds of the item, in canvas space.
The item should ensure that the bounds are up-to-date before
returning them, calling <a class="link" href="goocanvas-goocanvasitem.html#goo-canvas-item-ensure-updated"><code class="function">goo_canvas_item_ensure_updated()</code></a> if
necessary.
</p></li>
<li><p>
<code class="function">update()</code> - if the item has been changed since the last update,
or if the entire_tree flag is <a
href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#TRUE:CAPS"
><code class="literal">TRUE</code></a>, the item's bounds should
be recomputed (in canvas space). It should also request a redraw
of the old bounds and the new bounds, so the display is updated
appropriately. The new bounds should be returned in the bounds
argument.
</p></li>
<li><p>
<code class="function">paint()</code> - if the item's bounds intersect the given bounds then
the item should be painted on the given cairo context.
The scale parameter is only used to check if the item should be
visible, according to the item's <a class="link" href="goocanvas-goocanvasitem.html#GooCanvasItem--visibility"><span class="type">"visibility"</span></a> and
<a class="link" href="goocanvas-goocanvasitem.html#GooCanvasItem--visibility-threshold"><span class="type">"visibility-threshold"</span></a> property settings.
</p></li>
<li><p>
<code class="function">get_items_at()</code> - if the given point is inside the item then
a pointer to the item should be added to the start of the list
of found items. The list is then returned.
</p></li>
</ul></div>
<p>
</p>
<p>
The canvas item must also implement the
<a class="link" href="goocanvas-goocanvasitem.html#GooCanvasItem--parent"><span class="type">"parent"</span></a>, <a class="link" href="goocanvas-goocanvasitem.html#GooCanvasItem--title"><span class="type">"title"</span></a>,
<a class="link" href="goocanvas-goocanvasitem.html#GooCanvasItem--description"><span class="type">"description"</span></a>,
<a class="link" href="goocanvas-goocanvasitem.html#GooCanvasItem--visibility"><span class="type">"visibility"</span></a>, <a class="link" href="goocanvas-goocanvasitem.html#GooCanvasItem--visibility-threshold"><span class="type">"visibility-threshold"</span></a>,
<a class="link" href="goocanvas-goocanvasitem.html#GooCanvasItem--transform"><span class="type">"transform"</span></a> and <a class="link" href="goocanvas-goocanvasitem.html#GooCanvasItem--pointer-events"><span class="type">"pointer-events"</span></a> properties.
(The last 4 properties can simply be ignored if the application
doesn't intend to use them.)
</p>
<p>
If the canvas item will be used within a container that does item
layout, such as <a class="link" href="GooCanvasTable.html" title="GooCanvasTable"><span class="type">GooCanvasTable</span></a>, it must implement the first two
methods here at least:
</p>
<div class="itemizedlist"><ul type="disc">
<li><p>
<code class="function">get_requested_area()</code> - returns the requested area of the item,
in the parent's coordinate space.
</p></li>
<li><p>
<code class="function">allocate_area()</code> - allocates the item's area, in the parent's
coordinate space.
</p></li>
<li><p>
<code class="function">get_requested_height()</code> - returns the requested height of the
item, given a particular allocated width, in the parent's
coordinate space. (This only needed for items that change height
as their width is changed, such as text items.)
</p></li>
</ul></div>
<p>
</p>
<p>
If the canvas item supports a transformation matrix it must implement:
</p>
<div class="itemizedlist"><ul type="disc">
<li><p>
<code class="function">get_transform()</code> - returns the item's transformation matrix.
</p></li>
<li><p>
<code class="function">set_transform()</code> - sets the item's transformation matrix.
</p></li>
</ul></div>
<p>
</p>
<p>
If the canvas item supports a <a class="link" href="GooCanvasStyle.html" title="GooCanvasStyle"><span class="type">GooCanvasStyle</span></a> setting, it must
implement:
</p>
<div class="itemizedlist"><ul type="disc">
<li><p>
<code class="function">get_style()</code> - returns the item's style.
</p></li>
<li><p>
<code class="function">set_style()</code> - sets the item's style.
</p></li>
</ul></div>
<p>
</p>
<p>
Since <a class="link" href="GooCanvasItemSimple.html" title="GooCanvasItemSimple"><span class="type">GooCanvasItemSimple</span></a> implements most of the above methods and
properties its source code is a good place to look for help.
</p>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="creating-item-models"></a><h3>Creating Item Models</h3>
<p>
As with creating canvas items, to create item models it
is possible to subclass <a class="link" href="GooCanvasItemModelSimple.html" title="GooCanvasItemModelSimple"><span class="type">GooCanvasItemModelSimple</span></a> or to
implement the <a class="link" href="goocanvas-goocanvasitemmodel.html#GooCanvasItemModel"><span class="type">GooCanvasItemModel</span></a> interface directly.
</p>
<p>
Subclassing <a class="link" href="GooCanvasItemModelSimple.html" title="GooCanvasItemModelSimple"><span class="type">GooCanvasItemModelSimple</span></a> is very easy, since only one
method from the <a class="link" href="goocanvas-goocanvasitemmodel.html#GooCanvasItemModel"><span class="type">GooCanvasItemModel</span></a> interface must be implemented -
<code class="function">create_item()</code>. This should return a new canvas item for viewing the
item model in a canvas. (It may be called multiple times if multiple
canvases are viewing the same canvas model.)
</p>
<p>
The <a class="link" href="GooCanvasItemModelSimple.html" title="GooCanvasItemModelSimple"><span class="type">GooCanvasItemModelSimple</span></a> subclass should emit the "changed"
signal whenever it has changed, with a boolean flag indicating if
the bounds need to be recomputed. The canvas items will connect to
this signal and request an update or a redraw as appropriate.
</p>
<p>
To implement the <a class="link" href="goocanvas-goocanvasitemmodel.html#GooCanvasItemModel"><span class="type">GooCanvasItemModel</span></a> interface directly, the class
must implement the <code class="function">get_parent()</code>, <code class="function">set_parent()</code> and <code class="function">create_item()</code>
methods. It may also implement <code class="function">get_transform()</code>, <code class="function">set_transform()</code>,
<code class="function">get_style()</code> and <code class="function">set_style()</code> methods if desired.
</p>
<p>
The class must also implement the
<a class="link" href="goocanvas-goocanvasitemmodel.html#GooCanvasItemModel--parent"><span class="type">"parent"</span></a>, <a class="link" href="goocanvas-goocanvasitemmodel.html#GooCanvasItemModel--title"><span class="type">"title"</span></a>,
<a class="link" href="goocanvas-goocanvasitemmodel.html#GooCanvasItemModel--description"><span class="type">"description"</span></a>, <a class="link" href="goocanvas-goocanvasitemmodel.html#GooCanvasItemModel--can-focus"><span class="type">"can-focus"</span></a>,
<a class="link" href="goocanvas-goocanvasitemmodel.html#GooCanvasItemModel--visibility"><span class="type">"visibility"</span></a>,
<a class="link" href="goocanvas-goocanvasitemmodel.html#GooCanvasItemModel--visibility-threshold"><span class="type">"visibility-threshold"</span></a>,
<a class="link" href="goocanvas-goocanvasitemmodel.html#GooCanvasItemModel--transform"><span class="type">"transform"</span></a> and <a class="link" href="goocanvas-goocanvasitemmodel.html#GooCanvasItemModel--pointer-events"><span class="type">"pointer-events"</span></a>
properties.
(The last 4 properties can simply be ignored if the application
doesn't intend to use them.)
</p>
</div>
</div>
</div>
</body>
</html>
|