Integration at Document Level

www.altova.com Print this Topic Previous Page Up One Level Next page

Home >  Programmers' Reference > ActiveX Integration >

Integration at Document Level

Compared to integration at application level, integration at document level is a more complex, yet more flexible way to embed Authentic Desktop functionality into your application by means of ActiveX controls. With this approach, your code can access selectively the following parts of the Authentic Desktop user interface:

 

Document editing window
Project window
Info window
Messages window
Entry helper windows (Elements, Attributes, Entities)
Output window

 

As mentioned in Integration at Application Level, for an ActiveX integration at application level, only one control is required, namely the AuthenticDesktopControl. However, for an ActiveX integration at document level, functionality Authentic Desktop is provided by the following ActiveX controls:

 

1.AuthenticDesktopControl
2.AuthenticDesktopControl Document
3.AuthenticDesktopControl Placeholder

 

These controls are supplied by the AuthenticControl.ocx file available in the application installation folder of Authentic Desktop. When you develop the ActiveX integration with Visual Studio, you will need to add these controls to the Visual Studio toolbox (see Adding the ActiveX Controls to the Toolbox).

 

The basic steps to integrate the ActiveX controls at document level into your application are as follows:

 

1.First, instantiate AuthenticDesktopControl in your application. Instantiating this control is mandatory; it enables support for the AuthenticDesktopControl Document and AuthenticDesktopControl Placeholder controls mentioned above. It is important to set the IntegrationLevel property to ICActiveXIntegrationOnDocumentLevel (or "1"). To hide the control from the user, set its Visible property to False.

 

Note:When integrating at document level, do not use the Open method of the AuthenticDesktopControl; this might lead to unexpected results. Use the corresponding open methods of AuthenticDesktopControl Document and AuthenticDesktopControl PlaceHolder instead.

 

2.Create at least one instance of AuthenticDesktopControl Document in your application. This control supplies the document editing window of Authentic Desktop to your application and can be instantiated multiple times if necessary.

 

Use the method Open to load any existing file. To access document-related functionality, use the Path and Save or methods and properties accessible via the property Document.

 

Note:The control does not support a read-only mode. The value of the property ReadOnly is ignored.

 

3.Optionally, add to your application the AuthenticDesktopControl Placeholder control for each additional window (other than the document window) that must be available to your application.

 

Instances of AuthenticDesktopControl PlaceHolder allow you to selectively embed additional windows of Authentic Desktop into your application. The window kind (for example, Project window) is defined by the property PlaceholderWindowID. Therefore, to set the window kind, set the property PlaceholderWindowID. For valid window identifiers, see AuthenticDesktopControlPlaceholderWindow.

 

Note:Use only one AuthenticDesktopControl PlaceHolder for each window identifier.

 

For placeholder controls that select the Authentic Desktop project window, additional methods are available. Use OpenProject to load a Authentic Desktop project. Use the property Project and the methods and properties from the Authentic Desktop automation interface to perform any other project related operations.

 

For example, in C# or VB.NET with Visual Studio, the steps to create a basic, one-form application which integrates the Authentic Desktop ActiveX controls at document level could be similar to those listed below. Note that your application may be more complex if necessary; however, the instructions below are important to understand the minimum requirements for an ActiveX integration at document level.

 

1.Create a new Visual Studio Windows Forms project with a new empty form.
2.If you have not done that already, add the ActiveX controls to the toolbox (see Adding the ActiveX Controls to the Toolbox).
3.Drag the AuthenticDesktopControl from the toolbox onto your new form.
4.Set the IntegrationLevel property of the AuthenticDesktopControl to ICActiveXIntegrationOnDocumentLevel, and the Visible property to False. You can do this either from code or from the Properties window.
5.Drag the AuthenticDesktopControl Document from the toolbox onto the form. This control provides the main document window of Authentic Desktop to your application, so you may need to resize it to a reasonable size for a document.
6.Optionally, add one or more AuthenticDesktopControl Placeholder controls to the form (one for each additional window type that your application needs, for example, the Project window). You will typically want to place such additional placeholder controls either below or to the right or left of the main document control, for example:

ax_control_windows

7.Set the PlaceholderWindowID property of each AuthenticDesktopControl Placeholder control to a valid window identifier. For the list of valid values, see AuthenticDesktopControlPlaceholderWindow.
8.Add commands to your application (at minimum, you will need to open, save and close documents), as shown below.

 

Querying Authentic Desktop Commands

When you integrate at document level, no Authentic Desktop menu or toolbar is available to your application. Instead, you can retrieve the required commands, view their status, and execute them programmatically, as follows:

 

To retrieve all available commands, use the CommandsList property of the AuthenticDesktopControl.
To retrieve commands organized according to their menu structure, use the MainMenu property.
To retrieve commands organized by the toolbar in which they appear, use the Toolbars property.
To send commands to Authentic Desktop, use the Exec method.
To query if a command is currently enabled or disabled, use the QueryStatus method.

 

This enables you to flexibly integrate Authentic Desktop commands into your application's menus and toolbars.

 

Your installation of Authentic Desktop also provides you with command label images used within Authentic Desktop. See the folder <ApplicationFolder>\Examples\ActiveX\Images of your Authentic Desktop installation for icons in GIF format. The file names correspond to the command names as they are listed in the Command Reference section.

 

General considerations

To automate the behaviour of Authentic Desktop, use the properties, methods, and events described for the AuthenticDesktopControl, AuthenticDesktopControl Document, and AuthenticDesktopControl Placeholder.

 

For more complex access to Authentic Desktop functionality, consider using the following properties:

 

AuthenticDesktopControl.Application
AuthenticDesktopControlDocument.Document
AuthenticDesktopControlPlaceHolder.Project

 

These properties give you access to the Authentic Desktop automation interface (AuthenticDesktopAPI)

 

Note:To open a document, always use AuthenticDesktopControlDocument.Open or AuthenticDesktopControlDocument.New on the appropriate document control. To open a project, always use AuthenticDesktopControlPlaceHolder.OpenProject on a placeholder control embedding a Authentic Desktop project window.

 

For examples that show how to instantiate and access the necessary controls in different programming environments, see ActiveX Integration Examples.


© 2019 Altova GmbH