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 Source Structure.

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::StringConverter

This interface is responsible for providing rules for string conversions inside nodes. There is a default implementation accessible by the call NE::GetDefaultStringConverter ().

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 accessible by the call NUIE::GetDefaultSkinParams (). 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, a group or a slot.
• OnDoubleClick: The engine calls this function when the user double clicks on the blank area.
• OnParameterSettings: The engine calls this function if a node or group parameter settings dialog should appear.

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

    }

    virtual NUIE::MenuCommandPtr OnContextMenu (
        const NUIE::Point& position,
        const NUIE::MenuCommandStructure& commands) override
    {
        return nullptr;
    }

    virtual NUIE::MenuCommandPtr OnContextMenu (
        const NUIE::Point& position,
        const NUIE::UINodePtr& uiNode,
        const NUIE::MenuCommandStructure& commands) override
    {
        return nullptr;
    }

    virtual NUIE::MenuCommandPtr OnContextMenu (
        const NUIE::Point& position,
        const NUIE::UIOutputSlotConstPtr& inputSlot,
        const NUIE::MenuCommandStructure& commands) override
    {
        return nullptr;
    }

    virtual NUIE::MenuCommandPtr OnContextMenu (
        const NUIE::Point& position,
        const NUIE::UIInputSlotConstPtr& inputSlot,
        const NUIE::MenuCommandStructure& commands) override
    {
        return nullptr;
    }

    virtual NUIE::MenuCommandPtr OnContextMenu (
        const NUIE::Point& position,
        const NUIE::UINodeGroupPtr& group,
        const NUIE::MenuCommandStructure& commands) override
    {
        return nullptr;
    }

    virtual void OnDoubleClick (
        const NUIE::Point& position) override
    {

    }

    virtual bool OnParameterSettings (
        NUIE::ParameterInterfacePtr paramAccessor,
        const NUIE::UINodePtr& uiNode) override
    {
        return false;
    }

    virtual bool OnParameterSettings (
        NUIE::ParameterInterfacePtr paramAccessor,
        const NUIE::UINodeGroupPtr& uiGroup) 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:

• OnEvaluationBegin/OnEvaluationEnd: Called when the main calculation algorithm is beginning and ending. You may want to change the cursor to busy, or something like this.
• 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 (),
        stringConverter (NE::GetDefaultStringConverter ()),
        skinParams (NUIE::GetDefaultSkinParams ()),
        drawingContext (),
        eventHandlers (),
        evaluationEnv (nullptr)
    {

    }

    virtual const NE::StringConverter& GetStringConverter () override
    {
        return stringConverter;
    }

    virtual const NUIE::SkinParams& GetSkinParams () override
    {
        return skinParams;
    }

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

    virtual double GetWindowScale () override
    {
        return 1.0;
    }

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

    virtual void OnEvaluationBegin () override
    {

    }

    virtual void OnEvaluationEnd () override
    {

    }

    virtual void OnValuesRecalculated () override
    {

    }

    virtual void OnRedrawRequested () override
    {

    }

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

private:
    NE::BasicStringConverter    stringConverter;
    NUIE::BasicSkinParams       skinParams;
    NUIE::NullDrawingContext    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. Currently the demo is only available on Windows, but the basics are the same for all operating systems.