Cincom Smalltalk. ObjectStudio. OLE User s Guide P ObjectStudio 8.3

Transcription

1 Cincom Smalltalk ObjectStudio OLE User s Guide P ObjectStudio 8.3

2 Cincom Smalltalk ObjectStudio OLE User's Guide Publication Number P , 2001, 2003, 2005, 2006, 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 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 USA PHONE: (513) FAX: (513) WORLD WIDE WEB: 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.

3 Release information for this manual Cincom Smalltalk ObjectStudio OLE User's Guide, P , is dated February 16, This document supports Release 8.3 of ObjectStudio. Cincom Technical Support for ObjectStudio All customers Web: USA customers Phone: Fax: (513) Attn: ObjectStudio Support Mail: Cincom Systems, Inc. Attn: ObjectStudio Support 55 Merchant Street Cincinnati, OH USA Outside of USA All: Visit the support links at 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.

4 Contents 1. OLE overview... 7 What is OLE?... 7 OLE and object-oriented programming... 8 Component objects... 9 Object vocabulary Objects are packaged into components OLE services in ObjectStudio Enabling ObjectStudio OLE support Embedding, linking, and visual editing Drag and drop OLE custom controls Compound documents Component client and server services More about ObjectStudio as a server OLE classes Embedding, linking, and visual editing Introduction Containers and sites Using the Designer to embed and link objects How to embed and link an object Using the Insert Object dialog box Using drag and drop to embed objects Embedding and linking from the Clipboard Saving an embedded object Smalltalk support for embedding and linking Embedding in Smalltalk FormOLEItem class FormEmbed class Form class Controller class Selecting whether to process OLE data synchronously or asynchronously OLE event handling Configuring OLE event handling Visual editing Activating and deactivating visual editing Hiding the toolbar and merging menus Controlling size during visual editing Smalltalk support for visual editing OLE User s Guide, P Contents

5 3. Working with OLE custom controls What is an OLE custom control? Where to find custom controls How custom controls fit into OLE architecture How to use the Designer with custom controls Registering a control Adding a control to a form Customizing a control Setting ambient properties for a container Responding to user interaction Smalltalk support for custom controls FormOLEItem class FormOLEControl class InterfacePart class Notes about licensing Working with OLE component client services Using ObjectStudio as a client Loading the OLE demo files Running the OLE demo How the Automation demo works OLE development overview Creating an instance of OLEObject Interacting with the OLEObject Using OLE Automation Mechanics of OLE Automation IDispatch interface Implementing an Automation Controller Creating an Automation client object Working with an object s properties Invoking methods Type conversion Using Uniform Data Transfer Creating an OLEDataTransfer object Working with Uniform Data Transfer Setting data Getting data Working with advises Working with OLE component server services Using ObjectStudio as a server Loading the OLE demo server object files OLE User s Guide, P Contents

6 Inspecting an OLE object Starting the demo Creating an object Working with the timer server Creating an ObjectStudio component Using the OLE Server Object Manager Opening the OLE Server Object Manager Toolbar and menu Creating a subclass of OLESrvObject Create OLE Server Object dialog box: Upper portion Create OLE Server Object dialog box: Lower portion Subclassing interfaces OLE Server IDataObject interface OLE Server IDispatch interface OLE data types Implementing business logic Preparing to run the server Creating a simple OLE server Overview of steps If you need assistance Creating an OLE Server class Creating an IDataObject interface class Creating an IDispatch interface class Saving the OLE Server class Adding code to the IDataObject class Adding code to the OLE Server class Registering the server Testing the server using ObjectStudio as the client Testing the server using a Visual Basic application as the client OCX licensing Introduction OCX custom control modes ObjectStudio/OCX licensing Edit-time mode Run-time mode Incorporating licensing Incorporating a run-time license Incorporating run-time and edit-time licenses Distribution requirements Index OLE User s Guide, P Contents

7 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, P Chapter: 1. OLE overview Section: What is OLE?

