Selection< Elem > Class Template Reference

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	merge (Selection *pOther)
	Merge the selection groups of two Selection widgets. More...
void	dump ()
bool	isMoving () const
	Is there an ongoing (and incomplete) selection movement gesture? More...
bool	isMouseGesture () const
	Is there a mouse gesture in progress? More...
QPoint	movingOffset () const
	During a selection "move" gesture, return the current movement position relative to the start position, in screen coordinates. More...
bool	isLasso () const
	Is there an ongoing lasso gesture? More...
bool	isSelected (Elem e) const
	Is an element in the set of currently selected elements? More...
void	removeFromSelection (Elem e, bool bCheck=true)
void	addToSelection (Elem e)
void	clearSelection (bool bCheck=true)
void	updateWidgetGroup ()
	Update any widgets in this selection group. More...
void	cancelGesture ()
	Cancel any selection gesture (lasso, move, with keyboard or mouse) in progress. More...
void	paintSelection (QPainter *painter)
	Paint selection-related elements (ie lasso) More...
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. More...
void	updateKeyboardCursorPosition (QRect cursor)
	Update the keyboard cursor. More...

Private Attributes
SelectionWidget< Elem > *	m_pWidget
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. More...
DragScroller *	m_pDragScroller
	Scroller to use while dragging selections. More...
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. More...
QMouseEvent *	m_pClickEvent
	Mouse event to deliver as 'click' or 'drag' events. More...

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. More...
QPoint	m_movingOffset
	Offset that a selection has been moved by. More...
QRect	m_keyboardCursorStart
	Keyboard cursor position at the start of a keyboard gesture. More...

Selection iteration
Shorthand iteration is provided so that ranged for loops can be used for convenience: Selection<items> selection; ... for ( auto i : selection ) { ...
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.

Member Typedef Documentation

iterator

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

Member Enumeration Documentation

MouseState

enum MouseState

private

Enumerator
Up
Down
Dragging

SelectionState

enum SelectionState

private

Enumerator
Idle
MouseLasso
MouseMoving
KeyboardLasso
KeyboardMoving

Constructor & Destructor Documentation

Selection()

Selection ( SelectionWidget< Elem > *  w )

inline

Member Function Documentation

addToSelection()

void addToSelection ( Elem  e )

inline

begin()

iterator begin ( )

inline

cancelGesture()

void cancelGesture ( )

inline

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

clearSelection()

void clearSelection ( bool  bCheck = true )

inline

dump()

void dump ( )

inline

end()

iterator end ( )

inline

isLasso()

bool isLasso ( ) const

inline

Is there an ongoing lasso gesture?

isMouseGesture()

bool isMouseGesture ( ) const

inline

Is there a mouse gesture in progress?

isMoving()

bool isMoving ( ) const

inline

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

isSelected()

bool isSelected ( Elem  e ) const

inline

Is an element in the set of currently selected elements?

keyPressEvent()

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.

merge()

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.

mouseClick()

void mouseClick ( QMouseEvent *  ev )

inline

mouseDragEnd()

void mouseDragEnd ( QMouseEvent *  ev = nullptr )

inline

mouseDragStart()

void mouseDragStart ( QMouseEvent *  ev )

inline

mouseDragUpdate()

void mouseDragUpdate ( QMouseEvent *  ev )

inline

mouseMoveEvent()

void mouseMoveEvent ( QMouseEvent *  ev )

inline

mousePressEvent()

void mousePressEvent ( QMouseEvent *  ev )

inline

mouseReleaseEvent()

void mouseReleaseEvent ( QMouseEvent *  ev )

inline

movingOffset()

QPoint movingOffset ( ) const

inline

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

paintSelection()

void paintSelection ( QPainter *  painter )

inline

Paint selection-related elements (ie lasso)

removeFromSelection()

void removeFromSelection ( Elem  e, bool  bCheck = true  )

inline

updateKeyboardCursorPosition()

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.

updateWidgetGroup()

void updateWidgetGroup ( )

inline

Update any widgets in this selection group.

Field Documentation

m_checkpointSelectedElements

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.

m_keyboardCursorStart

QRect m_keyboardCursorStart

private

Keyboard cursor position at the start of a keyboard gesture.

m_lasso

QRect m_lasso

private

Dimensions of a current selection lasso.

m_mouseButton

Qt::MouseButton m_mouseButton

private

Mouse button that began the gesture.

m_mouseState

enum Selection::MouseState m_mouseState

private

m_movingOffset

QPoint m_movingOffset

private

Offset that a selection has been moved by.

m_pClickEvent

QMouseEvent* m_pClickEvent

private

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

m_pDragScroller

DragScroller* m_pDragScroller

private

Scroller to use while dragging selections.

m_pSelectionGroup

std::shared_ptr< SelectionGroup > m_pSelectionGroup

private

m_pWidget

SelectionWidget< Elem >* m_pWidget

private

m_selectionState

enum Selection::SelectionState m_selectionState

private