RaphBoard · Documentation

Cross-browser drawing board based on
Raphaël JavaScript Vector Library

NOTE: This documentation is still for v1.0.1!!!

So, you wanna know more, oh you nosey you?

Okay, here's a quick API Reference. Open this window while you're playing with yourself in the sandbox.

And while at it, check the Raphaël's documentation too.

Basic stuff

Here's how to start with the RaphBoard:

// v1.0.2
// Attach RaphBoard to the container
$( document ).ready( function( $ ) {
	$( "#board" ).RaphBoard();

	// It can be invoked with options too:
	$( "#board" ).RaphBoard( { "showToolBar": false } );
});

// RaphBoard will take its container's dimensions, so don't hesitate
// to show some style (put this in the <head> section of your page)
<style>
	#board {
		width: 650px;
		height: 380px;
		background-color: black;
	}
</style>

API browser

RaphBoard Object

The main object.

Set RaphBoard's options (defaults)

Parameter(s): Object with key/value pairs or single key/value pair

// Set global options for every new RaphBoard:
$.RaphBoard.options( { "showToolBar": false } );

// Set options during initialization:
var board = $( "#board" ).RaphBoard( { "stroke": "#777" } );

// Set options after RaphBoard initialization:
board.options( { "strokeWidth": 6 } );
board.options( "lineCap", "round" );

Default options and values:

editable: true

Enable or disable editing

May be useful if you want "view only" mode and you load the content via .fromJSON() method or using the board in "non-interactive" mode.

showToolBar: true

Instructs RaphBoard to not render the ToolBar

May be useful if you want to create your own toolbar or use the board in "non-interactive" mode.

fill: "#FFF"

Default fill attribute for shapes

Take a look at Raphaël's Attributes documentation for possible values.

stroke: "#FFF"

Default stroke color

Take a look at Raphaël's Attributes documentation for possible values.

strokeWidth: 1

Default stroke width

RaphBoard uses 4 default strokes that a user can choose from in the AttributesPanel:

  • 1px - default
  • 4px - "medium"
  • 8px - "big"
  • 16px - "huge"

If you set some other value here, it will be overridden by user's selection in AttributesPanel.

Therefore, it only makes sense in "non-interactive" mode.

lineCap: "round"

Default line endigs type

Take a look at Raphaël's Attributes documentation for possible values.

lineJoin: "round"

Default line joining type

Take a look at Raphaël's Attributes documentation for possible values.

arrowEnd: "classic-medium-medium"

Default arrow type-width-length attributes

Take a look at Raphaël's Attributes documentation for possible values.

fontSize: 12

Default text font size

Take a look at Raphaël's Attributes documentation for possible values.

textAnchor: "start"

Default text anchor

Take a look at Raphaël's Attributes documentation for possible values.

animation: { params: {}, ms: 100, easing: "<>" }

Default animation for "move", "undo" and "redo" events

Set to null if no animation required.

Take a look at Raphaël's Animation documentation for possible values.

RaphBoard Event Handling

RaphBoard provides "hooks" to catch interactive drawing events:

  • before_mode_change - called before mode change procedure starts
  • after_mode_change - called after mode change procedure completes
  • before_start - called before drawing procedure starts
  • after_start - called after drawing procedure completes
  • before_change - called before drawing change procedure starts
  • after_change - called after drawing change procedure completes
  • before_end - called before drawing procedure starts
  • after_end - called after drawing procedure completes
  • before_cut - called before cut procedure starts
  • after_cut - called after cut procedure completes
  • before_undo - called before undo procedure starts
  • after_undo - called after undo procedure completes
  • before_redo - called before redo procedure starts
  • after_redo - called after redo procedure completes
  • before_clear - called before clearing procedure starts
  • after_clear - called after clearing procedure completes

At the moment, RaphBoard does NOT use Raphaël's eve event handler. It's planned for future releases.

There are two methods available:

.on( eventType, callback )

Set up event handler

Parameter(s): String, Function

RaphBoard.on( "before_cut", function () {
	return false; // Cancel the operation
} );

Returns: RaphBoard

.off( eventType )

Remove event handler

Parameter(s): String

RaphBoard.off( "before_cut" );

Returns: RaphBoard

.version()

Return RaphBoard's version ( String )

RaphBoard.version();

.UUID()

Return RaphBoard's UUID ( String )

RaphBoard.UUID();

.left()

Return RaphBoard container's offset from the left ( Integer )

RaphBoard.left();

.top()

Return RaphBoard container's offset from the top ( Integer )

RaphBoard.top();

.width()

Return RaphBoard container's width ( Integer )

RaphBoard.width();

.height()

Return RaphBoard container's height ( Integer )

RaphBoard.height();

.isEnabled()

Return RaphBoard's edit status ( Boolean )

RaphBoard.isEnabled();

.canUndo()

Return RaphBoard undo buffer's status ( Boolean )

RaphBoard.canUndo();

.canRedo()

Return RaphBoard redo buffer's status ( Boolean )

