cincom smalltalk™ objectstudio · ♦ form-based services ♦ component client services ♦...

Cincom Smalltalk™

ObjectStudio®

OLE User’s Guide

P40-3805-03

ObjectStudio 8.3

Cincom Smalltalk™ ObjectStudio® OLE User's Guide Publication Number P40-3805-03 © 1988–1999, 2001, 2003, 2005, 2006, 2008–2011 Cincom Systems, Inc. All Rights Reserved CINCOM SYSTEMS, INC. MAKES NO WARRANTY OF ANY KIND WITH REGARD TO THE MATERIAL CONTAINED IN THIS MANUAL, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. The information contained in this manual is subject to change without notice. This manual contains proprietary information that is protected by copyright. All rights are reserved. It may not be photocopied, reproduced, or translated, in whole or in part, without the prior express written consent of Cincom Systems, Inc. See http://www.cincom.com/legal/terms.html for a list of Cincom trademarks and other trademarks that may appear in Cincom product documentation. All other trademarks are trademarks or registered trademarks of their respective companies. Cincom Systems, Inc. 55 Merchant Street Cincinnati, Ohio 45246-3732 USA PHONE: (513) 612-2300 FAX: (513) 612-2000 WORLD WIDE WEB: http://www.cincom.com Attention: Some Cincom products, programs, or services referred to in this publication may not be available in all countries in which Cincom does business. Additionally, some Cincom products, programs, or services may not be available for all operating systems or all product releases. Contact your Cincom representative to be certain the items are available to you.

http://www.cincom.com/legal/terms.html

http://www.cincom.com

Release information for this manual

Cincom Smalltalk™ ObjectStudio® OLE User's Guide, P40-3805-03, is dated February 16, 2011. This document supports Release 8.3 of ObjectStudio.

Cincom Technical Support for ObjectStudio

All customers Web: http://supportweb.cincom.com

USA customers Phone: 1-800-727-3525

Fax: (513) 612-2000 Attn: ObjectStudio Support

Mail: Cincom Systems, Inc. Attn: ObjectStudio Support 55 Merchant Street Cincinnati, OH 45246-3732 USA

Outside of USA All: Visit the support links at http://www.cincom.com to find contact information for your nearest Customer Service Center.

Document description This guide is for developers who want to use the features of Microsoft

® Object

Linking and Embedding (OLE) 2.0. Form items and the OLE Server Object Manager are provided to make it easy to use ObjectStudio

® and OLE.

http://supportweb.cincom.com

http://www.cincom.com

OLE User’s Guide, P40-3805 4 Contents

Contents 1. OLE overview ........................................................................... 7

What is OLE? ............................................................................................... 7 OLE and object-oriented programming ................................................................ 8 Component objects ....................................................................................... 9

Object vocabulary .................................................................................. 10 Objects are packaged into components ........................................................ 10

OLE services in ObjectStudio .......................................................................... 11 Enabling ObjectStudio OLE support ............................................................. 12 Embedding, linking, and visual editing ......................................................... 12 Drag and drop ....................................................................................... 13 OLE custom controls ............................................................................... 13 Compound documents ............................................................................. 14 Component client and server services .......................................................... 14 More about ObjectStudio as a server ............................................................ 15

OLE classes ............................................................................................... 16

2. Embedding, linking, and visual editing .......................................... 18 Introduction .............................................................................................. 18 Containers and sites .................................................................................... 19 Using the Designer to embed and link objects ..................................................... 20

How to embed and link an object ............................................................... 20 Using the Insert Object dialog box .............................................................. 23 Using drag and drop to embed objects ......................................................... 26 Embedding and linking from the Clipboard .................................................... 27 Saving an embedded object ...................................................................... 28

Smalltalk support for embedding and linking ....................................................... 28 Embedding in Smalltalk ........................................................................... 29 FormOLEItem class ................................................................................. 30 FormEmbed class ................................................................................... 33 Form class ........................................................................................... 37 Controller class ..................................................................................... 38

Selecting whether to process OLE data synchronously or asynchronously ..................... 39 OLE event handling ................................................................................ 39 Configuring OLE event handling .................................................................. 40

Visual editing ............................................................................................ 41 Activating and deactivating visual editing ..................................................... 41 Hiding the toolbar and merging menus ......................................................... 42 Controlling size during visual editing ........................................................... 43 Smalltalk support for visual editing ............................................................. 43


3. Working with OLE custom controls ............................................... 44 What is an OLE custom control? ....................................................................... 44

Where to find custom controls ................................................................... 45 How custom controls fit into OLE architecture ................................................ 45

How to use the Designer with custom controls ..................................................... 45 Registering a control ............................................................................... 45 Adding a control to a form ........................................................................ 46 Customizing a control.............................................................................. 47 Setting ambient properties for a container .................................................... 50 Responding to user interaction ................................................................... 53

Smalltalk support for custom controls ............................................................... 55 FormOLEItem class ................................................................................. 55 FormOLEControl class .............................................................................. 56 InterfacePart class ................................................................................. 58 Notes about licensing .............................................................................. 58

4. Working with OLE component client services ................................. 59 Using ObjectStudio as a client ........................................................................ 59

Loading the OLE demo files ....................................................................... 60 Running the OLE demo ............................................................................ 60 How the Automation demo works ............................................................... 62

OLE development overview ............................................................................ 63 Creating an instance of OLEObject .............................................................. 63 Interacting with the OLEObject .................................................................. 64

Using OLE Automation .................................................................................. 66 Mechanics of OLE Automation .................................................................... 66 IDispatch interface ................................................................................. 67 Implementing an Automation Controller ....................................................... 68 Creating an Automation client object .......................................................... 69 Working with an object’s properties ............................................................ 70 Invoking methods ................................................................................... 71 Type conversion .................................................................................... 73

Using Uniform Data Transfer .......................................................................... 75 Creating an OLEDataTransfer object ............................................................ 75 Working with Uniform Data Transfer ............................................................ 76 Setting data ......................................................................................... 76 Getting data ......................................................................................... 76 Working with advises .............................................................................. 77

5. Working with OLE component server services ................................ 78 Using ObjectStudio as a server ........................................................................ 78

Loading the OLE demo server object files ...................................................... 79


Inspecting an OLE object ............................................................................... 80 Starting the demo .................................................................................. 80 Creating an object ................................................................................. 81 Working with the timer server ................................................................... 82

Creating an ObjectStudio component ................................................................ 84 Using the OLE Server Object Manager ............................................................... 85

Opening the OLE Server Object Manager ....................................................... 85 Toolbar and menu .................................................................................. 86

Creating a subclass of OLESrvObject ................................................................. 87 Create OLE Server Object dialog box: Upper portion ........................................ 88 Create OLE Server Object dialog box: Lower portion ........................................ 89

Subclassing interfaces .................................................................................. 90 OLE Server IDataObject interface ............................................................... 91 OLE Server IDispatch interface ................................................................... 93 OLE data types ..................................................................................... 100

Implementing business logic .......................................................................... 101 Preparing to run the server ........................................................................... 102 Creating a simple OLE server ......................................................................... 104

Overview of steps ................................................................................. 104 If you need assistance ............................................................................ 105 Creating an OLE Server class .................................................................... 106 Creating an IDataObject interface class ....................................................... 108 Creating an IDispatch interface class .......................................................... 110 Saving the OLE Server class ...................................................................... 114 Adding code to the IDataObject class .......................................................... 114 Adding code to the OLE Server class ........................................................... 115 Registering the server ............................................................................ 117 Testing the server using ObjectStudio as the client ......................................... 118 Testing the server using a Visual Basic application as the client .......................... 120

6. OCX licensing ........................................................................ 121 Introduction ............................................................................................. 121 OCX custom control modes ........................................................................... 121 ObjectStudio/OCX licensing .......................................................................... 122

Edit-time mode .................................................................................... 122 Run-time mode .................................................................................... 124

Incorporating licensing ................................................................................ 125 Incorporating a run-time license ................................................................ 125 Incorporating run-time and edit-time licenses ............................................... 125

Distribution requirements............................................................................. 126

Index ...................................................................................... 127

OLE User’s Guide, P40-3805 7 Chapter: 1. OLE overview Section: What is OLE?

1. OLE overview What is OLE?

OLE is a collection of operating system services that allow you to include component objects in an application or allow you to package component objects for use in other applications.

ObjectStudio offers the following benefits:

♦ Simplifies the amount of work you need to do to include OLE features in your application

♦ Automates and helps with many of the tasks involved in working with OLE

♦ Frees you from the details of registering components in the OLE Registry, adding and releasing reference counts, working with class factories, and managing memory

Once you learn the basics, you may want to learn more about OLE architecture or learn about how to use OLE with other languages. Some of the advanced projects that you can pursue include:

♦ Using the IDataObject interface with complex C data structures

♦ Adding New OLE interfaces to ObjectStudio

OLE User’s Guide, P40-3805 8 Chapter: 1. OLE overview Section: OLE and object-oriented programming

OLE and object-oriented programming The use of object-oriented programming techniques encourages you to develop modular applications that are reusable and are easy to maintain. However, object-oriented programming alone cannot deliver the full benefits of object technology.

Without operating system tools, objects that exist within one application cannot communicate with objects in another application. For example, you might want an application to communicate with another custom application, a standard off-the-shelf application, or a third-party add-in product.

Windows provides a set of software services that enable interobject communication. These services are the Component Object Model (COM) framework. Microsoft refers to the COM framework and the OLE software services built on top of COM as Object Enabled System Services. The Distributed Component Object Model (DCOM) framework is an extension of COM that enables distributed interobject communication over a network in a reliable, secure, and efficient manner.

Object Enabled System Services and object-oriented programming are complementary. Together, they can enhance productivity for application developers because they extend the benefits of object-oriented programming across all development tools that support OLE.

OLE User’s Guide, P40-3805 9 Chapter: 1. OLE overview Section: Component objects

Component objects OLE uses component objects, which are standalone objects that establish a contract with other objects when they are invoked. DCOM implements the infrastructure to support component objects, and it also creates the contracts for communication.

Component objects support interfaces to communicate with other objects. Each interface is a collection of related functions that can be invoked when you need to interact with the component. The only way to interact with the component is by means of a function in one of the component’s interfaces.

Unlike Smalltalk objects, component objects do not support inheritance. OLE disallows inheritance to increase the integrity of the run-time environment where objects from multiple vendors, multiple releases, and transparent locations must coexist. Because component objects do not inherit from other objects, they are more resilient to changes in a heterogeneous run-time environment.

ObjectStudio supports Smalltalk objects and OLE component objects. ObjectStudio applications can use objects (components) developed in other languages. Hundreds of OLE compliant components and products are available. For example, some OLE components manage electronic payments or provide multimedia capabilities. Other OLE components are standard applications such as spreadsheets and word processors.

You can also use ObjectStudio to create OLE components. ObjectStudio provides an ideal rapid-development environment for creating business object components. Once you create a component, you can integrate it into applications that you build with tools such as C++, Microsoft Visual Basic, and Visual Basic for Applications (VBA). VBA is used in Microsoft products such as Excel and Word.

OLE User’s Guide, P40-3805 10 Chapter: 1. OLE overview Section: Component objects

Object vocabulary An OLE object is similar to a Smalltalk object. The following table describes how Smalltalk and OLE (or DCOM) terms relate:

Feature/Term Smalltalk term DCOM term

Class Class Class Object

Instance/Object Instance/Object Instance (Provided via IClassFactory or other instance creation interfaces)

Object’s data Instance variable Property (Provided via IDispatch interface calls to Properties)

Object’s behavior Method Function when referring to Interfaces. Method when referring to IDispatch method calls.

Notifications Event Event (Sometimes provided by the IConnectionPoint interface)

Objects are packaged into components A component is an implementation that contains an OLE object and resides in a dynamic link library (DLL) or executable file. The component can exist or execute anywhere: within the same application, within the same process, locally on the same machine, and remotely across a network. The DCOM framework connects a client to a server and then gets out of the way to allow direct communication.

OLE User’s Guide, P40-3805 11 Chapter: 1. OLE overview Section: OLE services in ObjectStudio

OLE services in ObjectStudio In ObjectStudio, the OLE services fall into the following categories:

♦ Form-based services

♦ Component client services

♦ Component server services

Form-based services are implemented within the framework of the ObjectStudio graphical user interface (GUI) class hierarchy. They allow you to work with OLE objects from the Designer, much as you work with other form items. You can also write Smalltalk code that works with these services. The form-based services are:

♦ Embedding, linking, and visual editing

♦ Drag and drop

♦ OLE custom controls

To support component services, ObjectStudio provides a Smalltalk class framework. When you use the framework and the visual tools that support it, the tasks of creating components and working with them are simplified greatly. ObjectStudio also provides direct access to OLE interfaces so that you can take advantage of all of the flexibility that OLE offers.

OLE User’s Guide, P40-3805 12

Enabling ObjectStudio OLE support Enable ObjectStudio OLE support by loading the OLE loadable application. To do this, select OLE from the Applications dialog box. If OLE support is not loaded, selecting any menu items that use OLE will result in a warning message box that states “OLE component is not loaded.”

Embedding, linking, and visual editing Embedding and linking make data from one program accessible to other programs.

When you embed an object, the system copies and stores its data once and breaks the connection between the original object and the copy. When you link an object, the system maintains the connection between the original object and the linked object. The system updates the linked object whenever the original object changes.

Visual editing is the ability to change a linked or embedded object without having to leave the application in which you are working. With visual editing, when the user double-clicks an OLE object, the system replaces or merges the application’s menu and toolbar with those appropriate to the object.

In some contexts, visual editing is called in-place activation.

For more information about embedding, linking, and visual editing, see “Embedding, linking, and visual editing” on page 12.

Example. You may want to view or use data from an Excel spreadsheet in an ObjectStudio application. Without OLE, you would need to leave the ObjectStudio application and start Excel.

With OLE, you can embed or link the spreadsheet in an ObjectStudio form. You can view the spreadsheet’s data whenever the form is visible. With a few keystrokes, you can set up the embedding so that whenever the user double-clicks the spreadsheet, ObjectStudio menus and toolbars are replaced with those of Excel. The user can interact with Excel directly from the ObjectStudio form. To restore ObjectStudio menus and toolbars, the user simply clicks outside the spreadsheet.

Chapter: 1. OLE overview Section: OLE services in ObjectStudio


Drag and drop The drag and drop facility allows you to use the mouse to drag an OLE object within an application or from one application to another. Drag and drop is similar to the more familiar cut and paste, but it does not use the Clipboard.

Specifically, you can move an embedded object from ObjectStudio to another application, or you can move an object onto an ObjectStudio form. You can move the object or move a copy of it.

For more information about drag and drop, see “Using drag and drop to embed objects” on page 26.

Example. If you create an ObjectStudio form with an embedded Excel spreadsheet, you then can drag the spreadsheet from the ObjectStudio form and drop it in a Word document. The spreadsheet becomes an embedded object within the Word document.

OLE custom controls OLE custom controls (informally known as OCXs because their file extension is .ocx) are add-in controls that are similar to Visual Basic controls (VBXs). OLE custom controls are useful because they can be used by many different types of applications, not just Visual Basic.

OLE custom controls provide a standard mechanism for adding third-party products to OLE-compliant applications. Think of them as an easy way to plug units of functionality into an application.

Available OLE custom controls range from packages of GUI controls, such as packages of buttons and list boxes, to functional units, such as multimedia, telephony, imaging, and numerical analysis. For more information about custom controls, see “What is an OLE custom control?” on page 44.

Example. Consider an ObjectStudio application that might benefit from a three-dimensional display of data. If an OLE custom control exists that provides three-dimensional business graphing and charting capabilities, you can include it in your application. You can even use the ObjectStudio Designer to include it. Once it is included in the application, you can treat it much as you treat any other form item.


Compound documents Compound documents are documents that store multiple types of data in a single file. For example, a compound file can include spreadsheets, documents, video clips, and voice clips all in one file.

