ComponentPath

class HPS::ComponentPath : public HPS::Sprocket 

The ComponentPath contains an array of components, organized from leaf to root. It allows the user to perform queries and operations along that path.

Public Types

using const_iterator = HPS::ComponentArray::const_iterator

using const_reverse_iterator = HPS::ComponentArray::const_reverse_iterator

using iterator = HPS::ComponentArray::iterator

enum PathType

Enumerates the types of ComponentPaths.

Values:

enumerator Complete: The ComponentPath contains all components between leaf and root.

enumerator Unique: The ComponentPath contains only components which are unique to this request, omitting ambiguous entries.

using reverse_iterator = HPS::ComponentArray::reverse_iterator

Public Functions

ComponentPath &Append(Component const &in_component)

Appends the supplied Component into this object. Same as operator+= function.

Deprecated:: This function exists for compatibility. Use ComponentPath::PushBack instead.

Parameters: in_component – The Component to be appended to this.
Returns: A reference to this object.

ComponentPath &Append(ComponentArray const &in_components)

Appends the supplied key into this object. Same as operator+= function.

Deprecated:: This function exists for compatibility. Use ComponentPath::PushBack instead.

Parameters: in_components – The ComponentArray to be appended to this.
Returns: A reference to this object.

ComponentPath &Append(ComponentPath const &in_path)

Appends the supplied key into this object. Same as operator+= function.

Deprecated:: This function exists for compatibility. Use ComponentPath::PushBack instead.

Parameters: in_path – The ComponentPath to be appended to this.
Returns: A reference to this object.

Component &At(size_t in_index)

Access a Component in this ComponentPath object. An HPS::IndexOutOfRangeException exception is thrown if in_index is out of range.

Parameters: in_index – The index of the Component to access, zero based.
Returns: The Component at position in_index in this ComponentPath.

Component const &At(size_t in_index) const

Access a Component in this ComponentPath object. An HPS::IndexOutOfRangeException exception is thrown if in_index is out of range.

Parameters: in_index – The index of the Component to access, zero based.
Returns: The Component at position in_index in this ComponentPath.

Component &Back()

Returns the last component of this ComponentPath. An HPS::IndexOutOfRangeException exception is thrown if the ComponentPath is empty.

Returns: The last component of this ComponentPath.

Component const &Back() const

Returns the last component of this ComponentPath. An HPS::IndexOutOfRangeException exception is thrown if the ComponentPath is empty.

Returns: The last component of this ComponentPath.

iterator begin()

Returns an iterator pointing to the first Component contained in this ComponentPath

Returns: An iterator pointing to the first Component contained in this ComponentPath.

const_iterator begin() const

Returns an iterator pointing to the first Component contained in this ComponentPath

Returns: An iterator pointing to the first Component contained in this ComponentPath.

const_iterator cbegin() const

Returns a constant iterator pointing to the first Component contained in this ComponentPath

Returns: A constant iterator pointing to the first Component contained in this ComponentPath.

const_iterator cend() const

Returns a constant iterator pointing to the last Component contained in this ComponentPath

Returns: A constant iterator pointing to the last Component contained in this ComponentPath.

ComponentPath(): Creates an uninitialized ComponentPath that refers to no database objects.

ComponentPath(ComponentArray const &in_components)

Creates a new ComponentPath object based on the supplied path.

Parameters: in_components – An array of components arranged from leaf to root.

ComponentPath(ComponentPath &&in_that)

The move constructor creates a ComponentPath by transferring the underlying impl of the rvalue reference to this ComponentPath thereby avoiding a copy and allocation.

Parameters: in_that – An rvalue reference to a ComponentPath to take the impl from.

ComponentPath(ComponentPath const &in_that): Copies in_that into this ComponentPath.

ComponentPath(size_t in_count, Component const in_components[])

Creates a new ComponentPath object based on the supplied path.

Parameters

in_count – The number of keys in the array.
in_components – An array of components arranged from leaf to root.

virtual bool Empty() const

Indicates whether this ComponentPath is empty.

Returns: true if no components are set on the path, false otherwise.

iterator end()

Returns a constant iterator pointing to the last Component contained in this ComponentPath

Returns: A constant iterator pointing to the last Component contained in this ComponentPath.

const_iterator end() const

Returns a constant iterator pointing to the last Component contained in this ComponentPath

Returns: A constant iterator pointing to the last Component contained in this ComponentPath.

bool Equals(ComponentPath const &in_that) const

Check if the source ComponentPath is equivalent to this object.

