DiaShape

Name

DiaShape -- Shapes define the look of an object.

Synopsis



#define     DIA_SHAPE                       (sh)
enum        DiaShapeType;
enum        DiaShapeVisibility;
enum        DiaJoinStyle;
enum        DiaCapStyle;
enum        DiaFillStyle;
struct      DiaDashStyle;
struct      DiaShape;
GType       dia_shape_get_type              (DiaShape *shape);
DiaShape*   dia_shape_new                   (DiaShapeType type);
void        dia_shape_free                  (DiaShape *shape);
void        dia_shape_request_update        (DiaShape *shape);
void        dia_shape_set_color             (DiaShape *shape,
                                             DiaColor color);
void        dia_shape_set_visibility        (DiaShape *shape,
                                             DiaShapeVisibility vis);
#define     dia_shape_get_visibility        (shape)
gboolean    dia_shape_get_bounds            (DiaShape *shape,
                                             DiaRectangle *bb);
struct      DiaShapePath;
#define     dia_shape_path_new              ()
void        dia_shape_line                  (DiaShape *shape,
                                             DiaPoint *start,
                                             DiaPoint *end);
void        dia_shape_rectangle             (DiaShape *shape,
                                             DiaPoint *upper_left,
                                             DiaPoint *lower_right);
void        dia_shape_polyline              (DiaShape *shape,
                                             guint n_points,
                                             DiaPoint *points);
void        dia_shape_polygon               (DiaShape *shape,
                                             guint n_points,
                                             DiaPoint *points);
void        dia_shape_path_set_line_width   (DiaShape *shape,
                                             gdouble line_width);
void        dia_shape_path_set_join         (DiaShape *shape,
                                             DiaJoinStyle join);
void        dia_shape_path_set_cap          (DiaShape *shape,
                                             DiaCapStyle cap);
void        dia_shape_path_set_fill         (DiaShape *shape,
                                             DiaFillStyle fill);
void        dia_shape_path_set_fill_color   (DiaShape *shape,
                                             DiaColor fill_color);
void        dia_shape_path_set_dash         (DiaShape *shape,
                                             gdouble offset,
                                             guint n_dash,
                                             gdouble *dash);
void        dia_shape_path_set_cyclic       (DiaShape *shape,
                                             gboolean cyclic);
void        dia_shape_path_set_clipping     (DiaShape *shape,
                                             gboolean clipping);
gboolean    dia_shape_path_is_clip_path     (DiaShape *shape);
struct      DiaShapeBezier;
#define     dia_shape_bezier_new            ()
void        dia_shape_bezier                (DiaShape *shape,
                                             DiaPoint *start,
                                             guint n_points,
                                             DiaPoint *points);
void        dia_shape_bezier_set_line_width (DiaShape *shape,
                                             gdouble line_width);
void        dia_shape_bezier_set_join       (DiaShape *shape,
                                             DiaJoinStyle join);
void        dia_shape_bezier_set_cap        (DiaShape *shape,
                                             DiaCapStyle cap);
void        dia_shape_bezier_set_fill       (DiaShape *shape,
                                             DiaFillStyle fill);
void        dia_shape_bezier_set_fill_color (DiaShape *shape,
                                             DiaColor fill_color);
void        dia_shape_bezier_set_dash       (DiaShape *shape,
                                             gdouble offset,
                                             guint n_dash,
                                             gdouble *dash);
void        dia_shape_bezier_set_cyclic     (DiaShape *shape,
                                             gboolean cyclic);
void        dia_shape_bezier_set_clipping   (DiaShape *shape,
                                             gboolean clipping);
gboolean    dia_shape_bezier_is_clip_path   (DiaShape *shape);
struct      DiaShapeEllipse;
#define     dia_shape_ellipse_new           ()
void        dia_shape_ellipse               (DiaShape *shape,
                                             DiaPoint *center,
                                             gdouble width,
                                             gdouble height);
void        dia_shape_arc                   (DiaShape *shape,
                                             DiaPoint *begin,
                                             DiaPoint *middle,
                                             DiaPoint *end);
void        dia_shape_ellipse_set_line_width
                                            (DiaShape *shape,
                                             gdouble line_width);
void        dia_shape_ellipse_set_fill      (DiaShape *shape,
                                             DiaFillStyle fill);
