Synopsis

#include <adg-1/adg.h>

struct              AdgCanvas;
struct              AdgCanvasClass;
AdgCanvas *         adg_canvas_new                      (void);
void                adg_canvas_set_size                 (AdgCanvas *canvas,
                                                         const CpmlPair *size);
void                adg_canvas_set_size_explicit        (AdgCanvas *canvas,
                                                         gdouble x,
                                                         gdouble y);
const CpmlPair *    adg_canvas_get_size                 (AdgCanvas *canvas);
void                adg_canvas_set_scales               (AdgCanvas *canvas,
                                                         ...);
void                adg_canvas_set_scales_valist        (AdgCanvas *canvas,
                                                         va_list var_args);
void                adg_canvas_set_scales_array         (AdgCanvas *canvas,
                                                         gchar **scales);
gchar **            adg_canvas_get_scales               (AdgCanvas *canvas);
void                adg_canvas_autoscale                (AdgCanvas *canvas);
void                adg_canvas_set_background_dress     (AdgCanvas *canvas,
                                                         AdgDress dress);
AdgDress            adg_canvas_get_background_dress     (AdgCanvas *canvas);
void                adg_canvas_set_frame_dress          (AdgCanvas *canvas,
                                                         AdgDress dress);
AdgDress            adg_canvas_get_frame_dress          (AdgCanvas *canvas);
void                adg_canvas_set_title_block          (AdgCanvas *canvas,
                                                         AdgTitleBlock *title_block);
AdgTitleBlock *     adg_canvas_get_title_block          (AdgCanvas *canvas);
void                adg_canvas_set_top_margin           (AdgCanvas *canvas,
                                                         gdouble value);
gdouble             adg_canvas_get_top_margin           (AdgCanvas *canvas);
void                adg_canvas_set_right_margin         (AdgCanvas *canvas,
                                                         gdouble value);
gdouble             adg_canvas_get_right_margin         (AdgCanvas *canvas);
void                adg_canvas_set_bottom_margin        (AdgCanvas *canvas,
                                                         gdouble value);
gdouble             adg_canvas_get_bottom_margin        (AdgCanvas *canvas);
void                adg_canvas_set_left_margin          (AdgCanvas *canvas,
                                                         gdouble value);
gdouble             adg_canvas_get_left_margin          (AdgCanvas *canvas);
void                adg_canvas_set_margins              (AdgCanvas *canvas,
                                                         gdouble top,
                                                         gdouble right,
                                                         gdouble bottom,
                                                         gdouble left);
void                adg_canvas_apply_margins            (AdgCanvas *canvas,
                                                         CpmlExtents *extents);
void                adg_canvas_switch_frame             (AdgCanvas *canvas,
                                                         gboolean new_state);
gboolean            adg_canvas_has_frame                (AdgCanvas *canvas);
void                adg_canvas_set_top_padding          (AdgCanvas *canvas,
                                                         gdouble value);
gdouble             adg_canvas_get_top_padding          (AdgCanvas *canvas);
void                adg_canvas_set_right_padding        (AdgCanvas *canvas,
                                                         gdouble value);
gdouble             adg_canvas_get_right_padding        (AdgCanvas *canvas);
void                adg_canvas_set_bottom_padding       (AdgCanvas *canvas,
                                                         gdouble value);
gdouble             adg_canvas_get_bottom_padding       (AdgCanvas *canvas);
void                adg_canvas_set_left_padding         (AdgCanvas *canvas,
                                                         gdouble value);
gdouble             adg_canvas_get_left_padding         (AdgCanvas *canvas);
void                adg_canvas_set_paddings             (AdgCanvas *canvas,
                                                         gdouble top,
                                                         gdouble right,
                                                         gdouble bottom,
                                                         gdouble left);
void                adg_canvas_set_paper                (AdgCanvas *canvas,
                                                         const gchar *paper_name,
                                                         GtkPageOrientation orientation);
