Chapter 9. Writing Add-In COM Object

Basic Concepts of Add-In COM Object

As discussed in 'Chapter 3. Hello world Example' simple Script codes can be defined to add new functionalities to StarUML™. However, to facilitate more complex and useful functionalities, it is better to use a program development environment that supports COM objects. For implementing StarUML™ Add-In COM Objects, it does not matter whether Delphi, Visual Basic or any other programming environment is used, as long as it supports COM technology.

The most important point about implementing StarUML™ Add-In COM Objects is that the IStarUMLAddIn interface defined by StarUML™ must be used.

As illustrated above, the IStarUMLAddIn interface inherits IUnknown and defines the three additional interface methods: InitializeAddIn(), FinalizeAddIn(), and DoMenuAction().

IStarUMLAddIn Interface Methods

The methods to be defined for implementing the IStarUMLAddIn interface are as follows.

Add-In COM Object Example

The following is a simple example of an StarUML™ Add-In COM Object implementing the IStarUMLAddIn interface. This is written in the Delphi Pascal syntax.

type
    AddInExample = class(TComObject, IStarUMLAddIn)
    private
        StarUMLApp: IStarUMLApplication;
    protected
        function InitializeAddIn: HResult; stdcall;
        function FinalizeAddIn: HResult; stdcall;
        function DoMenuAction(ActionID: Integer): HResult; stdcall;
        ...
    public
        procedure Initialize; override;
        destructor Destroy; override;
        ...
    end;

...

implementation

procedure AddInExample.Initialize;
begin
    inherited;
    StarUMLApp := CreateOleObject('StarUML.StarUMLApplication') as IStarUMLApplication;
    ...
end;

destructor AddInExample.Destroy;
begin
    ...
    StarUMLApp := nil;
    inherited;
end;

function AddInExample.InitializeAddIn: HResult;
begin
    ...
    Result := S_OK;
end;

function AddInExample.FinalizeAddIn: HResult;
begin
    ...
    Result := S_OK;
end;

function AddInExample.DoMenuAction(ActionID: Integer): HResult; stdcall;
begin
    Result := S_OK;
    ...
end;

Writing Add-In Description File

Basic Concept of Add-In Description File

Add-In Description file(*.aid) is XML based text file. All add-Ins plug-ined in StarUML must offer one add-in description file. StarUML registers Add-In object at system registry and initializes the Add-In object and menu extension file associated with it on the reference of add-in description file context.

Note: Add-In description file must have *.aid extension file name and placed in the subdirectory of StarUML module directory(<install-dir>\modules).

Structure of Approach Document File

Add-In description files follow the XML document conventions, and user-defined menu items are contained within the 'ADDIN' element.

<?xml version="1.0" encoding="..."?>

<ADDIN>
    <NAME>...</NAME>
    <DISPLAYNAME>...</DISPLAYNAME>
    <COMOBJ>...</COMOBJ>
    <FILENAME>...</FILENAME>
    <COMPANY>...</COMPANY>
    <COPYRIGHT>...</COPYRIGHT>
    <HELPFILE>...</HELPFILE>
    <ICONFILE>...</ICONFILE>
    <ISACTIVE>...</ISACTIVE>
    <MENUFILE>...</MENUFILE>
    <VERSION>...</VERSION>
    <MODULES>
        <MODULEFILENAME>...</MODULEFILENAME>
    </MODULES>
</ADDIN>

• encoding property: Defines the encoding property value of the XML document (e.g. UTF-8, EUC-KR). For details on this property value, see XML-related resources.
• NAME element: Defines the name of Add-In. (string value)
• DISPALYNAME element: Defines the name of Add-In that is shown to users in user interface. (string value)
• COMOBJ element: Specifies a ProgID of COM object. This element is used only in case of COM object based add-in. (string value)
• FILENAME element: Specifies Add-In file name. (string value)
• COMPANY element: Describes information of the Add-In developer company / individual. (string value)
• COPYRIGHT element: Describes the copyright notice. (string value)
• HELPFILE element: Specifies URL that contains help of the Add-In. (string value)
• ICONFILE element: Specifies icon file name of Add-In. (string value)
• ISACTIVE element: Specifies whether activates Add-in automatically in the starting of the program. (boolean value)
• MENUFILE element: Specifies menu extension file name associated to the Add-In. (string value)
• MODULES/MODULEFILENAME element: Specifies file names for additional COM objects in case that an Add-In object uses another COM objects. StarUML registers all additional COM objects specified in this element on execution. (string value)

