1.0 Introduction

1.1 Compiling and Linking

1.2 Supported Platforms

2.0 Creating Custom Controls

2.1 Control Properties and Methods

2.2 Adding Features to Custom Controls

3.0 HOOPS 3D Stream Control:  Overview and Usage

4.0 Experimenting with the HOOPS 3D Stream Control



1.0 Introduction

This guide explains how to use the HOOPS ATL Stream Control to create your own custom ActiveX control.  It assumes familiarity with the architecture of the HOOPS/MVO Classes.

1.1 Compiling and Linking

Windows 95/98/NT/2000/XP
The headers and source code for the HOOPS ATL Stream Control are located in the /demo/atl/Hoops3dStreamCtrl/source directory. This directory includes the Microsoft DevStudio Project files for rebuilding with Visual C++. 

1.2 Supported Platforms

The ATL based HOOPS/ActiveX Integration is supported on all major Windows 95/98/NT/XP platforms, and support Microsoft Internet Explorer 4.7 and higher, as well as MS Office97 and higher.  Custom controls should also run properly inside any compliant OLE container application. For specific information regarding the supported versions of compilers and Operating Systems, refer to the Microsoft Windows 95/98/NT section of the HOOPS/3DAF Platform and Device Guide.


2.0 Creating Custom Controls

To create a custom control we recommend using the existing code for the HOOPS Stream Control as a starting point and modify/extend it's functionality as desired. One complication stems from the fact that any modified ActiveX control requires a new set of GUID's to allow them to be uniquely identified on the same computer and/or the internet. To make this "find&replace" approach as easy as possible all individual GUID occurrences are replaced by a set of defines which are combined into one file called guidlist.h. By simply replacing these predefined GUID's with new ones generated by "GUIDGEN" a unique control with custom functionality can be created. In some cases it might be necessary to also bump up the version number of the control. This can be done by replacing the version occurences in Hoops3dStream.idl and Hoops3dStreamCtrl.rgs (search for "Version"). To change the name of the control we recommend using a "find & replace" tool that can deal with multpile files simultanously.
In future version of the HOOPS Application Framework this process will be simplified by a custom AppWizard.

2.1 Control Properties and Methods

OLE Container applications can access exposed methods and properties of custom ActiveX controls (such as the HOOPS 3D Stream Control). The HOOPS ATL control contains a large number of properties which can be used to drive the control from any container application.

One of the most important properties is called 'filename'. 

The 'filename' property drives the control by calling the method 'OnFilenameChanged' , which modifies the filename asssociated with the control.  'OnFilenameChanged' is called anytime a webpage references the control and passes in a 'filename'.  In other cases, the 'OnFilenameChanged' method is called when the user pulls up the control 'Properties' from an OLE container application and loads a file. Here is a HTML excerpt that embeddes the ATL control into a webpage and loads a default file:

<OBJECT name = "atltest"     classid ="clsid:AD5F3C4B-BD73-11D5-838B-0050042DF1E4" width=600 height=500><PARAM name="filename" value="snowmobile.hsf"></OBJECT> 'Embed' is another property used by custom controls.  In the case of OLE container applications, checking 'Embed' within the 'Property' page before loading in the file ensures data persistence.  Specifically, if you save a Word document that includes the control and a file was loaded into the control, then the file will be stored inside the Word document if 'Embed' is selected (the state of the file is then 'serialized').  When the document is reopened, the .hsf or .hmf file contents will be loaded back into the HOOPS/3dGS scene-graph.

 

For more information on the various properties and methods please see the reference manual . A set of sample HTML pages that incorporate the control can be found in the demo/atl/hoops3dstreamctrl/html folder of the HOOPS 8.0 distribution

 

2.2 Adding features to custom controls

Once you have created custom HOOPS/ActiveX control classes (manually via the approach mentioned previously, or with the upcoming automated AppWizard), proceed by defining a user interface. Custom user interfaces can take the form of right-click menus or JavaScript or VBscript buttons inside webpages. 

At the very least, the 'Filename' propertly would be one of the properties of your custom HOOPS/ActiveX control. 'Embed' would be necessary if you wanted to support persistence within OLE Container applications such as the MS Office programs.

A good starting point for evaluation and prototyping is to begin customizing the HOOPS 3D Stream Control. All the HOOPS/ActiveX-specific support logic and HSF streaming support is encapsulated in the base classes and the HOOPS 3D Stream Control classes. Therefore, customized code would primarily consist of working with vanilla MFC menu programming and CWnd methods to customize the right-click popup menu. Menu options can implement HOOPS/MVO and HOOPS/3dGS tools to create powerful, custom operators.


3.0 HOOPS 3D Stream Control:  Overview and Usage

The HOOPS 3D Stream Control is a customized, ATL-based ActiveX control that is built upon the HOOPS/MVO Classes and includes support for streaming HSF files. The customized features include a basic right-click popup menu containing various methods of scene interaction and support for native Windows GDI Printing/Copy-to-Clipboard. 

The source code for the HOOPS 3D Stream Control is available with the HOOPS/3dAF release.  To access, just open the MSDev Workspace hview.dsw located in /hoops/demo/atl/hoops3dstreamctrl/source/. 


4.0 Experimenting with the HOOPS 3D Stream Control

To install the HOOPS 3D Stream Control on your system, build the control from the project or download it from the following URL:

    http://hoops3d.com/streaming/control/control_download.htm

After downloading or manually building the 3D Stream Control, it will be registered on your system.  At this point the control is accessible from within the 'Insert->Object' list within MS Office applications (or any OLE-container application, such as Visio, etc...), and will be instantiated whenever web pages that reference the control are loaded into Microsoft Internet Explorer (MSIE). 

'Filename' Property

To experiment with the 'filename' property, insert the HOOPS 3D Stream Control into MS Word by selecting the menu option 'Insert > Object' and selecting  'HOOPS 3D Stream Control'.  DeSelect and then Select the object via a single click.  This will then let you access the menu option 'Edit > HOOPS 3D Stream Control Object > Properties' (alternatively, you can right-click on the control's border).  Choose a file with the .hsf extension and that file will be streamed in.  The file can be local or specified via a remote URL such as :

    http://www.hoops3d.com/stream/bridge.hsf

Finally, double-click to activate the control 'in-place'.  The control's right-click UI should now accessible.