Jcrop API

Jcrop » API Documentation

jcrop.png

The API allows developers to create custom Jcrop interaction and behaviors.

Features currently supported by the API

  • Alter callback handlers after instantiation
  • Set selection manually
  • Obtain current crop coordinates
  • Animate current selection to new selection

API Invocation Method

As of v0.9.9, to grab a handle to the Jcrop API, use the "ready" callback: 

var jcrop_api;
$('#target').Jcrop(options,function(){
  jcrop_api = this;
});

Please note several things about this pattern:

  • Call within DOM-ready container (not shown) like most jQuery plugins
  • Define the variable in the outer-most scope that you want it to be available
  • All Jcrop callback handlers have the API available as the keyword "this"
  • Callback is not called immediately; Jcrop may take a moment to initialize
  • Do not call methods on the API object until after it has initialized

Deprecated Approach

Another pattern for grabbing the Jcrop API, is as follows: 

$(window).load(function(){
    var api = $.Jcrop(obj,options);
});

Proper values for obj can be a DOM object, a jQuery selector string, or a jQuery object. If the resultant jQuery object contains multiple elements, the first one is used. Options may be specified as the second parameter, see example below.

Important note: you must call the API Invocation Method from within $(window).load() or unexpected behavior may occur.

API Functionality

Setting the Selection

setSelect(array) Set selection, format: [ x,y,x2,y2 ]
animateTo(array) Animate selection to new selection, format: [ x,y,x2,y2 ]

Notice: If you are using scaled images these calls will set based on the true image size.

The selection can also be cleared:

release() Release current selection

Getting the Selection

The Jcrop API provides an alternative to using callbacks by providing methods to query the current selection values.

tellSelect() Query current selection values (true size)
tellScaled() Query current selection values (interface)

Controlling Interactivity

Jcrop can be disabled and re-enabled using these API calls:

disable() Disables Jcrop interactivity
enable() Enables Jcrop interactivity

Jcrop can also be completely removed from the image:

destroy() Remove Jcrop entirely

Example Code 

jQuery(function($){
 
  var jcrop_api;

  $('#target').Jcrop({
    bgColor: 'red'
  },function(){
    jcrop_api = this;
  });

  $('#animbutton').click(function(e){
    jcrop_api.animateTo([ 120,120,80,80 ]);
    return false;
  });

  $('#delselect').click(function(e){
    jcrop_api.release();
    return false;
  });

});
Retrieved from "http://deepliquid.com/content/Jcrop_API.html"