Registering Add-In Description File

To make an add-in description file to be recognized automatically by StarUML, must place the file in the subdirectory of  StarUML module directory(<install-dir>\modules). StarUML searches and reads all add-in description files in the module directory and registers them at the program automatically when StarUML is initializing. If add-in description file is invalid or it's extension file name is not .aid, StarUML will not read the add-in description file and ignore it. It is recommended that make a subdirectory in the StarUML module directory and place the add-in description file in there to avoid modules being out of order.

Note: Delete the add-in description file from the StarUML module directory(<install-dir>\modules) not to use the add-in any more.

Option Extension

Basic Concept of Option Extension

StarUML supports setup options to adjust environment and detail functions of StarUML. Options are necessary not to StarUML application self but also add-ins supplies by third-party vendors. StarUML option extension enables Add-Ins to equip option configuring function without additional implementation. For using option extension, Add-In developer just defines option items with text file and places it in the Add-In directory. These option definitions are loaded on the program in initializing and displayed on option dialog. Add-In developer can save their time and efforts for implementing Add-In, and provide consistent user interface to users.

Follow the steps below to support setup options in Add-In.

1. Create an option schema document file (.opt) to define option items for the Add-In.
2. Copy the option schema document file (.opt) to subdirectory of module directory.

Hierarchy of Option Schema

StarUML constructs the option schema hierarchically as follows to manage many option items that defined in the application and add-ins in integrative.

• Option Schema: Option schema is the highest classification of option structure and is unit of option schema file. It appears as folder icon on the top level in the treeview that is placed in the left of option dialog.
• Option Category: Option category is the division of option schema by function, and displayed as lower level of treeview in the left of option dialog.
• Option Classification: Option classification classifies option items in detail, and corresponds to category row of inspector in option dialog. It has several option items that can be edited.
• Option Item: Option item is a unit of editing option value and corresponds to one row of inspector in option dialog.

Writing Option Schema

Option schema file to define option items is XML based text file which extension file name is *.opt. The option schema contents are contained within the OPTIONSCHEMA element, and there must not be any errors in syntax or contents.

<?xml version=”1.0” encoding=”...” ?>
<OPTIONSCHEMA id="..."> 
    <HEADER>
    ...
    </HEADER>
    <BODY>
    ...
    </BODY>
</OPTIONSCHEMA>

• encoding property: Specifies the encoding property value for the XML document (e.g. UTF-8, EUC-KR). For details on this property value, see XML-related resources.
• id property (OPTIONSCHEMA element): Specifies the name of the option schema. It is a unique name to identify the option schema from the others.
• HEADER element: See the Header Contents section.
• BODY element: See the Body Contents section.

Header Contents

The HEADER section of an option schema document contains general information for the option schema such as the option schema title and description. Structure of the header section is as follows.

<HEADER>
    <CAPTION>...</CAPTION> 
    <DESCRIPTION>...</DESCRIPTION> 
</HEADER>

• CAPTION element: This is a title of the option schema and displayed as caption of node in treeview of option dialog.
• DESCRIPTION element: Contains the description of the option schema.

Body Contents

The BODY section of an option schema document contains definition of all option items hierarchically.

<BODY>
    <OPTIONCATEGORY>
        <CAPTION>...</CAPTION>
        <DESCRIPTION>...</DESCRIPTION>
        <OPTIONCLASSIFICATION>
            <CAPTION>...</CAPTION>
            <DESCRIPTION>...</DESCRIPTION>
            <OPTIONITEM>
               ...
            </OPTIONITEM>
            ...             
        </OPTIONCLASSIFICATION>
         ... 
    </OPTIONCATEGORY>
     ... 
