How to Create a QuickField Add-in

With QuickField 5.1, you can extend its capabilities with add-ins. Add-in is a program or component that adds custom features to QuickField, such as custom menu items, toolbar buttons etc.

In this paper we describe how to create and register your own add-in. We also describe how to create a setup program for your add-in.

Overview of Add-in Support in QuickField

Add-in Types

There are two types of add-ins in QuickField: COM add-ins and EXE add-ins.

• COM add-ins are called from QuickField using COM (OLE Automation). So, COM add-in should be a COM server (either DLL server or EXE server). See How to Write a COM Add-ins below for more details.
  

• With EXE add-ins, it is possible to use any program as an add-in. During the add-in registration, you specify the name of the executable file (may be with parameter), and then, when necessary, QuickField will run this executable file.

Registration

To use an add-in, it is necessary to register it in QuickField. During this registration, you should specify the following information:

• Add-in type

• For COM add-ins, name of the COM class

• For EXE add-in, command line to start the executable

• User-friendly name for the add-in (optional)

• A brief description of the add-in (optional)

• Menu items for the add-in. As a rule, only one menu item is specified. However, for more advanced add-ins, you can specify several items.

  For each menu item, you should specify the following:

  • Menu text

  • Menu to add this item to (File, Edit, Problem, Tools etc.)

  • Status line to show for this menu item (optional)

  • You can specify, when this menu item should be available. You can choose one of the following variants: Always, In model editor only, In postprocessor only.

  • You can specify that this menu item should be added to context (right button) menu also.

  • You can specify that this menu item should be available from toolbar also.
    In this case, you can choose an icon for the toolbar button from the list of predefined icons.

  • You can specify a shortcut key for this menu item.

For more details about the add-in properties and add-in menu item properties, see articles Add-in Properties dialog box and Add-in Menu Item dialog box in the QuickField help.

You can register an add-in manually (using the QuickField dialog boxes), or programmatically (adding necessary keys to the registry).

• To register an add-in manually, click Add-in Manager on the Tools menu. Then click Add and specify the necessary fields in the Add-in Properties dialog box. For more details, see context help for these dialogs.

• To register an add-in programmatically, it is necessary to add several keys to the registry. See How to Register an Add-in from Setup Program below for more details about it.

How to Write a COM Add-in

In this section, we discuss how to create a COM add-in. (We do not discuss creating EXE add-ins in this article, just because it is very easy. In fact, any program can be used as an EXE add-in.)

You can create a COM add-in using any programming tool that allows creating a COM server (Visual Basic, Visual C++, Visual C#, Delphi and many other tools.)

In your COM server, you should implement an object with the following methods:

• OnCommand
• OnStart

Method OnStart is optional and could be omitted.

OnCommand Method

Summary

This method is called when user tries to perform the add-in action (that is, when user click the menu item, or click the toolbar button, or press the shortcut key for add-in).

Syntax

OnCommand (
   App As QuickField.Application,
   Menu As String,
   Flags As Long
)

Parameters

App

QuickField.Application object. This object allows you to manage QuickField application from your add-in. In particular, you should use this parameter to access other QuickField o bjects (Problem, Model, Result etc.).

Menu

Name of the menu item. Typically you need this parameter when there are several menu items for the same add-in only.

Flags

Bit 0 of this parameter is equal to 1 if the add-in was called from popup menu, otherwise it is equal to 0. Other bits are not used in the current version and are reserved for future use.

OnStart Method

Summary

This method is called when add-in is started, immediately before OnCommand method is called for the first time. So it makes sense to put your initialization code here. This method is optional and can be omitted.

Syntax

OnStart (
   App As QuickField.Application
)

Parameters

App

QuickField.Application object.

Creating Sample Add-in

Let us consider a simple example on how to create a QuickField COM add-in using Visual Basic 6.0.

You should do the following:

1. Start Visual Basic
   

2. Create new ActiveX DLL project (or ActiveX EXE, if you like).
   

3. Specify a project name (for example, MyProject).
   

4. Rename class Class1 (provide some readable name). In our example, let it be MyAddin.
   

5. On the Project menu click References and add the reference to the QuickField 5.1 Object Library.
   

6. In the Code window, insert the following lines:

   Public Sub OnCommand(app As QuickField.Application, menu As String)
   ... insert you code here ...
   End Sub

7. Build your program.

Now you should register your add-in in QuickField.

1. In the QuickField Tools menu click Add-in Manager.

2. Click the Add button. Add-in Properties dialog box will appear. In this dialog:

   1. Select Simple COM Add-in radio button.

   2. In the Name of the COM object for the add-in box, specify the COM object name.
      For our example, you should specify MyProject.MyAddin.
      In general, for Visual Basic projects the object name is <project name>.<class name>.

3. Click Add Item. Add-in Menu Item dialog box will appear.

   In this dialog, specify the Menu Text field. For our example, let it be My First Addin.

   Note    It also makes sense to specify other fields in Add-in Properties and Add-in Menu Item dialog boxes. For more details, see context help.

4. Click OK several times to close all dialog boxes.

Now the add-in is registered. Click Tools menu, and you will see that the new item My First Add-in was added to it.

If you click My First Add-in, the component you just wrote will be started, and your code will be executed.

How to Register an Add-in from Setup Program

To install your add-in, the following operations should be done in your setup program:

1. Copy your add-in (DLL or EXE file) to the user's disk.

2. For COM add-in, register it as a COM server.

3. Add the branch describing the add-in properties to the registry.

Let us consider the last step in more details.

Adding Add-in Properties to the Registry

All the properties of an add-in are stored in the registry branch:

   HKEY_LOCAL_MACHINE\Software\Tera Analysis\QuickField\AddIns\<name>,

where <name> is:

• for COM add-ins - an object name, as specified in the Name of the COM object for the add-in field.

• for EXE add-ins - a command line, as specified in the Command line to call the add-in field.

For example, for the sample add-in described above, the branch name will be:

   HKEY_LOCAL_MACHINE_USER\Software\Tera Analysis\QuickField\AddIns\MyProject.MyAddin

To add this branch from your setup program, we would recommend the following steps:

1. At your own computer, register your add-in manually using the Add-in Manager dialog box.

2. Using Regedit program, find the branch with the add-in settings.

3. Copy this branch to some .reg file (click Export Registry File in menu Registry in Regedit.)

4. Use this .reg file in your setup program to add the branch to the registry of the user's computer.