Filtering¶

Criteria¶

Module providing the Criteria class.

class UI4.Widgets.SceneGraphView.Filtering.Criteria.Criteria(numberOfElements=1)¶

Bases: object

A wrapper for a set of arbitrary indexed values which can be retrieved as a tuple of Integers, Floats or Strings.

__init__(numberOfElements=1)¶: Initializes an instance of the class.

getAsFloat()¶

Return type:	`tuple` of `float`
Returns:	The value(s) stored in this Criteria object as an ordered tuple of float.

getAsInt()¶

Return type:	`tuple` of `int`
Returns:	The value(s) stored in this Criteria object as an ordered tuple of integers.

getAsObject()¶

Return type:	`tuple` of `object`
Returns:	The value(s) stored in this Criteria object as an ordered tuple in their original form.

getAsString()¶

Return type:	`tuple` of `string`
Returns:	The value(s) stored in this Criteria object as an ordered tuple of string.

setValue(index, value)¶

Set the value at the given index.

Parameters:	index (`int`) – The numeric index which determines the position of the value set. value (Any value capable of converting to Integer, Double or String) – The value to be set at the specified index.

Evaluator¶

Module providing the Evaluator base class.

UI4.Widgets.SceneGraphView.Filtering.Evaluator.GetEvaluatorCriteria(name)¶

Return the list of criteria for the evaluator registered under the given name.

Parameters:	name (`str`) – The registered name of the Evaluator.
Return type:	`list` of `dict`
Returns:	Ordered list specifying the criteria accepted by the evaluator or None if the evaluator is not registered.
See:	`Evaluator.registerCriteriaList`

UI4.Widgets.SceneGraphView.Filtering.Evaluator.RegisterEvaluator(name, evaluatorClass)¶

Register the evaluator class type, evaluatorClass, against the specified name.

Parameters:	name (`str`) – Name to register the evaluator. evaluatorClass (`Evaluator`) – The class type so instances of the evaluator can be created.

class UI4.Widgets.SceneGraphView.Filtering.Evaluator.Evaluator¶

Bases: object

The Evaluator class contains the method signatures that subclasses of Evaluator must implement.

__init__()¶: Initializes an instance of the class.

clearCriteria()¶: Clears the criteria for this evaluator.

evaluate(value)¶

This method will be passed a value which you should evaluated against the criteria that have been set and return True or False.

Return type:	`bool`
Returns:	`True` or `False` depending on the input and criteria specified.

getCriteria()¶

Return type:	`dict` of `dict`
Returns:	A dictionary of dictionaries describing the currently set criteria for the Evaluator.

getDefaultCriteria()¶

Return type:	`tuple` of (`str`, `Criteria`)
Returns:	A tuple describing the criteria and it’s value that can be used where nothing has been supplied.

classmethod getName()¶

Return type:	`str`
Returns:	The name used to describe this evaluator.

classmethod registerCriteriaList()¶

This method should return an ordered list of dictionaries which describe the criteria this evaluator can accept.

The dictionary must specify the following key, value pairs:

name: C{str}
prefix: C{str}
suffix: C{str}
type: C{ColumnDataType}
default: C{object}
num_elements: C{int}

e.g.:

{
    "name": "Color",
    "prefix": "(RGB)",
    "suffix": None,
    "type": ColumnDataType.Color,
    "default": [255, 255, 255],
    "num_elements": 3
}

Users will create valid criteria based on the list you return from this function. name, prefix and suffix are human readable values that can be used to display in UIs.

Return type:	`list` of `dict`
Returns:	A list of dictionaries as specified above.

setCriteria(name, criteria)¶

Sets the criteria specified by name to the instance of the Criteria object, criteria.

Parameters:	name (`str`) – A name used to describe the criteria being set obtained from the list of criteria registered via registerCriteria(). criteria (`Criteria`) – An instance of a `Criteria` class.
See:	`registerCriteriaList`, `Criteria`

class UI4.Widgets.SceneGraphView.Filtering.Evaluator.CelEvaluator¶

Bases: UI4.Widgets.SceneGraphView.Filtering.Evaluator.Evaluator