</BODY>

• OPTIONCATEGORY element: Defines structure of option category.
  • CAPTION element: Specifies caption of the option category displayed as node in treeview of the option dialog.
  • DESCRIPTION element: Contains brief description of the option category that displayed at option description memo box appears in the option dialog.
• OPTIONITEM element: Defines a number of option items. See the Option Item Definition section.

Option Item Definition

OPTIONCLASSIFICATION element can contain a number of option item definitions. Option item type are defined as several types such as integer, real, boolean, enumeration and so on. Option dialog supports information for inputting value or restricts value according to option item type.

Available types of option item are as follows.

The following represents format of option item definitions that belongs to OPTIONCLASSIFICATION in the option schema file.

<OPTIONCLASSIFICATION>
    <OPTIONITEM-INTEGER key="...">
        <CAPTION>...</CAPTION>
        <DESCRIPTION>...</DESCRIPTION>
        <DEFAULTVALUE>...</DEFAULTVALUE>
    </OPTIONITEM-INTEGER>
    <OPTIONITEM-REAL key="...">
        <CAPTION>...</CAPTION>
        <DESCRIPTION>...</DESCRIPTION>
        <DEFAULTVALUE>...</DEFAULTVALUE>
    </OPTIONITEM-REAL>
    <OPTIONITEM-STRING key="...">
        <CAPTION>...</CAPTION>
        <DESCRIPTION>...</DESCRIPTION>
        <DEFAULTVALUE>...</DEFAULTVALUE>
    </OPTIONITEM-STRING>
    <OPTIONITEM-BOOLEAN key="...">
        <CAPTION>...</CAPTION>
        <DESCRIPTION>...</DESCRIPTION>
        <DEFAULTVALUE>...</DEFAULTVALUE>
    </OPTIONITEM-BOOLEAN>
    <OPTIONITEM-TEXT key="...">
        <CAPTION>...</CAPTION>
        <DESCRIPTION>...</DESCRIPTION>
        <DEFAULTVALUE>...</DEFAULTVALUE>
    </OPTIONITEM-TEXT>
    <OPTIONITEM-ENUMERATION key="...">
        <CAPTION>...</CAPTION>
        <DESCRIPTION>...</DESCRIPTION>
        <DEFAULTVALUE>...</DEFAULTVALUE>
        <ENUMERATIONITEM>...</ENUMERATIONITEM>
        ...
    </OPTIONITEM-ENUMERATION>
    <OPTIONITEM-FONTNAME key="...">
        <CAPTION>...</CAPTION>
        <DESCRIPTION>...</DESCRIPTION>
        <DEFAULTVALUE>...</DEFAULTVALUE>
    </OPTIONITEM-FONTNAME>
    <OPTIONITEM-FILENAME key="...">
        <CAPTION>...</CAPTION>
        <DESCRIPTION>...</DESCRIPTION>
        <DEFAULTVALUE>...</DEFAULTVALUE>
    </OPTIONITEM-FILENAME>
    <OPTIONITEM-PATHNAME key="...">
        <CAPTION>...</CAPTION>
        <DESCRIPTION>...</DESCRIPTION>
        <DEFAULTVALUE>...</DEFAULTVALUE>
    </OPTIONITEM-PATHNAME>
    <OPTIONITEM-COLOR key="...">
        <CAPTION>...</CAPTION>
        <DESCRIPTION>...</DESCRIPTION>
        <DEFAULTVALUE>...</DEFAULTVALUE>
    </OPTIONITEM-COLOR>
    <OPTIONITEM-RANGE key="...">
        <CAPTION>...</CAPTION>
        <DESCRIPTION>...</DESCRIPTION>
        <DEFAULTVALUE>...</DEFAULTVALUE>
        <MINVALUE>...</MINVALUE>
        <MAXVALUE>...</MAXVALUE>
        <STEP>...</STEP>
    </OPTIONITEM-RANGE>
     ... 
</OPTIONITEMCLASSIFICATION>