void        dia_shape_ellipse_set_fill_color
                                            (DiaShape *shape,
                                             DiaColor fill_color);
void        dia_shape_ellipse_set_dash      (DiaShape *shape,
                                             gdouble offset,
                                             guint n_dash,
                                             gdouble *dash);
void        dia_shape_ellipse_set_clipping  (DiaShape *shape,
                                             gboolean clipping);
gboolean    dia_shape_ellipse_is_clip_path  (DiaShape *shape);
struct      DiaShapeImage;
#define     dia_shape_image_new             ()
void        dia_shape_image                 (DiaShape *shape,
                                             GdkPixbuf *image);
void        dia_shape_image_set_pos         (DiaShape *shape,
                                             DiaPoint *pos);
void        dia_shape_image_set_affine      (DiaShape *shape,
                                             gdouble affine[6]);
struct      DiaShapeText;
#define     dia_shape_text_new              ()
void        dia_shape_text                  (DiaShape *shape,
                                             PangoFontDescription *font_desc,
                                             const gchar *text);
void        dia_shape_text_set_text         (DiaShape *shape,
                                             const gchar *text);
void        dia_shape_text_set_static_text  (DiaShape *shape,
                                             const gchar *text);
void        dia_shape_text_set_font_description
                                            (DiaShape *shape,
                                             PangoFontDescription *font_desc);
void        dia_shape_text_set_pos          (DiaShape *shape,
                                             DiaPoint *pos);
void        dia_shape_text_set_text_width   (DiaShape *shape,
                                             gint width);
void        dia_shape_text_set_max_width    (DiaShape *shape,
                                             gint width);
void        dia_shape_text_set_max_height   (DiaShape *shape,
                                             gint height);
void        dia_shape_text_set_justify      (DiaShape *shape,
                                             gboolean justify);
void        dia_shape_text_set_alignment    (DiaShape *shape,
                                             PangoAlignment alignment);
void        dia_shape_text_set_wrap_mode    (DiaShape *shape,
                                             PangoWrapMode wrap_mode);
void        dia_shape_text_set_line_spacing (DiaShape *shape,
                                             gint line_spacing);
void        dia_shape_text_set_affine       (DiaShape *shape,
                                             gdouble affine[6]);
void        dia_shape_text_set_cursor       (DiaShape *shape,
                                             gint cursor);
gboolean    dia_shape_text_cursor_from_pos  (DiaShape *shape,
                                             DiaPoint *pos,
                                             gint *cursor);
PangoLayout* dia_shape_text_to_pango_layout (DiaShape *shape,
                                             gboolean fill);
void        dia_shape_text_fill_pango_layout
                                            (DiaShape *shape,
                                             PangoLayout *layout,
                                             gdouble scale);
struct      DiaShapeClip;
void        dia_shape_clip                  (DiaShape *shape,
                                             gdouble left,
                                             gdouble top,
                                             gdouble right,
                                             gdouble bottom);


Description

Shapes are an interesting part of DiaCanvas2. A shape is an abstract definition of some sort of figure that has to be drawn on the canvas. Currently five types of shapes are supported: Line like shapes (DiaShapePath) like lines, polygons and rectangles, ellipses (DiaShapeEllipse), text (DiaShapeText) and bitmap images (DiaShapeImage).

All shapes are renderer independent. They can be rendered by a canvas view (with or without anti-alias support) or a renderer can be created that creates some sort of file (like PostScript or PNG).

A shape can be restricted on their visibility. You can create shapes and allow them only to be drawn if the item they belong to is selected (or focused). This will allow you to create helper lines and such.

There is one special kind of shape: DiaShapeClip. This shape is not really a shape: it defines a clipping rectangle for all shapes that have to be drawn.

Details

DIA_SHAPE()

#define DIA_SHAPE(sh) ((DiaShape*)(sh))

sh :


enum DiaShapeType

typedef enum
{
	DIA_SHAPE_NONE,
	DIA_SHAPE_PATH, /* Line, polygon, rectangle */
	DIA_SHAPE_BEZIER,
	DIA_SHAPE_ELLIPSE, /* ellipse, circle */
	DIA_SHAPE_TEXT,
	DIA_SHAPE_IMAGE,
	DIA_SHAPE_WIDGET, /* Only widgets w/ a model/view architecture? */
	DIA_SHAPE_CLIP /* Set a clip path for the following shapes. */
} DiaShapeType;


