OLE class

An OLE container control hosts a linked or embedded OLE Automation object — typically a Word document, an Excel spreadsheet, or any other registered OLE server — directly on a form, and lets the user activate and edit the contained object in place via its registered verbs.

Note

The OLE container control is a VB6 compatibility stub in twinBASIC. Almost every OLE-specific property, method, and event is currently unimplemented (each is flagged below). The inherited base-control surface — positioning, sizing, anchoring, focus, drag, mouse cursor — does work normally, so a project ported from VB6 still parses and lays out the control on its form, but cannot create, embed, link, paste, save, or activate an actual OLE object through it.

There is no default property. The default-designer event is Click.

' The OLE-specific calls below are not currently functional
' in twinBASIC; the example is given for reference only.
Private Sub Form_Load()
    OLE1.CreateEmbed vbNullString, "Excel.Sheet"   ' [Unimplemented]
End Sub

Private Sub OLE1_Click()
    OLE1.DoVerb vbOLEPrimary                       ' [Unimplemented]
End Sub

• Linked vs embedded objects
• Verbs
• Activation and display
• Updates and storage
• Data binding
• Properties
• Methods
• Events

Linked vs embedded objects

An OLE container holds either a linked object — a reference to a document on disk that opens in its registered server when activated — or an embedded object whose data is stored inside the host form’s data stream. CreateLink creates a linked object from an existing file; CreateEmbed creates a fresh embedded object of a given class. OLEType reports which form the current contents take, and OLETypeAllowed restricts which forms the container will accept at design or run time.

SourceDoc and SourceItem identify the linked file (and, for partial links, the item within it). Class holds the ProgID of the embedded server (e.g. "Word.Document", "Excel.Sheet").

Verbs

Each OLE server registers a set of verbs — labelled actions like Open, Edit, or Play. FetchVerbs populates the per-instance verb list, exposed as the indexed ObjectVerbs, ObjectVerbFlags, and ObjectVerbsCount properties. DoVerb executes a verb by index — passing vbOLEPrimary runs the server’s primary verb, which is the action invoked by a double-click. AutoVerbMenu controls whether right-clicking the control automatically pops up the verb menu.

Activation and display

AutoActivate chooses when the embedded object is activated for in-place editing — manually, on focus, or on a double-click. DisplayType selects between rendering the object’s content directly and rendering a registered icon. SizeMode chooses how the object’s bitmap is fitted into the container (clipped, stretched, auto-sized, or zoomed).

Updates and storage

A linked object’s last-cached presentation can be re-fetched from its server with Update; UpdateOptions decides whether updates happen automatically or only on demand. The container can be persisted out of an open file with SaveToFile (or SaveToOle1File for the legacy OLE1 stream format) and re-loaded with ReadFromFile, in each case using a Basic file number opened with Open. InsertObjDlg and PasteSpecialDlg raise the standard Windows OLE dialogs for picking an object class or a clipboard format.

Data binding

Setting DataSource and DataField connects the container’s contents to a binary field on a Data control’s recordset, so the embedded object is loaded from and saved back into the row. DataChanged reports whether the contained object differs from the bound row’s stored value.

Properties

Action

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

A run-time-only Integer that, when assigned, performs one of the predefined OLE actions such as create, delete, paste, or update. Modern code uses the equivalent named methods (CreateEmbed, Delete, Paste, Update, …) instead.

Anchors

The set of edges of the parent that the OLE control’s corresponding edges follow when the parent resizes. Read-only — assign individual .Left, .Top, .Right, .Bottom flags through the returned Anchors object.

Appearance

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

Determines how the container’s border is drawn. A member of AppearanceConstants: vbAppearFlat or vbAppear3d (default).

AppIsRunning

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

A run-time-only Boolean: True while the OLE server hosting the embedded object is running. Assigning True starts the server; assigning False shuts it down.

AutoActivate

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

Selects when the embedded object is activated for in-place editing. A member of OLEContainerActivateConstants: vbOLE_ActivateManual, vbOLE_ActivateGetFocus, vbOLE_ActivateDoubleclick (default), or vbOLE_ActivateAuto.

AutoVerbMenu

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

When True (default), right-clicking the container automatically pops up a menu of the contained object’s registered verbs. Boolean.

BackColor

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

The background colour, as an OLE_COLOR. Defaults to the system window-background colour.

BackStyle

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

Selects between an opaque and transparent background (BackFillStyleConstants): vbBFTransparent or vbBFOpaque (default).

BorderStyle

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

Whether the container is drawn with a border. A member of ControlBorderStyleConstants: vbNoBorder or vbFixedSingleBorder (default).

CausesValidation

Determines whether the previously focused control’s Validate event runs before this control receives the focus. Boolean, default True.

