Things used to notify your code of user input or other significant events. More...

Collaboration diagram for Events:

Classes
class	EventEmitter
	Distributes events to event handlers. More...

class	EventManager
	Distributes events to event handlers. More...

class	IEventHandler
	Interface for any class which handles events. More...

struct	KeyEvent
	a key down or up event More...

struct	KeyPressEvent
	the user pressed and released a key More...

struct	MouseEvent
	the user did something with the mouse More...

struct	MouseTrackingEvent
	the mouse entered or left a tracking region (NOT IMPLEMENTED) More...

struct	PortDrawEvent
	a port needs to be redrawn (GUI Only) More...

struct	PortResizedEvent
	a port has been resized (GUI Only) More...

struct	ScrollWheelEvent
	the user repositioned the scroll wheel More...

struct	ShutdownEvent
	a timer fire event More...

struct	SoundEvent
	a sound completed or is looping (GUI Only) More...

struct	SpriteAnimateEvent
	a Sprite did some animation (Optional) More...

struct	SpriteBreakEvent
	a Sprite joint is breaking because it was overstressed (Chipmunk Physics Only) More...

struct	SpriteCollideEvent
	a Sprite collided with something (Optional) More...

struct	SpriteLayerEvent
	something happened to this layer More...

struct	SpriteTouchEvent
	the user clicked on (or touched) a Sprite More...

class	TimerManager
	manages timers that can fire at a particular time, or repeatedly at an interval More...

Variables
const	all_events = 0
	a special catch-all for events that weren't handled by specific event handlers More...

const	eventType_KeyDown = 4
	the user pushed down on a key More...

const	eventType_KeyPress = 6
	the user pressed and released a key More...

const	eventType_KeyUp = 5
	the user released a key More...

const	eventType_MouseDown = 7
	the user pressed a mouse button More...

const	eventType_MouseEnter = 22
	the user moved the mouse into a tracking area (NOT IMPLEMENTED) More...

const	eventType_MouseLeave = 23
	the user moved the mouse out of a tracking area (NOT IMPLEMENTED) More...

const	eventType_MouseMove = 9
	the user moved the mouse More...

const	eventType_MouseUp = 8
	the user release a mouse button More...

const	eventType_PortDraw = 24
	a port needs to be redrawn More...

const	eventType_PortResized = 15
	a port was resized More...

const	eventType_ScrollWheel = 16
	the user moved the scroll wheel More...

const	eventType_Shutdown = 2
	one time application shutdown event More...

const	eventType_SoundEvent = 14
	a sound finished or looped More...

const	eventType_SpriteAnimate = 17
	a sprite finished an animation (Optional) More...

const	eventType_SpriteBreak = 21
	joined sprites broke apart (Chipmunk Physics only) More...

const	eventType_SpriteCollide = 20
	a collision between sprites More...

const	eventType_SpriteLayer = 18
	something happening to a sprite layer More...

const	eventType_SpriteTouch = 19
	sprite touched event (Optional) More...

const	eventType_Timer = 3
	a timer fire event More...

Detailed Description

Things used to notify your code of user input or other significant events.

Class Documentation

class pdg::IEventHandler

Interface for any class which handles events.

Specific Subclasses should be written to implement particular handlers. Typically you would call an onXXX() method of the EventEmitter object that is generating the event you want, and it will take care of creating the event handler for you, and adding a convenient cancel() method to the handler. For example:

var mySpriteCollisionHandler = mySprite.onCollideSprite(function(event) {
   // do something about the collision
});
...
mySpriteCollisionHandler.cancel();   // stop handling collision events with this handler

This cancel() method will only work for a single emitter. So if you may want to create a handler that is used with multiple emitters, you should create it once and then explicitly add it to and remove it from each emitter. Here's how:

var mySpriteHandler = new pdg.IEventHandler(function(event) {
                console.log("in my event handler with "+event);
});
mySprite.addHandler(mySpriteHandler, pdg.eventType_SpriteCollide);
...
mySprite.removeHandler(mySpriteHandler, pdg.eventType_SpriteCollide);

