Documentation Selection Events

[awehring]

Version

2.7.0

Test Case

fiddle

Information about environment

Browser

Overview

While working with multi-selections I discovered that the selection functionality is much smarter than I thought. The various selection-events return different usefull properties, depending on the way you (de-)selected objects.
It would be worth to explain this better in the Documenation / Tutorial or as a Demo.
The following is a bit verbose, so that it can be used there.

At the end I propose some minor enhancements / bugs.

TL;DR ? Play the fiddle.

Selecting

You can select fabric.js objects by clicking at an object or by drawing a selection area with the mouse. Objects can be added or removed from the selection by shift-clicking them (hold down the shift-key while clicking).
Clicking at the canvas clears the selection.

Selection Events

There are four events that might be fired, depending on how you selected:

• selection:created After a new selection is created.
• selection:updated After an existing selection is expanded or reduced.
• before:selection:cleared After a selection is cleared, but before the selection-object is destroyed.
• selection:cleared After the selection object is destroyed.

Event Properties

Each event returns one or more properties:

• evt.selected is set when a new selection was created or expanded, with selection:created and selection:updated events
• evt.updated is set when the selection changed, with selection:updated event
• evt.deselected is set when the selection has changed, was reduced or cleared, with selection:created and selection:cleared events
• evt.target holds the (still) selected object(s) after the selection took place, with selection:created , or selection:updated, or before:selection:cleared events

Datatypes

The datatypes of the event-properties are dissimilar.
evt.selected and evt.deselected always holds the object(s) in an array.
selection:updated holds the object directly.
evt.target holds the object directly or holds an ActiveSelection object when more than one object is affected.

Get Current Selection

Besides the event-properties it is allways possible to obtain the currently selected object(s) with two methods:

• Canvas.getActiveObject() Returns the selected object or an ActiveSelection object, when more than one object is selected. Returns undefined or null when nohing is selected.
• Canvas.getActiveObjects() Allways returns an array with the selected object(s). Returns an empty array [ ] when nothing is selected.

Generally the methods return the same objects as the evt.target property. Except for the before:selection:cleared event, when more than one object was deselected (propably a bug, see below).

Event-Properties Table

The table shows which events are triggered by different selection procedures and which properties and objects are returned with the event-object.
The details can be examined with the linked fiddle.

Purpose	Interaction	event	evt.selected	evt.updated	evt.deselected	evt.target	getActiveObject()
Select object	Click object	selection:created	[object]	undefined	undefined	object	object
Select different object	Click different object	selection:updated	[new object]	new object	[old object]	new object	new object
Expand selection	Shift-click different object	selection:updated	[new object]	new object	[ ]	activeSelection {new object, old object}	{new object, old object}
Reduce selection	Shift-click selected object	selection:updated	[ ]	deselected object	[deselected object]	still selected object	still selected object
Deselect	Click canvas (deselect)	before:selection:cleared	undefined	undefined	undefined	old object	old object
		selection:cleared	undefined	undefined	[old object]	undefined	null
Select several objects	Select objects with mouse	selection:created	[new object, new object]	undefined	undefined	activeSelection {new object, new object}	{new object, new object}
Deselect several objects	Click canvas ()	before:selection:cleared	undefined	undefined	undefined	old object (first in collection)	{old object, old object}
		selection:cleared	undefined	undefined	[old object, old object]	undefined	null

Improvements / Bugs

a) The evt.target property after the before:selection:cleared event returns only the first object, when more than one object was deselected. This differs from the Canvas.getActiveObject() method.
Fixed with Version 3.0, issue #5658.

b) The event-properties are either undefined, or null, or an empty array [ ] when no object is returned in the specific case. A unification would be easier.

c) That the event-properties contain the objects as different datatypes is somewhat confusing (object directly, array of objects, ActiveSelection object).

d) Including this information in the Documentation / Tutorial / Demo would help newbies.

I hope this information helps someone to use the wonderfull fabric.js library more effective.

[asturur]

this would be a pretty awesome doc.

Can you old on some days i decided to update to fabric 3.0 and i update the website with what i have, then you can open a pr on fabricjs.com?

[melchiar]

Great doc! Just a thought, perhaps using the term "clear selection" rather than "delete selection" would help to prevent confusion about the objects themselves being deleted. Great work @awehwring!

[awehring]

Thank you for the kind response. :-)

@asturur: Are the sources of the Tutorial and the Demos are somewhere accesible? I think I could contribute to them or update them now and than. I'm not a very experienced JavaScript developer, so I'm afraid to open a PR for the fabric.js sourcecode. Might do more harm than good.

@melchiar: English is a foreign language to me, so I'm happy about any improvements. I updated the initial posting with your suggestion.

[asturur]

English is foreign to me too, and I use Grammarly to get better sentences. It integrates with browsers and teaches you lots of things.

https://github.com/fabricjs/fabricjs.com/ is where the website is stored. Is all plain text so should be fine to add documents. I think it supports MD formatting, so maybe you can just add that or you can eventually make a simple html with it. If you have problems running the website locally let me know.

[asturur]

the discussion about what to fix and improve is valid too, just i do not have time to examinate it and talk about it, but i m sure some points are valid.

[awehring]

Ok, thanks, I'll try to contribute to the website.

[awehring]

a) The evt.target property after the before:selection:cleared event returns only the first object, when more than one object was deselected. This differs from the Canvas.getActiveObject() method.

With fabric.js version 3.0.0 bug a) is fixed; issue #5658.

Updated fiddle using version 3.0.0

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[ShaMan123]

What about this beauty?

[awehring]

ShaMan123, I'm still having this on my todo list. Would like to add it to the official documentation.

But things slip ... 😏

As we are now already in Version 5 with fabricjs, I have to check if it still behaves the same.