Parameters: in_that – The source ComponentPath to compare to this object.
Returns: true if the objects are equivalent, false otherwise.

Component &Front()

Returns the first component of this ComponentPath. An HPS::IndexOutOfRangeException exception is thrown if the ComponentPath is empty.

Returns: The first component of this ComponentPath.

Component const &Front() const

Returns the first component of this ComponentPath. An HPS::IndexOutOfRangeException exception is thrown if the ComponentPath is empty.

Returns: The first component of this ComponentPath.

ComponentArray GetComponents() const

Gets the components defining this ComponentPath.

Returns: The components defining this ComponentPath.

KeyPathArray GetKeyPaths() const

Gets the KeyPath objects corresponding to this ComponentPath. These key paths will include all possible paths which include the path components and all Canvas, Layout and View paths which include the Model which contains the path components.

Returns: All KeyPath objects for this ComponentPath.

KeyPathArray GetKeyPaths(Canvas const &in_canvas, size_t in_layer = 0) const

Gets the KeyPath objects corresponding to this ComponentPath which are included by the specified Canvas and layer.

Parameters

in_canvas – The Canvas the returned KeyPath objects should reference.
in_layer – The layer under the provided Canvas the returned KeyPath objects should reference.

Returns

The KeyPath objects for this ComponentPath which are included by the specified Canvas and layer.

void Hide(Canvas const &in_canvas, size_t in_layer = 0)

Hides this ComponentPath under the given Canvas in the specified layer. This forces the visibility of the selected ComponentPath and all components under this path to invisible. Any visibility changes made previously at or below this path are flushed. When performing a highlight in combination with this function the highlight must be applied with Drawing::Overlay::InPlace to display properly. See this section for limitations and details on managing component visibility.

See: Show
See: Isolate
See: IsHidden
See: ResetVisibility
See: Programming Guide: Managing Component Visibility

Parameters

in_canvas – The Canvas in which to hide the ComponentPath.
in_layer – The layer under the provided Canvas in which to hide the ComponentPath.

void Highlight(Canvas const &in_canvas, HighlightOptionsKit const &in_options, bool in_remove_existing = true) const

Highlights this ComponentPath with the provided options under the given Canvas in layer zero.

Parameters

in_canvas – The Canvas in which to perform the highlight.
in_options – The options to use to perform the highlight.
in_remove_existing – Indicates whether this highlight should flush existing highlights at the specified path for the desired overlay type. If HPS::ComponentPath::Isolate(), HPS::ComponentPath::Hide(), or HPS::ComponentPath::Show() have been called on this ComponentPath, in_remove_existing should be set to false so that it doesn’t override those visibility states.

void Highlight(Canvas const &in_canvas, size_t in_layer, HighlightOptionsKit const &in_options, bool in_remove_existing = true) const

Highlights this ComponentPath with the provided options under the given Canvas in the specified layer.

Parameters

in_canvas – The Canvas in which to perform the highlight.
in_layer – The layer under the provided Canvas in which to perform the highlight.
in_options – The options to use to perform the highlight. If HPS::ComponentPath::Isolate(), HPS::ComponentPath::Hide(), or HPS::ComponentPath::Show() have been called on this ComponentPath, in_remove_existing should be set to false so that it doesn’t override those visibility states.

void Insert(size_t in_index, Component const &in_item)

Inserts in_item in the ComponentPath before the element at position in_index, increasing the size of the ComponentPath by one. An HPS::IndexOutOfRangeException exception is thrown if in_index is out of range.

Parameters

in_index – The index where in_item will be inserted
in_item – The component to insert in this key path.

bool IsHidden(Canvas const &in_canvas, size_t in_layer = 0) const

Indicates whether this ComponentPath under the given Canvas in the specified layer is hidden. Note that even if a path is hidden, it’s possible that paths descending from this path may not be hidden.

See: Hide
See: Show
See: Isolate
See: ResetVisibility
See: Programming Guide: Managing Component Visibility

Parameters

in_canvas – The Canvas in which to check whether the specified path is hidden.
in_layer – The layer under the provided Canvas in which to check whether the specified path is hidden.

Returns

true if this path is hidden, false otherwise.

void Isolate(Canvas const &in_canvas, size_t in_layer = 0)

Shows only this ComponentPath and hides all other Component objects under the given Canvas in the specified layer. When performing a highlight in combination with this function the highlight must be applied with Drawing::Overlay::InPlace to display properly. See this section for limitations and details on managing component visibility.

See: Hide
See: Show
See: IsHidden
See: ResetVisibility
See: Programming Guide: Managing Component Visibility

