CrCanvas

typedef struct {
        guint32 flags;
} CrCanvas;

cr_canvas_new ()

GtkWidget*          cr_canvas_new                       (const gchar *first_arg_name,
                                                         ...);

A convenience routine to create the canvas widget and set its properties in one call.

cr_canvas_set_scroll_region ()

void                cr_canvas_set_scroll_region         (CrCanvas *canvas,
                                                         gdouble scroll_x1,
                                                         gdouble scroll_y1,
                                                         gdouble scroll_x2,
                                                         gdouble scroll_y2);

Sets the canvas to a finite "world". The scrollbars or adjustments will not allow the canvas to scroll outside the input boundaries. The world to screen coordinate conversions are defined by the matrix held within the root group item.

cr_canvas_get_scroll_region ()

void                cr_canvas_get_scroll_region         (CrCanvas *canvas,
                                                         gdouble *scroll_x1,
                                                         gdouble *scroll_y1,
                                                         gdouble *scroll_x2,
                                                         gdouble *scroll_y2);

Gets the current scrolling area of the canvas. If the canvas is in 'infinite world' mode, this region will change often.

cr_canvas_set_scroll_factor ()

void                cr_canvas_set_scroll_factor         (CrCanvas *canvas,
                                                         double scroll_factor_x,
                                                         double scroll_factor_y);

This tells the canvas to assume that the world boundaries are infinite, but that scrolling should be arbitrarily limited to a factor of the displayed viewport size. i.e. a factor of 2 would allow a viewport showing a 100 unit range to be scrolled over a 200 unit range. This call causes the canvas to be in no way dependent on any setting in the root group item.

cr_canvas_scroll_to ()

void                cr_canvas_scroll_to                 (CrCanvas *canvas,
                                                         gdouble x,
                                                         gdouble y);

Places the given coordinate in the upper left corner of the current viewport. Coordinates are expected to be in user space and are translated to device space using the root group matrix. If finite world scrolling is used, it may be impossible to set the center to the requested coordinate. If infinite world scrolling is used the scroll area will be adjusted such that the requested center is also the center of the scroll region. This function is typically used with a document model when the 'auto_scale' and 'maintain_center' properties are disabled.

cr_canvas_get_scroll_offsets ()

void                cr_canvas_get_scroll_offsets        (CrCanvas *canvas,
                                                         gdouble *x,
                                                         gdouble *y);

A convenience function to get the upper leftmost canvas coordinate in root group units.

cr_canvas_center_on ()

void                cr_canvas_center_on                 (CrCanvas *canvas,
                                                         gdouble x,
                                                         gdouble y);

Places the given coordinate in the center of the current viewport. Coordinates are expected to be in user space and are translated to device space using the root group matrix. If finite world scrolling is used, it may be impossible to set the center to the requested coordinate. If infinite world scrolling is used the scroll area will be adjusted such that the requested center is also the center of the scroll region. This function is typically used when the 'auto_scale' or 'maintain_center' properties are set.

cr_canvas_get_center ()

void                cr_canvas_get_center                (CrCanvas *canvas,
                                                         gdouble *x,
                                                         gdouble *y);

Convenience function to get the center point of the viewport in root group coordinates.

cr_canvas_center_scale ()

void                cr_canvas_center_scale              (CrCanvas *canvas,
                                                         gdouble x,
                                                         gdouble y,
                                                         gdouble w,
                                                         gdouble h);

Centers and scales the canvas in one call. If a finite world scrolling is used, it may be impossible to honor this request. If infinite world scrolling is used the scrollable area will be adjusted such that the requested center is now the center of the scroll area. If the maintain_aspect property is TRUE, the scale request will be honored such that an equal to or larger area will be shown in the viewport.

cr_canvas_get_center_scale ()

void                cr_canvas_get_center_scale          (CrCanvas *canvas,
                                                         gdouble *cx,
                                                         gdouble *cy,
                                                         gdouble *w,
                                                         gdouble *h);

Passes back the center and width and height in user space.

cr_canvas_set_viewport ()

void                cr_canvas_set_viewport              (CrCanvas *canvas,
                                                         gdouble x1,
                                                         gdouble y1,
                                                         gdouble x2,
                                                         gdouble y2);

A simple wrapper around cr_canvas_center_scale. This procedure attempts to set the canvas viewport to honor the coordinates provided. If necessary, the canvas will be re-centeredand re-scaled. If a finite world scrolling is used, it may be impossible to honor this request. If infinite world scrolling is used the scrollable area will be adjusted such that the requested center is now the center of the scroll area. If the maintain_aspect property is TRUE, the scale request will be honored such that an equal to or larger area will be shown in the viewport.

cr_canvas_get_viewport ()

void                cr_canvas_get_viewport              (CrCanvas *canvas,
                                                         gdouble *x1,
                                                         gdouble *y1,
                                                         gdouble *x2,
                                                         gdouble *y2);

The four corners of the current viewport in user space.

cr_canvas_zoom ()

void                cr_canvas_zoom                      (CrCanvas *canvas,
                                                         gdouble x_factor,
                                                         gdouble y_factor);

Zooms the viewable area of the canvas in or out. Values greater than 1 zoom in, less than 1 zoom out. If the auto_scale or maintain_center properties are set, the viewport will be zoomed about the current center point, otherwise the viewport will be zoomed from upper left to lower right such that the upper left user coordinate is maintained. For a canvas where the maintain_aspect property is set, only the x_factor is used.

cr_canvas_zoom_world ()

void                cr_canvas_zoom_world                (CrCanvas *canvas);

