PgmDrawable

PgmDrawable — A base class used for embedding media types.

Synopsis


#include <pgm/pgm.h>

enum                PgmDrawableLayer;
enum                PgmDrawableProperty;
                    PgmDrawable;
                    PgmDrawableClass;
PgmError            pgm_drawable_hide                   (PgmDrawable *drawable);
PgmError            pgm_drawable_show                   (PgmDrawable *drawable);
PgmError            pgm_drawable_is_visible             (PgmDrawable *drawable,
                                                         gboolean *visible);
PgmError            pgm_drawable_set_size               (PgmDrawable *drawable,
                                                         gfloat width,
                                                         gfloat height);
PgmError            pgm_drawable_get_size               (PgmDrawable *drawable,
                                                         gfloat *width,
                                                         gfloat *height);
PgmError            pgm_drawable_set_position           (PgmDrawable *drawable,
                                                         gfloat x,
                                                         gfloat y,
                                                         gfloat z);
PgmError            pgm_drawable_get_position           (PgmDrawable *drawable,
                                                         gfloat *x,
                                                         gfloat *y,
                                                         gfloat *z);
PgmError            pgm_drawable_set_rotation_x         (PgmDrawable *drawable,
                                                         gfloat angle);
PgmError            pgm_drawable_get_rotation_x         (PgmDrawable *drawable,
                                                         gfloat *angle);
PgmError            pgm_drawable_set_rotation_y         (PgmDrawable *drawable,
                                                         gfloat angle);
PgmError            pgm_drawable_get_rotation_y         (PgmDrawable *drawable,
                                                         gfloat *angle);
PgmError            pgm_drawable_set_rotation_z         (PgmDrawable *drawable,
                                                         gfloat angle);
PgmError            pgm_drawable_get_rotation_z         (PgmDrawable *drawable,
                                                         gfloat *angle);
PgmError            pgm_drawable_set_scale              (PgmDrawable *drawable,
                                                         gfloat scale);
PgmError            pgm_drawable_get_scale              (PgmDrawable *drawable,
                                                         gfloat *scale);
PgmError            pgm_drawable_set_fg_color           (PgmDrawable *drawable,
                                                         guchar r,
                                                         guchar g,
                                                         guchar b,
                                                         guchar a);
PgmError            pgm_drawable_get_fg_color           (PgmDrawable *drawable,
                                                         guchar *r,
                                                         guchar *g,
                                                         guchar *b,
                                                         guchar *a);
PgmError            pgm_drawable_set_bg_color           (PgmDrawable *drawable,
                                                         guchar r,
                                                         guchar g,
                                                         guchar b,
                                                         guchar a);
PgmError            pgm_drawable_get_bg_color           (PgmDrawable *drawable,
                                                         guchar *r,
                                                         guchar *g,
                                                         guchar *b,
                                                         guchar *a);
PgmError            pgm_drawable_set_opacity            (PgmDrawable *drawable,
                                                         guchar opacity);
PgmError            pgm_drawable_get_opacity            (PgmDrawable *drawable,
                                                         guchar *opacity);
PgmError            pgm_drawable_set_grid_aligned       (PgmDrawable *drawable,
                                                         gboolean aligned);
PgmError            pgm_drawable_get_grid_aligned       (PgmDrawable *drawable,
                                                         gboolean *aligned);
PgmError            pgm_drawable_set_drag_distance      (PgmDrawable *drawable,
                                                         guchar distance);
PgmError            pgm_drawable_get_drag_distance      (PgmDrawable *drawable,
                                                         guchar *distance);
PgmError            pgm_drawable_regenerate             (PgmDrawable *drawable);
PgmError            pgm_drawable_from_canvas            (PgmDrawable *drawable,
                                                         gfloat *x_drawable,
                                                         gfloat *y_drawable,
                                                         gfloat x_canvas,
                                                         gfloat y_canvas,
                                                         gfloat z_canvas);
PgmError            pgm_drawable_to_canvas              (PgmDrawable *drawable,
                                                         gfloat *x_canvas,
                                                         gfloat *y_canvas,
                                                         gfloat *z_canvas,
                                                         gfloat x_drawable,
                                                         gfloat y_drawable);

Object Hierarchy

  GObject
   +----GstObject
         +----PgmDrawable
               +----PgmImage
               +----PgmText

Signals

  "changed"                                        : Run First
  "clicked"                                        : Run Last
  "double-clicked"                                 : Run Last
  "drag-begin"                                     : Run Last
  "drag-end"                                       : Run Last
  "drag-motion"                                    : Run Last
  "entered"                                        : Run Last
  "left"                                           : Run Last
  "motion"                                         : Run Last
  "pressed"                                        : Run Last
  "pressured"                                      : Run Last
  "released"                                       : Run Last
  "scrolled"                                       : Run Last

Description

Manipulating drawables

PgmDrawable represents a visual object on which you can embed media types such as text, images and video, or 2D graphics. It is meant to be a base abstract class for more specific visual objects such as PgmImage or PgmText. Drawables are not visible until they are added to a PgmCanvas. A drawable never knows about physical on screen coordinates such as pixels, and use floating point canvas coordinates. Drawables are positioned in 3D and then projected on a PgmViewport.

