Selection management for editor widgets. More...

#include <Selection.h>

Data Structures
struct	SelectionGroup
	Group of SelectionWidget objects sharing the same selection set. More...

Public Member Functions
	Selection (SelectionWidget< Elem > *w)

void	addToSelection (Elem e)

void	cancelGesture ()
	Cancel any selection gesture (lasso, move, with keyboard or mouse) in progress.

void	clearSelection (bool bCheck=true)

void	dump ()

bool	isLasso () const
	Is there an ongoing lasso gesture?

bool	isMouseGesture () const
	Is there a mouse gesture in progress?

bool	isMoving () const
	Is there an ongoing (and incomplete) selection movement gesture?

bool	isSelected (Elem e) const
	Is an element in the set of currently selected elements?

void	merge (Selection *pOther)
	Merge the selection groups of two Selection widgets.

QPoint	movingOffset () const
	During a selection "move" gesture, return the current movement position relative to the start position, in screen coordinates.

void	paintSelection (QPainter *painter)
	Paint selection-related elements (ie lasso)

void	removeFromSelection (Elem e, bool bCheck=true)

void	updateWidgetGroup ()
	Update any widgets in this selection group.

Raw mouse events
Raw mouse events from Qt. These are handled by a state machine that models the intended user interaction including clicks and drags, with single buttons held down, and translated to meaningful user-level interaction events. These are named identically for the corresponding QWidget event handlers and should be called from those handlers of the SelectionWidget.
void	mousePressEvent (QMouseEvent *ev)

void	mouseMoveEvent (QMouseEvent *ev)

void	mouseReleaseEvent (QMouseEvent *ev)

Higher-level mouse events
These events are synthesised by the MouseState state machine, and are either processed by the SelectionState state machine, or passed to the corresponding event handlers of the SelectionWidget.
void	mouseClick (QMouseEvent *ev)

void	mouseDragStart (QMouseEvent *ev)

void	mouseDragUpdate (QMouseEvent *ev)

void	mouseDragEnd (QMouseEvent *ev=nullptr)

Keyboard interactions
bool	keyPressEvent (QKeyEvent *ev)
	Key press event filter.

void	updateKeyboardCursorPosition (QRect cursor)
	Update the keyboard cursor.

Private Attributes
std::set< Elem >	m_checkpointSelectedElements
	For gestures modifying a selection, store the initial selection set as a checkpoint to restore when rebuilding the selection with the current lasso area.

DragScroller *	m_pDragScroller
	Scroller to use while dragging selections.

SelectionWidget< Elem > *	m_pWidget


std::shared_ptr< SelectionGroup >	m_pSelectionGroup

Mouse state model
The state of the mouse is modeled as a simple state machine to distinguish user-level mouse actions (click, drag) using the information available in the lower-level Qt events (mouse press, release and move). This also filters out the potential ordering effects of non-standard user behaviour, such as pressing multiple mouse buttons at once. The Qt standard drag distance and time are used to identify the transition from a click to a drag.
enum	MouseState { Up , Down , Dragging }

enum Selection::MouseState	m_mouseState

Qt::MouseButton	m_mouseButton
	Mouse button that began the gesture.

QMouseEvent *	m_pClickEvent
	Mouse event to deliver as 'click' or 'drag' events.

Selection gestures
The Selection class implements a few multi-step gestures: Dragging a rectangular selection lasso Dragging a selection to reposition it Both of these are supported by mouse or by keyboard.
enum	SelectionState { Idle , MouseLasso , MouseMoving , KeyboardLasso , KeyboardMoving }

enum Selection::SelectionState	m_selectionState

QRect	m_lasso
	Dimensions of a current selection lasso.

QPoint	m_movingOffset
	Offset that a selection has been moved by.

QRect	m_keyboardCursorStart
	Keyboard cursor position at the start of a keyboard gesture.

