📄 gnome-canvas-using.html
字号:
<HTML><HEAD><TITLE>Using the Canvas</TITLE><METANAME="GENERATOR"CONTENT="Modular DocBook HTML Stylesheet Version 1.61"><LINKREL="HOME"TITLE="Writing GNOME Applications"HREF="index.html"><LINKREL="UP"TITLE="The GNOME Canvas"HREF="gnome-canvas.html"><LINKREL="PREVIOUS"TITLE="Coordinate Systems"HREF="gnome-canvas-coordinates.html"><LINKREL="NEXT"TITLE="Canvas Items"HREF="gnome-canvas-items.html"></HEAD><BODYCLASS="SECT1"><DIVCLASS="NAVHEADER"><TABLEWIDTH="100%"BORDER="0"CELLPADDING="0"CELLSPACING="0"><TR><THCOLSPAN="3"ALIGN="center">Writing GNOME Applications</TH></TR><TR><TDWIDTH="10%"ALIGN="left"VALIGN="bottom"><AHREF="gnome-canvas-coordinates.html">Prev</A></TD><TDWIDTH="80%"ALIGN="center"VALIGN="bottom">Chapter 11. The GNOME Canvas</TD><TDWIDTH="10%"ALIGN="right"VALIGN="bottom"><AHREF="gnome-canvas-items.html">Next</A></TD></TR></TABLE><HRALIGN="LEFT"WIDTH="100%"></DIV><DIVCLASS="SECT1"><H1CLASS="SECT1"><ANAME="GNOME-CANVAS-USING">Using the Canvas</A></H1><P> The GNOME Canvas is fundamentally a GTK+ widget, and as such it uses an API similar to that used by most other GTK+ widgets. You create it with a _new( ) function and destroy it with the gtk_object_destroy( ) function. You can connect to its GTK+ signals and interact with the user through the GDK event system. In this section we'll explore the ins and outs of interacting with the GNOME Canvas widget. </P><DIVCLASS="SECT2"><H2CLASS="SECT2"><ANAME="AEN1080">GDK versus AA</A></H2><P> The GNOME Canvas supports two different drawing modes: GDK mode, which uses native GDK elements; and anti-aliased mode, or AA mode, which uses the advanced rendering features of the GdkRGB system and allows varying degrees of transparency between Canvas items. GDK mode, which is the default Canvas mode, is quicker, more direct, and less intensive but lacks the smoothed edges and translucency of AA mode. The anti-aliased Canvas is also more flexible about which transforms you can perform on its items, but its per- formance is slower,1 and it does not currently support all of the native GDK drawing properties, like dotted lines and stippled fills. </P><P> You determine which Canvas mode to use at the time of widget creation; you cannot change modes later without causing a lot of problems, so make your choice carefully. Each mode has its own creation function: </P><TABLEBORDER="0"BGCOLOR="#E0E0E0"WIDTH="100%"><TR><TD><PRECLASS="PROGRAMLISTING">GtkWidget *gnome_canvas_new( );GtkWidget *gnome_canvas_new_aa( ); </PRE></TD></TR></TABLE><P> The only difference between these two functions is a single Boolean flag, aa, in the GnomeCanvas structure, which is turned on for AA Canvas items and off for GDK Canvas items. This is an internal value, and you should never try to change it yourself. The Canvas uses this flag throughout its operations to differentiate between the two styles of rendering. You are not really creating two different types of Canvas widgets, but rather telling a single type of widget to behave differently in each case. </P><P> Each mode handles color depths and visuals according to its own needs. To help accommodate these needs and make sure the Canvas can find the proper color maps and visuals (see Chapter 10), you should wrap the creation function with push and pop calls to load and unload them, respectively, de- pending on how you intend to use the Canvas. </P><P> The anti-aliased Canvas always uses GdkRGB to render, so you should push its specially tuned visual and color map for AA-mode Canvas widgets. You should also remember to initialize GdkRGB beforehand, using the gdk_rgb_init( ) function: </P><TABLEBORDER="0"BGCOLOR="#E0E0E0"WIDTH="100%"><TR><TD><PRECLASS="PROGRAMLISTING">GtkWidget *canvas_widget;gdk_rgb_init( );gtk_widget_push_visual(gdk_rgb_get_visual( ));gtk_widget_push_colormap(gdk_rgb_get_cmap( ));canvas_widget = gnome_canvas_new_aa( );gtk_widget_pop_visual( );gtk_widget_pop_colormap( ); </PRE></TD></TR></TABLE><P> If you forget to do this, your Canvas will probably still work, but it may experience strange color problems in certain situations. The GDK-mode Canvas can also use the GdkRGB visual and color map if you plan on using the gdk- pixbuf library to load your images. In this case you will want to use the GnomeCanvasPixbuf item (see Section 11.4.6). </P><P> On the other hand, if you want to use Imlib as your image loader, you should load up GdkImlib's visual and color map instead of GdkRGB's: </P><TABLEBORDER="0"BGCOLOR="#E0E0E0"WIDTH="100%"><TR><TD><PRECLASS="PROGRAMLISTING">GtkWidget *canvas_widget;gtk_widget_push_visual(gdk_imlib_get_visual( ));gtk_widget_push_colormap(gdk_imlib_get_colormap( ));canvas_widget = gnome_canvas_new( );gtk_widget_pop_visual( );gtk_widget_pop_colormap( ); </PRE></TD></TR></TABLE><P> Since Imlib's color map tends to clash with GdkRGB, it's not a good idea to use Imlib with an AA-mode Canvas. Thus with Imlib you should stick to using GDK mode and the GnomeCanvasImage item (also in Section 11.4.6). </P><P> If you want your Canvas to have scroll bars, you can embed them in a GtkScrolledWindow widget with minimal effort. GtkScrolledWindow will attach itself to the Canvas and automatically wire up its scroll bars with the Canvas's scrolling code. The following snippet of code is all you'll need in most cases: </P><TABLEBORDER="0"BGCOLOR="#E0E0E0"WIDTH="100%"><TR><TD><PRECLASS="PROGRAMLISTING">GtkWidget *scrollwin;scrollwin = gtk_scrolled_window_new(NULL, NULL);gtk_container_add(GTK_CONTAINER(scrollwin), canvas_widget); </PRE></TD></TR></TABLE><P> You can then put the GtkScrolledWindow widget into your GnomeApp widget, or pack it into whatever container you want to hold your Canvas. </P></DIV><DIVCLASS="SECT2"><H2CLASS="SECT2"><ANAME="AEN1096">The Scrolling Region</A></H2><P> If you stop right here, your Canvas will not have all the information it needs to render your Canvas items properly. You need to tell it how much of the potentially infinite reaches of the world coordinate space the Canvas should be allowed to draw on and scroll through. You do this by setting the Canvas's scrolling region. The Canvas cannot scroll outside of this region: </P><TABLEBORDER="0"BGCOLOR="#E0E0E0"WIDTH="100%"><TR><TD><PRECLASS="PROGRAMLISTING">void gnome_canvas_set_scroll_region (GnomeCanvas *canvas, double x1, double y1, double x2, double y2); </PRE></TD></TR></TABLE><P> You can safely call this function at any time, which implies that it's legal to have Canvas items outside the boundaries of the scrolling region. They just won't be visible until they move inside the region or the region expands to in- clude them. </P><P> Another property you can change is the scaling factor between the (abstract) world coordinates and the (pixel-based) canvas coordinates. By default, this value is set to 1.0, which means that world coordinates will have a one-to-one relationship to pixels. When world coordinates are transformed into canvas coordinates, they are multiplied-in both directions, x and y alike-by this scaling factor. Thus if you set the scaling factor to a high number, the Canvas will render everything bigger, as if you had zoomed in. If you set the scaling factor to a fraction, between 0.0 and 1.0, the Canvas will render things smaller. The function gnome_canvas_set_pixels_per_unit( ) changes this scaling factor and triggers a redraw of the entire visible area: </P><TABLEBORDER="0"BGCOLOR="#E0E0E0"WIDTH="100%"><TR><TD><PRECLASS="PROGRAMLISTING">void gnome_canvas_set_pixels_per_unit(GnomeCanvas *canvas, double n); </PRE></TD></TR></TABLE><P> Usually scroll bars are enough to cover your Canvas scrolling needs, especially if your scrolling region always matches your viewable region. Sometimes, however, you will want to control the scrolling manually, programmatically, to override the default scrolling behavior. Perhaps you need to snap the Canvas up to the top of the scrolling area, or move it to follow something the user is doing. </P><P> The gnome_canvas_scroll_to( ) function allows you to explicitly move the view port to any portion of the Canvas's area, identified by Canvas pixel coordinates. The Canvas will attempt to scroll to place those coordinates into the upper left corner of the Canvas display, but it may adjust the position a little to maximize the viewable space. The complementary function, gnome_canvas_get_scroll_offsets( ), retrieves the current scroll position: </P><TABLEBORDER="0"BGCOLOR="#E0E0E0"WIDTH="100%"><TR><TD><PRECLASS="PROGRAMLISTING">void gnome_canvas_scroll_to(GnomeCanvas *canvas, int cx, int cy);void gnome_canvas_get_scroll_offsets(GnomeCanvas *canvas, int *cx, int *cy); </PRE></TD></TR></TABLE><P> Thus given a viewable area of 100 100 pixels and a Canvas size of 200 200 pixels, an attempt to scroll to the coordinates (150, 150) would theoretically end up showing only a 50 50-pixel square of valid Canvas in the upper left corner of the viewing space, with the other 75 percent showing blank, invalid space (see Figure 11.2). To minimize this wasted space, the Canvas automatically shifts the offset from (150, 150) to (100, 100) so that the entire viewing area contains valid Canvas space. </P><DIVCLASS="FIGURE"><ANAME="AEN1107"></A><P><B>Figure 11-2. Maximizing the Viewing Space</B></P><DIVCLASS="MEDIAOBJECT"><P><IMGSRC="figures/11f2.png"></IMG></P></DIV></DIV><P> These two functions deal in absolute coordinates. Relative scrolling is also possible, by identifying the current scrolling position with the gnome_canvas_get_scroll_offsets( ) function and calculating a new position to send to gnome_canvas_scroll_to( ). For example, if you wanted to scroll 20 pixels to the right, regardless of where the Canvas currently was, you could do something like this: </P><TABLEBORDER="0"BGCOLOR="#E0E0E0"WIDTH="100%"><TR><TD><PRECLASS="PROGRAMLISTING">int x;int y;GnomeCanvas *canvas;...gnome_canvas_get_scroll_offsets(canvas, &x, &y);gnome_canvas_scroll_to(canvas, x + 20, y); </PRE></TD></TR></TABLE></DIV><DIVCLASS="SECT2"><H2CLASS="SECT2"><ANAME="AEN1114">Adding Canvas Items</A></H2><P> Now that the GnomeCanvas widget exists, you can start adding items to it. GNOME has only one function for creating Canvas items. Each time you create a new item, you must pass in the Canvas group to which you want it added, the GTK+ type for the Canvas item, and an optional list of properties with which to initialize the item: </P><TABLEBORDER="0"BGCOLOR="#E0E0E0"WIDTH="100%"><TR><TD><PRECLASS="PROGRAMLISTING">GnomeCanvasItem *gnome_canvas_item_new(GnomeCanvasGroup *parent, GtkType type, const gchar *first_arg_name, ...); </PRE></TD></TR></TABLE><P> If you need to set or change any properties after the fact, you can use the item's accessor function: </P><TABLEBORDER="0"BGCOLOR="#E0E0E0"WIDTH="100%"><TR><TD><PRECLASS="PROGRAMLISTING">void gnome_canvas_item_set(GnomeCanvasItem *item, const gchar *first_arg_name, ...); </PRE></TD></TR></TABLE><P> Both variable parameter lists-indicated by the ellipses-work in the same way. Each property in the list requires exactly two parameters: The first parameter is a string declaring the property's name, and the second parameter is the actual value of that property. The property-value pairs can come in any order. You must always terminate the variable parameter list with a NULL value so that the parameter-parsing code will know when to stop. Also, since the value parameter can be a different type for each property, you have to be very careful not to pass in the wrong type. For example, if you⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -