Developer Guide
===============

This section provides an overview of the internal architecture and implementation details of the XGEE framework. It is intended for developers contributing to the core framework or those seeking a deeper understanding of how XGEE works under the hood.

Architecture Overview
---------------------

XGEE employs a specialized implementation of the **Model-View-Controller (MVC)** pattern to manage the graphical editor. This architecture separates the underlying data model (EOQ/Ecore), the graphical representation (mxGraph), and the user interaction logic.

Core Components
^^^^^^^^^^^^^^^

1.  **The Model Side (GraphModel)**
    The "Model" in XGEE refers to the state of the diagram being edited. It bridges the gap between the semantic user model (your domain data) and the graphical presentation.

    *   **GraphModelFactory:** The builder class responsible for constructing the graph model hierarchy. It iterates through the ``editorModel`` configuration to instantiate the necessary managers.
    *   **GraphModel:** Holds the hierarchy of graph objects (Vertices, Edges, Containers) and manages the synchronization between the graphical state and the underlying Ecore resources.
    *   **Managers (e.g., VertexManager):** Each type of graph object has a corresponding manager. These managers listen for changes in the Ecore model (e.g., a name change) and update the graphical representation accordingly.
    *   **Type Objects (e.g., VertexType):** Configuration objects created from the ``editorModel``. They inform the managers *how* an object should look (e.g., shape, color, size).

2.  **The Controller Side (GraphController)**
    The "Controller" handles user input, tool execution, and the application logic that dictates how the diagram behaves.

    *   **GraphControllerFactory:** The builder class for the controller hierarchy. Similar to the Model factory, it iterates the ``editorModel`` to build a parallel tree of controllers.
    *   **GraphController:** The central coordinator for user interactions. It manages the active tools (palette), drag-and-drop operations, and context menus.
    *   **Controllers (e.g., VertexController):** Specific controllers for each element type handle interaction logic, such as selection behavior and query execution (e.g., resolving sub-elements via queries).
    *   **Type Objects:** The controller side *also* instantiates Type objects (e.g., ``VertexType``). These are used to understand the *capabilities* of the objects (e.g., "Is this object resizable?", "What is the query string?").

Initialization Process
^^^^^^^^^^^^^^^^^^^^^^

When an editor is opened, both the Model and Controller hierarchies are built independently based on the same ``editorModel`` definition:

1.  **Model Initialization:** The ``GraphModelFactory`` traverses the editor definition, creating Managers and their corresponding Type objects.
2.  **Controller Initialization:** The ``GraphControllerFactory`` traverses the editor definition, creating Controllers. Crucially, it requests new Type objects from the factory to configure these controllers.

.. note::
   Because both factories instantiate Type objects independently, the system employs checks (e.g., via ``WeakSet``) to ensuring that initialization logic (like deprecation warnings) runs exactly once per editor definition element.

This separation allows the graphical state logic (Model) to remain distinct from the interaction logic (Controller), promoting modularity and easier maintenance.