8 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, P Chapter: 1. OLE overview Section: OLE and object-oriented programming

9 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, P Chapter: 1. OLE overview Section: Component objects

10 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, P Chapter: 1. OLE overview Section: Component objects

11 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, P Chapter: 1. OLE overview Section: OLE services in ObjectStudio

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 doubleclicks 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. OLE User s Guide, P Chapter: 1. OLE overview Section: OLE services in ObjectStudio

13 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. OLE User s Guide, P Chapter: 1. OLE overview Section: OLE services in ObjectStudio

14 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. OLE User s Guide, P Chapter: 1. OLE overview Section: OLE services in ObjectStudio

15 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, P Chapter: 1. OLE overview Section: OLE services in ObjectStudio

16 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, P 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, P Chapter: 1. OLE overview Section: OLE classes

17 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. OLE User s Guide, P Chapter: 1. OLE overview Section: OLE classes

18 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. OLE User s Guide, P Chapter: 2. Embedding, linking, and visual editing Section: Introduction

19 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. OLE User s Guide, P Chapter: 2. Embedding, linking, and visual editing Section: Containers and sites

20 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: OLE User s Guide, P Chapter: 2. Embedding, linking, and visual editing Section: Using the Designer to embed and link objects

21 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 Initial Server Size Move In-place Menu Server Size Resize Display as Icon Description 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. 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. 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. 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. 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. Instead of displaying the object, display an icon that represents the object. Visual editing occurs in a separate window from the ObjectStudio form. OLE User s Guide, P Chapter: 2. Embedding, linking, and visual editing Section: Using the Designer to embed and link objects

22 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 Create New Item Create From File Create From File and Linked Allows you to Embed an OLE item with no user data. Embed the OLE item specified in the Filename entry field with user data. 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. OLE User s Guide, P Chapter: 2. Embedding, linking, and visual editing Section: Using the Designer to embed and link objects

23 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: OLE User s Guide, P Chapter: 2. Embedding, linking, and visual editing Section: Using the Designer to embed and link objects

24 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. OLE User s Guide, P Chapter: 2. Embedding, linking, and visual editing Section: Using the Designer to embed and link objects

25 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. 7. Save and test your work. You also can do the previous procedure from the Form OLE Item Options dialog box by completing the Object Type and Class ID fields. OLE User s Guide, P Chapter: 2. Embedding, linking, and visual editing Section: Using the Designer to embed and link objects

26 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. 7. Save and test your work. 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. OLE User s Guide, P Chapter: 2. Embedding, linking, and visual editing Section: Using the Designer to embed and link objects

27 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. OLE User s Guide, P Chapter: 2. Embedding, linking, and visual editing Section: Using the Designer to embed and link objects

28 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. OLE User s Guide, P Chapter: 2. Embedding, linking, and visual editing Section: Smalltalk support for embedding and linking

29 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. OLE User s Guide, P Chapter: 2. Embedding, linking, and visual editing Section: Smalltalk support for embedding and linking

30 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. OLE User s Guide, P Chapter: 2. Embedding, linking, and visual editing Section: Smalltalk support for embedding and linking

31 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. OLE User s Guide, P Chapter: 2. Embedding, linking, and visual editing Section: Smalltalk support for embedding and linking

32 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. OLE User s Guide, P Chapter: 2. Embedding, linking, and visual editing Section: Smalltalk support for embedding and linking

33 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 OLE User s Guide, P Chapter: 2. Embedding, linking, and visual editing Section: Smalltalk support for embedding and linking

34 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. OLE User s Guide, P Chapter: 2. Embedding, linking, and visual editing Section: Smalltalk support for embedding and linking

35 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. OLE User s Guide, P Chapter: 2. Embedding, linking, and visual editing Section: Smalltalk support for embedding and linking