void                adg_canvas_set_page_setup           (AdgCanvas *canvas,
                                                         GtkPageSetup *page_setup);
GtkPageSetup *      adg_canvas_get_page_setup           (AdgCanvas *canvas);

Object Hierarchy

  GObject
   +----GInitiallyUnowned
         +----AdgEntity
               +----AdgContainer
                     +----AdgCanvas

Properties

  "background-dress"         AdgDress              : Read / Write
  "bottom-margin"            gdouble               : Read / Write
  "bottom-padding"           gdouble               : Read / Write
  "frame-dress"              AdgDress              : Read / Write
  "has-frame"                gboolean              : Read / Write
  "left-margin"              gdouble               : Read / Write
  "left-padding"             gdouble               : Read / Write
  "right-margin"             gdouble               : Read / Write
  "right-padding"            gdouble               : Read / Write
  "scales"                   GStrv                 : Read / Write
  "size"                     CpmlPair*             : Read / Write
  "title-block"              AdgTitleBlock*        : Read / Write
  "top-margin"               gdouble               : Read / Write
  "top-padding"              gdouble               : Read / Write

Description

The canvas is the toplevel entity of an ADG drawing. It can be bound to a GTK+ widget, such as AdgGtkArea, or manually rendered to a custom surface.

Tipically, the canvas contains the description and properties of the media used, such as such as size (if relevant), margins, border and paddings. This approach clearly follows the block model of the CSS specifications level 2.

The paddings specify the distance between the entities contained by the canvas and the border. The margins specify the distance between the canvas border and the media extents.

The canvas (hence the media) size can be explicitely specified by directly writing to the "size" property or using any valid setter, such as adg_canvas_set_size(), adg_canvas_set_size_explicit() or the convenient adg_canvas_set_paper() GTK+ wrapper. You can also set explicitely only one dimension and let the other one be computed automatically. This is done by using the special value 0 that specifies a side must be autocalculated.

By default either width and height must be autocalculated (are set to 0), so the arrange() phase on the canvas is performed. Margins and paddings are then added to the extents to get the border coordinates and the final bounding box.

When the size is explicitely set, instead, the final bounding box is forcibly set to this value without taking the canvas extents into account. The margins are then subtracted to get the coordinates of the border. In this case, the paddings are simply ignored.

Details

struct AdgCanvas

struct AdgCanvas;

All fields are private and should not be used directly. Use its public methods instead.

Since 1.0


struct AdgCanvasClass

struct AdgCanvasClass {
};

adg_canvas_new ()

AdgCanvas *         adg_canvas_new                      (void);

Creates a new empty canvas object.

Returns :

the newly created canvas. [transfer full]

Since 1.0


adg_canvas_set_size ()

void                adg_canvas_set_size                 (AdgCanvas *canvas,
                                                         const CpmlPair *size);

Sets a specific size on canvas. The x and/or y component of size can be set to 0, in which case the exact value will be autocalculated, that is the size component returned by adg_entity_get_extents() on canvas will be used instead.

canvas :

an AdgCanvas

size :

the new size for the canvas. [transfer none]

Since 1.0


adg_canvas_set_size_explicit ()

void                adg_canvas_set_size_explicit        (AdgCanvas *canvas,
                                                         gdouble x,
                                                         gdouble y);

A convenient function to set the size of canvas using explicit coordinates. Check adg_canvas_set_size() for further details.

canvas :

an AdgCanvas

x :

the new width of the canvas or 0 to reset

y :

the new height of the canvas or 0 to reset

Since 1.0


adg_canvas_get_size ()

const CpmlPair *    adg_canvas_get_size                 (AdgCanvas *canvas);

Gets the specific size set on canvas. The x and/or y components of the returned CpmlPair could be 0, in which case the size returned by adg_entity_get_extents() on canvas will be used instead.

canvas :

an AdgCanvas

Returns :

the explicit size set on this canvas or NULL on errors. [transfer none]

