aboutsummaryrefslogtreecommitdiff
path: root/static/js/wpaint/README.md
blob: eac4c2abc4b641e7f53daaf7475a423fdfa40a58 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
# wPaint.js

A jQuery paint plugin for a simple drawing surface that you can easily pop into your pages, similar to the basic windows paint program.

* [View the wPaint demo](http://wpaint.websanova.com)
* [Download the lastest version of wPaint](https://github.com/websanova/wPaint/tags)


## Related Plugins

* [wScratchPad](http://wscratchpad.websanova.com) - Plugin simulating scratch card.
* [wColorPicker](http://wcolorpicker.websanova.com) - Color pallette seleciton plugin.


## Support 

If you enjoy this plugin please leave a small contribution on [Gittip](https://gittip.com/websanova).  I work on these plugins completely in my free time and any contribution is greatly appreciated.


## Settings

Settings are available per plugin.  Meaning only when that plugin is included will those settings be available.

### core

```js
$.fn.wPaint.defaults = {
  path:            '/',                // set absolute path for images and cursors
  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
  imageStretch:    false,              // stretch smaller images to full canvans dimensions
  onShapeDown:     null,               // callback for draw down event
  onShapeMove:     null,               // callback for draw move event
  onShapeUp:       null                // callback for draw up event
};
```

### main

```js
$.extend($.fn.wPaint.defaults, {
  mode:        'pencil',  // set mode
  lineWidth:   '3',       // starting line width
  fillStyle:   '#FFFFFF', // starting fill style
  strokeStyle: '#FFFF00'  // start stroke style
});
```

### text

```js
$.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
});
```

### shapes

No settings.

### file

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.

```js
$.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
});
```


## Examples

To start, you will need to include any dependencies (the paths and versions may differ):
```html
<!-- 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:
```html
<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.

```html
<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>
```


### path

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.

```js
$('#wPaint').wPaint({
  path: '/js/lib/wPaint/'
});
```


### save / load

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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Same_origin_policy_for_JavaScript) policies.  There are some potential workarounds for this using [CORS](https://developer.mozilla.org/en-US/docs/HTML/CORS_Enabled_Image?redirectlocale=en-US&redirectslug=CORS_Enabled_Image) 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.


### themes

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.

```js
$("#elem").wPaint({
   theme: 'standard classic'
});
```


### image data

Set image on the fly.  This can be a base64 encoded image or simply a path to any image on the same domain.

```js
$('#wPaint').wPaint('image', '<image_data>');
```

Get the image data:

```js
var imageData = $("#wPaint").wPaint("image");
            
$("#canvasImage").attr('src', imageData);
```


### callbacks

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.

```js
$("#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);
    }
});
```


### image / bg

Set the image or background with an image or color at any time.

```js
$("#wPaint").wPaint({
  image: './some/path/imagepreload.png',
  bg: '#ff0000'
});
```


### resize

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.

```js
$("#wPaint").wPaint('resize');
```


### clear

Clear the canvas manually.

```javascript
$('#wPaint').wPaint('clear');
```


### undo / redo

We can also manually run an `undo` or `redo`.

```javascript
$('#wPaint').wPaint('undo');
$('#wPaint').wPaint('redo');
```


## Extending

With version 2.0 wPaint can now easily be extended by setting all or some of the following properties:

```js
// 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();
  }
});
```


### overriding

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.



### menus

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:

```js
$.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.

```js
$.fn.wPaint.menus.main.items.undo = {
  title: 'Undo at your own risk',
  after: 'clear'
};
```


### icon properties

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.

```js
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:

```js
_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;
}
```


### icon images

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.

```js
$.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(); }
    }
}
```


### cursors

There is now a master `cursors` object used to store cursor references.

$.extend($.fn.wPaint.cursors, {
  pencil: 'url("/plugins/main/img/cursor-pencil.png") 0 11.99, default',
});

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.

```js
$('#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

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).

* [Rounded corners and extending Canvas with new shapes](http://js-bits.blogspot.com/2010/07/canvas-rounded-corner-rectangles.html)
* [Nice efficient algorithm for fill tool](http://www.williammalone.com/articles/html5-canvas-javascript-paint-bucket-tool)


## Resources

* [More jQuery plugins by Websanova](http://websanova.com/plugins)
* [Websanova JavaScript Extensions Project](http://websanova.com/extensions)
* [jQuery Plugin Development Boilerplate](http://wboiler.websanova.com)
* [The Ultimate Guide to Writing jQuery Plugins](http://www.websanova.com/blog/jquery/the-ultimate-guide-to-writing-jquery-plugins)


## License

MIT licensed

Copyright (C) 2011-2012 Websanova http://www.websanova.com