Class

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

The ProgID of the OLE server class for the contained object — for example "Word.Document" or "Excel.Sheet". String. Used together with SourceDoc and SourceItem when populating the container at design time, or as the default class for InsertObjDlg.

Container

The control that hosts this OLE control — typically the form. Read with Get, change with Set. Setting Container re-parents the control to a different container at run time.

ControlType

A read-only ControlTypeConstants value identifying this control as an OLE container. Always vbOLEControl.

Data

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

A run-time-only Long handle to the data block returned for the format named in Format. Used together with the ObjectAcceptFormats / ObjectGetFormats machinery to round-trip raw OLE data.

DataChanged

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

A run-time-only Boolean: True if the bound recordset field has changed since the container last loaded it. Cleared after a successful save.

DataField

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

The name of the binary field, in the recordset of the bound DataSource, whose contents are stored and retrieved by the OLE container. String.

DataSource

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

A reference to a Data control (or other DataSource provider) whose recordset supplies the value for DataField. Set with Set.

DataText

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

A run-time-only String alias for transferring text-format data into and out of the contained object’s clipboard equivalent.

DisplayType

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

Whether the container shows the object’s content or its registered icon. A member of OLEContainerDisplayTypeConstants: vbOLE_DisplayContent (default) or vbOLE_DisplayIcon.

Dock

Where the OLE control is docked within its container. A member of DockModeConstants: vbDockNone (default), vbDockLeft, vbDockTop, vbDockRight, vbDockBottom, or vbDockFill. Docked controls ignore Anchors.

DragIcon

A StdPicture used as the mouse cursor while the control is being drag-and-dropped (see Drag and DragMode).

DragMode

Whether the control should drag itself when the user holds the mouse over it. A member of DragModeConstants: vbManual (0, default — call Drag from code) or vbAutomatic (1).

Enabled

Determines whether the control accepts user input. Boolean, default True.

FileNumber

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

A run-time-only Integer giving the Basic file number passed to the most recent ReadFromFile, SaveToFile, or SaveToOle1File call.

Format

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

The clipboard format identifier currently associated with the Data handle. String.

Height

The control’s height, in twips by default (or in the container’s ScaleMode units). Single.

HelpContextID

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC. Available only when the host build defines FEATURE_HELP.

A Long identifying a topic in the application’s help file, retrieved when the user presses F1 while the control has focus.

HostName

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

The friendly name the OLE server should display for the host application — e.g. shown in Word’s title bar while editing the embedded document in place. String.

hWnd

The Win32 window handle for the underlying control, as a LongPtr. Read-only. Useful for passing to API functions.

Index

When the control is part of a control array, the Long zero-based index of this instance within the array. Reading Index on a non-array instance raises run-time error 343 (Object not an array). Read-only at run time.

Left

The horizontal distance from the left edge of the container to the left edge of the control. Single.

LpOleObject

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

A run-time-only LongPtr giving the raw IOleObject interface pointer of the contained object, for hand-off to native code.

MiscFlags

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

A bit-mask of miscellaneous container behaviours (see OLEContainerConstants — vbOLEMiscFlagMemStorage, vbOLEMiscFlagDisableInPlace). Long.

MouseIcon

A StdPicture used as the mouse cursor when MousePointer is vbCustom and the pointer is over the control.

MousePointer

The mouse cursor shown when the pointer is over the control. A member of MousePointerConstants.

Name

The unique design-time name of the control on its parent form. Read-only at run time.

object

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

A run-time-only Object reference to the OLE Automation interface of the contained object — the late-bound entry point for scripting it. Read-only.

ObjectAcceptFormats

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

An indexed String property listing the clipboard formats that the contained object can accept on a paste. Use ObjectAcceptFormatsCount to bound the index.

ObjectAcceptFormatsCount

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

The number of entries in ObjectAcceptFormats. Integer.

ObjectGetFormats

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

An indexed String property listing the clipboard formats that the contained object can produce on a copy. Use ObjectGetFormatsCount to bound the index.

ObjectGetFormatsCount

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

The number of entries in ObjectGetFormats. Integer.

ObjectVerbFlags

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

An indexed Long property giving the menu-flag bit-mask for each entry in ObjectVerbs. The flag values match the Win32 MF_* menu constants and indicate whether the verb item is greyed, checked, etc.

ObjectVerbs

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

An indexed String property listing the names of the verbs registered for the contained object — populated by FetchVerbs. Pass an index to DoVerb to invoke a verb.

ObjectVerbsCount

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

The number of entries in ObjectVerbs. Long.

OLEDropAllowed

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

When True, the container accepts OLE objects dragged onto it from outside the application. Boolean, default False.

OLEType

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