The base class implements simple drawing methods that are common to the different subclasses. For example if you want to draw a left aligned green text you would do something like that:

Example 4. Calling drawing functions on a drawable

pgm_drawable_set_fg_color (text, 0, 255, 0, 255);
pgm_drawable_set_bg_color (text, 255, 0, 0, 255);
pgm_text_set_label (PGM_TEXT (text), "Hello world!");


You are basically using a mix of drawable calls and text calls on the same object at different level of the object hierarchy.

The changed signal is fired whenever a property of a drawable is changed. There are also signals for handling mouse picking. For instance, you just need to connect a callback to the clicked signal to be notified of a click on a drawable.

Last reviewed on 2007-09-25 (0.3.1)

Details

enum PgmDrawableLayer

typedef enum {
  PGM_DRAWABLE_UNBOUND,
  PGM_DRAWABLE_FAR,
  PGM_DRAWABLE_MIDDLE,
  PGM_DRAWABLE_NEAR
} PgmDrawableLayer;

The rendering layers.

PGM_DRAWABLE_UNBOUND

Not bound to a Canvas.

PGM_DRAWABLE_FAR

Layer of drawables drawn behind the other layers.

PGM_DRAWABLE_MIDDLE

Layer of drawables drawn over the drawables in the far layer and behind the drawables in the near one.

PGM_DRAWABLE_NEAR

Layer of drawables drawn over the other layers.

enum PgmDrawableProperty

typedef enum {
  /* PgmDrawable properties */
  PGM_DRAWABLE_VISIBILITY            = 0,
  PGM_DRAWABLE_SIZE                  = 1,
  PGM_DRAWABLE_POSITION              = 2,
  PGM_DRAWABLE_TRANSFORMATION_MATRIX = 3,
  PGM_DRAWABLE_BG_COLOR              = 4,
  PGM_DRAWABLE_FG_COLOR              = 5,
  PGM_DRAWABLE_OPACITY               = 6,
  PGM_DRAWABLE_REGENERATE            = 7,
  /* PgmImage properties */
  PGM_IMAGE_DATA_FILE                = 8,
  PGM_IMAGE_DATA_BUFFER              = 9,
  PGM_IMAGE_DATA_GST_BUFFER          = 10,
  PGM_IMAGE_DATA_PIXBUF              = 11,
  PGM_IMAGE_DATA_SYSTEM_BUFFER       = 12,
  PGM_IMAGE_DATA_IMAGE               = 13,
  PGM_IMAGE_DATA_EMPTY               = 14,
  PGM_IMAGE_SYSTEM_BUFFER_CONTENT    = 15,
  PGM_IMAGE_MAPPING_MATRIX           = 16,
  PGM_IMAGE_ALIGNMENT                = 17,
  PGM_IMAGE_LAYOUT                   = 18,
  PGM_IMAGE_INTERP                   = 19,
  PGM_IMAGE_WRAPPING                 = 20,
  PGM_IMAGE_ASPECT_RATIO             = 21,
  PGM_IMAGE_BORDER_WIDTH             = 22,
  PGM_IMAGE_BORDER_INNER_COLOR       = 23,
  PGM_IMAGE_BORDER_OUTER_COLOR       = 24,
  /* PgmText properties */
  PGM_TEXT_LABEL                     = 25,
  PGM_TEXT_MARKUP                    = 26,
  PGM_TEXT_FONT_FAMILY               = 27,
  PGM_TEXT_HEIGHT                    = 28,
  PGM_TEXT_ELLIPSIZE                 = 29,
  PGM_TEXT_JUSTIFY                   = 30,
  PGM_TEXT_ALIGNMENT                 = 31,
  PGM_TEXT_WRAP                      = 32,
  PGM_TEXT_GRAVITY                   = 33,
  PGM_TEXT_STRETCH                   = 34,
  PGM_TEXT_STYLE                     = 35,
  PGM_TEXT_VARIANT                   = 36,
  PGM_TEXT_WEIGHT                    = 37,
  PGM_TEXT_MULTILINE                 = 38,
  PGM_TEXT_LINE_SPACING              = 39,
  PGM_TEXT_COLOR                     = 40,
  PGM_TEXT_OUTLINE_COLOR             = 41,
  PGM_TEXT_OUTLINE_WIDTH             = 42,
  PGM_TEXT_CAST_SHADOW               = 43,
  PGM_TEXT_SHADOW_POSITION           = 44,
  PGM_TEXT_SHADOW_COLOR              = 45
} PgmDrawableProperty;

The different properties of the drawables.

PGM_DRAWABLE_VISIBILITY

PgmDrawable visibility property.

PGM_DRAWABLE_SIZE

PgmDrawable size property.

PGM_DRAWABLE_POSITION

PgmDrawable position property.

PGM_DRAWABLE_TRANSFORMATION_MATRIX

PgmDrawable transformation matrix property.

PGM_DRAWABLE_BG_COLOR

PgmDrawable background color property.

PGM_DRAWABLE_FG_COLOR

PgmDrawable foreground color property.

PGM_DRAWABLE_OPACITY

PgmDrawable opacity property.