36 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 #InitialServerSize #ServerSize #Move #Resize #InPlaceMenu #DisplayAsIcon Meaning if included in the array 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. 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. 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. 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. When the user initiates visual editing (by doubleclicking the object), the object s application menus can merge with or replace the form s menus. 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. OLE User s Guide, P Chapter: 2. Embedding, linking, and visual editing Section: Smalltalk support for embedding and linking

37 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. OLE User s Guide, P Chapter: 2. Embedding, linking, and visual editing Section: Smalltalk support for embedding and linking

38 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, P Chapter: 2. Embedding, linking, and visual editing Section: Smalltalk support for embedding and linking

39 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. OLE User s Guide, P Chapter: 2. Embedding, linking, and visual editing Section: Selecting whether to process OLE data synchronously or asynchronously

40 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). OLE User s Guide, P Chapter: 2. Embedding, linking, and visual editing Section: Selecting whether to process OLE data synchronously or asynchronously

41 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. OLE User s Guide, P Chapter: 2. Embedding, linking, and visual editing Section: Visual editing

42 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. OLE User s Guide, P Chapter: 2. Embedding, linking, and visual editing Section: Visual editing

43 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, P Chapter: 2. Embedding, linking, and visual editing Section: Visual editing

44 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, P Chapter: 3. Working with OLE custom controls Section: What is an OLE custom control?

45 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. OLE User s Guide, P Chapter: 3. Working with OLE custom controls Section: How to use the Designer with custom controls

46 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. OLE User s Guide, P Chapter: 3. Working with OLE custom controls Section: How to use the Designer with custom controls

47 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: OLE User s Guide, P Chapter: 3. Working with OLE custom controls Section: How to use the Designer with custom controls

48 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. OLE User s Guide, P Chapter: 3. Working with OLE custom controls Section: How to use the Designer with custom controls

49 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: OLE User s Guide, P Chapter: 3. Working with OLE custom controls Section: How to use the Designer with custom controls

50 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. OLE User s Guide, P Chapter: 3. Working with OLE custom controls Section: How to use the Designer with custom controls

51 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. OLE User s Guide, P Chapter: 3. Working with OLE custom controls Section: How to use the Designer with custom controls

52 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. OLE User s Guide, P Chapter: 3. Working with OLE custom controls Section: How to use the Designer with custom controls

53 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, P 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. OLE User s Guide, P Chapter: 3. Working with OLE custom controls Section: How to use the Designer with custom controls

54 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, P Chapter: 3. Working with OLE custom controls Section: How to use the Designer with custom controls

55 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. OLE User s Guide, P Chapter: 3. Working with OLE custom controls Section: Smalltalk support for custom controls

56 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. OLE User s Guide, P Chapter: 3. Working with OLE custom controls Section: Smalltalk support for custom controls

57 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. OLE User s Guide, P Chapter: 3. Working with OLE custom controls Section: Smalltalk support for custom controls

58 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. OLE User s Guide, P Chapter: 3. Working with OLE custom controls Section: Smalltalk support for custom controls

59 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 OLE User s Guide, P Chapter: 4. Working with OLE component client services Section: Using ObjectStudio as a client

60 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, P Chapter: 4. Working with OLE component client services Section: Using ObjectStudio as a client

61 3. Click the Service Change button. The ObjectStudio Customer Service dialog box that contains information about the customer you selected appears, as shown here: OLE User s Guide, P Chapter: 4. Working with OLE component client services Section: Using ObjectStudio as a client

62 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 OLE User s Guide, P Chapter: 4. Working with OLE component client services Section: Using ObjectStudio as a client

63 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. OLE User s Guide, P Chapter: 4. Working with OLE component client services Section: OLE development overview

64 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. OLE User s Guide, P Chapter: 4. Working with OLE component client services Section: OLE development overview

65 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, P Chapter: 4. Working with OLE component client services Section: OLE development overview

66 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. OLE User s Guide, P Chapter: 4. Working with OLE component client services Section: Using OLE Automation

67 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. OLE User s Guide, P Chapter: 4. Working with OLE component client services Section: Using OLE Automation

