ofx::DOM::Document Class Reference

The Document represents the root DOM Element in an DOM tree. More...

#include <Document.h>

Inheritance diagram for ofx::DOM::Document:

Public Member Functions
	Document ()
	Create a default Document. More...
virtual	~Document ()
	Destroy the Document.
void	setup (ofEventArgs &e)
	Callback for the setup event. More...
void	update (ofEventArgs &e)
	Callback for the update event. More...
void	draw (ofEventArgs &e)
	Callback for the draw event. More...
void	exit (ofEventArgs &e)
	Callback for the exit event. More...
void	windowResized (ofResizeEventArgs &e)
	Callback for the window resized event. More...
bool	fileDragEvent (ofDragInfo &e)
	Callback for file drag events. More...
bool	onKeyEvent (ofKeyEventArgs &e)
	Callback for key events events. More...
void	setAutoFillScreen (bool autoFillScreen)
	Determine if the Document size should always match the screen size. More...
bool	getAutoFillScreen () const
bool	onPointerEvent (PointerEventArgs &e)
	Callback for pointer events. More...
void	setPointerCaptureForElement (Element *element, std::size_t id)
	Set a pointer capture on a given Element. More...
void	releasePointerCaptureForElement (Element *element, std::size_t id)
	Release a pointer capture on a given Element. More...
Public Member Functions inherited from ofx::DOM::Element
	Element (float x, float y, float width, float height)
	Construct a new Element with the given parameters. More...
	Element (const std::string &id, float x, float y, float width, float height)
	Construct a new Element with the given parameters. More...
virtual	~Element ()
	Destroy the Element.
template<typename ElementType >
ElementType *	addChild (std::unique_ptr< ElementType > element)
	Take ownership of the passed std::unique_ptr<Element>. More...
template<typename ElementType , typename... Args>
ElementType *	addChild (Args &&...args)
	Create a child using a templated Element type. More...
std::unique_ptr< Element >	removeChild (Element *element)
	Release ownership of a child Element. More...
void	moveToFront ()
	Move this Element in front of all of its siblings.
void	moveForward ()
	Move this Element in front of its next sibling.
void	moveToBack ()
	Move this Element in back of all of its siblings.
void	moveBackward ()
	Move this Element in back of its next sibling.
void	moveChildToIndex (Element *element, std::size_t index)
	Move the given Element to the the given index. More...
void	moveChildToFront (Element *element)
	Move the given Element in front of all of its siblings. More...
void	moveChildForward (Element *element)
	Move the given Element in front of its next sibling. More...
void	moveChildToBack (Element *element)
	Move the given Element in back of all of its siblings. More...
void	moveChildBackward (Element *element)
	Move the given Element in back of its next sibling. More...
bool	isChild (Element *element) const
	Determine if the given Element is a child of this Element. More...
bool	isSibling (Element *element) const
	Determine if the given Element is a sibling of this Element. More...
std::size_t	numSiblings () const
std::vector< Element * >	siblings ()
template<typename ElementType >
std::vector< ElementType * >	siblings ()
	Get a list of siblings of a given Element or Element subclass. More...
bool	isParent (Element *element) const
	Determine if the given Element is the parent of this Element. More...
std::size_t	numChildren () const
std::vector< Element * >	children ()
	Get a list of pointers to the child elements. More...
template<typename ElementType >
std::vector< ElementType * >	children ()
	Get a list of pointers to the child elements. More...
bool	hasParent () const
	Determine if this Element has a parent Element. More...
Element *	findFirstChildById (const std::string &id)
	Find this Element's first child by its id. More...
std::vector< Element * >	findChildrenById (const std::string &id)
	Find all of this Element's matching the given id. More...
Element *	parent ()
	Get a pointer to the parent. More...
const Element *	parent () const
	Get a pointer to the parent. More...
Document *	document ()
	Get a pointer to the parent Document. More...
const Document *	document () const
	Get a pointer to the parent Document. More...
template<typename LayoutType , typename... Args>
LayoutType *	createLayout (Args &&...args)
	Create a Layout using a templated Layout type. More...
template<typename LayoutType >
LayoutType *	setLayout (std::unique_ptr< LayoutType > layout)
	Take ownership of the passed std::unique_ptr<Layout>. More...
std::unique_ptr< Layout >	removeLayout ()
	Release ownership of the Layout. More...
Layout *	layout ()
	Get a pointer to the associated Layout. More...