Compound documents can be structured like entire folders. They contain storages, which are analogous to folders, and streams, which are analogous to files.

ObjectStudio does not use compound documents. ObjectStudio uses files that contain only one type of data—code. Nevertheless, ObjectStudio does allow you to create and write to compound documents.

Component client and server services When you use OLE to integrate two applications, one application requests the services of the other. In OLE terms, the requesting application is the client, and the application that provides the service is the server.

OLE provides the following functionality to support component integration:

♦ Automation. Automation allows you to invoke the features of one program from another program. The invocation can happen behind the scenes and without user involvement. In more technical terms, Automation allows you to programmatically call the application programming interface (API) of a server.

For example, the user of an ObjectStudio application can press a button that causes ObjectStudio to invoke Word to generate a form letter. The application developer can design this activity so that the user is not even aware that Word is activated.

In this example, ObjectStudio is the Automation client, and Word is the Automation server. In other cases, ObjectStudio can also act as an Automation server.

Chapter: 1. OLE overview Section: OLE services in ObjectStudio


♦ Uniform Data Transfer. Uniform Data Transfer enhances the Windows Clipboard facility. It enables applications to retrieve and update data from other applications.

For example, an ObjectStudio application can display the result of a numerical calculation performed by the Windows Calculator. The ObjectStudio application can use notification services to update itself whenever the calculation changes.

ObjectStudio is the Data Transfer client and the Windows Calculator is the Data Transfer server. ObjectStudio can also act as a Data Transfer server. For example, ObjectStudio can provide data that the calculator uses to perform arithmetic operations.

♦ Structured Storage. (Supported only when ObjectStudio is a client.) OLE uses Structured Storage to manage OLE compound documents, which are described in “Compound documents” on page 14. ObjectStudio supports Structured Storage when ObjectStudio is a client but not when ObjectStudio is a server.

Through Structured Storage, ObjectStudio allows you to create and destroy storages and streams and write to and read from streams.

Each service provides one or more interfaces, which are sets of related functions that you can use to interact with the component.

For more information about component client services, see “Using ObjectStudio as a client” on page 59. For more information about component server services, see “Using ObjectStudio as a server” on page 78.

More about ObjectStudio as a server An ObjectStudio OLE Server component can support multiple client applications simultaneously. In addition, multiple ObjectStudio OLE Server components can run simultaneously.

Example. Consider an ObjectStudio OLE Server component that adjusts insurance claims. A Visual Basic application, a C++ application, and Excel can all request services simultaneously from that server component.

OLE User’s Guide, P40-3805 16 Chapter: 1. OLE overview Section: OLE classes

OLE classes You can use the Class Browser to familiarize yourself with the ObjectStudio classes that relate to OLE. For more information about each of the OLE-related classes, refer to the ObjectStudio Class Reference Manual, P40-3801.

To find OLE-related classes in the Class Browser, use the following starting points; then look through the subclasses:

♦ Linking, embedding, and visual editing. Class FormEmbed is a subclass of FormItem.

♦ Drag and drop. Drag and drop is included in Class FormEmbed.

♦ Custom controls. Look at the following classes:

- FormOLEControl is a subclass of FormEmbed.

- AmbientProperty is a subclass of Object.

♦ Client components. Look at the following classes:

- OLEObject is a subclass of Object and represents an OLEObject within ObjectStudio.

- OLEDataTransfer is a high-level class that helps you work with Uniform Data Transfer. It is a wrapper for an instance of class IDataObject and provides an interface that is easier to use.

- OLEDispatcher and OLEStaticDispatcher are high-level classes that help you work with OLE Automation. These classes are wrappers for the IDispatch class.

- IStorage and IStream provide support for OLE Structured Storage within ObjectStudio.

OLE User’s Guide, P40-3805 17 Chapter: 1. OLE overview Section: OLE classes

♦ Server components. OLESrvObject and OLESrvInterface are subclasses of Object. Also, browse through the subclasses of ClassTemplate, which is a subclass of Object.

♦ OLE interfaces. These classes include:

- Automation (AutomationValue is a subclass of Object.)

- OLEInterface (This class is a subclass of Object. There are a number of other OLE-related classes that are subclasses of Object. Change the Class Browser view to hierarchical and locate the subclasses of Object that start with O.)

- Templates (Browse through the subclasses of ClassTemplate, which is a subclass of Object.)

♦ OLE structures and external libraries. These classes include:

- OLE structures (Browse through the subclasses of Structure, which is a subclass of ExternalAddress, which is a subclass of Object.)

- OLE DLL Interface Classes (Browse the subclasses of ExternalLibrary, which is a subclass of Object.)

Once you are familiar with the purpose, contents, and interactions of these classes, you can extend the ObjectStudio OLE support if needed.


2. Embedding, linking, and visual editing Introduction

This chapter describes how to use the embedding, linking, and visual editing features of OLE.

ObjectStudio allows you to use the Designer to accomplish much of this work. You can also write Smalltalk code to accomplish the same tasks.

Before you can use OLE with ObjectStudio, you must enable ObjectStudio OLE support. See “Enabling ObjectStudio OLE support” on page 12.

Chapter: 2. Embedding, linking, and visual editing Section: Introduction


Containers and sites You should know about these important OLE terms before you read this chapter:

♦ OLE container. A form on which you place the object. A container can have properties that affect the object.

♦ OLE site. An object that holds the embedded or linked object on the container. A site can exist independently of an embedded object, but an embedded object cannot exist on a form without being on a site.

The following figure shows an example of a container, a site, and an embedded object (an Excel worksheet):

In Smalltalk, the OLE site is an instance of class FormEmbed.

When you add an embedded object to a form—for example, by using the loadDocumentName: method or by using drag and drop—one of two situations can occur:

♦ A site (an instance of FormEmbed) can already exist on the form. In this case, ObjectStudio refreshes the site with the object and, optionally, its contents.

♦ A site does not already exist on the form. In this case, ObjectStudio dynamically creates an instance of FormEmbed with the default settings. If the original settings for the object’s site are different from the default settings, the appearance of the object can change.

Chapter: 2. Embedding, linking, and visual editing Section: Containers and sites


Using the Designer to embed and link objects Embedding is the act of including an object in a container (in ObjectStudio terms, a form). The object can have associated data; for example, a bitmap or spreadsheet data. ObjectStudio manages and saves the site information for an object that is embedded on an ObjectStudio form.

Linking is similar to embedding, except that the data resides with the original object. If the original object changes, the linked object is also updated.

How to embed and link an object This section describes how to use the Form OLE Item Options dialog box to embed and link an object.

To open the Form OLE Item Options dialog box:

1. Select FormItem > New Item from the Designer menu to display the New Item dialog box.

2. Select the OLE Item form item from the New Item dialog box and place it on the form. The OLE Item form item is a site for an embedded or linked OLE object.

3. Double-click the OLE Item to display the Form OLE Item Options dialog box, as shown here:

Chapter: 2. Embedding, linking, and visual editing Section: Using the Designer to embed and link objects

OLE User’s Guide, P40-3805 21 Chapter: 2. Embedding, linking, and visual editing Section: Using the Designer to embed and link objects

Two ways to create an embedded object. ObjectStudio provides the following two ways to create an embedded object from the Form OLE Item Options dialog box:

♦ Click the Browse button to display the Insert Object dialog box, which contains options for embedding and linking the object.

♦ Enter the Object Type and Class ID directly in the Form OLE Item Options dialog box without using the Insert Object dialog box.

One reason to interact directly with the Form OLE Item Options dialog box is to embed an object that is not registered on your system. Options on the Form OLE Item Options dialog box are described in the following list. For more information about registering an object, see Register the component or “Registering the server” on page 117.

♦ Item Name. The Item Name is the site in which to embed or link the OLE object.

♦ Server Options. Server Options determine the areas of responsibility for managing the OLE object. The following table describes the Server Options:

Option Description

Initial Server Size

The OLE server determines the size of the object when you embed the object, when you open its form, or when you visually edit the object. If this option is not checked, you determine the size by setting it in the Designer.

Move The user can use the mouse to move the object when visual editing is not in effect. Note: Do not use this option with the form item options #HMove or #VMove.

In-place Menu

When the user initiates visual editing (by double-clicking the object), the object’s application menus can merge with or replace the form’s menus.

Server Size During visual editing, if the user updates the object’s data, the server can reset the size of the object. If this option is not checked, the size is static.

Resize The user can use the mouse to resize the object when visual editing is not in effect. Do not use this option with the form item options #HResize or #VResize.

Display as Icon

Instead of displaying the object, display an icon that represents the object. Visual editing occurs in a separate window from the ObjectStudio form.


♦ Source Type. The Source Type options determine the type of OLE item to embed or link. The following table describes the Source Type options:

Option Allows you to

Create New Item Embed an OLE item with no user data.

Create From File Embed the OLE item specified in the Filename entry field with user data.

Create From File and Linked Link the OLE item specified in the Filename entry field with user data.

♦ Filename. The Filename entry field appears if you select the Create From File or the Create From File and Linked radio button. You can enter the pathname of the file that you want to embed or link. You can also click Browse to display the Insert Object dialog box. For more information about the Insert Object dialog box, see “Using the Insert Object dialog box” on page 23.

♦ Object Type. The Object Type indicates the type of object that you are embedding or linking. It is a user-readable field in which you can enter an object type, or it is filled in automatically when you close the Insert Object dialog box.

♦ Class ID. The Class ID is the unique ID assigned to the OLE object. If the object is registered on your operating system, the system fills in the Class ID for you. If you are embedding an object that is not registered, you can find the Class ID in the documentation that comes with the object.


Using the Insert Object dialog box This section describes how to embed or link an OLE item into an OLE Item site.

You work with the Insert Object dialog box to embed or link an OLE item into an OLE Item site. To display the dialog box, click Browse on the Form OLE Item Options dialog box. The Insert Object dialog box appears, as shown here:



Embedding a new OLE object This section describes how to embed a new OLE object into an OLE Item site. A new OLE object contains no user data. An empty spreadsheet or a new Word document is an example of a new OLE object.

To embed a new OLE object into an OLE Item site:

1. Select the Create New radio button on the Insert Object dialog box.

2. Select the type of object to create from the Object Type list box.

3. Check the Display As Icon check box if you want the OLE item to appear as an icon.

The Results topic box describes the object you selected and show you what the icon looks like.

4. Click OK to return to the Form OLE Item Options dialog box.

5. Note that ObjectStudio fills in fields on the Form OLE Item Options dialog box.

6. Click OK on the Form OLE Item Options dialog box to return to the Designer.

7. Save and test your work.


Embedding an existing OLE object This section describes how to embed an existing OLE object into an OLE Item site. An existing OLE object contains user data. Examples of existing OLE objects are a spreadsheet that contains equations and data, or a Word document that contains text.

To embed an existing OLE object into an OLE Item site:

1. Select the Create from File radio button on the Insert Object dialog box.

The Insert Object dialog box appears:


2. Click Browse to display the Browse dialog box.

3. From the Browse dialog box, select the file to embed.

4. Click OK to return to the Insert Object dialog box.

5. Click OK on the Insert Option dialog box to return to the Form OLE Item Options dialog box.

Note that ObjectStudio fills in some of the fields on the Form OLE Item Options dialog box.

6. Click OK on the Form OLE Item Options box to return to Designer.


You also can do the previous procedure from the Form OLE Item Options dialog box by completing the Object Type and Class ID fields.


Linking an existing OLE object This section describes how to link an existing OLE object to an OLE Item site. The linked object is updated when the original changes.

To link an existing OLE object to an OLE Item site:

1. Select the Create from File radio button on the Insert Object dialog box.

2. Select the Link check box.

3. Click Browse to display the Browse dialog box.

4. From the Browse dialog box, select the file that you want to link.

5. Click OK on the Insert Option dialog box to return to the Form OLE Item Options dialog box.

Note that ObjectStudio fills in some of the fields on the Form OLE Item Options dialog box.

6. Click OK on the Form OLE Item Options dialog box to return to the Designer.


Using drag and drop to embed objects Use drag and drop as a visual shortcut to embed an object. You can drag and drop embedded objects or even selected regions of data. You can drag an object either from or to ObjectStudio.

To drag and drop:

1. Select the object (or portion of data) that you want to move.

2. Press mouse button 1 and drag the object to the location where you want to move the object.

Also, you can hold down the CTRL key as you drag the object to copy it.

3. Release the mouse button.

The object (or a copy of it) appears where you release the mouse button. If you drag and drop onto a form in the Designer, you may need to test the interface (select File > Test Interface from the Designer menu) to see the object.



Embedding and linking from the Clipboard You can embed or link by pasting the contents of the Clipboard during application run time. You can perform the following types of paste:

♦ Paste. The Paste option copies the contents of the Clipboard to the form.

♦ Paste Link. The Paste Link option copies the contents of the Clipboard to the form but retains a link to the original item. When the original item changes, the item that you linked also changes.

To set up a form to allow pasting, supply some mechanism that allows the user to paste. For example, create a menu item, a button, a mnemonic, or an accelerator that initiates a paste action.

Send one or both of the following messages:

♦ canPaste:. The canPaste: message is a class method in class FormEmbed and returns a Boolean value. If it returns true, then there is something on the Clipboard, and it is available for pasting.

The parameter is a Boolean value that causes the method to test whether there is an item on the Clipboard that is available for pasting and linking.

♦ onEditPaste: link: useDialog:. The onEditPaste: link: useDialog: message is an instance method in class Form. It does the paste action where:

- Parameter 1 is the site (an instance of class FormEmbed) in which to paste the contents of the Clipboard.

- Parameter 2 is a Boolean value. When it is true, the action is a paste and a link. When it is false, the action is a paste.

- Parameter 3 is a Boolean value. If it is true, ObjectStudio displays the standard Microsoft Paste Special dialog box. If it is false, ObjectStudio does not display the dialog box.


Saving an embedded object When you create an embedded object, you need to save the embedded object with the saveDocumentName: method. The method saves all of the OLE objects that are embedded on a form. It does not save the embed sites, but it does save the embedded object’s user data.

For example, you can create an embedded drawport on a form in the Designer. In test mode, you draw on the drawport. In edit mode, save your Designer work with the saveDocumentName: method. ObjectStudio saves all data about the form with the new user data in embedded objects. As a result, the next time you display the form with the drawport, the drawings you added are included.

It is the programmer’s responsibility to save an embedded object’s data explicitly. Otherwise, the data that a user adds last, during the time that the form is open, is erased when the form is closed.

Smalltalk support for embedding and linking To support embedding and linking, Smalltalk provides several classes in the following object hierarchy:

Object FormItem FormOLEItem FormEmbed Form Controller

The following sections describe the variables and methods from the classes that you are most likely to use when you write code to work with linking and embedding.

Chapter: 2. Embedding, linking, and visual editing Section: Smalltalk support for embedding and linking

OLE User’s Guide, P40-3805 29 Chapter: 2. Embedding, linking, and visual editing Section: Smalltalk support for embedding and linking

Embedding in Smalltalk This section describes how to create an embedded item programmatically.

To create an embedded item programmatically:

1. Create an instance of FormEmbed, which creates a site on the form; for example:

myEmbed := FormEmbed newRect: rect options: options form: form.

2. Send the serverOptions: message with an array of symbols; for example:

