Web Sketchpad Document Event API

Version 4.8.0

Introduction

The Document Event API emits custom DOM events via the jQuery.trigger() API.

Document Events

Event Parameters

Each event generated by Document Event API is associated with two sets of parameters:

canvasDOMNode.on(events, handler)

handler(event, context, attributes) { ... }

event

This event object contains data on the event itself that was triggered.

type

context

attributes

Events

Document Load

Events sent during Web Sketch creation.

• LoadDocument.WSP

  Sent when the sketchpad document has finished loading, but before the sketch page has loaded.

• UnloadDocument.WSP

  Sent when the sketchpad document still exists, but is just about to be unloaded.

Re-ordering, Adding, and Removing Tools

Events sent when tools are re-ordered, added, or removed.

• ToolMoved.WSP

  Sent when a tool has been moved to a different index in the tools array.

  attributes

  • tool.nameThe name of the added tool.
  • oldIndexThe tool's original index in the tools array.
  • newIndexThe tool's new index in the tools array.
• ToolPagesChanged.WSP

  Sent when a tool's list of active pages has changed.

  attributes

  • tool.nameThe name of the tool.
  • activePagesString containing "none", "all", or a comma-separated list of page numbers.
  • newIndexThe tool's new index in the tools array.
• ToolAdded.WSP

  Sent when a tool has been added to the document, at the end of the tools array.

  attributes

  • tool.nameThe name of the added tool.
  • indexThe index of the new tool in the doc's tools object.
• ToolRemoved.WSP

  Sent when a tool is removed from the document.

  attributes

  • tool.nameThe name of the removed tool.
  • indexThe index in the tools array from which the tool was removed.

Page Loading and Starting

Events sent during page change. The current page can change, but a given page can start and stop (even without page switch).

The event order switching from an old page to a new page is

