ActiveX Controls

1. ActiveX Controls Jim Fawcett CSE775 – Distributed Objects Spring 2004

2. ActiveX Controls • Controls Have a User Interface • Controls know about events, properties, and automation

4. ActiveX Events • windows events: • start in the raw system event queue • get passed to the window manager • to the handling window • inserted into the window message queue • get processed when the window gets to it in the queue • For ActiveX events: • interested observers register with the control for notification • registration consists of sending a callback for an event handler • when the event occurs the control “calls the observer back” • the mechanisms to do this are based on connectable object interfaces.

5. ActiveX Properties • Properties are persistent scalar values which can be read and written by a control’s container and/or program user. • Often the container also has “ambient” properties which the control is expected to adopt at start up. • ActiveX controls support the notion of property pages which allow a control’s properties to be examined and modified in a standard way through a standard user interface. • A control’s properties are accessed through an IDispatch inter-face.

6. Automation - IDispatch Interface • Allows scripting languages, which don’t know anything about interface pointers, to make calls to COM components • GetTypeInfoCount type info avail? • GetTypeInfo returns pointer to type info • GetIDsOfNames get index of method to call • invoke call method through a dispatch table using - DISPPARAMS structure - DISPID

7. ActiveX Control Functionality • A control is: • A COM object: • A User Interface: • Createable • A control usually has: • Properties, both stock and custom • Event callbacks, both stock and custom • Property change notification • On-demand rendering of a view • Support for containers: OLE control and in-place activation • Persistance support • Windowless activation: an initialization optimization • Object safety settings • Drag and Drop support • Graphical editing of its properties • Support for arranging properties by category • Default keyboard handling: tabbing, arrow keys, help

8. ActiveX Control in Container

9. Relationship between ActiveX Control and its Container

10. Invoking a Control’s Methods

14. Connection Points

16. Embedding Control in Container • Controls usually participate in building container’s user interface. • The container supports in-place activation of control. • The control uses a data cache object to store a static image of itself, used by container before the control is activated. • Container supports one client site object for each embedded control. • The control stores any persistent data in container’s document.

17. Loading Container • When container is loaded it loads a data cache object handler to render a static image of the control • container uses control’s IPersistStorage interface to supply a pointer to the container’s storage containing control’s cached view • data cache object loads the view • container uses the control’s IViewObject2 interface to get the data cache object to draw cached view at a container specified location • The container renders the rest of its view on its main frame window • If no user action (mouse click for example) activates the control it is never loaded

18. Activating the Control • When a user action activates the control: • container invokes IOleObject::DoVerb on its IOleObject representation of the control • OLEIVERB_PRIMARY, OLEIVERB_SHOW, OLEIVERB_OPEN, OLEIVERB_HIDE, OLEIVERB_UIACTIVATE, OLEIVERB_INPLACEACTIVATE, OLEIVERB_DISCARDUNDOSTATE • container’s IOleObject calls CoCreateInstance for the control using its CLSID saved in the container’s persistent storage • container’s IOleObject uses the control’s IPersistStorage to give it a pointer to the container’s storage • The control loads its persistant data from storage • The container’s IOleObject now calls control’s IOleObject::DoVerb which creates control’s window and starts processing messages

19. Modifying Container and Control State • Container’s IOleObject invokes control’s IDataObject::DAdvise passing a pointer to container’s IAdviseSink interface so control can update container. • When user interacts with control to change its state: • the control is an in-proc component, in the process of the container, and so may up-date its own window • the control uses IAdviseSink::OnDataChange to update container as needed by the application • The container communicates with the control through its IDispatch interface.

20. ActiveX Control Events • A control can also communicate with its container, and other interested components as well, through events. • A control can define a set of events • its container would then be expected to provide a way to react to each received event • events are methods that a control invokes on its container • to make this work the control must acquire a pointer to an interface supported by the container with methods that match the events the control wants to send • We say that the control supports a source interface for events and the container must provide a sink for that interface.

21. Establishing Events Connections • Both a control’s events and its methods are defined in dispinterfaces, accessed via IDispatch. • the control must provide a type library describing both its incoming (method) and outgoing (event) interfaces. • a container can read the type library to learn what methods and events it supports • the events are simply methods the control knows how to invoke • the container must dynamically create an IDispatch::invoke that supports those methods • it can do that because the methods and parameters are described by dispIDs in the the controls type library

