au.com.swz.swttocom.swt.types
Class AutomationComposite

java.lang.Object
  extended by org.eclipse.swt.widgets.Widget
      extended by org.eclipse.swt.widgets.Control
          extended by org.eclipse.swt.widgets.Scrollable
              extended by org.eclipse.swt.widgets.Composite
                  extended by au.com.swz.swttocom.swt.types.AutomationComposite
All Implemented Interfaces:
IAutomationObject, org.eclipse.swt.graphics.Drawable

public class AutomationComposite
extends org.eclipse.swt.widgets.Composite
implements IAutomationObject

An Automation Composite provides support for embedding a COM control or OLE Document in to a SWT application as if it were just another SWT widget. It provides methods for interacting with the Control/Document however it is usually extended by either a Delegate or Facade that will provide access to the control through more meaningful methods.

Author:
Mark Richter

Field Summary
 
Fields inherited from class org.eclipse.swt.widgets.Control
handle
 
Constructor Summary
AutomationComposite(org.eclipse.swt.widgets.Composite parent, int style, java.lang.String progId)
          Create an AutomationComposite widget with the specified OLE Class embedded.
AutomationComposite(org.eclipse.swt.widgets.Composite parent, int style, java.lang.String progId, java.io.File file)
          Create an AutomationComposite widget and initialise it with the contents of the specified file using the specified application.
 
Method Summary
 void deactivateInPlaceClient()
          Deactivates an active in-place object and discards the object's undo state.
 int[] getIDsOfNames(java.lang.String[] names)
          Returns the integer values (IDs) that are associated with the specified names by the IDispatch implementor.
 java.lang.String getLastErrorSWT()
          Returns a description of the last error encountered.
 org.eclipse.swt.ole.win32.OleAutomation getOleAutomation()
          Returns the OleAutomation object currently being used to call the COM interface.
 org.eclipse.swt.ole.win32.OleClientSite getOleClientSite()
          Returns the OleClientSite currently being used to host the document/control.
 org.eclipse.swt.ole.win32.OleFrame getOleFrame()
          Returns the OleFrame currently being used to manage the frame menus.
 org.eclipse.swt.ole.win32.Variant getProperty(int dispIdMember)
          Returns the value of the property specified by the dispIdMember.
 org.eclipse.swt.ole.win32.Variant getProperty(int dispIdMember, org.eclipse.swt.ole.win32.Variant[] rgvarg)
          Returns the value of the property specified by the dispIdMember.
 org.eclipse.swt.ole.win32.Variant getProperty(int dispIdMember, org.eclipse.swt.ole.win32.Variant[] rgvarg, int[] rgdispidNamedArgs)
          Returns the value of the property specified by the dispIdMember.
 org.eclipse.swt.ole.win32.Variant invoke(int dispIdMember)
          Invokes a method on the OLE Object; the method has no parameters.
 org.eclipse.swt.ole.win32.Variant invoke(int dispIdMember, org.eclipse.swt.ole.win32.Variant[] rgvarg)
          Invokes a method on the OLE Object; the method has no optional parameters.
 org.eclipse.swt.ole.win32.Variant invoke(int dispIdMember, org.eclipse.swt.ole.win32.Variant[] rgvarg, int[] rgdispidNamedArgs)
          Invokes a method on the OLE Object; the method has optional parameters.
 void invokeNoReply(int dispIdMember)
          Invokes a method on the OLE Object; the method has no parameters.
 void invokeNoReply(int dispIdMember, org.eclipse.swt.ole.win32.Variant[] rgvarg)
          Invokes a method on the OLE Object; the method has no optional parameters.
 void invokeNoReply(int dispIdMember, org.eclipse.swt.ole.win32.Variant[] rgvarg, int[] rgdispidNamedArgs)
          Invokes a method on the OLE Object; the method has optional parameters.
 boolean isDirty()
          Indicates whether the contents of the embedded document has changed since it was last saved.
 void oleDiscardUndoState()
          Used to tell objects to discard any undo state that they may be maintaining without deactivating the object.
 void oleHide()
          Causes an object to remove its user interface from the view.
 void oleInplaceActivate()
          Activates an object in place without displaying tools, such as menus and toolbars, that end users need to change the behavior or appearance of the object.
 void oleOpen()
          Instructs an object, including one that otherwise supports in-place activation, to open itself for editing in a window separate from that of its container.
 void olePrimary()
          Specifies the action that occurs when an end user double-clicks the object in its container.
 void oleShow()
          Instructs an object to show itself for editing or viewing.
 void oleUIActivate()
          Activates an object in place, along with its full set of user-interface tools, including menus, toolbars, and its name in the title bar of the container window.
 boolean save(boolean includeOleInfo)
           Saves the embedded document to the same file from which it was loaded.
 boolean save(java.io.File file, boolean includeOleInfo)
          Saves the embedded document to the specified file.
 boolean setProperty(int dispIdMember, org.eclipse.swt.ole.win32.Variant rgvarg)
          Sets the property specified by the dispIdMember to a new value.
 boolean setProperty(int dispIdMember, org.eclipse.swt.ole.win32.Variant[] rgvarg)
          Sets the property specified by the dispIdMember to a new value.
 
