Uranium
Application Framework
UM.Settings.SettingDefinition.SettingDefinition Class Reference

Defines a single Setting with its properties. More...

Public Member Functions

def __init__
 Construcutor. More...
 
def __getattr__
 Override getattr to provide access to definition properties. More...
 
def __setattr__
 Override setattr to enforce invariant status of definition properties. More...
 
def key (self)
 The key of this setting. More...
 
def container (self)
 The container of this setting. More...
 
def parent (self)
 The parent of this setting. More...
 
def children (self)
 A list of children of this setting. More...
 
def relations (self)
 A list of SettingRelation objects of this setting. More...
 
def serialize (self)
 Serialize this setting to a string. More...
 
def getAllKeys (self)
 Gets the key of this setting definition and of all its descendants. More...
 
def serialize_to_dict (self)
 Serialize this setting to a dict. More...
 
def deserialize
 Deserialize this setting from a string or dict. More...
 
def getChild
 Get a child by key. More...
 
def matchesFilter
 Check if this setting definition matches the provided criteria. More...
 
def findDefinitions
 Find all definitions matching certain criteria. More...
 
def isAncestor
 Check whether a certain setting is an ancestor of this definition. More...
 
def isDescendant
 Check whether a certain setting is a descendant of this definition. More...
 
def getAncestors (self)
 Get a set of keys representing the setting's ancestors. More...
 
def __repr__ (self)
 
def __eq__
 
def addSupportedProperty
 Define a new supported property for SettingDefinitions. More...
 
def getPropertyNames
 Get the names of all supported properties. More...
 
def hasProperty
 Check if a property with the specified name is defined as a supported property. More...
 
def getPropertyType
 Get the type of a specified property. More...
 
def isRequiredProperty
 Check if the specified property is considered a required property. More...
 
def isReadOnlyProperty
 Check if the specified property is considered a read-only property. More...
 
def dependsOnProperty
 Check if the specified property depends on another property. More...
 
def addSettingType
 Add a new setting type to the list of accepted setting types. More...
 
def settingValueFromString
 Convert a string to a value according to a setting type. More...
 
def settingValueToString
 Convert a setting value to a string according to a setting type. More...
 
def getValidatorForType
 Get the validator type for a certain setting type. More...
 

Detailed Description

Defines a single Setting with its properties.

This class defines a single Setting with all its properties. This class is considered immutable, the only way to change it is using deserialize(). Should any state need to be stored for a definition, create a SettingInstance pointing to the definition, then store the value in that instance.

== Supported Properties

The SettingDefinition class contains a concept of "supported properties". These are properties that are supported when serializing or deserializing a setting. These properties are defined through the addSupportedProperty() method. Each property needs a name and a type. In addition, there are two optional boolean value to indicate whether the property is "required" and whether it is "read only". Currently, four types of supported properties are defined. Please DefinitionPropertyType for a description of these types.

Required properties are properties that should be present when deserializing a setting. If the property is not present, an error will be raised. Read-only properties are properties that should never change after creating a SettingDefinition. This means they cannot be stored in a SettingInstance object.

Constructor & Destructor Documentation

◆ __init__()

def UM.Settings.SettingDefinition.SettingDefinition.__init__ (   self,
  key 
)

Construcutor.

Parameters
keystring The unique, machine readable/writable key to use for this setting.
containerDefinitionContainerInterface The container of this setting. Defaults to None.
parentSettingDefinition The parent of this setting. Defaults to None.
i18n_catalogi18nCatalog The translation catalog to use for this setting. Defaults to None.

Member Function Documentation

◆ __getattr__()

def UM.Settings.SettingDefinition.SettingDefinition.__getattr__ (   self,
  name 
)

Override getattr to provide access to definition properties.

◆ __setattr__()

def UM.Settings.SettingDefinition.SettingDefinition.__setattr__ (   self,
  name 
)

Override setattr to enforce invariant status of definition properties.

