#include "steam/mobject/session/query-focus.hpp"

Description

Current focus location to use as point-of reference for contents and location discovery queries.

This is the frontend to be used by client code: a smart-handle, internally linked through the ScopeLocaor singleton to a stack of current focus path locations. The intention is for this current location to follow the ongoing query/discovery operations mostly automatically.

usage

A QueryFocus (frontend handle) can be default constructed, in which case it will automatically connect to what is currently the focus location for any further queries. Here, the current focus location is defined as the most recently used location which is still referred by some QueryFocus handle.

Alternatively, through the static factory function push(), a new focus location may be opened, thereby pushing the currently used focus location aside. This new focus location will remain the current focus, until all handles referring to it go out of scope.

Using an existing QueryFocus (handle), the current focus may be shifted to another scope within the current session. This »navigating« operation will use the current focus position as point of departure, thus retaining a similar access path to any nested sequences. (These might be attached multiple times within the same session, each attachment constituting a different context scope. Navigating tries to retain the current context)

The templated query functions allow to issue specifically typed queries to retrieve all children (immediately contained in a given scope), or do discover depth-first any content within this scope. The result set of these queries will be filtered to yield only placements compatible to the specified kind of MObject. E.g, you may query all Clip objects within a given Fork.

The implementation of these query operations is backed by the PlacementIndex in the current session. The link to the session is established the moment these query functions are invoked. The returned iterator (Lumiera Forward Iterator) contains a smart-ptr to keep the hidden result set alive. The results are delivered without any defined order (implementation is hashtable based)

See also: QueryFocus_test; scope-path.hpp (concept: path of scopes)

Definition at line 102 of file query-focus.hpp.

Public Member Functions
	QueryFocus ()
	create a new QueryFocus (handle) linked to the current focus for discovery queries. More...

ScopePath const &	currentPath () const

RefPlacement	currentPoint () const

template<class MO >
ScopeQuery< MO >::iterator	explore () const
	discover any matching object contained as immediate Child within current focus. More...

lib::IterSource< const Scope >::iterator	locate (Scope const &toTarget)
	shift or navigate the current focus to point at the given target scope. More...

	operator Scope () const
	allowing direct conversion to Scope. More...

	operator string () const
	diagnostic self-display based on the ScopePath

QueryFocus &	pop ()
	cease to use this specific reference to the current frame. More...

template<class MO >
ScopeQuery< MO >::iterator	query () const
	discover depth-first any matching object within current focus. More...

QueryFocus &	reset ()
	discard any state and navigate current focus path to model root

QueryFocus &	shift (Scope const &)
	shift this QueryFocus to a container-like scope, causing it to navigate, changing the current ScopePath as a side-effect More...

Static Public Member Functions
static QueryFocus	push (Scope const &)
	push the "current QueryFocus" aside and open a new focus frame. More...

static QueryFocus	push ()
	push the "current QueryFocus" aside and open a new focus frame, which starts out at the same location as the original

Private Member Functions
	QueryFocus (ScopePath &)

Static Private Member Functions
static ScopePath &	currPath ()

Private Attributes
boost::intrusive_ptr< ScopePath >	focus_

Constructor & Destructor Documentation

◆ QueryFocus() [1/2]

QueryFocus ( )

create a new QueryFocus (handle) linked to the current focus for discovery queries.

The existence of this QueryFocus instance keeps this current focus alive, but multiple instances share a common focus location and may change this location.

Definition at line 41 of file query-focus.cpp.

◆ QueryFocus() [2/2]

QueryFocus ( ScopePath & path_to_attach )

private

build a new QueryFocus as located to an existing path.

Definition at line 50 of file query-focus.cpp.

Member Function Documentation

◆ currentPath()

ScopePath const & currentPath ( ) const

inline

Returns: ref to internal datastructure

Warning: don't store it directly. Rather copy it or store a QueryFocus instance.

Note: use #attach if the intention is to manipulate the current focus location

Definition at line 159 of file query-focus.hpp.

Referenced by QueryFocus_test::checkNavigation(), and steam::mobject::session::test::anonymous_namespace{query-focus-test.cpp}::refs().

Here is the caller graph for this function:

◆ currentPoint()

RefPlacement currentPoint ( ) const

inline

Returns: placement-ref to the object the QueryFocus is currently pointing at

Definition at line 168 of file query-focus.hpp.

Referenced by SessionImpl::attach().

Here is the caller graph for this function:

◆ operator Scope()

operator Scope ( ) const

inline

allowing direct conversion to Scope.

Implemented by copying the scope at leaf position of the current focus path

Definition at line 147 of file query-focus.hpp.

◆ shift()

QueryFocus & shift ( Scope const & container )

shift this QueryFocus to a container-like scope, causing it to navigate, changing the current ScopePath as a side-effect

Exceptions

error::Invalid if the given container is invalid or can't be located within the model

Definition at line 101 of file query-focus.cpp.

Referenced by QueryFocus_test::checkNavigation(), and QueryFocus_test::manipulate_subFocus().

Here is the caller graph for this function:

◆ push()

QueryFocus push ( Scope const & otherContainer )

static

push the "current QueryFocus" aside and open a new focus frame.

This new QueryFocus will act as "current" until going out of scope

Exceptions

error::Invalid in case of invalid or unlocatable target scope

Definition at line 116 of file query-focus.cpp.

◆ pop()

QueryFocus & pop ( )

cease to use this specific reference to the current frame.

This operation immediately tries to re-attach to what is "current" and readjusts the internal handle. But when the previously released reference was the last one, releasing it will cause the QueryFocusStack to pop, in which case we'll re-attach to the now uncovered previous stack top.

Definition at line 148 of file query-focus.cpp.

References QueryFocus::currPath().

Referenced by QueryFocus_test::manipulate_subFocus().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ query()

ScopeQuery< MO >::iterator query ( ) const

inline

discover depth-first any matching object within current focus.

Resolution is delegated to the current session

Definition at line 179 of file query-focus.hpp.

References ScopeLocator::instance.

Referenced by QueryFocus_test::checkNavigation().

Here is the caller graph for this function:

◆ explore()

ScopeQuery< MO >::iterator explore ( ) const

inline

discover any matching object contained as immediate Child within current focus.

Resolution through current session

Definition at line 190 of file query-focus.hpp.

References ScopeLocator::instance.

Referenced by QueryFocus_test::checkNavigation(), and QueryFocus_test::manipulate_subFocus().

Here is the caller graph for this function:

◆ locate()

lib::IterSource< const Scope >::iterator locate ( Scope const & toTarget )

inline

shift or navigate the current focus to point at the given target scope.

In case of multiple possible access paths, the current location is taken into account, trying to reach the new location in a similar fashion as much as possible.

Note: moves the current focus as side-effect

Returns: the effective / virtual new access path leading to the new target focus scope

Definition at line 205 of file query-focus.hpp.

References ScopeLocator::instance.

◆ currPath()

ScopePath & currPath ( )

staticprivate

access the path designating the current focus location

Definition at line 58 of file query-focus.cpp.

References ScopeLocator::instance.

Referenced by QueryFocus::pop(), and QueryFocus::push().

Here is the caller graph for this function:

Collaboration diagram for QueryFocus:

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

Description

usage

Public Member Functions

Static Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Constructor & Destructor Documentation

◆ QueryFocus() [1/2]

◆ QueryFocus() [2/2]

Member Function Documentation

◆ currentPath()

◆ currentPoint()

◆ operator Scope()

◆ shift()

◆ push()

◆ pop()

◆ query()

◆ explore()

◆ locate()

◆ currPath()