.. _manipulation_extension:

Manipulation Extension
====================================================================================

.. image:: /images/FE_logo_345_60.*
   :width: 345px
   :height: 60px

| |FABRIC_PRODUCT_NAME| version |FABRIC_VERSION|
| |FABRIC_COPYRIGHT|

The Manipulation extension provides tools for defining custom user interaction models 
based on events propagated from a host DCC application or custom tool. 

The Manipulation system provides a flexible and low level api that enables any custom
tool to be build based on the provided events. No assumptions are made about the 
type of tool being build, or how manipulations should be defined. The major DCCs
expose APIs for developing custom tools that are heavily limited in flexibility due
to the assumptions made about the kinds of tools that TDs in production might need
to build.  


Events
------
The Manipulation systems are defined around custom event handling. Events, usually sent
from Fabric running in a DCC such as Maya, are handled via custom event handlers. 

The Events in Fabric Engine are modeled after the events generated by Qt. We have
:kl-ref:`KeyEvent`, :kl-ref:`MouseEvent` and :kl-ref:`MouseWheelEvent` objects that have
similar methods and members as the Qt events. This makes it easy to integrate the 
manipulation system into applications using the Qt event system. For example Maya uses
Qt for window management, so the Qt events can be easily translated into Fabric Engine 
events and sent to our :kl-ref:`EventDispatcher` via the :kl-ref:`EventDispatcherHandle`.

Each Fabric Engine integration converts events from the exposed tools API to the :kl-ref:`EventDispatcher`
in KL. While we have made every effort to ensure the events sent from the DCCs are similar
in some cases it has not been possible to propagate all events. 

In Maya, we have hooked an event filter directly into the Main Window and are able to
propagate all Qt events into the KL :kl-ref:`EventDispatcher`. In Softimage we do not 
have the ability to install an event filter so are limited to the events sent by the 
Softimage custom tools API.

Manipulators
------------
Only one manipulator can be active at any given time. All events from the DCC 
are propagated to the active manipulator for handling. 

If an event is sent to the manipulator, but the manipulator doesn't handle the event, then
the event is propagated back to the host DCC application. 


Undo Redo
---------

As a manipulator handles events, it can generate changes in the Fabric Engine 
data. These changes can be stored in the Host DCC undo stack via the method :kl-ref:`Host.addUndoRedoCommand`, which pushes KL Command objects onto the Host DCC undo stack. This enables artists to use undo and redo with the custom manipulators defined in KL. 


Table of Contents
-----------------

.. toctree::
  :maxdepth: 2
  
  files
  types
  functions
  constants

Indices and Tables
------------------

* :ref:`genindex`
* :ref:`search`