OLEContainer

Implemented under Windows only

Description

The OLEContainer object allows you to include OLE (Object Linking and Embedding) documents in your APLX windows. For example, you could include a Microsoft Word document as part of a more complex window, merging the Word menus and toolbar with your own. The OLEContainer control handles all of the OLE protocol required for this to work; you merely need to specify the document (or type of document) to be embedded or linked, or alternatively you can allow the user to select one. (You can use the 'Control Browser' item in the APLX 'Tools' menu to find out information about the OLE object types available on your system).

The OLEContainer object automatically merges menus defined by the OLE server application with your own menus on the same window. The group property of your main menu items determine how the merging takes place. Top-level menu items whose group property is one of 0, 2, and 4 are left unchanged. Top-level menu items whose group property is one of 1, 3, and 5 are merged with the OLE server applications menus. In addition, OLE objects which are activated inside your windows add their own toolbars to your window.

Once the document is embedded or linked, the OLEContainer object will have additional properties, methods, and events which belong to the external software but which you can access just as you do with ordinary APLX objects. (To avoid any possible ambiguity, each external property, method, or event name is prefixed with an 'x', but you can omit this provided there is no clash with an APLX built-in name.)

More information on using OLE objects can be found in the separate chapter on OCX/ActiveX Controls and OLE Automation.

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 oledoctypes property of the System object. 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.

Example

      ∇DEMO_OLEContainer;doc_class;contents;DEMO
[1]  ⍝ Sample function demonstrating use of the OLEContainer object
[2]   DEMO←'⎕' ⎕NEW 'Window' ⋄ DEMO.title←'OLE Example'
[3]   DEMO.OLE.New 'OLEContainer' ⋄ DEMO.OLE.align←¯1
[4]   DEMO.Show
[5]  ⍝
[6]  ⍝ Set the file property to empty vector to put up selection dialog.
[7]  ⍝ This will ask the user to choose a document to embed or link
[8]   DEMO.OLE.file←''
[9]  ⍝
[10] ⍝ See what was selected
[11]  doc_class←DEMO.OLE.progid
[12]  :If doc_class≡''
[13]    ⍝ No valid document selected - user probably cancelled dialog
[14]    DEMO.Close 1
[15]    :Return
[16]  :EndIf
[17]  'Document of class ',doc_class,' loaded'
[18] ⍝
[19] ⍝ Read the raw bytes which represent (in encoded form) the document.
[20] ⍝ In a real example, we might save this data to file and later use
[21] ⍝ it to re-create the document in another OLE container
[22]  contents←DEMO.OLE.contents
[23]  'The document requires ',(⍕⍴contents),' bytes of storage'
[24] ⍝
[25] ⍝ Wait for the user to close the window
[26]  0 0⍴⎕WE DEMO
      ∇

Properties

align anchors aquaadjust autoactivate autodraw border caption children class color contents data docstate doublebuffered dragsource droptarget enabled events extent file handle maxsize methods minsize modified name opened order pointer progid properties scale self size sizemode sourceformats style tabstop targetformats tie units verbs visible where winptr

In addition, any properties exported by the embedded object will be available, with the name prefixed by 'x'. You can omit the prefix if the name does not clash with an APLX built-in name.

Methods

Click Clienttoscreen Close Closedocument Delete Doverb Draw Focus Hide New Open Paint Refresh Resize Screentoclient Send Set Show Showproperties Trigger

In addition, any methods exported by the embedded object will be available, with the name prefixed by 'X'. You can omit the prefix if the name does not clash with an APLX built-in name.

Callbacks

onClick onClose onDblClick onDestroy onDragDrop onDragEnd onDragEnter onDragLeave onDragOver onDragStart onFocus onHide onKeyDown onKeyPress onKeyUp onMouseDown onMouseMove onMouseUp onOpen onResize onSend onShow onUnFocus

In addition, any event callbacks defined by the embedded object will be available, with the name prefixed by 'onX'. You can omit the 'X' in the prefix if the name does not clash with an APLX built-in name.