![]() |
![]() |
![]() |
adg-1 reference manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties |
#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
);
"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
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.
struct AdgCanvas;
All fields are private and should not be used directly. Use its public methods instead.
Since 1.0
AdgCanvas * adg_canvas_new (void
);
Creates a new empty canvas object.
Returns : |
the newly created canvas. [transfer full] |
Since 1.0
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.
|
an AdgCanvas |
|
the new size for the canvas. [transfer none] |
Since 1.0
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.
|
an AdgCanvas |
|
the new width of the canvas or 0 to reset |
|
the new height of the canvas or 0 to reset |
Since 1.0
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.
|
an AdgCanvas |
Returns : |
the explicit size set on this canvas or NULL on errors. [transfer none]
|
Since 1.0
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.
|
an AdgCanvas |
|
NULL terminated list of strings |
Since 1.0
void adg_canvas_set_scales_valist (AdgCanvas *canvas
,va_list var_args
);
Vararg variant of adg_canvas_set_scales()
.
|
an AdgCanvas |
|
NULL terminated list of strings |
Since 1.0
void adg_canvas_set_scales_array (AdgCanvas *canvas
,gchar **scales
);
Array variant of adg_canvas_set_scales()
.
Rename to: adg_canvas_set_scales
|
an AdgCanvas |
|
NULL terminated array of scales. [array zero-terminated=1][allow-none]
|
Since 1.0
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.
|
an AdgCanvas |
Returns : |
the NULL terminated list of valid scales. [element-type utf8][transfer none]
|
Since 1.0
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.
|
an AdgCanvas |
Since 1.0
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.
Since 1.0
AdgDress adg_canvas_get_background_dress (AdgCanvas *canvas
);
Gets the background dress to be used in rendering canvas
.
|
an AdgCanvas |
Returns : |
the current background dress. |
Since 1.0
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.
Since 1.0
AdgDress adg_canvas_get_frame_dress (AdgCanvas *canvas
);
Gets the frame dress to be used in rendering the border of canvas
.
|
an AdgCanvas |
Returns : |
the current frame dress. |
Since 1.0
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
.
|
an AdgCanvas |
|
a title block. [transfer full] |
Since 1.0
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.
|
an AdgCanvas |
Returns : |
the title block object or NULL . [transfer none]
|
Since 1.0
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.
|
an AdgCanvas |
|
the new margin, in global space |
Since 1.0
gdouble adg_canvas_get_top_margin (AdgCanvas *canvas
);
Gets the top margin (in global space) of canvas
.
|
an AdgCanvas |
Returns : |
the requested margin or 0 on error. |
Since 1.0
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.
|
an AdgCanvas |
|
the new margin, in global space |
Since 1.0
gdouble adg_canvas_get_right_margin (AdgCanvas *canvas
);
Gets the right margin (in global space) of canvas
.
|
an AdgCanvas |
Returns : |
the requested margin or 0 on error. |
Since 1.0
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.
|
an AdgCanvas |
|
the new margin, in global space |
Since 1.0
gdouble adg_canvas_get_bottom_margin (AdgCanvas *canvas
);
Gets the bottom margin (in global space) of canvas
.
|
an AdgCanvas |
Returns : |
the requested margin or 0 on error. |
Since 1.0
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.
|
an AdgCanvas |
|
the new margin, in global space |
Since 1.0
gdouble adg_canvas_get_left_margin (AdgCanvas *canvas
);
Gets the left margin (in global space) of canvas
.
|
an AdgCanvas |
Returns : |
the requested margin or 0 on error. |
Since 1.0
void adg_canvas_set_margins (AdgCanvas *canvas
,gdouble top
,gdouble right
,gdouble bottom
,gdouble left
);
Convenient function to set all the margins at once.
|
an AdgCanvas |
|
top margin, in global space |
|
right margin, in global space |
|
bottom margin, in global space |
|
left margin, in global space |
Since 1.0
void adg_canvas_apply_margins (AdgCanvas *canvas
,CpmlExtents *extents
);
A convenient function to apply the margins of canvas
to the
arbitrary CpmlExtents struct extents
.
|
an AdgCanvas |
|
where apply the margins |
Since 1.0
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.
|
an AdgCanvas |
|
the new flag status |
Since 1.0
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
).
|
an AdgCanvas |
Returns : |
the current status of the frame flag. |
Since 1.0
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.
|
an AdgCanvas |
|
the new padding, in global space |
Since 1.0
gdouble adg_canvas_get_top_padding (AdgCanvas *canvas
);
Gets the top padding (in global space) of canvas
.
|
an AdgCanvas |
Returns : |
the requested padding or 0 on error. |
Since 1.0
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.
|
an AdgCanvas |
|
the new padding, in global space |
Since 1.0
gdouble adg_canvas_get_right_padding (AdgCanvas *canvas
);
Gets the right padding (in global space) of canvas
.
|
an AdgCanvas |
Returns : |
the requested padding or 0 on error. |
Since 1.0
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.
|
an AdgCanvas |
|
the new padding, in global space |
Since 1.0
gdouble adg_canvas_get_bottom_padding (AdgCanvas *canvas
);
Gets the bottom padding (in global space) of canvas
.
|
an AdgCanvas |
Returns : |
the requested padding or 0 on error. |
Since 1.0
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.
|
an AdgCanvas |
|
the new padding, in global space |
Since 1.0
gdouble adg_canvas_get_left_padding (AdgCanvas *canvas
);
Gets the left padding (in global space) of canvas
.
|
an AdgCanvas |
Returns : |
the requested padding or 0 on error. |
Since 1.0
void adg_canvas_set_paddings (AdgCanvas *canvas
,gdouble top
,gdouble right
,gdouble bottom
,gdouble left
);
Convenient function to set all the paddings at once.
|
an AdgCanvas |
|
top padding, in global space |
|
right padding, in global space |
|
bottom padding, in global space |
|
left padding, in global space |
Since 1.0
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.
|
an AdgCanvas |
|
a paper name |
|
the page orientation |
Since 1.0
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); |
|
an AdgCanvas |
|
the page setup. [allow-none][transfer none] |
Since 1.0
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.
|
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
"background-dress"
property"background-dress" AdgDress : Read / Write
The color dress to use for the canvas background.
"bottom-margin"
property "bottom-margin" gdouble : Read / Write
The margin (in global space) to leave empty below the frame.
Default value: 15
"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
"frame-dress"
property"frame-dress" AdgDress : Read / Write
Line dress to use while drawing the frame around the canvas.
"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
"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
"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
"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
"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
"scales"
property "scales" GStrv : Read / Write
List of scales to be tested while autoscaling the drawing.
"size"
property"size" CpmlPair* : Read / Write
The size set on this canvas: use 0 to have an automatic dimension based on the canvas extents.
"title-block"
property"title-block" AdgTitleBlock* : Read / Write
The title block to assign to this canvas.
"top-margin"
property "top-margin" gdouble : Read / Write
The margin (in global space) to leave above the frame.
Default value: 15