-
Notifications
You must be signed in to change notification settings - Fork 37
Events System
Diva has a publish/subscribe Events system that allows plugins to hook in at certain points in the document viewing process.
If you are writing your own plugins, you will likely want to subscribe to Events to fire functions in your plugin at the appropriate points, and publish Events to allow Diva and other plugins to react to changes made by your plugin.
diva.Events.publish(topic, args, scope)
Any arguments (args) you supply will be passed to subscribers of the event. Arguments must be passed in as an array.
The scope argument is optional. Using the scope argument, you may supply an Object (for example, the default this) within which the Event can be subscribed to.
For example, we might want to create an Event for when a new page has loaded, and pass the new page index, filename, and selector (stored in the variables pageIndex, filename, and pageSelector respectively) to any subscribers:
diva.Events.publish("PageDidLoad", [pageIndex, filename, pageSelector])
diva.Events.subscribe(topic, callback)
In our PageDidLoad example, we might want to call a function every time a page has loaded:
diva.Events.subscribe("PageDidLoad", highlight)
In the instance above, highlight(pageIndex, filename, pageSelector) will be called every time a page loads. This is because the PageDidLoad event publishes [pageIndex, filename, pageSelector]. For a list of default events and what they publish, see Core Events.
diva.Events.subscribe returns a handle that we can use when unsubscribing from the Event.
diva.Events.unsubscribe(handle, completely)
The handle argument is an array of the form [topic, callback]. In our PageDidLoad example, this array would look like ["PageDidLoad", highlight]. We can pass the handle in manually, or we can use the handle returned by diva.Events.subscribe.
For example, when subscribing, we could write:
var myHandle = diva.Events.subscribe("PageDidLoad", highlight)
Then to unsubscribe from the same event:
diva.Events.unsubscribe(myHandle)
(For further reference, the core of Diva's Events subsystem is located in utils.js on line 700.)
These are the Events that Diva publishes so far. The arguments in brackets are passed to subscribed functions.
Subscribe to these in your plugin, and/or fork diva.js/develop and add more!
Fires when the entire document has finished loading. Passes the page index and filename of the first page to subscribing functions.
Fires when the document viewer has finished loading. Passes the entire settings object to subscribed functions. Note that the settings object is also available from the diva instance by calling $('#diva-wrapper').diva.getSettings();.
Fires when Diva starts preparing the next page to load.
As the next page is entering the Document Viewer Pane, Diva loads the necessary structures to display the page before loading the page itself. This event fires when a page container (a div in HTML) enters the DOM.
Passes the page index, filename, and CSS selector of the <div> element of the page to be loaded.
Fires when a page has finished loading. Passes the page index, filename, and CSS selector of the <div> element of the page to be loaded. Subject to settings.pageLoadTimeout (Document view) or settings.rowLoadTimeout (Grid view), which wait for an interval to see if the user is scrolling past the current page or not.
Fires when Diva switches in and out of fullscreen mode. Passes a boolean that is true if the viewer is entering fullscreen mode, and false if exiting fullscreen mode.
Fires when Diva switches in and out of Grid view. Passes a boolean that is true if the viewer is entering Grid view, and false if exiting Grid view.
If the highlight plugin is loaded, this event fires when the highlight function has finished highlighting the current page. The highlight function is called every time the current page changes, regardless of whether there is anything to be highlighted on the current page (it is itself subscribed to the PageWillLoad event).
CanvasViewDidHide
CanvasViewDidActivate