Tips for using OLE in Notes by John Thornton (with Barbara Burch) [Editor’s note: This article resides in “Iris Today”, the technical Webzine located on the http://www.notes.net Web site produced by Iris Associates, the developers of Domino and Notes.] From the very beginning, Notes has played well with other applications. Whether using import/export capabilities in R1, or OLE features and NotesFX (Notes Field Exchange) in R3, or ActiveX support and beyond, you've always been able to easily transfer data in-and-out of Notes. In fact, according to former Iris developer Jack Ozzie, "Notes R3 was one of the first, if not the first, OLE container." Since then, Notes has continuously expanded its support of OLE as a powerful design tool. R4 included rich OLE features like in-place editing, drag-and-drop support, NotesLinks, and the extension of NotesFX to include Notes actions (NotesFlow). In addition, you could use Notes as an automation object with LotusScript, or use Notes as an OLE automation controller. Notes R4.6 enhanced its OLE features further by adding ActiveX support. This introduced several OLE properties to control how OLE and OLE custom controls (OCX) load and display in Notes. For example, these properties allow an object to size to the window, size below a field, update from a document instead of from a form, or run in read mode. You can see examples of these features when you use Lotus Word Pro or Microsoft Word as your mail editor in Notes R4.6. In the rest of this article, we'll take a closer look at some of the OLE features in Notes. We'll first look at the three new NotesEmbeddedObject properties that are available in Notes R4.6.2 via LotusScript, and show you those properties in action. Then, we'll provide some tips for using specific OLE features in Notes, including examples of NotesFX and NotesFlow. Finally, we'll answer some common questions about OLE that have come up in the Notes/Domino forum on Notes.net. Downloading the sample database You can try out the techniques described in this article by downloading the following self-extracting database (185Kb): Ole.exe Note: The LotusScript examples in this database require that you use R4.6.2 or later. You can download R4.6.2 from Notes.net. The NotesFX examples work with any release of R4.x. An introduction to new OLE properties in R4.6.2 Notes R4.6 introduced four new properties for OLE and OCX objects: size object to window, size object below fields, run object when reading document, and update from document. You can set these properties manually by selecting the object and choosing menu options. For example, you can select a Lotus 1-2-3 OLE object and then choose Workbook - Object Properties, or you can select an OCX object, and choose Applet - Object Properties. In Notes R4.6.2, these properties (except for update from document) are now available via LotusScript. These properties can be very powerful in allowing you to make OLE/OCX objects work seamlessly in Notes. Below are descriptions of these properties, and comments concerning when and how to use them. FitToWindow The FitToWindow property sizes embedded objects to fit the document window. This property is available for embedded OLE objects and OLE controls (ActiveX or OCX). When you enable the FitToWindow property, the embedded object takes over the entire document window when activated. If the embedded object supports ActiveX documents (DocObject) and has requested this behavior from Notes, Notes only honors the request if FitToWindow or FitBelowFields is set. (An embedded object cannot have both this property and the FitBelowFields property set.) Since controls run when you open a document in edit mode (and in read-only mode when RunReadOnly is set), the object immediately takes over the window. OLE embedded objects take over the window when they are UI activated (for example, by double-clicking on the OLE object). As a result of the activation, any other objects or Notes fields are hidden. Because of this, we suggest that you use the FitToWindow property when you have only one embedded object on a document. This property is useful when you want users to be able to use their OLE application (or OLE control) and still be within a Notes document. For example, you can see this property at work when you use the Microsoft Office Library template (DOCLBM46.ntf), and when you use Lotus Word Pro or Microsoft Word as your default memo editor (choose File - Tools - User Preferences, click the Mail icon, and select an application in the Document Memo Editor field). For more information on the Microsoft Office Library template, see the article "Managing documents with the MS Office Library template." For more on the mail editor feature, see the article "Editing mail with Lotus WordPro or Microsoft Word." Defined in - NotesEmbeddedObject Data type - Boolean Syntax To get: flag = notesEmbeddedObject.FitToWindow To set: notesEmbeddedObject.FitToWindow = flag Legal Values True. Take over the entire document window when activated False. Do normal, in-place activation. This is the default. FitBelowFields The FitBelowFields property sizes embedded objects to fit below the first layout region in the document. This property is available for embedded OLE objects and OLE controls (ActiveX or OCX). When you enable the FitBelowFields property, the embedded object takes over the entire document window below the layout region when activated. The UI behavior of the embedded object is the same as if it did not have FitBelowFields set. If the embedded object supports ActiveX documents (DocObject) and has requested this behavior from Notes, Notes only honors the request if FitToWindow or FitBelowField is set. (An embedded object cannot have both this property and the FitBelowFields property set.) The layout region and object behave in tandem, moving and sizing together, always keeping the same relative positions. Automatic scrolling of the layout region -- for when the window is sized to be smaller than the layout -- is disabled for this relationship. Since controls run when a document is opened in edit mode (and in read-only mode if RunReadOnly is set), the object immediately takes over the window below the layout region. OLE embedded objects take over the window below the layout region when they are UI activated. As a result of the activation, any other objects or Notes fields (except the layout region) are hidden. Because of this, we suggest that you use the FitBelowFields property when you have only one embedded object on a document. This property is useful to use when you have a form using a layout region on the top portion, and you want your embedded object to load below this layout region. This gives the user the ability to quickly select something in the layout region or work in the embedded object. Defined in - NotesEmbeddedObject Data type - Boolean Syntax To get: flag = notesEmbeddedObject.FitBelowFields To set: notesEmbeddedObject.FitBelowFields = flag Legal Values True. Take over the document window after first layout when activated False. Do normal, in-place activation. This is the default. RunReadOnly The RunReadOnly property runs the embedded object when users read the document. This property is available only for embedded OLE controls (ActiveX or OCX). When you enable the RunReadOnly property, the embedded control allows editing during read-only mode, but no changes are saved. The control is in-place activated (but not UI-activated) when the document is in read-only mode. Therefore, the property is not applicable to embedded OLE objects, since you can activate them in read-only mode without saving changes. This property is useful when you want to allow a user to activate an OLE control, and to also see the data while in read mode. (Many OLE controls do not load in read mode, and sometime do not even render data in read mode.) Of course, no changes are allowed during read mode. Defined in - NotesEmbeddedObject Data type - Boolean Syntax To get: flag = notesEmbeddedObject.RunReadOnly To set: notesEmbeddedObject.RunReadOnly = flag Legal Values True. Run the control when document is in read-only mode False. Do not run the control when the document is in read-only mode. This is the default. Update object from document This is the one object property that is not available via LotusScript, but we'll go ahead and talk about it here. The "Update Object from Document" property is available only for embedded OLE objects or OLE controls (ActiveX or OCX) on a subform or form. When you enable the "Update Object from Document" property, the embedded object is updated according to edits made via the document and not from the form (which is the default behavior). For example, embed either an OLE object or control on a form, and enable this property. When users create a document using the form, then edit the embedded object and save the document, their changes are saved. The next time you open the document, you'll see the new data in the embedded object, and not what was originally on the form. The new OLE properties in action The sample database contains three agents that demonstrate each of the new LotusScript properties, and an agent that clears the properties. Each agent cycles through each document and looks for an OLE/OCX with an object name of "Object Test." To see the properties at work, use the following steps: Note: To see the OLE control activation in this example, you need to have Lotus Components Sheet (version 1.2) installed on your system. To see the OLE object activation, you need to have one of the following: Paint, WordPad, Lotus 1-2-3 97, or Microsoft Excel 97.