| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
| <meta name="Author" content="Grant Gayed"> |
| <link href="../article.css" type="text/css" rel="stylesheet"> |
| <title>ActiveX Support In SWT</title> |
| </head> |
| |
| <body> |
| <h1>ActiveX Support In SWT</h1> |
| <div class="summary"> |
| <h2>Summary</h2> |
| <p>OLE Documents, such as Word, Excel or PowerPoint, and ActiveX |
| Controls such as Internet Explorer are COM objects that can be embedded |
| into other applications running on a Microsoft® Windows® |
| platform. This article provides an overview of integrating OLE Documents |
| and ActiveX Controls into an application using SWT.</p> |
| <div class="author">By Veronika Irvine, OTI</div> |
| <div class="copyright">Copyright © 2001 Object Technology |
| International, Inc.</div> |
| <div class="date">March 22, 2001</div> |
| </div> |
| |
| |
| <div class="content"> |
| |
| <h2>Embedding an OLE Object in your SWT Application</h2> |
| <p>OLE Objects can be contained in SWT widgets. From there, they can |
| be activated and deactivated for user interaction, and manipulated by |
| the application according to their specification. For example, edited |
| data and state can be retrieved or saved. If the object is no longer |
| required, it can be disposed.</p> |
| |
| <h3>Create the OLE Object</h3> |
| |
| <p>An OLE Document or ActiveX Control is added to an application by |
| inserting it into a Container. The Container is made up of two parts:</p> |
| |
| <ol> |
| <li>The <i> OleFrame</i> object handles sizing, menu management |
| and window placement.</li> |
| <li>The <i> OleClientSite</i> (for OLE Documents) or <i> |
| OleControlSite</i> (for ActiveX Controls) handles interactions with a |
| specific OLE Object.</li> |
| </ol> |
| |
| <p>The first step in embedding an OLE Object is to create the <i>OleFrame</i>:</p> |
| |
| <pre> |
| Display display = new Display(); |
| Shell shell = new Shell(display); |
| OleFrame frame = new OleFrame(shell, SWT.NONE); |
| </pre> |
| |
| <p>When activated, an OLE Document displays its own menu bar over |
| top of the application's menu bar. The application can contribute menus |
| to the OLE Document's menu bar through the <i> OleFrame</i> as follows:</p> |
| |
| <pre> |
| Menu bar = new Menu(shell, SWT.BAR); |
| shell.setMenuBar(bar); |
| |
| MenuItem fileItem1 = new MenuItem(bar, SWT.CASCADE); |
| fileItem1.setText("&File_Item_1"); |
| MenuItem fileItem2 = new MenuItem(bar, SWT.CASCADE); |
| fileItem2.setText("&File_Item_2"); |
| |
| MenuItem containerItem = new MenuItem(bar, SWT.CASCADE); |
| containerItem.setText("&Container_Item"); |
| |
| MenuItem windowItem1 = new MenuItem(bar, SWT.CASCADE); |
| windowItem1.setText("&Window_Item_1"); |
| MenuItem windowItem2 = new MenuItem(bar, SWT.CASCADE); |
| windowItem2.setText("&Window_Item_2"); |
| |
| frame.setFileMenus(new MenuItem[] {fileItem1, fileItem2}); |
| frame.setContainerMenus(new MenuItem[] {containerItem}); |
| frame.setWindowMenus(new MenuItem[] {windowItem1, windowItem2}); |
| </pre> |
| |
| <p>The next step is to create an <i> OleClientSite</i> or an <i>OleControlSite</i>. |
| Some COM objects can function as both an OLE Document and an ActiveX |
| Control. Embedding an OLE Document is equivalent to embedding the entire |
| application. The OLE Document provides its own toolbar and menu bar for |
| accessing its behavior. An ActiveX Control only provides the content |
| part and the parent application must manage the behavior of the content |
| through the API of the ActiveX Control. To determine if a COM object |
| supports the OLE Document behavior, look for the IOleDocument interface. |
| To determine if a COM object supports the ActiveX Control behavior, look |
| for the IOleControl interface. To see which interfaces the OLE Object |
| implements, look at the type library.</p> |
| |
| <p>To embed an OLE Document, create an <i> OleClientSite</i> object. |
| To embed an ActiveX Control, create an <i> OleControlSite</i> object. |
| The parent in either case is the <i>OleFrame</i>. When you create the <i> |
| OleClientSite</i> or the <i>OleControlSite</i>, the associated OLE Document |
| or ActiveX Control will automatically be created and associated with the |
| container site.</p> |
| |
| <p>There are two ways to create an <i>OleClientSite</i>:</p> |
| |
| <ol> |
| <li>Create an <i> OleClientSite</i> from a ProgramID. A ProgramID |
| is a string that identifies the application. For example, the ProgramID |
| for Word is "Word.Document" and the ProgramID for Excel is |
| "Excel.Chart". The ProgramID for an application can be found |
| in the Windows Registry. Using the following constructor, a blank |
| document is created (similar to choosing File->New from a standalone |
| application):</li> |
| |
| <pre> |
| OleClientSite clientSite = new OleClientSite(frame, SWT.NONE, "Word.Document"); |
| </pre> |
| |
| <li>Create an <i> OleClientSite</i> from a Storage file. A Storage |
| file is a file with an OLE format that contains information about the |
| type of OLE Object that can view it. It also contains a structured |
| storage format and will store information such as paragraph formats, |
| dictionaries or Author/Title/Description tags. For example, a |
| ".doc" file created by Word is a Storage file. Given a |
| Storage file, OLE will figure out which OLE Document to create.</li> |
| |
| <pre> |
| File file = new File("C:\\OleDocumentation.doc"); |
| OleClientSite clientSite = new OleClientSite(frame, SWT.NONE, file); |
| </pre> |
| </ol> |
| |
| <p>An <i> OleControlSite</i> is created from the ProgramID for the |
| ActiveX Control. For example, the ProgramID for the Internet Explorer is |
| "Shell.Explorer". The web browser can be embedded in an |
| application as follows:</p> |
| |
| <pre> |
| OleControlSite controlSite = new OleControlSite(frame, SWT.NONE, "Shell.Explorer"); |
| </pre> |
| |
| <h3>Activate the OLE Object</h3> |
| |
| <p>The final step before an OLE Document or ActiveX control becomes |
| visible inside the application is to activate the OLE Object (often |
| referred to as <i> in-place activation</i>). This is done by invoking |
| the "doVerb" action on the <i> OleClientSite</i> or <i> |
| OleControlSite</i>. The "doVerb" syntax is as follows:</p> |
| |
| <pre> |
| public int doVerb(int verb) |
| </pre> |
| |
| <p>where</p> |
| |
| <ul> |
| <li><b>verb</b> – an integer value mapping to one of the |
| following pre-defined verb values:</li> |
| |
| <ul> |
| <li>OLE.OLEIVERB_PRIMARY – 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.</li> |
| |
| <li>OLE.OLEIVERB_SHOW – 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.</li> |
| |
| <li>OLE.OLEIVERB_OPEN – 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 OLEIVERB_SHOW.</li> |
| |
| <li>OLE.OLEIVERB_HIDE – Causes an object to remove its user |
| interface from the view. Applies only to objects that are activated |
| in-place.</li> |
| |
| <li>OLE.OLEIVERB_INPLACEACTIVATE – 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.</li> |
| |
| <li>OLE.OLEIVERB_UIACTIVATE – 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.</li> |
| |
| <li>OLE.OLEIVERB_DISCARDUNDOSTATE – Used to tell objects to |
| discard any undo state that they may be maintaining without |
| deactivating the object.</li> |
| </ul> |
| |
| <li><b>return value</b> – OLE.S_OK if the doVerb command was |
| successful.</li> |
| </ul> |
| |
| <p><b>Further Reading</b> on "doVerb": MSDN Library: |
| Windows CE Documentation->Application Development->API |
| Reference->Core |
| ->Interfaces->IOleObject::IUnknown->IOleObject::DoVerb</p> |
| |
| <h3>Saving changes to an OLE Document</h3> |
| |
| <p>The changes made to the OLE Document can be saved to a Storage |
| file or an ordinary file. As described above, a Storage file contains |
| information in the header that is specific to OLE.</p> |
| |
| <p>Applications like Word save additional information in the Storage |
| file such as paragraph formats, Author's name and Company. If you save a |
| Word Document to an ordinary file, only the text will be saved.</p> |
| |
| <p>Some applications edit resources which are not OLE specific and |
| therefore can not save their contents into a Storage file because then |
| other applications will not understand the contents. For example, a |
| bitmap can be edited with Microsoft's Paint application which can be |
| embedded as an OLE Document. A bitmap, however, has a format that does |
| not include an OLE header. In this case, the contents must be saved to |
| an ordinary file.</p> |
| |
| <p>Before saving the file, check that a save is necessary using the |
| method <tt>isDirty()</tt> on the <i>OleClientSite</i>. If a save is |
| required, invoke the method <tt>save(File file, boolean |
| includeOleInfo)</tt> on the <i>OleClientSite</i>. The boolean <tt>includeOleInfo</tt> |
| should be set to <b> true</b> to save to a Storage file and <b>false</b> to save to an ordinary file.</p> |
| |
| <pre> |
| File file = new File("C:\\OleDocumentation.doc"); |
| OleClientSite clientSite = new OleClientSite(frame, SWT.NONE, file); |
| |
| // ... edit the document ... |
| |
| if (clientSite.isDirty()) { |
| File tempFile = new File(file.getAbsolutePath() + ".tmp"); |
| file.renameTo(tempFile); |
| if (clientSite.save(file, true)){ |
| // save was successful so discard the backup |
| tempFile.delete(); |
| } else { |
| // save failed so restore the backup |
| tempFile.renameTo(file); |
| } |
| } |
| </pre> |
| |
| <h3>Deactivating the OLE Object</h3> |
| |
| <p>If several OLE Documents or ActiveX Controls are embedded in an |
| application, it may be preferable to have only one OLE Object "active" |
| at a time. The OLE Object that is not currently being used can be |
| deactivated. When the OLE Object is deactivated, it is placed in a |
| "Running" state, its contents are visible but the toolbar and |
| menu bar have been removed and the content does not respond to mouse or |
| keyboard actions. In this state, the object is still alive. If |
| modifications have been made to the object, when the object is returned |
| to the active state, those changes will still be present.</p> |
| |
| <p>NOTE: In the case of OLE Documents, the order of activating and |
| deactivating is very important; first deactivate the old document and |
| then activate the new document otherwise the menu bar will not appear |
| correctly.</p> |
| |
| <p>Deactivating an OLE Document or ActiveX Control is done by |
| calling <tt>deactivateInPlaceClient</tt> on the <i> OleClientSite</i> or |
| <i>OleControlSite</i>:</p> |
| |
| <pre> |
| currentSite.deactivateInPlaceClient(); |
| </pre> |
| |
| <h3>Disposing the OLE Object</h3> |
| |
| <p>Because <i> OleFrame</i>, <i> OleClientSite</i> and <i> |
| OleControlSite</i> are SWT Widgets, when the parent is disposed, the |
| children will be disposed automatically. To terminate an OLE Document or |
| ActiveX Control while other OLE Objects are still running in the same <i> |
| OleFrame</i>, directly dispose of the object:</p> |
| |
| <pre> |
| myClientSite.dispose(); |
| </pre> |
| |
| <p>or</p> |
| |
| <pre> |
| myControlSite.dispose(); |
| </pre> |
| |
| <p>Note: When an OLE Object is terminated, saving is not performed |
| automatically, nor will there be any checking for a "dirty" |
| state (no checking for unsaved changes before closing). The application |
| must write this code.</p> |
| |
| <h2>Using Customized Behavior</h2> |
| |
| <p>ActiveX Controls and OLE Documents can provide customized behavior. To |
| see what kinds of customized behavior are available refer to the type |
| library associated with the OLE Object. SWT provides access to several |
| different types of customized behavior: the "Exec Command", |
| the "IDispatch interface", Events and Property Change |
| Notification.</p> |
| |
| <h3>Exec Command</h3> |
| |
| <p>The "exec" command is a generic way of sending a predefined |
| set of commands to either an OLE Document or an ActiveX Control. The |
| command syntax is as follows:</p> |
| |
| <pre> |
| int OleClientSite.exec(int cmdID, int options, Variant in, Variant out) |
| </pre> |
| |
| <p>where</p> |
| |
| <ul> |
| <li><b>cmdID</b> – an identifier for the command such as |
| OLE.OLECMDID_OPEN, OLE.OLECMDID_NEW, OLE.OLECMDID_SAVE</li> |
| |
| <li><b>options</b> – the behavior of the command can be |
| modified through the use of options such as |
| OLE.OLECMDEXECOPT_DODEFAULT, OLE.OLECMDEXECOPT_PROMPTUSER, |
| OLE.OLECMDEXECOPT_DONTPROMPTUSER or OLE.OLECMDEXECOPT_SHOWHELP</li> |
| |
| <li><b>in</b> – parameters to be passed into the command</li> |
| |
| <li><b>out</b> – values return from the command</li> |
| |
| <li><b>return value</b> – the return value will be OLE.S_OK |
| if the action was successful.</li> |
| </ul> |
| |
| <p>In and out parameters are defined using a Variant, which is the |
| OLE mechanism for generically passing around any type of data. A Variant |
| may contain an integer, a boolean, a string or many other different |
| types of objects.</p> |
| |
| <p>The OLE Object may or may not recognize the command. Before |
| sending a command, you can ask an OLE Object if it recognizes the |
| command using OleClientSite.queryStatus(int cmdID). This will return |
| some combination of the following values:</p> |
| |
| <ul> |
| <li>OLE.OLECMDF_SUPPORTED – The command is supported by this |
| object.</li> |
| <li>OLE.OLECMDF_ENABLED – The command is available and |
| enabled.</li> |
| <li>OLE.OLECMDF_LATCHED – The command is an on-off toggle |
| and is currently on.</li> |
| </ul> |
| |
| <p>Here is an example of how the Exec command is used:</p> |
| |
| <pre> |
| int result = controlSite.queryStatus(OLE.OLECMDID_PRINT); |
| if ((result & OLE.OLECMDF_ENABLED) == OLE.OLECMDF_ENABLED) { |
| controlSite.exec(OLE.OLECMDID_PRINT, OLE.OLECMDEXECOPT_PROMPTUSER, null, null); |
| } |
| </pre> |
| |
| <p><b>Further Reading</b> on "exec": MSDN Library: |
| Platform SDK->Component Services ->COM ->OLE and Data |
| Transfer->Reference ->Interfaces->IOleCommandTarget</p> |
| |
| <h3>IDispatch or OLE Automation</h3> |
| |
| <p>An OLE Document or ActiveX Control can also provide a much richer set of |
| commands than the generic set defined for the "exec" command. |
| To access these, use the IDispatch interface. IDispatch provides access |
| to get and set property values and invoke methods. For example, Word |
| provides the entire Word Basic interface that gives you access to all |
| sorts of commands and properties like cut/copy/paste, print, spell |
| check, select text, change paragraph format, etc. In SWT the IDispatch |
| capabilities are accessed using the <i> OleAutomation</i> object.</p> |
| |
| <h4>Creating the Automation object:</h4> |
| |
| <p>An <i> OleAutomation</i> object can be created from a client or control |
| site or it can be obtained as the return value from a method invocation.</p> |
| |
| <p>A simple case is the Web Browser. It provides commands like |
| navigate, back, forward, home which you can access like this:</p> |
| |
| <pre> |
| OleControlSite controlSite = new OleControlSite(frame, SWT.NONE, "Shell.Explorer"); |
| OleAutomation automation = new OleAutomation(controlSite ); |
| </pre> |
| |
| <h4>Get a Property</h4> |
| |
| <p>A Property is obtained from an OLE Object using the <i> |
| OleAutomation</i> method <tt><b>getProperty</b></tt>:</p> |
| |
| <pre> |
| Variant getProperty(int dispIdMember) |
| </pre> |
| |
| <p>where</p> |
| |
| <ul> |
| <li><b>dispIDMember</b> - identifies the Property in which you are |
| interested. You may already know the value of the dispIDMember from |
| looking in the type library or you may just know the string identifier |
| (also available in the type library). You can get the integer value |
| from the string identifier using <tt>OleAutomation.GetIDsOfNames(String[] |
| names)</tt>. The method getProperty returns a Variant; as discussed above, |
| this is the OLE mechanism for being able to generically pass around any |
| type of data. You ask the Variant to provide the value it contains in |
| the format that you require.</li> |
| |
| <li><b>return value</b> - this is a Variant containing the value |
| of the property. A Variant is a generic way of passing around data. You |
| can ask the Variant for the data in the format that you prefer.</li> |
| </ul> |
| |
| <p>For example:</p> |
| |
| <pre> |
| OleControlSite controlSite = new OleControlSite(frame, SWT.NONE, "Shell.Explorer"); |
| OleAutomation automation = new OleAutomation(controlSite); |
| int[] rgdispid = automation.getIDsOfNames(new String[]{"LocationName"}); |
| int dispIdMember = rgdispid[0]; |
| Variant result = automation.getProperty(dispIdMember); |
| System.out.println("The Web Browser is currently viewing the URL "+result.getString()); |
| </pre> |
| |
| <p>Matching type library record:</p> |
| |
| <pre> |
| interface IWebBrowser : IDispatch { |
| ... |
| [id(0x000000d2), propget, helpstring("Gets the short (UI-friendly) name of the URL/file currently viewed.")] |
| HRESULT LocationName([out, retval] BSTR* LocationName); |
| ... |
| } |
| </pre> |
| |
| <h4>Set a Property</h4> |
| |
| <p>This is very similar to "Get a Property". In this case the |
| method is:</p> |
| <pre> |
| boolean OleAutomation.setProperty(int dispIdMember, Variant rgvarg). |
| </pre> |
| |
| <p>where</p> |
| |
| <ul> |
| <li><b>dispIdMember</b> – as above</li> |
| <li><b>rgvarg</b> - contains the value to which you want the |
| property set.</li> |
| <li><b>return value</b> – true if property was set.</li> |
| </ul> |
| |
| <p>For example:</p> |
| |
| <pre> |
| // Allow multiple selection in an embedded Calendar Control |
| OleControlSite controlSite = new OleControlSite(frame, SWT.NONE, "MSComCtl2.MonthView"); |
| OleAutomation automation = new OleAutomation(controlSite); |
| int[] rgdispid = automation.getIDsOfNames(new String[]{"MultiSelect"}); |
| int dispIdMember = rgdispid[0]; |
| Variant multiSelect = new Variant((short)1); // set to true (0 = false) |
| automation.setProperty(dispIdMember, multiSelect); |
| </pre> |
| |
| <p>Matching type library record:</p> |
| |
| <pre> |
| interface IMonthView : IDispatch { |
| ... |
| [id(0x000000013), propput, helpstring("Allow multiple selection."), helpcontext(0x00030da8)] |
| HRESULT MultiSelect([in] BSTR pbMultiSelect); |
| ... |
| } |
| </pre> |
| |
| <h4>Invoke a Command</h4> |
| |
| <p>Invoking a command is a bit more complicated because you can pass |
| in multiple parameters and because some of these parameters may be |
| optional, you must pass an identifier for the parameter as well as the |
| value of the parameter. There are three variants on the |
| OleAutomation.invoke method to accommodate this:</p> |
| |
| <ul> |
| <li><tt>Variant invoke(int dispIdMember)</tt> – Command |
| takes no parameters</li> |
| |
| <li><tt>Variant invoke(int dispIdMember, Variant[] rgvarg)</tt> |
| – All parameters are mandatory and therefore none are named</li> |
| |
| <li><tt>Variant invoke(int dispIdMember, Variant[] rgvarg, |
| int[] rgdispidNamedArgs)</tt> – Some parameters are optional and |
| therefore all the parameters are named</li> |
| </ul> |
| |
| <p>where</p> |
| |
| <ul> |
| <li><b>dispIdMember</b> – the identifier of the command</li> |
| |
| <li><b>rgvarg</b> – an array of Variants holding the values |
| of the parameters you are passing in.</li> |
| |
| <li><b>rgdispidNamedArgs</b> – an array of the identifiers |
| for the arguments.</li> |
| |
| <li><b>return value</b> – a Variant containing the result |
| that was passed back by the command. Depending on the command, this may |
| be null.</li> |
| </ul> |
| |
| <p>Example 1:</p> |
| |
| <p>The "GoForward" command on the Web Browser takes no |
| parameters:</p> |
| |
| <pre> |
| OleControlSite webSite = new OleControlSite(frame, SWT.NONE, "Shell.Explorer"); |
| OleAutomation automation = new OleAutomation(webSite); |
| int[] rgdispid = automation.getIDsOfNames(new String[]{"GoForward"}); |
| int dispIdMember = rgdispid[0]; |
| Variant pVarResult = automation.invoke(dispIdMember); |
| </pre> Note: Call <b> getIDsOfNames</b> to get the ID of the command |
| |
| <p>Matching type library record:</p> |
| |
| <pre> |
| interface IWebBrowser : IDispatch { |
| ... |
| [id(0x00000065), helpstring("Navigates to the next item in the history list.")] |
| HRESULT GoForward(); |
| ... |
| } |
| </pre> |
| |
| <p>Example 2:</p> |
| |
| <p>The "Navigate" command of the Web Browser takes several |
| arguments but there is only one mandatory parameter and that is the |
| "URL". In this example we are not going to send any of the |
| optional arguments:</p> |
| |
| <pre> |
| OleControlSite controlSite = new OleControlSite(frame, SWT.NONE, "Shell.Explorer"); |
| OleAutomation automation = new OleAutomation(controlSite); |
| int[] rgdispid = automation.getIDsOfNames(new String[]{"Navigate"}); |
| int dispIdMember = rgdispid[0]; |
| Variant[] rgvarg = new Variant[1]; // this is the URL parameter |
| rgvarg[0] = new Variant("www.ibm.com"); |
| Variant pVarResult = automation.invoke(dispIdMember, rgvarg); |
| </pre> |
| |
| <p>Matching type library record:</p> |
| |
| <pre> |
| interface IWebBrowser : IDispatch { |
| ... |
| [id(0x00000068), helpstring("Navigates to a URL or file.")] |
| HRESULT Navigate( |
| [in] BSTR URL, |
| [in, optional] VARIANT* Flags, |
| [in, optional] VARIANT* TargetFrameName, |
| [in, optional] VARIANT* PostData, |
| [in, optional] VARIANT* Headers); |
| ... |
| } |
| </pre> |
| |
| <p>Example 3:</p> |
| |
| <p>The "FormatFont" command in Word Basic takes several |
| optional parameters and we are interested in just a few of them:</p> |
| |
| <pre> |
| // This is a helper method for getting access to Word's WordBasic IDispatch interface |
| // because it is rather complicated |
| private OleAutomation getWordBasic(OleClientSite clientSite) { |
| // Get generic IDispatch interface |
| OleAutomation dispInterface = new OleAutomation(clientSite); |
| |
| // Get Application |
| int[] appId = dispInterface.getIDsOfNames(new String[]{"Application"}); |
| if (appId == null) OLE.error(OLE.ERROR_APPLICATION_NOT_FOUND); |
| Variant pVarResult = dispInterface.getProperty(appId[0]); |
| if (pVarResult == null) OLE.error(OLE.ERROR_APPLICATION_NOT_FOUND); |
| OleAutomation application = pVarResult.getAutomation(); |
| |
| // Get Word Basic |
| int[] wbId = application.getIDsOfNames(new String[]{"WordBasic"}); |
| if (wbId == null) OLE.error(OLE.ERROR_APPLICATION_NOT_FOUND); |
| Variant pVarResult2 = application.getProperty(wbId[0]); |
| if (pVarResult2 == null) OLE.error(OLE.ERROR_APPLICATION_NOT_FOUND); |
| return pVarResult2.getAutomation(); |
| } |
| |
| OleClientSite clientSite = new OleClientSite(frame, SWT.NONE, "Word.Document"); |
| OleAutomation automation = getWordBasic(clientSite); |
| // set the font to 12 point, Italic, Bold - ignore Color and Font name |
| int[] rgdispid = automation.getIDsOfNames(new String[]{"FormatFont", "Points", "Color", "Font", "Bold", "Italic"}); |
| int dispIdMember = rgdispid[0]; |
| Variant[] rgvarg = new Variant[3]; |
| int[] rgdispidNamedArgs = new int[3]; |
| rgvarg[0] = new Variant(12); // this is the Points parameter |
| rgdispidNamedArgs[0] = rgdispid[1]; |
| rgvarg[1] = new Variant(1); // this is the Bold parameter |
| rgdispidNamedArgs[1] = rgdispid[4]; |
| rgvarg[2] = new Variant(1); // this is the Italic |
| rgdispidNamedArgs[2] = rgdispid[5]; |
| automation.invokeNoReply(dispIdMember, rgvarg, rgdispidNamedArgs); |
| </pre> |
| |
| <p>Note: Here we have used <b>invokeNoReply</b> instead of <b>invoke</b>. |
| Word was the first OLE Document ever written and as such it is written |
| slightly differently than other OLE Documents. If a Word command does |
| not return a value, you should use the "InvokeNoReply" |
| variations of invoke. For most other OLE Objects, you can always use |
| "invoke" even if there is no value returned.</p> |
| |
| <p><b>Further Reading</b>: MSDN Library: Books->Inside |
| OLE->Chapter 14->The Mechanics of OLE Automation->The IDispatch |
| Interface</p> |
| |
| <h3>Events and Property changes in Controls</h3> |
| |
| <p><b>addEventListener</b> – allows the user to listen for Events on |
| the Control.</p> |
| |
| <p>Example:</p> |
| <pre> |
| // Respond to ProgressChange events in the Web Browser by updating the applications Progress bar |
| OleControlSite controlSite = new OleControlSite(frame, SWT.NONE, "Shell.Explorer"); |
| OleAutomation automation = new OleAutomation(controlSite); |
| int ProgressChange = 108; //0x6C - obtained from the type library |
| ProgressBar progressBar = new ProgressBar(shell, SWT.BORDER); |
| controlSite.addEventListener(ProgressChange, new OleListener() { |
| public void handleEvent(OleEvent event) { |
| if (event.detail != ProgressChange) return; |
| Variant progress = event.arguments[0]; |
| Variant maxProgress = event.arguments[1]; |
| if (progress == null || maxProgress == null) return; |
| |
| progressBar.setMaximum(maxProgress.getInt()); |
| progressBar.setSelection(progress.getInt()); |
| } |
| }); |
| </pre> |
| |
| <p>Note: The application must know the identifier for the event |
| (ProgressChange) and what kind of data it is being given in the <tt>event.argument</tt> |
| (In our example <tt>event.arguments[0]</tt> is the current progress |
| value and <tt>event.arguments[1]</tt> is the maximum progress |
| value)– You can find this out from the type library:</p> |
| |
| <pre> |
| dispinterface DWebBrowserEvents { |
| ... |
| |
| [id(0x0000006c), helpstring("Fired when download progress is updated.")] |
| void ProgressChange( |
| [in] long Progress, |
| [in] long ProgressMax); |
| ... |
| } |
| </pre> |
| |
| <p><b>addPropertyListener</b> – allows the user to be notified |
| before property changes occur—with the option to veto the |
| change—and after property change has occurred.</p> |
| |
| <p>Example:</p> |
| |
| <pre> |
| OleControlSite controlSite = new OleControlSite(frame, SWT.NONE, "Shell.Explorer"); |
| OleAutomation automation = new OleAutomation(controlSite); |
| int[] rgdispid = automation.getIDsOfNames(new String[]{"ReadyState"}); |
| int READYSTATE = rgdispid[0]; |
| |
| // Listen for changes to the ready state and print out the current state |
| controlSite.addPropertyListener(READYSTATE, new OleListener() { |
| public void handleEvent(OleEvent event) { |
| if (event.detail == OLE.PROPERTY_CHANGING) { |
| // Print out the old state |
| Variant state = automation.getProperty(READYSTATE); |
| System.out.println("Web State changing from " + state.getInt()); |
| event.doit = true; // allow property change to happen |
| |
| } |
| if (event.detail == OLE.PROPERTY_CHANGED) { |
| Variant state = automation.getProperty(READYSTATE); |
| System.out.println("Web State changed to " + state.getInt()); |
| } |
| } |
| }); |
| </pre> |
| |
| <p>You can listen for a change to any property defined in the type |
| library.</p> |
| |
| <p>The type library also contains enumerations that can be used to |
| interpret the property values. For example the "ReadyState" |
| values in the previous example are integer values belonging to the |
| following enumeration:</p> |
| |
| <pre> |
| typedef enum { |
| READYSTATE_UNINITIALIZED = 0, |
| READYSTATE_LOADING = 1, |
| READYSTATE_LOADED = 2, |
| READYSTATE_INTERACTIVE = 3, |
| READYSTATE_COMPLETE = 4 |
| } tagREADYSTATE; |
| </pre> |
| |
| <h3>Summary</h3> |
| |
| <p>On the Windows platform, adding OLE Objects to your application |
| expands the user experience. SWT makes this easy to do by allowing OLE |
| Objects to be embedded in SWT <i>Container</i> widgets, making the |
| Object's interface available to your application, and therefore to your |
| users.</p> |
| |
| </div> |
| <div class="notices"> |
| <p>Microsoft, Windows, Windows NT, and the Windows logo are |
| trademarks of Microsoft Corporation in the United States, other |
| countries, or both.</p> |
| <p></p> |
| </div> |
| </body> |