Your Custom Function:

As you can see from the examples above, your Event Handler function will be called with a single parameter, and return a boolean:

Parameters

event the event that occurred (from the See Also list below)

Returns: true if the event has been completely handled and should not propagate any further; or false it should be allowed to continue to propagate through the handler chain.

See Also: KeyEvent; KeyPressEvent; MouseEvent; MouseTrackingEvent; PortDrawEvent; PortResizedEvent; ScrollWheelEvent; ShutdownEvent; SoundEvent; SpriteAnimateEvent; SpriteBreakEvent; SpriteCollideEvent; SpriteLayerEvent; SpriteTouchEvent

struct pdg::KeyEvent

a key down or up event

Generated by the EventManager when the user pushes down on a key (eventType_KeyDown) or releases a key (eventType_KeyUp). Use this for arcade style key handling.

For keyboard data entry, use eventType_KeyPress.

{ 
    emitter: {},       // the emitter that generated this event
    eventType: 4,      // the event type (eventType_KeyUp or eventType_KeyDown)
    keyCode: 34        // the raw key code from the OS
}

See Also: eventType_KeyDown; eventType_KeyUp; eventType_KeyPress; onKeyDown(); EventManager.isKeyDown(); EventManager.isRawKeyDown()

struct pdg::KeyPressEvent

the user pressed and released a key

Generated by the EventManager when the user presses and releases a key (a keystroke). Also generated by repeat key events from the OS when a key is held down.

For arcade style multi-key handling see eventType_KeyDown and eventType_KeyUp.

{ 
    emitter: {},            // the emitter that generated this event
    eventType: 6,           // the event type (eventType_KeyPress)
    shift: false,           // true if the shift key is held down
    ctrl: false,            // true if the control key is held down
    alt: false,             // true if the alt (or option) key is held down
    meta: false,            // true if the meta (windows or command) key is held down
    unicode: 48,            // the Unicode character code generated by this key
    isRepeating: false,     // true if this is a repeat key event
}

See Also: eventType_KeyPress; onKeyPress(); Key Code Constants

struct pdg::MouseEvent

the user did something with the mouse

Generated by the EventManager whenever the user moves the mouse (eventType_MouseMove) or clicks a mouse button (eventType_MouseDown and eventType_MouseUp).

The EventManager also tracks the state of the mouse buttons, so you can retrieve that at any time with EventManager.isButtonDown(). The GraphicsManager tracks the position of the mouse, and that can be retrieved at any time with GraphicsManager.getMouse().

{ 
    emitter: {},            // the emitter that generated this event
    eventType: 7,           // the event type (eventType_MouseDown, eventType_MouseUp, or eventType_MouseMove)
    shift: false,           // true if the shift key is held down
    ctrl: false,            // true if the control key is held down
    alt: false,             // true if the alt (or option) key is held down
    meta: false,            // true if the meta (windows or command) key is held down
    mousePos: {
        x: 456,                         // the x coordinate of the mouse when the event occurred
        y: 201              // the y coordinate of the mouse when the event occurred
    },
    leftButton: false,      // true if the left mouse button was down
    rightButton: false,     // true if the left mouse button was down
    buttonNumber: 0,        // true if the meta (windows or command) key is held down
    lastClickPos: { 
        x: 456,                         // the x coordinate of the last mouseDown event
        y: 201              // the y coordinate of the last mouseDown event
    },
    lastClickElapsed: 201   // the number of milliseconds since the last mouseDown
}

Location and time since the last mouseDown event are provided to make it easier to detect double-clicks, dragging, and gestures.

Note: on a touch device mouse moved events are only generated when the user is touching the device, and each finger touching is treated like a separate mouse button, with the button number based on the order the fingers touched the device.; A SpriteLayer has the ability to automatically handle these mouse events and generate eventType_SpriteTouch for any Sprite that was clicked on, or pass these on as mouse events if no Sprite was hit.