virtual bool	hitTest (const Position &parentPosition) const
	Perform a hit test on the Element. More...
virtual bool	childHitTest (const Position &localPosition) const
	Perform a hit test on a child Element. More...
Position	localToScreen (const Position &localPosition) const
	Convert the local coordinates to screen coordinates. More...
Position	screenToLocal (const Position &screenPosition) const
	Convert the screen coordinates to local coordinates. More...
Position	parentToScreen (const Position &parentPosition) const
	Convert the parent coordinates to screen coordinates. More...
Position	screenToParent (const Position &screenPosition) const
	Convert the screen coordinates to parent coordinates. More...
void	setPosition (float x, float y)
	Set the position of the Element in its parent coordinates. More...
void	setPosition (const Position &position)
	Set the position of the Element in its parent coordinates. More...
Position	getPosition () const
	Get the position of the Element in its parent coordinates. More...
float	getX () const
	Get the X position of the Element in its parent coordinates. More...
float	getY () const
	Get the Y position of the Element in its parent coordinates. More...
Position	getScreenPosition () const
	Get the Position of the Element in screen coordinates. More...
float	getScreenX () const
	Get the X position of the Element in screen coordinates. More...
float	getScreenY () const
	Get the Y position of the Element in screen coordinates. More...
void	setSize (float width, float height)
	Set the size of the Element. More...
Size	getSize () const
	Get the Size of the Element. More...
float	getWidth () const
	Get the width of the Element. More...
float	getHeight () const
	Get the height of the Element. More...
Geometry	getGeometry () const
	Get the geometry of the Element in its parent coordinates. More...
void	setGeometry (const Geometry &geometry)
	Set the geometry of the Element in its parent coordinates. More...
Geometry	getChildGeometry () const
	Get the bounding box representing all child elements. More...
Geometry	getTotalGeometry () const
	Get the bounding box representing the union of the child geometry and the element geometry. More...
std::string	getId () const
	Get the id of this Element. More...
void	setId (const std::string &id)
	Set the id of the Element. More...
bool	hasAttribute (const std::string &name) const
	Determine of the Element has an attribute with the given name. More...
template<typename AnyType >
AnyType	getAttribute (const std::string &key, bool inherit=false) const
	Get a named attribute via its key. More...
void	setAttribute (const std::string &name, const Any &value)
	Set a value for a named attribute. More...
void	clearAttribute (const std::string &name)
	Clear a named attribute. More...
void	setPointerCapture (std::size_t id)
	Request that the parent Document capture the given pointer id. More...
void	releasePointerCapture (std::size_t id)
	Release a captured pointer with the given id. More...
bool	isEnabled () const
void	setEnabled (bool enabled)
	Enable or disable this Element. More...
bool	isHidden () const
void	setHidden (bool hidden)
	Hide or show this Element. More...
bool	isLocked () const
void	setLocked (bool locked)
	Lock or unlock a this Element. More...
Public Member Functions inherited from ofx::DOM::EventTarget< Element >
	EventTarget ()
	Create an EventTarget.
virtual	~EventTarget ()
	Destroy the EventTarget.
void	addEventListener (EventType &event, void(ListenerClass::*listenerMethod)(const void *, ArgumentsType &), bool useCapture=false, int priority=OF_EVENT_ORDER_AFTER_APP)
void	addEventListener (EventType &event, void(ListenerClass::*listenerMethod)(ArgumentsType &), bool useCapture=false, int priority=OF_EVENT_ORDER_AFTER_APP)
void	addEventListener (EventType &event, bool(ListenerClass::*listenerMethod)(const void *, ArgumentsType &), bool useCapture=false, int priority=OF_EVENT_ORDER_AFTER_APP)
void	addEventListener (EventType &event, bool(ListenerClass::*listenerMethod)(ArgumentsType &), bool useCapture=false, int priority=OF_EVENT_ORDER_AFTER_APP)
void	removeEventListener (EventType &event, void(ListenerClass::*listenerMethod)(const void *, ArgumentsType &), bool useCapture=false, int priority=OF_EVENT_ORDER_AFTER_APP)
void	removeEventListener (EventType &event, void(ListenerClass::*listenerMethod)(ArgumentsType &), bool useCapture=false, int priority=OF_EVENT_ORDER_AFTER_APP)
void	removeEventListener (EventType &event, bool(ListenerClass::*listenerMethod)(const void *, ArgumentsType &), bool useCapture=false, int priority=OF_EVENT_ORDER_AFTER_APP)
void	removeEventListener (EventType &event, bool(ListenerClass::*listenerMethod)(ArgumentsType &), bool useCapture=false, int priority=OF_EVENT_ORDER_AFTER_APP)
bool	dispatchEvent (EventType &event)
	Dispatch the given event. More...