22. Acquiring a Connection • The container calls control’s IProvideClassInfo2::GetClassInfo: • it acquires a pointer to an ITypeInfo object describing the control’s coclass that lists all the interfaces the control supports • container can then call ::CreateStdDispatch passing in ITypeInfo pointer which returns with a pointer to the new dispatch interface • Container then calls IConnectionPointContainer::FindConnectionPoint passing in the IID of the control’s event interface. • The control returns a pointer to its IConnectionPoint interface for this source interface. • The container invokes IConnectionPoint::Advise passing to the control the pointer to its newly created dispatch interface. • Now the control can notify the container about its events.

23. Properties • A control implements a dispinterface providing access to its properties. • Some controls provide an ISpecifyPropertyPages interface. When a user askes to see a control’s properties its container calls the control’s ISpecifyPropertyPages::GetPages. This returns with a list of GUIDs, one for each property page object supported by the control. • The container then creates a property frame which instantiates each property page using CoCreateInstance. • For each property page the frame provides a site object supporting the IPropertyPageSite interface. Each property page object presents its page to the frame which builds a tabbed dialog box.

26. Basic COM Interfaces IUnknownThe base interface for all other interfaces, thus implemented by all objects. Allows clients to obtain interface pointers to other interfaces supported by an object and manage objects through reference counting. IMallocThe interface implemented by allocator objects to support memory allocation with specified ownership rules. OLE implements a default allocator. IClassFactory[2]The interface associated with a "class object" that manufactures (instantiates) objects of that class. Also support locking of an object server in memory. IClassFactory2 is an extension of IClassFactory that provides functions for handling licensing issue for object creation. IClassFactory2 is defined in OLE Controls but is simply an extension to COM.IEnum<X>Supports iteration (enumeration) through a sequence of structures or objects of type <X>.

27. Embedding and Caching Interfaces IOleObjectPrimary interface through which compound document objects provide services to containers, such as execution of verbs (action). IEnumOLEVERBProvided through IOleObject to enumerate supported verbs of an object. IOleAdviseHolderManages IAdviseSink interfaces given to compound document objects for notification. IOleClientSiteImplemented by container applications to provide container context information to compound document objects. .

