Seadragon.Button class

Version 0.8.8 - Back to Seadragon Ajax API Reference

Overview

A utility class for creating interactive and flexible image-based buttons. These buttons have four states:

Rest (the mouse is off this button and off related buttons)
Group (the mouse is off this button but on a related button)
Hover (the mouse is on this button)
Down (the mouse is pressed on this button)

This class requires an image for each state. It encapsulates the transitions between and behavior of these images. In addition, it supports callbacks for five different events:

Press (the mouse is initially pressed on this button)
Release (the mouse was pressed and released on this button)
Click (the mouse was clicked on this button)
Enter (the mouse entered this button, and the mouse is down from this button)
Exit (the mouse exited this button, and the mouse is down from this button)

These events are restricted subsets of the corresponding Seadragon.MouseTracker events. For example, the "release" callback is only fired when the MouseTracker releaseHandler's insideElmtPress and insideElmtRelease are both true. Similarly, the "click" callback is only fired when the MouseTracker clickHandler's quick is true.

To have related buttons function as a group, see the Seadragon.ButtonGroup class.

Constructors

Signature	Description
Seadragon.Button(tooltip, srcRest, srcGroup, srcHover, srcDown, onPress, onRelease, onClick, onEnter, onExit)	Creates a button with the given tooltip, state images and event handlers.

Properties

Name	Type	Description
elmt	HTML Element	The element representing this button. This property is aliased; re-assigning it has no effect, but modifying it does.

Methods

Name and Signature	Return Type	Description
notifyGroupEnter()	-	Notifies this button that the mouse has entered a button group that contains this button. This method is used by the Seadragon.ButtonGroup class.
notifyGroupExit()	-	Notifies this button that the mouse has exited a button group that contains this button. This method is used by the Seadragon.ButtonGroup class.

Example Usage

The following code creates a typical action-on-release button for going home and adds the HTML element as a control to an existing Seadragon viewer. Note that because the action should occur on any release over the button, the function is passed as the release handler and not the click handler. This allows the user to move the mouse and keep it pressed for any period of time before releasing.

If you want to add multiple buttons that are related, see the Seadragon.ButtonGroup example usage.

function goHome() {
    // ...
}

var button = new Seadragon.Button(
    "Go Home",
    "home_rest.png",
   "home_group.png",
   "home_hover.png",
    "home_down.png",
    null,       // do nothing on initialpress
    goHome,     // go home on release
    null,       // no need to use clickthresholds
    null,       // do nothing on enter
    null,       // do nothing on exit
);

viewer.addControl(button.elmt,Seadragon.ControlAnchor.TOP_LEFT);