addin technoligy

Add-In

Technology

1 General Description 2

Add-In Technology

Copyright 2015 by Allplan GmbH

Table of Contents

1. General Description 4

1.1 Main Idea ........................................................................................ 4

1.2 What does integration to Allplan GUI includes? .................................... 4

1.3 Plugins (AddIns) .............................................................................. 6

1.3.1 Types of Plugins ....................................................................... 6

1.3.2 Plugin Components ................................................................... 7

2. Plugin Definition File 8

2.1 File Name ........................................................................................ 8

2.2 Format ............................................................................................ 8

2.2.1 Plugin Document Type Definition (DTD) ...................................... 8

2.2.2 XML Coding ............................................................................. 8

2.2.3 XML declaration ....................................................................... 8

2.2.4 Document declaration ............................................................... 8

2.3 Elements ......................................................................................... 8

2.3.1 Logical structure ...................................................................... 9

2.3.2 Attributes .............................................................................. 11

2.3.2.1 attributes ...................................................... 11

2.3.2.2 attributes ........................................ 11

2.3.2.3 attributes ..................................... 12

2.3.2.4 attributes .................................... 12

2.3.2.5 attributes ............................................ 12

2.3.2.6 attributes ..................................................... 13

2.3.2.7 attributes .................................................... 14

2.3.2.8 attributes...................................................... 14

2.3.2.9 attributes ............................................... 15

2.3.2.10 attributes ......................................................... 15

3. Setup Instruction 16

4. How To 17

4.1 Verify npd-file ................................................................................ 17

4.2 Create resource DLL ....................................................................... 18

4.3 Create registered Plugin .................................................................. 18

4.4 Create licensed Plugin ..................................................................... 19


Add-In Technology


5. Examples 20

5.1 Simple Plugin ................................................................................. 20

5.2 More complicated Plugin .................................................................. 21


Add-In Technology


1. General Description

1.1 Main Idea This technology was developed for easier integration of external modules created by means of Allplan GmbH technologies NOI and FF in Allplan GUI . The main requirement was to create a technology which should integrate these external modules without any support from Allplan GmbH side and so they would be independent on Allplan releasing (except licensed Plugins via Allplan license file). Another requirement was that integrated Plugins modules look like native modules in Allplan.

1.2 What does integration to Allplan GUI includes?

Adding modules (like Lageplan) and module groups (like Geo) to Allplan CAD Navigator

Adding modules (like Lageplan) and module groups to context menu under the popup menu ModulWechsel


Add-In Technology


Adding items to the main program menu under menu popup Create and Modify

Creating toolbars and buttons for user functions

Associating of help(activated by F1 and Shift +F1) to user functions


Add-In Technology


Adding items to object context menu (like Linie knicken) for objects defined within AddIn

All Plugins integration controls (buttons, toolbars, menu items.) have same functional properties like native controls. It means for example:

- user can assign hotkey for plugin function(buttons) and modules - user can modify plugin toolbars - user can move/delete/add plugin buttons from(to) any toolbar - .

1.3 Plugins (AddIns) Plugin (Addin) in this document is understood an external dll created by means of technologies NOI and FF which add some user functionality to Allplan.

1.3.1 Types of Plugins

Plugins could be divided according to


Add-In Technology


licensing (related to End-User of plugin) on:

Licensed Plugins (licensed via Allplan license file)

Free Plugins ( no need special user license to see and to use this kind of Plugins in Allplan GUI)

Registration (related to Developer of plugin) on:

registered Plugins (this kind of plugin can for example create own Module Groups )

not registered (this kind of Plugins can not create own module group, their modules are always inserted to Module group Add-On modules)

who is creator on:

Intern ( developed by Allplan GmbH) Plugins. (These kind of Plugins are always licensed)

Extern Plugins (developed by other company)

1.3.2 Plugin Components Every Plugin consists of :

Dll created with using of FF and NOI technologies which contains user functionalities

Definition file (extension .npd), which defined how plugin is integrated in Allplan GUI. (This document just deals with how to create definition file for plugin)

Optionally, plugin can also consist of :

Resource DLL (dll which contains bitmaps (icons) for CAD navigator, for buttons, for menu items)