PGM_DRAWABLE_REGENERATE

PgmDrawable regenerate property.

PGM_IMAGE_DATA_FILE

PgmImage file data property.

PGM_IMAGE_DATA_BUFFER

PgmImage buffer data property.

PGM_IMAGE_DATA_GST_BUFFER

PgmImage GstBuffer data property.

PGM_IMAGE_DATA_PIXBUF

PgmImage GdkPixbuf data property.

PGM_IMAGE_DATA_SYSTEM_BUFFER

PgmImage system buffer data property.

PGM_IMAGE_DATA_IMAGE

PgmImage image data property.

PGM_IMAGE_DATA_EMPTY

PgmImage empty data property.

PGM_IMAGE_SYSTEM_BUFFER_CONTENT

PgmImage system buffer content property.

PGM_IMAGE_MAPPING_MATRIX

PgmImage mapping matrix data property.

PGM_IMAGE_ALIGNMENT

PgmImage alignment property.

PGM_IMAGE_LAYOUT

PgmImage layout property.

PGM_IMAGE_INTERP

PgmImage interpolation property.

PGM_IMAGE_WRAPPING

PgmImage wrapping property.

PGM_IMAGE_ASPECT_RATIO

PgmImage aspect-ratio property.

PGM_IMAGE_BORDER_WIDTH

PgmImage border width property.

PGM_IMAGE_BORDER_INNER_COLOR

PgmImage border inner color property.

PGM_IMAGE_BORDER_OUTER_COLOR

PgmImage border outer color property.

PGM_TEXT_LABEL

PgmText label property.

PGM_TEXT_MARKUP

PgmText markup property.

PGM_TEXT_FONT_FAMILY

PgmText font family property.

PGM_TEXT_HEIGHT

PgmText height property.

PGM_TEXT_ELLIPSIZE

PgmText ellipsize property.

PGM_TEXT_JUSTIFY

PgmText justify property.

PGM_TEXT_ALIGNMENT

PgmText alignment property.

PGM_TEXT_WRAP

PgmText wrap property.

PGM_TEXT_GRAVITY

PgmText gravity property.

PGM_TEXT_STRETCH

PgmText stretch property.

PGM_TEXT_STYLE

PgmText style property.

PGM_TEXT_VARIANT

PgmText variant property.

PGM_TEXT_WEIGHT

PgmText weight property.

PGM_TEXT_MULTILINE

PgmText multiline property.

PGM_TEXT_LINE_SPACING

PgmText line spacing property.

PGM_TEXT_COLOR

PgmText color property.

PGM_TEXT_OUTLINE_COLOR

PgmText outline color property.

PGM_TEXT_OUTLINE_WIDTH

PgmText outline width property.

PGM_TEXT_CAST_SHADOW

PgmText cast shadow property.

PGM_TEXT_SHADOW_POSITION

PgmText shadow position property.

PGM_TEXT_SHADOW_COLOR

PgmText shadow color.

PgmDrawable

typedef struct {
  /* Transformation */
  PgmMat4x4 *transformation_matrix;
  gfloat angle_x, angle_y, angle_z;

  /* Layer */
  PgmDrawableLayer layer;

  /* Position */
  gfloat x, y, z;
  gfloat orig_x, orig_y;

  /* Scale */
  gfloat scale;

  /* Size */
  gfloat width, height;
  gfloat orig_width, orig_height;
  gboolean grid_aligned;

  /* Colors */
  guchar fg_r, fg_g, fg_b, fg_a;
  guchar bg_r, bg_g, bg_b, bg_a;

  /* Opacity */
  guchar opacity;
} PgmDrawable;

Pigment drawable abstract base class.

PgmMat4x4 *transformation_matrix;

the drawable transformation matrix.

gfloat angle_x;

the drawable angle of rotation on the x axis.

gfloat angle_y;

the drawable angle of rotation on the y axis.

gfloat angle_z;

the drawable angle of rotation on the z axis.

PgmDrawableLayer layer;

the layer the drawable belongs to.

gfloat x;

the drawable position on the x axis.

gfloat y;

the drawable position on the y axis.

gfloat z;

the drawable position on the z axis.

gfloat orig_x;

the drawable original position on the x axis.

gfloat orig_y;

the drawable original position on the y axis.

gfloat scale;

the drawable scale factor.

gfloat width;

the drawable width.

gfloat height;

the drawable height.

gfloat orig_width;

the drawable original width.

gfloat orig_height;

the drawable original height.

gboolean grid_aligned;

the grid aligned boolean.

guchar fg_r;

the drawable foreground red color component.

guchar fg_g;

the drawable foreground green color component.

guchar fg_b;

the drawable foreground blue color component.

guchar fg_a;

the drawable foreground alpha color component.

guchar bg_r;

the drawable background red color component.

guchar bg_g;

the drawable background green color component.

guchar bg_b;

the drawable background blue color component.

guchar bg_a;

the drawable background alpha color component.

guchar opacity;

the drawable opacity.

PgmDrawableClass