• key property (all OPTIONITEM elements): Specifies it's own key value of the option item which is unique in the option schema. It is used in reading option values with COM interface.
• CAPTION element: Specifies caption of option item used in option dialog.
• DESCRIPTION element: Contains brief description of the option item that displayed at option description memo box appears in the option dialog.
• DEFAULTVALUE 요소 : Specifies default value of the option item. It must be in the range of valid values as follows. If default value is not valid as the type specified, can't edit value in the option dialog.　

  Option item type	Range of valid values
  OPTIONITEM-INTEGER	Integer in -2147483648 ~ 2147483647
  OPTIONITEM-REAL	Integer or floating-point value
  OPTIONITEM-STRING	String value
  OPTIONITEM-BOOLEAN	True or False
  OPTIONITEM-TEXT	String value
  OPTIONITEM-ENUMERATION	String defined in ENUMERATIONITEM element
  OPTIONITEM-FONTNAME	Font name.  e.g. Tahoma
  OPTIONITEM-FILENAME	File name with full path or empty string e.g. C:\My Document\Default.xml
  OPTIONITEM-PATHNAME	Valid path name or empty string e.g. C:\My Document
  OPTIONITEM-COLOR	Formatted string as follows ${W}{B}{G}{R} 　 {W} Reserved . Must be 00 {B} Blue of the color. Hexadecimal value in 0 ~ 255 (00 ~ FF) {G} Green of the color. Hexadecimal value in 0 ~ 255 (00 ~ FF) {R} Red of the color. Hexadecimal value in 0 ~ 255 (00 ~ FF) i.e. $00FF0000 , $00A0A0A0, $00FF00FF
  OPTIONITEM-RANGE	Integer value between minimum value specified in MINVALUE and maximum value specified in MAXVALUE

• ENUMERATIONITEM element: Enumerate items that selectable in the enumeration typed option item(OPTION-ENUMERATION). OPTION-ENUMERATION element must have at least one ENUMERATIONITEM element.
• MINVALUE element: Specifies minimum integer value in range typed option item(OPTION-RANGE).
• MAXVALUE element: Specifies maximum integer value in range typed option item(OPTION-RANGE).
• STEP element: Specifies an increment of range typed option value when click the spin button for editing.

The following example is the part of option schema file for StarUML.

<?xml version="1.0" encoding="UTF-8" ?>
<OPTIONSCHEMA id="ENVIRONMENT">
    <HEADER>
        <CAPTION>Environment</CAPTION>
        <DESCRIPTION> </DESCRIPTION>
    </HEADER>
    <BODY>
        <OPTIONCATEGORY>
            <CAPTION>General</CAPTION>
            <DESCRIPTION>General Configuration is a group of the basic and general option items for the program. This category includes the [General], [Browser], [Collection Editor] and [Web] subcategories.</DESCRIPTION>
            <OPTIONCLASSIFICATION>
                <CAPTION>General</CAPTION>
                <DESCRIPTION></DESCRIPTION>
                <OPTIONITEM-RANGE key="UNDO_LEVEL">
                    <CAPTION>Max. number of undo actions</CAPTION>
                    <DESCRIPTION>Specifies the maximum number of actions for undo and redo.</DESCRIPTION>
                    <DEFAULTVALUE>30</DEFAULTVALUE>
                    <MINVALUE>1</MINVALUE>
                    <MAXVALUE>100</MAXVALUE>
                    <STEP>1</STEP>
                </OPTIONITEM-RANGE>
                <OPTIONITEM-BOOLEAN key="CREATE_BACKUP">
                    <CAPTION>Create backup files</CAPTION>
                    <DESCRIPTION>Specifies whether to create backup files when saving changes.</DESCRIPTION>
                    <DEFAULTVALUE>True</DEFAULTVALUE>
                </OPTIONITEM-BOOLEAN>
            </OPTIONCLASSIFICATION>
        </OPTIONCATEGORY>
    </BODY>
</OPTIONSCHEMA>

Registering Option Schema

