============================
Direction (hwx.inspire.core)
============================

Specify a direction relative to another entity.

Directions are get or set in global coordinates.

Directional components are [x,y,z].

Directions are not normalized, this is required to match Inspire
behaviour of showing non normalized directions in Property Editor.

--------------
Public Methods
--------------

  +--------------------------------------------------+
  | classmethod apply_ (cls, **kwds)                 |
  +--------------------------------------------------+
  | OnAttributeModify_ (self, obj, attr, *args)      |
  +--------------------------------------------------+
  | activateListener_ (self, obj)                    |
  +--------------------------------------------------+
  | castForGet_ (self, obj, value)                   |
  +--------------------------------------------------+
  | castForSet_ (self, obj, value)                   |
  +--------------------------------------------------+
  | create_ (self, obj)                              |
  +--------------------------------------------------+
  | createList_ (self, listAttr, obj)                |
  +--------------------------------------------------+
  | createListList_ (self, listAttr, obj)            |
  +--------------------------------------------------+
  | deactivateListener_ (self, obj)                  |
  +--------------------------------------------------+
  | disable_ (self, obj)                             |
  +--------------------------------------------------+
  | enable_ (self, obj)                              |
  +--------------------------------------------------+
  | getCreateArgs_ (self)                            |
  +--------------------------------------------------+
  | getDisplayName_ (self, obj)                      |
  +--------------------------------------------------+
  | getGuiValue_ (self, obj, component=None, **kwds) |
  +--------------------------------------------------+
  | getInCoreValue_ (self, obj)                      |
  +--------------------------------------------------+
  | getReferenceFrame_ (self, obj)                   |
  +--------------------------------------------------+
  | getUnits_ (self, obj)                            |
  +--------------------------------------------------+
  | getValueList_ (self, obj)                        |
  +--------------------------------------------------+
  | getValueListList_ (self, obj)                    |
  +--------------------------------------------------+
  | getWrt_ (self, obj)                              |
  +--------------------------------------------------+
  | initialize_ (self, objCls, name)                 |
  +--------------------------------------------------+
  | loadValue_ (self, obj, value)                    |
  +--------------------------------------------------+
  | setInCoreValue_ (self, obj, value)               |
  +--------------------------------------------------+
  | setValue_ (self, obj, value)                     |
  +--------------------------------------------------+
  | setValueList_ (self, obj, value)                 |
  +--------------------------------------------------+
  | setValueListList_ (self, obj, value)             |
  +--------------------------------------------------+

--------------
Method Details
--------------

.. _apply:
.. classmethod:: apply(cls, **kwds)

Context manager to specify Attribute constructor kwds
Useful to avoid repeating kwds while defining a related group

.. _OnAttributeModify:
.. method:: OnAttributeModify(self, obj, attr, *args)

Callback method when the reference object gets modified.

.. _activateListener:
.. method:: activateListener(self, obj)

Listen to referenced object for any changes.

.. _castForGet:
.. method:: castForGet(self, obj, value)

Returns and validates the specified value.

.. _castForSet:
.. method:: castForSet(self, obj, value)

Converts and validates the triple value before setting.

:param obj: Object this attribute belongs to.
:type obj: GeneralObject
:param value: Value of the attribute to set.
:type value: str | list[float]

:returns: Validated and converted value.
:rtype: math.Vector


.. _create:
.. method:: create(self, obj)

Creates a triple attribute for the specified object.

.. _createList:
.. method:: createList(self, listAttr, obj)

Creates an attribute that has list of values for the specified object.

.. _createListList:
.. method:: createListList(self, listAttr, obj)

Creates an attribute that has nested list of values for the specified object.

.. _deactivateListener:
.. method:: deactivateListener(self, obj)

Stop listening to referenced objects.

.. _disable:
.. method:: disable(self, obj)

Disables listener for the reference object.

.. _enable:
.. method:: enable(self, obj)

Enables listener for the reference object.

.. _getCreateArgs:
.. method:: getCreateArgs(self)

Helper used in create methods

.. _getDisplayName:
.. method:: getDisplayName(self, obj)

Returns the display name of the attribute.

Display name is used show the objects attribute name in the Property editor.

.. _getGuiValue:
.. method:: getGuiValue(self, obj, component=None, **kwds)

Formats the direction value to display it in the Property Editor.

:param obj: Object to get direction value from.
:type obj: GeneralObject
:param component: Specifies which component of the direction is needs formatting.
               Component can be 'x', 'y' or 'z'.
:type component: str

:returns: Formatted direction value.
:rtype: str


.. _getInCoreValue:
.. method:: getInCoreValue(self, obj)

Calls the incore get method (defined in C++) of the attribute.

:param obj: Object this attribute belongs to.
:type obj: GeneralObject
:param value: Value of the attribute to get.
:type value: Any

:returns: Value returned by the incore get method.
:rtype: Any


.. _getReferenceFrame:
.. method:: getReferenceFrame(self, obj)

Get reference frames Matrix44 in base units.

.. _getUnits:
.. method:: getUnits(self, obj)

Returns the units of the attribute.

.. _getValueList:
.. method:: getValueList(self, obj)

Returns the list of values from the specified object.

.. _getValueListList:
.. method:: getValueListList(self, obj)

Returns the nested list of values from the specified object.

.. _getWrt:
.. method:: getWrt(self, obj)

Get object this attribute is relative to.

.. _initialize:
.. method:: initialize(self, objCls, name)

Initializes the attribute.

:param objCls: Object class this attribute belongs to.
:type objCls: class
:param name: Name of the attribute.
:type name: str


.. _loadValue:
.. method:: loadValue(self, obj, value)

Loads and sets the value, when a model is loaded

.. _setInCoreValue:
.. method:: setInCoreValue(self, obj, value)

Calls the incore set method (defined in C++) of the attribute.

:param obj: Object this attribute belongs to.
:type obj: GeneralObject
:param value: Value of the attribute to set.
:type value: Any


.. _setValue:
.. method:: setValue(self, obj, value)

Sets the specified value.

.. _setValueList:
.. method:: setValueList(self, obj, value)

Sets the specified list of values for the attribute.

.. _setValueListList:
.. method:: setValueListList(self, obj, value)

Sets the specified nested list of values for the attribute.