Embedded KitchenDraw Plugins

The plugins described previously whatever they are .NET, ActiveX, ordinary .DLL, or JavaScript plugins are the plugins that could be qualified as global plugins because they run independently of the catalogs used. This can be a problem for certain functions touching the objects of the scene.

For example, an OnObjectPlaceAfter plugin function belonging to a global plugin will be executed after any object is placed into the scene no matter what catalog it comes from. However, it is often suitable that this kind of function is called only for objects from a particular catalog.

The useless calls to plugin functions reduce the system performances. Moreover, a global plugin is separated from a catalog even if it is dedicated to managing only some objects of the catalog. This could lead to version inconsistency risks and makes it more difficult to deploy both the catalog and the plugin at the same time.

That's why embedded plugins technology was created. Embedded are inside the same plugins as global ones, but they are placed inside catalog resources.

The differences between these embedded plugins and global plugins are the following:

  • Additional events related to identified objects of the scene and belonging to the catalog can be managed: the placement, the deletion, the modification, the change of position, orientation or dimension of an object, the price calculation as well as the opening of the contextual menu when an object is active (allowing the addition of a menu item). Caution: the removal of a component triggers an OnChange modification event to the component object as well as to the "parent" object.
  • The association between a plugin function and an event can be done block per block in the block scripts.

To allow embedded plugins execution, KitchenDraw automatically extracts the plugins:

  • Plugins\Catalogs<catalogfilename>\ subdirectory of the application directory is used for .NET, ActiveX and ordinary .DLL plugins;
  • JavaScript plugins are directly loaded to memory from catalog resources.

A Very Basic Example

Here's the sample of a very basic embedded plugin, which should show a messagebox each time an object is being added:

using KD.SDK2;
using System.Windows.Forms; // to use MessageBox

namespace AVeryBasicEmbeddedPlugin
{
    public class Plugin
    {
        public bool B1P1T_Add(int unused)
        {
            // Let's obtain a connection to the KitchenDraw application:
            var appli = new Appli();

            // Let's get current active object - which is for this kind 
            // of event an object being added:
            Scene.Object activeObject = appli.CallParamsInfo.ActiveObject;

            MessageBox.Show(activeObject.Name);

            // Let's indicate that the execution was ok
            // and the adding of the object should be proceeded:
            return true;
        }
    }
}

After the plugin is compiled, you should incorporate it in the catalog resources. This is done in the following way:

  • Open MobiScript window (via Setup > Catalogs > MobiScript menu), and open the catalog in which you want to incorporate the plugin (via File > Open menu of the MobiScript window).
  • Go to the Resources table.
  • Add a line in the table by clicking the Add button in the bottom of the window.
  • Double-click the Name cell of the new line. "Open file" dialog box will apear allowing you to choose a file. Choose the plugin and it will be incorporated in the catalog.

If you wish to replace the existing plugin in the catalog, then the sequence is the same except that you should modify the existing line of the Resources table instead of adding a new one.

Please be aware that you need to restart the KitchenDraw application to load the updated version of an embedded plugin.

After the plugin is embedded, ordinary public methods declared in its Plugin class must be referred in block scripts in order to be executed. Here's the script of the block whose code is B1P1T:

B 1P(H=H-C59) +1T(H=C59)
@OnPlace(VeryBasicEmbeddedPlugin.dll.B1P1T_Add)

@OnPlace(...) expression in this script attaches to the OnPlace event fired for the block the B1P1T_Add function of a plugin from resource having VeryBasicEmdebbedPlugin.dll name. Notice that resource name is not necessarily the same as the plugin filename itself, though it is true in the in the overwhelming majority of cases. Notice also that the plugin function name can be chosen arbitrarily by a programmer, since the connection between an event and corresponding plugin function is managed by the block script for the events that are special for embedded plugins (you can find the list of them below).

Block Script Events For Embedded Plugins

Besides the "global" plugin events offered by the SDK2, embedded plugins can utilize some additional events fired by objects of a scene according to their block script:

Event Description
OnPlace Placement of an article in the scene by Drag and Drop from the catalogue window; by copy/paste or duplication; from an ECatalog or by execution of an SDK2 function adding an object. This event is also triggered for the object components.
OnDelete Deletion of an object of the scene by pressing the "Del" or "Back Space" key; by choosing the corresponding menu items; by choosing the "Edit
OnChange Change of the object itself (attributes, finishes, components, quantity, etc).
OnPriceCalculate Any modification of the object having a potential impact on its price (attributes, finishes, components, quantity, manual price change, discount, special conditions, opening of the scene,...)
It can be important to manage this event by Plugin if the calculation of the article price is so complex that it cannot be defined in MobiScript by one of the native price types.
In this case, the object price calculation function will be able to calculate the object price from its catalog price, an intermediate price, a price coming from a web service or from an external file (different to the catalog) combining the above data with its own formula which will perhaps use external coefficients or coefficients found in catalog resource files. Everything is possible or almost!
OnResizeBefore Change in the object dimensions by the attributes dialog box; by stretching with the mouse by executing a SDK function in a Plugin or indirectly (for a component) by changing its "parent" dimensions.
If the plugin function returns false, the dimensions change is not carried out.
OnResizeAfter
OnMoveBefore Displacement or of the object with the mouse or by a menu command.
If the plugin function returns False, the position and/or orientation change is not carried out.
OnMoveAfter
OnContextualMenuBefore Before the contextual menu shows up. This event allows inserting a menu item into the contextual menu before it shows up thanks to the Appli.ActiveObjectInsertContextualMenuItem method.

These events are the keywords that can be used in block scripts to assign particular plugin functions to object events like this:

B 1P(H=H-C59) +1T(H=C59)
@OnPlace(VeryBasicEmbeddedPlugin.dll.B1P1T_Add)

Where:

  • OnPlace is an event name;
  • VeryBasicEmbeddedPlugin.dll is a name of the catalog resource containing the plugin;
  • B1P1T_Add is a name of the plugin function to call.