typedef struct {
  GstObjectClass parent_class;


  /* Signals */

  void     (*changed)        (PgmDrawable *drawable,
                              PgmDrawableProperty property);

  gboolean (*pressed)        (PgmDrawable *drawable,
                              gfloat x,
                              gfloat y,
                              gfloat z,
                              PgmButtonType button,
                              guint32 time,
                              guint32 pressure);

  gboolean (*pressured)      (PgmDrawable *drawable,
                              gfloat x,
                              gfloat y,
                              gfloat z,
                              PgmButtonType button,
                              guint32 time,
                              guint32 pressure);

  gboolean (*released)       (PgmDrawable *drawable,
                              PgmButtonType button,
                              guint32 time);

  gboolean (*clicked)        (PgmDrawable *drawable,
                              gfloat x,
                              gfloat y,
                              gfloat z,
                              PgmButtonType button,
                              guint32 time,
                              guint32 pressure);

  gboolean (*double_clicked) (PgmDrawable *drawable,
                              gfloat x,
                              gfloat y,
                              gfloat z,
                              PgmButtonType button,
                              guint32 time);

  gboolean (*scrolled)       (PgmDrawable *drawable,
                              gfloat x,
                              gfloat y,
                              gfloat z,
                              PgmScrollDirection direction,
                              guint32 time);

  gboolean (*drag_begin)     (PgmDrawable *drawable,
                              gfloat x,
                              gfloat y,
                              gfloat z,
                              PgmButtonType button,
                              guint32 time,
                              guint32 pressure);

  gboolean (*drag_motion)    (PgmDrawable *drawable,
                              gfloat x,
                              gfloat y,
                              gfloat z,
                              PgmButtonType button,
                              guint32 time,
                              guint32 pressure);

  gboolean (*drag_end)       (PgmDrawable *drawable,
                              gfloat x,
                              gfloat y,
                              gfloat z,
                              PgmButtonType button,
                              guint32 time);

  gboolean (*motion)         (PgmDrawable *drawable,
                              gfloat x,
                              gfloat y,
                              gfloat z,
                              guint32 time);

  gboolean (*entered)        (PgmDrawable *drawable,
                              gfloat x,
                              gfloat y,
                              gfloat z,
                              guint32 time);

  gboolean (*left)           (PgmDrawable *drawable,
                              gfloat x,
                              gfloat y,
                              gfloat z,
                              guint32 time);

  /* virtual methods for subclasses */

  PgmError (*hide)                      (PgmDrawable *drawable);

  PgmError (*show)                      (PgmDrawable *drawable);

  PgmError (*set_size)                  (PgmDrawable *drawable,
                                         gfloat width,
                                         gfloat height);

  PgmError (*set_position)              (PgmDrawable *drawable,
                                         gfloat x,
                                         gfloat y,
                                         gfloat z);

  PgmError (*set_fg_color)              (PgmDrawable *drawable,
                                         guchar r,
                                         guchar g,
                                         guchar b,
                                         guchar a);

  PgmError (*set_bg_color)              (PgmDrawable *drawable,
                                         guchar r,
                                         guchar g,
                                         guchar b,
                                         guchar a);

  PgmError (*set_opacity)               (PgmDrawable *drawable,
                                         guchar opacity);
} PgmDrawableClass;

The PgmDrawable structure.

GstObjectClass parent_class;

the parent class structure.

changed ()

the "changed" signal.

pressed ()

the "pressed" signal.

pressured ()

the "pressured" signal.

released ()

the "released" signal.

clicked ()

the "clicked" signal.

double_clicked ()

the "double-clicked" signal.

scrolled ()

the "scrolled" signal.

drag_begin ()

the "drag-begin" signal.

drag_motion ()

the "drag-motion" signal.

drag_end ()

the "drag-end" signal.

motion ()

the "motion" signal.

entered ()

the "entered" signal.

left ()

the "left" signal.

hide ()

the hide virtual method.

show ()

the show virtual method.

set_size ()

the set_size virtual method.

set_position ()

the set_position virtual method.

set_fg_color ()

the set_fg_color virtual method.

set_bg_color ()

the set_bg_color virtual method.

set_opacity ()

the set_opacity virtual method.

pgm_drawable_hide ()

PgmError            pgm_drawable_hide                   (PgmDrawable *drawable);

Makes drawable invisible.

MT safe.

drawable :

a PgmDrawable object.

Returns :

a PgmError indicating success/failure.

pgm_drawable_show ()

PgmError            pgm_drawable_show                   (PgmDrawable *drawable);

Makes drawable visible.

MT safe.

drawable :

a PgmDrawable object.

Returns :

a PgmError indicating success/failure.

pgm_drawable_is_visible ()

PgmError            pgm_drawable_is_visible             (PgmDrawable *drawable,
                                                         gboolean *visible);

Retrieves whether drawable is visible.

MT safe.

drawable :

a PgmDrawable object.

visible :

a pointer to a gboolean where the visible state of the drawable is going to be stored.

Returns :

a PgmError indicating success/failure.

pgm_drawable_set_size ()

PgmError            pgm_drawable_set_size               (PgmDrawable *drawable,
                                                         gfloat width,
                                                         gfloat height);

Defines drawable size in canvas units to width x height.

MT safe.

drawable :

a PgmDrawable object.

width :

the width of the canvas.