bool	handleEvent (EventArgsType &e)
	Handle the given event. More...
bool	hasListenersForEventType (const std::string &type) const
	Determine if the EventTarget has listeners for an event. More...
bool	isEventTypeRegistered (const std::string &type) const
	Determine if the EventTarget is registered to receive the type of events. More...
void	registerEventType (const std::string &type, BaseDOMEvent *event)
	Register a new event type by name. More...
void	unregisterEventType (const std::string &type)
	Unregister a new event type by name. More...
virtual void	onSetup ()
virtual void	onUpdate ()
virtual void	onDraw () const
virtual void	onExit ()

Protected Types
typedef std::unordered_map< std::size_t, Element * >	PointerElementMap
	Map pointer ids to Elements.

Protected Attributes
bool	_autoFillScreen = true
	True if the Document size should always match the screen size.
PointerElementMap	_capturedPointerIdToElementMap
	Captured pointer and their capture target.
PointerElementMap	_activeTargets
	Currently active targets for given pointer ids. More...
std::unordered_map< std::size_t, PointerEventArgs >	_activePointers
	Currently active pointers and their last associated event. More...
Protected Attributes inherited from ofx::DOM::EventTarget< Element >
std::unordered_map< std::string, BaseDOMEvent * >	_eventRegistry

Additional Inherited Members
Public Attributes inherited from ofx::DOM::EventTarget< Element >
DOMEvent< PointerUIEventArgs >	pointerOver
DOMEvent< PointerUIEventArgs >	pointerEnter
DOMEvent< PointerUIEventArgs >	pointerDown
DOMEvent< PointerUIEventArgs >	pointerMove
DOMEvent< PointerUIEventArgs >	pointerUp
DOMEvent< PointerUIEventArgs >	pointerCancel
DOMEvent< PointerUIEventArgs >	pointerOut
DOMEvent< PointerUIEventArgs >	pointerLeave
DOMEvent< PointerUIEventArgs >	pointerScroll
DOMEvent< PointerCaptureUIEventArgs >	gotPointerCapture
DOMEvent< PointerCaptureUIEventArgs >	lostPointerCapture
DOMEvent< KeyboardUIEventArgs >	keyDown
DOMEvent< KeyboardUIEventArgs >	keyUp
DOMEvent< FocusEventArgs >	blur
DOMEvent< FocusEventArgs >	focusIn
DOMEvent< FocusEventArgs >	focus
DOMEvent< FocusEventArgs >	focusOut
ofEvent< ElementEventArgs >	addedTo
ofEvent< ElementEventArgs >	removedFrom
ofEvent< ElementOrderEventArgs >	reordered
ofEvent< ElementEventArgs >	siblingAdded
ofEvent< ElementEventArgs >	siblingRemoved
ofEvent< ElementOrderEventArgs >	siblingReordered
ofEvent< ElementEventArgs >	childAdded
ofEvent< ElementEventArgs >	childRemoved
ofEvent< ElementOrderEventArgs >	childReordered
ofEvent< MoveEventArgs >	move
ofEvent< ResizeEventArgs >	resize
ofEvent< AttributeEventArgs >	attributeSet
ofEvent< AttributeEventArgs >	attributeCleared
ofEvent< EnablerEventArgs >	enabled
ofEvent< EnablerEventArgs >	locked
ofEvent< EnablerEventArgs >	hidden
Protected Member Functions inherited from ofx::DOM::Element
void	_setup (ofEventArgs &e)
	Setup method called by parent Element. More...
void	_update (ofEventArgs &e)
	Update method called by parent Element. More...
void	_draw (ofEventArgs &e)
	Draw method called by parent Element. More...
void	_exit (ofEventArgs &e)
	Exit method called by parent Element. More...
Element *	recursiveHitTest (const Position &parentPosition)
	A recursive hit test to find a target element. More...
std::vector< std::unique_ptr< Element > >::iterator	findChild (Element *element)
	Find a child by a raw Element pointer. More...
bool	isPointerCaptured (std::size_t id) const
	Determine if a given pointer id is captured. More...