◆ addSettingType()

def UM.Settings.SettingDefinition.SettingDefinition.addSettingType (   cls,
  type_name 
)

Add a new setting type to the list of accepted setting types.

Parameters
type_nameThe name of the new setting type.
from_stringA function to call that converts to a proper value of this type from a string.
to_stringA function that converts a value of this type to a string.

◆ addSupportedProperty()

def UM.Settings.SettingDefinition.SettingDefinition.addSupportedProperty (   cls,
  name 
)

Define a new supported property for SettingDefinitions.

Since applications may want custom properties in their definitions, most properties are handled dynamically. This allows the application to define what extra properties it wants to support. Additionally, it can indicate whether a properties should be considered "required". When a required property is not missing during deserialization, an AttributeError will be raised.

Parameters
namestring The name of the property to define.
property_typeDefinitionPropertyType The type of property.
kwargsKeyword arguments. Possible values:
requiredTrue if missing the property indicates an error should be raised. Defaults to False.
read_onlyTrue if the property should never be set on a SettingInstance. Defaults to False. Note that for Function properties this indicates whether the result of the function should be stored.
defaultThe default value for this property. This will be returned when the specified property is not defined for this definition.
depends_onKey to another property that this property depends on; eg; if that value changes, this value should be re-evaluated.

◆ children()

def UM.Settings.SettingDefinition.SettingDefinition.children (   self,
  List,
  SettingDefinition 
)

A list of children of this setting.

Returns
list<SettingDefinition>

◆ container()

def UM.Settings.SettingDefinition.SettingDefinition.container (   self,
  DefinitionContainerInterface 
)

The container of this setting.

Returns

◆ dependsOnProperty()

def UM.Settings.SettingDefinition.SettingDefinition.dependsOnProperty (   cls,
  name 
)

Check if the specified property depends on another property.

The value of certain properties can change if the value of another property changes. This is used to signify that relation.

Parameters
namestring The name of the property to check if it depends on another setting.
Returns
string The property it depends on or None if it does not depend on another property.

◆ deserialize()

def UM.Settings.SettingDefinition.SettingDefinition.deserialize (   self,
  serialized 
)

Deserialize this setting from a string or dict.

Parameters
serializedstring or dict A serialized representation of this setting.

◆ findDefinitions()

def UM.Settings.SettingDefinition.SettingDefinition.findDefinitions (   self,
  kwargs 
)

Find all definitions matching certain criteria.

This will search this definition and its children for definitions matching the search criteria.

Parameters
kwargsdict A dictionary of keyword arguments that need to match properties of the children.
Returns
list A list of children matching the search criteria. The list will be empty if no children were found.

◆ getAllKeys()

def UM.Settings.SettingDefinition.SettingDefinition.getAllKeys (   self,
  Set,
  str 
)

Gets the key of this setting definition and of all its descendants.

Returns
A set of the key in this definition and all its descendants.

◆ getAncestors()

def UM.Settings.SettingDefinition.SettingDefinition.getAncestors (   self,
  Set,
  str 
)

Get a set of keys representing the setting's ancestors.

◆ getChild()

def UM.Settings.SettingDefinition.SettingDefinition.getChild (   self,
  key 
)

Get a child by key.

Parameters
keystring The key of the child to get.
Returns
SettingDefinition The child with the specified key or None if not found.

◆ getPropertyNames()

def UM.Settings.SettingDefinition.SettingDefinition.getPropertyNames (   cls,
  type 
)

Get the names of all supported properties.

Parameters
typeDefinitionPropertyType The type of property to get the name of. Defaults to None which means all properties.
Returns
A list of all the names of supported properties.

◆ getPropertyType()

def UM.Settings.SettingDefinition.SettingDefinition.getPropertyType (   cls,
  name 
)

Get the type of a specified property.

Parameters
namestr The name of the property to find the type of.
Returns
DefinitionPropertyType corresponding to the type of the property or None if not found.

