AdgCanvas

AdgCanvas — The drawing container

Synopsis

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

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
  "size"                     AdgPair*              : 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_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_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. [transfer none]

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_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_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. [transfer none]

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_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_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_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_get_size ()

const AdgPair *     adg_canvas_get_size                 (AdgCanvas *canvas);

Gets the specific size set on canvas. The x and/or y components of the returned AdgPair 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.

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_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_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_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_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_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_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_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_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_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_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_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_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_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 page_setup pointer is stored in the associative key _adg_page_setup and can be retrieved at any time with:

page_setup = g_object_get_data(G_OBJECT(canvas), "_adg_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.

// 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 = g_object_get_data(G_OBJECT(canvas), "_adg_page_setup");
// To restore the original status and have an autocomputed size:
adg_canvas_set_size(canvas, NULL);

canvas :

an AdgCanvas

page_setup :

the page setup

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_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_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_set_size ()

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

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

canvas :

an AdgCanvas

size :

the new size for the canvas

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_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

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_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_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

Property Details

The "background-dress" property

  "background-dress"         AdgDress              : Read / Write

The color dress to use for the canvas background.

Allowed values: [G_MAXINT,G_MININT]

Default value: 0


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.

Allowed values: [G_MAXINT,G_MININT]

Default value: 0


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 "size" property

  "size"                     AdgPair*              : 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