Methods inherited from class org.eclipse.swt.widgets.Composite
changed, checkSubclass, computeSize, getBackgroundMode, getChildren, getLayout, getLayoutDeferred, getTabList, isLayoutDeferred, layout, layout, layout, layout, setBackgroundMode, setFocus, setLayout, setLayoutDeferred, setTabList
 
Methods inherited from class org.eclipse.swt.widgets.Scrollable
computeTrim, getClientArea, getHorizontalBar, getVerticalBar
 
Methods inherited from class org.eclipse.swt.widgets.Control
addControlListener, addFocusListener, addHelpListener, addKeyListener, addMouseListener, addMouseMoveListener, addMouseTrackListener, addPaintListener, addTraverseListener, computeSize, forceFocus, getAccessible, getBackground, getBackgroundImage, getBorderWidth, getBounds, getEnabled, getFont, getForeground, getLayoutData, getLocation, getMenu, getMonitor, getParent, getShell, getSize, getToolTipText, getVisible, internal_dispose_GC, internal_new_GC, isEnabled, isFocusControl, isReparentable, isVisible, moveAbove, moveBelow, pack, pack, redraw, redraw, removeControlListener, removeFocusListener, removeHelpListener, removeKeyListener, removeMouseListener, removeMouseMoveListener, removeMouseTrackListener, removePaintListener, removeTraverseListener, setBackground, setBackgroundImage, setBounds, setBounds, setCapture, setCursor, setEnabled, setFont, setForeground, setLayoutData, setLocation, setLocation, setMenu, setParent, setRedraw, setSize, setSize, setToolTipText, setVisible, toControl, toControl, toDisplay, toDisplay, traverse, update
 
Methods inherited from class org.eclipse.swt.widgets.Widget
addDisposeListener, addListener, checkWidget, dispose, getData, getData, getDisplay, getStyle, isDisposed, isListening, notifyListeners, removeDisposeListener, removeListener, removeListener, setData, setData, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface au.com.swz.swttocom.swt.types.IAutomationObject
dispose, isDisposed
 

Constructor Detail

AutomationComposite

public AutomationComposite(org.eclipse.swt.widgets.Composite parent,
                           int style,
                           java.lang.String progId)
Create an AutomationComposite widget with the specified OLE Class embedded. The progId specified can be an activeX control, OLE document or any other visible Ole class. Use style bits to select a particular look or set of properties to be applied to the underlying Composite (eg: SWT.BORDER). The specified ProgID key can be either versioned or version independant but must be specified in the registry. For example; "Word.Document.8" (Versioned progid for MSWord 2003) or "Word.Document" (Unversioned progid for Word).

Parameters:
parent - the parent composite widget that will host the OLE Control/Docmunet.
style - the bitwise OR'ing of widget styles to be applied to the underlying Composite (eg: SWT.BORDER).
progId - the unique program identifier of an OLE Document/Control.
Throws:
java.lang.IllegalArgumentException -
  • ERROR_NULL_ARGUMENT when the parent is null
  • ERROR_INVALID_ARGUMENT when the parent is not an OleFrame
org.eclipse.swt.SWTException -
  • ERROR_THREAD_INVALID_ACCESS when called from the wrong thread
  • ERROR_INVALID_CLASSID when the progId does not map to a registered CLSID
  • ERROR_CANNOT_CREATE_OBJECT when failed to create OLE Object

AutomationComposite

public AutomationComposite(org.eclipse.swt.widgets.Composite parent,
                           int style,
                           java.lang.String progId,
                           java.io.File file)
