# odyniec.net

imgAreaSelect Home

# imgAreaSelect Documentation

Last revised: Jun 14, 2011

1. Introduction
2. Basic Usage
3. Options
4. Style Sheets
5. Elements and Classes
6. Callback Functions
7. Keyboard Support
8. API Methods

## Introduction

ImgAreaSelect is a jQuery plugin that lets the user select a rectangular area of an image using a simple and intuitive click-and-drag interface. The plugin can be used in web applications to easily implement image cropping functionality, as well as other features, like photo tagging, image editing functions, etc.

## Basic Usage

The plugin is invoked by calling the `imgAreaSelect()` method on a jQuery object that represents an `<img>` element:

    <script type="text/javascript">
    $(document).ready(function () {
        $('img#photo').imgAreaSelect({
            handles: true,
            onSelectEnd: someFunction
        });
    });
    </script>

If there is more than one element in the jQuery object, the plugin will be enabled for all elements in the set. This applies to non-image elements as well, as imgAreaSelect can actually be used with any block element (e.g., a `<div>` with a background image).

You can initialize the plugin either in the `$(document).ready()` or `$(window).load()` event handler.

## Options

The plugin is highly configurable through the use of options which are passed to the `imgAreaSelect` method when the plugin is initialized. The available options are:

Option | Description
--- | ---
`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 ends default: `false`
`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
`fadeDuration` | If set to a number greater than zero, showing or hiding the plugin is done with a graceful fade in/fade out animation default: `false`
`handles` | If set to `true`, resize handles are shown on the selection area; if set to `"corners"`, only corner handles are shown default: `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)
`instance` | If set to `true`, the `imgAreaSelect()` call returns a reference to an instance of imgAreaSelect bound to the image, allowing you to use its API methods (see below)
`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`
`parent` | A jQuery object or 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`
`remove` | If set to `true`, the plugin is completely removed
`resizable` | Determines whether the selection area should be resizable default: `true`
`resizeMargin` | Width (in pixels) of the selection area margin where resize mode is triggered
`show` | If set to `true`, selection area is shown
`x1` `y1` | Coordinates of the top left corner of the initial selection area
`x2` `y2` | Coordinates of the bottom right corner of the initial selection area
`zIndex` | The z-index 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
`onInit` | Callback function called when the plugin is initialized (see below)
`onSelectStart` | Callback function called when selection starts (see below)
`onSelectChange` | Callback function called when selection changes (see below)
`onSelectEnd` | Callback function called when selection ends (see below)

### Styling Options (Deprecated)

Prior to imgAreaSelect version 0.9, the default method of changing the plugin's appearance was with the use of "styling" options, which are listed below. These options are now deprecated in favor of style sheets, but they are still supported (mainly for backwards compatibility). If you intend to use these options with a recent version of the plugin, you need to include the `imgareaselect-deprecated.css` style sheet in your page.

Option | Description
--- | ---
`borderColor1` `borderColor2` | selection border colors
`borderOpacity` | selection border opacity
`borderWidth` | selection border width (in pixels)
`outerColor` | outer (unselected) area color
`outerOpacity` | outer area opacity
`selectionColor` | selection area color
`selectionOpacity` | selection area opacity

Please note that these options might be removed in a future version of the plugin, so it's strongly recommended to use style sheets instead.

## Style Sheets

Three style sheets are distributed with the plugin:

- `imgareaselect-default.css` – the default style sheet,
- `imgareaselect-animated.css` – same as `imgareaselect-default.css`, except it makes the selection area border animated,
- `imgareaselect-deprecated.css` – this style sheet should only be applied if you want to use the deprecated styling options.

You only need to include one of these in your page header. There are also four GIF files in the `css` folder of the distribution package (`border-h.gif`, `border-v.gif`, `border-anim-h.gif`, and `border-anim-v.gif`). These files are used to render the selection area border, and should be placed in the same directory as the style sheet.

## Elements and Classes

The plugin creates several `div` elements that represent the selection area, the borders, the resize handles, and the outer (unselected) area. These elements are assigned specific class names, so you can access them easily with CSS or jQuery selectors.

Class Name | Assigned to
--- | ---
`imgareaselect-selection` | the selection area
`imgareaselect-border1` `imgareaselect-border2` `imgareaselect-border3` `imgareaselect-border4` | the selection border, composed of four `div`s placed on top of each other
`imgareaselect-handle` | the resize handles (four or eight `div`s, or none if handles are not enabled)
`imgareaselect-outer` | the outer area, composed of four `div`s

This picture should give you a basic idea of how the plugin elements are positioned:

The default `"imgareaselect"` class name prefix can be changed to something else using the `classPrefix` option. This might be useful when there are multiple instances of imgAreaSelect on one page and you want to apply different CSS styles to each of them.

## Callback Functions

The callback functions (set with the `onInit`, `onSelectStart`, `onSelectChange`, and `onSelectEnd` options) are passed two arguments. First argument is a reference to the image that the plugin is attached to, the second is an object representing the current selection. The object has six properties:

Property | Description
--- | ---
`x1` `y1` | coordinates of the top left corner of the selected area
`x2` `y2` | 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 will be executed on selection end:

    $('img#photo').imgAreaSelect({
        onSelectEnd: function (img, selection) {
            alert('width: ' + selection.width + '; height: ' + selection.height);
        }
    });

## 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:

Key | Action
--- | ---
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:

Property | Description
--- | ---
`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.

If there is more than one instance of imgAreaSelect on the page initialized with the `keys` option, only one of them can be controlled with the keyboard at any moment. By default, any user action (selection area resize/move) or reinvocation of the `imgAreaSelect()` method on a plugin instance makes it the keyboard-controlled one.

## API Methods

Several API methods are provided to make it easier to extend the plugin and to integrate it with other web application components.

In order to use these methods, you need an instance of the plugin's object. To get one, call the `imgAreaSelect()` method with the `instance` option set to `true`:

    var ias = $('#photo').imgAreaSelect({ instance: true });

Now, you can use this object to call the public methods. For example, to set a predefined selection area:

    ias.setSelection(50, 50, 150, 200, true);
    ias.setOptions({ show: true });
    ias.update();

Note that you should only use the instance after the plugin has been fully initialized, i.e. in the `onInit` callback function, or anytime after `onInit` has been triggered.

The following methods are available:

Method | Description
--- | ---
`getOptions` | `getOptions()` Get current options Returns: An object containing the set of options currently in use
`setOptions` | `setOptions(newOptions)` Set plugin options Parameters: `newOptions` – The new options object
`getSelection` | `getSelection([noScale])` Get the current selection Parameters: `noScale` (optional) – If set to `true`, scaling is not applied to the returned selection Returns: Selection object
`setSelection` | `setSelection(x1, y1, x2, y2, [noScale])` Set the current selection Parameters: `x1` – X coordinate of the top left corner of the selection area `y1` – Y coordinate of the top left corner of the selection area `x2` – X coordinate of the bottom right corner of the selection area `y2` – Y coordinate of the bottom right corner of the selection area `noScale` (optional) – If set to `true`, scaling is not applied to the new selection Note: This method only sets the internal representation of selection in the plugin instance, it does not update the visual interface. If you want the new selection to be shown, call `update()` right after `setSelection()`. Also make sure that the `show` option is set to `true`.
`cancelSelection` | `cancelSelection()` Cancel the current selection Note: This method hides the selection/outer area, so no call to `update()` is necessary (as opposed to `setSelection()`).
`update` | `update([resetKeyPress])` Update plugin elements Parameters: `resetKeyPress` (optional) – If set to `false`, this instance's `keypress` event handler is not activated