Selection iteration
Shorthand iteration is provided so that ranged for loops can be used for convenience: Selection<items> selection; ... for ( auto i : selection ) { ... Selection::Selection Selection(SelectionWidget< Elem > w) Definition* Selection.h:272
typedef std::set< Elem >::iterator	iterator

iterator	begin ()

iterator	end ()

Detailed Description

template<class Elem>
class Selection< Elem >

Selection management for editor widgets.

This template class bundles up the functionality necessary for interactive selections using mouse and keyboard.

The Selection class:

maintains a set of selected elements
maps low-level Qt mouse events to user-level complete 'click' and 'drag' gestures
handles some clicks, drags and keyboard events to manage selection
provides an offset for 'moving' selections, so the client widget can draw moving selections
paints a selection lasso if needed

The client widget must:

pass mouse and keyboard events to the Selection
implement the SelectionWidget interface, which Selection uses to:
- find elements intersecting a selection area
- get the location of the keyboard input cursor
- pass on user-level mouse gestures
paint any moving elements
call paintSelection() to allow the Selection to paint a lasso

Selections can be shared between multiple widgets providing different views of the same underlying model, so long as they share the same element type.

Definition at line 194 of file Selection.h.

Member Typedef Documentation

◆ iterator

template<class Elem>

typedef std::set<Elem>::iterator iterator

Definition at line 370 of file Selection.h.

Member Enumeration Documentation

◆ MouseState

template<class Elem>

enum MouseState

private

Enumerator
Up
Down
Dragging

Definition at line 228 of file Selection.h.

◆ SelectionState

template<class Elem>

enum SelectionState

private

Enumerator
Idle
MouseLasso
MouseMoving
KeyboardLasso
KeyboardMoving

Definition at line 255 of file Selection.h.

Constructor & Destructor Documentation

◆ Selection()

template<class Elem>

Selection ( SelectionWidget< Elem > * w )

inline

Definition at line 272 of file Selection.h.

Member Function Documentation

◆ addToSelection()

template<class Elem>

void addToSelection ( Elem e )

inline

Definition at line 348 of file Selection.h.

◆ begin()

template<class Elem>

iterator begin ( )

inline

Definition at line 372 of file Selection.h.

◆ cancelGesture()

template<class Elem>

void cancelGesture ( )

inline

Cancel any selection gesture (lasso, move, with keyboard or mouse) in progress.

Definition at line 384 of file Selection.h.

◆ clearSelection()

template<class Elem>

void clearSelection ( bool bCheck = true )

inline

Definition at line 352 of file Selection.h.

◆ dump()

template<class Elem>

void dump ( )

inline

Definition at line 297 of file Selection.h.

◆ end()

template<class Elem>

iterator end ( )

inline

Definition at line 373 of file Selection.h.

◆ isLasso()

template<class Elem>

bool isLasso ( ) const

inline

Is there an ongoing lasso gesture?

Definition at line 332 of file Selection.h.

◆ isMouseGesture()

template<class Elem>

bool isMouseGesture ( ) const

inline

Is there a mouse gesture in progress?

Definition at line 321 of file Selection.h.

◆ isMoving()

template<class Elem>

bool isMoving ( ) const

inline

Is there an ongoing (and incomplete) selection movement gesture?

Definition at line 316 of file Selection.h.

◆ isSelected()

template<class Elem>

bool isSelected ( Elem e ) const

inline

Is an element in the set of currently selected elements?

Definition at line 337 of file Selection.h.

◆ keyPressEvent()

template<class Elem>

bool keyPressEvent ( QKeyEvent * ev )

inline

Key press event filter.

Called by the client Widget to allow Selection to take some action on key presses. Must be called before the client Widget decides to take action on the key event.

Returns: true to indicate that the Selection claims the keypress, false otherwise.

Definition at line 688 of file Selection.h.

◆ merge()

template<class Elem>

void merge ( Selection< Elem > * pOther )

inline

Merge the selection groups of two Selection widgets.

After this is called, the set of selected items will be shared between them, and any changes made by one widget will cause the other to be notified and potentially refreshed.

Definition at line 288 of file Selection.h.

◆ mouseClick()

template<class Elem>

void mouseClick ( QMouseEvent * ev )

inline

Definition at line 524 of file Selection.h.

◆ mouseDragEnd()

template<class Elem>

void mouseDragEnd ( QMouseEvent * ev = nullptr )

inline

Definition at line 651 of file Selection.h.

◆ mouseDragStart()

template<class Elem>

void mouseDragStart ( QMouseEvent * ev )

inline

Definition at line 563 of file Selection.h.

◆ mouseDragUpdate()

template<class Elem>

void mouseDragUpdate ( QMouseEvent * ev )

inline

Definition at line 615 of file Selection.h.

◆ mouseMoveEvent()

template<class Elem>

void mouseMoveEvent ( QMouseEvent * ev )

inline

Definition at line 464 of file Selection.h.

◆ mousePressEvent()

template<class Elem>

void mousePressEvent ( QMouseEvent * ev )

inline

Definition at line 412 of file Selection.h.

◆ mouseReleaseEvent()

template<class Elem>

void mouseReleaseEvent ( QMouseEvent * ev )

inline

Definition at line 481 of file Selection.h.

◆ movingOffset()

template<class Elem>

QPoint movingOffset ( ) const

inline

During a selection "move" gesture, return the current movement position relative to the start position, in screen coordinates.

Definition at line 327 of file Selection.h.

◆ paintSelection()

template<class Elem>

void paintSelection ( QPainter * painter )

inline

Paint selection-related elements (ie lasso)

Definition at line 503 of file Selection.h.

◆ removeFromSelection()

template<class Elem>

void removeFromSelection	(	Elem	e,
		bool	bCheck = true )

inline

Definition at line 341 of file Selection.h.

◆ updateKeyboardCursorPosition()

template<class Elem>

void updateKeyboardCursorPosition ( QRect cursor )

inline

Update the keyboard cursor.

Called by the client widget to tell the Selection the current location of the keyboard input cursor.

Definition at line 785 of file Selection.h.

◆ updateWidgetGroup()

template<class Elem>

void updateWidgetGroup ( )

inline

Update any widgets in this selection group.

Definition at line 377 of file Selection.h.

Field Documentation

◆ m_checkpointSelectedElements

template<class Elem>

std::set< Elem > m_checkpointSelectedElements

private

For gestures modifying a selection, store the initial selection set as a checkpoint to restore when rebuilding the selection with the current lasso area.

Definition at line 264 of file Selection.h.

◆ m_keyboardCursorStart

template<class Elem>

QRect m_keyboardCursorStart

private

Keyboard cursor position at the start of a keyboard gesture.

Definition at line 259 of file Selection.h.

◆ m_lasso

template<class Elem>

QRect m_lasso

private

Dimensions of a current selection lasso.

Definition at line 257 of file Selection.h.

◆ m_mouseButton

template<class Elem>

Qt::MouseButton m_mouseButton

private

Mouse button that began the gesture.

Definition at line 229 of file Selection.h.

◆ m_mouseState

template<class Elem>

enum Selection::MouseState m_mouseState

private

◆ m_movingOffset

template<class Elem>

QPoint m_movingOffset

private

Offset that a selection has been moved by.

Definition at line 258 of file Selection.h.

◆ m_pClickEvent

template<class Elem>

QMouseEvent* m_pClickEvent

private

Mouse event to deliver as 'click' or 'drag' events.

Definition at line 230 of file Selection.h.

◆ m_pDragScroller

template<class Elem>

DragScroller* m_pDragScroller

private

Scroller to use while dragging selections.

Definition at line 267 of file Selection.h.

◆ m_pSelectionGroup

template<class Elem>

std::shared_ptr< SelectionGroup > m_pSelectionGroup

private

Definition at line 203 of file Selection.h.

◆ m_pWidget

template<class Elem>

SelectionWidget< Elem >* m_pWidget

private

Definition at line 208 of file Selection.h.

◆ m_selectionState

template<class Elem>

enum Selection::SelectionState m_selectionState

private

Data Structures

Public Member Functions

Private Attributes

Mouse state model

Selection gestures

Selection iteration

Detailed Description

Member Typedef Documentation

◆ iterator

Member Enumeration Documentation

◆ MouseState

◆ SelectionState

Constructor & Destructor Documentation

◆ Selection()

Member Function Documentation

◆ addToSelection()

◆ begin()

◆ cancelGesture()

◆ clearSelection()

◆ dump()

◆ end()

◆ isLasso()

◆ isMouseGesture()

◆ isMoving()

◆ isSelected()

◆ keyPressEvent()

◆ merge()

◆ mouseClick()

◆ mouseDragEnd()

◆ mouseDragStart()

◆ mouseDragUpdate()

◆ mouseMoveEvent()

◆ mousePressEvent()

◆ mouseReleaseEvent()

◆ movingOffset()

◆ paintSelection()

◆ removeFromSelection()

◆ updateKeyboardCursorPosition()

◆ updateWidgetGroup()

Field Documentation

◆ m_checkpointSelectedElements

◆ m_keyboardCursorStart

◆ m_lasso

◆ m_mouseButton

◆ m_mouseState

◆ m_movingOffset

◆ m_pClickEvent

◆ m_pDragScroller

◆ m_pSelectionGroup

◆ m_pWidget

◆ m_selectionState