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.