Init

1 files changed, 421 insertions, 0 deletions

diff --git a/static/js/wpaint/README.md b/static/js/wpaint/README.md
new file mode 100644
index 0000000..eac4c2a
--- /dev/null
+++ b/static/js/wpaint/README.md
@@ -0,0 +1,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