This Evaluator will evntually containg CEL matching evaluation (basically handing off its criteria to a CEL matching function yet we don’t have matching functions exposed in Python yet.

CriteriaList = [{'num_elements': 1, 'name': 'CEL Expression', 'default': '//', 'prefix': None, 'type': <class 'UI4.Widgets.SceneGraphView.ItemDelegates.ParameterItemDelegate.ParameterItemDelegate'>, 'suffix': None}]¶

__init__()¶: Initializes an instance of the class.

evaluate(value)¶

getDefaultCriteria()¶

classmethod getName()¶

classmethod registerCriteriaList()¶

class UI4.Widgets.SceneGraphView.Filtering.Evaluator.RegexEvaluator¶

Bases: UI4.Widgets.SceneGraphView.Filtering.Evaluator.Evaluator

Evaluator to provide regular expression matching.

Internally this evaluator uses Python’s re module.

CriteriaList = [{'num_elements': 1, 'name': 'Regex', 'default': '.*', 'prefix': None, 'type': <class 'UI4.Widgets.SceneGraphView.ItemDelegates.ParameterItemDelegate.ParameterItemDelegate'>, 'suffix': None}]¶

__init__()¶: Initializes an instance of the class.

evaluate(value)¶

getDefaultCriteria()¶

classmethod getName()¶

classmethod registerCriteriaList()¶

setCriteria(name, criteria)¶

class UI4.Widgets.SceneGraphView.Filtering.Evaluator.EqualToEvaluator¶

Bases: UI4.Widgets.SceneGraphView.Filtering.Evaluator.Evaluator

Class provides simple Equality testing for strings and numbers

In the case of ColumnDataType.Number we convert the criteria and value passed to the evaluate function to float via float().

If you don’t specify either a Phrase or Number then False will be returned.

CriteriaList = [{'num_elements': 1, 'name': 'Phrase', 'default': '', 'prefix': None, 'type': <class 'UI4.Widgets.SceneGraphView.ItemDelegates.ParameterItemDelegate.ParameterItemDelegate'>, 'suffix': None}, {'num_elements': 1, 'name': 'Number', 'default': 0, 'prefix': None, 'type': <class 'UI4.Widgets.SceneGraphView.ItemDelegates.NumberItemDelegate.NumberItemDelegate'>, 'suffix': None}]¶

__init__()¶: Initializes an instance of the class.

evaluate(value)¶

getDefaultCriteria()¶

classmethod getName()¶

classmethod registerCriteriaList()¶

class UI4.Widgets.SceneGraphView.Filtering.Evaluator.LessThanEvaluator¶

Bases: UI4.Widgets.SceneGraphView.Filtering.Evaluator.Evaluator

Provides Less Than Evaluator.

CriteriaList = [{'num_elements': 1, 'name': 'Number', 'default': inf, 'prefix': None, 'type': <class 'UI4.Widgets.SceneGraphView.ItemDelegates.NumberItemDelegate.NumberItemDelegate'>, 'suffix': None}]¶

__init__()¶: Initializes an instance of the class.

evaluate(value)¶

getDefaultCriteria()¶

classmethod getName()¶

classmethod registerCriteriaList()¶

class UI4.Widgets.SceneGraphView.Filtering.Evaluator.GreaterThanEvaluator¶

Bases: UI4.Widgets.SceneGraphView.Filtering.Evaluator.Evaluator

Provides Greater Than Evaluator.

CriteriaList = [{'num_elements': 1, 'name': 'Number', 'default': -inf, 'prefix': None, 'type': <class 'UI4.Widgets.SceneGraphView.ItemDelegates.NumberItemDelegate.NumberItemDelegate'>, 'suffix': None}]¶

__init__()¶: Initializes an instance of the class.

evaluate(value)¶

getDefaultCriteria()¶

classmethod getName()¶

classmethod registerCriteriaList()¶

class UI4.Widgets.SceneGraphView.Filtering.Evaluator.FuzzyEqualityEvaluator¶

Bases: UI4.Widgets.SceneGraphView.Filtering.Evaluator.Evaluator

Class provides floating-point comparison within specified tolerance levels.

You can specify:

Both:
- PositiveTolerance Maximum allowable value from the value specified in the positive axis
- NegativeTolerance Maximum allowable value in the negative axis
  - True == Value - NegativeTolerance < Test < Value + PositiveTolerance
Or:
- Tolerance Maximum allowable in positive and negative axis.
  - True == Value - Tolerance < Test < Value + Tolerance

If neither are specified then Tolerance will be used with its default value.

This class is an example of more advanced use of the filtering system and is not currently made available.

CriteriaList = [{'num_elements': 1, 'name': 'Number', 'default': 0.0, 'prefix': None, 'type': <class 'UI4.Widgets.SceneGraphView.ItemDelegates.NumberItemDelegate.NumberItemDelegate'>, 'suffix': None}, {'num_elements': 1, 'name': 'PositiveTolerance', 'default': 0.1, 'prefix': None, 'type': <class 'UI4.Widgets.SceneGraphView.ItemDelegates.NumberItemDelegate.NumberItemDelegate'>, 'suffix': None}, {'num_elements': 1, 'name': 'NegativeTolerance', 'default': 0.1, 'prefix': None, 'type': <class 'UI4.Widgets.SceneGraphView.ItemDelegates.NumberItemDelegate.NumberItemDelegate'>, 'suffix': None}, {'num_elements': 1, 'name': 'Tolerance', 'default': 0.1, 'prefix': None, 'type': <class 'UI4.Widgets.SceneGraphView.ItemDelegates.NumberItemDelegate.NumberItemDelegate'>, 'suffix': None}]¶

__init__()¶: Initializes an instance of the class.

evaluate(value)¶

getDefaultCriteria()¶

classmethod getName()¶

classmethod registerCriteriaList()¶

Rule¶

Module providing the Rule class.

class UI4.Widgets.SceneGraphView.Filtering.Rule.Rule¶

Bases: object

Class draws together the Target and Evaluator classes and provides a method match which actually causes the invokation of the Evaluator’s evaluate() function for the resolved scene graph location.

__init__()¶

clearCriteria()¶: Clears the criteria for this rule.

flushLocationMatchCache()¶: Empty the cache of match results for this rule.

getComment()¶

Return type:	`str` or `None`
Returns:	This rule’s comment or `None` if one isn’t set.

getCriteria()¶

Return type:	`dict` of `dict`
Returns:	A dictionary of criteria that have been set for this evaluator.

getDefaultCriteria()¶

Return type:	`tuple` of (`str`, `Criteria`)
Returns:	A tuple describing the criteria and it’s value that can be used where nothing has been supplied.

getEvaluatorName()¶

Return type:	`str`
Returns:	The name of the evaluator being used by this rule.

getShowChildren()¶

getTarget()¶

Return type:	`Target`
Returns:	A reference to the target object.

isEnabled()¶

Return type:	`bool`
Returns:	`True` if this rule is enabled, otherwise `False`.

isInverted()¶

Return type:	`bool`
Returns:	`True` if this rule is inverted, otherwise `False`.

match(handle, topLevelHandle)¶

Using the Target, Evaluator and Criteria specified using setTarget, setEvaluator, setCriteria. Test if the value, as resolved by the Target object, at sceneGraphLocation matches the specifed Criteria for the given Evaluator.

Return type:	`bool`
Parameters:	handle (`SceneGraphHandle`) – Handle representing the scene graph location that will be used to test if the `Evaluator` and `Criteria` match. topLevelHandle (`SceneGraphHandle`) – Handle representing the top-level scene graph location that contains the scene graph location to evaluate.
Returns:	`True` if the `Rule` matches the scene graph location with the given handle under the scene graph location with the given top-level handle, otherwise `False`.

setComment(comment)¶

Sets the comment of this rule. The comment doesn’t affect the filtering itself, but is useful for documenting and identifying rules.

Parameters:	comment (`str` or `None`) – The new comment of this rule.

setCriteria(name, criteria)¶

Sets the Criteria required by the Criteria you have specified.

Parameters:	name (`str`) – The name used to refer to these particular criteria. criteria (`Criteria`) – The criteria object as described by the criteria required by the Evaluator you are using.

setEnabled(enabled)¶

Sets the enabled state of this rule. If not enabled, the rule will always match positively.

Parameters:	enabled (`bool`) – The new enabled state of this rule.

setEvaluator(evaluator)¶

Sets the Evaluator object to be used by this rule.

Parameters:	evaluator (`Evaluator`) – The evaulator that will be used to evaluator the rule.

setInverted(inverted)¶

Sets the inverted state of this rule. If inverted, the rule will invert the result of its matching procedure.

Parameters:	inverted (`bool`) – The new inverted state of this rule.

setShowChildren(showChildren)¶

setTarget(target)¶

Sets the Target object used to be used by this rule.

Parameters:	target (`Target`) – The target object that will be used to translate scene graph locations into actual values.

RuleConfigDialog¶

Module provides a simple Rule configuration user interface.

class UI4.Widgets.SceneGraphView.Filtering.RuleConfigDialog.RuleConfigDialog(bridge, parent=None)¶

Bases: PyQt5.QtWidgets.QDialog

Class to provide a simple filter rule configuration modeless dialog box.

COLUMN_ID_COMMENT = 8¶

COLUMN_ID_CRITERIA = 3¶

COLUMN_ID_ENABLE = 5¶

COLUMN_ID_EVALUATOR = 2¶

COLUMN_ID_INVERT = 6¶

COLUMN_ID_NAME = 0¶

COLUMN_ID_SHOWCHILDREN = 7¶

COLUMN_ID_TARGET = 1¶

COLUMN_ID_VALUE = 4¶

__init__(bridge, parent=None)¶

on_availableRulesMenu_triggered(action)¶

on_deleteSelectedButton_clicked()¶

on_invertMatchCheckBox_stateChanged(state)¶

on_matchPolicyCombo_currentIndexChanged(index)¶

showEvent(event)¶

RuleManager¶

Module providing the RuleManager class.

class UI4.Widgets.SceneGraphView.Filtering.RuleManager.RuleManager(bridge, evaluateRuleCallback)¶

Bases: object

Class to encapsulate the storage of filtering rules and rule matching logic.

MatchAllPolicy = 2¶

MatchAnyPolicy = 1¶

__init__(bridge, evaluateRuleCallback)¶

addRule(ruleName)¶

Adds a new rule to the current rule set using the specified name which can be used later to configure the rule.

The rule name must not be already used otherwise this function will raise an exception.

Parameters:	ruleName (`str`) – Name of the rule by which you can reference it later.
Raises:	e – `RuleManagerException` if ruleName already exists in the current rule set.

clearRuleCriteria(ruleName, triggerEvaluation=True)¶

Clears the criteria that have been set for the given rule.

Parameters:	ruleName (`str`) – The rule to be cleared. triggerEvaluation (`bool`) – Whether clearing the criteria should trigger re-evaluation of the rule set. This can be useful for managing user interaction.

getCurrentRules()¶

Return a dict of dict containing the list of current rules and their values.

Return type:	`dict` of `dict`
Returns:	Dictionary of dictionaries containing the current rule set.

getRuleByName(ruleName)¶

Parameters:	ruleName (`str`) – Name of the rule to return:
Return type:	`Rule` or `None`
Returns:	The rule object corresponding to the rule name or None if it does not exist.

getRuleMatchInversion()¶

Return type:	`bool`
Returns:	A boolean value indicating whether the result of rule evaluation will be inverted.

match(handle, topLevelHandle)¶

Using the current rule matching policy and rules that have been configured test if the current scene graph location matches the filter criteria.

Return type:	`bool`
Parameters:	handle (`SceneGraphHandle`) – Handle representing the scene graph location to evaluate. topLevelHandle (`SceneGraphHandle`) – Handle representing the top-level scene graph location that contains the scene graph location to evaluate.
Returns:	`True` if the rule set matches the scene graph location with the given handle under the scene graph location with the given top-level handle, otherwise `False`.

removeRule(ruleName)¶

Removes the rule specified by ruleName from the current rule set.

Parameters:	ruleName (`str`) – The ruleName to remove from the rule set. If if doesn’t exist this function will have no effect.

renameRule(oldName, newName)¶

Renames the given rule from the oldName to the newName. If this RuleManager instance already contains a Rule named the same as newName, name mangling will occur to avoid a conflict (_1, _2, etc will be appended to the end until a unique name is found). If the given oldName does not name a valid Rule, a ValueError is raised.

The result value is the finalised new rule name, after any potential name changes due to conflicts have taken place.

Return type:	`str`
Parameters:	oldName (`str`) – The name of the rule to be renamed. newName (`str`) – The new name to rename the rule to.
Returns:	The finalised new rule name, after any potential name changes due to conflicts have taken place.

setRuleComment(ruleName, comment)¶

Sets the comment of the given rule.

Parameters:	ruleName (`str`) – The rule whose inversion state we wish to set. comment (`str` or `None`) – The new comment of the given rule.

setRuleCriteria(ruleName, criteriaName, criteria)¶

Sets the criteria of the specified evaluator for a given rule.

This function will have no effect if ruleName refers to a non-existent Rule.

Parameters:	ruleName (`str`) – The rule name assigned to the Rule. criteriaName (`str`) – The criteria name required by the evaluator. criteria (`Criteria`) – The criteria object.

setRuleEnabled(ruleName, isEnabled, triggerEvaluation=True)¶

Sets the enabled state of the given rule.

Parameters:	ruleName (`str`) – The rule whose enabled state we wish to set. isEnabled (`bool`) – The new enabled state of the given rule. triggerEvaluation (`bool`) – Whether setting this state should trigger re-evaluation of the rule set. This can be useful for managing user interaction.

setRuleEvaluator(ruleName, evaluator, useDefaultCriteria=False)¶

Sets the evaluator of the specified rule.

This function will have no effect if ruleName refers to a non-existent Rule.

Parameters:	ruleName (`str`) – The rule name assigned to the Rule. evaluator (`Evaluator`) – The evaluator object to set.

setRuleInverted(ruleName, isInverted, triggerEvaluation=True)¶

Sets the inversion state of the given rule.

Parameters:	ruleName (`str`) – The rule whose inversion state we wish to set. isInverted (`bool`) – The new inversion state of the given rule. triggerEvaluation (`bool`) – Whether setting this state should trigger re-evaluation of the rule set. This can be useful for managing user interaction.

setRuleMatchInversion(invertMatch)¶

Sets whether the final result of all rule evaluation should be inverted.

Parameters:	invertMatch (`bool`) – A boolean value indicating whether the result of rule evaluation should be inverted.

setRuleMatchPolicy(policy)¶

Sets the rule matching policy the RuleManager should apply when testing scene graph locations against the current set of configured rules.

Parameters:	policy (`int`) – A valid rule matching policy

setRuleShowChildren(ruleName, showChildren, triggerEvaluation=True)¶

setRuleTarget(ruleName, column)¶

Sets the target of the specified rule.

This function will have no effect if ruleName refers to a non-existent Rule.

Parameters:	ruleName (`str`) – The rule name assigned to the Rule. column (`SceneGraphColumn`) – The column which will be targeted for the rule.

Target¶

Module providing the Target class.

class UI4.Widgets.SceneGraphView.Filtering.Target.Target(sceneGraphColumn, bridge, mode=0)¶

Bases: object

__init__(sceneGraphColumn, bridge, mode=0)¶

Creates a new instance of the Target class.

Parameters:	sceneGraphColumn (`SceneGraphColumn`) – The column object. bridge (`Bridge`) – A valid implementation of the `Bridge` class. mode (`int`) – The mode in which Target should behave, currently only AttributeMode is enabled.

getSceneGraphColumn()¶

Return type:	`SceneGraphColumn`
Returns:	The column against which to resolve each scene graph location.

resolve(handle, topLevelHandle)¶

Resolves the scene graph location specified to a particular value based on the target column and its current configuration.

Return type:	`object`
Parameters:	handle (`SceneGraphHandle`) – Handle representing the scene graph location to resolve to a value, in combination with the column with which this `Target` is associated. topLevelHandle (`SceneGraphHandle`) – Handle representing the top-level scene graph location that contains the scene graph location to evaluate.
Returns:	The value at the column and location pair.
Raises:	NotImplementedError – If `Target` mode is not AttributeMode.