===========================
Location (hwx.inspire.core)
===========================

Store a location relative to another entity.

Locations are get or set in global coordinates.

Locations relative to Features have special code to stay at the same point
on the feature after feature modifications like push/pull.

--------------
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)                                        |
  +------------------------------------------------------------+
  | getCoord_ (self, feature, point)                           |
  +------------------------------------------------------------+
  | getCoordLocation_ (self, feature, coord, normalized=False) |
  +------------------------------------------------------------+
  | 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)

Converts and returns the location value to gui units.

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

Converts and validates the location value before setting it.

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

:returns: Validated and converted value.
:rtype: Location


.. _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.

.. _getCoord:
.. method:: getCoord(self, feature, point)

Converts the location on the feature into UV coordinates.

None is returned if point is not touching feature

:param feature: Feature from which coordinates are extracted from.
:type feature: Feature
:param point: Point on the feature for which UV coordinates are derived.
:type point: Point

:returns: Coordinates from the converted location.
:rtype: UV Coordinates


.. _getCoordLocation:
.. method:: getCoordLocation(self, feature, coord, normalized=False)

Convert coordinates to location from the specified feature.

:param feature: Feature on which location is extracted.
:type feature: Feature
:param coord: Coordinates from which the location is derived.
:type coord: list[Point]
:param normalized: If True normalize the locations, defaults to False.
:type normalized: bool

:returns: Converted UV coordinates to location value.
:rtype: Location


.. _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 triple value to display it in the Property Editor.

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

:returns: Formatted triple 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.