.. |ico3| image:: /images/rightarrow.jpeg
   :height: 2ex

CLO Event Plugin
=================

Overview
---------
The **CLO Event Plugin** system allows you to define custom actions in response to user interactions inside CLO, such as dragging and dropping files or text into the **2D** or **3D** windows.  

By implementing the provided event handler methods, developers can trigger CLO API commands dynamically based on drop events.  
For example, you can detect when a fabric file is dropped onto a pattern and automatically load and assign it.

Supported Events
-----------------
Event plugins are implemented by inheriting from the ``CloEventPlugin`` class defined in ``CloEventPlugin.h``.

Two main event handler functions are available:

- **MouseDropEventOn2DView**
  
  Triggered when the user drags and drops data onto the **2D window**.

- **MouseDropEventOn3DView**
  
  Triggered when the user drags and drops data onto the **3D window**.

Both handlers receive:
- ``_scenePosX`` / ``_scenePosY``: Drop location in scene coordinates.
- ``_mimeData``: A map containing MIME type keys (e.g., ``text/plain``, ``text/uri-list``) with their associated string data values.

Registration
--------------
Event plugins must be compiled into a **.dll** (Windows) or **.dylib** (macOS) file.

To register an event plugin:

1. Place your compiled plugin file in the appropriate directory:

   - **macOS:** ``$HOME/Documents/clo/plugins``  
   - **Windows:** ``C:\Users\Public\Documents\CLO\Plugins``

2. Restart CLO.

When CLO starts, any plugin files in the directory above will be automatically loaded and available for use.


Example: Drag & Drop Fabric Assignment
---------------------------------------
The following example shows a plugin that assigns a dropped fabric file to the pattern located at the drop point.

.. code-block:: cpp

    bool CloEventPlugin::MouseDropEventOn2DView(
        float _scenePosX, float _scenePosY,
        const std::unordered_map<std::string, std::vector<std::string>>& _mimeData)
    {
        printf("MouseDropEventOn2DView : %f(x), %f(y)\n", _scenePosX, _scenePosY);

        // Retrieve dropped text data (e.g., fabric file path)
        auto textList = GetMimeData("text/plain", _mimeData);
        if (!textList.empty())
        {
            auto patternAPI = CLOAPI::APICommand::getInstance().GetPatternAPI();
            auto fabricAPI = CLOAPI::APICommand::getInstance().GetFabricAPI();
            auto utilityAPI = CLOAPI::APICommand::getInstance().GetUtilityAPI();
            auto fabricFilePath = textList.at(0);

            utilityAPI->CreateProgressBar();
            utilityAPI->SetProgress("Load Fabric", 30);
            auto addedFabricIndex = fabricAPI->AddFabric(fabricFilePath);

            utilityAPI->SetProgress("Search Pattern", 60);
            auto selectedPatternIndex = patternAPI->GetPatternIndexFrom2DView(_scenePosX, _scenePosY);

            if (addedFabricIndex >= 0 && selectedPatternIndex >= 0)
            {
                utilityAPI->SetProgress("Assign Fabric to Pattern", 100);
                fabricAPI->AssignFabricToPattern(addedFabricIndex, selectedPatternIndex, 1);
            }
            else
            {
                utilityAPI->DeleteProgressBar(true);
                utilityAPI->DisplayMessageBox("Failed to load or assign fabric.");
            }
        }
        return true;
    }

Notes
------
- ``_mimeData`` may contain multiple formats; use only those relevant to your use case.  
- Both **2D** and **3D** drop handlers can be implemented in the same plugin.
- This system supports a wide variety of actions — not just fabric assignment — since any CLO API can be called from within the event handler.


|ico3| **CLO Event Plugin Diagram** 

.. figure:: /images/plugineventdiagram.png
   :align: center

|



|ico3| **CLO Event Plugin Demo** 

.. figure:: /images/eventplugin.gif
   :align: center

|