A run-time-only Integer reporting whether the contained object is currently linked, embedded, or empty (see OLEContainerConstants — vbOLELinked, vbOLEEmbedded, vbOLEEither, vbOLENone).

OLETypeAllowed

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

Restricts which kinds of contained object the container will accept. A member of OLEContainerTypesAllowedConstants: vbOLE_Linked, vbOLE_Embedded, or vbOLE_Either (default).

Parent

A reference to the Form (or UserControl) that contains this control. Read-only.

PasteOK

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

A run-time-only, read-only Boolean: True if the current clipboard contents are in a format the contained object would accept via Paste.

Picture

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

A run-time-only, read-only IPictureDisp giving the contained object’s current presentation as a picture, suitable for printing or copying onto a PictureBox.

SizeMode

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

How the contained object’s bitmap is fitted into the container. A member of OLEContainerSizeModeConstants: vbOLE_SizeClip (default), vbOLE_SizeStretch, vbOLE_SizeAutoSize, or vbOLE_SizeZoom.

SourceDoc

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

The full path of the source file used by CreateLink (and the default value for InsertObjDlg). String.

SourceItem

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

The named item within SourceDoc that the link refers to — for example, an Excel range name. String.

TabIndex

The position of the control in the form’s TAB-key navigation order. Long.

TabStop

Whether the user can reach the control by pressing the TAB key. Boolean, default True. A disabled control is skipped regardless of this setting.

Tag

A free-form String the application can use to associate custom data with the control. Ignored by the framework.

Top

The vertical distance from the top of the container to the top of the control. Single.

UpdateOptions

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

How a linked object’s cached presentation is refreshed. A member of OLEContainerUpdateOptionsConstants: vbOLE_UpdateAutomatic (default), vbOLE_UpdateFrozen, or vbOLE_UpdateManual.

Verb

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

A Long verb index used by the legacy Action property when performing the do verb action. New code should call DoVerb directly.

Visible

Whether the control is shown. Boolean, default True.

WhatsThisHelpID

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC. Available only when the host build defines FEATURE_HELP.

A Long identifying a “What’s This?” help-pop-up topic in the application’s help file. See ShowWhatsThis.

Width

The control’s width. Single.

Methods

Close

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

Closes the contained object, ending the running server session if one is open. The container’s data is preserved; only the live editing connection is dropped.

Syntax: object.Close

Copy

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

Copies the contained object to the system clipboard.

Syntax: object.Copy

CreateEmbed

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

Creates a new embedded object of the given class, optionally pre-filled from a template file.

Syntax: object.CreateEmbed SourceDoc [, Class ]

SourceDoc

required A String. Path of a file to use as a template for the new object, or vbNullString to create a blank object.

Class

optional A Variant String ProgID identifying the OLE server class to instantiate (e.g. "Word.Document"). Required when SourceDoc is empty.

CreateLink

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

Creates a linked object that references an existing file on disk.

Syntax: object.CreateLink SourceDoc [, SourceItem ]

SourceDoc

required A String giving the full path of the source file.

SourceItem

optional A Variant String identifying a named item within the source file (e.g. an Excel range name) to link to a fragment rather than the whole document.

Delete

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

Removes the contained object from the container. Releases all resources associated with it.

Syntax: object.Delete

DoVerb

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

Invokes a registered verb on the contained object. The standard verb constants are defined in OLEContainerConstants — vbOLEPrimary (0), vbOLEShow (-1), vbOLEOpen (-2), vbOLEHide (-3), vbOLEUIActivate (-4), vbOLEInPlaceActivate (-5), vbOLEDiscardUndoState (-6); positive indices refer to the per-server entries in ObjectVerbs.

Syntax: object.DoVerb [ Verb ]

Verb

optional A Variant Long. Defaults to vbOLEPrimary if omitted.

Drag

Begins, completes, or cancels a manual drag-and-drop operation. Typically called from a MouseDown handler when DragMode is vbManual.

Syntax: object.Drag [ Action ]

Action

optional A member of DragConstants: vbCancel (0), vbBeginDrag (1, default), or vbEndDrag (2).

FetchVerbs

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

Re-reads the verb list from the contained object’s server and refreshes ObjectVerbs, ObjectVerbFlags, and ObjectVerbsCount.

Syntax: object.FetchVerbs

InsertObjDlg

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

Displays the standard Windows Insert Object dialog so the user can choose between a new embedded object, an existing file (linked or embedded), or an icon.

Syntax: object.InsertObjDlg

Move

Repositions and optionally resizes the control in a single call.

Syntax: object.Move Left [, Top [, Width [, Height ] ] ]

Left

required A Single giving the new horizontal position.

Top, Width, Height

