About com.ms.activeX

You can use the classes and interfaces in the com.ms.activeX package to host Microsoft® ActiveX® controls and ActiveX Automation objects, to use ActiveX streams, and to access helper functions.

Overview of Classes

The ActiveXControl class provides methods that enable you to host an ActiveX control. You can create the control using the ActiveXControl constructor and then call other methods in the class to set its properties, retrieve its properties, and invoke its methods. The Hosting an ActiveX Control section of this document further describes how you can host an ActiveX control in your Java application.

The ActiveXControlListener interface, when used with the ActiveXControl.addActiveXControlListener method, allows you to register a listener for an ActiveX control so that the listener will be notified when the ActiveX control has been created. Any listeners must implement the ActiveXControlListener interface, which contains a single method called controlCreated. When an ActiveX control is created, the Microsoft Win32 VM for Java calls the controlCreated method on the listener object. To view a code sample that adds a listener, see the Mixing Java and Native Code article.

The ActiveXInputStream and ActiveXOutputStream classes wrap IStream objects that are obtained from COM objects. Instances of these classes are compatible with other Java classes that take java.io.InputStream and java.io.OutputStream objects as parameters. These classes are also used by the Microsoft VM to wrap IStream objects that it obtains from ActiveX containers like Microsoft® Visual Basic®. Once the object is wrapped, the VM can use the java.io serialization classes that work only with InputStream and OutputStream objects.

The ActiveXToolkit class contains methods that allow you to create a FontX object, given an IUnknown interface. You can also use the methods in this class to retrieve the IUnknown interface of a Font object and to create a Java color from an OLE_COLOR.

Hosting an ActiveX Control

There are two ways two host an ActiveX control in a Java application. One way is to use the jactivex tool to generate a Java wrapper for the ActiveX control. The other is to use the ActiveXControl classes directly.

Generating a Java Wrapper for an ActiveX Control

You can run the jactivex tool on the ActiveX control to generate Java source code for the control. When you compile the .java files emitted by jactivex, you get .class files that you can import. You can then use the control just as you would any other Java object. For example, suppose you have obtained a control called MyControl that has a method called MyMethod. After you run the jactivex tool on this control and compile the resulting files, you could use the object in the following way.

   import MyControl.*;
   import java.awt.*;
   ...
   // create the control
   MyControl c = new MyControl();
 
   //add the control to the layout         
   add("Center", c);             
   ...

   // call MyMethod 
   c.MyMethod(...);	                            

For more information about using jactivex to host an ActiveX control, see the Mixing Java and Native Code article and the jactivex section of the Tools Quick Reference.

Using the ActiveXControl Class to Host an ActiveX Control

The other way to host an ActiveX control involves using the methods in the ActiveX control class. To create the control, you would pass the CLSID or ProgID to the ActiveXControl constructor. You can then invoke methods, retrieve properties, or set properties of the control. Again, suppose you have a control called MyControl that has a method called MyMethod. You can create the control and add it to the layout, as shown in the following example.

   import com.ms.activeX.ActiveXControl;
   import java.awt.*;
	
   ...
   // create the control
   ActiveXControl c = new ActiveXControl("MyControl");

   // add the control to the layout     
   add("Center", c); 
	
   // do something interesting 
   ...             

Invoking Methods of an ActiveX Control

Suppose MyControl has a method called MyMethod that you want to call. Let's assume that MyMethod takes three parameters: a String, an integer, and a boolean. The ActiveXControl.invoke method allows you to call MyMethod. The invoke method takes as a parameter an array of Variants that contains the arguments to the method you want to call. The arguments are passed to the control through IDispatch. This example shows how you could create and initialize an array of Variants called args and call MyMethod by passing args to the invoke method.

   Variant args[] = new Variant[3};
   args[0] = new Variant("String arg");
   args[1] = new Variant(100);
   args[2] = new Variant(true);
   c.invoke("MyMethod", args);

Retrieving Properties of an ActiveX Control

You can also use the ActiveXControl class to retrieve properties from an object. To do this, call the ActiveXControl.getProperty method. If MyControl had a property called MyProperty, you could retrieve its value in the following way.

   // Create the control as before
   ActiveXControl c = new ActiveXControl("MyControl");
   ...

   // Retrieve a property
   Variant propvalue = c.getProperty("MyProperty");

Initializing an ActiveX Control Using Property Bags

You can call the setProperty method of the ActiveXControl class to set a property of an ActiveX control. If the setProperty method is called before the addNotify method is called, the setProperty method places properties in the property bag of the control. This gives the control a mechanism for setting its default state. After the control has been called on addNotify, the setProperty method is invoked using IDispatch. The following example shows how to initialize two properties of MyControl using the setProperty method to place the properties in the property bag.

   ActiveXControl c = new ActiveXControl("MyControl");
   c.setProperty("MyProperty", true);
   c.setProperty("MyOtherProperty", 1);	
   add("Center", c);

Sinking Events from ActiveX Objects

Using the jactivex tool, you can gain access to the event interface of the ActiveX object. For example, suppose you have a control called MyControl that has an event interface called MyEventInterface. Let's say this interface has a method called theEvent, which needs to be implemented by any class that wants to sink theEvent from MyControl. A Java object can sink events from the ActiveX object by using the com.ms.com.ConnectionPointCookie class, as follows.

import MyControl.*;
import com.ms.activeX.ActiveXControl;
import com.ms.com.ConnectionPointCookie;

public class MyEventSinker implements MyEventInterface {

   ...
	
   MyControl c = new MyControl;      
   Eventcookie = new ConnectionPointCookie(c, this,
                 Class.forName("MyControl.MyEventInterface");

   // hold onto Eventcookie as long as you want the connection to exist
   ...
	
   public void theEvent(String x){
		
      // do something interesting
      ...
   }
}

Classes

Class ActiveXComponent

This class provides basic Microsoft® ActiveX® control functionality.

Class ActiveXControl

This class exposes methods, properties, and events used to host Microsoft® ActiveX® controls.

Class ActiveXInputStream

This class provides access to methods that manipulate input streams.

Class ActiveXOutputStream

This class provides access to methods that manipulate output streams.

Class ActiveXToolkit

This class provides a toolkit of Component Object Model (COM) functions.

Interfaces

Interface ActiveXControlListener

This interface provides a method that notifies an object after a Microsoft® ActiveX® control has been created.

Interface ActiveXControlServices

This interface represents a standard system service that is available for Java components hosted inside ActiveX containers.

Hierarchy

Object
  |
  +--ActiveXToolkit

Canvas
  |
  +--ActiveXComponent
     |
     +--ActiveXControl (Serializable, HeavyComponent)

InputStream
  |
  +--ActiveXInputStream

OutputStream
  |
  +--ActiveXOutputStream

ActiveXControlListener
ActiveXControlServices