RaphBoard.canRedo();

.enable()

Enable editing

Parameter(s): None

Trigger event(s): None

RaphBoard.enable();

Returns: RaphBoard

.disable()

Disable editing

Parameter(s): None

Trigger event(s): None

RaphBoard.disable();

Returns: RaphBoard

.mode( mode )

SET/GET RaphBoard's editing mode ( String )

Parameter(s): String

Trigger event(s): "before_mode_change", "after_mode_change"

// "move|pen|line|arrow|circle|ellipse|rect|text|cut"
RaphBoard.mode( "pen" );

Returns: Mode ( String )

NOTE: If called without parameter, only returns current mode and no event is triggered.

.element( id )

Return RaphBoard's element by it's Id ( Integer )

Parameter(s): Integer

Trigger event(s): None

RaphBoard.element( id );

Returns: Element

.move( id, dx, dy )

Move element

Parameter(s): Integer, Integer, Integer

Trigger event(s): None

RaphBoard.move( redCircle.id, 456, 123 );

Returns: Element

.line( x, y, dx, dy )

Draw a line

Parameter(s): Integer, Integer, Integer, Integer

Trigger event(s): None

RaphBoard.line( 0, 0, 456, 123 );

Returns: Element

NOTE: Set line attributes via RaphBoard.options

.arrow( x, y, dx, dy )

Draw a line with arrow end

Parameter(s): Integer, Integer, Integer, Integer

Trigger event(s): None

RaphBoard.arrow( 0, 0, 456, 123 );

Returns: Element

NOTE: Set arrow attributes via RaphBoard.options

.circle( x, y, r )

Draw a circle

Parameter(s): Integer, Integer, Integer

Trigger event(s): None

RaphBoard.circle( 456, 123, 50 );

Returns: Element

NOTE: Set circle attributes via RaphBoard.options

.ellipse( x, y, rx, ry )

Draw ellipse

Parameter(s): Integer, Integer, Integer, Integer

Trigger event(s): None

RaphBoard.ellipse( 456, 123, 100, 50 );

Returns: Element

NOTE: Set ellipse attributes via RaphBoard.options

.rect( x, y, dx, dy )

Draw a rectangle

Parameter(s): Integer, Integer, Integer, Integer

Trigger event(s): None

RaphBoard.rect( 456, 123, 100, 50 );

Returns: Element

NOTE: Set rectangle attributes via RaphBoard.options

.text( x, y, text, size )

Write a text

Parameter(s): Integer, Integer, String, Integer

Trigger event(s): "after_end"

RaphBoard.text( 456, 123, "Text!", 24 );

Returns: Element

NOTE: Set text attributes via RaphBoard.options

.cut( id )

Cut an element from the canvas

Parameter(s): Integer

Trigger event(s): None

RaphBoard.cut( redCircle.id );

Returns: Boolean true if cut

.toJSON( id, callback )

Return element (by its Id) as JSON string

Parameter(s): Integer, Function to execute on element

Trigger event(s): None

RaphBoard.toJSON( redCircle.id, null );

Returns: JSON string

.fromJSON( elements, callback )

Draw element(s) (as JSON object or string)

Parameter(s): JSON object or string, Function to execute on element

Trigger event(s): None

RaphBoard.fromJSON( jsonDrawing, null );

Returns: None

NOTE: This method has not been fully tested yet.

.undo()

Undo last board action

Parameter(s): None

Trigger event(s): None

RaphBoard.undo();

Returns: RaphBoard

.clearUndo()

Clears the Undo buffer

Parameter(s): None

Trigger event(s): None

RaphBoard.clearUndo();

Returns: RaphBoard

.redo()

Redo last undone board action

Parameter(s): None

Trigger event(s): None

RaphBoard.redo();

Returns: RaphBoard

.clearRedo()

Clears the Redo buffer

Parameter(s): None

Trigger event(s): None

RaphBoard.clearRedo();

Returns: RaphBoard

.indicateUndoRedo()

Indicate Undo/Redo action (if ToolBar is visible)

Parameter(s): None

Trigger event(s): None

RaphBoard.indicateUndoRedo();

Returns: RaphBoard

.clear()

Clear the board

Parameter(s): None

Trigger event(s): None

RaphBoard.clear();

Returns: RaphBoard

NOTE: Does not clear undo/redo buffers.

.flush()

Clear the board and undo/redo buffers

Parameter(s): None

Trigger event(s): None

RaphBoard.flush();

Returns: RaphBoard

NOTE: Clears undo/redo buffers as well.

RaphBoard's canvas object.

This is Raphaël.paper wrapper. See Raphaël's Paper documentation for more info.

.paper()

Return the Raphaël's paper ( Raphael.paper )

Canvas.paper();

RaphBoard's drawing attributes panel object.

The AttributesPanel contains drawing attributes - colors, line width and such.

.paper()

Return the Raphaël's paper object ( Raphael.paper )

AttributesPanel.paper();

.show()