height :

the height of the canvas.

Returns :

a PgmError indicating success/failure.

pgm_drawable_get_size ()

PgmError            pgm_drawable_get_size               (PgmDrawable *drawable,
                                                         gfloat *width,
                                                         gfloat *height);

Gets drawable size in canvas units.

MT safe.

drawable :

a PgmDrawable object.

width :

a pointer to a gfloat where the width of the drawable is going to be stored.

height :

a pointer to a gfloat where the height of the drawable is going to be stored.

Returns :

a PgmError indicating success/failure.

pgm_drawable_set_position ()

PgmError            pgm_drawable_set_position           (PgmDrawable *drawable,
                                                         gfloat x,
                                                         gfloat y,
                                                         gfloat z);

Sets position of drawable in canvas units.

MT safe.

drawable :

a PgmDrawable object.

x :

the position of drawable on the x axis.

y :

the position of drawable on the y axis.

z :

the position of drawable on the z axis.

Returns :

a PgmError indicating success/failure.

pgm_drawable_get_position ()

PgmError            pgm_drawable_get_position           (PgmDrawable *drawable,
                                                         gfloat *x,
                                                         gfloat *y,
                                                         gfloat *z);

Gets drawable position in canvas units.

MT safe.

drawable :

a PgmDrawable object.

x :

a pointer to a gfloat where the x position of drawable is going to be stored.

y :

a pointer to a gfloat where the y position of drawable is going to be stored.

z :

a pointer to a gfloat where the z position of drawable is going to be stored.

Returns :

a PgmError indicating success/failure.

pgm_drawable_set_rotation_x ()

PgmError            pgm_drawable_set_rotation_x         (PgmDrawable *drawable,
                                                         gfloat angle);

Defines the rotation to apply to drawable on the x axis. The rotation point is the center of drawable and the axis is its normal.

MT safe.

drawable :

a PgmDrawable object.

angle :

an angle of rotation, in radians.

Returns :

a PgmError indicating success/failure.

pgm_drawable_get_rotation_x ()

PgmError            pgm_drawable_get_rotation_x         (PgmDrawable *drawable,
                                                         gfloat *angle);

Retrieves in angle the current x rotation angle applied to drawable.

MT safe.

drawable :

a PgmDrawable object.

angle :

a gfloat pointer where the x rotation angle is going to be stored.

Returns :

a PgmError indicating success/failure.

pgm_drawable_set_rotation_y ()

PgmError            pgm_drawable_set_rotation_y         (PgmDrawable *drawable,
                                                         gfloat angle);

Defines the rotation to apply to drawable on the y axis. The rotation point is the center of drawable and the axis is its normal.

MT safe.

drawable :

a PgmDrawable object.

angle :

an angle of rotation, in radians.

Returns :

a PgmError indicating success/failure.

pgm_drawable_get_rotation_y ()

PgmError            pgm_drawable_get_rotation_y         (PgmDrawable *drawable,
                                                         gfloat *angle);

Retrieves in angle the current y rotation angle applied to drawable.

MT safe.

drawable :

a PgmDrawable object.

angle :

a gfloat pointer where the y rotation angle is going to be stored.

Returns :

a PgmError indicating success/failure.

pgm_drawable_set_rotation_z ()

PgmError            pgm_drawable_set_rotation_z         (PgmDrawable *drawable,
                                                         gfloat angle);

Defines the rotation to apply to drawable on the z axis. The rotation point is the center of drawable and the axis is its normal.

MT safe.

drawable :

a PgmDrawable object.

angle :

an angle of rotation, in radians.

Returns :

a PgmError indicating success/failure.

pgm_drawable_get_rotation_z ()

PgmError            pgm_drawable_get_rotation_z         (PgmDrawable *drawable,
                                                         gfloat *angle);

Retrieves in angle the current z rotation angle applied to drawable.

MT safe.

drawable :

a PgmDrawable object.

angle :

a gfloat pointer where the z rotation angle is going to be stored.

Returns :

a PgmError indicating success/failure.

pgm_drawable_set_scale ()

PgmError            pgm_drawable_set_scale              (PgmDrawable *drawable,
                                                         gfloat scale);

Defines the scale to apply to drawable. The scaling point is the center of drawable.

MT safe.

drawable :

a PgmDrawable object.

scale :

a scale factor.

Returns :

a PgmError indicating success/failure.

pgm_drawable_get_scale ()

PgmError            pgm_drawable_get_scale              (PgmDrawable *drawable,
                                                         gfloat *scale);

Retrieves in scale the current scale factor applied to drawable.

MT safe.

drawable :

a PgmDrawable object.

scale :

a gfloat pointer where the scale factor is going to be stored.

Returns :

a PgmError indicating success/failure.

pgm_drawable_set_fg_color ()

PgmError            pgm_drawable_set_fg_color           (PgmDrawable *drawable,
                                                         guchar r,
                                                         guchar g,
                                                         guchar b,
                                                         guchar a);

Set the color used for drawing operations on drawable to (r,g,b,a).

MT safe.

drawable :

a PgmDrawable object.

r :

the red foreground color.

g :

the green foreground color.

b :

the blue foreground color.

a :

