C#
The C# programming language can be used to access the Application API functionality. You could use Visual Studio 2012/2013/2015/2017/2019/2022 to create the C# code, saving it in a Visual Studio project. Create the project as follows:
1.In Microsoft Visual Studio, add a new project using File | New | Project.
2.Add a reference to the Authentic Desktop Type Library by clicking Project | Add Reference. The Add Reference dialog appears. Browse for the Authentic Desktop Type Library component, which is located in the Authentic Desktop application folder, and add it.
3.Enter the code you want.
4.Compile the code and run it.
Example C# project
Your Authentic Desktop package contains an example C# project, which is located in the API\C# subfolder of the Examples folder :
Windows 7, Windows 8, Windows 10, Windows 11 | C:\Users\<username>\Documents\ |
You can compile and run the project from within Visual Studio 2012/2013/2015/2017/2019/2022. The code listing below shows how basic application functionality can be used. This code is similar to the example C# project in the API Examples folder of your application package, but might differ slightly.
Platform configuration
If you have a 64-bit operating system and are using a 32-bit installation of Authentic Desktop, you must add the x86 platform in the solution's Configuration Manager and build the sample using this configuration. A new x86 platform (for the active solution in Visual Studio) can be created in the New Solution Platform dialog (Build | Configuration Manager | Active solution platform | <New…>).
What the code listing below does
The example code listing below creates a simple user interface (screenshot below) with buttons that invoke basic Authentic Desktop operations:
•Start Authentic Desktop: Starts Authentic Desktop, which is registered as an automation server, or activates the application if it is already running.
•Open OrgChart.pxf: Locates one of the example documents installed with Authentic Desktop and opens it. If this document is already open it becomes the active document.
•Open ExpReport.xml: Opens another example document.
•Toggle View Mode: Changes the view of all open documents between Text View and Authentic View. The code shows how to iterate through open documents.
•Validate: Validates the active document and shows the result in a message box. The code shows how to handle errors and COM output parameters.
•Shut down Authentic Desktop: Stops Authentic Desktop.
You can modify the code (of the code listing below or of the example C# project in the API Examples folder) in any way you like and run it.
Compiling and running the example
In the API Examples folder, double-click the file AutomateAuthenticDesktop_VS2008.sln or the file AutomateAuthenticDesktop_VS2010.sln (to open in Visual Studio 2012/2013/2015/2017/2019/2022). Alternatively the file can be opened from within Visual Studio (with File | Open | Project/Solution). To compile and run the example, select Debug | Start Debugging or Debug | Start Without Debugging.
Code listing of the example
Given below is the C# code listing of the basic functionality of the form (Form1.cs) created in the AutomateAuthenticDesktop example. Note that the code listed below might differ slightly from the code in the API Examples form.The listing below is commented for ease of understanding. Parts of the code are also presented separately in the sub-sections of this section, according to the Application API functionality they access.
The code essentially consists of a series of handlers for the buttons in the user interface shown in the screenshot above.
namespace WindowsFormsApplication2
{
public partial class Form1 : Form
{
public Form1()
{
InitializeComponent();
}
// An instance of AuthenticDesktop is accessed via its automation interface.
XMLSpyLib.Application AuthenticDesktop;
// Location of examples installed with AuthenticDesktop
String strExamplesFolder;
private void Form1_Load(object sender, EventArgs e)
{
// Locate examples installed with AuthenticDesktop.
// REMARK: You might need to adapt this if you have a different major version of the product.
strExamplesFolder = Environment.GetEnvironmentVariable("USERPROFILE") + "\\My Documents\\Altova\\Authentic2012\\AuthenticExamples\\";
}
// Handler for the "Start AuthenticDesktop" button
private void StartAuthenticDesktop_Click(object sender, EventArgs e)
{
if (AuthenticDesktop == null)
{
Cursor.Current = Cursors.WaitCursor;
// If there is no AuthenticDesktop instance, create one and make it visible.
AuthenticDesktop = new XMLSpyLib.Application();
AuthenticDesktop.Visible = true;
Cursor.Current = Cursors.Default;
}
else
{
// If an AuthenticDesktop instance is already running, make sure it's visible.
if (!AuthenticDesktop.Visible)
AuthenticDesktop.Visible = true;
}
}
// Handler for the "Open OrgChart.pxf" button
private void openOrgChart_Click(object sender, EventArgs e)
{
// Make sure there's a running Authentic Desktop instance, and that it's visible
StartAuthenticDesktop_Click(null, null);
// Open a sample file installed with the product.
AuthenticDesktop.Documents.OpenFile(strExamplesFolder + "OrgChart.pxf", false);
}
// Handler for the "Open ExpReport.xml" button
private void openExpReport_Click(object sender, EventArgs e)
{
// Make sure there's a running Authentic Desktop instance, and that it's visible
StartAuthenticDesktop_Click(null, null);
// Open a sample file installed with the product.
AuthenticDesktop.Documents.OpenFile(strExamplesFolder + "ExpReport.xml", false);
}
// Handler for the "Toggle View Mode" button
private void toggleView_Click(object sender, EventArgs e)
{
// Make sure there's a running Authentic Desktop instance, and that it's visible
StartAuthenticDesktop_Click(null, null);
// Iterate through all open documents and toggle the current view between Text View and Authentic View.
foreach (XMLSpyLib.Document doc in AuthenticDesktop.Documents)
if (doc.CurrentViewMode == XMLSpyLib.SPYViewModes.spyViewAuthentic)
doc.SwitchViewMode(XMLSpyLib.SPYViewModes.spyViewBrowser);
else
doc.SwitchViewMode(XMLSpyLib.SPYViewModes.spyViewAuthentic);
}
// Handler for the "Shut down AuthenticDesktop" button
// Shut down application instance by explicitely releasing the COM object.
private void shutdownAuthenticDesktop_Click(object sender, EventArgs e)
{
if (AuthenticDesktop != null)
{
// Allow shut down of AuthenticDesktop by releasing the UI
AuthenticDesktop.Visible = false;
// Explicitly release the COM object
try
{
while (System.Runtime.InteropServices.Marshal.ReleaseComObject(AuthenticDesktop) > 0) ;
}
finally
{
// Avoid subsequent access to this object.
AuthenticDesktop = null;
}
}
}
// Handler for the "Validate" button
private void validate_Click(object sender, EventArgs e)
{
// COM errors get returned to C# as exceptions. Use a try/catch block to handle them.
try
{
// Method 'IsValid' is one of the few functions that use output parameters.
// Use 'object' type for these parameters.
object strErrorText = "";
object nErrorNumber = 0;
object errorData = null;
if (!AuthenticDesktop.ActiveDocument.IsValid(ref strErrorText, ref nErrorNumber, ref errorData))
{
// The COM call succeeds but the document is not valid.
// A detailed description of the problem is returned in strErrorText, nErrorNumber and errorData.
listBoxMessages.Items.Add("Document " + AuthenticDesktop.ActiveDocument.Name + " is not valid.");
listBoxMessages.Items.Add("\tErrorText : " + strErrorText);
listBoxMessages.Items.Add("\tErrorNumber: " + nErrorNumber);
listBoxMessages.Items.Add("\tElement : " + (errorData != null ? ((XMLSpyLib.XMLData)errorData).TextValue : "null"));
}
else
{
// The COM call succeeds and the document is valid.
listBoxMessages.Items.Add("Document " + AuthenticDesktop.ActiveDocument.Name + " is valid.");
}
}
catch (Exception ex)
{
// The COM call was not successful.
// Probably no application instance has been started or no document is open.
listBoxMessages.Items.Add("Error validating active document: " + ex.Message);
}
}
delegate void addListBoxItem_delegate(string sText);
// Called from the UI thread
private void addListBoxItem(string sText)
{
listBoxMessages.Items.Add(sText);
}
// Wrapper method to call UI control methods from a worker thread
void syncWithUIthread(Control ctrl, addListBoxItem_delegate methodToInvoke, String sText)
{
// Control.Invoke: Executes on the UI thread, but calling thread waits for completion before continuing.
// Control.BeginInvoke: Executes on the UI thread, and calling thread doesn't wait for completion.
if (ctrl.InvokeRequired)
ctrl.BeginInvoke(methodToInvoke, new Object[] { sText });
}
// Event handler for OnDocumentOpened event
private void handleOnDocumentOpened(XMLSpyLib.Document i_ipDocument)
{
String sText = "";
if (i_ipDocument.Name.Length > 0)
sText = "Document " + i_ipDocument.Name + " was opened!";
else
sText = "An empty document was created.";
// Synchronize the calling thread with the UI thread because
// COM events are triggered from a working thread
addListBoxItem_delegate methodToInvoke = new addListBoxItem_delegate(addListBoxItem);
// Call syncWithUIthread with the following arguments:
// 1 - listBoxMessages - list box control to display messages from COM events
// 2 - methodToInvoke - a C# delegate which points to the method which will be called from the UI thread
// 3 - sText - the text to be displayed in the list box
syncWithUIthread(listBoxMessages, methodToInvoke, sText);
}
private void checkBoxEventOnOff_CheckedChanged(object sender, EventArgs e)
{
if (AuthenticDesktop != null)
{
if (checkBoxEventOnOff.Checked)
AuthenticDesktop.OnDocumentOpened += new XMLSpyLib._IApplicationEvents_OnDocumentOpenedEventHandler(handleOnDocumentOpened);
else
AuthenticDesktop.OnDocumentOpened -= new XMLSpyLib._IApplicationEvents_OnDocumentOpenedEventHandler(handleOnDocumentOpened);
}
}
}
}