ActiveX Overview

ActiveX support allows you to use any registered ActiveX control in your SWF Studio applications. You can create as many controls as you want and manage them individually. Not only can you get and set properties and call methods of these controls, but you can receive notifications for any event that the control generates and Guides that your ActiveX controls can "snap to" make ActiveX control layout and resizing a breeze.

Every ActiveX control has a globally unique identifier or GUID. GUIDs are 128-bit numbers, but are normally expressed as hexadecimal string values. For example, the GUID for the Adobe Acrobat Reader (version 7.0) is "{CA8A9780-280D-11CF-A24D-444553540000}". In this form we refer to these numbers as class identifiers or CLSIDs. Once an ActiveX control has been properly installed all you need to create an instance of the desired control is to know its CLSID.

Since CLSIDs can be difficult to remember (and for a few other technical reasons) most ActiveX controls also expose a more human readable programmatic identifier or ProgID. The ProgID for the Acrobat Reader is "AcroPDF.PDF", which is much easier to remember than "{CA8A9780-280D-11CF-A24D-444553540000}". When you ask Windows to create an instance of the AcroPDF.PDF control, it looks up the CLSID and does all the dirty work for you.

You can pass any ProgID to ActiveX.isRegistered to determine whether that ProgID is registered (and thus available for use) or not before you attempt to create an instance of an Active control using ActiveX.createObject. If the end-user does not have the ActiveX control your application requires then your application will not function as expected.

Here's a quick example showing how to create an instance of the Acrobat Reader control, load a PDF file into the control and display the PDF document. First, we do a quick check to make sure the control is registered and display the appropriate error message if anything goes wrong. After that we simply use the methods exposed by the Acrobat Reader control to load and show a PDF file.

ssCore.init();
ssDefaults.synchronousCommands = true;
ssCore.Win.show({});

// is the Acrobat Reader control registered (i.e. available on this system)?

var r = ssCore.ActiveX.isRegistered({progId:"AcroPDF.PDF"});

if (r.success)
{
    if (r.result != "TRUE")
    {
        ssCore.App.showMsgBox({prompt:"A required ActiveX control is not registered", icon:"critical"});
        ssCore.App.quit({});
    }
}
else
{
    ssCore.App.showMsgBox({prompt:"Unexpected error", icon:"critical"});
}

// create an instance of AcroPDF.PDF (the Acrobat Reader ActiveX control)
ssCore.ActiveX.createObject({object:"Reader1", progId:"AcroPDF.PDF"});

// load a PDF file into the Acrobat Reader
ssCore.Reader1.LoadFile({fileName:"c:\\test.pdf"});

// set the position of the control
ssCore.Reader1.setPosition({x:0, y:0});

// set the size of the control to match the Flash stage size
ssCore.Reader1.setSize({width:Stage.width, height:Stage.height});

// make the Acrobat Reader control visible
ssCore.Reader1.setVisible({visible:"true"});

The question on your mind now is probably "How do I know what properties, methods and events an ActiveX control exposes?". It's a good question and we have some good answers for you. The first place you should look is to the author of the control you're trying to use, they will have the best documentation on how to use their product. In the case of the Acrobat Reader, for example, the Adobe web site is the place to look.

The Acrobat SDK Documentation page on the Adobe site has a link to a PDF document called Acrobat Inter-Application Communication Reference (2.10 MB). Under the heading AxAcroPDFLib.AxAcroPDF in that document you will find a description of all of the properties and methods exposed by the Acrobat Reader ActiveX control, including allowable values for the exposed methods. You will need a copy of that document to use the Acrobat Reader ActiveX object effectively.

The next problem you may encounter is how to find ActiveX controls installed on your machine that you might want to use. We've created a tool called ActiveX Info (available in the Help button dropdown in SWF Studio) to give you a quick way find all the controls registered on your machine and to get some information about those controls, such as which properties, methods and events they expose. Below is the output from ActiveX Info for the Acrobat Reader.

The section at the top lists some important information about the ActiveX control.

The ProgId and CLSID (described above) are used to uniquely identify the control. The Class File tells you which DLL or OCX actually implements the functionality you'll be using and the Version is the full version information for the control, in this case version 7.0.5, the same thing you see in the About box for the Acrobat Reader.

Each of the sections that follow this header describe an interface of the ActiveX control and the properties, methods, events and constants that the interface exposes.

Readable Properties are identified by the symbol. You can retrieve the value of these properties using ActiveX.getProperty.

Writeable Properties are identified by the symbol. You can modify these properties using ActiveX.setProperty.

Methods are identified by the symbol. Some methods, like Print have no arguments while others have one or more arguments like LoadFile(fileName). All arguments are required unless they appear inside square brackets, those arguments are optional. See ActiveX.callMethod for more information on how to call methods of ActiveX controls.

Constants are identified by the symbol. You can't use the symbolic constants directly in your code, but you can find their values and use those instead.

Events are identified by the symbol. These represent all of the events that the control can generate. You can use any event listed in the ActiveX Info output as the event parameter to ActiveX.setNotify and ActiveX.clearNotify.

Following the ActiveX documentation, the object parameter you use in ActiveX.createObject is used to tell SWF Studio which object you are dealing with, as in the example below.

ssCore.ActiveX.createObject({object:"Reader1", progId:"AcroPDF.PDF"});
ssCore.ActiveX.callMethod({object:"Reader1", method:"LoadFile", fileName:"c:\\test.pdf"});
ssCore.ActiveX.setSize({object:"Reader1", width:Stage.width, height:Stage.height});
ssCore.ActiveX.setVisible({object:"Reader1", "visible:"true"});

However, once you have called createObject, the object name you passed becomes part of the ssCore namespace allowing you to use that as kind of shortcut reference to the object. This allows you to omit the object parameter from your calls like this:

ssCore.ActiveX.createObject({object:"Reader1", progId:"AcroPDF.PDF"});
ssCore.Reader1.callMethod({method:"LoadFile", fileName:"c:\\test.pdf"});
ssCore.Reader1.setSize({width:Stage.width, height:Stage.height});
ssCore.Reader1.setVisible({visible:"true"});

There is one further simplification you can make which allows you to remove the method parameter and the the callMethod method itself. Continuing with the example above the LoadFile method now looks like a native SWF Studio method on our Reader1 object.

ssCore.ActiveX.createObject({object:"Reader1", progId:"AcroPDF.PDF"});
ssCore.Reader1.LoadFile({fileName:"c:\\test.pdf"});
ssCore.Reader1.setSize({width:Stage.width, height:Stage.height});
ssCore.Reader1.setVisible({visible:"true"});