Embedding Tutorial

In this tutorial we will learn how to create a simple application which embeds VisualScriptEngine. Before reading this tutorial I highly recommend you to understand the Basic Concepts, Source Structure, and Building the Engine pages.

Building the Engine

Follow the steps on the Building the Engine page. You will need only the Core Modules, but if you are on windows, it is highly recommended to compile the windows related modules, too.

Linking the Engine to your Application

As the result of the previous step some binary library files are created. You have to link these to your application. Of course you have to add the Header folders of the modules to your applications include path.

You will need these modules:

• NodeEngine
• NodeUIEngine
• BuiltInNodes (optional, but recommended)
• WindowsAppSupport (optional, only if you are on windows, and don't want to do a lot of coding yourself)

Of course you can skip this step, and use the sources directly in your application.

Implementing Platform Dependent Interfaces

First of all you have to include the NUIE_NodeEditor.hpp file in your application. The next step is to implement the below platform dependent interfaces to make the engine well integrated with your system.

NUIE::StringSettings

This interface is responsible for providing rules for string conversions inside nodes. There is a default implementation called NE::DefaultStringSettings.

NUIE::SkinParams

This interface is responsible for the theme of the drawing. You can set colors, fonts, line weights and so on. There is a default implementation called NUIE::DefaultSkinParams. You can use this if you don't want to customize the look of the drawings.

NUIE::DrawingContext

This interface is responsible for all drawing operations. You have to implement all of the draw methods for primitives. If you use windows, you can find some implementations in the WindowsAppSupport module.

Important note: The context should be offscreen, because the engine usually draws on this context outside of the paint event. You should blit the content of this context in your applications paint event when the engine notifies you that the drawing is ready.

NUIE::EventHandlers

This interface is responsible for platform-dependent event handler implementations. The engine can call these functions anytime during user interactions. For this tutorial it is completely OK if we provide the default implementation for all of the functions.

Later, you have to implement two types of handlers:

• OnContextMenu: The engine calls these function when a context menu should appear over the blank area, or over a node or slot.
• OnParameterSettings: The engine calls this function if a node parameter settings dialog should appear.

class MyEventHandlers : public NUIE::EventHandlers
{
public:
    MyEventHandlers () :
        NUIE::EventHandlers ()
    {
    
    }

    virtual NUIE::UICommandPtr OnContextMenu (
        NUIE::NodeUIManager& uiManager,
        NUIE::NodeUIEnvironment& uiEnvironment,
        const NUIE::Point& position,
        const NUIE::UICommandStructure& commands) override
    {
        return nullptr;
    }

    virtual NUIE::UICommandPtr OnContextMenu (
        NUIE::NodeUIManager& uiManager,
        NUIE::NodeUIEnvironment& env,
        const NUIE::Point& position,
        const NUIE::UINodePtr& uiNode,
        const NUIE::UICommandStructure& commands) override
    {
        return nullptr;
    }

    virtual NUIE::UICommandPtr OnContextMenu (
        NUIE::NodeUIManager& uiManager,
        NUIE::NodeUIEnvironment& env,
        const NUIE::Point& position,
        const NE::OutputSlotPtr& outputSlot,
        const NUIE::UICommandStructure& commands) override
    {
        return nullptr;
    }

    virtual NUIE::UICommandPtr OnContextMenu (
        NUIE::NodeUIManager& uiManager,
        NUIE::NodeUIEnvironment& env,
        const NUIE::Point& position,
        const NE::InputSlotPtr& inputSlot,
        const NUIE::UICommandStructure& commands) override
    {
        return nullptr;
    }

    virtual NUIE::UICommandPtr OnContextMenu (
        NUIE::NodeUIManager& uiManager,
        NUIE::NodeUIEnvironment& env,
        const NUIE::Point& position,
        const NUIE::UINodeGroupPtr& group,
        const NUIE::UICommandStructure& commands) override
    {
        return nullptr;
    }

    virtual bool OnParameterSettings (
        NUIE::NodeParameterAccessorPtr paramAccessor) override
    {
        return false;
    }
};

NUIE::NodeUIEnvironment

When you implemented all of the above interfaces, you need one more implementation to get all of these together. The below implementation can do the job for you.

Some notes on the functions:

• OnValuesRecalculated: This function is called if any node is recalculated because of a user interaction.
• OnRedrawRequested: This function is called when the engine made some drawing on the offscreen context. In this case you have to fire a paint event, and blit the content of your offscreen context to an onscreen one.

class MyNodeUIEnvironment : public NUIE::NodeUIEnvironment
{
public:
    MyNodeUIEnvironment () :
        NUIE::NodeUIEnvironment (),
        stringSettings (L'.', L',', 2),
        skinParams (),
        eventHandlers (),
        evaluationEnv (nullptr),
        nodeEditorControl ()
    {
    
    }

    virtual const NE::StringSettings& GetStringSettings () override
    {
        return stringSettings;
    }

    virtual NUIE::SkinParams& GetSkinParams () override
    {
        return skinParams;
    }
    
    virtual NUIE::DrawingContext& GetDrawingContext () override
    {
        return drawingContext;
    }

    virtual NE::EvaluationEnv& GetEvaluationEnv () override
    {
        return evaluationEnv;
    }

    virtual void OnValuesRecalculated () override
    {
        
    }

    virtual void OnRedrawRequested () override
    {

    }

    virtual NUIE::EventHandlers& GetEventHandlers () override
    {
        return eventHandlers;
    }

private:
    NE::BasicStringSettings     stringSettings;
    NUIE::DefaultSkinParams     skinParams;
    MyDrawingContext            drawingContext;
    MyEventHandlers             eventHandlers;
    NE::EvaluationEnv           evaluationEnv;
};

Embedding the Engine

When all of the above interfaces are implemented, you have to create a NUIE::NodeEditor instance somewhere in your application, and forward all of your user inputs to this instance.

You can see an example on embedding the engine on Windows in the WindowsEmbeddingDemo folder.