Show Attributes Panel

Parameter(s): None

AttributesPanel.show();

Returns: AttributesPanel

NOTE: It will disable all interactions with board (toolbar and paper).

.hide()

Hide Attributes Panel

Parameter(s): None

AttributesPanel.hide();

Returns: AttributesPanel

NOTE: It will re-enable all interactions with board (toolbar and paper) after .show().

RaphBoard's ToolBar Object

The ToolBar can contain many buttons and they can be selectively shown or hidden, enabled or disabled. See the Button object for more info.

.height()

Return ToolBar's height ( Integer )

ToolBar.height();

.background()

Return ToolBar's background ( Raphael.paper.rect )

ToolBar.background();

.buttons()

Return ToolBar's buttons ( Array )

ToolBar.buttons();

.enable()

Enable ToolBar

Parameter(s): None

ToolBar.enable();

Returns: ToolBar

NOTE: Does not show the ToolBar, just make it responsive (ie. after .disable()).

.disable()

Disable ToolBar

Parameter(s): None

ToolBar.disable();

Returns: ToolBar

NOTE: Does not hide the ToolBar, just make it unresponsive.

.addButton( button )

Add button to ToolBar

Parameter(s): Button

ToolBar.addButton( button );

Returns: ToolBar

.insertButton( button, index )

Insert button in ToolBar at index

Parameter(s): Button, Integer

ToolBar.insertButton( button, 3 );

Returns: ToolBar

.removeButton( button )

Remove button from ToolBar

Parameter(s): Button

ToolBar.removeButton( button );

Returns: ToolBar

.button( name )

Return button referenced by it's name

Parameter(s): String

ToolBar.button( "circle" );

Returns: Button

.deselectAll()

Deselect all buttons in Toolbar

Parameter(s): None

ToolBar.deselectAll();

Returns: ToolBar

NOTE: Does not hide the buttons, just turns off Button's highlight & glow.

ToolBar's Button object.

The ToolBar can contain many buttons and they can be selectively shown, enabled or highlighted. See the ToolBar object for more info on button manipulation.

.isEnabled()

Get button's enabled status ( Boolean )

Button.isEnabled();

.isVisible()

Get button's visible status ( Boolean )

Button.isVisible();

.isSelected()

Get button's selected status ( Boolean )

Button.isSelected();

.name( name )

Get/set button's name ( String )

Button.name( "circle" );

.attr( attr )

Get/set button's attributes ( Object )

Button.attr( { "fill": "rgba( 0, 0, 0, 0 )" } );

.activeIcon()

Get currently active icon ( Icon )

Button.activeIcon();

NOTE: Set the active icon with .showIcon() method.

.hover( handler )

Set/get hover handler ( Function )

Button.hover( function () {} );

.mouseDown( handler )

Set/get mouseDown handler ( Function )

Button.mouseDown( function () {} );

.mouseUp( handler )

Set/get mouseUp handler ( Function )

Button.mouseUp( function () {} );

.addIcon( icon )

Add new Icon to the button

Parameter(s): Icon

Button.addIcon( icon );

Returns: Button

.insertIcon( index, icon )

Insert new Icon in button's icon library

Parameter(s): Integer, Icon

Button.insertIcon( 3, icon );

Returns: Button

.removeIcon( index )

Remove icon from the button

Parameter(s): Integer

Button.removeIcon( 3 );

Returns: Button

.showIcon( index )

Display icon in button's icon library (and hide others)

Parameter(s): Integer

Button.showIcon( 3 );

Returns: Button

.highlight( state, glow )

Add/remove highlight & glow appearance of a button

Parameter(s): Boolean, Boolean

Button.highlight( true, true );

Returns: Button

.enable()

Enable button's event handlers

Parameter(s): None

Button.enable();

Returns: Button

.disable()

Disable button's event handlers

Parameter(s): None

Button.disable();

Returns: Button

.select()

Change the button's appearance to selected

Parameter(s): None

Button.select();

Returns: Button

.deselect()

Change the button's appearance to deselected

Parameter(s): None

Button.deselect();

Returns: Button

Button's Icon Object

The Button can contain many icons and they can be selectively shown or hidden, one at a time - showing one icon will hide others. See the Button object for more info.

.isGlowing()

Return icon glowing status ( Boolean )

ButtonIcon.isGlowing();

.isVisible()

Return icon visible status ( Boolean )

ButtonIcon.isVisible();

.glow( toggle )

Toggle icon glow

Parameter(s): Boolean

ButtonIcon.glow( true );

Returns: Icon

.show()

Show icon

Parameter(s): None

ButtonIcon.show();

Returns: Icon

.hide()

Hide icon

Parameter(s): None

ButtonIcon.hide();

Returns: Icon


Support & Contact

Report intolerances and bugs to the project's issue tracker and pray for mercy,
or share your frustration (yeah, like anyone cares, tsk.)

Copyright & License

Copyright © 2012-2013 Miroslav Hibler.
Licensed by MIT license.