enum DiaShapeVisibility

typedef enum
{
	DIA_SHAPE_HIDDEN,
	DIA_SHAPE_VISIBLE,
	DIA_SHAPE_VISIBLE_IF_SELECTED,
	DIA_SHAPE_VISIBLE_IF_FOCUSED,
	DIA_SHAPE_VISIBLE_IF_GRABBED
} DiaShapeVisibility;

Change the visibility of a shape. Since DiaCanvasItem's are stateless, we can not create helper-lines and such. By changing the visibility, you can only make shapes visible if a view item is in a specific state.


enum DiaJoinStyle

typedef enum
{
	DIA_JOIN_MITER,
	DIA_JOIN_ROUND,
	DIA_JOIN_BEVEL
} DiaJoinStyle;


enum DiaCapStyle

typedef enum
{
	DIA_CAP_BUTT,
	DIA_CAP_ROUND,
	DIA_CAP_SQUARE
} DiaCapStyle;


enum DiaFillStyle

typedef enum
{
	DIA_FILL_NONE,
	DIA_FILL_SOLID
} DiaFillStyle;


struct DiaDashStyle

struct DiaDashStyle
{
	guint n_dash;
	gdouble dash[1];
};


struct DiaShape

struct DiaShape
{
	DiaShapeType type;

	guint visibility: 4;
	guint update_cnt: 28;

	DiaColor color;

	/* View specific information can be attached here */
	GList *view_info;
};

This is a collection of properties that count for all shapes. All shapes are "inherited" from DiaShape.


dia_shape_get_type ()

GType       dia_shape_get_type              (DiaShape *shape);

shape :

Returns :


dia_shape_new ()

DiaShape*   dia_shape_new                   (DiaShapeType type);

type :

Returns :


dia_shape_free ()

void        dia_shape_free                  (DiaShape *shape);

shape :


dia_shape_request_update ()

void        dia_shape_request_update        (DiaShape *shape);

shape :


dia_shape_set_color ()

void        dia_shape_set_color             (DiaShape *shape,
                                             DiaColor color);

shape :

color :


dia_shape_set_visibility ()

void        dia_shape_set_visibility        (DiaShape *shape,
                                             DiaShapeVisibility vis);

shape :

vis :


dia_shape_get_visibility()

#define     dia_shape_get_visibility(shape)

shape :


dia_shape_get_bounds ()

gboolean    dia_shape_get_bounds            (DiaShape *shape,
                                             DiaRectangle *bb);

shape :

bb :

Returns :


struct DiaShapePath

struct DiaShapePath
{
	DiaShape shape;
  
	ArtVpath *vpath;
  
	DiaColor  fill_color;

	guint     fill: 8;
	guint     join: 8;
	guint     cap: 8;
	guint     cyclic: 1;
	guint     clipping: 1;

	gdouble   line_width;

	ArtVpathDash dash;
};

Path like shapes are lines, polygons, rectangles, etc. If the shape is cyclic, you can set the fill style to DIA_FILL_SOLID and use fill_color to specify a color for the content.

Note that one shape can only represent a line, or a surface (e.g. a filled rectangle).


dia_shape_path_new()

#define dia_shape_path_new() dia_shape_new(DIA_SHAPE_PATH)


dia_shape_line ()

void        dia_shape_line                  (DiaShape *shape,
                                             DiaPoint *start,
                                             DiaPoint *end);

shape :

start :

end :


dia_shape_rectangle ()

void        dia_shape_rectangle             (DiaShape *shape,
                                             DiaPoint *upper_left,
                                             DiaPoint *lower_right);

shape :

upper_left :

lower_right :


dia_shape_polyline ()

void        dia_shape_polyline              (DiaShape *shape,
                                             guint n_points,
                                             DiaPoint *points);

Create a line with n_points elements. points is an array of n_points DiaPoint elements.

shape :

n_points :

points :


dia_shape_polygon ()

void        dia_shape_polygon               (DiaShape *shape,
                                             guint n_points,
                                             DiaPoint *points);

Like dia_shape_polyline(), but in this case the line is closed.

