## PgmEvents

PgmEvents — Various structs and functions used for events handling.

## Synopsis

    #include <pgm/pgm.h>

    enum                PgmEventType;
    enum                PgmModifierType;
    enum                PgmButtonType;
    enum                PgmScrollDirection;
    enum                PgmViewportState;
    union               PgmEvent;
                        PgmEventAny;
                        PgmEventMotion;
                        PgmEventButton;
                        PgmEventScroll;
                        PgmEventState;
                        PgmEventWin32Message;
                        PgmEventDnd;
                        PgmEventKey;
                        PgmEventExpose;
                        PgmEventConfigure;
    PgmEvent *          pgm_event_new                       (PgmEventType type);
    PgmEvent *          pgm_event_copy                      (PgmEvent *event);
    void                pgm_event_free                      (PgmEvent *event);
    guint32             pgm_keyval_to_unicode               (guint keyval);

## Description

Various structs and functions used by Pigment for events handling.

Last reviewed on 2007-04-12 (0.1.5)

## Details

### enum PgmEventType

    typedef enum {
      PGM_NOTHING             = -1,
      PGM_MOTION_NOTIFY       = 0,
      PGM_BUTTON_PRESS        = 1,
      PGM_DOUBLE_BUTTON_PRESS = 2,
      PGM_TRIPLE_BUTTON_PRESS = 3,
      PGM_BUTTON_PRESSURE     = 4,
      PGM_BUTTON_RELEASE      = 5,
      PGM_KEY_PRESS           = 6,
      PGM_KEY_RELEASE         = 7,
      PGM_EXPOSE              = 8,
      PGM_CONFIGURE           = 9,
      PGM_DRAG_MOTION         = 10,
      PGM_DRAG_DROP           = 12,
      PGM_DRAG_LEAVE          = 13,
      PGM_SCROLL              = 14,
      PGM_STATE               = 15,
      PGM_DELETE              = 16,
      PGM_WIN32_MESSAGE       = 17
    } PgmEventType;

Specifies the type of the event.

`PGM_NOTHING` | a special code to indicate a null event.
`PGM_MOTION_NOTIFY` | the pointer has entered the window.
`PGM_BUTTON_PRESS` | a mouse button has been pressed.
`PGM_DOUBLE_BUTTON_PRESS` | a mouse button has been clicked 2 times in a short period of time. Note that each click also generates a `PGM_BUTTON_PRESS` event.
`PGM_TRIPLE_BUTTON_PRESS` | a mouse button has been clicked 3 times in a short period of time. Note that each click also generates a `PGM_BUTTON_PRESS` event.
`PGM_BUTTON_PRESSURE` | a mouse button pressure has changed.
`PGM_BUTTON_RELEASE` | a mouse button has been released.
`PGM_KEY_PRESS` | a key has been pressed.
`PGM_KEY_RELEASE` | a key has been released.
`PGM_EXPOSE` | the window has become visible and needs to be redrawn.
`PGM_CONFIGURE` | the size or the position of the viewport has changed.
`PGM_DRAG_MOTION` | the mouse has moved in the viewport while a drag is in progress.
`PGM_DRAG_DROP` | the mouse has dropped data onto the viewport.
`PGM_DRAG_LEAVE` | the mouse has left the viewport while a drag is in progress.
`PGM_SCROLL` | the scroll wheel was turned.
`PGM_STATE` | the state of a viewport has changed.
`PGM_DELETE` | the window manager has requested that the toplevel window be destroyed, usually when the user clicks on a special icon in the title bar.
`PGM_WIN32_MESSAGE` | a Win32 message has been received (Only used on Windows).

### enum PgmModifierType

    typedef enum {
      PGM_SHIFT_MASK    = (1 << 0),
      PGM_CAPSLOCK_MASK = (1 << 1),
      PGM_CONTROL_MASK  = (1 << 2),
      PGM_ALT_MASK      = (1 << 3),
      PGM_NUMLOCK_MASK  = (1 << 4)
    } PgmModifierType;

A set of bit-flags to indicate the state of modifier keys. Typical modifier keys are Shift, Control, Alt and CapsLock.

`PGM_SHIFT_MASK` | the Shift key.
`PGM_CAPSLOCK_MASK` | the Caps Lock.
`PGM_CONTROL_MASK` | the Control key.
`PGM_ALT_MASK` | the Alt key.
`PGM_NUMLOCK_MASK` | the Num Lock.

