MSDN Library Visual Studio 6.0 disk1

THIS TOOL IS NOT SUPPORTED BY MICROSOFT CORPORATION. IT IS PROVIDED "AS IS" BECAUSE WE BELIEVE IT MAY BE USEFUL TO YOU. NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE It is necessary to build the FrameWrk samples before building ToDoSvr or WebImage. Running "nmake" from the <sdkdir>\samples\com\activexcontrol\basectl directory will build all of the sample code in the correct order. Before building any of the samples, run setenv.bat to add the Microsoft Platform SDK include, bin, and lib directories to the front of your environment. More information on the Internet-aware OLE controls is available in readme.txt files in the sample directories. The Framework Sample Code for Authoring non-MFC Controls ====+==================================================== This document presents a short discussion on using the ActiveX Controls Framework to author new ActiveX controls. 0. Contents =---------= 1.0 Introduction 1.1 Target Audience 1.2 Structure of the Framework 1.3 Target Environment 2.0 Creating an ActiveX Control 2.1 Building the Control 2.2 Working with the In-Process Server 3.0 Working with Your ActiveX Control 3.1 Structure of a Control 3.2 Painting a Control 3.3 Handling Messages in a Control 3.4 Adding a Property 3.5 Adding a Method 3.6 Adding an Event 3.7 Using Standard ActiveX Types 3.8 Throwing an Exception 4.0 Persistence 4.1 Text Persistence 4.2 Binary Persistence 5.0 Property Pages 5.1 Working with a Property Page 5.2 Navigating through Associated Objects 5.3 Marking Your Page as Dirty 6.0 String Manipulation 6.1 Types of Strings 6.2 Working with Strings 7.0 Localization 7.1 Setting up for Localization 8.0 Miscellaneous 8.1 Recommended Reading 8.2 Host-Specific Notes 8.2.1 Microsoft Access 95 1.0 Introduction =--------------= The ActiveX Controls Framework is a sample code base from which one can author new ActiveX controls for use in existing containers, such as Microsoft Visual Basic, Microsoft Access, and Microsoft Visual FoxPro, or in future containers of ActiveX Controls. It differs from the Microsoft Visual C++ CDK in many ways. Most notably, this framework is intended to be considerably more "bare bones." Only minimal functionality is provided to the programmer. Little in the way of default handlers for various windows messages, OLE events, et. al. has been provided. The ability to add them is there, but the code is not. The code base has also been designed primarily for performance and reduced code size as much as possible. Whenever a choice between ease of use and performance arose, the latter was typically chosen. In addition, the code is designed to take advantage of whatever OC '96 features are available from the host. The code will use any available features, and fall back to the 'older' behavior for those cases where they aren't. The code base is extremely extensible, however, and of course, all the source code is there -- if something doesn't do what you want it to, make it. 1.1 Target Audience This framework targets a slightly more advanced programmer than the Microsoft Visual C++ Control Developers Kit. Specifically, the programmer will be required to understand some of the fundamentals of OLE automation and dual interfaces. The user will have to be able to understand and modify an .ODL file on their own. In addition, the user will be required to understand and be able to work with OLE persistence interfaces, most notably IStream IPersistPropertyBag and IPersistStream. However, if it is not desired, the user will not be required to have much knowledge of OLE embedding interfaces. Programmers who do not have specific performance requirements, those not familiar with many of the pertinent OLE technologies, or those who work primarily with the Microsoft Foundation Classes will find the MFC/CDK far more suited to their needs. 1.2 Structure of the Framework The directory structure of the ActiveX Controls Framework is as follows: BaseCtl + |- \FrameWrk | |- \IELnk | |- \IEMIME | |- \Include | |- \Lib | |- \ToDoSvr | +- \WebImage The BaseCtl\Framewrk and BaseCtl\Include directories contain the core code for writing an ActiveX control. The BaseCtl\Include directory contains the headers that most controls will get their information from, and the BaseCtl\Framewrk directory contains the core functionality (in the COleControl class) which compiles into a static library (.LIB) form. A few samples are provided with the framework. 1.3 Target Environment This framework was developed assuming you have the Microsoft Visual C++ 4.0 (or later) toolset in your path and the Microsft Windows Platform SDK installed. Running 'nmake' in BaseCtl or BaseCtl\FrameWrk will build debug a version of the static library. 'nmake nodebug=1' will build a retail (nodebug) static library. All of the makefiles and build processes are command-line based. Various people have reported, however, that it's largely trivial to integrate that into their favorite environments. NOTE: Under Windows 95, Visual C++ will not, by default, register its environment variables to set up for command line builds. Occasionally on some Windows 95 machines you may get a bunch of "Out of Environment Space" messages when doing this. In the properties dialog for the Command Prompt, you can increase the size of the environment from "Auto" to some number like 1024, and this takes care of the problem. None of this should happen when developing under Microsoft Windows NT. The file dwinvers.h in <sdkdir>\samples\com\activexcontrol\BaseCtl\Framewrk is a file that contains version and copyright information that should be updated by you each time you run your builds. The framework does not do this work for you. 2.0 Creating an ActiveX Control =-------------------------= Creating an ActiveX control using this framework proves moderately straightforward. We will go into the process in brief here. Templating off the sample code should be able to fill in the holes. The framework implements the core functionality in a few C++ classes, notably CAutomationObject, COleControl (which inherits from CAutomationObject), and CPropertyPage. All objects inherit from CUnknownObject, which provides the support for aggregation. So, to write an ActiveX Control, you need to declare a new object which inherits from COleControl. In addition, you'll need to inherit from some sort of Automation interface that describes the properties and methods for your control, say, IMyControl. This interface description is generated by MKTYPLIB and will be put in some output file created by MKTYPLIB. COleControl has a number of virtual methods that are declared as pure, which you simply must implement in your control class. These include WindowProc, LoadBinaryState, LoadTextState, SaveBinaryState, SaveTextState, OnDraw, and RegisterClassData. To write a property page, you declare a new object which inherits from CPropertyPage. This object must implement a DialogProc. You can also implement automation objects and collections by declaring a new object that inherits from CAutomationObject. Since an ActiveX control is an In-Process OLE Server, you also need one file to describe all your objects, whether they be controls, automation objects, or property pages. This file will have a bunch of information in it, including a table of all objects and information about them. In addition, it'll have information on what sort of localization your server would like to use, and what sort of licensing support you'd like to have. Finally, you'll need