PDG engine v0.9.5
 All Classes Namespaces Functions Variables Groups Pages
Classes | Variables
Events

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  pdg::KeyEvent
 a key down or up event More...
 
struct  pdg::KeyPressEvent
 the user pressed and released a key More...
 
struct  pdg::MouseEvent
 the user did something with the mouse More...
 
struct  pdg::MouseTrackingEvent
 the mouse entered or left a tracking region (NOT IMPLEMENTED) More...
 
struct  pdg::PortDrawEvent
 a port needs to be redrawn (GUI Only) More...
 
struct  pdg::PortResizedEvent
 a port has been resized (GUI Only) More...
 
struct  pdg::ScrollWheelEvent
 the user repositioned the scroll wheel More...
 
struct  pdg::ShutdownEvent
 a timer fire event More...
 
struct  pdg::SoundEvent
 a sound completed or is looping (GUI Only) More...
 
struct  pdg::SpriteAnimateEvent
 a Sprite did some animation (Optional) More...
 
struct  pdg::SpriteBreakEvent
 a Sprite joint is breaking because it was overstressed (Chipmunk Physics Only) More...
 
struct  pdg::SpriteCollideEvent
 a Sprite collided with something (Optional) More...
 
struct  pdg::SpriteLayerEvent
 something happened to this layer More...
 
struct  pdg::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
 
const eventType_KeyDown = 4
 the user pushed down on a key
 
const eventType_KeyPress = 6
 the user pressed and released a key
 
const eventType_KeyUp = 5
 the user released a key
 
const eventType_MouseDown = 7
 the user pressed a mouse button
 
const eventType_MouseEnter = 22
 the user moved the mouse into a tracking area (NOT IMPLEMENTED)
 
const eventType_MouseLeave = 23
 the user moved the mouse out of a tracking area (NOT IMPLEMENTED)
 
const eventType_MouseMove = 9
 the user moved the mouse
 
const eventType_MouseUp = 8
 the user release a mouse button
 
const eventType_PortDraw = 24
 a port needs to be redrawn
 
const eventType_PortResized = 15
 a port was resized
 
const eventType_ScrollWheel = 16
 the user moved the scroll wheel
 
const eventType_Shutdown = 2
 one time application shutdown event
 
const eventType_SoundEvent = 14
 a sound finished or looped
 
const eventType_SpriteAnimate = 17
 a sprite finished an animation (Optional)
 
const eventType_SpriteBreak = 21
 joined sprites broke apart (Chipmunk Physics only)
 
const eventType_SpriteCollide = 20
 a collision between sprites
 
const eventType_SpriteLayer = 18
 something happening to a sprite layer
 
const eventType_SpriteTouch = 19
 sprite touched event (Optional)
 
const eventType_Timer = 3
 a timer fire event
 

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
eventthe 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:

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

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:

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.

See Also
KeyEvent
eventType_KeyUp
eventType_KeyPress
onKeyUp()
EventManager.isKeyDown()
EventManager.isRawKeyDown()
eventType_MouseDown = 7

the user pressed a mouse button

Generated by the EventManager when a timer fires

See Also
MouseEvent
eventType_MouseUp
onMouseDown()
EventManager.isButtonDown()
eventType_MouseEnter = 22

the user moved the mouse into a tracking area (NOT IMPLEMENTED)

Todo:
NOT IMPLEMENTED

Generated by the EventManager when the mouse enters a tracking area

See Also
MouseTrackingEvent
eventType_MouseLeave = 23

the user moved the mouse out of a tracking area (NOT IMPLEMENTED)

Todo:
NOT IMPLEMENTED

Generated by the EventManager when the mouse leaves a tracking area

See Also
MouseTrackingEvent
eventType_MouseMove = 9

the user moved the mouse

Generated by the EventManager when the user moves the mouse

See Also
MouseEvent
eventType_MouseUp = 8

the user release a mouse button

Generated by the EventManager whenever the user releases a mouse button.

See Also
MouseEvent
eventType_MouseDown
onMouseUp()
EventManager.isButtonDown()
eventType_PortDraw = 24

a port needs to be redrawn

Generated by the GraphicsManager whenever it is time to redraw the port

See Also
PortDrawEvent
eventType_PortResized = 15

a port was resized

Generated by the GraphicsManager whenever a port is resized

See Also
PortResizedEvent
eventType_ScrollWheel = 16

the user moved the scroll wheel

Generated by the EventManager whenever the user moves the scroll wheel

See Also
ScrollWheelEvent
eventType_Shutdown = 2

one time application shutdown event

Generated by the TimerManager when a timer fires

See Also
pdg::ShutdownEvent
eventType_SoundEvent = 14

a sound finished or looped

Generated by the SoundManager whenever a sound completes or loops, or when an error prevents a sound from playing

See Also
SoundEvent
eventType_SpriteAnimate = 17

a sprite finished an animation (Optional)

Optionally generated by a Sprite whenever it finishes an animation. Emitting this event must be turned on for each Sprite individually.

See Also
SpriteAnimateEvent
eventType_SpriteBreak = 21

joined sprites broke apart (Chipmunk Physics only)

Generated by a Sprite whenever forces acting on it exceed the break force set for a joint.

See Also
SpriteBreakEvent
eventType_SpriteCollide = 20

a collision between sprites

Generated by a Sprite whenever it collides with something

See Also
SpriteCollideEvent
eventType_SpriteLayer = 18

something happening to a sprite layer

Generated by SpriteLayer to give the application a chance to take action during various stages of animation and rendering.

See Also
SpriteLayerEvent
eventType_SpriteTouch = 19

sprite touched event (Optional)

Optionally generated by a Sprite whenever it is clicked on. Emitting this event must be turned on individually for each Sprite.

See Also
SpriteTouchEvent
eventType_Timer = 3

a timer fire event

Generated by the TimerManager when a timer fires

See Also
TimerEvent

User Comments