GTK_JUSTIFY_CENTER,  GTK_JUSTIFY_FILL} GtkJustification;        </PRE></TD></TR></TABLE><P>          The font_gdk property sets the GdkFont* value directly; you          would use it if you already had a font allocated. The font          and fontset properties allow you to set the font on the          basis of the contents of a string. The format of this string          is very carefully defined in the X11 specifications, in the          X Logical Font Description (XLFD) document (at          ftp://ftp.x.org/pub/R6.3/xc/doc/hardcopy/ XLFD/). When taken          to its full power, XLFD is quite complex and cumbersome,          but thanks to its support for wildcard characters, you can          manage with simple, generic usage. The GDK API reference          documents (at          http://developer.gnome.org/doc/API/gdk/gdk-fonts.html) also          have a clear, concise description of XLFD. Essentially, the          font property contains a single XLFD, while fontset holds a          list of XLFDs through which X11 will continue to search          until it finds a match.        </P><P>          Here are some examples of what XLFDs look like. You can          probably get by with something very simple, like the first          example:        </P><TABLEBORDER="0"BGCOLOR="#E0E0E0"WIDTH="100%"><TR><TD><PRECLASS="PROGRAMLISTING">-*-clean-medium-r-*-*-12-*-*-*-*-*-*-*-adobe-helvetica-medium-r-normal--12-*-72-72-p-*-iso8859-1-adobe-helvetica-bold-r-normal--12-*-72-72-p-*-iso8859-1-b&#38;h-lucida-bold-r-normal-*-14-*-*-*-p-*-iso8859-1        </PRE></TD></TR></TABLE><P>          The xfontsel application distributed with X11 is an          excellent tool for browsing the fonts installed on your          system, and you can even use it for building XLFD strings of          your own, although you should be careful not to hard-code          any obscure, narrowly defined fonts.        </P><P>          Because text layout has so many constraints, the text item          offers a double handful of properties for controlling how          the Canvas does it. The simplest properties, x_offset and          y_offset, allow you to specify an additional offset in world          coordinates from the anchor point to display the text. You          can use the offsets to fine tune the position of the text          without moving the anchor point.  The offsets are useful if          you have a changing message that needs a little tweaking          from time to time. To automate the calculation of these          offset tweaks, you'll need to find out the actual size of          the rendered text. The read-only properties text_width and          text_height supply this information, through the          gtk_object_getv( ) function. The following code fragment          creates a text item and then prints out the width and height          of the text:        </P><TABLEBORDER="0"BGCOLOR="#E0E0E0"WIDTH="100%"><TR><TD><PRECLASS="PROGRAMLISTING">GtkArg args[2];GnomeCanvasItem *item;item = gnome_canvas_item_new(group, GNOME_TYPE_CANVAS_TEXT,  "x", 20.0, "y", 50.0,  "text", "Print this on the Canvas",  "justification", GTK_JUSTIFY_CENTER,  "anchor", GTK_ANCHOR_CENTER,  "fill_color", "black",  "font", "-*-clean-medium-r-normal-*-12-*-*-*-*-*-*",  NULL);args[0].name = "GnomeCanvasText::text_width";args[1].name = "GnomeCanvasText::text_height";gtk_object_getv(GTK_OBJECT(item), 2, args);g_message("text width = %f, height = %f",    GTK_VALUE_DOUBLE(args[0]), GTK_VALUE_DOUBLE(args[1]));        </PRE></TD></TR></TABLE><P>          Another thing you may need to do if your Canvas is divided          into discrete regions is clip the rendered text to a          rectangular region. You certainly don't want text bleeding          into other areas of your Canvas, especially if you give the          user control over the displayable fonts and font sizes. It's          often better to clip off the text than to let it clutter the          surrounding interface. The clip_width and clip_height          properties set the relative bounding box for your text          item. The clip property switches the clipping on and off.        </P><P>          Although the GnomeCanvasText item provides a decent          interface for adding text to a Canvas, it does have its          weaknesses. The XLFD strings are fairly unwieldy, and the          resolution of the fonts that GnomeCanvasText can load is not          very good, especially when you need to scale them. A          TrueType font server helps the fonts look better, but          because they are X11 fonts they are still rendered from          bitmaps and aren't anti-aliased.        </P><P>          The gnome-print package has an experimental Canvas item for          rendering text, called GnomeCanvasHacktext. This item          converts Adobe Type 1 fonts into an ArtBpath Bezier path          and then renders it onto the Canvas for a smooth,          anti-aliased rendering. You probably shouldn't use          GnomeCanvasHacktext for day-to-day use until you're sure it          has stabilized (at least until it no longer has the word          "hack" in its name). GnomeCanvasHacktext was developed          primarily as a stopgap to allow high-quality rendering for          gnome-print without having to wait for anti-aliased fonts in          X11. You can use it, but at your own risk: The          GnomeCanvasHacktext API has tended to be rather unstable,          and it may change again at any time. It may or may not          eventually be included in the core gnome-libs package.        </P><P>          GTK+ 2.0 will have an entirely different font system, using          the new Pango library (http://www.pango.org). With Pango,          GTK+ 2.0 will support the Unicode specification and          right-to-left languages like Hebrew, as well as the picto-          graphic fonts of China, Japan, and so on. At this time the          Canvas text item will likely be overhauled to bring it up to          speed with the new font system.        </P></DIV><DIVCLASS="SECT2"><H2CLASS="SECT2"><ANAME="AEN1242">Graphical Canvas Items</A></H2><P>          Graphics support for the Canvas has grown and matured          throughout its illustrious life. When the Canvas was first          introduced to gnome-libs, gdk-pixbuf did not exist, so          GnomeCanvasImage, the original Canvas item for displaying          graphics, was written to use the Imlib image-loading          library. The properties for the GnomeCanvasImage item (see          Table 11.7) closely match the properties for          GnomeCanvasWidget (compare Table 11.5).        </P><P>          The main difference is that GnomeCanvasImage uses the image          property rather than the widget property for setting its          contents. You can create a GdkImlibImage structure with a          quick call to gdk_imlib_load_image( ) and destroy it later          with gdk_imlib_destroy_image( ). The following code frag-          ment shows how to create a Canvas item in this way. The          easiest approach is to set up a callback function to destroy          the GdkImlibImage when the Canvas item is destroyed:        </P><TABLEBORDER="0"BGCOLOR="#E0E0E0"WIDTH="100%"><TR><TD><PRECLASS="PROGRAMLISTING">void destroy_imlib_image_cb(GtkObject *object, gpointer data){  gdk_imlib_destroy_image (data);}GnomeCanvasImage* create_image_item(char *imagefile,    GnomeCanvasGroup *group, gdouble x, gdouble y){  GnomeCanvasItem *item;  GdkImlibImage *image;  image = gdk_imlib_load_image(imagefile);  item = gnome_canvas_item_new(group,    gnome_canvas_image_get_type(  ),    "image", image,    "x", x, "y", y,    "width", (double)image-&#62;rgb_width,    "height", (double)image-&#62;rgb_height,    "anchor", GTK_ANCHOR_CENTER,    NULL);  /* Clean up GdkImlibImage when Canvas item is destroyed */  gtk_signal_connect(GTK_OBJECT (item), "destroy",    (GtkSignalFunc) destroy_imlib_image_cb, image);  return item;}        </PRE></TD></TR></TABLE><P>          This code will work in both GDK and AA modes, even though          the Imlib color map will clash with the color map used by          libart in AA mode.  GnomeCanvasImage averts this problem by          converting the image from Imlib format to libart format          behind the scenes when using an AA Canvas. You still set and          retrieve the graphic with the image property, but the actual          rendering is done with ArtPixBuf instead. If you already          have an ArtPixBuf structure, you can set it directly with          the pixbuf property and avoid the conversion process, but be          aware that if you do this, you will not be able to retrieve          the value through either property, image or pixbuf. The          pixbuf property is write-only, and setting it will also set          the image property to NULL.        </P><P>          If you want to use libart instead of Imlib, you should use          the newer GnomeCanvasPixbuf item instead. Furthermore, since          Imlib is being phased out in GNOME 2.0, you should avoid          using it at all if you can use GnomeCanvasPixbuf          instead. The sooner you convert your application from Imlib          to gdk-pixbuf, the better.        </P><P>          GnomeCanvasPixbuf is fully integrated with gdk-pixbuf and          libart; in fact, it is distributed with the gdk-pixbuf          package.2 As a result of this integration and a fresher          approach, its properties (see Table 11.8) are completely          different from those of the other Canvas items we've          discussed.        </P><P>          The pixbuf property allows you to read and write the          GdkPixbuf structure used by the Canvas item. The item takes          care of incrementing the reference count when you set          pixbuf, and it decrements the reference count when the item          is destroyed. Setting pixbuf to a new value will unreference          the previous GdkPixbuf instance. Reading the pixbuf property          does not affect its reference count, so if you want to use          it for something else, you should probably reference it          yourself to make sure it remains.        </P><P>          The remaining 12 properties allow you to override the          default size and position of the image, and enable or          disable affine scaling on the image with very fine          granularity. The four basic properties are width, height, x,          and y.  The values of these properties are ignored if their          _set property is set to FALSE; a value of TRUE in their _set          property overrides the default value with whatever is in          that property. Thus if width is set to 50 on an image that          is normally 100 pixels wide, but width_set is FALSE, the          item will ignore width and display the image at 100          pixels-assuming that no scaling affines are applied to that          item, of course. If width_set is TRUE, the item will instead          ignore the image's true size and force it to display at          width units. The _set properties act independently of each          other, so you can lock the width of an image to a fixed          size, while letting it expand freely in the vertical          direction.        </P><P>          The _in_pixels properties override affine transformations;          any base property with its _in_pixels (and _set) property          set to TRUE will use the property as a fixed value, in          pixels instead of in world coordinates as it usually would.          In the case of width and height, the item won't apply any          scaling transforms on the image; in the case of x and y, the          item won't apply any translation offsets in that          direction. Table 11.9 explores these relationships.        </P><P>          The GnomeCanvasPixbuf item underwent a bit of a personality          crisis in its early days, caused primarily by the transition          from GNOME 1.0 to GNOME 1.2, and on to GNOME 2.0. This item          really belongs in gnome-libs because it is such a          fundamental drawing item, especially with Imlib and          GnomeCanvasImage both deprecated in GNOME 2.0. However,          gdk-pixbuf does not exist as far as the GNOME 1.0 gnome-libs          is concerned, so retrofitting gnome-libs with          GnomeCanvasPixbuf would have resulted in an added depen-          dency of gnome-libs on the gdk-pixbuf library. Such a          radical change in dependencies should occur only between          significant version increases, so in order for          GnomeCanvasPixbuf to exist in 1.0 and 1.2 applications, it          was added to the gdk-pixbuf distribution instead. With the          arrival of GNOME 2.0, GnomeCanvasPixbuf will likely move to          gnome-libs; as we learned in Chapter 10, gdk-pixbuf itself          will be rolled into GTK+ 2.0, making the dependency issue a          moot point.        </P><P>          This tangled web leads to the strange situation in which the          pixbuf Canvas item is part of the gdk-pixbuf library for 1.x          applications, but part of the gnome-libs library for 2.0          applications. In the latter case, you won't have to touch a          thing; GnomeCanvasPixbuf will be linked into your          application along with the rest of gnome-libs. In 1.0 and          1.2 applications, however, GnomeCanvasPixbuf is linked into          a library of its own, libgnomecanvaspixbuf.so. You will have          to add a couple of invocations of gnome-config to pull that          library into your project:        </P><TABLEBORDER="0"BGCOLOR="#E0E0E0"WIDTH="100%"><TR><TD><PRECLASS="PROGRAMLISTING">gnome-config gnomecanvaspixbuf --cflagsgnome-config gnomecanvaspixbuf --libs        </PRE></TD></TR></TABLE></DIV></DIV><DIVCLASS="NAVFOOTER"><HRALIGN="LEFT"WIDTH="100%"><TABLEWIDTH="100%"BORDER="0"CELLPADDING="0"CELLSPACING="0"><TR><TDWIDTH="33%"ALIGN="left"VALIGN="top"><AHREF="gnome-canvas-using.html">Prev</A></TD><TDWIDTH="34%"ALIGN="center"VALIGN="top"><AHREF="index.html">Home</A></TD><TDWIDTH="33%"ALIGN="right"VALIGN="top"><AHREF="gnome-canvas-events.html">Next</A></TD></TR><TR><TDWIDTH="33%"ALIGN="left"VALIGN="top">Using the Canvas</TD><TDWIDTH="34%"ALIGN="center"VALIGN="top"><AHREF="gnome-canvas.html">Up</A></TD><TDWIDTH="33%"ALIGN="right"VALIGN="top">Canvas Events</TD></TR></TABLE></DIV></BODY></HTML>