Since 1.0


adg_canvas_set_scales ()

void                adg_canvas_set_scales               (AdgCanvas *canvas,
                                                         ...);

Sets the scales allowed by canvas. Every scale identifies a specific factor to be applied to the local matrix of canvas. When adg_canvas_autoscale() will be called, the greatest scale that can render every entity inside a box of "size" dimensions will be applied. The drawing will be centered inside that box.

Every scale should be expressed with a string in the form of "x:y", where x and y are positive integers that identifies numerator an denominator of a fraction. That string itself will be put into the title block when used.

canvas :

an AdgCanvas

... :

NULL terminated list of strings

Since 1.0


adg_canvas_set_scales_valist ()

void                adg_canvas_set_scales_valist        (AdgCanvas *canvas,
                                                         va_list var_args);

Vararg variant of adg_canvas_set_scales().

canvas :

an AdgCanvas

var_args :

NULL terminated list of strings

Since 1.0


adg_canvas_set_scales_array ()

void                adg_canvas_set_scales_array         (AdgCanvas *canvas,
                                                         gchar **scales);

Array variant of adg_canvas_set_scales().

Rename to: adg_canvas_set_scales

canvas :

an AdgCanvas

scales :

NULL terminated array of scales. [array zero-terminated=1][allow-none]

Since 1.0


adg_canvas_get_scales ()

gchar **            adg_canvas_get_scales               (AdgCanvas *canvas);

Gets the list of scales set on canvas: check adg_canvas_set_scales() to get an idea of what scales are supposed to be.

If no scales are set, NULL is returned.

canvas :

an AdgCanvas

Returns :

the NULL terminated list of valid scales. [element-type utf8][transfer none]

Since 1.0


adg_canvas_autoscale ()

void                adg_canvas_autoscale                (AdgCanvas *canvas);

Applies one scale per time, in the order they have been provided in the adg_canvas_set_scales() call, until the drawing can be entirely contained into the current paper. If successful, the scale of the title block is changed accordingly and the drawing is centered inside the paper.

canvas :

an AdgCanvas

Since 1.0


adg_canvas_set_background_dress ()

void                adg_canvas_set_background_dress     (AdgCanvas *canvas,
                                                         AdgDress dress);

Sets a new background dress for rendering canvas: the new dress must be a color dress.

canvas :

an AdgCanvas

dress :

the new AdgDress to use

Since 1.0


adg_canvas_get_background_dress ()

AdgDress            adg_canvas_get_background_dress     (AdgCanvas *canvas);

Gets the background dress to be used in rendering canvas.

canvas :

an AdgCanvas

Returns :

the current background dress.

Since 1.0


adg_canvas_set_frame_dress ()

void                adg_canvas_set_frame_dress          (AdgCanvas *canvas,
                                                         AdgDress dress);

Sets the "frame-dress" property of canvas to dress: the new dress must be a line dress.

canvas :

an AdgCanvas

dress :

the new AdgDress to use

Since 1.0


adg_canvas_get_frame_dress ()

AdgDress            adg_canvas_get_frame_dress          (AdgCanvas *canvas);

Gets the frame dress to be used in rendering the border of canvas.

canvas :

an AdgCanvas

Returns :

the current frame dress.

Since 1.0


adg_canvas_set_title_block ()

void                adg_canvas_set_title_block          (AdgCanvas *canvas,
                                                         AdgTitleBlock *title_block);

Sets the "title-block" property of canvas to title_block.

Although a title block entity could be added to canvas in the usual way, that is using the adg_container_add() method, assigning a title block with adg_canvas_set_title_block() is somewhat different:

  • title_block will be automatically attached to the bottom right corner of to the canvas frame (this could be accomplished in the usual way too, by resetting the right and bottom paddings);

  • the title_block boundary box is not taken into account while computing the extents of canvas.

canvas :

an AdgCanvas

title_block :

a title block. [transfer full]

