## GnomeCanvas

GnomeCanvas

## Functions

#define | GNOME_CANVAS_COLOR()
#define | GNOME_CANVAS_COLOR_A()
GtkWidget * | gnome_canvas_new ()
GtkWidget * | gnome_canvas_new_aa ()
GnomeCanvasGroup * | gnome_canvas_root ()
void | gnome_canvas_set_scroll_region ()
void | gnome_canvas_get_scroll_region ()
void | gnome_canvas_set_center_scroll_region ()
gboolean | gnome_canvas_get_center_scroll_region ()
void | gnome_canvas_set_pixels_per_unit ()
void | gnome_canvas_scroll_to ()
void | gnome_canvas_get_scroll_offsets ()
void | gnome_canvas_update_now ()
GnomeCanvasItem * | gnome_canvas_get_item_at ()
void | gnome_canvas_request_redraw_uta ()
void | gnome_canvas_request_redraw ()
void | gnome_canvas_w2c_affine ()
void | gnome_canvas_w2c ()
void | gnome_canvas_w2c_d ()
void | gnome_canvas_c2w ()
void | gnome_canvas_window_to_world ()
void | gnome_canvas_world_to_window ()
int | gnome_canvas_get_color ()
gulong | gnome_canvas_get_color_pixel ()
void | gnome_canvas_set_stipple_origin ()
void | gnome_canvas_set_dither ()
GdkRgbDither | gnome_canvas_get_dither ()

## Properties

gboolean | aa | Read / Write / Construct Only
GnomeCanvasItem * | focused-item | Read / Write

## Signals

void | draw-background | Run Last
void | render-background | Run Last

## Types and Values

struct | GnomeCanvas
#define | GNOME_CANVAS_EPSILON
| GnomeCanvasBuf

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkObject
                ╰── GtkWidget
                    ╰── GtkContainer
                        ╰── GtkLayout
                            ╰── GnomeCanvas

## Implemented Interfaces

GnomeCanvas implements AtkImplementorIface and GtkBuildable.

## Includes

    #include <libgnomecanvas/libgnomecanvas.h>

## Description

## Functions

### GNOME_CANVAS_COLOR()

    #define             GNOME_CANVAS_COLOR(r, g, b)

### GNOME_CANVAS_COLOR_A()

    #define             GNOME_CANVAS_COLOR_A(r, g, b, a)

### gnome_canvas_new ()

    GtkWidget *
    gnome_canvas_new (void);

Creates a new empty canvas in non-antialiased mode.

#### Returns

A newly-created canvas.

### gnome_canvas_new_aa ()

    GtkWidget *
    gnome_canvas_new_aa (void);

Creates a new empty canvas in antialiased mode.

#### Returns

A newly-created antialiased canvas.

### gnome_canvas_root ()

    GnomeCanvasGroup *
    gnome_canvas_root (GnomeCanvas *canvas);

Queries the root group of a canvas.

#### Parameters

canvas | A canvas. |

#### Returns

The root group of the specified canvas.

### gnome_canvas_set_scroll_region ()

    void
    gnome_canvas_set_scroll_region (GnomeCanvas *canvas,
                                    double x1,
                                    double y1,
                                    double x2,
                                    double y2);

Sets the scrolling region of a canvas to the specified rectangle. The canvas will then be able to scroll only within this region. The view of the canvas is adjusted as appropriate to display as much of the new region as possible.

#### Parameters

canvas | A canvas. |
x1 | Leftmost limit of the scrolling region. |
y1 | Upper limit of the scrolling region. |
x2 | Rightmost limit of the scrolling region. |
y2 | Lower limit of the scrolling region. |

### gnome_canvas_get_scroll_region ()

    void
    gnome_canvas_get_scroll_region (GnomeCanvas *canvas,
                                    double *x1,
                                    double *y1,
                                    double *x2,
                                    double *y2);

Queries the scrolling region of a canvas.

#### Parameters

canvas | A canvas. |
x1 | Leftmost limit of the scrolling region (return value). |
y1 | Upper limit of the scrolling region (return value). |
x2 | Rightmost limit of the scrolling region (return value). |
y2 | Lower limit of the scrolling region (return value). |

### gnome_canvas_set_center_scroll_region ()

    void
    gnome_canvas_set_center_scroll_region (GnomeCanvas *canvas,
                                           gboolean center_scroll_region);

When the scrolling region of the canvas is smaller than the canvas window, e.g. the allocation of the canvas, it can be either centered on the window or simply made to be on the upper-left corner on the window. This function lets you configure this property.

#### Parameters

canvas | A canvas. |
center_scroll_region | Whether to center the scrolling region in the canvas window when it is smaller than the canvas' allocation. |

### gnome_canvas_get_center_scroll_region ()

    gboolean
    gnome_canvas_get_center_scroll_region (GnomeCanvas *canvas);

Returns whether the canvas is set to center the scrolling region in the window if the former is smaller than the canvas' allocation.

#### Parameters

canvas | A canvas. |

#### Returns

Whether the scroll region is being centered in the canvas window.

### gnome_canvas_set_pixels_per_unit ()

    void
    gnome_canvas_set_pixels_per_unit (GnomeCanvas *canvas,
                                      double n);