See Also: eventType_MouseDown; eventType_MouseUp; eventType_MouseMove; eventType_SpriteTouch; onMouseDown(); onMouseUp(); onMouseMove(); EventManager.isButtonDown(); GraphicsManager.getMouse()

struct pdg::MouseTrackingEvent

the mouse entered or left a tracking region (NOT IMPLEMENTED)

Todo:: NOT IMPLEMENTED

struct pdg::PortDrawEvent

a port needs to be redrawn (GUI Only)

Generated by the GraphicsManager whenever it is time to redraw a Port. All drawing calls should be done during the handling of a eventType_PortDraw.

{ 
    emitter: {},       // the emitter that generated this event
    eventType: 24,     // the event type (eventType_PortDraw)
    port: {},          // the port that needs to be redrawn
    frameNum: 12897    // how many times this event has been generated for this port
}

Note: these events are never generated in a non-GUI build, such as the PDG Node.js plugin

See Also: eventType_PortDraw; Port; GraphicsManager

struct pdg::PortResizedEvent

a port has been resized (GUI Only)

Generated by the GraphicsManager whenever a Port is resized or when the device orientation is changed.

{ 
    emitter: {},       // the emitter that generated this event
    eventType: 15,     // the event type (eventType_PortResized)
    port: {},          // the port that was resized
    screenPos: 0       // one of the screenPos_ constants, in this case screenPos_Normal
}

Note: these events are never generated in a non-GUI build, such as the PDG Node.js plugin

See Also: eventType_PortResized; Port; GraphicsManager

struct pdg::ScrollWheelEvent

the user repositioned the scroll wheel

Generated by the EventManager when the user moves the scroll wheel.

{ 
    emitter: {},            // the emitter that generated this event
    eventType: 16,          // the event type (eventType_ScrollWheel)
    shift: false,           // true if the shift key is held down
    ctrl: false,            // true if the control key is held down
    alt: false,             // true if the alt (or option) key is held down
    meta: false,            // true if the meta (windows or command) key is held down
    horizDelta: 0,          // the amount of horizontal scroll wheel movement
    vertDelta: -48          // the amount of vertical scroll wheel movement
}

See Also: eventType_ScrollWheel

struct pdg::ShutdownEvent

a timer fire event

Generated by the PDG Engine when the application exits normally. This is usually when pdg.quit() is called.

{ 
    emitter: {},            // the emitter that generated this event
    eventType: 2,           // the event type (eventType_Shutdown)
    exitReason: 0,          // the reason the application exited (TBD, always 0)
    exitCode: 0             // the exit code that will be returned to the OS
}

Todo:

Implement exitReason

Implement exitCode and pdg.abort( exitCode )

See Also: eventType_Shutdown; pdg.quit()

struct pdg::SoundEvent

a sound completed or is looping (GUI Only)

Generated by the SoundManager whenever a sound finishes playing (soundEvent_DonePlaying), or reaches the end and loops (soundEvent_Looping). If there is an error

For keyboard data entry, use eventType_KeyPress.

{ 
    emitter: {},       // the emitter that generated this event
    eventType: 14,     // the event type (eventType_SoundEvent)
    eventCode: 1,      // the sound event code (one of: soundEvent_DonePlaying, soundEvent_Looping, or soundEvent_FailedToPlay) 
    sound: {}          // the Sound object that caused the event
}

See Also: eventType_SoundEvent; soundEvent_DonePlaying; soundEvent_Looping; soundEvent_FailedToPlay; Sound

struct pdg::SpriteAnimateEvent

a Sprite did some animation (Optional)

A Sprite will generate one of these events when it completes an animation including fades (opacity animations), and moving on/offscreen or outside of the layer.

For frame based animations – that is, calls to Sprite.startFrameAnimation() – if it reaches the last frame and is not set to loop, action will be action_AnimationEnd. For looping animations action_AnimationLoop will be received each time the animation completes and starts over with the first frame.