optional New values for the corresponding properties. Omitted values are left unchanged.

Paste

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

Pastes the current clipboard contents into the container, if PasteOK reports the format is acceptable.

Syntax: object.Paste

PasteSpecialDlg

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

Displays the standard Windows Paste Special dialog so the user can choose how the current clipboard contents are pasted (link, embed, or as a specific format).

Syntax: object.PasteSpecialDlg

ReadFromFile

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

Reads the container’s contents from a Basic-style binary file previously written with SaveToFile.

Syntax: object.ReadFromFile FileNumber

FileNumber

required An Integer. The file number returned by the Open statement, on a stream opened For Binary.

SaveToFile

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

Writes the container’s contents — including the linked or embedded object’s data and any presentation cache — to a Basic-style binary file in the current OLE2 stream format.

Syntax: object.SaveToFile FileNumber

FileNumber

required An Integer opened For Binary.

SaveToOle1File

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

Writes the container’s contents in the legacy OLE1 stream format. Provided for round-tripping data files produced by very old applications; new code should use SaveToFile.

Syntax: object.SaveToOle1File FileNumber

FileNumber

required An Integer opened For Binary.

SetFocus

Moves the input focus to the control. The control must be both Visible and Enabled, or run-time error 5 (Invalid procedure call or argument) is raised.

Syntax: object.SetFocus

ShowWhatsThis

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC. Available only when the host build defines FEATURE_HELP.

Displays the topic identified by WhatsThisHelpID as a “What’s This?” pop-up.

Syntax: object.ShowWhatsThis

Update

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

For a linked object, retrieves the latest data from the source file and refreshes the cached presentation. For an embedded object whose server is running, asks the server to commit any pending changes back into the container.

Syntax: object.Update

ZOrder

Brings the control to the front or back of its sibling stack.

Syntax: object.ZOrder [ Position ]

Position

optional A member of ZOrderConstants: vbBringToFront (0, default) or vbSendToBack (1).

Events

Click

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

Raised when the user clicks the container with any mouse button. Default-designer event.

Syntax: object_Click( )

DblClick

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

Raised when the user double-clicks the container. With the default AutoActivate setting vbOLE_ActivateDoubleclick, this is the same gesture that activates the contained object for in-place editing.

Syntax: object_DblClick( )

DragDrop

Raised on the destination control when a manual drag operation ends over it.

Syntax: object_DragDrop( Source As Control, X As Single, Y As Single )

DragOver

Raised on the control under the cursor while a manual drag operation is in progress.

Syntax: object_DragOver( Source As Control, X As Single, Y As Single, State As Integer )

GotFocus

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

Raised when the control receives the input focus.

Syntax: object_GotFocus( )

Initialize

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

Raised once, after the control’s underlying window has been created.

Syntax: object_Initialize( )

KeyDown

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

Raised when the user presses any key while the control has focus.

Syntax: object_KeyDown( KeyCode As Integer, Shift As Integer )

KeyPress

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

Raised when the user types a character that produces an ANSI keystroke.

Syntax: object_KeyPress( KeyAscii As Integer )

KeyUp

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

Raised when the user releases a key while the control has focus.

Syntax: object_KeyUp( KeyCode As Integer, Shift As Integer )

LostFocus

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

Raised when the control loses the input focus.

Syntax: object_LostFocus( )

MouseDown

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

Raised when the user presses any mouse button over the control.

Syntax: object_MouseDown( Button As Integer, Shift As Integer, X As Single, Y As Single )

MouseMove

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

Raised when the cursor moves over the control.

Syntax: object_MouseMove( Button As Integer, Shift As Integer, X As Single, Y As Single )

MouseUp

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

Raised when the user releases a mouse button over the control.

Syntax: object_MouseUp( Button As Integer, Shift As Integer, X As Single, Y As Single )

ObjectMove

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

Raised when the contained object asks the container to relocate or resize itself — typically in response to in-place editing changes.

Syntax: object_ObjectMove( Left As Single, Top As Single, Width As Single, Height As Single )

Resize

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

Raised when the contained object reports a new natural size — for example, after an embedded image is replaced with one of different dimensions.

Syntax: object_Resize( HeightNew As Single, WidthNew As Single )

Updated

Note

Reserved for VB6 compatibility; not currently implemented in twinBASIC.

Raised after the contained object has been modified, so the host can flag itself as dirty. Code is one of the status values in OLEContainerConstants: vbOLEChanged, vbOLESaved, vbOLEClosed, or vbOLERenamed.

Syntax: object_Updated( Code As Integer )

Validate

Raised when the focus is moving to another control whose CausesValidation is True. Setting Cancel to True keeps the focus on this control.

Syntax: object_Validate( Cancel As Boolean )