Since 1.0


adg_canvas_get_title_block ()

AdgTitleBlock *     adg_canvas_get_title_block          (AdgCanvas *canvas);

Gets the AdgTitleBlock object of canvas: check adg_canvas_set_title_block() for details.

The returned entity is owned by canvas and should not be modified or freed.

canvas :

an AdgCanvas

Returns :

the title block object or NULL. [transfer none]

Since 1.0


adg_canvas_set_top_margin ()

void                adg_canvas_set_top_margin           (AdgCanvas *canvas,
                                                         gdouble value);

Changes the top margin of canvas by setting "top-margin" to value. Negative values are allowed.

canvas :

an AdgCanvas

value :

the new margin, in global space

Since 1.0


adg_canvas_get_top_margin ()

gdouble             adg_canvas_get_top_margin           (AdgCanvas *canvas);

Gets the top margin (in global space) of canvas.

canvas :

an AdgCanvas

Returns :

the requested margin or 0 on error.

Since 1.0


adg_canvas_set_right_margin ()

void                adg_canvas_set_right_margin         (AdgCanvas *canvas,
                                                         gdouble value);

Changes the right margin of canvas by setting "right-margin" to value. Negative values are allowed.

canvas :

an AdgCanvas

value :

the new margin, in global space

Since 1.0


adg_canvas_get_right_margin ()

gdouble             adg_canvas_get_right_margin         (AdgCanvas *canvas);

Gets the right margin (in global space) of canvas.

canvas :

an AdgCanvas

Returns :

the requested margin or 0 on error.

Since 1.0


adg_canvas_set_bottom_margin ()

void                adg_canvas_set_bottom_margin        (AdgCanvas *canvas,
                                                         gdouble value);

Changes the bottom margin of canvas by setting "bottom-margin" to value. Negative values are allowed.

canvas :

an AdgCanvas

value :

the new margin, in global space

Since 1.0


adg_canvas_get_bottom_margin ()

gdouble             adg_canvas_get_bottom_margin        (AdgCanvas *canvas);

Gets the bottom margin (in global space) of canvas.

canvas :

an AdgCanvas

Returns :

the requested margin or 0 on error.

Since 1.0


adg_canvas_set_left_margin ()

void                adg_canvas_set_left_margin          (AdgCanvas *canvas,
                                                         gdouble value);

Changes the left margin of canvas by setting "left-margin" to value. Negative values are allowed.

canvas :

an AdgCanvas

value :

the new margin, in global space

Since 1.0


adg_canvas_get_left_margin ()

gdouble             adg_canvas_get_left_margin          (AdgCanvas *canvas);

Gets the left margin (in global space) of canvas.

canvas :

an AdgCanvas

Returns :

the requested margin or 0 on error.

Since 1.0


adg_canvas_set_margins ()

void                adg_canvas_set_margins              (AdgCanvas *canvas,
                                                         gdouble top,
                                                         gdouble right,
                                                         gdouble bottom,
                                                         gdouble left);

Convenient function to set all the margins at once.

canvas :

an AdgCanvas

top :

top margin, in global space

right :

right margin, in global space

bottom :

bottom margin, in global space

left :

left margin, in global space

Since 1.0


adg_canvas_apply_margins ()

void                adg_canvas_apply_margins            (AdgCanvas *canvas,
                                                         CpmlExtents *extents);

A convenient function to apply the margins of canvas to the arbitrary CpmlExtents struct extents.

canvas :

an AdgCanvas

extents :

where apply the margins

Since 1.0


adg_canvas_switch_frame ()

void                adg_canvas_switch_frame             (AdgCanvas *canvas,
                                                         gboolean new_state);

Sets a new status on the "has-frame" property: TRUE means a border around the canvas extents (less the margins) should be rendered.

canvas :

an AdgCanvas

new_state :

the new flag status

Since 1.0


adg_canvas_has_frame ()