68 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 OLE User s Guide, P Chapter: 4. Working with OLE component client services Section: Using OLE Automation

69 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. OLE User s Guide, P Chapter: 4. Working with OLE component client services Section: Using OLE Automation

70 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'). OLE User s Guide, P Chapter: 4. Working with OLE component client services Section: Using OLE Automation

71 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'}. OLE User s Guide, P Chapter: 4. Working with OLE component client services Section: Using OLE Automation

72 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'}}. OLE User s Guide, P Chapter: 4. Working with OLE component client services Section: Using OLE Automation

73 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 OLE User s Guide, P Chapter: 4. Working with OLE component client services Section: Using OLE Automation

74 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, P Chapter: 4. Working with OLE component client services Section: Using OLE Automation

75 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. OLE User s Guide, P Chapter: 4. Working with OLE component client services Section: Using Uniform Data Transfer

76 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 gettextdata getbitmapdata getmetafiledata Returns an instance of Class String or Message Bitmap or Message MetaFile or Message OLE User s Guide, P Chapter: 4. Working with OLE component client services Section: Using Uniform Data Transfer

77 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, P Chapter: 4. Working with OLE component client services Section: Using Uniform Data Transfer

78 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. OLE User s Guide, P Chapter: 5. Working with OLE component server services Section: Using ObjectStudio as a server

79 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. OLE User s Guide, P Chapter: 5. Working with OLE component server services Section: Using ObjectStudio as a server

80 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: OLE User s Guide, P Chapter: 5. Working with OLE component server services Section: Inspecting an OLE object

81 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. OLE User s Guide, P Chapter: 5. Working with OLE component server services Section: Inspecting an OLE object

82 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. OLE User s Guide, P Chapter: 5. Working with OLE component server services Section: Inspecting an OLE object

83 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, P Chapter: 5. Working with OLE component server services Section: Inspecting an OLE object

84 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 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 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 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. OLE User s Guide, P Chapter: 5. Working with OLE component server services Section: Creating an ObjectStudio component

85 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: OLE User s Guide, P Chapter: 5. Working with OLE component server services Section: Using the OLE Server Object Manager

86 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. OLE User s Guide, P Chapter: 5. Working with OLE component server services Section: Using the OLE Server Object Manager

87 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 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. OLE User s Guide, P Chapter: 5. Working with OLE component server services Section: Creating a subclass of OLESrvObject

88 Create OLE Server Object dialog box: Upper portion The upper portion of the dialog box contains the items described in the following table: Field Class Name Program ID Class ID Long Type Name Short Type Name Multiple Instances Meaning 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. 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. 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. A descriptive name of the component that the system registers. Applications often display the long name instead of the program ID. A short descriptive name of the component. If multiple users might access the ObjectStudio OLE Server Component at the same time, then leave this check box checked. OLE User s Guide, P Chapter: 5. Working with OLE component server services Section: Creating a subclass of OLESrvObject

89 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, P Chapter: 5. Working with OLE component server services Section: Creating a subclass of OLESrvObject

90 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 IdataObject (Data Transfer) Idispatch (Automation) When You need to exchange data between your component and a requesting client. 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 User s Guide, P Chapter: 5. Working with OLE component server services Section: Subclassing interfaces

91 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: OLE User s Guide, P Chapter: 5. Working with OLE component server services Section: Subclassing interfaces

92 The following table describes the fields on the Create OLE IDataObject Interface dialog box: Field Smalltalk Class Name Supported Get Formats Supported Set Formats Meaning 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). 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. 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 User s Guide, P Chapter: 5. Working with OLE component server services Section: Subclassing interfaces

93 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: OLE User s Guide, P Chapter: 5. Working with OLE component server services Section: Subclassing interfaces