For fades, one of three action types are possible: action_FadeComplete for calls to Sprite.fadeTo(), action_FadeInComplete for calls to Sprite.fadeIn(), and action_FadeOutComplete for calls to Sprite.fadeOut().

When a Sprite has setWantsOffscreenEvents(true), action_Offscreen and action_Onscreen events will be generated for that sprite whenever it enters or departs the visible area of the port the layer is being rendered into.

When a Sprite has setWantsCollideWallEvents(true), action_ExitLayer events will be generated for that sprite whenever it moves completely outside the boundaries of the layer. (It will also get a SpriteCollideEvent when hits the boundary).

{
    emitter: {},            // the emitter that generated this event
    eventType: 17,          // the event type (eventType_SpriteAnimate)
    action: 0,              // what happened (action_AnimationEnd/Loop or action_Fade/In/OutComplete)
    actingSprite: {},       // the Sprite that was animating
    inLayer: {}             // the SpriteLayer that contains the Sprite
}

Note: At this time other kinds of animations such as calls to Sprite.startAnimation() do not generate any events.

See Also: eventType_SpriteAnimate; Sprite.startFrameAnimation(); Sprite.fadeTo(); Sprite.fadeIn(); Sprite.fadeOut(); Sprite.setWantsOffscreenEvents(); Sprite.setWantsCollideWallEvents()

struct pdg::SpriteBreakEvent

a Sprite joint is breaking because it was overstressed (Chipmunk Physics Only)

This event is generated by a Sprite whenever the forces acting on a joint with another Sprite are greater then the breaking force of the joint. To prevent the break from happening, return true from the handler that gets this event. If you return false then the joint will go ahead and break.

{
    emitter: {},            // the emitter that generated this event
    eventType: 21,          // the event type (eventType_SpriteBreak)
    action: 13,                 // what happened (action_JointBreak)
    actingSprite: {},       // the Sprite to which the forces were applied
    inLayer: {},            // the SpriteLayer that contains the Sprite
    targetSprite: {},       // the Sprite that was previously joined
    impulse: {              // the impulse applied 
      x: 29.35,
      y: 0.883
    },
    force: 384.0,           // the force of the collision
    breakForce: 100.0,      // the maximum force the joint could stand before breaking
    joint: {}               // the CpConstraint that defines the joint
}

Todo:: Need a lot more documentation on Joints

Note: Only joints that have a breaking force assigned will generate these events; without it joints between sprites are considered unbreakable.

See Also: eventType_SpriteBreak; Sprite.makeJointBreakable(); Sprite.makeJointUnbreakable(); Physics

struct pdg::SpriteCollideEvent

a Sprite collided with something (Optional)

This event is generated by a Sprite whenever it hits something. If it hits another Sprite action will be action_CollideSprite, if it hits a wall it will be action_CollideWall.

{
    emitter: {},            // the emitter that generated this event
    eventType: 20,          // the event type (eventType_SpriteCollide)
    action: 0,                  // what happened (action_CollideSprite or action_CollideWall)
    actingSprite: {},       // the moving Sprite
    inLayer: {},            // the SpriteLayer that contains the Sprite
    targetSprite: {},       // the Sprite that was collided with (if action was action_CollideSprite)
    normal: {               // the normal vector for the collision
      x: 1.0,
      y: 0.0
    },
    impulse: {              // the impulse imparted by the collision
      x: 29.35,
      y: 0.883
    },
    force: 384.0,           // the force of the collision
    kineticEnergy:883       // the total kinetic energy of the collision
}

Todo:

Need a lot more documentation on Collisions

Calculate kinetic energy of collision for Sprites not using Chipmunk Physics

Note: Collisions must be turned on for each Sprite using Sprite.enableCollisions() or Sprite.setCollisionRadius()

See Also: eventType_SpriteCollide; action_CollideSprite; action_CollideWall; Sprite.enableCollisions(); Sprite.setCollisionRadius()