Create an AutomationComposite widget and initialise it with the contents of the specified file using the specified application. The file should be associated with the specified host class id. If not an attempt is made to open the file using the specified application by first coping the file to a new storage file.

Parameters:
parent - the parent composite widget that will host the OLE Control/Docmunet.
style - the bitwise OR'ing of widget styles to be applied to the underlying Composite (eg: SWT.BORDER).
progId - the unique program identifier of an OLE Document/Control.
file - the file that is to be opened in this Composite.
Throws:
java.lang.IllegalArgumentException -
  • ERROR_NULL_ARGUMENT when the parent is null
org.eclipse.swt.SWTException -
  • ERROR_THREAD_INVALID_ACCESS when called from the wrong thread
  • ERROR_CANNOT_CREATE_OBJECT when failed to create OLE Object
  • ERROR_CANNOT_OPEN_FILE if the file is invalid or it cannot be opened.
  • ERROR_INTERFACE_NOT_FOUND when unable to create callbacks for OLE Interfaces
  • ERROR_INVALID_CLASSID when the host class id does not match the file class id.
Method Detail

oleInplaceActivate

public void oleInplaceActivate()
Activates an object in place without displaying tools, such as menus and toolbars, that end users need to change the behavior or appearance of the object. Single-clicking such an object causes it to negotiate the display of its user-interface tools with its container. If the container refuses, the object remains active but without its tools displayed.


oleShow

public void oleShow()
Instructs an object to show itself for editing or viewing. Called to display newly inserted objects for initial editing and to show link sources. Usually an alias for some other object-defined verb.


olePrimary

public void olePrimary()
Specifies the action that occurs when an end user double-clicks the object in its container. The object, not the container, determines this action. If the object supports in-place activation, the primary verb usually activates the object in place.


oleOpen

public void oleOpen()
Instructs an object, including one that otherwise supports in-place activation, to open itself for editing in a window separate from that of its container. If the object does not support in-place activation, this verb has the same semantics as oleShow().


oleHide

public void oleHide()
Causes an object to remove its user interface from the view. Applies only to objects that are activated in-place.


oleUIActivate

public void oleUIActivate()
Activates an object in place, along with its full set of user-interface tools, including menus, toolbars, and its name in the title bar of the container window.


oleDiscardUndoState

public void oleDiscardUndoState()
Used to tell objects to discard any undo state that they may be maintaining without deactivating the object.


getOleClientSite

public org.eclipse.swt.ole.win32.OleClientSite getOleClientSite()
Returns the OleClientSite currently being used to host the document/control.

Returns:
the OleClientSite currently being used to host the document/control.

isDirty

public boolean isDirty()
Indicates whether the contents of the embedded document has changed since it was last saved. The dirty flag is cleared by calling the save method.

Returns:
the contents of the dirty flag for the underlying COM storage.

save

public boolean save(java.io.File file,
                    boolean includeOleInfo)
Saves the embedded document to the specified file. The includeOleInfo/code> specifies whether file should include OLE specific information. For example, a word file should set this parameter to true because there is formatting information that should be stored in the OLE specific Storage format. On the other hand a bitmap file edited with MSPaint would set this parameter to false because bitmap is a standard format that does not include any OLE specific data.

Parameters:
file - the file to which the document should be saved.
includeOleInfo - true to include OLE specific information in the file.
Returns:
true if the save was successful

save

public boolean save(boolean includeOleInfo)
             throws java.lang.IllegalStateException

Saves the embedded document to the same file from which it was loaded. If no file was specified at the creation of this composite this methods throws a IllegalStateException.

The includeOleInfo/code> specifies whether file should include OLE specific information. For example, a word file should set this parameter to true because there is formatting information that should be stored in the OLE specific Storage format. On the other hand a bitmap file edited with MSPaint would set this parameter to false because bitmap is a standard format that does not include any OLE specific data.

Parameters:
includeOleInfo - true to include OLE specific information in the file.
Returns:
true if the save was successful
Throws:
java.lang.IllegalStateException - If no file was specified at the creation of this composite.

deactivateInPlaceClient

public void deactivateInPlaceClient()
Deactivates an active in-place object and discards the object's undo state. This method has no effect if the embedded document is not active.


getOleFrame

public org.eclipse.swt.ole.win32.OleFrame getOleFrame()
Returns the OleFrame currently being used to manage the frame menus.

Returns:
the OleFrame currently being used to manage the frame menus.

