Class pwlib.tools.selection

The selection tool.
Defined in: selection.js.

Class Summary
Constructor Attributes	Constructor Name and Description
	pwlib.tools.selection(app)

Field Summary
Field Attributes	Field Name and Description
<private> <inner>	lastSel The last selection rectangle that was drawn.
<private> <inner>	mouseArea The area type under the current mouse location.
<private> <inner>	mouseResize The resize type.
<private> <inner>	needsRedraw Tells if the drawing canvas needs to be updated or not.
	selection Holds selection information and image.
	state Selection state.
<constant>	STATE_DRAGGING The user is dragging/moving the selection rectangle.
<constant>	STATE_DRAWING The user is drawing a selection.
<constant>	STATE_NONE No selection is available.
<constant>	STATE_PENDING The selection has been dropped, and the mouse button is down.
<constant>	STATE_RESIZING The user is resizing the selection rectangle.
<constant>	STATE_SELECTED The selection rectangle is available.
<private> <inner>	timer The interval ID used for invoking the drawing operation every few milliseconds.
<private> <inner>	x0 Holds the starting point on the `x` axis of the image, for any ongoing operation.
<private> <inner>	y0 Holds the starting point on the `y` axis of the image, for the any ongoing operation.

Method Summary
Method Attributes	Method Name and Description
	activate() The tool activation code.
	clipboardPaste() Paste an image from the "clipboard".
	deactivate() The tool deactivation code.
<private> <inner>	ev_canvasSizeChange(ev) The `canvasSizeChange` application event handler.
<private> <inner>	ev_configChange(ev) The `configChange` application event handler.
	keydown(ev) The `keydown` event handler.
<private> <inner>	marqueeHide() Hide the selection marquee element.
<private> <inner>	marqueeMousedown(ev) The `mousedown` event handler for the selection marquee element.
<private> <inner>	marqueeMousemove(ev) The `mousemove` event handler for the selection marquee element.
<private> <inner>	marqueeMouseup(ev) The `mouseup` event handler for the selection marquee element.
<private> <inner>	mouseAreaUpdate() Determine the are where the mouse is located: if it is inside or outside of the selection rectangle, or on the selection border.
	mousedown(ev) The `mousedown` event handler.
	mousemove(ev) The `mousemove` event handler.
	mouseup(ev) The `mouseup` event handler.
	preActivate() The tool preactivation code.
	selectAll() Select all the entire image.
<private> <inner>	selectionBufferInit() Initialize the selection buffer, when the user starts dragging or resizing the selected pixels.
	selectionCopy() Copy the selected pixels.
	selectionCrop() Crop the image to selection width and height.
	selectionCut() Cut the selected pixels.
	selectionDelete() Perform selection delete.
<private> <inner>	selectionDrag() Perform the selection drag operation.
<private> <inner>	selectionDraw() Perform the selection rectangle drawing operation.
	selectionDrop() Drop the current selection.
	selectionFill() Fill the available selection with the current `bufferContext.fillStyle`.
	selectionMerge() Merge the selection buffer onto the current image layer.
<private> <inner>	selectionMergeStrict() Perform the selection buffer merge onto the current image layer.
<private> <inner>	selectionResize() Perform the selection resize operation.
<private> <inner>	timerFn() The timer function.

Class Detail

pwlib.tools.selection(app)

Parameters:
{PaintWeb} app: Reference to the main paint application object.

Field Detail

<private> <inner> {Object} lastSel

The last selection rectangle that was drawn. This is used by the selection drawing functions.

<private> <inner> {String} mouseArea

The area type under the current mouse location.

When the selection is available the mouse location can be on top/inside the selection rectangle, on the border of the selection, or outside the selection.

Possible values: 'in', 'out', 'border'.

Default Value:: 'out'

<private> <inner> {String} mouseResize

The resize type. If the mouse is on top of the selection border, then the selection can be resized. The direction of the resize operation is determined by the location of the mouse.

