SDK:VS Functions General Info

From Vectorworks Developer
Revision as of 15:39, 12 August 2013 by Root (talk | contribs) (1 revision)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

.SDK|SDK ..SDK:Types|SDK Types ..SDK:Using the SDK|Using the SDK ..VCOM:VCOM (Vectorworks Component Object Model)|VCOM Basics ..VCOM:Class Reference|VCOM Class Reference

VectorScript Functions Library

A VectorScript Function Extension enables developers to provide basic services to VectorScripts. They typically do not present any user interface, but simply perform some calculation or algorithm and then return the results.

Several library routines can be packaged together into one VectorScript Function Extension. There is a function name limitation in VectorScript of 20 characters. And also the parameters can be up to 10 for procedures and up to 9 for functions.

Calling a Library Routine

The VectorScript Function Extension defines routines that may be called from a VectorScript or from another SDK Plug-in.

Developers can refer to a list of currently installed library routines, and their code can verify that a particular routine is available at runtime also.

At runtime, the script can verify that a routine is currently installed by calling VerifyLibraryRoutine().

This technique will allow the script to continue to compile and run successfully even if a library routine is not available.

procedure test;
var
    update : BOOLEAN;
begin
    if VerifyLibraryRoutine('SomeRoutine') THEN
        SomeRoutine(24);
    else begin
        Message('The routine SomeRoutine is not available.');
    end;
end;
run(test);

The syntax for calling a library routine and passing in arguments is the same as for a built-in routine.


Register Menu Extension

Registering the extension is done in the module main function. See SDK:Plug-in Module#The Plug-in Module Environment.

This code registers a menu extension implementation class 'CExtVSFuncs' as such in the 'GROUPID_ExtensionVSFunctions' VCOM grouping (groups are used to improve the performance of Vectorworks when enumerating the available extensions):

REGISTER_Extension<TesterModule::CExtVSFuncs>( GROUPID_ExtensionVSFunctions, action, pInfo, ioData, cbp, reply );

Extension Class Definition

namespace TesterModule
{
    using namespace VWFC::PluginSupport;

Note #1, see after the code block.
    // ------------------------------------------------------------------------------------------------------
    class CExtVSFuncs : public VWExtensionVSFunctions
    {
    	DEFINE_VWVSFunctions;
    public:
                     CExtVSFuncs(CallBackPtr cbp);
    	virtual      ~CExtVSFuncs();
    };

Note #2, see after the code block.
    // ------------------------------------------------------------------------------------------------------
    class CMyVSRoutines : public VWPluginLibraryRoutine
    {
    public:
                        CMyVSRoutines();
    	virtual        ~CMyVSRoutines();

    public:
    	virtual PluginLibraryInitFlags    InitPluginLibrary();

    public:
    	// dispatch routine
    	DEFINE_LIB_DISPATCH_MAP;

Note #3, see after the code block.
    	// dispatch event functions
    	//void	  <function name>(VWPluginLibraryArgTable& argTable);

    	void	  OnAdd(VWPluginLibraryArgTable& argTable);
    	void	  OnMult(VWPluginLibraryArgTable& argTable);
    };
}
  • Note #1 - The 'CExtVSFuncs' is the VectorScript Functions extension definition class. It is subclass of VWFC:PluginSupport:VWExtensionVSFunctions.
  • Note #2 - The class 'CMyVSRoutines' is the implementation of a VectorScript routine set that is registered with the extension.
  • Note #3 - This is the section where a dispatch map is defined to redirect the VectorScript routine calls into separate functions.

Extension Class Implementation

using namespace TesterModule;

