imgAreaSelect
imgAreaSelect is a jQuery plugin for selecting a rectangular area of an image. It allows web developers to easily implement image cropping functionality, as well as other user interface features, such as photo notes (like those on Flickr).
Example
Click and drag on the image to select a rectangular area.
Selection coordinates:
X1:
Y1:
X2:
Y2:
Selection dimensions:
Width:
Height:
Usage
Download the script, unzip it, and place it
in the <head> section of your HTML document:
<head> ... <script type="text/javascript" src="jquery.imgareaselect-0.8.js"></script> ... </head>
Then, to enable selection on an image, use the imgAreaSelect
method:
<script type="text/javascript"> $(window).load(function () { $('img#example').imgAreaSelect({ handles: true, onSelectEnd: someFunction }); }); </script>
The argument passed to the method is an options object. The available options are:
aspectRatio |
a string of the form "width:height" which represents
the aspect ratio to maintain example: "4:3"
|
autoHide |
if set to true, selection area will disappear
when selection endsdefault: false
|
borderColor1 |
selection border color default: "black"
|
borderColor2 |
selection border color default: "white"
|
borderOpacity |
selection border opacity default: 0.5
|
borderWidth |
selection border width (in pixels) default: 1
|
classPrefix |
a string that is prepended to class names assigned to plugin
elements (see below for details) default: "imgareaselect"
|
disable |
if set to true, the plugin is disabled (the
selection area remains visible, unless hide is also
present)
|
enable |
if set to true, the plugin is re-enabled
|
handles |
if set to true, resize handles are shown on the
selection area; if set to "corners", only corner
handles are showndefault: false
|
hide |
if set to true, selection area is hidden
|
imageHeight |
true height of the image (if scaled with the CSS width
and height properties)
|
imageWidth |
true width of the image (if scaled with the CSS width
and height properties)
|
keys |
enables/disables keyboard support (see below for details) default: false
|
maxHeight |
maximum selection height (in pixels) |
maxWidth |
maximum selection width (in pixels) |
minHeight |
minimum selection height (in pixels) |
minWidth |
minimum selection width (in pixels) |
movable |
determines whether the selection area should be movable default: true
|
outerColor |
outer (unselected) area color default: "black"
|
outerOpacity |
outer area opacity default: 0.2
|
parent |
a jQuery selector string that specifies the parent element that
the plugin will be appended to default: "body"
|
persistent |
if set to true, clicking outside the selection area
will not start a new selection (ie. the user will only be able to
move/resize the existing selection area)default: false
|
resizable |
determines whether the selection area should be resizable default: true
|
selectionColor |
selection area color default: "white"
|
selectionOpacity |
selection area opacity default: 0
|
show |
if set to true, selection area is shown
|
x1y1 |
coordinates of the top left corner of the initial selection area |
x2y2 |
coordinates of the bottom right corner of the initial selection area |
zIndex |
zIndex value to be assigned to plugin elements; normally, imgAreaSelect figures it out automatically, but there are a few cases when it's necessary to set it explicitly |
onSelectStart |
callback function called when selection starts |
onSelectChange |
callback function called when selection changes |
onSelectEnd |
callback function called when selection ends |
The plugin creates several div elements that represent
the selection area, the borders, the resize handles, and the outer
(unselected) area. These elements have specific class names, so you
can access them with jQuery selectors.
imgareaselect-selection |
the selection area |
imgareaselect-border1imgareaselect-border2
|
the selection border (there are two divs,
one for each color) |
imgareaselect-handle |
the resize handles |
imgareaselect-outer |
the outer area, which is actually composed of
four divs, all sharing the same class name |
Additionally, with the classPrefix option, you can change
the default imgareaselect class name prefix to something
else. This might be useful when you have multiple plugins on one page.
Callback Functions
The callback functions (onSelectStart,
onSelectChange, and onSelectEnd)
are passed two arguments. First argument is a reference to the image,
the second is an object representing the selection.
The object has six properties:
x1y1 |
coordinates of the top left corner of the selected area |
x2y2 |
coordinates of the bottom right corner of the selected area |
width |
selection width |
height |
selection height |
Here's an example of a callback function that might be executed on selection end:
function selectionEnd(img, selection) { alert('width: ' + selection.width + '; height: ' + selection.height); }
Resetting Options Dynamically
If you call the imgAreaSelect method again with a
new set of options, the new options are applied dynamically to the
existing selection. For example, the following code could be used
to implement a button that toggles the selection area on every click:
$('button#toggle').toggle( function () { $('img#example').imgAreaSelect({ show: true }); }, function () { $('img#example').imgAreaSelect({ hide: true }); } );
Keyboard Support
When the keys option is set to true,
the selection area can be moved/resized using the keyboard. By default,
the following keys are used:
| arrow keys | move selection area by 10 pixels |
Shift + arrow keys |
move selection area by 1 pixel |
Ctrl + arrow keys |
resize selection area by 10 pixels |
Shift + Ctrl + arrow keys |
resize selection area by 1 pixel |
You can override these key bindings by setting the keys
option to an object that defines the desired key settings. The object
may have the following properties:
arrows |
defines the behavior of the arrow keys |
shift |
defines the behavior of the Shift key |
ctrl |
defines the behavior of the Ctrl key |
alt |
defines the behavior of the Alt key |
Each of these properties can be set to the number of pixels (≥1)
by which the selection area should
be moved/resized when the specific key is pressed, or the string
"resize", which indicates that the key should switch to
resize mode. Example:
$('img#example').imgAreaSelect({ keys: { arrows: 15, ctrl: 5, shift: 'resize' } });
With these settings, pressing the arrow keys alone will move the selection area by 15 pixels, holding Ctrl will move the area by 5 pixels, and holding Shift will switch to resizing.
Known Issues
Move/resize cursors are not displayed correctly in Opera, and
it seems to be a browser bug (thanks to
Arjan Eising for input on this
issue). Fixed in version 0.7
Download
imgareaselect-0.8.zip – a zip archive containing the plugin source and license files. Minified version included.
License
Dual licensed under the MIT and GPL licenses.
Links
imgAreaSelect on jQuery Plugins
PHP &jQuery
image upload and crop tutorial at WebMotionUK