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.