1. WillChangeCurrentPage
2. StopCurrentPage (old page)
3. UnloadPage (old page; implementation might delay unloading until anytime before document unload)
4. LoadPage (new page; if the page isn't already loaded)
5. StartCurrentPage (new page)
6. DidChangeCurrentPage (new page)

• DidChangeCurrentPage.WSP

  Sent when the document has changed to a new page

  context

  • sQuery - querying object for current/new page

  attributes

  • pageId - index of the new current page
  • oldPageId - index of the old page
• LoadPage.WSP

  Sent when a page loads, before it starts

  context

  • sQuery - querying object for current/new page

  attributes

  • pageId - index of the page that was loaded into the sketch
• StartCurrentPage.WSP

  Sent just after the start of the current page.

  context

  • sQuery - querying object for current/new page

  attributes

  • pageId - index of the page being started
• StopCurrentPage.WSP

  Sent just before the stop of the current page.

  attributes

  • pageId - index of the page being stopped
• UnloadPage.WSP

  Sent to a page when it still exists, just before it unloads

  context

  • sQuery - querying object for current/new page

  attributes

  • pageId - index of the page that was loaded into the sketch
• WillChangeCurrentPage.WSP

  Sent when the current page will be changed, before it has stopped

  attributes

  • newPageId - index of page that will become current
  • pageId - index of page that will change

Page Events

These are document-level events related to the current page.

• WillPlayTool.WSP

  Sent when the user activates a tool by tapping it in the toolbox.

  attributes

  • tool.nameThe name of the tool played.
  • deltaThe sketch changes since the sketch was begun, or since the last tool was played, whichever is later. This delta will be included in the delta reported by ToolPlayed.WSP.
• ToolPlayed.WSP

  Sent after the user confirms a tool, either by matching all its givens or clicking the confirm tool button.

  attributes

  • tool.nameThe name of the tool played.
  • deltaThe sketch changes since the sketch was begun, or since the last tool was played, whichever is later. This delta includes the preToolDelta.
• ToolAborted.WSP

  Sent after the user cancels a tool, either by pressing the Cancel tool button or by choosing a different tool without having matched any givens for the current tool.

  attributes

  • tool.nameThe name of the canceled tool.
• WillUndoRedo.WSP

  Sent just before the user performs an undo or a redo.

  attributes

  • type - "undo" or "redo"
  • context - optional informational string
• UndoRedo.WSP

  Sent after the user performs an undo or a redo.

  attributes

  • type - "undo" or "redo"
  • context - optional informational string describing what the user was undoing or redoing.
• DeleteGObjs.WSP

  Sent after the user deletes an object and its descendants.

  attributes

  • deleted gobjs - A list of the objects that were just deleted
  • delta - a record of the changes to the sketch resulting from the deletion.
• ClearTraces.WSP

  Sent after the user clears the traces.

  context

  • document - the sketch document

  attributes

  • pageId - The id of the page on which traces were cleared

Page Level sQuery events

These are document-level events related to sQuery sketch object events. sQuery events are used to monitor changes in sketch geometry (including objects not changing directly because of user interaction). sQuery events come in batches which conceptually happen at the same time, so we bracket those batches with document-level frame events, so that clients can know, for example, when a given batch of events is over.

• StartSketchFrame.WSP

  Sent before a batch of sQuery event callbacks are called

• EndSketchFrame.WSP

  Sent after a batch of sQuery event callbacks are called.

Interacting with Objects

Events sent when a user touches a sketch object, and taps, moves or changes it.

Tapping Objects

Events sent when a user taps a sketch object.

• Tap.WSP

  A tap occurred.

  context

  • secondaries - list of objects that were close enough to be hit by the tap, but not actually hit by it.

Dragging Objects

Events sent when a user touches a sketch object, and drags it around.

• StartDrag.WSP

  An object touch has begun. A touch can end with a Tap event, an EndDrag event, or a MergeGobjs event.

  StartDragConfirmed.WSP

  An object drag has begun

  MoveDrag.WSP

  An object drag continues

  EndDrag.WSP

  An object drag has ended

Manipulating Objects

Events sent when a user intereacts with an object and changes it or triggers object specific behavior, or when an Animate, Move, or Sequence button is activated (whether directly pressed by the user or indirectly activated by a Presentation button).

• PressButton.WSP

  Sent when the user presses a button, before the results of that button press are processed

  attributes

  • buttonType - type of button being pressed
• EditParameter.WSP

  Sent just after the user changes a parameter value

  attributes

  • oldValue - original value of the parameter
  • expression - the text entered into the paramter, which will be evaluated to determine the new value
  • value - current / just updated value of the parameter

Button Activation and Deactivation

Events sent when Animate, Move, or Sequence buttons are activated or deactivated. The events have common properties for context and attributes:

• StartAnimate.WSP, StartMove.WSP, StartSequence.WSP

  Sent when an Animate, Move, or Sequence button is activated, before the results of that button press are processed

  attributes

  • buttonType - type of button being pressed
• EndAnimate.WSP, EndMove.WSP, EndSequence.WSP

  Sent when an Animate, Move, or Sequence button is deactivated. The deactivation may be a result of the button's completing its action, or it may be a result of the user pressing the button (or a parent Presentation button) to stop the button before its animation, movement, or sequence has been completed.

  attributes

  • buttonType - type of button being pressed

Scrolling

Events sent when the user scrolls the sketch content area. The events have common properties for context and attributes:

• StartScroll.WSP

  A scroll has started

  MoveScroll.WSP

  A scroll continues

  EndScroll.WSP

  A scroll has ended

Widget Events

Events sent when the user changes an object's properties (style, trace status, text/label, visibility, or existence) using the object widgets.

• ChangeStyle.WSP

  The point style, line style, or color was changed for one or more objects

  ChangeTraceStatus.WSP

  Tracing was turned on or off for the object

  ChangeLabel.WSP

  The label of the object was changed, or the text of a caption was edited

  ChangeVisibility.WSP

  The visibility of one or more objects was changed

  DeleteGObjs.WSP

  An object (along with all its descendants) was deleted from the sketch

Examples of adding event handlers

• Basic example of Document Event API usage
  

  This basic example shows how we can use the Document Event API to add a sQuery event handler.

  Relevant code from previous example:

  
              $('#Isosceles').on("LoadPage.WSP", function(event, context, attrs) {
                var sQ = context.sQuery;
                // .. bind a update event handler on the sketch object with a certain label ...
                sQ('[label="Score"]').on("update", function(e) {
                  // ... and when the update happens push the new value into a span in the main page.
                  $('#Score').text(e.target.uValue);
                });
              })
            

• Adding different sQuery event handlers on two separate pages
  

  This example shows how to add different sQuery event handlers for each page, using the Document Event API.

  Relevant code from previous example:

  
                $('#QueryingAndInteracting').on("DidChangeCurrentPage.WSP", function(event, context, attrs) {
                var sQ = context.sQuery,
                        t1 = sQ('[label="t[1]"]'),
                        A = sQ('[label="A"]'),
                        j = sQ('[label="j"]'),
                        jColor;
                switch(attrs.pageId){
                    case "1":
                        $('#pushnumber').click(function(event) {
                            var v = parseFloat($('#number').val());
                            t1.value(v);
                        });
                        break;
                    case "2":
                        $('#pushpoint').click(function(event) {
                            var x = parseFloat($('#x').val()),
                                    y = parseFloat($('#y').val()),
                                    val = A.value();
  
                            val.x = x;
                            val.y = y;
                            A.value(val);
                        });
  
                        $('#j').hover(
                                function() {
                                    j.attr("color", "red");
                                },
                                function() {
                                    j.attr("color", jColor);
                                }
                        );
                        break;
                }
            })