gboolean            adg_canvas_has_frame                (AdgCanvas *canvas);

Gets the current status of the "has-frame" property, that is whether a border around the canvas extents (less the margins) should be rendered (TRUE) or not (FALSE).

canvas :

an AdgCanvas

Returns :

the current status of the frame flag.

Since 1.0


adg_canvas_set_top_padding ()

void                adg_canvas_set_top_padding          (AdgCanvas *canvas,
                                                         gdouble value);

Changes the top padding of canvas by setting "top-padding" to value. Negative values are allowed.

canvas :

an AdgCanvas

value :

the new padding, in global space

Since 1.0


adg_canvas_get_top_padding ()

gdouble             adg_canvas_get_top_padding          (AdgCanvas *canvas);

Gets the top padding (in global space) of canvas.

canvas :

an AdgCanvas

Returns :

the requested padding or 0 on error.

Since 1.0


adg_canvas_set_right_padding ()

void                adg_canvas_set_right_padding        (AdgCanvas *canvas,
                                                         gdouble value);

Changes the right padding of canvas by setting "right-padding" to value. Negative values are allowed.

canvas :

an AdgCanvas

value :

the new padding, in global space

Since 1.0


adg_canvas_get_right_padding ()

gdouble             adg_canvas_get_right_padding        (AdgCanvas *canvas);

Gets the right padding (in global space) of canvas.

canvas :

an AdgCanvas

Returns :

the requested padding or 0 on error.

Since 1.0


adg_canvas_set_bottom_padding ()

void                adg_canvas_set_bottom_padding       (AdgCanvas *canvas,
                                                         gdouble value);

Changes the bottom padding of canvas by setting "bottom-padding" to value. Negative values are allowed.

canvas :

an AdgCanvas

value :

the new padding, in global space

Since 1.0


adg_canvas_get_bottom_padding ()

gdouble             adg_canvas_get_bottom_padding       (AdgCanvas *canvas);

Gets the bottom padding (in global space) of canvas.

canvas :

an AdgCanvas

Returns :

the requested padding or 0 on error.

Since 1.0


adg_canvas_set_left_padding ()

void                adg_canvas_set_left_padding         (AdgCanvas *canvas,
                                                         gdouble value);

Changes the left padding of canvas by setting "left-padding" to value. Negative values are allowed.

canvas :

an AdgCanvas

value :

the new padding, in global space

Since 1.0


adg_canvas_get_left_padding ()

gdouble             adg_canvas_get_left_padding         (AdgCanvas *canvas);

Gets the left padding (in global space) of canvas.

canvas :

an AdgCanvas

Returns :

the requested padding or 0 on error.

Since 1.0


adg_canvas_set_paddings ()

void                adg_canvas_set_paddings             (AdgCanvas *canvas,
                                                         gdouble top,
                                                         gdouble right,
                                                         gdouble bottom,
                                                         gdouble left);

Convenient function to set all the paddings at once.

canvas :

an AdgCanvas

top :

top padding, in global space

right :

right padding, in global space

bottom :

bottom padding, in global space

left :

left padding, in global space

Since 1.0


adg_canvas_set_paper ()

void                adg_canvas_set_paper                (AdgCanvas *canvas,
                                                         const gchar *paper_name,
                                                         GtkPageOrientation orientation);

A convenient function to set the size of canvas using a paper_name and an orientation value. This should be a PWG 5101.1-2002 paper name and it will be passed as is to gtk_paper_size_new(), so use any valid name accepted by that function.

To reset this size, you could use adg_canvas_set_size() with a NULL size: in this way the size will match the boundary boxes of the entities contained by the canvas.

Furthermore, the margins will be set to their default values, that is the margins returned by the GtkPaperSize API. If you want to use your own margins on a named paper size, set them after the call to this function.

canvas :

an AdgCanvas

paper_name :

a paper name

orientation :

the page orientation

Since 1.0


adg_canvas_set_page_setup ()