Help file

2 Plugin Definition File 8

Add-In Technology


2. Plugin Definition File

2.1 File Name Title name of plugin definition file should be the same as title name of external dll. Otherwise plugin definition file must define name of DLL with user functionalities. Extension of plugin definition file is NPD

2.2 Format

File format of Plugin definition file is XML.

2.2.1 Plugin Document Type Definition (DTD)

Plugin definition file (npd-file) must fulfil plugin document type definition which is defined in the file Plugin.dtd which is installed in Allplan directory PRG.

2.2.2 XML Coding Because npd-files can contain texts for more languages it is recommended to use UTF-8 coding (eventually iso-8859-1) .

2.2.3 XML declaration Use in case of coding UTF-8

2.2.4 Document declaration

Use

2.3 Elements Here is the list of element names (XML) and their purpose:

- root element


Add-In Technology


- defines general properties of plugin - defines plugin element (like macro, wall) - define function for registered element, which will be added to context menu for given registered element - define group of modules - define module what is set of user functions - define toolbar - define user function (button) - define list of text string(like names of functions) for one language define one text string

2.3.1 Logical structure

Logical structure of npd(xml) file is defined in DTD (document type definition) file. The structure is also visible on the following picture:


Add-In Technology


Plugin

PluginProperties

RegisteredElement

AssociatedFunction AssociatedFunction

ModuleGroup

RegisteredElement

AssociatedFunction

Module

Toolbar

Button Button Button Button

Toolbar

Button Button

Module

Toolbar

Button Button Button

Toolbar

Button Button Button

ModuleGroup

Module

Toolbar

Button Button Button Button

Toolbar

Button Button

StringTable StringTable

Text Text Text Text

Text TextText Text

Obligatory Elements

Optional Elements


Add-In Technology


From it we can see count and type of elements which every element can or must contain.

Element Number Element Plugin 1 PluginProperties 0-999 RegisteredElements 1-999 ModuleGroup 1-999 StringTable RegisteredElements 1-999 AssociatedFunction ModuleGroup 1-999 Module Module 1-3 Toolbar Toolbar 1-999 Button StringTable 1-9999 text

2.3.2 Attributes

2.3.2.1 attributes

Attribute Name X - Obligatory

O - Optional

Description

xmlns x Fixed value "http://www.w3.org/XML/1998/namespace"

2.3.2.2 attributes


O - Optional

Description

NameIDS x Index of text in string table e.g. 101 Which define name of Plugin

UUID x Unique identificator (UUID) of plugin (need to be generate ) e.g.

172E324F-3B4A-4dc0-9CF1-8AD9530C7E0F

HelpFileNameS o Name of help file. If help file is not defined and plugin functions defines help ID, so Allplan help is used.

Allowed format hlp and chm e.g. Plugin.hlp

ResourceFileS o Name of resource dll, where bitmaps(icons) for buttons, modules . are stored. If resource file is not specified, so dll with main plugin functionalities is assumed that contains bitmaps. e.g. PluginRes.dll

DllFileNameS o Name of Dll with main plugin user functionalities. This name must be specified if title name of plugin definition file is not as title name of dll with main user functionalities.

AboutTextIDS o Index of text in string table e.g. 101


Add-In Technology


Which define text to About Dialog not used yet

2.3.2.3 attributes


O - Optional

Description

UUID x Unique identificator (UUID) of plugin element

e.g. 172E324F-3B4A-4dc0-9CF1-8AD9530C7E0F

id x Specify EventID of user function which creates element(object) whic

EventID means input value to the function ::StartInputFunction(int EventID) from plugin DLL.

e.g. 33107

2.3.2.4 attributes


O - Optional

Description

id x EventID of function(defined within plugin) which will be added to context menu for RegisteredElement

2.3.2.5 attributes


O - Optional

Description

id x Arbitrary but unique (within plugin) id e.g. 10

NameIDS 0 Index of text in string table e.g. 101 Which define name of Module group. This text is used for example in CAD Navigator, in Menu. Note: module groups are created only for registered plugin. Modules from not registered Plugins are inserted to common group Add-on module