To make a option schema to be recognized automatically by StarUML, must place the file in the subdirectory of StarUML module directory(<install-dir>\modules). StarUML searches and reads all option schema files in the module directory and registers them at the program automatically when StarUML is initializing. If option schema file is invalid or it's extension file name is not .opt, StarUML will not read the option schema file and ignore it. It is recommended that make a subdirectory in the StarUML module directory and place the add-in description file in there to avoid modules being out of order.

Note: Delete option schema file from the StarUML module directory(<install-dir>\modules) not to use the option extension any more.

Accessing Option Values

Accessing Option Values with COM Interface

You can access the option values that user changed in option dialog by using COM interface of StarUML.
GetOptionValue() of IStarUMLApplication returns option value depends on SchemaID and Key inputted as variant.
The method usage is as follows.

IStarUMLApplication.GetOptionValue(SchemaID: String, Key: String): Variant

• SchemaID: Schema id that defined in the option schema file.
• Key: Key of option item that defined in the option schema file.

Use the Variant typed return value of GetOptionValue() by casting it according to the type of each option item. You can read the value directly without additional type casting in script languages such as JScript and VBScript.

The following is JScript example that reads "UNDO_LEVEL" option value defined in the StarUML environment option schema and output it to message box.

var app = new ActiveXObject("StarUML.StarUMLApplication");
var undoLevel = app.GetOptionValue("ENVIRONMENT", "UNDO_LEVEL");

WScript.Echo("Max. number of undo actions : " + undoLevel);

Processing change event of option value

StarUML propagates events that occurs in using the program to Add-ins that implement IEventSubscriber interface. If user changes option values in option dialog, Application invokes event handler- NotifyEvent()- of Add-ins that implement IEventSubscriber. If you want to apply option values promptly to the Add-in when user changes the option values, implement IEventSubscriber interface and NotifiyEvent() to read the option values by using IStarUMLApplication.GetOptionValue() method in case of EVK_OPTIONS_APPLIED event. Add-Ins that use script such as VBScript and JSCript cannot apply option values to the Add-in becase they can't implement IEventSubscriber interface.

For the details of event handling, it will be featured in the next section.

Basic Concepts of Event Subscription

An Add-In Object that implements the IEventSubscriber interface can subscribe to various internal events of the StarUML™ application. Whenever an internal event occurs, the StarUML™ application calls the NotifyEvent method of the registered IEventSubscriber type objects.

The class diagram below illustrates the organization of the external API interfaces related to event subscription.

Kinds of Events

As illustrated above, the EventKind enumeration defines the kinds of internal events of the StarUML™ application that can be subscribed by Add-In objects that implement the IEventSubscriber interface. The table below describes each literal of the EventKind enumeration.

Subscribing to Events

In order for an Add-In to subscribe to the StarUML™ application events, it needs to implement the IEventSubscriber interface in addition to the IStarUMLAddIn interface, which is the common interface for all StarUML™ Add-Ins.

The following example shows the class definition of an StarUML™ Add-In object that implements the IStarUMLAddIn interface and the IEventSubscriber interface. This example is written in Delphi Pascal.

type
    AddInExample = class(TComObject, IStarUMLAddIn, IEventSubscriber)
    private
        StarUMLApp: IStarUMLApplication;
        EventPub: IEventPublisher;
    protected
        function InitializeAddIn: HResult; stdcall;
        function FinalizeAddIn: HResult; stdcall;
        function DoMenuAction(ActionID: Integer): HResult; stdcall;
        function NotifyEvent(AEvent: EventKind): HResult; stdcall;
        ...
    public
        procedure Initialize; override;
        destructor Destroy; override;
        ...
    end;

Event Subscription Registration and Removal

In order for an Add-In object, which implements the IEventSubscriber interface, to subscribe to events, the event subscription must be registered. Event subscription registration and removal can be done through the IEventPublisher type object. Reference to the IEventPublisher type object can be obtained through the IStarUMLApplication element. The following Delphi Pascal example shows obtaining reference to IStarUMLApplication and the IEventPublisher type object.

implementation