While the user resizes the selection this variable can hold the following values: 'n' (North), 'ne' (North-East), 'e' (East), 'se' (South-East), 's' (South), 'sw' (South-West), 'w' (West), 'nw' (North-West).

Default Value:: null

<private> <inner> {Boolean} needsRedraw

Tells if the drawing canvas needs to be updated or not.

Default Value:: false

{Object} selection

Holds selection information and image.

{Number} state

Selection state. Known states:

pwlib.tools.selection#STATE_PENDING - Selection dropped after the mousedown event is fired. The script can switch to STATE_DRAWING if the mouse moves, or to STATE_NONE if it does not (allowing the user to drop the selection).
pwlib.tools.selection#STATE_NONE - No selection is available.
pwlib.tools.selection#STATE_DRAWING - The user is drawing the selection rectangle.
pwlib.tools.selection#STATE_SELECTED - The selection rectangle is available.
pwlib.tools.selection#STATE_DRAGGING - The user is dragging/moving the current selection.
pwlib.tools.selection#STATE_RESIZING - The user is resizing the current selection.

Default Value:: STATE_NONE

<constant> STATE_DRAGGING

The user is dragging/moving the selection rectangle.

<constant> STATE_DRAWING

The user is drawing a selection.

<constant> STATE_NONE

No selection is available.

<constant> STATE_PENDING

The selection has been dropped, and the mouse button is down. The user has two choices: he releases the mouse button, thus the selection is dropped and the tool switches to STATE_NONE, or he moves the mouse in order to start a new selection (STATE_DRAWING).

<constant> STATE_RESIZING

The user is resizing the selection rectangle.

<constant> STATE_SELECTED

The selection rectangle is available.

<private> <inner> timer

The interval ID used for invoking the drawing operation every few milliseconds.

See:: PaintWeb.config.toolDrawDelay

<private> <inner> {Number} x0

Holds the starting point on the x axis of the image, for any ongoing operation.

<private> <inner> {Number} y0

Holds the starting point on the y axis of the image, for the any ongoing operation.

Method Detail

activate()

The tool activation code. This method sets-up multiple event listeners for several target objects.

{Boolean} clipboardPaste()

Paste an image from the "clipboard". The PaintWeb#clipboard object must be an ImageData. This method will generate a new selection which will hold the pasted image.

The pwlib.appEvent.selectionChange application event is dispatched.

If the PaintWeb.config.selection.transform value is false, then it becomes true. The pwlib.appEvent.configChange application is then dispatched.

Returns:: {Boolean} True if the operation was successful, or false if not.

deactivate()

The tool deactivation code. This removes all event listeners and cleans up the document.

<private> <inner> ev_canvasSizeChange(ev)

The canvasSizeChange application event handler. This method makes sure the selection size stays in sync.

Parameters:
{pwlib.appEvent.canvasSizeChange} ev: The application event object.

<private> <inner> ev_configChange(ev)

The configChange application event handler. This method makes sure that changes to the selection transparency configuration option are applied.

Parameters:
{pwlib.appEvent.configChange} ev: The application event object.

{Boolean} keydown(ev)

The keydown event handler. This method calls selection-related commands associated to keyboard shortcuts.

Parameters:
{Event} ev: The DOM Event object.

Returns:: {Boolean} True if the keyboard shortcut was recognized, or false if not.

See:: PaintWeb.config.selection.keys holds the keyboard shortcuts configuration.

<private> <inner> marqueeHide()

Hide the selection marquee element.

<private> <inner> marqueeMousedown(ev)

The mousedown event handler for the selection marquee element.

Parameters:
{Event} ev: The DOM Event object.

<private> <inner> marqueeMousemove(ev)

The mousemove event handler for the selection marquee element.

Parameters:
{Event} ev: The DOM Event object.

<private> <inner> marqueeMouseup(ev)

The mouseup event handler for the selection marquee element.