Bitmap16IDB 0 ID of bitmap (16x16 pixels) stored in resource file, which will be used as icon for this module group for example in CAD Navigator in case of small size of icon in Allplan.

Bitmap24IDB o ID of bitmap (24x24 pixels) stored in resource file,


Add-In Technology


which will be used as icon for this module group for example in CAD Navigator in case middle size of icon in Allplan.

PositionAfterIDS o - usable only for registered plugins

Index of text in string table e.g. 101 Which defines name of Module group after which will be this module group inserted. Text under index can be only one of these:

ALLGEMEINE

ZUSATZLICHE

GEO

ARCHITEKTUR

TGA

EXTERNE

VISUAL

FM

ING

HERSTELLER

FERTIGTEILE FEM

PositionBeforeIDS 0 - usable only for registered plugins

Index of text in string table e.g. 101 Which defines name of Module group before which will be this module group inserted. Text under index can be only one of these:

ALLGEMEINE

ZUSATZLICHE

GEO

ARCHITEKTUR

TGA

EXTERNE

VISUAL

FM

ING

HERSTELLER

FERTIGTEILE

FEM

2.3.2.6 attributes


O - Optional

Description

id x Arbitrary but unique (within plugin) id e.g. 10

NameIDS x Index of text in string table e.g. 101 Which define name of Module. . This text is used for example in CAD Navigator, in Menu.

Bitmap16IDB x ID of bitmap (16x16 pixels) stored in resource file, which will be used as icon for this module for


Add-In Technology


example in CAD Navigator in case of small size of icon in Allplan.

Bitmap24IDB o ID of bitmap (24x24 pixels) stored in resource file, which will be used as icon for this module group for example in CAD Navigator in case of middle size of icon in Allplan.

2.3.2.7 attributes


O - Optional

Description

NameS x Specify toolbar. It can be only one from these: Create Create2 Modify

2.3.2.8 attributes


O - Optional

Description

id x EventID of user function. Event ID means the value to the function ::StartInputFunction(int EventID)

NameIDS x Index of text in string table e.g. 101

Which define name of User Function. . This text is used for example in main and context menus

ArgumentS o additional argument for function (string value)

TooltipTextIDS o Index of text in string table e.g. 101 which define tooltip text for this button. If this is not defined, so name of function defined by NamesIDS attribute will be used also for tooltip.

StatusTextIDS o Index of text in string table e.g. 101

which define status text for this button. If this is not defined, so name of function defined by NamesIDS attribute will be used also for status.

HelpID 0 Defines ID of help page for the user function

Bitmap16IDB x ID of bitmap (16x16 pixels) stored in resource file, which will be used as icon for this button for example in toolbar in case of small size of icon in Allplan.

Bitmap24IDB o ID of bitmap (24x24 pixels) stored in resource file, which will be used as icon for this button group for example in toolbar in case of middle size of icon in Allplan.

EnabledIn o Define if this function will be enabled either File mode or Layout mode in Allplan. If this attribute is not defined , so this function (button) will be enabled both mode.


Add-In Technology


Possible values: FILE, LAYOUT

2.3.2.9 attributes


O - Optional

Description

xml:lang x Define language of texts. e.g. de Note: first string table in npd-document is taken as default string table and it is used in case when npd-document doesnt conten string table for current set program language in Allplan.

2.3.2.10 attributes


O - Optional

Description

ids x ID of string(text) on which is referring by a attribute within npd-document. Text for this ID is value of element

3 Setup Instruction 16

Add-In Technology


3. Setup Instruction

Installation (Uninstallation) of Plugins consists only of simply copying(deleting) of all plugin files (external dll, definition file, eventually resource and help files )

in case of extern Plugins to(from) the Allplan directory

\Allplan\Prg\Plugins

in case of intern and licensed Plugins to(from) \Allplan\Prg\ There is no need to anyhow register Plugins. Allplan simply look to those directories and all correct Plugins integrate to GUI.

4 How To 17

Add-In Technology


4. How To

4.1 Verify npd-file Npd files are automatically validated against DTD during Allplan start but if it is need to validate it, so for example it can be done by this code:

Verifying of XML

var xmlDoc = new ActiveXObject("Microsoft.XMLDOM")

xmlDoc.async="false"