Sets the zooming factor of a canvas by specifying the number of pixels that correspond to one canvas unit.

The anchor point for zooming, i.e. the point that stays fixed and all others zoom inwards or outwards from it, depends on whether the canvas is set to center the scrolling region or not. You can control this using the `gnome_canvas_set_center_scroll_region()` function. If the canvas is set to center the scroll region, then the center of the canvas window is used as the anchor point for zooming. Otherwise, the upper-left corner of the canvas window is used as the anchor point.

#### Parameters

canvas | A canvas. |
n | The number of pixels that correspond to one canvas unit. |

### gnome_canvas_scroll_to ()

    void
    gnome_canvas_scroll_to (GnomeCanvas *canvas,
                            int cx,
                            int cy);

Makes a canvas scroll to the specified offsets, given in canvas pixel units. The canvas will adjust the view so that it is not outside the scrolling region. This function is typically not used, as it is better to hook scrollbars to the canvas layout's scrolling adjusments.

#### Parameters

canvas | A canvas. |
cx | Horizontal scrolling offset in canvas pixel units. |
cy | Vertical scrolling offset in canvas pixel units. |

### gnome_canvas_get_scroll_offsets ()

    void
    gnome_canvas_get_scroll_offsets (GnomeCanvas *canvas,
                                     int *cx,
                                     int *cy);

Queries the scrolling offsets of a canvas. The values are returned in canvas pixel units.

#### Parameters

canvas | A canvas. |
cx | Horizontal scrolling offset (return value). |
cy | Vertical scrolling offset (return value). |

### gnome_canvas_update_now ()

    void
    gnome_canvas_update_now (GnomeCanvas *canvas);

Forces an immediate update and redraw of a canvas. If the canvas does not have any pending update or redraw requests, then no action is taken. This is typically only used by applications that need explicit control of when the display is updated, like games. It is not needed by normal applications.

#### Parameters

canvas | A canvas. |

### gnome_canvas_get_item_at ()

    GnomeCanvasItem *
    gnome_canvas_get_item_at (GnomeCanvas *canvas,
                              double x,
                              double y);

Looks for the item that is under the specified position, which must be specified in world coordinates.

#### Parameters

canvas | A canvas. |
x | X position in world coordinates. |
y | Y position in world coordinates. |

#### Returns

The sought item, or NULL if no item is at the specified coordinates.

### gnome_canvas_request_redraw_uta ()

    void
    gnome_canvas_request_redraw_uta (GnomeCanvas *canvas,
                                     ArtUta *uta);

Informs a canvas that the specified area, given as a microtile array, needs to be repainted. To be used only by item implementations.

#### Parameters

canvas | A canvas. |
uta | Microtile array that specifies the area to be redrawn. It will be freed by this function, so the argument you pass will be invalid after you call this function. |

### gnome_canvas_request_redraw ()

    void
    gnome_canvas_request_redraw (GnomeCanvas *canvas,
                                 int x1,
                                 int y1,
                                 int x2,
                                 int y2);

Convenience function that informs a canvas that the specified rectangle needs to be repainted. This function converts the rectangle to a microtile array and feeds it to `gnome_canvas_request_redraw_uta()`. The rectangle includes `x1` and `y1` , but not `x2` and `y2` . To be used only by item implementations.

#### Parameters

canvas | A canvas. |
x1 | Leftmost coordinate of the rectangle to be redrawn. |
y1 | Upper coordinate of the rectangle to be redrawn. |
x2 | Rightmost coordinate of the rectangle to be redrawn, plus 1. |
y2 | Lower coordinate of the rectangle to be redrawn, plus 1. |

### gnome_canvas_w2c_affine ()

    void
    gnome_canvas_w2c_affine (GnomeCanvas *canvas,
                             double affine[6]);

Gets the affine transform that converts from world coordinates to canvas pixel coordinates.

#### Parameters

canvas | A canvas. |
affine | An affine transformation matrix (return value). |

### gnome_canvas_w2c ()

    void
    gnome_canvas_w2c (GnomeCanvas *canvas,
                      double wx,
                      double wy,
                      int *cx,
                      int *cy);

Converts world coordinates into canvas pixel coordinates.

#### Parameters

canvas | A canvas. |
wx | World X coordinate. |
wy | World Y coordinate. |
cx | X pixel coordinate (return value). |
cy | Y pixel coordinate (return value). |

### gnome_canvas_w2c_d ()

    void
    gnome_canvas_w2c_d (GnomeCanvas *canvas,
                        double wx,
                        double wy,
                        double *cx,
                        double *cy);

Converts world coordinates into canvas pixel coordinates. This version returns coordinates in floating point coordinates, for greater precision.

#### Parameters

canvas | A canvas. |
wx | World X coordinate. |
wy | World Y coordinate. |
cx | X pixel coordinate (return value). |
cy | Y pixel coordinate (return value). |

### gnome_canvas_c2w ()

    void
    gnome_canvas_c2w (GnomeCanvas *canvas,
                      int cx,
                      int cy,
                      double *wx,
                      double *wy);

