## 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.