-
Notifications
You must be signed in to change notification settings - Fork 36
Embedding Tutorial
In this tutorial you can learn how to create a simple application which embeds VisualScriptEngine. Before reading this tutorial I highly recommend you to understand the Source Structure.
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.
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 on Windows)
- MacOSAppSupport (optional, only on MacOS)
Of course you can skip this step, and use the sources directly in your application.
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.
This interface is responsible for providing rules for string conversions inside nodes. There is a default implementation accessible by the call NE::GetDefaultStringConverter ().
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.
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.
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 fine if you 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.
- OnParameterSettings: The engine calls this function if a node or group parameter settings dialog should appear.
- OnDoubleClick: The engine calls this function when the user double clicks on the blank area.
class MyEventHandler : public NUIE::EventHandler
{
public:
MyEventHandler () :
NUIE::EventHandler ()
{
}
virtual NUIE::MenuCommandPtr OnContextMenu (
NUIE::EventHandler::ContextMenuType type,
const NUIE::Point& position,
const NUIE::MenuCommandStructure& commands) override
{
return nullptr;
}
virtual bool OnParameterSettings (
NUIE::EventHandler::ParameterSettingsType type,
NUIE::ParameterInterfacePtr paramAccessor,
const NUIE::UINodePtr& uiNode) override
{
return false;
}
virtual void OnDoubleClick (
const NUIE::Point& position,
NUIE::MouseButton mouseButton) override
{
}
};This interface is responsible for handling clipboard operations. The application should store and retrieve clipboard data through this interface. A default in-memory implementation is available as NUIE::MemoryClipboardHandler.
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 (),
eventHandler (),
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::EventHandler& GetEventHandler () override
{
return eventHandler;
}
virtual NUIE::ClipboardHandler& GetClipboardHandler () override
{
return clipboardHandler;
}
virtual void OnSelectionChanged (const NUIE::Selection& selection) override
{
}
virtual void OnUndoStateChanged (const NUIE::UndoState& undoState) override
{
}
private:
NE::BasicStringConverter stringConverter;
NUIE::BasicSkinParams skinParams;
NUIE::NullDrawingContext drawingContext;
MyEventHandler eventHandler;
NUIE::MemoryClipboardHandler clipboardHandler;
NE::EvaluationEnv evaluationEnv;
};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 in the WindowsEmbeddingDemo and the MacOSEmbeddingDemo folders.