Parameters:
{Event} ev: The DOM Event object.

<private> <inner> mouseAreaUpdate()

Determine the are where the mouse is located: if it is inside or outside of the selection rectangle, or on the selection border.

mousedown(ev)

The mousedown event handler. Depending on the mouse location, this method does initiate different selection operations: drawing, dropping, dragging or resizing.

Hold the Control key down to temporarily toggle the transformation mode.

Parameters:
{Event} ev: The DOM Event object.

mousemove(ev)

The mousemove event handler.

Parameters:
{Event} ev: The DOM Event object.

mouseup(ev)

The mouseup event handler. This method ends any selection operation.

This method dispatches the pwlib.appEvent.selectionChange application event when the selection state is changed or when the selection size/location is updated.

Parameters:
{Event} ev: The DOM Event object.

{Boolean} preActivate()

The tool preactivation code. This function prepares the selection canvas element.

Returns:: {Boolean} True if the activation did not fail, or false otherwise. If false is returned, the selection tool cannot be activated.

{Boolean} selectAll()

Select all the entire image.

This method dispatches the pwlib.appEvent.selectionChange application event.

Returns:: {Boolean} True if the operation was successful, or false if not.

<private> <inner> selectionBufferInit()

Initialize the selection buffer, when the user starts dragging or resizing the selected pixels.

{Boolean} selectionCopy()

Copy the selected pixels. The associated ImageData is stored in PaintWeb#clipboard.

This method dispatches the pwlib.appEvent.clipboardUpdate application event.

Returns:: {Boolean} True if the operation was successful, or false if not.

{Boolean} selectionCrop()

Crop the image to selection width and height. The selected pixels become the image itself.

This method invokes the this#selectionMerge and PaintWeb#imageCrop methods.

Returns:: {Boolean} True if the operation was successful, or false if not.

{Boolean} selectionCut()

Cut the selected pixels. The associated ImageData is stored in PaintWeb#clipboard.

This method dispatches two application events: pwlib.appEvent.clipboardUpdate and pwlib.appEvent.selectionChange.

Returns:: {Boolean} True if the operation was successful, or false if not.

{Boolean} selectionDelete()

Perform selection delete.

This method changes the PaintWeb.config.selection.transform value to false if the current selection has pixels that are currently being manipulated. In such cases, the pwlib.appEvent.configChange application event is also dispatched.

Returns:: {Boolean} True if the operation was successful, or false if not.

<private> <inner> {false|Array} selectionDrag()

Perform the selection drag operation.

Returns:: {false|Array} False is returned if the selection is too small, otherwise an array of two elements is returned. The array holds the selection coordinates, x and y.

<private> <inner> selectionDraw()

Perform the selection rectangle drawing operation.

{Boolean} selectionDrop()

Drop the current selection.

This method dispatches the pwlib.appEvent.selectionChange application event.

Returns:: {Boolean} True if the operation was successful, or false if not.

{Boolean} selectionFill()

Fill the available selection with the current bufferContext.fillStyle.

Returns:: {Boolean} True if the operation was successful, or false if not.

{Boolean} selectionMerge()

Merge the selection buffer onto the current image layer.

This method dispatches the pwlib.appEvent.selectionChange application event.

Returns:: {Boolean} True if the operation was successful, or false if not.

<private> <inner> selectionMergeStrict()

Perform the selection buffer merge onto the current image layer.

<private> <inner> {false|Array} selectionResize()

Perform the selection resize operation.

Returns:: {false|Array} False is returned if the selection is too small, otherwise an array of four elements is returned. The array holds the selection information: x, y, width and height.

<private> <inner> timerFn()

The timer function. When the mouse button is down, this method performs the dragging/resizing operation. When the mouse button is not down, this method simply tracks the mouse location for the purpose of determining the area being pointed at: the selection, the borders, or if the mouse is outside the selection.

Classes

Class pwlib.tools.selection