### enum PgmButtonType

    typedef enum {
      PGM_BUTTON_LEFT   = (1 << 0),
      PGM_BUTTON_MIDDLE = (1 << 1),
      PGM_BUTTON_RIGHT  = (1 << 2)
    } PgmButtonType;

The mouse button type.

`PGM_BUTTON_LEFT` | the left mouse button.
`PGM_BUTTON_MIDDLE` | the middle mouse button.
`PGM_BUTTON_RIGHT` | the right mouse button.

### enum PgmScrollDirection

    typedef enum {
      PGM_SCROLL_UP,
      PGM_SCROLL_DOWN
    } PgmScrollDirection;

The mouse wheel scrolling directions.

`PGM_SCROLL_UP` | the scrolling in the upward direction.
`PGM_SCROLL_DOWN` | the scrolling in the downward direction.

### enum PgmViewportState

    typedef enum {
      PGM_VIEWPORT_ICONIFIED  = (1 << 0)
    } PgmViewportState;

Specifies the state of a viewport.

`PGM_VIEWPORT_ICONIFIED` | The viewport is minimized.

### union PgmEvent

    union PgmEvent {
      PgmEventType         type;
      PgmEventAny          any;
      PgmEventMotion       motion;
      PgmEventButton       button;
      PgmEventScroll       scroll;
      PgmEventKey          key;
      PgmEventExpose       expose;
      PgmEventConfigure    configure;
      PgmEventDnd          dnd;
      PgmEventState        state;
    #ifdef WIN32
      PgmEventWin32Message win32_message;
    #endif /* WIN32 */
    };

The PgmEvent struct contains a union of all of the event structs, and allows access to the data fields in a number of ways.

The event type is always the first field in all of the event structs, and can always be accessed with the following code, no matter what type of event it is:

      PgmEvent *event;
      PgmEventType type;
      type = event->type;

To access other fields of the event structs, the pointer to the event can be cast to the appropriate event struct pointer, or the union member name can be used. For example if the event type is `PGM_BUTTON_PRESS` then the x coordinate of the button press can be accessed with:

      PgmEvent *event;
      gfloat x;
      x = ((PgmEventButton*) event)->x;

or with:

      PgmEvent *event;
      gfloat x;
      x = event->button.x;

### PgmEventAny

    typedef struct {
      PgmEventType type;
      guint8       source;
    } PgmEventAny;

Contains the fields which are common to all event structs. Any event pointer can safely be cast to a pointer to a PgmEventAny to access these fields.

PgmEventType `type`; | the type of the event.
guint8 `source`; | the source field that can be filled by applications to indicate the source of the event (mouse, pen, remote control, etc).

### PgmEventMotion

    typedef struct {
      PgmEventType type;
      guint8       source;
      guint32      time;
      gfloat       x, y;
      guint32      pressure;
    } PgmEventMotion;

Generated when the pointer moves.

PgmEventType `type`; | the type of the event.
guint8 `source`; | the source field that can be filled by applications to indicate the source of the event (mouse, pen, remote control, etc).
guint32 `time`; | the time of the event in milliseconds.
gfloat `x`; | the x coordinate of the pointer relative to the window.
gfloat `y`; | the y coordinate of the pointer relative to the window.
guint32 `pressure`; | the pressure force, set to 0 when not used with a touch screen.

### PgmEventButton

    typedef struct {
      PgmEventType  type;
      guint8        source;
      guint32       time;
      gfloat        x, y;
      PgmButtonType button;
      guint32       pressure;
    } PgmEventButton;

Used for button press and button release events.

PgmEventType `type`; | the type of the event.
guint8 `source`; | the source field that can be filled by applications to indicate the source of the event (mouse, pen, remote control, etc).
guint32 `time`; | the time of the event in milliseconds.
gfloat `x`; | the x coordinate of the pointer relative to the window.
gfloat `y`; | the y coordinate of the pointer relative to the window.
PgmButtonType `button`; | the button which was pressed or released.
guint32 `pressure`; | the pressure force, set to 0 when not used with a touch screen.

### PgmEventScroll

    typedef struct {
      PgmEventType       type;
      guint8             source;
      guint32            time;
      gfloat             x, y;
      PgmScrollDirection direction;
    } PgmEventScroll;

Generated when the mouse wheel is turned.

PgmEventType `type`; | the type of the event.
guint8 `source`; | the source field that can be filled by applications to indicate the source of the event (mouse, pen, remote control, etc).
guint32 `time`; | the time of the event in milliseconds.
gfloat `x`; | the x coordinate of the pointer relative to the window.
gfloat `y`; | the y coordinate of the pointer relative to the window.
PgmScrollDirection `direction`; | the scroll wheel direction.