getOleAutomation

public org.eclipse.swt.ole.win32.OleAutomation getOleAutomation()
Returns the OleAutomation object currently being used to call the COM interface. This method returns a copy of the OleAutomation object and increments the reference count for the underlying COM interface(s).

Returns:
the OleAutomation object currently being used to call the COM interface

getIDsOfNames

public int[] getIDsOfNames(java.lang.String[] names)
Returns the integer values (IDs) that are associated with the specified names by the IDispatch implementor. If you are trying to get the names of the parameters in a method, the first String in the names array must be the name of the method followed by the names of the parameters.

Specified by:
getIDsOfNames in interface IAutomationObject
Parameters:
names - an array of names for which you require the identifiers
Returns:
integer values that are associated with the specified names in the same order as the names where provided; or null if the names are unknown

getLastErrorSWT

public java.lang.String getLastErrorSWT()
Returns a description of the last error encountered.

Specified by:
getLastErrorSWT in interface IAutomationObject
Returns:
a description of the last error encountered

getProperty

public org.eclipse.swt.ole.win32.Variant getProperty(int dispIdMember)
Returns the value of the property specified by the dispIdMember.

Specified by:
getProperty in interface IAutomationObject
Parameters:
dispIdMember - the ID of the property as specified by the IDL of the ActiveX Control; the value for the ID can be obtained using OleAutomation.getIDsOfNames
Returns:
the value of the property specified by the dispIdMember or null

getProperty

public org.eclipse.swt.ole.win32.Variant getProperty(int dispIdMember,
                                                     org.eclipse.swt.ole.win32.Variant[] rgvarg)
Returns the value of the property specified by the dispIdMember.

Specified by:
getProperty in interface IAutomationObject
Parameters:
dispIdMember - the ID of the property as specified by the IDL of the ActiveX Control; the value for the ID can be obtained using OleAutomation.getIDsOfNames
rgvarg - an array of arguments for the method. All arguments are considered to be read only unless the Variant is a By Reference Variant type.
Returns:
the value of the property specified by the dispIdMember or null

getProperty

public org.eclipse.swt.ole.win32.Variant getProperty(int dispIdMember,
                                                     org.eclipse.swt.ole.win32.Variant[] rgvarg,
                                                     int[] rgdispidNamedArgs)
Returns the value of the property specified by the dispIdMember.

Specified by:
getProperty in interface IAutomationObject
Parameters:
dispIdMember - the ID of the property as specified by the IDL of the ActiveX Control; the value for the ID can be obtained using OleAutomation.getIDsOfNames
rgvarg - an array of arguments for the method. All arguments are considered to be read only unless the Variant is a By Reference Variant type.
rgdispidNamedArgs - an array of identifiers for the arguments specified in rgvarg; the parameter IDs must be in the same order as their corresponding values; all arguments must have an identifier - identifiers can be obtained using OleAutomation.getIDsOfNames
Returns:
the value of the property specified by the dispIdMember or null

invoke

public org.eclipse.swt.ole.win32.Variant invoke(int dispIdMember)
Invokes a method on the OLE Object; the method has no parameters.

Specified by:
invoke in interface IAutomationObject
Parameters:
dispIdMember - the ID of the method as specified by the IDL of the ActiveX Control; the value for the ID can be obtained using OleAutomation.getIDsOfNames
Returns:
the result of the method or null if the method failed to give result information

invoke

public org.eclipse.swt.ole.win32.Variant invoke(int dispIdMember,
                                                org.eclipse.swt.ole.win32.Variant[] rgvarg)
Invokes a method on the OLE Object; the method has no optional parameters.

Specified by:
invoke in interface IAutomationObject
Parameters:
dispIdMember - the ID of the method as specified by the IDL of the ActiveX Control; the value for the ID can be obtained using OleAutomation.getIDsOfNames
rgvarg - an array of arguments for the method. All arguments are considered to be read only unless the Variant is a By Reference Variant type.
Returns:
the result of the method or null if the method failed to give result information

invoke

public org.eclipse.swt.ole.win32.Variant invoke(int dispIdMember,
                                                org.eclipse.swt.ole.win32.Variant[] rgvarg,
                                                int[] rgdispidNamedArgs)
Invokes a method on the OLE Object; the method has optional parameters. It is not necessary to specify all the optional parameters, only include the parameters for which you are providing values.