Parameters

in_canvas – The Canvas in which to isolate the ComponentPath.
in_layer – The layer under the provided Canvas in which to isolate the ComponentPath.

inline virtual HPS::Type ObjectType() const

This function returns the type the object, as declared (if the object is derived, this does not give the true type of the derived object).

Returns: The declared type of the object in question, which may differ from the true, underlying type.

bool operator!=(ComponentPath const &in_that) const

Check if the source ComponentPath is not equivalent to this object.

Parameters: in_that – The source ComponentPath to compare to this object.
Returns: true if the objects are not equivalent, false otherwise.

ComponentPath &operator+=(Component const &in_component)

Appends the supplied Component into this object. Same as Append function.

Parameters: in_key – The key to be appended to this.
Returns: A reference to this object.

ComponentPath &operator+=(ComponentArray const &in_components)

Appends the supplied ComponentArray into this object. Same as Append function.

Parameters: in_components – The ComponentArray to be appended to this.
Returns: A reference to this object.

ComponentPath &operator+=(ComponentPath const &in_path)

Appends the supplied ComponentPath into this object. Same as Append function.

Parameters: in_key_path – The ComponentPath to be appended to this.
Returns: A reference to this object.

ComponentPath &operator=(ComponentArray const &in_path)

Copies an array of components into this object.

Parameters: in_path – The source array, assumed to be arranged from leaf to root.
Returns: A reference to this object.

ComponentPath &operator=(ComponentPath &&in_that)

The move assignment operator transfers the underlying impl of the rvalue reference to this ComponentPath thereby avoiding a copy.

Parameters: in_that – An rvalue reference to a ComponentPath to take the impl from.
Returns: A reference to this ComponentPath.

ComponentPath &operator=(ComponentPath const &in_that)

Copies the supplied path into this object.

Parameters: in_that – The source of the copy.
Returns: A reference to this object.

bool operator==(ComponentPath const &in_that) const

Check if the source ComponentPath is equivalent to this object.

Parameters: in_that – The source ComponentPath to compare to this object.
Returns: true if the objects are equivalent, false otherwise.

Component PopBack()

Returns the last component of this ComponentPath and returns it. An HPS::IndexOutOfRangeException exception is thrown if the ComponentPath is empty.

Returns: The last component of this ComponentPath.

Component PopFront()

Returns the first component of this ComponentPath and returns it. An HPS::IndexOutOfRangeException exception is thrown if the ComponentPath is empty.

Returns: The first component of this ComponentPath.

ComponentPath &PushBack(Component const &in_component)

Adds in_component to the end of the ComponentPath.

Parameters: in_component – The component to add to the end of the ComponentPath.
Returns: A reference to this object.

ComponentPath &PushBack(ComponentArray const &in_components)

Appends the supplied key into this object. Same as operator+= function.

Parameters: in_components – The ComponentArray to be appended to this.
Returns: A reference to this object.

ComponentPath &PushBack(ComponentPath const &in_path)

Appends the supplied key into this object. Same as operator+= function.

Parameters: in_path – The ComponentPath to be appended to this.
Returns: A reference to this object.

ComponentPath &PushFront(Component const &in_component)

Adds in_component to the front of the ComponentPath.

Parameters: in_component – The component to add to the front of the ComponentPath.
Returns: A reference to this object.

reverse_iterator rbegin()

Returns a reverse iterator pointing to the last Component contained in this ComponentPath

Returns: A reverse iterator pointing to the last Component contained in this ComponentPath.

const_reverse_iterator rbegin() const

Returns a constant reverse iterator pointing to the last Component contained in this ComponentPath

Returns: A constant reverse iterator pointing to the last Component contained in this ComponentPath.

void Remove(Component const &in_item)

Traverses the components in this ComponentPath and removes the first one which matches in_item NOTE: A useful ComponentPath should not contain duplicate components.

Parameters: in_item – The item to remove from the ComponentPath.

void Remove(size_t in_index)

Removes the the component at position in_index from this ComponentPath. An HPS::IndexOutOfRangeException exception is thrown if in_index is out of range.

Parameters: in_index – The index of the component to remove, zero based.

reverse_iterator rend()

Returns a reverse iterator pointing to the first Component contained in this ComponentPath

Returns: A reverse iterator pointing to the first Component contained in this ComponentPath.

const_reverse_iterator rend() const

Returns a constant iterator pointing to the first Component contained in this ComponentPath

Returns: A constant iterator pointing to the first Component contained in this ComponentPath.

