Topic: APLX Help : System Classes : OCX/ActiveX Controls and OLE Automation : Using OLE linked/embedded documents
[ Previous |Next | Contents | Index | APL Home ]

www.microapl.co.uk

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 | APL Home ]