Specified by:
invoke in interface IAutomationObject
Parameters:
dispIdMember - the ID of the method as specified by the IDL of the ActiveX Control; the value for the ID can be obtained using OleAutomation.getIDsOfNames
rgvarg - an array of arguments for the method. All arguments are considered to be read only unless the Variant is a By Reference Variant type.
rgdispidNamedArgs - an array of identifiers for the arguments specified in rgvarg; the parameter IDs must be in the same order as their corresponding values; all arguments must have an identifier - identifiers can be obtained using OleAutomation.getIDsOfNames
Returns:
the result of the method or null if the method failed to give result information

invokeNoReply

public void invokeNoReply(int dispIdMember)
Invokes a method on the OLE Object; the method has no parameters. In the early days of OLE, the IDispatch interface was not well defined and some applications (mainly Word) did not support a return value. For these applications, call this method instead of calling public void invoke(int dispIdMember).

Specified by:
invokeNoReply in interface IAutomationObject
Parameters:
dispIdMember - the ID of the method as specified by the IDL of the ActiveX Control; the value for the ID can be obtained using OleAutomation.getIDsOfNames
Throws:
org.eclipse.swt.SWTException -
  • ERROR_ACTION_NOT_PERFORMED when method invocation fails

invokeNoReply

public void invokeNoReply(int dispIdMember,
                          org.eclipse.swt.ole.win32.Variant[] rgvarg)
Invokes a method on the OLE Object; the method has no optional parameters. In the early days of OLE, the IDispatch interface was not well defined and some applications (mainly Word) did not support a return value. For these applications, call this method instead of calling public void invoke(int dispIdMember, Variant[] rgvarg).

Specified by:
invokeNoReply in interface IAutomationObject
Parameters:
dispIdMember - the ID of the method as specified by the IDL of the ActiveX Control; the value for the ID can be obtained using OleAutomation.getIDsOfNames
rgvarg - an array of arguments for the method. All arguments are considered to be read only unless the Variant is a By Reference Variant type.
Throws:
org.eclipse.swt.SWTException -
  • ERROR_ACTION_NOT_PERFORMED when method invocation fails

invokeNoReply

public void invokeNoReply(int dispIdMember,
                          org.eclipse.swt.ole.win32.Variant[] rgvarg,
                          int[] rgdispidNamedArgs)
Invokes a method on the OLE Object; the method has optional parameters. It is not necessary to specify all the optional parameters, only include the parameters for which you are providing values. In the early days of OLE, the IDispatch interface was not well defined and some applications (mainly Word) did not support a return value. For these applications, call this method instead of calling public void invoke(int dispIdMember, Variant[] rgvarg, int[] rgdispidNamedArgs).

Specified by:
invokeNoReply in interface IAutomationObject
Parameters:
dispIdMember - the ID of the method as specified by the IDL of the ActiveX Control; the value for the ID can be obtained using OleAutomation.getIDsOfNames
rgvarg - an array of arguments for the method. All arguments are considered to be read only unless the Variant is a By Reference Variant type.
rgdispidNamedArgs - an array of identifiers for the arguments specified in rgvarg; the parameter IDs must be in the same order as their corresponding values; all arguments must have an identifier - identifiers can be obtained using OleAutomation.getIDsOfNames
Throws:
org.eclipse.swt.SWTException -
  • ERROR_ACTION_NOT_PERFORMED when method invocation fails

setProperty

public boolean setProperty(int dispIdMember,
                           org.eclipse.swt.ole.win32.Variant rgvarg)
Sets the property specified by the dispIdMember to a new value.

Specified by:
setProperty in interface IAutomationObject
Parameters:
dispIdMember - the ID of the property as specified by the IDL of the ActiveX Control; the value for the ID can be obtained using OleAutomation.getIDsOfNames
rgvarg - the new value of the property
Returns:
true if the operation was successful

setProperty

public boolean setProperty(int dispIdMember,
                           org.eclipse.swt.ole.win32.Variant[] rgvarg)
Sets the property specified by the dispIdMember to a new value.

Specified by:
setProperty in interface IAutomationObject
Parameters:
dispIdMember - the ID of the property as specified by the IDL of the ActiveX Control; the value for the ID can be obtained using OleAutomation.getIDsOfNames
rgvarg - an array of arguments for the method. All arguments are considered to be read only unless the Variant is a By Reference Variant type.
Returns:
true if the operation was successful