the alpha foreground color.

Returns :

a PgmError indicating success/failure.

pgm_drawable_get_fg_color ()

PgmError            pgm_drawable_get_fg_color           (PgmDrawable *drawable,
                                                         guchar *r,
                                                         guchar *g,
                                                         guchar *b,
                                                         guchar *a);

Retrieves the color used for drawing operations on drawable in (r,g,b,a).

MT safe.

drawable :

a PgmDrawable object.

r :

a pointer to a guchar where the red foreground color is going to be stored.

g :

a pointer to a guchar where the green foreground color is going to be stored.

b :

a pointer to a guchar where the blue foreground color is going to be stored.

a :

a pointer to a guchar where the alpha foreground color is going to be stored.

Returns :

a PgmError indicating success/failure.

pgm_drawable_set_bg_color ()

PgmError            pgm_drawable_set_bg_color           (PgmDrawable *drawable,
                                                         guchar r,
                                                         guchar g,
                                                         guchar b,
                                                         guchar a);

Sets the color used to fill the background of drawable to (r,g,b,a).

MT safe.

drawable :

a PgmDrawable object.

r :

the red background color.

g :

the green background color.

b :

the blue background color.

a :

the alpha background color.

Returns :

a PgmError indicating success/failure.

pgm_drawable_get_bg_color ()

PgmError            pgm_drawable_get_bg_color           (PgmDrawable *drawable,
                                                         guchar *r,
                                                         guchar *g,
                                                         guchar *b,
                                                         guchar *a);

Retrieves the color used to fill the background of drawable in (r,g,b,a).

MT safe.

drawable :

A PgmDrawable object.

r :

a pointer to a guchar where the red background color is going to be stored.

g :

a pointer to a guchar where the green background color is going to be stored.

b :

a pointer to a guchar where the blue background color is going to be stored.

a :

a pointer to a guchar where the alpha background color is going to be stored.

Returns :

A PgmError indicating success/failure.

pgm_drawable_set_opacity ()

PgmError            pgm_drawable_set_opacity            (PgmDrawable *drawable,
                                                         guchar opacity);

Defines the opacity of drawable to opacity.

MT safe.

drawable :

a PgmDrawable object.

opacity :

the opacity of drawable.

Returns :

a PgmError indicating success/failure.

pgm_drawable_get_opacity ()

PgmError            pgm_drawable_get_opacity            (PgmDrawable *drawable,
                                                         guchar *opacity);

Retrieves the opacity of drawable in opacity.

MT safe.

drawable :

a PgmDrawable object.

opacity :

a pointer to a guchar where the opacity is going to be stored.

Returns :

a PgmError indicating success/failure.

pgm_drawable_set_grid_aligned ()

PgmError            pgm_drawable_set_grid_aligned       (PgmDrawable *drawable,
                                                         gboolean aligned);

Sets whether or not drawable must be automatically aligned to the pixel boundaries in the viewport.

MT safe.

drawable :

a PgmDrawable object.

aligned :

the grid aligned boolean. FALSE by default.

Returns :

a PgmError indicating success/failure.

pgm_drawable_get_grid_aligned ()

PgmError            pgm_drawable_get_grid_aligned       (PgmDrawable *drawable,
                                                         gboolean *aligned);

Gets whether or not drawable must be automatically aligned to the pixel boundaries in the viewport.

MT safe.

drawable :

a PgmDrawable object.

aligned :

a pointer to a gboolean where the grid aligned boolean is going to be stored.

Returns :

a PgmError indicating success/failure.

pgm_drawable_set_drag_distance ()

PgmError            pgm_drawable_set_drag_distance      (PgmDrawable *drawable,
                                                         guchar distance);

Defines the drag distance of drawable to distance. The drag distance is the distance in pixels the user has to cover with a mouse button pressed to trigger the 'drag-begin' signal.

MT safe.

drawable :

a PgmDrawable object.

distance :

the drag distance of drawable. 5 by default.

Returns :

a PgmError indicating success/failure.

pgm_drawable_get_drag_distance ()

PgmError            pgm_drawable_get_drag_distance      (PgmDrawable *drawable,
                                                         guchar *distance);

Retrieves the drag distance of drawable in distance.

MT safe.

drawable :

a PgmDrawable object.

distance :

a pointer to a guchar where the drag distance is going to be stored.

Returns :

a PgmError indicating success/failure.

pgm_drawable_regenerate ()

PgmError            pgm_drawable_regenerate             (PgmDrawable *drawable);

Forces a regeneration of the drawable.

MT safe.

drawable :

a PgmDrawable object.

Returns :

a PgmError indicating success/failure.

pgm_drawable_from_canvas ()

PgmError            pgm_drawable_from_canvas            (PgmDrawable *drawable,
                                                         gfloat *x_drawable,
                                                         gfloat *y_drawable,
                                                         gfloat x_canvas,
                                                         gfloat y_canvas,
                                                         gfloat z_canvas);

Converts a position in the canvas into its orthogonal projection in the plane of drawable, with the (0,0) coordinate in that plane being the upper left corner of drawable.

drawable :

a PgmDrawable object.

x_drawable :

where to return the x coordinate in the drawable plane.