shape :

n_points :

points :


dia_shape_path_set_line_width ()

void        dia_shape_path_set_line_width   (DiaShape *shape,
                                             gdouble line_width);

Set the line width for a path like shape.

shape :

line_width :


dia_shape_path_set_join ()

void        dia_shape_path_set_join         (DiaShape *shape,
                                             DiaJoinStyle join);

Set the join style for a line.

shape :

join :


dia_shape_path_set_cap ()

void        dia_shape_path_set_cap          (DiaShape *shape,
                                             DiaCapStyle cap);

The the line end (cap) style for a line, thsi property is not very useful if a path is set to cyclic.

shape :

cap :


dia_shape_path_set_fill ()

void        dia_shape_path_set_fill         (DiaShape *shape,
                                             DiaFillStyle fill);

Set the fill style for the path.

shape :

fill :


dia_shape_path_set_fill_color ()

void        dia_shape_path_set_fill_color   (DiaShape *shape,
                                             DiaColor fill_color);

Set the color that is to be used if the shape is to be filled. The fill style can be set with dia_shape_path_set_fill().

shape :

fill_color :


dia_shape_path_set_dash ()

void        dia_shape_path_set_dash         (DiaShape *shape,
                                             gdouble offset,
                                             guint n_dash,
                                             gdouble *dash);

Set the dash style for the line.

shape :

offset :

n_dash :

dash :


dia_shape_path_set_cyclic ()

void        dia_shape_path_set_cyclic       (DiaShape *shape,
                                             gboolean cyclic);

Set the path to cyclic. Cyclic paths are closed.

shape :

cyclic :


dia_shape_path_set_clipping ()

void        dia_shape_path_set_clipping     (DiaShape *shape,
                                             gboolean clipping);

If the clipping attribute is set, the shape will be used as a clipping path Note that clipping paths can also contain a path including filling.

shape :

clipping :


dia_shape_path_is_clip_path ()

gboolean    dia_shape_path_is_clip_path     (DiaShape *shape);

shape :

Returns :

TRUE if the path is indeed a clip path.


struct DiaShapeBezier

struct DiaShapeBezier
{
	DiaShape shape;
  
	ArtBpath *bpath;
  
	DiaColor  fill_color;

	guint     fill: 8;
	guint     join: 8;
	guint     cap: 8;
	guint     cyclic: 1;
	guint     clipping: 1;

	gdouble   line_width;

	ArtVpathDash dash;
};

Bezier path.


dia_shape_bezier_new()

#define dia_shape_bezier_new() dia_shape_new(DIA_SHAPE_BEZIER)


dia_shape_bezier ()

void        dia_shape_bezier                (DiaShape *shape,
                                             DiaPoint *start,
                                             guint n_points,
                                             DiaPoint *points);

shape :

start :

starting point for the bezier curve.

n_points :

the number of points, should be a multitude of 3.

points :

Array of n_points points


dia_shape_bezier_set_line_width ()

void        dia_shape_bezier_set_line_width (DiaShape *shape,
                                             gdouble line_width);

shape :

line_width :


dia_shape_bezier_set_join ()

void        dia_shape_bezier_set_join       (DiaShape *shape,
                                             DiaJoinStyle join);

shape :

join :


dia_shape_bezier_set_cap ()

void        dia_shape_bezier_set_cap        (DiaShape *shape,
                                             DiaCapStyle cap);

shape :

cap :


dia_shape_bezier_set_fill ()

void        dia_shape_bezier_set_fill       (DiaShape *shape,
                                             DiaFillStyle fill);

shape :

fill :


dia_shape_bezier_set_fill_color ()

void        dia_shape_bezier_set_fill_color (DiaShape *shape,
                                             DiaColor fill_color);

shape :

fill_color :


dia_shape_bezier_set_dash ()

void        dia_shape_bezier_set_dash       (DiaShape *shape,
                                             gdouble offset,
                                             guint n_dash,
                                             gdouble *dash);

shape :

offset :

n_dash :

dash :


dia_shape_bezier_set_cyclic ()

void        dia_shape_bezier_set_cyclic     (DiaShape *shape,
                                             gboolean cyclic);

shape :

cyclic :


dia_shape_bezier_set_clipping ()

