Using OLE linked/embedded documents
The second type of OLE Automation supported by APLX is the embedding or linking of a document in one of your APLX windows, using a special control called an OLEContainer. ('Embedding' means that there is a copy of the document associated with the control, whereas 'linking' means that the control does not have a copy of the data but maintains a link to an existing file). The user can edit the document using the application associated with it.
As an example, suppose you want to embed a Microsoft Word document in your application. You must first create a window, and then place an OLEContainer control on it. We use the align property to cause it to fill the window:
W←'⎕' ⎕NEW 'Window' W.OLE.New 'OLEContainer W.OLE.align←¯1
Initially, there is no document in the container, and the properties and methods comprise only those which APLX defines:
W.OLE.properties align anchors autoactivate autodraw border canpaste caption children class colo r contents data docstate doublebuffered dragsource droptarget enabled even ts file handle methods modified name opened order pointer properties scale self size sizemode sourceformats style tabstop targetformats tie verbs vi sible where winptr W.OLE.methods Click Close Closedocument Delete Doverb Draw Focus Hide New Open Paint Refresh Resize Send Set Show Showproperties Trigger
You can invoke Word to embed a document in several ways, as described below. These include writing a filename (or empty vector) to the file property, writing a class name to the progid property, or writing a previously saved document to the contents property. In this example, we create a new blank Word document:
Our APLX window now looks like this, and the user can enter text (if there were a menu on the window, Word's menu would be merged with it):
If the server application exposes its own properties and methods, these will now be accessible to APLX. Not all OLE servers provide such facilities, but Word certainly does:
W.OLE.properties align anchors autoactivate autodraw border canpaste caption children class colo r contents data docstate doublebuffered dragsource droptarget enabled even ts file handle methods modified name opened order pointer properties scale self size sizemode sourceformats style tabstop targetformats tie verbs vi sible where winptr x_CodeName xActiveTheme xActiveThemeDisplayName xActive Window xActiveWritingStyle xApplication xAttachedTemplate xAutoHyphenation xBackground xBookmarks xBuiltInDocumentProperties xCharacters xClickAndTy peParagraphStyle xCodeName xCommandBars xComments xCompatibility xConsecut iveHyphensLimit xContainer xContent xCreator xCustomDocumentProperties xDe faultTabStop xEmail xEmbedTrueTypeFonts xEndnotes xEnvelope ... etc etc W.OLE.methods Click Close Closedocument Delete Doverb Draw Focus Hide New Open Paint Refresh Resize Send Set Show Showproperties Trigger XAcceptAllRevisions XActivate XAddToFavorites XApplyTheme XAutoFormat XAutoSummarize XCheckConsistency X CheckGrammar XCheckSpelling XClose XClosePrintPreview XCompare XComputeSta tistics XConvertNumbersToText XCopyStylesFromTemplate XCountNumberedItems XCreateLetterContent XDataForm XDetectLanguage XEditionOptions ... etc etc
We have again truncated the lists for brevity.
Some properties are themselves objects. For example, the xContent property is actually a pointer to a Content object:
You can explore the properties and methods of the sub-object in the normal way, using a dot notation to drill down the levels:
W.OLE.xContent.properties xApplication xBold xBoldBi xBookmarkID xBookmarks xBorders xCase xCells xCharac ters xCharacterWidth xColumns xCombineCharacters xComments xCreator xDisab leCharacterSpaceGrid xDuplicate xEmphasisMark xEnd xEndnotes xFields xFind xFitTextWidth xFont xFootnotes xFormattedText xFormFields xFrames xGramma rChecked xGrammaticalErrors xHighlightColorIndex xHorizontalInVertical xHy perlinks xID xInformation xInlineShapes xIsEndOfRowMark xItalic xItalicBi xKana xLanguageDetected xLanguageID xLanguageIDFarEast xLanguageIDOther xL istFormat xListParagraphs xNextStoryRange xNoProofing xOrientation xPageSe tup xParagraphFormat xParagraphs xParent xPreviousBookmarkID xReadabilityS tatistics xRevisions xRows xScripts xSections xSentences xShading xShapeRa nge xSpellingChecked xSpellingErrors xStart xStoryLength xStoryType xStyle xSubdocuments xSynonymInfo xTables xText xTextRetrievalMode xTopLevelTabl es xTwoLinesInOne xUnderline xWords
This allows you to set or retrieve the properties of the sub-objects. For example, to write text to the Word document:
W.OLE.xContent.text←'Now is the time'
The main OLEContainer properties are:
style: The style is the sum of a set of flags:
1 = Linked instead of embedded document (must be set before setting the 'file' property) 2 = Allow in-place activation 4 = Show as icon instead of document (must be set before setting 'file' property)
progid: A character vector determining the class of object (for example, whether it is a Word document or a Pinnacle Chart). It is of the same form as the third column of the System object's oledoctypes property. If there is a document loaded, reading the progid property allows you to find out what the document type is. Writing to the progid property creates a new empty document of the appropriate class. If you write an empty vector, a dialog is displayed allowing the user to choose.
file: A character vector determining the name of the document contained in the OLEContainer. If the OLE container is linked to a document, reading the file property allows you to find out its name. Writing to the file property causes the container to attempt to load the document (or link to it, if the style is 1). If you write an empty vector, a dialog is displayed allowing the user to choose a document.
autoactivate: Determines how the activation of the document takes place. One of:
0 = Manual (use the DoVerb method to activate the document) 1 = Automatic (APLX activates it automatically) [Default] 2 = Activate when the control gets focus 3 = Activate when the user double-clicks in the control.
sizemode: Determines how the document fits in the container. One of:
0 = Displays the OLE object at its normal size, clipping any parts that don't fit within the container. [Default] 1 = Displays the OLE object at its normal size, centering it within the container. 2 = Scales or shrinks the view of the OLE object to fit within the container, by scaling width and height proportionally. 3 = Scales or shrinks the view of the OLE object to fill the OLE container, without regard to preserving the proportions of the OLE object. 4 = Displays the OLE object at its normal size and automatically resizes the container to fit the size of the OLE object.
docstate: Read-only property giving information about the OLE document state. One of:
0 = There is no OLE object in the container. 1 = There is an OLE object in the container, but its server application isn't currently running. 2 = The OLE object's server is running. 3 = The OLE object is open in a separate window. 4 = The OLE object is activated inplace, but hasn't yet merged its menus or toolbars. 5 = The OLE object is activated inplace and menus and toolbars have been merged
modified: Boolean property, saying whether the document has been modified. You can reset this to 0 (false).
verbs: Read-only property. It returns a nested array of the application-specific 'verbs' which the server application defines. See the Doverb method for details.
contents: When you read the contents property, APLX returns a character vector containing the internal representation of the document (or the link) in the container, encoded as a series of bytes and including information about the type of the document. You should never change the contents of this vector, but you can store it in a file and write the same vector back to an OLEContainer to cause it to re-display the same document.
The main OLEContainer methods are:
Showproperties: (No arguments). Displays the document's properties dialog.
Doverb: Takes an integer argument which is the ID of a 'verb' to perform. This can either be a positive integer representing one of the application-specific verbs (see the verbs property), or one of the standard verbs:
0 Specifies the action that occurs when an end-user double-clicks the object in its container. ¯1 Instructs an object to show itself for editing or viewing. ¯2 Instructs an object to open itself for editing in a window separate from that of its container. ¯3 Causes an object to remove its user interface from the view. Applies only to objects that are activated in-place. ¯4 Activates an object in place, along with its full set of user-interface tools, including menus, If the object does not support in-place activation, gives domain error ¯5 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. ¯6 Used to tell objects to discard any undo state that they may be maintaining without deactivating the object.
Refresh: (No arguments). Causes the display to be updated to reflect any changes to the source document.
Closedocument: (No arguments). Closes the document, remembers its state, and disconnects from the server application. You can still read the contents property to retrieve the document contents.
Copyright © 1996-2010 MicroAPL Ltd