y_drawable :

where to return the y coordinate in the drawable plane.

x_canvas :

x coordinate in the canvas space.

y_canvas :

y coordinate in the canvas space.

z_canvas :

z coordinate in the canvas space.

Returns :

a PgmError indicating success/failure.

pgm_drawable_to_canvas ()

PgmError            pgm_drawable_to_canvas              (PgmDrawable *drawable,
                                                         gfloat *x_canvas,
                                                         gfloat *y_canvas,
                                                         gfloat *z_canvas,
                                                         gfloat x_drawable,
                                                         gfloat y_drawable);

Converts a position in the plane of drawable into the canvas space.

drawable :

a PgmDrawable object.

x_canvas :

where to return the x coordinate in the canvas space.

y_canvas :

where to return the y coordinate in the canvas space.

z_canvas :

where to return the z coordinate in the canvas space.

x_drawable :

x coordinate in the drawable plane.

y_drawable :

y coordinate in the drawable plane.

Returns :

a PgmError indicating success/failure.

Signal Details

The "changed" signal

void                user_function                      (PgmDrawable        *drawable,
                                                        PgmDrawableProperty property,
                                                        gpointer            user_data)      : Run First

Will be emitted after property of drawable is changed.

drawable :

the PgmDrawable

property :

the PgmDrawableProperty changed in drawable

user_data :

user data set when the signal handler was connected.

The "clicked" signal

gboolean            user_function                      (PgmDrawable  *drawable,
                                                        gfloat        x,
                                                        gfloat        y,
                                                        gfloat        z,
                                                        PgmButtonType button,
                                                        guint         time,
                                                        guint         pressure,
                                                        gpointer      user_data)      : Run Last

Will be emitted after drawable is clicked.

drawable :

the PgmDrawable

x :

the x coordinate of the point intersecting the click on drawable

y :

the y coordinate of the point intersecting the click on drawable

z :

the z coordinate of the point intersecting the click on drawable

button :

the PgmButtonType

time :

the timestamp of the button press event

pressure :

the pressure force, set to 0 when not used with a touch screen

user_data :

user data set when the signal handler was connected.

Returns :

TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

The "double-clicked" signal

gboolean            user_function                      (PgmDrawable  *drawable,
                                                        gfloat        x,
                                                        gfloat        y,
                                                        gfloat        z,
                                                        PgmButtonType button,
                                                        guint         time,
                                                        gpointer      user_data)      : Run Last

Will be emitted after drawable is clicked.

drawable :

the PgmDrawable

x :

the x coordinate of the point intersecting the double-click on drawable

y :

the y coordinate of the point intersecting the double-click on drawable

z :

the z coordinate of the point intersecting the double-click on drawable

button :

the PgmButtonType

time :

the timestamp of the button press event

user_data :

user data set when the signal handler was connected.

Returns :

TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

The "drag-begin" signal

gboolean            user_function                      (PgmDrawable  *drawable,
                                                        gfloat        x,
                                                        gfloat        y,
                                                        gfloat        z,
                                                        PgmButtonType button,
                                                        guint         time,
                                                        guint         pressure,
                                                        gpointer      user_data)      : Run Last

Will be emitted after drawable is initially dragged. You can for instance use that signal to change drawable properties or store the intersecting point for further computations during the "drag-motion" signal emission.

drawable :

the PgmDrawable

x :

the x coordinate of the point intersecting the initial click on drawable

y :

the y coordinate of the point intersecting the initial click on drawable

z :

the z coordinate of the point intersecting the initial click on drawable

button :

the PgmButtonType

time :

the timestamp of the motion event

pressure :

the pressure force, set to 0 when not used with a touch screen

user_data :

user data set when the signal handler was connected.

Returns :

TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

The "drag-end" signal

gboolean            user_function                      (PgmDrawable  *drawable,
                                                        gfloat        x,
                                                        gfloat        y,
                                                        gfloat        z,
                                                        PgmButtonType button,
                                                        guint         time,
                                                        gpointer      user_data)      : Run Last

Will be emitted after drawable is released. This signal is emitted on all the drawables which have received a "drag-begin" signal.

drawable :

the PgmDrawable

x :

the x coordinate of the point intersecting the release event on the dragged drawable plane

y :

the y coordinate of the point intersecting the release event on the dragged drawable plane

z :

the z coordinate of the point intersecting the release event on the dragged drawable plane

button :

the PgmButtonType

time :

the timestamp of the motion event

user_data :

user data set when the signal handler was connected.

Returns :

TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

The "drag-motion" signal

gboolean            user_function                      (PgmDrawable  *drawable,
                                                        gfloat        x,
                                                        gfloat        y,
                                                        gfloat        z,
                                                        PgmButtonType button,
                                                        guint         time,
                                                        guint         pressure,
                                                        gpointer      user_data)      : Run Last

Will be emitted after drawable is dragged.

drawable :

the PgmDrawable

x :

the x coordinate of the point intersecting the cursor position on the dragged drawable plane

y :

the y coordinate of the point intersecting the cursor position on the dragged drawable plane

z :

the z coordinate of the point intersecting the cursor position on the dragged drawable plane

button :