std::vector< CapturedPointer >::iterator	findCapturedPointerById (std::size_t id)
	Find the given CapturePointer info by id. More...
std::vector< CapturedPointer >::const_iterator	findCapturedPointerById (std::size_t id) const
	Find the given CapturePointer info by id. More...
std::vector< CapturedPointer > &	capturedPointers ()
	Get a reference to the captured pointer vector. More...
const std::vector< CapturedPointer > &	capturedPointers () const
	Get a reference to the captured pointer vector. More...
virtual void	invalidateChildGeometry () const
	Called internally to invalidate the child geometry tree.
void	setImplicitPointerCapture (bool implicitPointerCapture)
	Set if the pointer is implicitly captured on pointer down. More...
bool	getImplicitPointerCapture () const
	Determine if pointer is automatically captured on pointer down. More...

Detailed Description

The Document represents the root DOM Element in an DOM tree.

Constructor & Destructor Documentation

ofx::DOM::Document::Document

(

)

Create a default Document.

The Document will have the default id of "document" and will fill the entire screen.

Member Function Documentation

void ofx::DOM::Document::draw

(

ofEventArgs &

e

)

Callback for the draw event.

Parameters

e	the event data.

void ofx::DOM::Document::exit

(

ofEventArgs &

e

)

Callback for the exit event.

Parameters

e	the event data.

bool ofx::DOM::Document::fileDragEvent

(

ofDragInfo &

e

)

Callback for file drag events.

Parameters

e	the event data.

Returns

true iff the event was handled.

bool ofx::DOM::Document::getAutoFillScreen

(

)

const

Returns

true if the Document size will always match the screen size.

bool ofx::DOM::Document::onKeyEvent

(

ofKeyEventArgs &

e

)

Callback for key events events.

Parameters

e	the event data.

Returns

true iff the event was handled.

bool ofx::DOM::Document::onPointerEvent

(

PointerEventArgs &

e

)

Callback for pointer events.

Parameters

e	The PointerEventArgs.

Returns

true if the event was handled.

Todo:

Implement way to call default action if the event is not handled.

pointerout, pointerleave, pointerover and pointer enter events will

void ofx::DOM::Document::releasePointerCaptureForElement	(	Element *	element,
		std::size_t	id
	)

Release a pointer capture on a given Element.

Parameters

element	A pointer to the capturing Element.
id	The pointer id to release.

Exceptions

DOMException

on invalid DOM state or pointer id.

void ofx::DOM::Document::setAutoFillScreen

(

bool

autoFillScreen

)

Determine if the Document size should always match the screen size.

Parameters

true	if if the Document size should always match the screen size.

void ofx::DOM::Document::setPointerCaptureForElement	(	Element *	element,
		std::size_t	id
	)

Set a pointer capture on a given Element.

Parameters

element	A pointer to the capturing Element.
id	The pointer id to capture.

Exceptions

DOMException

on invalid DOM state or pointer id.

void ofx::DOM::Document::setup

(

ofEventArgs &

e

)

Callback for the setup event.

Parameters

e	the event data.

void ofx::DOM::Document::update

(

ofEventArgs &

e

)

Callback for the update event.

Parameters

e	the event data.

void ofx::DOM::Document::windowResized

(

ofResizeEventArgs &

e

)

Callback for the window resized event.

Parameters

e	the event data.

Member Data Documentation

std::unordered_map<std::size_t, PointerEventArgs> ofx::DOM::Document::_activePointers

protected

Currently active pointers and their last associated event.

This map is a basic list of the pointers that we know about.

For pointers that support hovering (e.g. mouse, trackball, etc) the pointer's id will always be active. For pointers that do not support hovering (e.g. multi-touch surfaces) the pointer ids will only be recorded until they leave the surface via a pointerup or pointercancel event.

PointerElementMap ofx::DOM::Document::_activeTargets

protected

Currently active targets for given pointer ids.

It is not required that these targets are captured, only that they passed a hit test. This is used for doing pointer in / pointer out, etc when the pointer isn't captured (e.g. mouse over, etc).

In some cases, an active target may be a nullptr, meaning that the last pointer event could not be handled by any Element in the Document tree. This may happen, for instance, if the root Document does not cover the entire screen and we receive an event that falls outside.

We still keep track of these events in order to correctly generate various synthesized events and gestures.

---

The documentation for this class was generated from the following files:

• Document.h
• Document.cpp