xmlDoc.validateOnParse="true"

xmlDoc.load("pluginone.npd")

document.write("Error Code: ")

document.write(xmlDoc.parseError.errorCode)

document.write("Error Reason: ")

document.write(xmlDoc.parseError.reason)

document.write("Error Line: ")

document.write(xmlDoc.parseError.line)

Copy it and create from it a html document and open it in Internet Explorer. Replace red text by name of verified npd-document. One note: the npd document must be stored in Plugins directory. If everything is correct so result will look like on the following picture:

4 How To 18

Add-In Technology


4.2 Create resource DLL A resource-only DLL is a DLL that contains nothing but resources, such as icons, bitmaps, strings, and dialog boxes.

Here are steps how to create it in Visual Studio:

1, To create a resource-only DLL, you create a new Win32 DLL (non-MFC) project and add your resources to the project.

2, Select Win32 Project in the New Project dialog box and specify a DLL project type in the Win32 Project Wizard.

3, Create a new resource script that contains the resources (such as a string or a menu) for the DLL and save the .rc file.

4, On the Project menu, click Add Existing Item and insert the new .rc file into the project.

5, Specify the /NOENTRY linker option. /NOENTRY prevents the linker from linking a reference to _main into the DLL; this option is required to create a resource-only DLL.

6,B uild the DLL.

These steps how to create resource DLL was taken over :

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/vccore/html/_core_Create_a_Resource.2d.Only_DLL.asp

For npd-files are usable only bitmaps. Bitmaps:

Format ( bmp, png )

Size ( 16x16 pixels, 24x24 pixels )

Colors ( up to 16,7 mil.)

4.3 Create registered Plugin To have plugin registered is need if it is wanted to have plugin own modules group. In that case it is need to create plugin npd-files in the same way as in case of unregistered and then contact fy. Allplan GmbH for registration.

4 How To 19

Add-In Technology


Npd-file will be needed for registration.

4.4 Create licensed Plugin

To have plugin licenced is need if it is wanted to have plugin available only for user with concrete Allplan license. In that case it is need to create plugin npd-files in the same way as in case of not licensed plugin and then contact fy. Allplan GmbH.

Npd-file will be needed for licensing

5 Examples 20

Add-In Technology


5. Examples

5.1 Simple Plugin Here is example of creating of definition file(npd-file) for the simplest Plugin (contains only one user function).

What is need to know (to have)before creating of npd-file?

- external dll with user functionality (in our case for example Plugin.dll) - location of bitmaps (in Plugin.dll) - name of user functions (FunctionOne) - name of module ( ModuleOne) - event ID of user functions (33107) - bitmaps IDs and their size (for user function 1027 (size 16x16 pixels), for module

1028 (size 16x16pixels)) - name of toolbars where button for user functions will be inserted (Create toolbar) - languages of texts (only English) - help files and help ids for user function ( no help) - registered ? (no) - licenced ? (no)

What is need to do at first?

- Generate UUID of plugin (0C8052F0-A4D0-4296-94D1-F85CC307815A) - Assign arbitrary but unique id for module groups and modules (id of module group

is 1 , id of module 2)

Here is contents of npd-file:

PluginOne

5 Examples 21

Add-In Technology


Allplan GmbH

ModuleOne

FunctionOne

5.2 More complicated Plugin Here is example of definition file(npd-file) for more complicated Plugin which contains:

- 2 modules (ModuleOne, ModuleTwo) - 4 user functions in 3 toolbars - 2 text languages (English and German) - help file (PluginTwo.hlp) - resource file (PluginTwoRes.dll)

Contexts of npd-files:

5 Examples 22

Add-In Technology


NameIDS="0008"

Bitmap16IDB="26010"

HelpID="128"

EnabledIn="LAYOUT"/>

Plugin Two

Allplan GmbH

ModulOne

Function 1

Function 2

ModulTwo

Function3

Function 4

Plugin Zwei

Allplan GmbH

Modul Eins

Funktion 1

Funktion 2

Modul Zwei

Funktion 3

Funktion 4

addin technoligy

Documents

general description

addin technology copyright

plugin definition file

simple plugin

plugin components

registered plugin

licensed plugin

complicated plugin