procedure AddInExample.Initialize;
begin
    inherited;
    StarUMLApp := CreateOleObject('StarUML.StarUMLApplication') as IStarUMLApplication;
    EventPub := StarUMLApp.EventPublisher;
end;

destructor AddInExample.Destroy;
begin
    EventPub := nil;
    StarUMLApp := nil;
    inherited;
end;

The IEventPublisher interface provides the following methods for registration and removal of event subscription. The "ASubscriber" argument for each method represents the actual Add-In object that implements the IEventSubscriber interface.

Use the Subscribe method if an Add-In object needs to subscribe to certain events only. For instance, for subscribing to two specific events, call the Subscribe method for each event. Use the SubscribeAll method to subscribe to all events. In general, the Subscribe and SubscribeAll methods are called by the IPlasticAddIn.InitializeAddIn method.

If an Add-In object no longer needs to subscribe to the registered events (e.g. when the object is terminated), all the events registered must be unregistered. Use the Unsubscribe method if the subscription was registered by the Subscribe method, and use the UnsubscribeAll method if the subscription was registered by the SubscribeAll method. In general, the Unsubscribe and SubscribeAll methods are called by the IStarUMLAddIn.FinalizeAddIn method.

The following example shows registration and removal of subscription to the EVK_ELEMENTS_ADDED and EVK_ELEMENTS_DELETED events.

implementation

function AddInExample.InitializeAddIn: HResult;
begin
    EventPub.Subscribe(Self, EVK_ELEMENTS_ADDED);
    EventPub.Subscribe(Self, EVK_ELEMENTS_DELETED);
    ...
    Result := S_OK;
end;

function AddInExample.FinalizeAddIn: HResult;
begin
    EventPub.Unsubscribe(Self, EVK_ELEMENTS_ADDED);
    EventPub.Unsubscribe(Self, EVK_ELEMENTS_DELETED);
    ...
    Result := S_OK;
end;

Acquiring Event Argument

When an event occurs, it is necessary to acquire the related arguments. For instance, when an event related to the creation of a modeling element occurs (EVK_ELEMENTS_ADDED), it is necessary to identify which modeling element is created. The IEventPublisher interface provides the following methods in respect of event arguments.

Processing Events

When a subscribed event occurs, the Add-In needs to execute appropriate processes. Whenever a subscribed event occurs, the StarUML™ application calls the NotifyEvent method of the respective Add-In and passes the event kind as an argument. The event kind is passed as an argument for the NotifyEvent method because it is possible for an Add-In to subscribe to more than one event. Each Add-In needs to implements the NotifyEvent method to arrive at a logic to execute various processes according to the event kinds.

The following example shows implementation of the NotifyEvent method. This example verifies the semantic validity of the element connections when the association element (UMLAssociation) or the generalization element (UMLGeneralization) is created in the StarUML™ application. (This example is a continuation of the examples above. For definition of the Add-In object, see the examples above.)

implementation

function AddInExample.NotifyEvent(AEvent: EventKind): HResult;
var
    M: IModel;
    Assoc: IUMLAssociation;
    Gen: IUMLGeneralization;
    End1, End2: IUMLClassifier;
begin
    if AEvent = EVK_ELEMENTS_ADDED then 
    begin
        if EventPub.GetEventArgModelCount = 1 then 
        begin
            M := EventPub.GetEventArgModelAt(0);

            // Association
            if M.QueryInterface(IUMLAssociation, Assoc) = S_OK then 
            begin
                End1 := Assoc.GetConnectionAt(0).Participant;
                End2 := Assoc.GetConnectionAt(1).Participant
                if End1.IsKindOf('UMLPackage') or End2.IsKindOf('UMLPackage') then
                    ShowMessage('Packages cannot have associations.')
                ...
            end;

          // Generalization
          if M.QueryInterface(IUMLGeneralization, Gen) = S_OK then 
          begin
              if Gen.Child.IsRoot then
                  ShowMessage('Root elements cannot have parent elements.');
              if Gen.Parent.IsLeaf then
                  ShowMessage('Leaf elements cannot have child elements.');
           end;
        end;
    end;

    Result := S_OK;
end;