## 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:

          W.OLE.progid„'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:

    	W.OLE.xContent
    1826228

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'

#### OLEContainer properties

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.

#### OLEContainer methods

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.

Topic: APLX Help : System Classes : OCX/ActiveX Controls and OLE Automation : Using OLE linked/embedded documents

[ Previous |Next | Contents | Index ]