◆ getValidatorForType()

def UM.Settings.SettingDefinition.SettingDefinition.getValidatorForType (   cls,
  type_name 
)

Get the validator type for a certain setting type.

◆ hasProperty()

def UM.Settings.SettingDefinition.SettingDefinition.hasProperty (   cls,
  name 
)

Check if a property with the specified name is defined as a supported property.

Parameters
namestring The name of the property to check if it is supported.
Returns
True if the property is supported, False if not.

◆ isAncestor()

def UM.Settings.SettingDefinition.SettingDefinition.isAncestor (   self,
  key 
)

Check whether a certain setting is an ancestor of this definition.

Parameters
keystr The key of the setting to check.
Returns
True if the specified setting is an ancestor of this definition, False if not.

◆ isDescendant()

def UM.Settings.SettingDefinition.SettingDefinition.isDescendant (   self,
  key 
)

Check whether a certain setting is a descendant of this definition.

Parameters
keystr The key of the setting to check.
Returns
True if the specified setting is a descendant of this definition, False if not.

◆ isReadOnlyProperty()

def UM.Settings.SettingDefinition.SettingDefinition.isReadOnlyProperty (   cls,
  name 
)

Check if the specified property is considered a read-only property.

Read-only properties are properties that cannot have their value set in SettingInstance objects.

Parameters
namestring The name of the property to check if it is read-only or not.
Returns
True if the property is supported and is read-only, False if it is not required or is not part of the list of supported properties.

◆ isRequiredProperty()

def UM.Settings.SettingDefinition.SettingDefinition.isRequiredProperty (   cls,
  name 
)

Check if the specified property is considered a required property.

Required properties are checked when deserializing a SettingDefinition and if not present an error will be reported.

Parameters
namestring The name of the property to check if it is required or not.
Returns
True if the property is supported and is required, False if it is not required or is not part of the list of supported properties.

◆ key()

def UM.Settings.SettingDefinition.SettingDefinition.key (   self,
  str 
)

The key of this setting.

Returns
string

◆ matchesFilter()

def UM.Settings.SettingDefinition.SettingDefinition.matchesFilter (   self,
  kwargs 
)

Check if this setting definition matches the provided criteria.

Parameters
kwargsdict A dictionary of keyword arguments that need to match its attributes.

◆ parent()

def UM.Settings.SettingDefinition.SettingDefinition.parent (   self,
  SettingDefinition 
)

The parent of this setting.

Returns
SettingDefinition

◆ relations()

def UM.Settings.SettingDefinition.SettingDefinition.relations (   self,
  List,
  SettingRelation 
)

A list of SettingRelation objects of this setting.

Returns
list<SettingRelation>

◆ serialize()

def UM.Settings.SettingDefinition.SettingDefinition.serialize (   self,
  str 
)

Serialize this setting to a string.

Returns
string A serialized representation of this setting.

◆ serialize_to_dict()

def UM.Settings.SettingDefinition.SettingDefinition.serialize_to_dict (   self,
  Dict,
  str,
  Any 
)

Serialize this setting to a dict.

Returns
dict A representation of this setting definition.

◆ settingValueFromString()

def UM.Settings.SettingDefinition.SettingDefinition.settingValueFromString (   cls,
  type_name 
)

Convert a string to a value according to a setting type.

Parameters
type_namestring The name of the type to convert to.
string_valuestring The string to convert.
Returns
The string converted to a proper value.
Exceptions
ValueErrorRaised when the specified type does not exist.

◆ settingValueToString()

def UM.Settings.SettingDefinition.SettingDefinition.settingValueToString (   cls,
  type_name 
)

Convert a setting value to a string according to a setting type.

Parameters
type_namestring The name of the type to convert from.
valueThe value to convert.
Returns
string The specified value converted to a string.
Exceptions
ValueErrorRaised when the specified type does not exist.

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