void        dia_shape_bezier_set_clipping   (DiaShape *shape,
                                             gboolean clipping);

shape :

clipping :


dia_shape_bezier_is_clip_path ()

gboolean    dia_shape_bezier_is_clip_path   (DiaShape *shape);

shape :

Returns :


struct DiaShapeEllipse

struct DiaShapeEllipse
{
	DiaShape shape;
  
	DiaPoint  center;
	gdouble   width, height;
	
	DiaColor  fill_color;

	guint     fill: 8;
	guint     clipping: 1;

	gdouble   line_width;

	ArtVpathDash dash;
};

Shape for ellipses and circles. This might be extended in the near future to arc (curve) like shapes.


dia_shape_ellipse_new()

#define dia_shape_ellipse_new() dia_shape_new(DIA_SHAPE_ELLIPSE)


dia_shape_ellipse ()

void        dia_shape_ellipse               (DiaShape *shape,
                                             DiaPoint *center,
                                             gdouble width,
                                             gdouble height);

shape :

center :

width :

height :


dia_shape_arc ()

void        dia_shape_arc                   (DiaShape *shape,
                                             DiaPoint *begin,
                                             DiaPoint *middle,
                                             DiaPoint *end);

Not implemented yet.

shape :

begin :

middle :

end :


dia_shape_ellipse_set_line_width ()

void        dia_shape_ellipse_set_line_width
                                            (DiaShape *shape,
                                             gdouble line_width);

shape :

line_width :


dia_shape_ellipse_set_fill ()

void        dia_shape_ellipse_set_fill      (DiaShape *shape,
                                             DiaFillStyle fill);

shape :

fill :


dia_shape_ellipse_set_fill_color ()

void        dia_shape_ellipse_set_fill_color
                                            (DiaShape *shape,
                                             DiaColor fill_color);

shape :

fill_color :


dia_shape_ellipse_set_dash ()

void        dia_shape_ellipse_set_dash      (DiaShape *shape,
                                             gdouble offset,
                                             guint n_dash,
                                             gdouble *dash);

shape :

offset :

n_dash :

dash :


dia_shape_ellipse_set_clipping ()

void        dia_shape_ellipse_set_clipping  (DiaShape *shape,
                                             gboolean clipping);

shape :

clipping :


dia_shape_ellipse_is_clip_path ()

gboolean    dia_shape_ellipse_is_clip_path  (DiaShape *shape);

shape :

Returns :


struct DiaShapeImage

struct DiaShapeImage
{
	DiaShape shape;
  
	GdkPixbuf *pixbuf;

	gdouble affine[6];
};

A DiaShapeImage contains an image. The affine matrix can be used to change the offset. Rotating and shearing can result in ugly results.


dia_shape_image_new()

#define dia_shape_image_new() dia_shape_new(DIA_SHAPE_IMAGE)


dia_shape_image ()

void        dia_shape_image                 (DiaShape *shape,
                                             GdkPixbuf *image);

shape :

image :


dia_shape_image_set_pos ()

void        dia_shape_image_set_pos         (DiaShape *shape,
                                             DiaPoint *pos);

shape :

pos :


dia_shape_image_set_affine ()

void        dia_shape_image_set_affine      (DiaShape *shape,
                                             gdouble affine[6]);

shape :

affine :


struct DiaShapeText

struct DiaShapeText
{
	DiaShape shape;
  
	PangoFontDescription *font_desc;
	gchar *text;

	gboolean need_free;
	gboolean justify;
	gboolean markup;
	PangoWrapMode wrap_mode;
	gint line_spacing;
	PangoAlignment alignment;

	gint max_width, max_height;
	gint text_width;
	gdouble affine[6];

	gint cursor;
};

Text is described by a font (font_desc) and a text string. The text can be clipped by setting maximum values for width and height. The text_width property can be used to determine the width of the text block (text can be word-wrapped at text_width).

A special part of a DiaShapeText object is its cursor position. A DiaCanvasItem can specify a cursor position in the text. The cursor will only be drawn if the view has the focus and if the object containing the shape has the focus. As a result there will only be one cursor visible in all DiaCanvasViews.


dia_shape_text_new()

#define dia_shape_text_new() dia_shape_new(DIA_SHAPE_TEXT)


dia_shape_text ()