struct pdg::SpriteLayerEvent

something happened to this layer

This event can be generated with action_LayerFadeInComplete or action_LayerFadeOutComplete when the layer finishes a fade.

This event can be generated with action_ZoomComplete with the layer finishes a zoom animation.

These events are also generated regularly by a SpriteLayer to give the application a chance to take action at various stages of sprite animation and rendering.

{ 
    emitter: {},            // the emitter that generated this event
    eventType: 18,          // the event type (eventType_SpriteLayer)
    action: 0,              // one of: action_AnimationStart/Complete, action_Pre/PostAnimateLayer, action_ErasePort, action_Pre/PostDrawLayer, or action_DrawPortComplete
    actingLayer: {},        // the SpriteLayer that is taking action
    millisec: 1025448321,   // the millisecond time when this entire animation step started (when action_AnimationStart fired) 
}

A single step of animation will generate these events:

action_AnimationStart with actingLayer set to the first layer (Z-order = 0)
for each layer, with actingLayer set to that layer, in Z-order (0...n):
- action_PreAnimateLayer just before animation starts
- action_PostAnimateLayer after all animation is complete
action_AnimationComplete with actingLayer set to the last layer

In a similar fashion, a rendering a single frame will generate these events:

action_ErasePort with actingLayer set to the first layer (Z-order = 0)
for each layer, with actingLayer set to that layer, in Z-order (0...n):
- action_PreDrawLayer just before layer rendering starts
- action_PostDrawLayer after all sprites in the layer have been drawn
action_DrawPortComplete with actingLayer set to the last layer

See Also: eventType_SpriteLayer

struct pdg::SpriteTouchEvent

the user clicked on (or touched) a Sprite

This event is generated by a Sprite whenever a user clicks on it (or touches it in on a touch device).

{
    emitter: {},            // the emitter that generated this event
    eventType: 1,           // the event type (eventType_SpriteTouch)
    touchType: 0,           // touch_MouseDown, touch_MouseUp, or touch_MouseClick
    touchedSprite: {},      // the Sprite that was clicked or touched
    inLayer: {}             // the SpriteLayer that contains the Sprite
}

A single click may generate up to three separate events, each with a different touchType:

touch_MouseDown when a mouse button goes down inside a Sprite
touch_MouseUp when a mouse button is released inside a Sprite
touch_MouseClick when the mouse button was clicked and released inside the same Sprite

Note: Click events must be turned on for each Sprite using Sprite.setWantsClickEvents(); If no Sprite was hit by a mouse event, the original eventType_MouseDown or eventType_MouseUp is passed on through the EventManager

Bug:: will emit touch_MouseClick event if one button was clicked inside a sprite and a different button then released in the same Sprite.

See Also: eventType_SpriteTouch; Sprite.onMouseDown(); Sprite.onMouseUp(); Sprite.onMouseClick(); Sprite.setWantsClickEvents()

Variable Documentation

all_events = 0

a special catch-all for events that weren't handled by specific event handlers

See Also: EventEmitter.addHandler(); EventEmitter.removeHandler()

eventType_KeyDown = 4

the user pushed down on a key

Generated by the EventManager when the user first pushes down on a key. Use this for arcade style key handling.

To detect the key being released, use eventType_KeyUp. For keyboard data entry, use eventType_KeyPress.

See Also: KeyEvent; eventType_KeyUp; eventType_KeyPress; onKeyDown(); EventManager.isKeyDown(); EventManager.isRawKeyDown()

eventType_KeyPress = 6

the user pressed and released a key

Also generated by repeat key events from the OS when a key is held down

See Also: KeyPressEvent; onKeyPress()

eventType_KeyUp = 5

the user released a key

Generated by the EventManager when the user releases a key that was being held down. Use this for arcade style key handling. To detect the key being pushed down, use eventType_KeyDown.

For keyboard data entry, use eventType_KeyPress.