void ResetVisibility(Canvas const &in_canvas, size_t in_layer = 0)

Resets the visibility of all components at or below this ComponentPath back to the visibility state defined by their model & view. See this section for limitations and details on managing component visibility.

See: Hide
See: Show
See: Isolate
See: IsHidden
See: Programming Guide: Managing Component Visibility

Parameters

in_canvas – The Canvas in which to isolate the ComponentPath.
in_layer – The layer under the provided Canvas in which to isolate the ComponentPath.

ComponentPath Reverse() const

Creates and returns a new ComponentPath object, with the components organized in the reverse order.

Returns: A new ComponentPath object, containing components organized in the reverse order.

void Set(ComponentPath const &in_that)

Copies the supplied path into this object.

Parameters: in_that – The source of the copy.

ComponentPath &SetComponents(ComponentArray const &in_components)

Copies an array of components into this object.

Parameters: in_components – The source array, assumed to be arranged from leaf to root.
Returns: A reference to this object.

ComponentPath &SetComponents(size_t in_count, Component const in_components[])

Copies an array of components into this object.

Parameters

in_count – the number of components in the array.
in_components – The source array, assumed to arranged from leaf to root.

Returns

A reference to this object.

void Show(Canvas const &in_canvas, size_t in_layer = 0)

Shows this ComponentPath under the given Canvas in the specified layer. This makes the selected path visibile but preserves the model-defined visibility of any components that exist underneath the chosen path. Any visibility changes made subsequently at or below this path are honored unless they are redundant. When performing a highlight in combination with this function the highlight must be applied with Drawing::Overlay::InPlace to display properly. See this section for limitations and details on managing component visibility.

See: Hide
See: Isolate
See: IsHidden
See: ResetVisibility
See: Programming Guide: Managing Component Visibility

Parameters

in_canvas – The Canvas in which to show the ComponentPath.
in_layer – The layer under the provided Canvas in which to show the ComponentPath.

size_t Size() const

Returns the number of Components contained in this ComponentPath object.

Returns: the number of Components in this ComponentPath.

void Unhighlight(Canvas const &in_canvas, HighlightOptionsKit const &in_options = HighlightOptionsKit()) const

Unhighlights this ComponentPath with the provided options under the given Canvas in layer zero.

Parameters

in_canvas – The Canvas in which to perform the unhighlight.
in_options – The options to use to perform the unhighlight.

void Unhighlight(Canvas const &in_canvas, size_t in_layer, HighlightOptionsKit const &in_options = HighlightOptionsKit()) const

Unhighlights this ComponentPath with the provided options under the given Canvas in the specified layer.

Parameters

in_canvas – The Canvas in which to perform the unhighlight.
in_layer – The layer under the provided Canvas in which to perform the unhighlight.
in_options – The options to use to perform the unhighlight.

virtual ~ComponentPath(): Releases a reference to the database object this object is tied to.

Public Static Functions

static void Isolate(HPS::ComponentPathArray &in_component_paths, Canvas const &in_canvas, size_t in_layer = 0)

Shows only the objects in the supplied ComponentPathArray and hides all other Component objects under the given Canvas in the specified layer. When performing a highlight in combination with this function the highlight must be applied with Drawing::Overlay::InPlace to display properly. See this section for limitations and details on managing component visibility.

See: Hide
See: Show
See: IsHidden
See: ResetVisibility
See: Programming Guide: Managing Component Visibility

Parameters

in_component_paths – A ComponentPathArray containing paths to isolate.
in_canvas – The Canvas in which to isolate the supplied paths.
in_layer – The layer under the provided Canvas in which to isolate the supplied paths.

static void ResetVisibility(HPS::ComponentPathArray &in_component_paths, Canvas const &in_canvas, size_t in_layer = 0)

Resets the visibility of all components at or below the given paths back to the visibility state defined by their model & view. See this section for limitations and details on managing component visibility.

See: Hide
See: Show
See: Isolate
See: IsHidden
See: Programming Guide: Managing Component Visibility

Parameters

in_component_paths – A ComponentPathArray containing paths to reset.
in_canvas – The Canvas in which to isolate the supplied paths.
in_layer – The layer under the provided Canvas in which to isolate the supplied paths.

static void SetPathMetaVisible(HPS::KeyPath const &path, bool visible)

Force the KeyPath to be visible or invisible. This will override the visibility state defined by the model and view.

Parameters

path – The path to teh segment to set the visibility of.
visible – True to make the segment visible, false to make it invisible.

Public Static Attributes

static const HPS::Type staticType = HPS::Type::ComponentPath