the PgmButtonType

time :

the timestamp of the motion event

pressure :

the pressure force, set to 0 when not used with a touch screen

user_data :

user data set when the signal handler was connected.

Returns :

TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

The "entered" signal

gboolean            user_function                      (PgmDrawable *drawable,
                                                        gfloat       x,
                                                        gfloat       y,
                                                        gfloat       z,
                                                        guint        time,
                                                        gpointer     user_data)      : Run Last

Will be emitted when the pointer enters the drawable area.

drawable :

the PgmDrawable

x :

the x coordinate of the point intersecting the cursor position on the drawable plane

y :

the y coordinate of the point intersecting the cursor position on the drawable plane

z :

the z coordinate of the point intersecting the cursor position on the drawable plane

time :

the timestamp of the motion event

user_data :

user data set when the signal handler was connected.

Returns :

TRUE if drawables under drawable should not be in "entered" state until the pointer leaves drawable, FALSE otherwise.

The "left" signal

void                user_function                      (PgmDrawable *drawable,
                                                        gfloat       x,
                                                        gfloat       y,
                                                        gfloat       z,
                                                        guint        time,
                                                        gpointer     user_data)      : Run Last

Will be emitted when the pointer leaves the drawable area.

drawable :

the PgmDrawable

x :

the x coordinate of the point intersecting the cursor position on the drawable plane

y :

the y coordinate of the point intersecting the cursor position on the drawable plane

z :

the z coordinate of the point intersecting the cursor position on the drawable plane

time :

the timestamp of the motion event

user_data :

user data set when the signal handler was connected.

The "motion" signal

gboolean            user_function                      (PgmDrawable *drawable,
                                                        gfloat       x,
                                                        gfloat       y,
                                                        gfloat       z,
                                                        guint        time,
                                                        gpointer     user_data)      : Run Last

Will be emitted when the pointer is moved over drawable.

drawable :

the PgmDrawable

x :

the x coordinate of the point intersecting the cursor position on the drawable plane

y :

the y coordinate of the point intersecting the cursor position on the drawable plane

z :

the z coordinate of the point intersecting the cursor position on the drawable plane

time :

the timestamp of the motion event

user_data :

user data set when the signal handler was connected.

Returns :

TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

The "pressed" signal

gboolean            user_function                      (PgmDrawable  *drawable,
                                                        gfloat        x,
                                                        gfloat        y,
                                                        gfloat        z,
                                                        PgmButtonType button,
                                                        guint         time,
                                                        guint         pressure,
                                                        gpointer      user_data)      : Run Last

Will be emitted after drawable is pressed.

drawable :

the PgmDrawable

x :

the x coordinate of the point intersecting the click on drawable

y :

the y coordinate of the point intersecting the click on drawable

z :

the z coordinate of the point intersecting the click on drawable

button :

the PgmButtonType

time :

the timestamp of the button press event

pressure :

the pressure force, set to 0 when not used with a touch screen

user_data :

user data set when the signal handler was connected.

Returns :

TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

The "pressured" signal

gboolean            user_function                      (PgmDrawable  *drawable,
                                                        gfloat        x,
                                                        gfloat        y,
                                                        gfloat        z,
                                                        PgmButtonType button,
                                                        guint         time,
                                                        guint         pressure,
                                                        gpointer      user_data)      : Run Last

Will be emitted after the touch pressure on drawable change.

drawable :

the PgmDrawable

x :

the x coordinate of the point intersecting the click on drawable

y :

the y coordinate of the point intersecting the click on drawable

z :

the z coordinate of the point intersecting the click on drawable

button :

the PgmButtonType

time :

the timestamp of the button press event

pressure :

the pressure force

user_data :

user data set when the signal handler was connected.

Returns :

TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

The "released" signal

gboolean            user_function                      (PgmDrawable  *drawable,
                                                        gfloat        x,
                                                        gfloat        y,
                                                        gfloat        z,
                                                        PgmButtonType button,
                                                        guint         time,
                                                        gpointer      user_data)      : Run Last

Will be emitted after drawable is released.

drawable :

the PgmDrawable

x :

the x coordinate of the point intersecting the click on drawable plane

y :

the y coordinate of the point intersecting the click on drawable plane

z :

the z coordinate of the point intersecting the click on drawable plane

button :

the PgmButtonType

time :

the timestamp of the button release event

user_data :

user data set when the signal handler was connected.

Returns :

TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

The "scrolled" signal

gboolean            user_function                      (PgmDrawable       *drawable,
                                                        gfloat             x,
                                                        gfloat             y,
                                                        gfloat             z,
                                                        PgmScrollDirection direction,
                                                        guint              time,
                                                        gpointer           user_data)      : Run Last

Will be emitted after drawable is scrolled.

drawable :

the PgmDrawable

x :

the x coordinate of the point intersecting the scroll on drawable

y :

the y coordinate of the point intersecting the scroll on drawable

z :

the z coordinate of the point intersecting the scroll on drawable

direction :

the PgmScrollDirection

time :

the timestamp of the scroll event

user_data :

user data set when the signal handler was connected.

Returns :

TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

See Also

#PgmImage, PgmText, PgmCanvas.