Converts canvas pixel coordinates to world coordinates.

#### Parameters

canvas | A canvas. |
cx | Canvas pixel X coordinate. |
cy | Canvas pixel Y coordinate. |
wx | X world coordinate (return value). |
wy | Y world coordinate (return value). |

### gnome_canvas_window_to_world ()

    void
    gnome_canvas_window_to_world (GnomeCanvas *canvas,
                                  double winx,
                                  double winy,
                                  double *worldx,
                                  double *worldy);

Converts window-relative coordinates into world coordinates. You can use this when you need to convert mouse coordinates into world coordinates, for example.

#### Parameters

canvas | A canvas. |
winx | Window-relative X coordinate. |
winy | Window-relative Y coordinate. |
worldx | X world coordinate (return value). |
worldy | Y world coordinate (return value). |

### gnome_canvas_world_to_window ()

    void
    gnome_canvas_world_to_window (GnomeCanvas *canvas,
                                  double worldx,
                                  double worldy,
                                  double *winx,
                                  double *winy);

Converts world coordinates into window-relative coordinates.

#### Parameters

canvas | A canvas. |
worldx | World X coordinate. |
worldy | World Y coordinate. |
winx | X window-relative coordinate. |
winy | Y window-relative coordinate. |

### gnome_canvas_get_color ()

    int
    gnome_canvas_get_color (GnomeCanvas *canvas,
                            const char *spec,
                            GdkColor *color);

Allocates a color based on the specified X color specification. As a convenience to item implementations, it returns TRUE if the color was allocated, or FALSE if the specification was NULL. A NULL color specification is considered as "transparent" by the canvas.

#### Parameters

canvas | A canvas. |
spec | X color specification, or NULL for "transparent". |
color | Returns the allocated color. |

#### Returns

TRUE if `spec` is non-NULL and the color is allocated. If `spec` is NULL, then returns FALSE.

### gnome_canvas_get_color_pixel ()

    gulong
    gnome_canvas_get_color_pixel (GnomeCanvas *canvas,
                                  guint rgba);

Allocates a color from the RGBA value passed into this function. The alpha opacity value is discarded, since normal X colors do not support it.

#### Parameters

canvas | A canvas. |
rgba | RGBA color specification. |

#### Returns

Allocated pixel value corresponding to the specified color.

### gnome_canvas_set_stipple_origin ()

    void
    gnome_canvas_set_stipple_origin (GnomeCanvas *canvas,
                                     GdkGC *gc);

Sets the stipple origin of the specified GC as is appropriate for the canvas, so that it will be aligned with other stipple patterns used by canvas items. This is typically only needed by item implementations.

#### Parameters

canvas | A canvas. |
gc | GC on which to set the stipple origin. |

### gnome_canvas_set_dither ()

    void
    gnome_canvas_set_dither (GnomeCanvas *canvas,
                             GdkRgbDither dither);

Controls dithered rendering for antialiased canvases. The value of dither should be GDK_RGB_DITHER_NONE, GDK_RGB_DITHER_NORMAL, or GDK_RGB_DITHER_MAX. The default canvas setting is GDK_RGB_DITHER_NORMAL.

#### Parameters

canvas | A canvas. |
dither | Type of dithering used to render an antialiased canvas. |

### gnome_canvas_get_dither ()

    GdkRgbDither
    gnome_canvas_get_dither (GnomeCanvas *canvas);

Returns the type of dithering used to render an antialiased canvas.

#### Parameters

canvas | A canvas. |

#### Returns

The dither setting.

## Types and Values

### struct GnomeCanvas

    struct GnomeCanvas;

### GNOME_CANVAS_EPSILON

    #define GNOME_CANVAS_EPSILON 1e-10

### GnomeCanvasBuf

    typedef struct {
    	/* 24-bit RGB buffer for rendering */
    	guchar *buf;

    	/* Rectangle describing the rendering area */
    	ArtIRect rect;

    	/* Rowstride for the buffer */
    	int buf_rowstride;

    	/* Background color, given as 0xrrggbb */
    	guint32 bg_color;

    	/* Invariant: at least one of the following flags is true. */

    	/* Set when the render rectangle area is the solid color bg_color */
    	unsigned int is_bg : 1;

    	/* Set when the render rectangle area is represented by the buf */
    	unsigned int is_buf : 1;
    } GnomeCanvasBuf;

## Property Details

### The `“aa”` property

      “aa”                       gboolean

The antialiasing mode of the canvas.

Owner: GnomeCanvas

Flags: Read / Write / Construct Only

Default value: FALSE

### The `“focused-item”` property

      “focused-item”             GnomeCanvasItem *

Owner: GnomeCanvas

Flags: Read / Write

## Signal Details

### The `“draw-background”` signal

    void
    user_function (GnomeCanvas *canvas,
                   GdkDrawable *arg1,
                   int          arg2,
                   int          arg3,
                   int          arg4,
                   int          arg5,
                   gpointer     user_data)

Flags: Run Last

### The `“render-background”` signal

    void
    user_function (GnomeCanvas *canvas,
                   gpointer     arg1,
                   gpointer     user_data)

Flags: Run Last