JavaScripting

The definitive source of the best
JavaScript libraries, frameworks, and plugins.


  • ×

    jQuery Paint Plugin
    Filed under  › 

    • 🔾23%Overall
    • 315
    • 25.4 days
    • 🕩122
    • 👥3

    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.

    Support

    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

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

    core

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

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

    text

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

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

    <!-- 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>
    

    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.

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

    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.

    $("#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.

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

    Get the image data:

    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.

    $("#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.

    $("#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.

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

    clear

    Clear the canvas manually.

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

    undo / redo

    We can also manually run an undo or redo.

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

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

    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'
    };
    

    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.

    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;
    }
    

    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.

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

    $('#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).

    Resources

    License

    MIT licensed

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

    Show All