### PgmEventState

    typedef struct {
      PgmEventType     type;
      guint8           source;
      PgmViewportState changed_mask;
      PgmViewportState state_mask;
    } PgmEventState;

Generated when the state of a viewport changes.

PgmEventType `type`; | the type of the event.
guint8 `source`; | the source field that can be filled by applications to indicate the source of the event (mouse, pen, remote control, etc).
PgmViewportState `changed_mask`; | mask specifying what viewport flags have changed.
PgmViewportState `state_mask`; | mask specifying the new viewport flags.

### PgmEventWin32Message

    typedef struct {
      PgmEventType type;
      guint8       source;
      guint32      time;
      UINT         message;
      WPARAM       wparam;
      LPARAM       lparam;
    } PgmEventWin32Message;

Describes a Win32 message.

PgmEventType `type`; | the type of the event.
guint8 `source`; | the source field that can be filled by applications to indicate the source of the event (mouse, pen, remote control, etc).
guint32 `time`; | the time of the event in milliseconds.
UINT `message`; | the Win32 message value.
WPARAM `wparam`; | additional message information depending on the message value.
LPARAM `lparam`; | additional message information depending on the message value.

### PgmEventDnd

    typedef struct {
      PgmEventType   type;
      guint8         source;
      guint32        time;
      gfloat         x, y;
      gchar        **uri;
    } PgmEventDnd;

Describes a drag motion, drop, or leave event.

PgmEventType `type`; | the type of the event.
guint8 `source`; | the source field that can be filled by applications to indicate the source of the event (mouse, pen, remote control, etc).
guint32 `time`; | the time of the event in milliseconds.
gfloat `x`; | the new x coordinate of the window.
gfloat `y`; | the new y coordinate of the window.
gchar **`uri`; | the list of URI as a NULL-terminated array of strings.

### PgmEventKey

    typedef struct {
      PgmEventType type;
      guint8       source;
      guint32      time;
      guint        modifier;
      guint        keyval;
      guint16      hardware_keycode;
    } PgmEventKey;

Describes a key press or key release event.

PgmEventType `type`; | the type of the event.
guint8 `source`; | the source field that can be filled by applications to indicate the source of the event (mouse, pen, remote control, etc).
guint32 `time`; | the time of the event in milliseconds.
guint `modifier`; | A bit-mask representing the state of the modifier keys (e.g. Control, Shift and Alt), see PgmModifierType.
guint `keyval`; | the key that was pressed or released. See the pgm/pgmkeysyms.h header file for a complete list of Pigment key codes.
guint16 `hardware_keycode`; | the raw code of the key that was pressed or released.

### PgmEventExpose

    typedef struct {
      PgmEventType type;
      guint8       source;
    } PgmEventExpose;

Generated when a window becomes visible and needs to be redrawn.

PgmEventType `type`; | the type of the event.
guint8 `source`; | the source field that can be filled by applications to indicate the source of the event (mouse, pen, remote control, etc).

### PgmEventConfigure

    typedef struct {
      PgmEventType type;
      guint8       source;
      gint         x, y;
      gint         width, height;
    } PgmEventConfigure;

Generated when a viewport size or position has changed.

PgmEventType `type`; | the type of the event.
guint8 `source`; | the source field that can be filled by applications to indicate the source of the event (mouse, pen, remote control, etc).
gint `x`; | the new x coordinate of the window.
gint `y`; | the new y coordinate of the window.
gint `width`; | the new width of the viewport.
gint `height`; | the new height of the viewport.

### pgm_event_new ()

    PgmEvent *          pgm_event_new                       (PgmEventType type);

Creates a new PgmEvent of the specified type.

MT safe.

`type` : | the type of event.
Returns : | a new PgmEvent instance.

### pgm_event_copy ()

    PgmEvent *          pgm_event_copy                      (PgmEvent *event);

Copies `event`.

MT safe.

`event` : | a PgmEvent object.
Returns : | a newly allocated PgmEvent.

### pgm_event_free ()

    void                pgm_event_free                      (PgmEvent *event);

MT safe.

Frees all resources used by `event`.

`event` : | A PgmEvent object.

### pgm_keyval_to_unicode ()

    guint32             pgm_keyval_to_unicode               (guint keyval);

Converts from a Pigment key symbol to the corresponding ISO10646 (Unicode) character.

MT safe.

`keyval` : | a Pigment key symbol.
Returns : | the corresponding unicode character, or 0 if there is no corresponding one.