94 The following table describes the fields on the Create OLE Automation Server Object dialog box: Item Class Name Library Name Help String Interface Members Meaning 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). The external name by which other (client) applications refer to this Automation interface. It can be different from the Class Name. An optional string that contains the purpose of this Automation interface. External (client) applications query the Help String. 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. OLE User s Guide, P Chapter: 5. Working with OLE component server services Section: Subclassing interfaces

95 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. OLE User s Guide, P Chapter: 5. Working with OLE component server services Section: Subclassing interfaces

96 Field The following table describes the fields on the Add Property dialog box: Property Name Property Type Get Method Name Set Method Name Default Property Meaning An identifier that describes the property. The data type of the property, as described in OLE data types on page 100. 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. 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. 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. OLE User s Guide, P Chapter: 5. Working with OLE component server services Section: Subclassing interfaces

97 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. OLE User s Guide, P Chapter: 5. Working with OLE component server services Section: Subclassing interfaces

98 The following table describes the fields on the Add Method dialog box: Field External Method Name Internal Method Name Return Type Parameters Parameter Name Parameter Type Meaning 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. 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. 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. A list of the method s parameters. The name of the parameter. Naming conventions follow standard Smalltalk guidelines. 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. OLE User s Guide, P Chapter: 5. Working with OLE component server services Section: Subclassing interfaces

99 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 User s Guide, P Chapter: 5. Working with OLE component server services Section: Subclassing interfaces

100 OLE data types The following table describes the data types that OLE recognizes: Data type void long short Boolean float double char BSTR CURRENCY DATE HRESULT LPDISPATCH Description OLE equivalent to Smalltalk s nil. Use this type only when specifying a method s return value. A 32-bit integer. A 16-bit integer. Returns true or false. It is returned to Smalltalk as a Boolean object. A floating point number with single precision. A floating point number with double precision (Smalltalk Float class). A single character (Smalltalk class Character). A string that is prefixed by its length. It is not null terminated. An 8-byte fixed number, which is returned to Smalltalk as a Point object. A timestamp object that is converted into the VT_DATE type. 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. 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, P Chapter: 5. Working with OLE component server services Section: Subclassing interfaces

101 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, P Chapter: 5. Working with OLE component server services Section: Implementing business logic

102 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, P Chapter: 5. Working with OLE component server services Section: Preparing to run the server

103 - 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. The Save As dialog box appears. 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. OLE User s Guide, P Chapter: 5. Working with OLE component server services Section: Preparing to run the server

104 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, P OLE User s Guide, P Chapter: 5. Working with OLE component server services Section: Creating a simple OLE server

105 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 Translation server object IDataObject interface class IDispatch interface class Class name OLETranslator OLETranslatorIDataObject 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 OLE User s Guide, P Chapter: 5. Working with OLE component server services Section: Creating a simple OLE server

106 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: OLE User s Guide, P Chapter: 5. Working with OLE component server services Section: Creating a simple OLE server

107 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 Class Name Program ID Long Type Name Short Type Name Class ID Value OLETranslator ObjectStudio.Translator ObjectStudio Translator Translate The value is supplied; for example: {44130EC D3-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. OLE User s Guide, P Chapter: 5. Working with OLE component server services Section: Creating a simple OLE server

108 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. The Save As dialog box appears. OLE User s Guide, P Chapter: 5. Working with OLE component server services Section: Creating a simple OLE server

109 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. OLE User s Guide, P Chapter: 5. Working with OLE component server services Section: Creating a simple OLE server

110 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. OLE User s Guide, P Chapter: 5. Working with OLE component server services Section: Creating a simple OLE server

111 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. OLE User s Guide, P Chapter: 5. Working with OLE component server services Section: Creating a simple OLE server

112 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. OLE User s Guide, P Chapter: 5. Working with OLE component server services Section: Creating a simple OLE server

113 Saving the interface class To save the IDispatch interface class: 1. Click OK on the Create OLE Automation Server Object dialog box. The Save As dialog box appears. 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, P Chapter: 5. Working with OLE component server services Section: Creating a simple OLE server