28. More Embedding and Caching IOleCache[2]Implemented in object handlers (such as OLE's default handler) to allow containers to manage cached presentations of a compound document object. IOleCache2 provides containers a way to force an update of the cached presentations. IOleCacheControlImplemented in object handlers to support the connection of the cache to another object's IDataObject implementation IRunnableObjectProvides a way for objects to know when they transition from a "loaded" state to a "running" state andwhen they become contained in compound documents.

29. Uniform Data Transfer Interfaces IDataObjectThe single interface through which data transfers happen with methods to get/set data, enumerate and query formats, and to establish or terminate a notification loop with an advise sink (IAdviseSink[2]). IDataAdviseHolderHelps implementers of IDataObject to manage multiple IAdviseSink connections. IAdviseSink[2]Receives asynchronous data change and other notifications (such as view and document changes. IAdviseSink2 is the same with one added method for compound document linking. IViewObject[2]Implemented by an object to support direct renderings to device contexts, such as the screen or printer, as well as supporting a notification connection for view changes through IAdviseSink. IViewObject2 is an extension to IViewObject that includes an additional member for obtaining object extents. IEnumFORMATETCProvided through IDataObject implementations to enumerate arrays of FORMATETC data structures, describing the data formats available from the object. IEnumSTATDATAEnumerates a set of notification connections to an IDataObject implementer.

30. Connection Point Interfaces IConnectionPointContainerImplemented by an object to provide access to its various connection points (IConnectionPoint implementations) for generic notification connections to the object. This handles an objects "outgoing" interfaces on the order of how IUnknown handles incoming interfaces. IConnectionPointProvides functions to establish and terminate a generic notification connection to an object.

31. In-Place Activation Interfaces IOleWindowThe base interface for other in-place activation interfaces; it contains a function to retrieve the window associated with the interface and for entering or exiting context-sensitive help mode. IOleInPlaceObjectImplemented on compound document objects to indicate in-place activation support; it supplies activa-tion functions to containers.. IOleInPlaceActivateObjectSupports communication between an in-place object and the container's frame and document windows. IOleInPlaceSiteImplemented next to IOleClientSite in a container to indicate in-place activation support and to provide objects a way to notify the container when in-place state changes occur. IOleInPlaceUIWindowImplemented on container document and frame related objects to support border space negotiation for in-place objects. IOleInPlaceFrameDerived from IOleInPlaceUIWindow, this interface is implemented on a container's frame object to support not only border space negotiation but also menu merging and keyboard accelerator translation.

32. Newer OLE Controls Interfaces IOleControlImplemented by an OLE Control to provide for keyboard mnemonic translation and notification of changes in a container's ambient properties. IOleControlSiteImplemented by an OLE Control container to supply container operations to OLE Controls, such as transformation of coordinates and accelerator translation.

33. Structured Storage Interfaces IStorageImplemented on "storage" objects to provide directory-like functions for the management of a storage hierarchy. IStreamImplemented on "stream" objects to provide file I/O type functions through which components can write binary data. IRootStorageImplemented on the root storage object of a compound file, that is, the one connected to the underlying disk file. This interface is used to change the underlying disk file in low-memory save operations. ILockBytesIn OLE's Compound Files implementation, ILockBytes makes any binary storage medium such as a disk file, database record, or block of memory, appear as a contiguous byte array to objects that implement IStorage and IStream. OLE provides standard disk file and memory implementations of this interface, and applications can provide their own to build a compound file in other storage systems. IEnumSTATSGEnumerates STATSG structures which provide information about storage and stream objects such as open mode, element name, creation date and time, etc.

34. More Structured Storage Interfaces IPersistBase interface for persistent object interfaces through which a caller can obtain the class identifier of an object that can handle the contents of the storage element. IPersistStorageImplemented by an object to indicate its capability of reading and writing its persistent state to an from an IStorage object. Compound document objects always implement this interface. IPersistStream[Init]Implemented by an object to indicate its capability of reading and writing its persistent state to an from an IStream object. IPersistStreamInit is an interface defined in OLE Controls that extends IPersistStream with an initialization function. IPersistFileImplemented by an object to indicate its capability of reading and writing its persistent state to an from a standard file.

35. OLE Automation Interfaces IDispatchImplemented by OLE Automation objects to expose their methods and properties for access by Automation controllers. ITypeLibUsed by Automation controllers to navigate information in type libraries. ITypeInfoUsed by Automation controllers to obtain type descriptions of individual objects or IDispatch interfaces. ITypeCompProvides a way to access information needed by compilers to bind to and instantiate structures and interfaces. ICreateTypeInfoUsed by tools for creating type information for individual objects. IProvideClassInfoImplemented by an object to provide easy access to the ITypeInfo interface that describes all the automation interfaces of that object. This interface is defined as part of OLE Controls, but is an extension of OLE Automation.

36. Property Notification and Property Page Interfaces IPropNotifySinkImplemented by the client of an automation object to be notified when an object's property changes as well as to control potential property changes. A client connects this interface to an object via connection points.ISpecifyPropertyPagesImplemented by an object to indicate what implementations of IPropertyPage are available for this object's properties. IPropertyPage[2]Implemented by a property page object to support creation of UI in which a user can manipulate proper-ties. IPropertyPage2 is a simple extension to IPropertyPage to support browsing of properties. IPerPropertyBrowsingImplemented by a property page object to support browsing of individual properties.

37. Remoting Interfaces IExternalConnectionProvides a way for objects to know when remote connections to the object are being established and terminated. IMarshalUsed to package and send interface method arguments between applications (or networks), the process called marshaling. IStdMarshalInfoRetrieves the class identifier of the proxy and stub implementations used to handle marshaling of a custom interface.

38. Naming Interfaces IMonikerImplemented on moniker objects to provide binding and other name-related services. IParseDisplayNameIncludes functions to convert a human readable name into a moniker. IBindCtxUsed to describe track a monikers binding process to pass information between components used in the binding. This can help monikers break out of circular reference loops. IEnumMonikerEnumerates through monikers. IRunningObjectTableImplemented on OLE’s “running object table”, which tracks which objects are currently running according to their monikers. Used to avoid relaunching applications or reloading files redundantly thereby optimizing moniker binding.

39. Linking Interfaces IOleLinkProvides functions for manipulating a linked object, supported alongside IOleObject. This interface is always implemented in OLE's default handler for any object. IOleContainerImplemented by container applications to allow enumeration of the object in the container. IOleItemContainerImplemented by applications that support complex linking to portions of documents or to embedded objects within a document. Specifically used by the binding process of items monikers..

40. Drag and Drop Interfaces IDropSourceImplemented by the source of a drag-and-drop operation to control the duration of the operation and the mouse cursor. IDropTargetImplemented by registered targets for drag-and-drop operations to know when the mouse enters or leaves a window, moves in a window, or when a drop happens.