namespace TesterModule
{
Note #1, see after the code block.
    // --------------------------------------------------------------------------------------------------------
    SFunctionDef    gArrFunctionDefs[] = {
        {
            /* fName */            "Add",
            /* fCategory */        "Test Category",
            /* fDescription */     "This is test function",
            /* fVersion */          0,
            /* fScope */            0,
            /* fHasReturnValue */   true,
            /* fParams */ {
                { "p1",            kIntegerArgType },
                { "p2",            kIntegerArgType },
                { "RETURN",        kIntegerArgType },
                { NULL,            kIntegerArgType },
                { NULL,            kIntegerArgType },
                { NULL,            kIntegerArgType },
                { NULL,            kIntegerArgType },
                { NULL,            kIntegerArgType },
                { NULL,            kIntegerArgType },
                { NULL,            kIntegerArgType },
                { NULL,            kIntegerArgType },
            }
    	},
        {
            /* fName */            "Mult",
            /* fCategory */        "Test Category",
            /* fDescription */     "This is test function",
            /* fVersion */          0,
            /* fScope */            0,
            /* fHasReturnValue */   true,
            /* fParams */ {
                { "p1",            kIntegerArgType },
                { "p2",            kIntegerArgType },
                { "RETURN",        kIntegerArgType },
                { NULL,            kIntegerArgType },
                { NULL,            kIntegerArgType },
                { NULL,            kIntegerArgType },
                { NULL,            kIntegerArgType },
                { NULL,            kIntegerArgType },
                { NULL,            kIntegerArgType },
                { NULL,            kIntegerArgType },
                { NULL,            kIntegerArgType },
            }
    	},
    	// TERMINATE
    	{ NULL, NULL, NULL, 0, 0, FALSE, { {NULL,kIntegerArgType}, {NULL,kIntegerArgType}, {NULL,kIntegerArgType}, {NULL,kIntegerArgType}, {NULL,kIntegerArgType}, {NULL,kIntegerArgType}, {NULL,kIntegerArgType}, {NULL,kIntegerArgType}, {NULL,kIntegerArgType}, {NULL,kIntegerArgType}, {NULL,kIntegerArgType} } }
    };
}

Note #2, see after the code block.
// --------------------------------------------------------------------------------------------------------
// {FE9DB889-E94B-4175-8669-EC29380B2E73}
BEGIN_VWVSFunctions(
	/*Extension class*/   CExtVSFuncs,
	/*Universal name*/    "MyVSFuncs",
	/*Version*/           1,
	/*UUID*/              0xfe9db889, 0xe94b, 0x4175, 0x86, 0x69, 0xec, 0x29, 0x38, 0xb, 0x2e, 0x73 );
ADD_VWVSFunctions_ROUTINE( CMyVSRoutines );
END_VWVSFunctions;

Note #3, see after the code block.
// --------------------------------------------------------------------------------------------------------
// --------------------------------------------------------------------------------------------------------
CExtVSFuncs::CExtVSFuncs(CallBackPtr cbp)
    : VWExtensionVSFunctions( cbp, gArrFunctionDefs )
{
}

CExtVSFuncs::~CExtVSFuncs()
{
}

Note #4, see after the code block.
// --------------------------------------------------------------------------------------------------------
// --------------------------------------------------------------------------------------------------------
// define dispatch map
BEGIN_LIB_DISPATCH_MAP_Ex( CMyVSRoutines, gArrFunctionDefs );
    ADD_LIB_FUNCTION_Ex( "Add",        OnAdd	);
    ADD_LIB_FUNCTION_Ex( "Mult",       OnMult	);
END_LIB_DISPATCH_MAP_Ex;

Note #5, see after the code block.
// --------------------------------------------------------------------------------------------------------
CMyVSRoutines::CMyVSRoutines()
{
}

CMyVSRoutines::~CMyVSRoutines()
{
}

PluginLibraryInitFlags CMyVSRoutines::InitPluginLibrary()
{
    return PluginLibraryInitFlags(0);
}

void CMyVSRoutines::OnAdd(VWPluginLibraryArgTable& argTable)
{
Note #6, see after the code block.
    short    a = argTable.GetArgument(0).GetArgInteger();
    short    b = argTable.GetArgument(1).GetArgInteger();

    argTable.GetResult().SetArgInteger( a + b );
}

void CMyVSRoutines::OnMult(VWPluginLibraryArgTable& argTable)
{
    short    a = argTable.GetArgument(0).GetArgInteger();
    short    b = argTable.GetArgument(1).GetArgInteger();

    argTable.GetResult().SetArgInteger( a * b );
}
  • Note #1 - Implementing VWFC:PluginSupport:VWExtensionVSFunctions requires use of that structure to define the VectorScript Funcitons extension. This is actually an array of the structure. Each entry in the array is a single function definition. The last parameter defines the type of the return value if a function is defined. gcc compiler (on Mac) requires all 10 parameter to be defined when defining the array, so the extra parameters are just empty (NULL).
  • Note #2 - A macro that identifies the routine provider for the extension, the universal name, and the VCOM UUID.
  • Note #3 - Implementation of the custom menu extension.
  • Note #4 - This is the definition of the dispatch map. It maps a universal routine name to a function in the specified class.
  • Note #5 - Implementation of the routines provider class.
  • Note #6 - This is a sample of an implementation of a routine. The parameter provides the parameters for the call and is used to store the result.

See Also