void        dia_shape_text                  (DiaShape *shape,
                                             PangoFontDescription *font_desc,
                                             const gchar *text);

shape :

font_desc :

text :


dia_shape_text_set_text ()

void        dia_shape_text_set_text         (DiaShape *shape,
                                             const gchar *text);

shape :

text :


dia_shape_text_set_static_text ()

void        dia_shape_text_set_static_text  (DiaShape *shape,
                                             const gchar *text);

shape :

text :


dia_shape_text_set_font_description ()

void        dia_shape_text_set_font_description
                                            (DiaShape *shape,
                                             PangoFontDescription *font_desc);

shape :

font_desc :


dia_shape_text_set_pos ()

void        dia_shape_text_set_pos          (DiaShape *shape,
                                             DiaPoint *pos);

shape :

pos :


dia_shape_text_set_text_width ()

void        dia_shape_text_set_text_width   (DiaShape *shape,
                                             gint width);

Set the width of the text. Text will be word wrapped if that option is enabled and the text is actually longer than the text_width.

shape :

width :


dia_shape_text_set_max_width ()

void        dia_shape_text_set_max_width    (DiaShape *shape,
                                             gint width);

Set the max width of the text box.

shape :

width :


dia_shape_text_set_max_height ()

void        dia_shape_text_set_max_height   (DiaShape *shape,
                                             gint height);

Set the height of the text box.

shape :

height :


dia_shape_text_set_justify ()

void        dia_shape_text_set_justify      (DiaShape *shape,
                                             gboolean justify);

shape :

justify :


dia_shape_text_set_alignment ()

void        dia_shape_text_set_alignment    (DiaShape *shape,
                                             PangoAlignment alignment);

Set the text alignment for a shape (left, right, center, justified).

shape :

alignment :


dia_shape_text_set_wrap_mode ()

void        dia_shape_text_set_wrap_mode    (DiaShape *shape,
                                             PangoWrapMode wrap_mode);

Set the wrapping mode for the text shape.

shape :

wrap_mode :


dia_shape_text_set_line_spacing ()

void        dia_shape_text_set_line_spacing (DiaShape *shape,
                                             gint line_spacing);

shape :

line_spacing :


dia_shape_text_set_affine ()

void        dia_shape_text_set_affine       (DiaShape *shape,
                                             gdouble affine[6]);

shape :

affine :


dia_shape_text_set_cursor ()

void        dia_shape_text_set_cursor       (DiaShape *shape,
                                             gint cursor);

Set the cursor in a text to a certain position. The cursor should be shown once the item the shape belongs to gets the focus. Use -1 to hide the cursor.

shape :

cursor :


dia_shape_text_cursor_from_pos ()

gboolean    dia_shape_text_cursor_from_pos  (DiaShape *shape,
                                             DiaPoint *pos,
                                             gint *cursor);

Find the cursor position belonging to the position pos.

shape :

A DiaShapeText

pos :

cursor position, in item relative coordinates.

cursor :

Set the cursor.

Returns :


dia_shape_text_to_pango_layout ()

PangoLayout* dia_shape_text_to_pango_layout (DiaShape *shape,
                                             gboolean fill);

Create a PangoLayout based on the information of the shape. The maximum width and height, nor the affine transformation are added to the layout.

shape :

fill :

Add information of teh shape to the PangoLayout.

Returns :

A new PangoLayout.


dia_shape_text_fill_pango_layout ()

void        dia_shape_text_fill_pango_layout
                                            (DiaShape *shape,
                                             PangoLayout *layout,
                                             gdouble scale);

Create a PangoLayout object from a DiaShapeText. Use dia_shape_text_pretty_fill_pango_layout() if you want the lines to stay the same when the text is scaled.

shape :

layout :

scale :


struct DiaShapeClip

struct DiaShapeClip
{
	DiaShape shape;
	
	ArtDRect clip;
};

This shape is not really a shape. It can be set to create a clipping rectangle: all shapes have to be within the clipping rectangle.


dia_shape_clip ()

void        dia_shape_clip                  (DiaShape *shape,
                                             gdouble left,
                                             gdouble top,
                                             gdouble right,
                                             gdouble bottom);

shape :

left :

top :

right :

bottom :

See Also

DiaCanvasItem