| Navigation: Language Reference > App A - DDE, OLE, and OCX > Object Linking and Embedding >====== OLE Container Properties ====== |    |
Contents:
Clarion OLE/OCX library and object hierarchies
There are a number of properties associated with an OLE container control that deal only with OLE objects (not .OCX controls).
Attribute Properties
| PROP:Create | The CREATE attribute (blank if none). (WRITE ONLY) |
| PROP:Open | The OPEN attribute (blank if none). (WRITE ONLY) |
| PROP:Document | The DOCUMENT attribute (blank if none). (WRITE ONLY) |
| PROP:Link | The LINK attribute (blank if none). (WRITE ONLY) |
| PROP:Clip | The CLIP attribute. A toggle attribute. Assigning a null string () or zero turns it off, and '1' or 1 turns it on. (WRITE ONLY) |
| PROP:Stretch | The STRETCH attribute. A toggle attribute. Assigning a null string () or zero turns it off, and '1' or 1 turns it on. (WRITE ONLY) |
| PROP:Autosize | The AUTOSIZE attribute. A toggle attribute. Assigning a null string () or zero turns it off, and '1' or 1 turns it on. (WRITE ONLY) |
| PROP:Zoom | The ZOOM attribute. A toggle attribute. Assigning a null string () or zero turns it off, and '1' or 1 turns it on. (WRITE ONLY) |
| PROP:Compatibility | The COMPATIBILITY attribute (blank if none). (WRITE ONLY) |
Undeclared Properties
| PROP:Blob | Convert an object to and from a blob. (READ/WRITE) | ||||
| PROP:SaveAs | Saves the object to an OLE Compound Storage file. (WRITE ONLY) The syntax for placing the object in the file is 'filename\!component' For example: | ||||
| ?controlx{PROP:SaveAs} = 'myfile\!objectx' | |||||
| PROP:DoVerb | Executes an OLE doverb command from the following set of commands (WRITE ONLY): | ||||
| DOVERB:Primary (0) | Calls the object's primary action. The object, not the container, determines this action. If the object supports in-place activation, the primary verb usually activates the object in-place. | | | ||
| DOVERB:Show (-1) | Tells the object to show itself for editing or viewing. Called to display newly inserted objects for initial editing and to show link sources. This is usually an alias for some other object-defined action. | | | ||
| DOVERB:Open (-2) | Tells the object to open itself for editing in a separate window from its container (this includes objects that support in-place activation). If the object does not support in-place activation, this has the same action as DOVERB:Show. | | | ||
| DOVERB:Hide (-3) | Tells the object to remove its user interface. This applies only to objects activated in-place. | | | ||
| DOVERB:UIActivate (-4) | Activates the object in place, along with its full set of user-interface tools, including menus, toolbars, and its name in the title bar of the container window. | | | ||
| DOVERB:InPlaceActivate (-5) | Activates the object in-place without displaying the tools (menus and toolbars) that end-users need to change the behavior or appearance of the object. | | | ||
| DOVERB:DiscardUndoState (-6) | Tells the object to discard any undo state that it may be maintaining without deactivating the object. | | | ||
| DOVERB:Properties (-7) | Invokes the modal system property browser for the object to allow the user to set its properties. | | | ||
| PROP:Deactivate | Deactivates an in-place active OLE object. (READ/WRITE/EXECUTE) |
| PROP:Update | Tells the OLE object to update itself. (READ/WRITE/EXECUTE) |
| PROP:CanPaste | Can you paste the object in the clipboard? (READ ONLY) |
| PROP:Paste | Pastes an object from the clipboard to an OLE container control. (READ/WRITE/EXECUTE) |
| PROP:CanPasteLink | Can the object in the clipboard be pasted as a link? (READ ONLY) |
| PROP:PasteLink | Pastes and links an object from the clipboard to an OLE container control. (READ/WRITE/EXECUTE) |
| PROP:Copy | Copies an object in an OLE container control to the clipboard. (READ/WRITE/EXECUTE) |
| PROP:ReportException | Report OLE exceptions (for debug). (WRITE ONLY) |
| PROP:OLE | Is there an OCX or OLE object in the container? (READ ONLY) |
| PROP:Language | The number for the language used for OLE Automation or OCX Method. The number for US English is 0409H, and other language numbers can be computed from the data in the WINNT.H file in the MS Windows SDK. (READ/WRITE) |
Example Program:
PROGRAM
MAP
INCLUDE('OCX.CLW')
SelectOleServer PROCEDURE(OleQ PickQ),STRING
END
INCLUDE 'XL.CLW' !Constants that Excel uses
INCLUDE 'ERRORS.CLW' !Include errorcode constants
SaveLinks FILE,DRIVER('TopSpeed'),PRE(SAV),CREATE
Object BLOB
Record RECORD
LinkType STRING(1) !F = File, B = BLOB
LinkFile STRING(64) !OLE Compound Storage file name and object
END
END
i LONG !Loop counters
j LONG
ResultQ QUEUE !Queue to hold return from OLEDIRECTORY
Name CSTRING(64)
CLSID CSTRING(64)
ProgID CSTRING(64)
END
MainWin WINDOW('OLE Demo'),AT(,,350,200),STATUS(-1,-1),SYSTEM,GRAY,RESIZE,MAX,TIMER(1)
MENUBAR
MENU('&File')
ITEM('e&xit'),USE(?exit)
END
MENU('&Objects')
ITEM('Create Object'),USE(?CreateObject)
ITEM('Paste Object'),USE(?PasteObject)
ITEM('PasteLink Object'),USE(?PasteLinkObject)
ITEM('Save Object to BLOB'),USE(?SaveObjectBlob),DISABLE
ITEM('Save Object to OLE File'),USE(?SaveObjectFile),DISABLE
ITEM('Retrieve Saved Object'),USE(?GetObject),DISABLE
END
MENU('&Activate')
ITEM('&Spreadsheet'),USE(?ActiveExcel)
ITEM('&Any OLE Object'),USE(?ActiveOLE),DISABLE
END
END
OLE,AT(5,10,160,100),COLOR(0808000H),USE(?ExcelObject)
MENUBAR
MENU('&Clarion App')
ITEM('&Deactivate Excel'),USE(?DeactExcel)
END
END
END
OLE,AT(170,10,160,100),USE(?AnyOLEObject),AUTOSIZE
MENUBAR
MENU('&Clarion App')
ITEM('&Deactivate Object'),USE(?DeactOLE)
END
END
END
END
CODE
OPEN(SaveLinks)
IF ERRORCODE() !Check for error on Open
IF ERRORCODE() = NoFileErr !if the file doesn't exist
CREATE(SaveLinks) !then create it
IF ERRORCODE() THEN HALT(,ERROR()) END
OPEN(SaveLinks) !then open it for use
IF ERRORCODE() THEN HALT(,ERROR()) END
ELSE
HALT(,ERROR())
END
END
OPEN(MainWin)
?ExcelObject{PROP:Create} = 'Excel.Sheet.5' !Create an Excel spreadsheet object
DO BuildSheetData !populate it with some random data
IF RECORDS(SaveLinks) !Check for existing saved record
SET(SaveLinks) !and get it
NEXT(SaveLinks)
POST(EVENT:Accepted,?GetObject) !and display it
DO MenuEnable
ELSE
ADD(SaveLinks) !or add blank record
END
IF ERRORCODE() THEN HALT(,ERROR()) END
ACCEPT
CASE EVENT()
OF EVENT:CloseWindow
?ExcelObject{PROP:Deactivate} !Deactivate the OLE Server applications
?AnyOLEObject{PROP:Deactivate}
OF EVENT:Timer
IF CLIPBOARD()
IF ?AnyOLEObject{PROP:CanPaste} !Can Paste object from the clipboard?
IF ?PasteObject{PROP:Disable}
ENABLE(?PasteObject)
END
ELSIF NOT ?PasteObject{PROP:Disable}
DISABLE(?PasteObject)
END
IF ?AnyOLEObject{PROP:CanPasteLink} !Can PasteLink object from clipboard?
IF ?PasteLinkObject{PROP:Disable}
ENABLE(?PasteLinkObject)
END
ELSIF NOT ?PasteLinkObject{PROP:Disable}
DISABLE(?PasteLinkObject)
END
END
OF EVENT:Accepted
CASE FIELD()
OF ?Exit
POST(EVENT:CloseWindow)
OF ?CreateObject
OLEDIRECTORY(ResultQ,0) !Get a list of installed OLE Servers
?AnyOLEObject{PROP:Create} = SelectOleServer(ResultQ) !Let the user pick one
?AnyOLEObject{PROP:DoVerb} = 0 !Activate OLE Server in its default mode
DO MenuEnable
OF ?PasteObject
?AnyOLEObject{PROP:Paste} !Paste the object
SETCLIPBOARD('Paste Completed') !Assign non-object text to clipboard
DO MenuEnable
OF ?PasteLinkObject
?AnyOLEObject{PROP:PasteLink} !PasteLink the object
SETCLIPBOARD('PasteLink Completed') !Assign non-object text to clipboard
DO MenuEnable
OF ?SaveObjectBlob !Save object to BLOB
SAV:Object{PROP:Handle} = ?AnyOLEObject{PROP:Blob}
SAV:LinkType = 'B'
PUT(SaveLinks)
IF ERRORCODE() THEN STOP(ERROR()) END
OF ?SaveObjectFile !Save to OLE Compound Storage file
?AnyOLEObject{PROP:SaveAs} = 'TEST1.OLE\!Object'
SAV:LinkFile = 'TEST1.OLE\!Object'
SAV:LinkType = 'F'
PUT(SaveLinks)
IF ERRORCODE() THEN STOP(ERROR()) END
OF ?GetObject
IF SAV:LinkType = 'F' !Saved to OLE Compound Storage file?
?AnyOLEObject{PROP:Open} = SAV:LinkFile
ELSIF SAV:LinkType = 'B' !Saved to BLOB?
?AnyOLEObject{PROP:Blob} = SAV:Object{PROP:Handle}
END
DISPLAY
OF ?ActiveExcel
?ExcelObject{PROP:DoVerb} = 0 !In-place activate Excel
OF ?ActiveOLE
?AnyOLEObject{PROP:DoVerb} = 0 !Activate OLE Server in its default mode
OF ?DeactExcel
?ExcelObject{PROP:Deactivate} !Return to the Clarion application
OF ?DeactOLE
?AnyOLEObject{PROP:Deactivate} !Return to the Clarion application
END !CASE FIELD()
END !CASE EVENT0()
END !ACCEPT
BuildSheetData ROUTINE !Use OLE Automation to build spreadsheet
?ExcelObject{PROP:ReportException} = TRUE !Excel will report any errors
?ExcelObject{'Application.Calculation'} = xlManual !turn off auto recalc
LOOP i = 1 TO 3 !Fill Sheet with some values
LOOP j = 1 TO 3
?ExcelObject{'Cells(' & i & ',' & j & ').Value'} = Random(100,900)
END
?ExcelObject{'Cells(4,' & i & ').Value'} = 'Sum'
?ExcelObject{'Cells(5,' & i & ').FormulaR1C1'} = '=SUM(R[-4]C:R[-2]C)'
?ExcelObject{'Cells(6,' & i & ').Value'} = 'Average'
?ExcelObject{'Cells(7,' & i & ').FormulaR1C1'} = '=AVERAGE(R[-6]C:R[-4]C)'
END
!turn auto recalc back on
?ExcelObject{'Application.Calculation'} = xlAutomatic
DISPLAY
MenuEnable ROUTINE !Enable menu items
ENABLE(?ActiveOLE)
ENABLE(?SaveObjectBlob,?GetObject)
SelectOleServer PROCEDURE(OleQ PickQ)
window WINDOW('Choose OLE Server'),AT(,,122,159),CENTER,SYSTEM,GRAY
LIST,AT(11,8,100,120),USE(?List),HVSCROLL, |
FORMAT('146L~Name~@s64@135L~CLSID~@s64@20L~ProgID~@s64@'),FROM(PickQ)
BUTTON('Select'),AT(42,134),USE(?Select)
END
CODE
OPEN(window)
SELECT(?List,1)
ACCEPT
CASE ACCEPTED()
OF ?Select
GET(PickQ,CHOICE(?List))
IF ERRORCODE() THEN STOP(ERROR()) END
POST(EVENT:CloseWindow)
END
END
RETURN(PickQ.ProgID)
Interface Properties
| PROP:Object | Gets the Dispatch interface for the object. (READ ONLY) |
| In VB the toolbar and tree control use the image-list control to show icons in the tree control and on the buttons on the toolbar. To associate an image control with a toolbar, use the following code: | |
| ?toolbar{'ImageList'} = ?imagelist{prop:object} | |
| PROP:SelectInterface | Selects the interface to use with the object. (WRITE ONLY) |
| ?x{PROP:SelectInterface} = 'x.y' | |
| ?x{'z(1)'} = 1 | |
| ?x{'z(2)'} = 2 | |
| has the same meaning as | |
| ?x{'x.y.z(1)'} = 1 | |
| ?x{'x.y.z(2)'} = 2 | |
| PROP:AddRef | Increments the reference count for an interface. (WRITE ONLY) |
| PROP:Release | Decrements the reference count for an interface. (WRITE ONLY) |
Clarion OLE/OCX library and object hierarchies:
At the time of the design and implementation of the Clarion OLE library, the lack of access to secondary objects created by a primary object (example from excel: ExcelUse{'Application.Charts.Add'}), was not considered a problem as there were other ways of accessing the object(ExcelUse {'Application.Charts(Chart1).ChartWizard(' &?ex{'Range(A5:C5)'}&','&xl3DPie&',7,1,0,0,2,,,,)'})
At the time there was only one known instance where this was not the case. This is probably still true today as the OLE standard states that an object implement a collection, must also implement a method for accessing the objects by indexing.
Due to the special case mentioned above, when an object was created by one control and passed onto an other object as a parameter, a method which would be more or less transparent to the user, was implemented.
Calling a method which returns an IDispatchInterface is converted into a special representation (a '`' followed by a number of digits). This special representation is recognized in a couple of places in the OLE library.
The place that you will find most useful is, when the special representation is in the place where an interface could occur in the property syntax it will replace any previous interface in the access of the properties or methods of the object. For example:
x=y{'charts.add()')
y{x&'p(7)'}
where y is an ole object and x is a cstring. This is an example of a method returning an interface and later this interface is used to access a method p with the parameter 7.
In this context a further complication arises form the reference counting used in OLE. Which means that if the object are used more than once it must have it's reference count increased before use.
x=y{'charts.add()')
y{PROP:AddRef}=x
y{x&'p(7)'}
y{x&'p(7)'} ;last use of x