void                adg_canvas_set_page_setup           (AdgCanvas *canvas,
                                                         GtkPageSetup *page_setup);

A convenient function to setup the page of canvas so it can also be subsequentially used for printing. It is allowed to pass NULL for page_setup to unset the setup data from canvas.

A reference to page_setup is added, so there is no need to keep alive this object outside this function. The internal page_setup pointer is stored in the associative key _adg_page_setup and can be retrieved at any time with adg_canvas_get_page_setup().

The size and margins provided by page_setup are used to set the size and margins of canvas much in the same way as what adg_canvas_set_paper() does. This means if you set a page and then unset it, the canvas will retain size and margins of the original page although page_setup will not be used for printing. You must unset the size with adg_canvas_set_size() with a NULL size.

1
2
3
4
5
6
7
8
9
// By default, canvas does not have an explicit size
adg_canvas_set_page_setup(canvas, a4);
// Here canvas has the size and margins specified by a4
adg_canvas_set_page_setup(canvas, NULL);
// Now the only difference is that canvas is no more bound
// to the a4 page setup, so the following will return NULL:
page_setup = adg_canvas_get_page_setup(canvas);
// To restore the original status and have an autocomputed size:
adg_canvas_set_size(canvas, NULL);

canvas :

an AdgCanvas

page_setup :

the page setup. [allow-none][transfer none]

Since 1.0


adg_canvas_get_page_setup ()

GtkPageSetup *      adg_canvas_get_page_setup           (AdgCanvas *canvas);

If adg_canvas_set_page_setup() is called, a GtkPageSetup object is created and bound to canvas. This metho returns a pointer to that internal object or NULL if adg_canvas_set_page_setup() has not been called before.

canvas :

an AdgCanvas

Returns :

the GtkPageSetup with size and margins of canvas of NULL on no setup found or errors. [allow-none][transfer none]

Since 1.0

Property Details

The "background-dress" property

  "background-dress"         AdgDress              : Read / Write

The color dress to use for the canvas background.


The "bottom-margin" property

  "bottom-margin"            gdouble               : Read / Write

The margin (in global space) to leave empty below the frame.

Default value: 15


The "bottom-padding" property

  "bottom-padding"           gdouble               : Read / Write

The padding (in global space) to leave empty below between the drawing and the frame.

Default value: 15


The "frame-dress" property

  "frame-dress"              AdgDress              : Read / Write

Line dress to use while drawing the frame around the canvas.


The "has-frame" property

  "has-frame"                gboolean              : Read / Write

If enabled, a frame using the frame dress will be drawn around the canvas extents, taking into account the margins.

Default value: TRUE


The "left-margin" property

  "left-margin"              gdouble               : Read / Write

The margin (in global space) to leave empty at the left of the frame.

Default value: 15


The "left-padding" property

  "left-padding"             gdouble               : Read / Write

The padding (in global space) to leave empty at the left between the drawing and the frame.

Default value: 15


The "right-margin" property

  "right-margin"             gdouble               : Read / Write

The margin (in global space) to leave empty at the right of the frame.

Default value: 15


The "right-padding" property

  "right-padding"            gdouble               : Read / Write

The padding (in global space) to leave empty at the right between the drawing and the frame.

Default value: 15


The "scales" property

  "scales"                   GStrv                 : Read / Write

List of scales to be tested while autoscaling the drawing.


The "size" property

  "size"                     CpmlPair*             : Read / Write

The size set on this canvas: use 0 to have an automatic dimension based on the canvas extents.


The "title-block" property

  "title-block"              AdgTitleBlock*        : Read / Write

The title block to assign to this canvas.


The "top-margin" property

  "top-margin"               gdouble               : Read / Write

The margin (in global space) to leave above the frame.

Default value: 15


The "top-padding" property

  "top-padding"              gdouble               : Read / Write

The padding (in global space) to leave empty above between the drawing and the frame.

Default value: 15