myEmbed serverOptions: {#InitialServerSize #InPlaceMenu}.

3. Insert an OLE object into the FormEmbed site; for example:

myEmbed insertDirectProgram: programName

where:

programName is either a string or a user’s Long Type Name.

You also can do the following to insert an OLE object into the FormEmbed site:

myEmbed insertDirect: type fileId: fileOrClassIdOrProgramId handle: iconHandle

where:

type is one of the following symbols:

♦ #‘Create New Item’

♦ #‘Create From File’

♦ #‘Create From File and Linked’

fileOrClassIdOrProgramId is a string containing a pathname, a classId, or programId.

iconHandle is either an instance of PMHandle that contains a handle to the object’s icon or nil for the default.


FormOLEItem class The FormOLEItem class is an abstract class from which the FormEmbed class inherits functionality.

Instance variables Following are the instance variables in class FormOLEItem:

♦ cCntrItem. The cCntrItem instance variable is a handle to the embedded object or is nil if no OLE object is embedded.

♦ objectVerbs. The objectVerbs instance variable is an array of symbols that corresponds to the verbs to which the objects respond. The description of the doVerb: instance method (in the following section) lists the possible verbs.

♦ objectVerbsDict. The objectVerbsDict instance variable is a dictionary of the verbs to which the object responds. Each key is the name of a verb. The values are IDs that the system uses internally.


Instance methods Following are the instance methods in class FormOLEItem:

♦ activate:. The activate: instance method initiates or stops activation of the object without involving the object’s user interface. The parameter is a Boolean value. If the value is true, activation of the object is initiated. If the value is false, the activation is stopped.

♦ activateUI:. The activateUI: instance method initiates or stops visual activation of the object. The parameter is a Boolean value: true initiates visual editing and false stops it.

♦ close. The close instance method deletes the OLE object from its container and frees system resources associated with the OLE object.

♦ doVerb:. The doVerb: instance method performs one of the OLE object’s verbs. The parameter is a symbol (the verb to perform). Possible values are:

#OLEIVERB_PRIMARY #OLEIVERB_SHOW #OLEIVERB_OPEN #OLEIVERB_HIDE #OLEIVERB_UIACTIVATE #OLEIVERB_INPLACEACTIVATE #OLEIVERB_DISCARDUNDOSTATE

♦ oleFileId:. The oleFileId: instance method returns an OLE class ID string that uniquely identifies the OLE object to the system or returns a file name if the object was created from a file.

♦ oleMiscFlag:. The oleMiscFlag: instance method returns an integer that represents the OLE object’s flags. A flag represents a protocol that the object supports or an object’s state. For example, one flag is OLE_misc_invisible_at_runtime, which means that the OLE object is not visible to the user. Each flag has an associated integer value. The flags are defined in the OLE_Constants pool dictionary.

Flags are for advanced use only. For more information about flags, refer to the Microsoft OLE Control Developer Kit, User Guide and Reference, Volume Six.



♦ oleUsername:. The oleUsername: instance method returns a readable string (the object’s long name) that describes the object or returns nil if the object was created from a file.

♦ onActivate:. The onActivate: instance method notifies the receiver when the OLE object is activated without involving the object’s user interface. It allows you to instruct the system to perform certain actions when visual editing takes place. The parameter is a Boolean value. If it is true, the object is being activated. If it is false, the object is being deactivated.

♦ onActivateUI:. The onActivateUI: instance method notifies the receiver when the OLE object is UI activated (the activateUI: method executes, or the user starts visual editing on the object and the object responds by changing the UI). It allows you to instruct the system to perform certain actions when an in-place activation with UI changes occurs. The parameter is a Boolean value. If it is true, the object is being activated. If it is false, the object is being deactivated.


FormEmbed class Each instance of FormEmbed represents an embed site, which can have an embedded or linked object associated with it.

Class methods Following is the one class method available in class FormEmbed:

♦ defaultOptions. The defaultOptions class method returns the default server options as an array of symbols. If a programmer alters the array, the return value may not accurately reflect the default settings. ObjectStudio uses the default options when an OLE item is created dynamically.

Instance methods Following are the instance methods in class FormEmbed:

♦ cCopyToClipboard. The cCopyToClipboard instance method copies the OLE object to the Clipboard.

♦ cGetIconicMetafile. The cGetIconicMetafile instance method returns an instance of class PMHandle that represents an icon handle to the object. Before exiting the session, you must send the message deleteMetafilePict to the icon handle.

♦ cGetType. The cGetType instance method returns one of the following integers indicating how the object was created:

- 0 = Unknown

- 1 = Link

- 2 = Embedded

- 3 = Static


♦ cGetUserType:. The cGetUserType: instance method returns a readable string describing the OLE object. The parameter, which is an integer, determines the type of data to return. The parameter is one of the following:

- 1 = Return the OLE object’s long name

- 2 = Return the OLE object’s short name

- 3 = Return the application name

♦ createDefaultInPlaceMenu. The createDefaultInPlaceMenu instance method allows you to customize the menu that is displayed during visual editing.

♦ cSetSelection. The cSetSelection instance method makes the OLE object the currently selected object.

♦ getDrawAspect. The getDrawAspect instance method returns a symbol that indicates how the OLE object is drawn.

♦ insertDirect:fileId. The insertDirect:fileId: instance method inserts an OLE object into a site. The parameters are:

- Parameter 1 is one of the following symbols: ‘#Create New Item’ ‘#Create From File’ ‘#Create From File and Linked’

- Parameter 2 is either a string containing a pathname or is a classId.

♦ insertDirect:fileId:handle:. The insertDirect:fileId:handle: instance method inserts an OLE object into a site. The parameters are:

- Parameter 1 is one of the following symbols: ‘#Create New Item’ ‘#Create From File’ ‘#Create From File and Linked’

- Parameter 2 is either a string containing a pathname or is a classId or programId.

- Parameter 3 is an instance of PMHandle, containing a handle to the object’s icon or is nil for the default.


♦ insertDirectProgram:. The insertDirectProgram: instance method inserts a new OLE object into a site. The parameter is the name of the application that implements the object, as a string.

♦ onChange:param:. The onChange:param: instance method notifies the receiver that it has changed. The first parameter is the type of change, as an integer. The second parameter depends on the first parameter.

♦ onDrop. The onDrop instance method notifies the receiver when the user uses drag and drop to create an embedded object on an ObjectStudio form. It allows you to specify the actions to take when drag and drop occurs.

♦ onInsert: The onInsert: instance method notifies the receiver when it is being inserted. The parameter is the type of embedding that occurs:

- 0 = the object is a new item

- 1 = the object is embedded from a file

- 2 = the object is linked from a file

This method sends an event to the controller item and to the controller. Do not subclass this method.

♦ onPaste. The onPaste instance method notifies the receiver when the user pastes an object from the Clipboard onto an ObjectStudio form. It allows you to specify the actions to take when a paste occurs.

♦ oleMetaPict. The oleMetaPict instance method returns a handle (or nil) that points to the default file name to use when displaying the object as an icon. When the method returns a value other than nil, the value overrides any OLE server rendering of the object. If #DisplayAsIcon is set in serverOptions, then the value that this method returns is overridden.

♦ oleMetaPict:. The oleMetaPict: instance method sets the file name to use when displaying the OLE object as an icon. For more information, see the preceding description of oleMetaPict.

♦ open. The open instance method creates the OLE object.



♦ remove. The remove instance method deletes the OLE object and its site.

♦ serverOptions. The serverOptions instance method returns an array of symbols representing features of the OLE server.

♦ serverOptions:. The serverOptions: instance method sets features of the OLE server. The parameter is an array that can contain any of the symbols described in the following table:

Symbol Meaning if included in the array

#InitialServerSize The OLE server determines the size of the object when you embed the object, when you open its form, or when you visually edit the object. If this option is not in the array, you indicate the size by setting it in the Designer.

#ServerSize If the user updates the object during visual editing, the server can reset the size of the object. If this option is not in the array, the size is static.

#Move The user can use the mouse to move the object when visual editing is not in effect. Do not use this option with the form item options #HMove or #VMove.

#Resize The user can use the mouse to resize the object when visual editing is not in effect. Do not use this option with the form item options #HResize or #VResize.

#InPlaceMenu When the user initiates visual editing (by double-clicking the object), the object’s application menus can merge with or replace the form’s menus.

#DisplayAsIcon Instead of displaying the object, display an icon that represents the object. Visual editing occurs in a window different from the ObjectStudio form.

♦ temporary. The temporary instance method returns a Boolean value that indicates whether the embedded object is deleted when the user closes the form.

♦ temporary:. The temporary: instance method indicates whether to delete the embedded object when the user closes the form. The parameter is a Boolean value. If it is true, ObjectStudio deletes the FormEmbed object when the user closes the form. If it is false, ObjectStudio performs the default FormItem behavior.


Form class The Form class provides methods that help you work with embedded objects.

Instance methods Following are the instance methods in class Form:

♦ createDefaultInPlaceMenuAt:. The instance method createDefaultInPlaceMenuAt: allows you to specify how the form’s menu changes when visual editing starts. By default, the object’s application menu is placed after the form’s menu. The parameter specifies the position of the form’s menu where the application’s menu should be inserted.

See also the createDefaultInPlaceMenuForm: method shown in “Merging menus during in-place activation” on page 43.

♦ loadDocumentName:. The loadDocumentName: instance method loads embedded objects onto the form from the file named in the parameter. (The file is created with the saveDocumentName: method.) It does not load the object’s site.

♦ saveDocumentName:. The saveDocumentName: instance method saves the objects that are embedded onto a form in the file named in the parameter. It does not save the object’s site.

It is the responsibility of the programmer to save the contents of embedded objects. For more information about saving embedded objects, see “Saving an embedded object” on page 28.



Controller class The Controller class provides methods that help you work with embedded objects.

Instance methods Following are the instance methods in class Controller:

♦ onDropDataObj:x:y:form:. The onDropDataObj:x:y:form: instance method returns a Boolean value indicating whether the controller accepts drag and drop objects. The parameters are:

- Parameter 1 is a handle to the object being dropped.

- Parameter 2 is the x position of the drop.

- Parameter 3 is the y position of the drop.

- Parameter 4 is the form where the object is being dropped.

♦ getFEmbedHandle:form:. The getFEmbedHandle:form: instance method is called whenever an embedded object is created dynamically (for example, by drag and drop). The parameters are:

- Parameter 1 is a handle to the item being embedded.

- Parameter 2 is the name of the form where the object is being embedded.

OLE User’s Guide, P40-3805 39 Chapter: 2. Embedding, linking, and visual editing Section: Selecting whether to process OLE data synchronously or asynchronously

Selecting whether to process OLE data synchronously or asynchronously

OLE event handling OLE objects perform their processing by reacting to events from the system. In ObjectStudio, the ObjectStudio virtual machine forwards events from the OLE object into the Smalltalk image, for processing by Smalltalk. The OLE event handling can perform its processing in two different ways:

Synchronously. The OLE event handling sends a message to ObjectStudio and waits until the Smalltalk processing is completed. This approach would be useful if the OLE object needed Smalltalk to return an answer to an event before the OLE object could continue.

Asynchronously. The OLE event handling sends a message to ObjectStudio and continues running while the Smalltalk processing is completed.

The controller determines which way the processing is performed.


Configuring OLE event handling As of ObjectStudio 7.0, the controller can configure OLE event handling in the following two ways:

By event

By controller

The following occurs in OLE event handling:

1. Smalltalk sends #processSynchronouslyForEventName: to the FormOLEControl just before sending #processEvent:args:.

2. FormOLEControl>>processSynchronouslyForEventName: forwards the question of how to proceed to Controller>>processSynchronouslyForOLEEventName:.

3. Controller>>processSynchronouslyForOLEEventName: can answer either of the following:

true

false

Modifying or overriding Controller>>processSynchronouslyForOLEEventName: - You can perform either of the following steps:

- Modify this method in order to always answer true, in which case OLE event handling is always performed synchronously.

- Override this method in your own controller subclasses and check the event name to control the behavior by event.

4. Depending on the answer received from Controller>>processSynchronouslyForOLEEventName:, the FormOLEControl can answer either of the following:

true—OLE event handling waits for FormOLEControl>>processEvent:args: to complete before continuing.

false—OLE event handling sends #processEvent:args: asynchronously (on the idle queue).

Chapter: 2. Embedding, linking, and visual editing Section: Selecting whether to process OLE data synchronously or asynchronously

OLE User’s Guide, P40-3805 41 Chapter: 2. Embedding, linking, and visual editing Section: Visual editing

Visual editing This section describes visual editing, also called in-place activation. Visual editing is a facility that enables you to work with embedded objects.

Visual editing is an OLE feature that allows you to work directly with an object that is embedded in an ObjectStudio form. You can work with the embedded object as if you are working in the original application.

Once you finish visual editing, you can return the menus and toolbars of the ObjectStudio forms to their state prior to the visual editing session.

Activating and deactivating visual editing To start visual editing:

1. Select File > Test interface from the Designer menu, or you can run the application.

2. Double-click the embedded object.

The Designer places a hatched border around the object and changes the menus and toolbars as described previously.

To stop visual editing, click outside the object. The Designer restores the form to its state prior to the visual editing session.


Hiding the toolbar and merging menus When you initiate visual editing, the menus and toolbars of the embedded application can merge with or can replace those of the ObjectStudio form.

Hiding the toolbar When you create a toolbar, you can determine if the embedded application’s toolbar replaces the toolbar of the application or if both toolbars are displayed.

To hide the application’s toolbar:

1. Select Tools > Toolbar from the Designer menu. 2. Select the toolbar that you want to hide from the Toolbars for Form list

box. 3. Click Edit on the Toolbars for Form dialog box. The Toolbar Options for Form dialog box appears. 4. Click Options. The Form Toolbar Misc Options dialog box appears, as shown here:

5. Check the Hidden During OLE In-place Activation check box. 6. Click OK to close the Form Toolbar Misc Options dialog box. 7. Click OK to close the Toolbar Options for Form dialog box.

Chapter: 2. Embedding, linking, and visual editing Section: Visual editing

OLE User’s Guide, P40-3805 43 Chapter: 2. Embedding, linking, and visual editing Section: Visual editing

Merging menus during in-place activation You can merge the menu of your application with the embedded application by subclassing the following method in your own controller:

Controller>>createDefaultInPlaceMenuForm:

For example, your application has the File, Edit, View, and Window menus. During visual editing, you want to replace Edit and View with the embedded object’s menu. The following code shows how you could merge the two menus:

createDefaultInPlaceMenuForm: aForm

aForm createDefaultInPlaceMenuAt: 2 remove: {#Edit #View}.

!"End createDefaultInPlaceMenuForm:"

Menus of the mainForm for a MDIWindowsController can use the menu of the child form. Therefore, you must specify the menus of the child when you specify the menus to remove.

Controlling size during visual editing Recall that when the ServerSize option is set, the server can reset the size of the object if user actions might cause the size of the object to change. For example, if the user adds cells to an embedded Excel spreadsheet, the server can make the embedded spreadsheet larger if the ServerSize option is set.

In the same situation, if the ServerSize option is not set, the size of the spreadsheet remains static during visual editing regardless of user actions.

Smalltalk support for visual editing ObjectStudio provides Smalltalk support for visual editing through the FormEmbed and the Form class. For more information, see “Smalltalk support for embedding and linking” on page 28.

OLE User’s Guide, P40-3805 44 Chapter: 3. Working with OLE custom controls Section: What is an OLE custom control?

3. Working with OLE custom controls What is an OLE custom control?

An OLE custom control is a discrete unit of functionality that you can plug into an application. The control is independent of where it resides. Software vendors distribute OLE custom controls as reusable pieces of software. One common use of custom controls is as supplemental form items available to the application. A control can be manipulated programmatically, which allows another piece of code to use it to perform specific tasks.

OLE custom controls are informally known as OCXs because they are packaged in files with a .ocx file extension. It is easy to use them from ObjectStudio because the Designer allows you to work with them much as you work with other form items.

A custom control has the following features:

♦ Properties. Properties describe the state of the custom control. They are analogous to instance variables in Smalltalk. Most custom controls are packaged with property sheets that allow you to customize the control.

♦ Methods. Methods are functions implemented in the control and can be called from the controlling program to perform an action. As in Smalltalk, a method is an operation that you can call.

♦ Events. Events are external actions that happen to a control and cause the control to call an event handler (for example, a mouse click or a timer elapsed event). As in Smalltalk, an event is a notification message that announces a change in the state of the control.

Most custom controls are packaged with a Help file that lists the properties, methods, and events that the custom control supports.

OLE User’s Guide, P40-3805 45 Chapter: 3. Working with OLE custom controls Section: How to use the Designer with custom controls

Where to find custom controls Many companies, including Microsoft, produce custom controls. One of the easiest ways to find custom controls is to use the World Wide Web. If you use your favorite search engine to search for the string OCX, you will probably find a mix of shareware and commercial sources.

How custom controls fit into OLE architecture In OLE terms, a custom control is an OLE compound document that supports visual editing. Each custom control file (OCX) is a DLL. It is more efficient to communicate with OCX files than it is to communicate with OLE servers (which are executable files).

How to use the Designer with custom controls This section describes how to use the Designer to work with custom controls.

The examples discussed here are cumulative and use a custom control, Fountain Fill, which creates interesting graphic patterns. This control is provided in the ole_demo folder. These examples assume you are familiar with the Designer.

Registering a control Before you include a custom control in an application, you must register it so that the operating system is aware of its existence. You only need to register a control once.

To register the Fountain Fill control:

1. Select Form Item > Custom Control > Register Control from the Designer menu.

The Open dialog box appears.

2. Find the folder that contains the control that you want to register and select the file name. Recall that .ocx is the default file extension for custom controls.

For example, from the Open dialog box, select the ole_demo folder and the fountain.ocx file.

3. Click Open.

The system registers the Fountain Fill custom control.


Adding a control to a form This section describes how to add a custom control to a form from the Designer.

To add the Fountain Fill control to the form:

1. Double-click the OLE Custom Control form item on the New Item dialog box. You also can drag the form item from the New Item dialog box to the form.

The Insert an OLE Control dialog box appears, listing the registered custom controls.

2. Select Fountain Fill Control from the Insert an OLE Control dialog box, as shown here:

3. Click OK.

The Designer adds the Fountain Fill control to the form.

Chapter: 3. Working with OLE custom controls Section: How to use the Designer with custom controls


Customizing a control To customize an OLE custom control, use techniques that are similar to the ones you use with other form items.

To customize an OLE custom control:

1. Double-click the control item on the form (for example, the Fountain Fill control).

The Form OLE Custom Control Options dialog box appears, as shown here:



2. Click Control Property.

The Fountain Fill Control Properties dialog box appears, as shown here:

A. From the General tab, choose a Fill Type, Start Color, and End Color;

for example:

♦ Set the Fill type to ellipse

♦ Set the Start Color to dark gray

♦ Set the End Color to light gray

B. On the Caption page, type text in the caption entry field; for example, enter ObjectStudio.

C. Click OK on the Control Properties dialog box.



To open the Form Item Options dialog box:

1. Double-click the custom control form item on the form.

The Form OLE Custom Control Options dialog box appears.

2. Click Options to open the Form Item Options dialog box.

3. Select the options you want to change from the check boxes in the Miscellaneous topic box. You can make the control moveable and resizable (horizontally or vertically).

4. Click OK to close the Form Item Options dialog box.

5. Click OK to close the Form OLE Custom Control Options dialog box.

The custom control changes to reflect the edits you made. The Fountain Fill custom control appears, as shown here:



Setting ambient properties for a container You can set characteristics for a container (recall that the OLE term for a form is container). These characteristics, called ambient properties, affect custom controls that you subsequently create, but they do not affect custom controls that already exist.

One reason to set ambient properties is to ensure that all of the custom controls on one form have a consistent appearance or behavior. ObjectStudio saves the ambient properties when it saves the controller that contains the form of the properties.

Ambient properties Following are the ambient properties for custom controls:

♦ AutoClip. [No documentation is available at this time.]

♦ BackColor. The color for the interior of a control.

♦ DisplayName. The name that the control displays for itself in error messages.

♦ ForeColor. The color that the control uses to display text and graphics.

♦ MessageReflect. A Boolean value. If the value is true, the control reflects Windows messages back to the control.

♦ ScaleUnits. The name of the coordinate units that the container uses.

♦ ShowGrabHandles. A Boolean value. If the value is true, the control displays grab handles when the visual editing starts.

♦ ShowHatchings. A Boolean value. If the value is true, the control does not draw a hatched border when visual editing starts.


♦ SupportsMnemonics. A Boolean value. If the value is true, the control supports mnemonics.

♦ TextAlign. An integer that specifies how to align text in the control. Values are:

- 0 = Numbers on the right, text on the left

- 1 = Left align

- 2 = Center align

- 3 = Right align

- 4 = Fill justify

♦ UIDead. A Boolean value. If the value is true, the control can detect situations when the container should not allow the control to interact with user input. If the value is false (the default), the UI does not respond, the control should not set the cursor, and it should ignore UI input.

♦ UserMode. A Boolean value that describes how the control is being used. If the value is false, the control is being used to design an object such as a control container. If the value is true, the user is viewing or interacting with the control. The value can change dynamically.


Setting ambient properties To set ambient properties for a form:

1. Select FormItem > Custom Control > Ambient Property from the Designer menu.

The Property Editor appears, as shown here:

The topmost drop-down list box lists the form for which you are changing

ambient properties.

The entry field displays the value for the currently selected property and optionally provides a way to change the value. (Usually, there is a button, a drop-down list box, or an entry field.)

The list box displays the ambient properties and their current values.

2. Select the form (for example, Work1) for which you want to set default characteristics from the topmost drop-down list box.



3. Double-click the property in the Name column that you want to change.

The system presents a way to change the value by displaying a dialog box or by toggling the value. For example:

A. Double-click the BackColor property.

The Color dialog box appears.

B. Select a new color from the Color dialog box.

C. Click OK on the Color dialog box.

4. Close the Property Editor.

5. Test your work by creating a new Fountain Fill custom control.

The new control should have the background color that you selected.

Responding to user interaction You can use the Event Editor to allow the custom control to respond to user interaction:

♦ It lists the Smalltalk events to which the control can respond (for example, gotFocus and lostFocus). The names of these events tend to start with a lowercase letter.

♦ It lists the events that are specific to the control. The names of these events start with an uppercase letter.

For more information about the Event Editor, refer to ObjectStudio User Interface Guide, P40-3811.

The Fountain Fill custom control can respond to the Click event, which occurs when the user clicks inside the control. Fountain Fill also has a method, AboutBox, which displays a dialog box containing information about the control.


To display the control’s About Box when the user clicks inside the Fountain Fill control:

1. Select Controller > Events from the Designer menu.

The Event Editor appears, as shown here:

2. Select the following values (starting from the upper-left corner and

continuing in a clockwise fashion):

A. Sender object (the object that experiences the event). For example, select oleCustomControl1 from the Sender objects box.

B. Event names (the name of the event to react to). For example, select Click from the Event names list box.

C. Event receiver objects (the object that should react to the event). For example, select oleCustomControl1 from the Specify event receiver list box.

D. Messages (the message to send when the event occurs). For example, select AboutBox from the Message list box.


OLE User’s Guide, P40-3805 55 Chapter: 3. Working with OLE custom controls Section: Smalltalk support for custom controls

3. Click Add.

4. The system adds the event you specified to the Hooked receiver objects and Messages list boxes.

5. Click OK to close the Event Editor.

6. Select File � Test interface to test the interface.

7. Click the Fountain Fill control to display the Fountain Fill About Box.

When the event that you specified occurs, the system responds by sending the message to the event receiver.

Smalltalk support for custom controls To support OLE custom controls, ObjectStudio Smalltalk provides several classes in the following object hierarchy:

Object FormItem FormOLEItem FormOLEControl InterfacePart

The following sections describe the methods from the classes that you are most likely to use when you write code to work with custom controls.

FormOLEItem class The FormOLEItem class is an abstract class from which FormOLEControl inherits functionality. For more information about FormOLEItem, see “FormOLEItem class” on page 30.


FormOLEControl class Each instance of FormOLEControl represents an instance of a custom control.

Instance variable Following is the one instance variable in class FormOLEControl:

dispatcher. An instance of OLEDispatcher, a Smalltalk wrapper class that interfaces with OLE Automation. All changes to the custom control’s properties and all of the custom control’s method calls are forwarded to this instance.

Class methods Following are the class methods in class FormOLEControl:

♦ new. Creates a new instance of a FormOLEControl.

♦ registerControl:. Registers a custom control with the operating system.

♦ unregisterControl:. Removes the operating system’s registration for a custom control.

Instance methods Following are the instance methods in class FormOLEControl:

♦ call:params:. Invokes a custom control’s method. The first parameter is a string containing the message to send. The second parameter is an array of parameters to the message; for example:

fountain call: 'AboutBox' params: {}.

♦ call:params:namedParams:. Invokes a custom control’s method. To specify only a few parameters out of a long list, use this method to invoke an OLE method and specify each parameter by name.

The first parameter is a string containing the message to send. The second parameter is an empty array. The third parameter is an array of arrays. Each subarray represents a method parameter. Its first element is a string representing the name of the parameter, and the second element is the parameter’s value; for example:

wordObj call: 'EditFind' params: {} namedParams: {{'Find' 'hello'} {'Wrap' 1}}.

♦ methodNames. Returns an array containing the names of the method that the custom control implements.


♦ controlMethods. Return a Dictionary that describes the control’s methods. Each key is a method name. Each value is an instance of class AutomationMethod and includes a description of the method’s parameters.

♦ controlName. Returns a string (the custom control’s internal name) that describes the custom control.

♦ controlName:. Sets the custom control’s internal name, which should describe the custom control. The parameter, a string, is the custom control’s internal name.

The developer should not have to use the controlName: method directly. The custom control’s internal name is used internally to store an ID, related to the ActiveX control, in the .prj file.

♦ eventNames. Returns an array of names of events to which the custom control can respond.

♦ events. Returns a Dictionary that describes the control’s events. Each key is an event name. Each value is an instance of AutomationMethod and describes the event.

♦ getProperty:. Returns the value of a property. The parameter is a string containing the name of the property; for example:

fountain getProperty: 'Caption'.

♦ insertOCX. Displays the Insert Custom Control dialog box, which you use to add a custom control to a form.

♦ onCreateItem:controlTypeInfo:eventTypeInfo:. A notification method that is sent when the custom control is created.

♦ open. Creates the custom control and displays it on a form. This method behaves like other open methods in the FormItem class hierarchy.

♦ properties. Returns a Dictionary that describes the control’s properties. Each key is a property of the custom control. Each value is an instance of class AutomationProperty and contains descriptive information about the property such as type and ID.

♦ propertyNames. Returns an array of the custom properties supported by the specified OLE control.

♦ setProperty:to:. Sets a property to a new value. The first parameter is a string representing the property. The second parameter is the value; for example:

fountain setProperty: 'Caption' to: 'ObjectStudio'.

♦ ShowPropertyPage. Displays the property page for the custom control.

Chapter: 3. Working with OLE custom controls Section: Smalltalk support for custom controls


InterfacePart class The InterfacePart class provides one method, listed here, that registers a response to a custom control event.

on:for:action:. Although it is recommended that you use the Event Editor to respond to a custom control event, you can also send the following message:

on: eventName for: item action: anAction

For example, the following code responds to a Click event on a control named fountain by executing the AboutBox action:

self on: #Click for: fountain

action: (OLEControlAction receiver: fountain

action: #AboutBox).

Notes about licensing OLE custom controls are packaged in one of the following ways:

♦ If they are packaged with a license file, you can include them in applications and distribute them to end users.

♦ If they are packaged without a license file, they can be used as part of the application with which they are packaged, but they cannot be included in other applications.

ObjectStudio embeds the license key in the application. Therefore, when you distribute an application that includes OLE custom controls, you do not need to package the control’s license file with the application.


4. Working with OLE component client services Using ObjectStudio as a client

The ObjectStudio OLE Component Client services help you integrate Smalltalk objects with external OLE components. This feature of ObjectStudio can help you migrate from large, monolithic applications to collections of components.

ObjectStudio includes a class framework for mapping Smalltalk into OLE interfaces. ObjectStudio also provides abstract classes, class templates, and tools that automate much of the work for integrating OLE into an application or component.

The following topics lead you through a demonstration in which you use ObjectStudio as an Automation client and Microsoft Word as an Automation server. This demo uses Microsoft Word to generate a confirmation letter for any change in the financial service that is provided to a customer.

If Microsoft Word is not installed on your system, you cannot successfully run this demo. However, you can still benefit from reading the description of the demo.

Automation is a way for one application to use the functionality of another application. The application that is doing the work may or may not be visible to the user.

Automation works in the following manner:

♦ The Automation server publishes an interface of specific functions

♦ The Automation client calls the functions, causing the server to do work

Chapter: 4. Working with OLE component client services Section: Using ObjectStudio as a client

Loading the OLE demo files

Before loading the OLE demo files, make certain you have loaded the OLE loadable application.

To load the OLE demo files:

1. On the Desktop, select the File > Load application menu option.

The Applications dialog box appears.

2. Select OLE Demo Files from the list box.

3. Click the Load button.

Files are loaded from the w32\Ole_demo folder inside your ObjectStudio folder.

ObjectStudio loads OLE demo files and creates icons for them on the Desktop.

Running the OLE demo To run the demo:

1. On the Desktop, double-click the Customer Selection icon.

The Investment Advisor dialog box appears, as shown here:

2. Select a customer from the Customer List.

OLE User’s Guide, P40-3805 60 Chapter: 4. Working with OLE component client services Section: Using ObjectStudio as a client


3. Click the Service Change button.

The ObjectStudio Customer Service dialog box that contains information about the customer you selected appears, as shown here:

Chapter: 4. Working with OLE component client services Section: Using ObjectStudio as a client

OLE User’s Guide, P40-3805 62 Chapter: 4. Working with OLE component client services Section: Using ObjectStudio as a client

4. Select Commodities from the Service drop-down list box.

5. Select Added from the Status drop-down list box.

6. Click the Confirmation Letter button.

ObjectStudio opens Microsoft Word.

7. Switch focus to the Microsoft Word window so that you can watch Word work.

Microsoft Word displays a form letter and fills in the merge fields with data from the ObjectStudio Customer Service dialog box.

8. Switch focus to the ObjectStudio Customer Service dialog box.

9. Click the Done button.

If you have Microsoft Word 2000, ObjectStudio closes the form letter document but does not close Microsoft Word. If you have Microsoft Word 97, ObjectStudio closes Microsoft Word. The Customer Service dialog box closes and focus returns to the Investment Advisor dialog box.

10. If you have Microsoft Word 2000, close Microsoft Word.

11. In the Investment Advisor dialog box, click the Close button.

How the Automation demo works The Automation demo does the following:

1. When you click the Service Change button in the Investment Advisor dialog box, the ObjectStudio Customer Service dialog box appears.

2. When you click the Confirmation Letter button in the ObjectStudio Customer Service dialog box, ObjectStudio creates an instance of a Word Automation object, which opens Word.

3. ObjectStudio invokes a series of methods in the Word Automation object. These methods instruct Word to load a mail merge file and to replace specific fields with data that ObjectStudio supplies.

4. When you click the Done button in the ObjectStudio Customer Service dialog box, ObjectStudio releases the Automation object. This closes Word 97. It closes the form letter document in Word 2000 but does not close Word 2000.

OLE User’s Guide, P40-3805 63 Chapter: 4. Working with OLE component client services Section: OLE development overview

OLE development overview ObjectStudio OLE Client Services provide support for OLE Automation, Uniform Data Transfer, and Structured Storage. Your application can implement any combination of these services. The implementation process is similar for all three services.

The process for adding OLE Client Services to an application is:

1. Create an instance of OLEObject.

2. Create an instance of an interface or an interface helper.

3. Use the interface’s methods to interact with the OLEObject.

OLE object references are released during the next garbage collection. The following sections describe these steps in more detail.

Creating an instance of OLEObject The instance of OLEObject is a Smalltalk representation of the OLE server object that you create. The infrastructure that this instance implements can attend to many of the OLE details for you.

Class methods. The following class methods in class OLEObject allow you to create an instance and associate it with an OLE Server:

♦ newProgId:. Assumes that an OLE object has been registered with the system using the program ID that you pass as a parameter; for example:

OLEObject newProgId: #'Excel.Application'.

♦ getClipboardObject. Allows you to retrieve an OLE object from the Clipboard; for example:

OLEObject newFromClipboard.

The OLE object supports the IDataObject interface for use in retrieving the object’s data. If the Clipboard does not contain an OLE object, the system creates an OLE object from the data on the Clipboard.

Once you retrieve an OLE object from the Clipboard, you usually send it the message oleDataTransferObject to retrieve an interface for getting and setting the data.


Interacting with the OLEObject To interact with the OLEObject, retrieve one or more of the object’s interfaces and use the interfaces to send messages to the object. You can proceed in one of the following ways:

♦ Use a high-level helper class to send messages to the OLEObject. Using such a class is the easiest way to interact with OLE objects that support Automation or Uniform Data Transfer.

♦ Work directly with OLE interfaces, using interface methods to perform tasks with the OLE server.

Using a high-level helper class To use a high-level helper class, send one of the following messages to an instance of OLEObject:

♦ dispatcher. Returns an instance of OLEDispatcher for accessing an object’s Automation interfaces. This object simplifies using Automation objects that support the IDispatch interface. For more information, see “Using OLE Automation” on page 66.

♦ staticDispatcherNamed:. Returns an instance of a subclass of OLEStaticDispatcher. The resulting object is a customized static dispatcher. This object simplifies access to Automation objects whose automation methods and properties have been predefined within ObjectStudio. For more information, see “Using OLE Automation” on page 66.

♦ dataTransferObject. Returns an instance of class OLEDataTransfer. The result is an instance of the class OLEDataTransfer. This object simplifies using Data Transfer objects that support the IDataObject interface. For more information, see “Using Uniform Data Transfer” on page 75.


Working directly with OLE interfaces Once you create an instance of OLEObject, retrieve one or more of the object’s OLE interfaces. (The retrieval process is called querying.) To retrieve an OLE interface, send the message interfaceName: to the instance of OLEObject. The parameter is a symbol that is the name of an OLE Client Interface that ObjectStudio supports. The possible choices are:

♦ #IDataObject

♦ #IDispatch

♦ #IEnumFORMATETC

♦ #IEnumSTATSTG

♦ #IPersist

♦ #IRootStorage

♦ #IRunnableObject

♦ #IStorage

♦ #IStream

♦ #ITypeInfo

♦ #ITypeLib

The method returns an instance of the supporting interface class. The name of the class directly corresponds to the name of the OLE Interface. All interface classes are subclasses of IUnknown, which, in turn, is a subclass of the abstract class OLEInterface. IUnknown and OLEInterface implement common behavior and attributes for the interface classes.

Once you retrieve an OLE interface, you can use the methods of that interface to send requests to the OLE Server.

OLE User’s Guide, P40-3805 66 Chapter: 4. Working with OLE component client services Section: Using OLE Automation

Using OLE Automation OLE Automation is the Microsoft technology that replaces cross-application macro programming. The component and application that provide functionality or information are the Automation Objects. Applications that make use of the Automation Objects are Automation Controllers.

Any Automation Controller can use every Automation Object, and any Automation Object can be integrated with every Automation Controller. You can use ObjectStudio to write an Automation Object or an Automation Controller.

These sections describe the mechanisms that make Automation work and show how ObjectStudio integrates with OLE Automation.

Mechanics of OLE Automation OLE Automation involves an Automation Controller, usually an application with a programming environment of some kind (Smalltalk in the case of ObjectStudio), and one or more Automation Objects. Because Automation Objects can be driven from an external programming environment, they are also called programmable objects.

The Automation Controller is a client of the Automation objects. Like other OLE objects, Automation Objects communicate by means of interfaces. The interface for Automation Objects is IDispatch.

Automation Controllers must be able to access data inside the objects at run time, which is important for controllers built on interpreted languages such as Smalltalk.

The need to perform late binding involves the following types of elements through which objects and controllers communicate:

♦ Incoming methods. Incoming methods are callable functions that instruct an object to do specific operations.

♦ Outgoing methods. Outgoing methods are also called events. These are functions that an object calls to notify the controller that something interesting has happened. The most interesting events are usually triggered in response to asynchronous actions, such as user input.

♦ Properties. Properties are the object’s data. Properties can be read-only, write-only, or both.

Methods and properties can fully describe the functionality and information of any object.


IDispatch interface To illustrate how the IDispatch interface works, consider a very simple object, the Beeper, that has one property, Sound, and one method, Beep. Exporting this object through Automation involves the use of an IDispatch interface with its own ID, where data members can be expressed directly as properties:

dispinterface DIBeeper {

properties:

[id (0)] long Sound;

methods:

[id (1)] long Beep (void);

}

The syntax of this piece of code is part of the Object Description Language (ODL), which is the language that you use to describe Automation objects. The ODL is compiled into a Type Library file (TLB), with which Controllers can interact to extract the capabilities of the object. In this example, the id(xx) attribute assigns the dispatch identifier (or dispID) to each member. The Sound property has dispID = 0, and the Beep method has dispID = 1.

The dispatch identifiers are used at run time to dispatch method calls and property gets or puts. A client, in this case an Automation controller, has a pointer to some interface pointer through which it can access the members of the IDispatch interface by their dispatch identifiers.

Instead of calling a function directly to access a property or to invoke a method, the controller calls a generic function and passes it a dispID with any additional parameters that are needed for the property or method. The generic function maps the dispID to the correct piece of implementation. It is the responsibility of the Automation object to provide the generic function, through the IDispatch interface.


Implementing an Automation Controller ObjectStudio provides everything you need to create an Automation Controller easily. This section describes the architecture of the ObjectStudio Automation client and how to use it with your application.

The ObjectStudio implementation of an Automation client hides many of the details of Automation and provides an object-oriented framework for using OLE Automation. The classes OLEDispatcher and OLEStaticDispatcher help you access OLE Automation. ObjectStudio provides the following mechanisms for using OLE Automation:

♦ Creation of an Automation client (in Smalltalk terminology, instantiation)

♦ Methods for getting and setting properties

♦ Methods for invoking methods

♦ Type-conversion mechanism for marshaling between Smalltalk data and OLE data

The difference between OLEDispatcher and OLEStaticDispatcher is that OLEDispatcher uses dynamic invocation; that is, given a name, it calls the IDispatch interface to convert name to ID. Given a Smalltalk variable, it figures out the matching type, and then converts the data.

In contrast, OLEStaticDispatcher is provided with all of this information on creation, so at invocation time, it is faster than OLEDispatcher. With OLEStaticDispatcher, however, you have to do the following for properties and methods:

♦ Provide the dispIDs

♦ Describe type information


Creating an Automation client object There are several ways to create an Automation client object:

♦ Directly from OLEDispatcher. To create an Automation client object directly from OLEDispatcher, use code as in the following example:

myDispatch := OLEDispatcher new: 'Word.Basic'.

The parameter is a progid, which is the name under which the OLE object is registered. This method instantiates an instance of OLEDispatcher and creates a new instance of the application. In this example, it starts Word.

♦ From OLEObject. To create an Automation client from OLEObject, load the OLE Demo Server Objects loadable application and then perform the following:

OLEObj := OLEObject newProgId:

#'ObjectStudio.StockServer'.

OLEDisp := OLEObj dispatcher.

OLEObject is a class that encapsulates the Smalltalk interface for accessing OLE DCOM objects (see “Creating an instance of OLEObject” on page 63). From the instance of OLEObject, call the method dispatcher that returns an instance of OLEDispatcher.

You usually use this style of creating an Automation client when you are using a generic OLE DCOM object that implements multiple interfaces, and one of the interfaces happens to be IDispatch. This method creates a new instance of the application.

♦ Using the getObject:progName: class method. You can create an Automation client using the class method getObject:progName: for the following purposes:

- Binding to an application if it is already running—For example, if you already have a copy of Word running, you can bind to that application using the following code:

myDispatch := OLEDispatcher getObject: nil progName: 'Word.Document'.

- Activating an object from a file—Many OLE Automation applications allow the user to save objects in files. For example, a spreadsheet application can allow the user to save the worksheet in a file. The same application can support a chart object that the user can also save in a file. You use the getObject:progName: class method to activate an object that has been saved to a file; for example: spreadSheet := OLEDispatcher getObject: 'sheet1.xls' progName: nil.


Working with an object’s properties Once you have a variable that references an OLE object, you can get and set the object’s properties.

To assign a value to a property of an object, use the at:put: instance method of OLEDispatcher, as in the following example:

myDispatch := OLEDispatcher new: 'MyApplication.MyObjectType'.

myDispatch at: 'Text' put: 'Hello, world'.

You can also retrieve property values from an object, as in the following example:

entryField put: (myDispatch at: 'Text').


Invoking methods Once you have a variable that references an OLE object, you can also perform methods on the object. Some methods return a value; some do not. Consider the following method calls:

♦ Normal method call. Normally, you invoke a method using the call:params: method in class OLEDispatcher:

myDispatch call: procName params: params

where:

procName is a string or symbol that is the name of the Automation method

params is an Array object that contains the parameters for the method; for example:

myDispatch := OLEDispatcher new: 'Word.Basic'.

myDispatch call: 'FileOpen' params: {'hello.doc'}.

♦ Method call with optional arguments. Some OLE Automation methods allow optional arguments, that is, the argument has a default value and the caller does not need to specify a value. For example, consider the following Word method:

VOID Maximize (optional BSTR windowName);

where:

The Maximize function maximizes a window.

If no windowName is provided, it maximizes the Word application window. In ObjectStudio, you specify the default value by passing the symbol #Default; for example:

word call: 'Maximize' params: {#Default}.

You can override the default value by passing in an argument; for example:

word call: 'Maximize' params: {'My Window Name'}.


♦ Method call with named arguments. Named arguments are arguments that can be placed anywhere in a method’s argument list. They are identified by a name that has a meaning to the method.

For example, consider a method in a musical database called FindRockBand that has three named arguments. The arguments are strings containing the last names of the band members: LeadGuitar, BassGuitar, and Percussion. In the object’s type information, declare this method, which might return a long identifier to the database record:

LONG FindRockBand(BSTR LeadGuitar,

BSTR BassGuitar, BSTR Percussion);

Using named arguments, you can invoke FindRockBand from an Automation controller:

id=Database.FindRockBand (LeadGuitar="Lifeson", BassGuitar="Lee", Percussion="Peart");

Because the parameters in the previous example are named rather than positional, an exact equivalent is as follows or can be any other permutation:

id=Database.FindRockBand (BassGuitar="Lee", LeadGuitar ="Lifeson", Percussion="Peart");

To call the method with named parameters from ObjectStudio, use one of the following methods in class OLEDispatcher:

call: procName namedParams: namedParams

call: procName params: params namedParams: namedParams

where:

namedParams is an Array of two-element arrays. In each two-element array, the first element is the named parameter name and the second element is the actual parameter.

For example, the previous call translates into the following ObjectStudio code:

id := database call: 'FindRockBand' namedParams: {{'BassGuitar' 'Lee'} {'LeadGuitar' 'Lifeson'} {'Percussion' 'Peart'}}.


Type conversion In OLEDispatcher, type conversion from the Smalltalk data type to an OLE Automation data type is provided for you. Nevertheless, it helps to understand the fundamental Automation data types when you read the object’s type library or Help file.

Users are responsible for providing the correct Smalltalk data type when invoking an OLE property or method. For example, consider the ListView Common Control OCX Sample in the Sample Browser. The ColumnHeader interface expects the #Width property’s put function to have a parameter of type single, which corresponds to the Smalltalk type float. Therefore, the correct Smalltalk invocation of the #Width property’s put function must have a second argument of type float, as is the case in the following example:

colHeader at: #Width put: 100 asFloat.

The following table describes OLE Automation data types and their associated Smalltalk data types:

Automation type

ExternalVariable data class

ObjectStudio data class

VT_EMPTY None None (Used for Function VOID)

VT_I2 VWord SmallInteger

VT_I4 VDWord LongInteger

VT_R4 VFloat Float

VT_R8 VFloat Float

VT_CY VCurrency Point

VT_DATE VDate Date

VT_DISPATCH VDWord OLEDispatcher

VT_ERROR None None

VT_BSTR VBString String

VT_BOOL VBoolean Boolean

VT_VOID None None (C style VOID)

VT_VARIANT VVariant None

Chapter: 4. Working with OLE component client services Section: Using OLE Automation


The VT_DISPATCH data type is used to indicate that a method or property returns another IDispatch pointer. For example, consider the Excel Automation object. The main object created is the Application object. There is also an ActiveWorkBook property that returns a workBook object. Consider the following example:

excelApp := OLEDispatcher new: 'Excel.Sheet'.

workBook := excelApp at: 'ActiveWorkBook'.

workBook at: 'Author' put: 'My Name'.

In the Excel type library, the property ActiveWorkBook returns a VT_DISPATCH code, meaning that it contains a new dispatcher object. Note that the workBook object is a new instance of the OLEDispatcher class. Once you get this instance, you can get or set properties of the workBook object.

For more information. This section has described the Microsoft Automation architecture and how to use ObjectStudio as an Automation client. It has not described the implementation details that ObjectStudio hides from you. If you are interested in learning more about these details, refer to a reference manual, such as Inside OLE Second Edition or OLE2 Programmer’s Reference, Volume Two.

OLE User’s Guide, P40-3805 75 Chapter: 4. Working with OLE component client services Section: Using Uniform Data Transfer

Using Uniform Data Transfer This section describes how to use the Uniform Data Transfer interface of OLE server components. The OLEDataTransfer class provides an easy way to use the Uniform Data Transfer capabilities of an OLE object. OLE Data Transfer allows you to:

♦ Set data into an object

♦ Get the current data from an object

♦ Ask for advises (notifications) whenever the object’s data changes

OLE can represent (or format) an object’s data in several ways. The OLEDataTransfer class supports text, bitmap, and metafile formats.

Creating an OLEDataTransfer object This section describes how to create an OLEDataTransfer object. Recall that in OLE terms, you interact with an OLE object by querying (retrieving) an interface of the object and executing functions that the interface provides.

To create an OLEDataTransfer object:

1. Create an instance of OLEObject, as described in “Creating an instance of OLEObject” on page 63.

The instance of OLEObject is a Smalltalk representation of an OLE server object. You use Data Transfer to interact with the OLEObject.

2. Ensure that the instance of OLEObject supports the IDataObject interface. If you created the OLEObject from the Clipboard (by sending the message getClipboardObject), the object is guaranteed to support this interface.

3. Send the message dataTransferObject to the instance of OLEObject.

On success, this method returns an instance of OLEDataTransfer associated with the OLEObject. On failure, this method returns an instance of class Message.

4. You can now work with the Data Transfer interface to act on the OLEObject. To do so, perform instance methods of OLEDataTransfer.


Working with Uniform Data Transfer The following sections describe how to work with a Uniform Data Transfer interface and discuss how to:

♦ Set data into the instance of OLEObject

♦ Get data from the instance of OLEObject

♦ Work with advises to get notification whenever the instance of OLEObject changes

Setting data To set data in the instance of OLEObject, send the setData: message. The parameter is an instance of one of the following classes:

♦ Bitmap

♦ MetaFile

♦ String

If you pass a parameter to the method that is of any other type, the method converts the parameter to a string (it sends the asString message) and treats the parameter as text.

Getting data To get data from the instance of OLEObject, send one of the messages described in the following table. Each of these methods returns the data in the format you requested. If the OLEObject does not support the format, the method returns an instance of class Message.

Method Returns an instance of Class

getTextData String or Message

getBitmapData Bitmap or Message

getMetaFileData MetaFile or Message


Working with advises Uniform Data Transfer provides a feature that notifies you whenever the instance of OLEObject changes. The notification feature is called an advise.

These methods help you work with advises:

♦ advise:block: method. Sets up an advise.

♦ unadvise method. Terminates the advise.

Setting up an advise To set up an advise link, use the advise:cfFormat:block: method.

The cfFormat parameter can be one of the following values:

♦ CF_TEXT

♦ CF_BITMAP

♦ CF_METAFILEPICT

♦ CF_ENHMETAFILE

♦ CF_UNICODETEXT

To use these constants as parameters, the class containing the code must include the OLEConstants global as a pool dictionary.

Alternately, you can specify the parameter:

(OLEConstants at: #CF_TEXT).

The block parameter is a Smalltalk block with a single parameter that receives the latest data value for the OLEObject each time it changes. The type of the data received depends on the format that you specify in the cfFormat parameter.

Terminating an advise You can terminate a running advise link at any time by using the unAdvise message. You must send this message before you finish using the object.

OLE User’s Guide, P40-3805 78 Chapter: 5. Working with OLE component server services Section: Using ObjectStudio as a server

5. Working with OLE component server services Using ObjectStudio as a server

You can use ObjectStudio to develop a business component object that provides data or services to requesting (client) applications.

The ObjectStudio business component object can use the OLE Automation or OLE Uniform Data Transfer functionality (or both) to communicate with the client application. You can create ObjectStudio components by including them as part of an application.

The client application can be developed in any environment that supports OLE 2.0 Client Automation or Uniform Data Transfer.


Loading the OLE demo server object files To load the OLE demo server object files:

1. Load the demo application:

A. On the ObjectStudio Desktop, select the File > Load application menu option.

The Applications dialog box appears.

B. Select OLE Demo Server Objects from the list box.

C. Click the Load button.

Files are loaded from the w32\Ole_demo folder inside your ObjectStudio folder.

2. On the Desktop, select the Tools > OLE Server Object Manager menu option:

3. Use the OLE Server Object Manager to prepare the Timer Server:

A. Select ObjectStudio 5.0 Time Server from the Served Objects list box.

B. Select the File > Update Registry menu option.

C. Select the File > Register Class Factory menu option.

Chapter: 5. Working with OLE component server services Section: Using ObjectStudio as a server


Inspecting an OLE object This part of the demo shows you a tool that acts as an inspector for OLE Uniform Data Transfer objects.

Starting the demo To start the demo:

1. Minimize the ObjectStudio Desktop that is running the OLE Server Object Manager.

The ObjectStudio process that you minimize is the Server ObjectStudio.

2. Start a second ObjectStudio process.

This new ObjectStudio process is the Client ObjectStudio.

3. To load the DataObjectTester class, select File > Load file and open dataobj.cls, which is located in the ole_demo folder.

The DataObjectTester icon appears on the Desktop.

4. Double-click the DataObjectTester icon to open its user interface.

The Data Object Test dialog box for the OLE Data Transfer inspector that you will use in this demo appears, as shown here:

Chapter: 5. Working with OSection: Inspecting an OLE object

LE component server services


Creating an object This demo works with the Timer Server object that you registered in “Loading the OLE demo server object files” on page 79.

To create an instance of the Timer Server:

1. Select ObjectStudio.TimeServer from the Id drop-down list box in the Data Object Test dialog box.

2. Click Create Object.

ObjectStudio creates and starts a Timer Server, displaying a representation of the timer:

The Data Object Test status line shows the Timer Server’s class ID and displays the text “Have Object.” These two pieces of information indicate that the Data Object Test created an instance of the Timer Server.

Chapter: 5. Working with OLE component server services Section: Inspecting an OLE object


Working with the timer server In this section, you work with features on the Data Object Test dialog box to test the Timer Server.

An advise, which is supported by Data Transfer, is a notification of change. Advise flags are options (for advanced use) that change the way advises happen.

To use advises:

1. Select CF_TEXT from the Format drop-down list box (in the Input Format group box).

ObjectStudio fills in the other fields in the Input Format group box on the Data Object Test dialog box.

2. Click Start Advise.

The Advise Flags dialog box appears, as shown here:

3. Click OK on the Advise Flags dialog box.

The Data Object Test dialog displays a new time every second in the Text entry field.

Chapter: 5. Working with OLE component server services Section: Inspecting an OLE object

OLE User’s Guide, P40-3805 83 Chapter: 5. Working with OLE component server services Section: Inspecting an OLE object

4. Click Stop Advise.

ObjectStudio stops updating the Text entry field when the Timer Server changes.

5. In the Text entry field of the Data Object Test dialog, enter:

stop

6. Click Set Data.

The ObjectStudio OLE Timer Server stops updating itself. The Timer Server responds to the following keywords:

start stop reset set num

where num is a number representing hundredths of a second. (You may want to experiment with these keywords.)

7. When you are done, click Close.

ObjectStudio closes the Timer Server and the Data Test Object.

You can close the Client ObjectStudio process and the Server ObjectStudio process.

OLE User’s Guide, P40-3805 84 Chapter: 5. Working with OLE component server services Section: Creating an ObjectStudio component

Creating an ObjectStudio component This section provides an overview that describes how to create an ObjectStudio component object. “Creating a simple OLE server” on page 104 leads you through the process of creating a simple component object in ObjectStudio. The process for developing an ObjectStudio component object is:

1. Create a subclass of OLESrvObject.

For more information, see “Creating a subclass of OLESrvObject” on page 87.

2. Subclass each subclass of OLESrvInterface (OLESrvIDataObject for Data Transfer, or OLESrvIDispatch for Automation) that the component makes available to client applications. You can use the OLE Server Object Manager to create these subclasses.

For more information, see “Subclassing interfaces” on page 90.

3. Implement the business logic for the component. Also, specify how the component should respond to requests passed through each supported OLE interface.

For more information, see “Implementing business logic” on page 101.

4. Generate a type library if the object includes an IDispatch interface.

For more information, see the following section, “Using the OLE Server Object Manager.”

5. Use the ObjectStudio Program Generator to create an application that includes one or more OLE server objects.

For more information, see “Preparing to run the server” on page 102.


Using the OLE Server Object Manager The OLE Server Object Manager is used to create an OLE component. Some of the options in the OLE Server Object Manager require that you enter information, and some options can generate some of the Smalltalk source code required by a component object. Of course, you can write code that performs these steps, but in most cases, using the OLE Server Object Manager is more convenient.

Opening the OLE Server Object Manager Select Tools ⇒ OLE Server Object Manager from the Desktop menu to open the OLE Server Object Manager. The OLE Server Object Manager appears, as shown here:

Chapter: 5. Working with OLE component server services Section: Using the OLE Server Object Manager


Toolbar and menu From left to right, the buttons on the OLE Server Object Manager toolbar correspond to the following menu options:

Button Menu option

Select File > New Object from the OLE Server Object Manager menu to create a new ObjectStudio OLE Server component object. Use this option to create a subclass of OLESrvObject.

Select File > Edit from the OLE Server Object Manager menu to edit an ObjectStudio OLE interface object. Use this option to open a custom Class Browser so you can edit the classes for your component.

Select File > Update Registry from the OLE Server Object Manager menu to update the OLE Registry with your new ObjectStudio OLE Server Component. The OLE Registry contains information about all OLE-enabled components and applications on your computer system.

Select File > Register Class Factory from the OLE Server Object Manager menu to register a class factory. Enables the Windows system to create an instance of an ObjectStudio OLE Server Component when a client application requests it.

Select File > Revoke Class Factory from the OLE Server Object Manager menu to revoke a class factory. Prevents an instance of your ObjectStudio OLE Server Component from being created.

Select File > Generate from the OLE Server Object Manager menu to produce a registration (.reg) file for an OLE Automation server.

Select File > Create Type Library from the OLE Server Object Manager menu to create a type library. Displays the Create OLE Server Object dialog box, which allows you to create a Type Library file (file extension .tlb). A Type Library file contains a description of the available methods and properties for your object. External programs use this file to see the capabilities of your server object.

Chapter: 5. Working with OLE component server services Section: Using the OLE Server Object Manager


Creating a subclass of OLESrvObject The OLE Server Object Manager helps you create a new subclass of the OLESrvObject class. The OLE Server Object Manager also copies class variables, instance variables, and methods from a generic template of a subclass of OLESrvObject.

The most convenient way to create a subclass of OLESrvObject is to use the OLE Server Object Manager. To create a subclass of OLESrvObject:

1. Select File > New Object from the OLE Server Object Manager menu.

The Create OLE Server Object dialog box appears, as shown in the following figure. Enter information about the subclass in the entry fields. For an example of this procedure, see “Creating an OLE Server class” on page 106.

2. When you have finished entering information about the subclass, click OK.

The system generates class code for the OLESrvObject subclass and displays the Save As dialog box.

Chapter: 5. Working with OLE component server services Section: Creating a subclass of OLESrvObject

OLE User’s Guide, P40-3805 88 Chapter: 5. Working with OLE component server services Section: Creating a subclass of OLESrvObject

Create OLE Server Object dialog box: Upper portion The upper portion of the dialog box contains the items described in the following table:

Field Meaning

Class Name The name of the subclass you are creating. This name is not used externally to ObjectStudio. Of course, when naming the class, follow ObjectStudio rules for naming classes.

Program ID The name of the OLE Component. Client applications use this name as the registered program ID when accessing the component. A typical name is ObjectStudio.TimeServer.

Class ID OLE requests and provides this 128-bit unique identifier that is used internally to identify the server component. This size ensures that it uniquely identifies the component even across a distributed environment. Typically, you should allow the system to generate this number.

Long Type Name A descriptive name of the component that the system registers. Applications often display the long name instead of the program ID.

Short Type Name A short descriptive name of the component.

Multiple Instances If multiple users might access the ObjectStudio OLE Server Component at the same time, then leave this check box checked.

OLE User’s Guide, P40-3805 89 Chapter: 5. Working with OLE component server services Section: Creating a subclass of OLESrvObject

Create OLE Server Object dialog box: Lower portion The lower portion of the dialog box allows you to fill in the Interface Map for the OLESrvObject subclass. The Interface Map is a dictionary where:

♦ The keys are the names of the OLE interfaces (IDataObject and IDispatch) by which your component object communicates with other OLE-enabled components and applications.

♦ The values are the Smalltalk classes that support those OLE interfaces.

Click New to create new subclasses of an interface. Select the type of interface from the OLE Interfaces and Classes drop-down list box. For more information, see “Subclassing interfaces” on page 90.

Once you define the OLE Interface subclasses, click Add to add them to the Interface Map. The Interface Map contains the current contents of the Interface Map dictionary. You can remove entries from the Interface Map list box.

When you finish entering information in the dialog box, click OK to save the OLESrvObject subclass and all of the specified subclasses of the OLE Interface classes. The OLE Server Object Manager window updates itself.

OLE User’s Guide, P40-3805 90 Chapter: 5. Working with OLE component server services Section: Subclassing interfaces

Subclassing interfaces The ObjectStudio OLE Server component object can support the following OLE interfaces:

♦ IDataObject. This is the main interface for the OLE Data Transfer class of services. IDataObject allows you to get and set data between applications. In this case, other applications can ask an ObjectStudio OLE Server component to provide data or make updates to data.

♦ IDispatch. This is the main interface for the OLE Automation class of services. IDispatch allows you to invoke features and set attributes within other OLE Automation-enabled components and applications. In this case, other applications can drive the functionality of an ObjectStudio server component.

The subclass of OLESrvObject needs to know which OLE interfaces are supported by the component. Include this information in the class method interfaceMap.

Select the set of OLE interfaces to support in the ObjectStudio server component according to the purpose of the component, as illustrated in the following table:

Select When

IdataObject (Data Transfer) You need to exchange data between your component and a requesting client.

Idispatch (Automation) The requesting client needs to perform batch operations using your component’s functionality.

The OLE interfaces are listed in the drop-down list box on the right side of the Create OLE Server Object dialog box. Select the first one from the drop-down list box to create an ObjectStudio subclass and click New. The system displays a dialog box whose contents depend on the interface you selected.


OLE Server IDataObject interface To create an IDataObject interface, select File > New Interface > OLE Server IDataObject from the OLE Server Object Manager menu. The Create OLE IDataObject Interface dialog box appears, as shown here:

Chapter: 5. Working with OLE component server services Section: Subclassing interfaces


The following table describes the fields on the Create OLE IDataObject Interface dialog box:

Field Meaning

Smalltalk Class Name

Assign the name for the IDataObject subclass for use within the ObjectStudio environment. The system uses the class name as the value for the Interface Map dictionary (IDataObject is the key).

Supported Get Formats

IDataObject, which resembles an enhanced clipboard, allows you to represent the data in different display formats. Indicate which representations to provide to users of the OLE object from the following list: CF_TEXT CF_BITMAP CF_METAFILEPICT CF_ENHMETAFILE CF_UNICODETEXT For each representation that you select, you must write code to handle requests for those representations.

Supported Set Formats

Similar to Supported Get Formats, but these are the formats of data that the OLE Object accepts from the client application when the client performs a SetData operation.

You can specify multiple formats by highlighting multiple entries in the Set and Get Format list boxes. Once you complete these entries, do the following:

1. Click OK to save the IDataObject subclass.

The Save As dialog box appears.

2. Type the name of the file to which you want to save the subclass.

3. Click Save on the Save As dialog box.

4. Click Add on the Create OLE Server Object dialog box to add the interface class to the Interface Map.


OLE Server IDispatch interface To create an IDispatch interface, select File > New Interface > OLE Server IDispatch from the OLE Server Object Manager menu.

The Create OLE Automation Server Object dialog box appears, as shown here:



The following table describes the fields on the Create OLE Automation Server Object dialog box:

Item Meaning

Class Name Assign a name to the IDispatch subclass for use within the ObjectStudio environment. The system uses the class name as the value for the Interface Map dictionary (IDispatch is the key).

Library Name The external name by which other (client) applications refer to this Automation interface. It can be different from the Class Name.

Help String An optional string that contains the purpose of this Automation interface. External (client) applications query the Help String.

Interface Members

A list of methods and properties that make up the Automation interface. To add new properties, click Add Property. To add new methods, click Add Method. When you click these buttons, the system displays dialog boxes that prompt you for information, as described later in “Adding a property” on page 112 and “Adding a method” on page 111.


Adding IDispatch properties When you click Add Property in the Create OLE Automation Server Object dialog box, the Add Property dialog box appears, as shown in the following figure. The dialog box prompts you to define the IDispatch properties.



The following table describes the fields on the Add Property dialog box:

Field Meaning

Property Name An identifier that describes the property.

Property Type The data type of the property, as described in “OLE data types” on page 100.

Get Method Name The name of the Smalltalk method that you code for retrieving the value of this property. For example, if the property name is Customer, you might call the Get Method Name customer. You must implement an instance method with this name in the OLEServerObject subclass that implements the dispatch.

Set Method Name

The name of the Smalltalk method you create to update the value of this property. For example, if the property name is Customer, you might call the Set Method Name customer:. You must implement an instance method with this name in the OLEServerObject subclass that implements the dispatch.

Default Property There can be one default property per Automation interface. Other (client) applications can refer to the default property by using the Automation interface object name only, rather than the typical objectName.propertyName convention.

When you finish filling in these items, click OK to save the IDispatch property definition and return to the Create OLE Automation dialog box.


Adding IDispatch methods When you click Add Method in the Create OLE Automation Server Object dialog box, the Add Method dialog box appears, as shown in the following figure. The dialog box prompts you to define the IDispatch method.



The following table describes the fields on the Add Method dialog box:

Field Meaning

External Method Name

The name that other (Automation client) programs use to invoke this method. Most commonly, it is the same as the internal name of the method, but it can be different.

Internal Method Name

The name (message selector) that Smalltalk uses for the method. You must implement an instance method with this name in the OLEServerObject subclass that implements the dispatch. When the automation method is invoked, the system calls this method.

Return Type The data type of the return value for this method. Note that void can be used when no specific value is returned. For more information, see “OLE data types” on page 100.

Parameters A list of the method’s parameters.

Parameter Name The name of the parameter. Naming conventions follow standard Smalltalk guidelines.

Parameter Type A list of data types that correspond to each parameter name. For more information, see “OLE data types” on page 100.

Specifying parameters To specify parameters for a method, do the following for each parameter:

1. Type the parameter name in the Name entry field.

2. Select the parameter’s type from the Type drop-down list box.

3. Click Add to add the parameter to the end of the parameter list.

You can also highlight an existing parameter entry and click Insert to place it before the highlighted entry in the Parameters list box.

4. When you finish entering methods and parameters, click OK to save the IDispatch method definition and return to the Create OLE Automation Server Object dialog box.


Interface Members list box The Interface Members list box contains the methods (M) and properties (P) assigned to the interface. Below the Interface Members list box (see the following figure) is an entry field that displays the member prototype for the highlighted entry in the list box. If the highlighted entry is a property member, the entry field contains the property data type and the name of the property. If the highlighted entry is a method, the entry field contains the return type, the method name, parameters, and the parameter data types.

Saving your work When you finish adding methods and properties, click OK on the Create OLE Automation Server Object dialog box to save the IDispatch subclass definition.



OLE data types The following table describes the data types that OLE recognizes:

Data type Description

void OLE equivalent to Smalltalk’s nil. Use this type only when specifying a method’s return value.

long A 32-bit integer.

short A 16-bit integer.

Boolean Returns true or false. It is returned to Smalltalk as a Boolean object.

float A floating point number with single precision.

double A floating point number with double precision (Smalltalk Float class).

char A single character (Smalltalk class Character).

BSTR A string that is prefixed by its length. It is not null terminated.

CURRENCY An 8-byte fixed number, which is returned to Smalltalk as a Point object.

DATE A timestamp object that is converted into the VT_DATE type.

HRESULT Specifies the type of an OLE error code. For more information about HRESULTs and error passing, see the following section, “Implementing business logic” on page 101.

LPDISPATCH Use when passing another IDispatch interface. An ObjectStudio OLE component server object can support several Automation interfaces at the same time. To pass a pointer to the client application for another Automation interface, use this data type.

OLE User’s Guide, P40-3805 101 Chapter: 5. Working with OLE component server services Section: Implementing business logic

Implementing business logic After you create a subclass of OLESrvObject and you subclass the interfaces, you can implement the Smalltalk code that supports the purpose of the component object.

The OLE Server Object Manager does not provide direct support for this step because it is specific to the component. For help with this process, you can:

1. Highlight the component in the OLE Server Object Manager.

2. Select File > Edit from the OLE Server Object Manager menu.

The OLE Server Object Manager opens a custom Class Browser loaded with only the classes for your component.

You can use the text-editing capabilities of the Class Browser to add logic to the component. Also, you can use an external editor.

Regardless of how you implement component logic, ensure that you implement methods and properties that you specified when you created the IDispatch interface in the OLESrvObject subclass that supports the object.

OLE User’s Guide, P40-3805 102 Chapter: 5. Working with OLE component server services Section: Preparing to run the server

Preparing to run the server At some point during development, you may want to run your component object. Before you run the component, you need to do the following tasks, which are described in more detail in the sections that follow:

♦ Register the component. You must register the component with the OLE Registry. The OLE Registry keeps track of all OLE-enabled applications and components on your system. There are two ways to register the component: from ObjectStudio and from a registration (.reg) file.

- Registering the component from ObjectStudio:

1. Select Tools > OLE Server Object Manager from the Desktop menu.

2. Highlight the name of component object in the OLE Server Object Manager list box.

3. Select File > Update from the OLE Server Object Manager menu.

The system displays a message informing you that the component was registered. In this case, the component server application is listed as ostudio.exe. Other OLE-enabled software is now able to communicate with your component.

Users do not have to take special steps to register the component when they install it. It is registered automatically the first time it is invoked. For more information, see Generate an image.

OLE User’s Guide, P40-3805 103 Chapter: 5. Working with OLE component server services Section: Preparing to run the server

- Registering the component from a registration (.reg) file—Create a registration (.reg) file and then execute this registration file on the OLE client’s machine. This will register the component on the OLE client’s machine.

To produce a registration file for the component, perform the following steps on the component’s machine:

A. In the OLE Server Object Manager, select the desired OLE Automation server from the Served Objects scrolling list box.

B. Select the File > Generate menu option.


C. Using the Save As dialog box, save the registration file to the desired location.

To register the component on the OLE client’s machine:

A. Copy the newly saved registration file to the OLE client’s machine.

B. On the OLE client’s machine, execute the registration file.

The component is now registered on the OLE client’s machine.

♦ Allow instantiation of the component. Once you register the component, you must instruct the OLE Class Factory to allow instantiation of the component object. To do so, select the object in the Served Objects list box, then select File > Register Class Factory from the OLE Server Object Manager menu. This step is required before client applications can create instances of the component object and communicate with it.

♦ Generate an image. When you finish coding and testing the ObjectStudio component object, you can include it in an application that you create with the Program Generator. The first time that you run the application, the system automatically registers any OLE components that the application contains. The system also automatically registers any OLE components in images that you save.

Once you do these tasks, you can run the component from the ObjectStudio development environment without generating a standalone component.


Creating a simple OLE server This section describes how to create a simple OLE server in ObjectStudio. After you create the server, you can use it to translate words from one language to another. You can also add words to the translator. The server’s client can be another ObjectStudio process or a process written with another tool.

Overview of steps The demo consists of the following steps:

The demo takes about an hour.

1. Create an OLE Server class from the OLE Server template.

2. Create an IDataObject interface class from a template.

3. Create an IDispatch interface class from a template.

4. Add code to the IDataObject class.

5. Add code to the OLE Server class.

6. Register the server.

7. Test the server using ObjectStudio as the client.

8. Test the server using a Visual Basic application as the client.

Before you start, recall that a template is a tool that helps you create classes. This section provides all of the information that you need to use the templates required for this demo. For more information about templates, refer to the ObjectStudio User’s Guide, P40-3807.

Chapter: 5. Working with OLE component server services Section: Creating a simple OLE server


If you need assistance

The following table describes and lists the names of the classes that you build in this demo. You can find completed versions of these classes in the ole_demo package.

Class description Class name

Translation server object OLETranslator

IDataObject interface class OLETranslatorIDataObject

IDispatch interface class OLETranslatorIDispatch

The ole_demo folder contains completed class files for the demo. The following table describes and lists the names of the files that you build in this demo and lists the names of the corresponding files in the ole_demo folder:

File description File you create File in ole_demo

Translation server object translat.cls transobj.cls

IDataObject interface class tidataob.cls transd.cls

IDispatch interface class tidispa.cls transdsp.cls



Creating an OLE Server class In this section, you create a class that implements the OLE server, which acts as a translator.

To create a class that implements the OLE server:

1. Select Tools > OLE Server Object Manager from the Desktop menu.

The OLE Server Object Manager appears, as shown here:



2. Select File > New Object from the OLE Server Object Manager.

The Create OLE Server Object dialog box appears, as shown here:

The Create OLE Server Object dialog box is the user interface for the Server Object template. Use this dialog box to create the OLE Server class.

3. Fill in fields on the Create OLE Server Object dialog box, as described in the following table:

Field Value

Class Name OLETranslator

Program ID ObjectStudio.Translator

Long Type Name ObjectStudio Translator

Short Type Name Translate

Class ID The value is supplied; for example: {44130EC0-2599-11D3-A018-00C04F800B7B}

You have now done most of the work of creating an OLE Server class named OLETranslator.

Do not save the class now. Continue working through the demo and save the class when you are prompted to do so in “Saving the OLE Server class” on page 114.



Creating an IDataObject interface class Information here describes how to create interface classes for the OLE Server. An interface is an OLE feature that allows clients to execute server functions.

To create the IDataObject interface class, continue working with the Create OLE Server Object dialog box, and do the following:

1. Select IDataObject from the OLE Interfaces and Classes drop-down list box in the Interface Map group.

2. Click New.

The Create OLE IDataObject Interface dialog box appears, as shown here:

The Create OLE IDataObject Interface dialog box is the user interface for

the OLE Server IDataObject template.

3. Type the following in the Smalltalk Class Name field:

OLETranslatorIDataObject

4. Select CF_TEXT from the Supported Get Formats list box.

5. Select CF_TEXT from the Supported Set Formats list box.

6. Click OK.




7. Save the class to a file (for example, tidataob.cls).

ObjectStudio saves the new class. It redisplays the Create OLE Server Object dialog box. The new class you created is listed in the OLE Interfaces and Classes drop-down list box.

9. Select the new class, OLETranslatorIDataObject, in the OLE Interfaces and Classes drop-down list box.

10. Click Add.

ObjectStudio updates the Interface Map list with the name of the interface (IDataObject) and the name of its supporting class (OLETranslatorIDataObject), as shown here:

Keep the Create OLE Server Object dialog box open and continue the demo.



Creating an IDispatch interface class To create the IDispatch interface class, continue working with the Create OLE Server Object dialog box, and do the following:

1. Select IDispatch from the OLE Interfaces and Classes drop-down list box in the Interface Map topic box.

2. Click New.

The Create OLE Automation Server Object dialog box appears, as shown here:

The Create OLE Automation Server Object dialog box is the user interface

for the OLE Server IDispatch template.

3. In the Class Name field, type the following:

OLETranslatorIDispatch

4. Add a method as described in the next procedure, “Adding a method.”



Adding a method To add a method to the class:

1. Click Add Method to display the Add Method dialog box, as shown here:

2. Fill in the fields as described in the following table:

Field Value

External Method Name translate

Internal Method Name translate:

Return Type BSTR

3. In the Parameters section, fill in fields as described in the following table:

Field Value

Name Word

Type BSTR

4. Click Add.

ObjectStudio adds the word parameter to the Parameters list box.



5. Click OK.

ObjectStudio redisplays the Create OLE Automation Server Object dialog box. The translate method is listed in the Interface Members list.

6. Add a property as described in the next procedure, “Adding a property.”

Adding a property To add a property to the class:

1. Click Add Property to display the Add Property dialog box, as shown here:

2. Fill in the fields as described in the following table:

Field Value

Property Name reverse

Property Type boolean

Get Method Name reverse

Set Method Name reverse:

3. Click OK.

ObjectStudio redisplays the Create OLE Automation Server Object dialog box, listing the reverse property in the Interface Members list.

4. Save the interface class as described in the next procedure.



Saving the interface class To save the IDispatch interface class:

1. Click OK on the Create OLE Automation Server Object dialog box.


2. Save the class to a file (for example, tidispa.cls).

ObjectStudio saves the new class and redisplays the Create OLE Server Object dialog box. The OLE Interfaces and Classes drop-down list box contains the new class.

3. Select the new class, OLETranslatorIDispatch, from the OLE Interfaces and Classes drop-down list box.

5. Click Add on the Create OLE Server Object dialog box.

The Interface Map list box appears, as shown here:

ObjectStudio updates the Interface Map list with the name of the interface (IDispatch) and the name of the new class (OLETranslatorIDispatch).


OLE User’s Guide, P40-3805 114 Chapter: 5. Working with OLE component server services Section: Creating a simple OLE server

Saving the OLE Server class After you create an OLE Server class, you need to save it.

To save the OLE Server class:

1. Click OK on the Create OLE Server Object dialog box.


2. Save the class to the file translat.cls.

3. Click Save on the Save As dialog box.

ObjectStudio displays ObjectStudio Translator in the Served Objects list box on the OLE Server Object Manager.

Adding code to the IDataObject class Information here describes how to add code to the OLETranslatorIDataObject interface class that you created in “Creating an IDataObject interface class” on page 108.

To add code to the IDataObject class:

1. Select File > Edit Class from the OLE Server Object Manager menu.

ObjectStudio displays a Class Browser that includes only the classes that pertain to the server object that you are creating. You may want to browse through the classes to see the code that ObjectStudio generates as a result of your working with the templates.

2. Select OLETranslatorIDataObject from the Class Browser class list.

3. Select the onGetDataFormat:returnData: instance method.

4. Replace the method’s code with the following code:

onGetDataFormat: format returnData: dataParameter format == CF_TEXT ifTrue: [ dataParameter value: (self srvObject dictionary). ^S_OK. ]. ^E_INVALIDARG.

5. Select Method > Save from the Class Browser menu.

6. Select the onSetData: instance method.


7. Replace the method’s code with the following code:

onSetData: value | arr | (value isKindOf: String) ifTrue: [ arr := value asArrayOfSubstrings. srvObject newWord: (arr at: 1) translation: (arr at: 2). ^S_OK. ]. ^E_INVALIDARG.

8. Select Method > Save from the Class Browser menu.

You have now added the necessary code to the OLETranslatorIDataObject class.

Adding code to the OLE Server class Here, you add instance variables and methods to the OLETranslator class. For all of these tasks, continue to use the same Class Browser that you used earlier.

Adding instance variables To add instance variables:

1. Select the OLETranslator class from the class list in the Class Browser.

2. Select Class > Definition from the Class Browser menu to display the Class Definition form.

3. Add the following instance variables to the class:

dictionary

reverse

4. Click OK.


Adding instance methods Create the following instance methods in class OLETranslator using the Class Browser:

♦ create. This method is similar to an initialize method, and is called when an instance of the class is created. Add the create method, using the following code:

create dictionary := IdentityDictionary new. dictionary at: #MONITOR put: #BILDSCHRIM. dictionary at: #TREE put: #BAUM. dictionary at: #STREET put: #STRASSE. dictionary at: #EARTH put: #ERDE. dictionary at: #MOUNTAIN put: #BERG. dictionary at: #CLIMB put: #STEIGEN. dictionary at: #TRUCK put: #LASTWAGEN. dictionary at: #LANDSCAPE put: #LANDSCHAFT. reverse := false.

♦ dictionary. This method returns the value stored in the dictionary variable as a store string. Add the dictionary method, using the following code:

dictionary ^ dictionary store.

♦ newWord:translation:. This method returns the value stored in the dictionary variable. Add the newWord:translation: method, using the following code:

newWord: word translation: translation dictionary at: word asUpperCase asSymbol put: translation asUpperCase asSymbol.

♦ reverse. This method is the get method for the reverse instance variable. Add the reverse method, using the following code:

reverse

^ reverse.

♦ reverse:. This method is the set method for the reverse instance variable. Add the reverse: method, using the following code:

reverse: value

reverse := value.


♦ translate:. This method retrieves the translation of the word that is passed to it as a parameter. Add the translate: method, using the following code:

translate: word reverse ifFalse: [

^ (dictionary at: word asUpperCase asSymbol) asString. ] ifTrue: [

^ (dictionary keyAtValue: word asUpperCase asSymbol) asString.

].

You have now added the necessary code to the OLETranslator class. You can close the Class Browser.

Registering the server To use the server, register it with the system:

1. Select ObjectStudio Translator from the Served Objects list box on the OLE Server Object Manager.

2. Select File > Update Registry from the menu.

A message appears in the status line that says that the registry is updated.

3. Select File > Register Class Factory from the menu.

A message appears in the status line that says that the class factory is registered.


Testing the server using ObjectStudio as the client You can test the Translate OLE Server by using ObjectStudio as a client. The basic technique is:

1. Start a second ObjectStudio process.

2. Open the Workspace.

3. Open the System Transcript.

4. Execute code in the Workspace.

5. Observe the results in the System Transcript window.

Shortcut Code is listed here to type and execute in the Workspace. Also, you can load the same code into the Workspace and execute it all at once by performing the following steps:

1. Select File ⇒ Open from the Workspace menu.

The Open dialog box appears.

2. Select the trans.sm file in the ole_demo folder.

3. Click OK.

ObjectStudio loads the file into the Workspace but does not execute any of the code.

4. Select all of the code in the Workspace.

5. Select Smalltalk > Execute on the Workspace menu to execute the code.

Global versus local variables The code in trans.sm uses local variables (the variables start with a lowercase letter). If you load trans.sm and execute all of the code at once, no errors result. You may want to execute only a few lines at a time. In this case, the System Transcript produces warning messages about the variables, which you can ignore safely.

The code listed here uses global variables (the variables start with an uppercase letter) but is otherwise identical to the code in trans.sm. If you choose to type and execute the code shown in the following discussion, you will not get error messages about variables. However, the global variables that you use persist in the ObjectStudio environment until you end the ObjectStudio session.


Code to execute The next few paragraphs describe the steps and list the lines of code that you can execute to test the OLE Server. Recall that you execute the code from the Workspace in the second ObjectStudio process.

1. Create an OLE server by creating an instance of the Translator.

OLEObj := OLEObject newProgId: #'ObjectStudio.Translator'.

2. Create the data transfer object and add a new word to the dictionary.

DtObj := OLEObj dataTransferObject.

DtObj getTextData out.

DtObj setData: 'Wall Wand'.

DtObj getTextData out.

3. Get a dispatcher and translate some words.

Dispatcher := OLEObj dispatcher.

(Dispatcher call: 'translate' params: {'Tree'}) out.

(Dispatcher call: 'translate' params: {'Wall'}) out.

4. Set the reverse property and try translating in the other direction.

Dispatcher at: 'reverse' put: true. (Dispatcher call: 'translate' params: {'Baum'}) out. (Dispatcher call: 'translate' params: {'Wand'}) out.

5. When you are done, set DtObj to nil so that the OLE object can be released.

DtObj := nil.

Close the ObjectStudio process that you used as a client when you are done testing.


Testing the server using a Visual Basic application as the client You can test the Translate OLE Server by using a Visual Basic application as the client.

To test the Translate OLE Server:

1. Run trans.exe that is located in the ole_demo folder.

A Visual Basic controller opens.

2. In the Word entry field, type a word to translate, for example, TREE.

3. Click Translate Word.

The controller should display the word BAUM in the Translation field.

4. Check the Reverse Translation check box.

5. In the Word entry field, type a word to translate, for example, BAUM.

6. Click Translate Word.

The controller displays the word TREE in the Translation field.

7. Close the VB Controller when you are done testing.

OLE User’s Guide, P40-3805 121 Chapter: 6. OCX licensing Section: Introduction

6. OCX licensing Introduction

ObjectStudio licensing uses the licensing facilities provided by the OCX custom control, such as the IClassFactory2 OLE interface.

The IClassFactory2 OLE interface uses a license key to implement licensing. If your application includes a custom control with a license key, ObjectStudio embeds this license key in your application. Then, when you distribute the application, the license key will be distributed with it.

The license key for the IClassFactory2 OLE interface determines whether the license is valid depending upon the OCX custom control’s state or mode, as described in the following section:

OCX custom control modes An OCX custom control has the following two modes:

♦ Edit-time. When you are developing your application in ObjectStudio and place an OCX custom control on a form, the OCX custom control is in edit-time mode. In this mode you can resize and reposition the control on the form, change properties and methods, and write code that will respond to events.

When the OCX custom control is in edit mode, you can set and manipulate ambient properties. The OCX custom control, however, does not fire any events because it is not in run-time mode.

♦ Run-time. In run-time mode, the OCX custom control receives messages and properties and fires events. To perform these tasks, you or the users of your application must have a run-time license.


ObjectStudio/OCX licensing ObjectStudio uses the following procedures in the licensing of OCX custom controls for each mode. These procedures are in accordance with the OLE IClassFactory2 interface.

Edit-time mode When you are developing your application in edit-time mode, ObjectStudio and the OCX custom control perform the following steps:

1. When you place an OCX custom control on a Designer form, ObjectStudio requests the license key from the OCX custom control by checking the LICINFO structure to verify if the fLicVerified and fRuntime elements are set to true.

2. The OCX custom control gets its license information from the registry or a file, depending upon the control’s implementation.

3. The OCX custom control then sends the license key (an IClassFactory2 pointer) to ObjectStudio via OLE.

The following figure illustrates steps 1–3:

Chapter: 6. OCX licensing Section: ObjectStudio/OCX licensing

ObjectStudio requestslicense key Registry

Form OCX File

OLE

returnslicense key


4. If the license key if valid, ObjectStudio requests an instance from the OCX custom control and provides the license key.

5. The OCX custom control creates an instance on this machine.

6. The OCX custom control returns a reference of the instance to ObjectStudio.

7. ObjectStudio stores the valid license key in a class method of the OCX custom control. The following figure illustrates steps 4–7:

Starting with version 8.2.1, ObjectStudio is Unicode based. OLE controllerItems created with prior versions of ObjectStudio should be loaded in this version and saved so as to create the correct format and contents of the prj file.



Run-time mode When you are deploying your application in run-time mode, ObjectStudio and the OCX custom control perform the following steps:

1. When a user executes the ObjectStudio application, the OCX custom control writes the license key to a temporary .PRJ file in the following location:

- For Windows XP, it is in C:\Documents and Settings\<USERNAME>\Local Settings\Temp\ObjectStudioX\OLElicenses

- For Windows 7 and Vista, it is in C:\Users\<Username>\AppData\Local\Temp\ObjectStudioxxx\OLElicenses where xxx is the version of ObjectStudio (for example, 8.2.1 or 8.3)

2. ObjectStudio passes it to the OCX custom control. If the license key is not valid, ObjectStudio notifies the user that a run-time key is unavailable and does not insert the control into the form.

3. If the license key is valid, the OCX custom control creates an instance on this machine.

4. The OCX custom control returns a reference of the instance to ObjectStudio.

The following figure illustrates these steps:


OLE User’s Guide, P40-3805 125 Chapter: 6. OCX licensing Section: Incorporating licensing

Incorporating licensing You can incorporate licensing by using the IClassFactory2 OLE interface, as described in the following sections.

Incorporating a run-time license To incorporate only a run-time license:

1. Create your application using the OCX custom control, which automatically stores the license key in a class method of the OCX custom control.

2. Ship your application, the OCX control, and any other files required by the control, such as DLLs.

Because the license key provides only a run-time license, the user will not be able to place the control in edit mode. The OCX custom control determines how this functionality is implemented.

Incorporating run-time and edit-time licenses To incorporate run-time and edit-time licenses:

1. Create your application using the OCX custom control, which automatically stores the license key in a class method of the OCX custom control.

2. Ship your application, the OCX control, the required licensing from the developer of the OCX custom control, and any other files required by the control, such as DLLs. See the manufacturer’s OCX custom control documentation.

OLE User’s Guide, P40-3805 126 Chapter: 6. OCX licensing Section: Distribution requirements

Distribution requirements To incorporate licensing, you must distribute the following items with your application:

♦ The ObjectStudio application. For information about creating ObjectStudio applications, refer to the ObjectStudio User’s Guide, P40-3807.

♦ All controls on the forms or used within the application.

You can distribute your application in such a manner that the user can edit a control in edit-time mode. Therefore, you are responsible for verifying that you are not violating any license agreement with the provider of the control, because the control will have to be distributed with the global licensing features. See the manufacturer’s OCX control documentation for further information about licensing.

OLE User’s Guide, P40-3805 127 Index

Index A

activate: instance method 31 activateUI: instance method

31 advise 77 advise:block: method 77 advise:cfFormat:block:

method 77 ambient properties

description 50 setting 52

asynchronous OLE event handling, selecting 39

Automation client

communicating with 78 object, creating 69

Controller description 66 implementing 68

data types 73 demo

description 62 running 60

description 14, 59, 66 Object 66

C

call:params: instance method 71

canPaste: class method 27 cCopyToClipboard instance

method 33 cGetIconicMetafile instance

method 33 cGetType instance method 33 cGetUserType: instance

method 34 Class Browser

OLE classes, browsing 16 opening 86

Class Factory instantiation, allowing 103 registering 86 revoking 86

class methods canPaste: 27 defaultOptions 33 getObject:progName: 69 in class FormEmbed 33 in class FormOLEControl 56 in class OLEObject 63 interfaceMap 90

classes controller 38 Form 37 FormEmbed 33 FormOLEControl 56 FormOLEItem 30, 31, 55 high-level helper 64 IDataObject interface,

creating 108 IDispatch interface, creating

110 InterfacePart 58 method, adding 111 OLE server

implementing 106 saving 114

properties, adding 112 Click event 53 client

communicating with 78 description 14

Clipboard 27 close: instance method 31 COM framework 8 component

description 10 object

creating 84, 86 description 9 implementing 101 including in an image 103 instantiation of 103

registering from a registration file

103 from ObjectStudio 102

services 11


Component Object Model. See COM framework

compound documents 14 container

default characteristics, setting 50

definition 19 Controller

class 38 client of Automation objects

66 createDefaultInPlaceMenu

instance method 34 createDefaultInPlaceMenuAt:

instance method 37 createDefaultInPlaceMenuFor

m: method 37 cSetSelection instance method

34 custom controls

adding to forms 46 customizing 47, 53 features 44 Fountain Fill 45 licensing 58 OCX 13 registering 45 responding to user

interaction 53 Smalltalk support for 55 using with Designer 45

D

Data Object Test dialog box, testing the Timer Server 82

Data Transfer. See Uniform Data Transfer

data types Automation 73 OLE 100 VT_DISPATCH 74

DataObjectTester icon 80 DCOM framework 8 defaultOptions class method

33 Designer, using custom

controls 45 Distributed Component Object

Model. See DCOM framework

documents, compound 14 doVerb: instance method 30,

31 drag and drop

description 13 embedding an OLE object 26

E

edit-time mode licensing 122 OCX 121

embedded object adding to form 19 saving 28

embedding description 12, 20 linking and

from Clipboard 27 Smalltalk support for 28

programmatically 29 using drag and drop 26

enabling OLE support 12 events

custom control 44

F

Form class 37 Form OLE Item Options dialog

box, opening 20 form, adding a custom control

46 form-based services 11 FormEmbed class

class methods 33 instance methods 33

FormOLEControl class class methods 56 instance methods 56 instance variable 56

FormOLEItem class description 55 instance methods 31 instance variables 30

Fountain Fill custom control 45


G

getDrawAspect instance method 34

getFEmbedHandle:form: instance method 38

getObject:progName: class method, creating Automation client 69

H

high-level helper class 64

I

IDataObject interface class, creating 108 creating 91 description 90

IDispatch interface class

creating 110 saving 113

creating 93 description 90 how it works 67 methods, adding 97 properties, adding 95

incoming methods 66 in-place activation. See visual

editing insertDirect:fileId: instance

method 34 insertDirect:fileId:handle:

instance method 34 insertDirectProgram: instance

method 35 inspector, for Uniform Data

Transfer Objects 80

instance methods activate: 31 activateUI: 31 cCopyToClipboard 33 cGetIconicMetafile 33 cGetType 33 cGetUsetType: 34 class OLETranslator, creating

116 close: 31 createDefaultInPlaceMenu

34 createDefaultInPlaceMenuAt

: 37 cSetSelection 34 doVerb: 30, 31 getDrawAspect 34 getFEmbedHandle:form: 38 in class Controller 38 in class Form 37 in class FormEmbed 33 in class FormOLEControl 56 in class FormOLEItem 31 insertDirect:fileId: 34 insertDirect:fileId:handle: 34 loadDocumentName: 37 methodNames 56 oleField: 31 oleMetaPict 35 oleMetaPict: 35 oleMiscFlag: 31 oleUsername: 32 onActivate: 32 onActivateUI: 32 onChange:param: 35 onDrop: 35 onDropDataObj:x:y:form: 38 onEditPaste:link:useDialog

27 onInsert: 35 onPaste: 35 open 35 propertyNames 57 remove 36 saveDocumentName: 37 serverOptions 36 serverOptions: 36 temporary 36 temporary: 36


instance variables adding to OLETranslator

class 115 in class FormOLEControl 56 in class FormOLEItem 30

instantiation 103 interface

IDataObject creating 91 description 90

IDispatch creating 93 description 90

Interface Map 89 Interface Members list box 99 interface object, editing 86 interfaceMap class method 90 interfaceName: message 65 InterfacePart class 58 Investment Advisor demo

description 62 running 60

K

keys, licensing 121

L

licensing custom controls 58 keys 121 OCX 121, 125

linking description 12, 20 from Clipboard 27

loadDocumentName: instance method 37

M

MDIWindowsController, merging menus 43

menu, merging during visual editing 43

messages interfaceName: 65 setData: 76

method call normal 71 with named arguments 72 with optional arguments 71

methodNames instance method 56

methods. See also class methods and instance methods

adding to classes 111 advise:block: 77 advise:cfFormat:block: 77 call:params: 71 class InterfacePart 58 createDefaultInPlaceMenuFo

rm: 37 custom control 44 IDispatch interface 97 invoking 71 saveDocumentName: 28 unadvise 77

N

named arguments 72

O

Object Description Language. See ODL

Object Enabled System Services 8

object-oriented programming 8

objects, resetting size during visual editing 43

ObjectStudio, using as a server 78

OCX custom control. See custom

controls licensing 121, 125

ODL 67


OLE classes 16 container 19 custom controls. See custom

controls data types 100 description 7 development overview 63 interface

description 90 retrieving 65

Investment Advisor demo description 62 running 60

loadable application 12 object

compared to Smalltalk object 10

embedding existing object 25

embedding new object 24 embedding with drag and

drop 26 linking 26 Uniform Data Transfer 75 working with properties

70 OCX licensing 121 server, creating 104 services 11 site 19 support, enabling 12

OLE 2.0. See OLE OLE Component Client

services 59 OLE event handling, selecting

synchronous or asynchronous 39

OLE Item form item embedding

existing OLE object in 25 new OLE object in 24

linking an OLE object to 26 placing on a form 20

OLE Registry, updating 86 OLE Server class

creating 106 saving 114

OLE Server Object Manager OLESrvObject, creating

subclass 87 overview 85 toolbar description 86

OLEDataTransfer class 75 object, creating 75

OLEDispatcher Automation client, creating

69 type conversion 73

oleFileId: instance method 31 oleMetaPict instance method

35 oleMetaPict: instance method

35 oleMiscFlag: instance method

31 OLEObject

Automation client, creating 69

class methods 63 data

getting from the instance 76

setting in the instance 76 instance, creating 63 interacting with 64

OLESrvObject Smalltalk code,

implementing 101 subclass, creating 87

OLETranslator class adding instance methods 116 adding instance variables

115 OLETranslatorIDataObject

interface class, adding code to 114

oleUsername: instance method 32

onActivate: instance method 32

onActivateUI: instance method 32

onChange:param: instance method 35


onDrop instance method 35 onDropDataObj:x:y:form:

instance method 38 onEditPaste:link:useDialog:

instance method 27 onInsert: instance method 35 onPaste instance method 35 open instance method 35 outgoing methods 66

P

parameters, specifying for a method 98

properties adding to class 112 custom control 44 description 66 IDispatch interface 95 object 70

propertyNames instance method 57

Q

querying 65

R

registration from a registration file 103 from ObjectStudio 102

Registry components in, registering

from a registration file 103

from ObjectStudio 102 server 117

remove instance method 36 run-time mode

licensing 124 OCX 121

S

saveDocumentName: instance method 28, 37

server description 14 implementing 106 ObjectStudio, using as a

server 78 OLE server, creating 104 preparing to run 102 registering 117 testing

using ObjectStudio 118 using Visual Basic

application 120 serverOptions instance

method 36 serverOptions: instance

method 36 setData: message 76 site 19 Smalltalk

embedded item, creating programmatically 29

objects vs. component objects 9

support for custom controls 55 embedding and linking 28 visual editing 43

storages 14 streams 14 Structured Storage 15 synchronous OLE event

handling, selecting 39


T

temporary instance method 36 temporary: instance method

36 Timer Server

instance, creating 81 testing 82

toolbar hiding during visual editing

42 OLE Server Object Manager

86 type conversion, in

OLEDispatcher 73 Type Library file

creating 86 IDispatch interface and 67

U

unadvise method 77 Uniform Data Transfer

client, communicating with 78

description 15 inspector for 80 using 75 working with 76

V

VBX. See Visual Basic controls Visual Basic controls 13 visual editing

activating 41 deactivating 41 description 12 menus, merging 43 object size, resetting 43 Smalltalk support for 43 toolbar, hiding 42

VT_DISPATCH data type 74