A jQuery paint plugin for a simple drawing surface that you can easily pop into your pages, similar to the basic windows paint program.
- wScratchPad - Plugin simulating scratch card.
- wColorPicker - Color pallette seleciton plugin.
If you enjoy this plugin please leave a small contribution on Gittip. I work on these plugins completely in my free time and any contribution is greatly appreciated.
Settings are available per plugin. Meaning only when that plugin is included will those settings be available.
$.fn.wPaint.defaults = {
theme: 'standard classic', // set theme
autoScaleImage: true, // auto scale images to size of canvas (fg and bg)
autoCenterImage: true, // auto center images (fg and bg, default is left/top corner)
menuHandle: true, // setting to false will means menus cannot be dragged around
menuOrientation: 'horizontal', // menu alignment (horizontal,vertical)
menuOffsetLeft: 5, // left offset of primary menu
menuOffsetTop: 5, // top offset of primary menu
bg: null, // set bg on init
image: null, // set image on init
onShapeDown: null, // callback for draw down event
onShapeMove: null, // callback for draw move event
onShapeUp: null // callback for draw up event
};$.extend($.fn.wPaint.defaults, {
mode: 'pencil', // set mode
lineWidth: '3', // starting line width
fillStyle: '#FFFFFF', // starting fill style
strokeStyle: '#FFFF00' // start stroke style
});$.extend($.fn.wPaint.defaults, {
fontSize : '12', // current font size for text input
fontFamily : 'Arial', // active font family for text input
fontBold : false, // text input bold enable/disable
fontItalic : false, // text input italic enable/disable
fontUnderline : false // text input italic enable/disable
});No settings.
Note that the callbacks for file are user generated for the most part as they deal heavily with client/server side code. You can view the demo code to get a feeling for how they might be setup.
$.extend($.fn.wPaint.defaults, {
saveImg: null, // callback triggerd on image save
loadImgFg: null, // callback triggered on image fg
loadImgBg: null // callback triggerd on image bg
});To start, you will need to include any dependencies (the paths and versions may differ):
<!-- jQuery -->
<script type="text/javascript" src="./lib/jquery.1.10.2.min.js"></script>
<!-- jQuery UI -->
<script type="text/javascript" src="./lib/jquery.ui.core.1.10.3.min.js"></script>
<script type="text/javascript" src="./lib/jquery.ui.widget.1.10.3.min.js"></script>
<script type="text/javascript" src="./lib/jquery.ui.mouse.1.10.3.min.js"></script>
<script type="text/javascript" src="./lib/jquery.ui.draggable.1.10.3.min.js"></script>
<!-- wColorPicker -->
<link rel="Stylesheet" type="text/css" href="./lib/wColorPicker.min.css" />
<script type="text/javascript" src="./lib/wColorPicker.min.js"></script>Then you need to include the wPaint core files:
<link rel="Stylesheet" type="text/css" href="./wPaint.min.css" />
<script type="text/javascript" src="./wPaint.min.js"></script>From here we will need to include plugin files for whatever menu icons we would like to support. This can include the plugins provided with the release of this plugin or any additional plugins that you can write on your own.
<script type="text/javascript" src="./plugins/main/wPaint.menu.main.min.js"></script>
<script type="text/javascript" src="./plugins/text/wPaint.menu.text.min.js"></script>
<script type="text/javascript" src="./plugins/shapes/wPaint.menu.main.shapes.min.js"></script>
<script type="text/javascript" src="./plugins/file/wPaint.menu.main.file.min.js"></script>If you are putting wPaint into a path other than root (most likely you will) then you will need to set the path option since the image and cursor icon paths are set in the JavaScript and not in CSS. This means we can not make them relative from the included file like we can in the CSS file but rather relative to the dispalying page. The default path is just the root folder / but a path can be set for wpaint.
$('#wPaint').wPaint({
path: '/js/lib/wPaint/'
});There have been many questions regarding saving / loading images using wPaint. Loading images CANNOT be done locally or from other domains due to browser restrictions with cross origin policies. There are some potential workarounds for this using CORS but this has not been implemented yet.
As it stands the best approach to this is to first upload the image to your server, save it, then use the url from your server to set images in the future. You can check the upload.php file in the test folder with a php example for saving an image. However note that saving the image on your server will depend on the language/framework being used.
With this release multiple themeing has been introduced by simply space separating multiple theme keywords. For example 'standard classic'. This is to allow us to theme colours and sizes separately and use them interchangeably.
$("#elem").wPaint({
theme: 'standard classic'
});Set image on the fly. This can be a base64 encoded image or simply a path to any image on the same domain.
$('#wPaint').wPaint('image', '<image_data>');Get the image data:
var imageData = $("#wPaint").wPaint("image");
$("#canvasImage").attr('src', imageData);There are three callbacks available for each drawing operation of down, move, and up. Available is the this object which refers to the wPaint object and gives access to all internal functions.
$("#elem").wPaint({
onDrawDown: function (e) {
console.log(this.settings.mode + ": " + e.pageX + ',' + e.pageY);
},
onDrawMove: function (e) {
console.log(this.settings.mode + ": " + e.pageX + ',' + e.pageY);
},
onDrawUp: function (e) {
console.log(this.settings.mode + ": " + e.pageX + ',' + e.pageY);
}
});Set the image or background with an image or color at any time.
$("#wPaint").wPaint({
image: './some/path/imagepreload.png',
bg: '#ff0000'
});In case you want to resize your canvas there is a resize utility function available. Call this after you change the dimensions of your canvas element. Check the test/fullscreen.html demo for sample code.
$("#wPaint").wPaint('resize');Clear the canvas manually.
$('#wPaint').wPaint('clear');We can also manually run an undo or redo.
$('#wPaint').wPaint('undo');
$('#wPaint').wPaint('redo');With version 2.0 wPaint can now easily be extended by setting all or some of the following properties:
// add menu
$.fn.wPaint.menus.main = {
img: '/plugins/main/img/icons-menu-main.png',
items: {
undo: {
icon: 'generic',
title: 'Undo',
index: 0,
callback: function () { this.undo(); }
}
}
// extend cursors
$.extend($.fn.wPaint.cursors, {
pencil: 'url("/plugins/main/img/cursor-pencil.png") 0 11.99, default',
});
// extend defaults
$.extend($.fn.wPaint.defaults, {
mode: 'pencil', // set mode
lineWidth: '3', // starting line width
fillStyle: '#FFFFFF', // starting fill style
strokeStyle: '#FFFF00' // start stroke style
});
// extend functions
$.fn.wPaint.extend({
undo: function () {
if (this.undoArray[this.undoCurrent - 1]) {
this._setUndo(--this.undoCurrent);
}
this._undoToggleIcons();
}
});When calling the $.fn.wPaint.extend() function the values for functions will not override the existing functions but just extend them with duck punching technique. This means the original funciton will always run followed by your extended function.
This allows us to just string multiple generate or init functions together and not have to worry about overwriting any code.
The first menu appended will always automatically become the primary menu meaning it is the one displayed on init. All other menus will become secondary menus meaning they are toggled by icons.
We can extend, modify or add items in the menu by updating the object we want. So for instance if we want to add a new icon to the main menu we could just do:
$.fn.wPaint.menus.main.items.undo = {
// set properties here
};Likewise we can overwrite or add properties to an existing object. For instance below we modified the title and added the after property to change the position in which the undo icon will appear in the menu.
$.fn.wPaint.menus.main.items.undo = {
title: 'Undo at your own risk',
after: 'clear'
};Below is just a sample to list all possible icon properties. Note that the icon name such as undo is the key name used for CSS styling and internal naming.
undo: {
// The icon sets the type of icon we want to generate
// below are the available types that come out of the box.
//
// generic: just runs a callback and nothing else
// activate: runs callback and activates (highlights)
// colorPicker: generates a color picker
// select: generates a select box (list)
// toggle: toggles on/off returns true or false
// menu: toggles secondary menu (icon/menu name must match)
icon: 'generic',
// Set a group for an icon turning it into a stacked
// group select (list). All icons with this group name will
// be appended to that select list. If not set the icon will
// just be standalone.
group: null,
// Set placement of icon in reference to another icon
after: 'clear',
// Title displayed on hover.
title: 'Undo',
// set an alternate image path to use for this icon
img: '/som/path.png',
// Index position in image file starting from 0
index: 0,
// a range of values to use for a select icon
range: [1, 2, 3, 4, 5],
// User range will set the value of the range as the
// css property based on the name of the icon. For instance
// if the icon is fontFamily that css property will get set.
useRange: true,
// The default value to set for this icon. This of course
// can be overridden using `set` calls on init.
value: 3,
// Callback when icon is clicked.
callback: function () { this.undo(); }
}If you want to create a new icon type you will need to extend wPaint to include processing for this new icon. A funciton in the form below should be written:
_createIconType: function (item) {
// Get your started with a base icon.
var $icon = this._createIconBase(item);
// Return the icon with whatever functionality
// you want to add to it.
return $icon;
}Images for each plugin should be kept in one file and can be either specificed by the img value on the top level and can be overriden at the icon level. Each icon should also specify an index value as to the position of the icon in the image starting from 0. Icons should alll be the same size and dimensions should be set in the size theme.
$.fn.wPaint.menus.main.items.undo = {
img: '/plugins/main/img/icons-menu-main.png',
items: {
undo: {
icon: 'generic',
title: 'Undo',
img: '/some/other/path.png'
index: 0,
callback: function () { this.undo(); }
}
}There is now a master cursors object used to store cursor references.
We can sepcify the cursor to use by calling setCursor() and passing the cursor name to use. Note that this is a set function and we can set the cursor at any time.
$('#wPaint').wPaint('cursor', 'rocket');Note that when you are setting the position of the cursor never set it to the exact dimension. For instance if the iamge is 12x12 and you want it's position to be 12 set it to 11.99. This is do to some strange bug in Chrome which will not position the curosr if set exactly.
Thanks to everyone who has contribute code in the previous version and has showed interest in the plugin. Below is some thanks and attribution for code used in this plugin (if I left you out please let me know).
- More jQuery plugins by Websanova
- Websanova JavaScript Extensions Project
- jQuery Plugin Development Boilerplate
- The Ultimate Guide to Writing jQuery Plugins
MIT licensed
Copyright (C) 2011-2012 Websanova http://www.websanova.com