Causes the canvas scale to zoom-out to show its maximum extents (or whole world). The maximum extents are determined as follows: (1) If finite world model (set_scroll_region), then such coordinates are used to define the new viewport. (2) If infinite world model and the min_scale_factor has been defined, then this is used. (3) Else the canvas is zoomed by the current scroll_factor.

cr_canvas_set_repaint_mode ()

void                cr_canvas_set_repaint_mode          (CrCanvas *canvas,
                                                         gboolean on);

Changes the canvas redraw model from invalidate to repaint. In the repaint model, the canvas redraws all items regardless of how many requested to be redrawn. This is useful when implementing scaling tools which would require all of the items to be redrawn for each update. It reduces the processing load slightly by preventing the canvas from running its invalidate loop. It may also be useful for implemenations that wish to implement a periodic screen refresh.

cr_canvas_queue_repaint ()

void                cr_canvas_queue_repaint             (CrCanvas *canvas);

Queues all items in the canvas to be repainted. This avoids running the canvas update loop until after the redraw is complete. This is useful when you need to continuously repaint for several cycles and want to avoid the cost of the canvas update loop until the repaint cycles are complete. Calling the routine is the same setting canvas repaint mode on and then switching it off at the first G_PRIORITY_LOW idle event.

cr_canvas_set_max_scale_factor ()

void                cr_canvas_set_max_scale_factor      (CrCanvas *canvas,
                                                         double x_factor,
                                                         double y_factor);

Defines the closest zoom-in scale allowed. This is used to prevent the underlying rendering routines from doing crazy things when a user presses a zoom-in button too many times. Example: For a 100x100 pixel window, values of 4,4 would allow the user to zoom in to show no less than 25x25 world coordinates.

cr_canvas_set_min_scale_factor ()

void                cr_canvas_set_min_scale_factor      (CrCanvas *canvas,
                                                         double x_factor,
                                                         double y_factor);

Defines the farthest zoom-out scale allowed. Example: For a 100x100 pixel window, values of 0.25, 0.25 would allow the user to zoom out to show no more than 400x400 world coordinates. In infinite world mode, this routine can be used to limit the maximum amount of the world view that can be rendered to There is no need to ever call this function if you use the finite world model by calling set_scroll_region. It will automatically be called whenever the canvas is resized.

cr_canvas_set_vadjustment ()

void                cr_canvas_set_vadjustment           (CrCanvas *canvas,
                                                         GtkAdjustment *adjustment);

Sets the vertical scroll adjustment for the layout.

See GtkScrolledWindow, GtkScrollbar, GtkAdjustment for details.

cr_canvas_set_hadjustment ()

void                cr_canvas_set_hadjustment           (CrCanvas *canvas,
                                                         GtkAdjustment *adjustment);

Sets the horizontal scroll adjustment for the layout.

See GtkScrolledWindow, GtkScrollbar, GtkAdjustment for details.

The "auto-scale" property

  "auto-scale"               gboolean              : Read / Write

Present viewport contents are retained on resize. This means items will be zoomed in or out depending on how the window changes.

Default value: FALSE

The "hadjustment" property

  "hadjustment"              GtkAdjustment*        : Read / Write

The GtkAdjustment for the horizontal position.

The "maintain-aspect" property

  "maintain-aspect"          gboolean              : Read / Write

Aspect ratio is maintained on resize andzooming events.

Default value: TRUE

The "maintain-center" property

  "maintain-center"          gboolean              : Read / Write

World center point remains on resize.

Default value: FALSE

The "pick-item" property

  "pick-item"                CrItem*               : Read

The lowest item in the tree presently receiving cursor events.

The "repaint-mode" property

  "repaint-mode"             gboolean              : Read / Write

Canvas repaints all items on each update.

Default value: FALSE

The "repaint-on-scroll" property

  "repaint-on-scroll"        gboolean              : Read / Write

Repaint the whole canvas when the scrollbar is moved. Default behavior is to move the previously painted area, This changes the default behavior to repaint the whole canvas instead. This is needed for the use case where something on the canvas will be changed immediately as a result of the scroll action.

Default value: FALSE

The "root" property

  "root"                     CrItem*               : Read / Write

The root canvas item for this widget.

The "show-less" property

  "show-less"                gboolean              : Read / Write

Whether to show more area or less area on a viewport resize when the aspect ratio changes. This only has an effect when both auto-scale and maintain-aspect are set.

Default value: FALSE

The "vadjustment" property

  "vadjustment"              GtkAdjustment*        : Read / Write

The GtkAdjustment for the vertical position.

The "before-paint" signal

void                user_function                      (CrCanvas  *canvas,
                                                        CrContext *cr,
                                                        gboolean   viewport_changed,
                                                        gpointer   user_data)             : Run First

This signal is emitted from the expose event of the canvas. It can be used to request additional updates or to take specific action resulting from a change to the viewport. The viewport may change as a result of a scrolling action or as a result of a scroll_to or center-on call. The viewport_changed flag will be FALSE if there was no change to the viewport since the last paint.

The "scroll-region-changed" signal

void                user_function                      (CrCanvas *canvas,
                                                        gpointer  user_data)      : Run First

This signal is emitted whenever the canvas scrolling region is manually or automatically modified. In the finite world model it is emitted only when cr_canvas_set_scroll_region is called external. In the infinite world model, it is emitted more frequently whenever the scrollbars are automatically re-centered or as a result of calling cr_canvas_set_scroll_factor externally.

The "set-scroll-adjustments" signal

void                user_function                      (CrCanvas      *crcanvas,
                                                        GtkAdjustment *arg1,
                                                        GtkAdjustment *arg2,
                                                        gpointer       user_data)      : Run Last / Action