HOOPS/ATL Integration Guide

1.0 Introduction

2.0 Experimenting with the HOOPS 3D Stream Control

3.0 Scripting The ATL Control

4.0 Customizing the ATL Control


1.0 Introduction

The HOOPS/ATL Integration is an ATL-based ActiveX control which integrates with HOOPS Visualize to support loading and viewing of HSF files. This is a demonstration application intended to help developers create their own custom control, and is built upon the HOOPS/MVO classes. The customized features include a basic right-click pop up menu containing various methods of scene interaction and support for native Windows GDI Printing and Copy-to-Clipboard. A prebuilt reference control called the HOOPS 3D Stream Control is also provided, which is based on the HOOPS/ATL integration.

This guides assumes familiarity with ATL and ActiveX technology, as well as the architecture of the HOOPS/MVO Classes and ATL technology.

1.1 Compiling and Linking

The headers and source code for HOOPS/ATL Integration is located in the /demo/atl/Hoops3dStreamCtrl/source directory. This directory includes the Microsoft Visual Studio Project files for rebuilding with Visual C++.

1.2 Supported Platforms

The ATL based HOOPS/ActiveX Integration works on all supported Windows platforms (Windows 8 in desktop mode), and supports Microsoft Internet Explorer 9.0 and higher, as well as MS Office 2007 and 2010. Custom controls should also run properly inside any compliant OLE container application.

1.2.1 Using the HOOPS ATL control in Microsoft Word 2007

In Microsoft Word 2007, the reference HOOPS 3D Stream Control object can be accessed via the Developer Tab. To enable this tab, open the Word Options dialog. In the left panel of the dialog, select the Popular option. On the right, under the "Top options for working with Word", select the checkbox which reads "Show Developer tab in the Ribbon." Then, apply the changes and exit the dialog.

In the main Word 2007 application, there should be a Developer Tab. When you select this tab, you will see five group boxes. The second group box will contain a button with an icon showing a folder and tools. When you select this option, it will open a pop-up menu. Under the ActiveX Controls, select the last option, "More Controls."

The More Controls dialog will appear. In this window, scroll down to "HOOPS 3D Stream Control Class."Highlight this option and then select "OK." This will insert the HOOPS 3D Stream Control class into your Microsoft Word document.


2.0 Experimenting with the HOOPS 3D Stream Control

IMPORTANT NOTE: The prebuilt reference HOOPS 3D Stream Control is provided as-is, and no end-user support is provided by Tech Soft Developer Support. If you wish to share the prebuilt control with customers, you should provide your own hosting of the control. The URL for the reference control listed below is NOT guaranteed to persist indefinitely.

The prebuilt control is located at the following location: http://downloads.techsoft3d.com/HOOPSATL/hoopsatlcontrol.cab. Alternately, you can manually rebuild or install the control from the source located in /demo/atl/Hoops3dStream/source. After loading an HTML page that refers to the CAB file, or after manually rebuilding it, the control will be registered on the system. At this point, the control is accessible from within the 'Insert->Object' list within MS Office applications (or any OLE-container application), and will also be instantiated whenever web pages that refer to the control are loaded into Microsoft Internet Explorer.

'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.mycompany.com/mymodel.hsf'.

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

3.0 Scripting The ATL Control

OLE Container applications or hosting web pages can access exposed methods and properties of the HOOPS 3D Stream Control. Properties include stock properties which can only be accessed when the control is first references in a web page, along with the other properties that can be accessed from JavaScript, etc... The control's exposed properties/methods are documented in the Reference Manual entry for the IHoops3dStreamCtrl interface. The stock properties for IHoops3dStreamCtrl include the following:

  • IHoops3dStreamCtrl::AllowEntitySelection
  • IHoops3dStreamCtrl::AllowMenu
  • IHoops3dStreamCtrl::Antialiasing
  • IHoops3dStreamCtrl::AntialiasingLevel
  • IHoops3dStreamCtrl::AxisMode
  • IHoops3dStreamCtrl::BhvContinuousPlay
  • IHoops3dStreamCtrl::CullingThreshold
  • IHoops3dStreamCtrl::DriverType
  • IHoops3dStreamCtrl::Filename
  • IHoops3dStreamCtrl::FrameRate
  • IHoops3dStreamCtrl::FramerateType
  • IHoops3dStreamCtrl::HardwareAntialiasing
  • IHoops3dStreamCtrl::MaximumThreshold
  • IHoops3dStreamCtrl::SegmentDL
  • IHoops3dStreamCtrl::StaticModel

Developers who wish to customize the control's source code should have experience with ATL development and HOOPS Visualize. The control's core class is documented in the Reference Manual entry for CHoops3dStreamCtrl. Refer to Section 4.0 below for more details.

Sample HTML pages:

The assembly.html sample embeds the ATL control into a web page, and sets up the control assuming that it will primarily be viewing 3d models (assemblies). (It will only load if the control is already installed on your system.) Note that it first sets stock properties during initialization which specify the filename and enable the 'right-click' pop up menu. It then defines an initializeControl method which:

  • Sets the 'NoOrbit' non-stock property to 'false' to allow for camera orbiting.
  • Sets the current interaction operator to HOpCameraOrbit.
  • Sets a perspective camera projection.
  • Sets the starting render mode to 'shaded' (the control's right-click pop up menu allows this to be changed)
  • Explicitly turns on the visibility of 'lines' that may also reside in the model (this could be optional depending on whether you wanted the initial view to display 'lines' or not).
<HTML>
<HEAD>
<SCRIPT LANGUAGE="JavaScript">
function initializeControl()
{
if (hoopscontrol.DLinProgress == true)
{
setTimeout("initializeControl()",100)
}
else
{
hoopscontrol.NoOrbit = false
hoopscontrol.SetOperator("HOpCameraOrbit")
hoopscontrol.SetProjectionModePerspective()
hoopscontrol.SetRenderMode("shaded")
hoopscontrol.OpenModelSegment()
hoopscontrol.HATL_Set_Visibility("lines=on")
hoopscontrol.HATL_Close_Segment()
}
}
</SCRIPT>
</HEAD>
<BODY>
<OBJECT name = "hoopscontrol" classid ="clsid:AD5F3C4B-BD73-11D5-838B-0050042DF1E4" width="500" Height="500">
<PARAM name="Filename" value="assembly.hsf">
<PARAM name="AllowMenu" value=1>
</OBJECT>
<SCRIPT LANGUAGE="JavaScript">
initializeControl()
</SCRIPT>
</BODY>
</HTML>

The drawing.html sample embeds the ATL control into a web page, and sets up the control assuming that it will primarily be viewing 2d drawings. Again, it will only load if the control is already on your system. Note that it first sets stock properties during initialization which specify the filename and enable the 'right-click' pop up menu. It then defines an 'initializeControl' method which:

  • Sets the 'NoOrbit' non-stock property to 'true' to prevent camera orbiting.
  • Sets the current interaction operator to OpCameraPan.
  • Sets an orthographic camera projection.
<HTML>
<HEAD>
<SCRIPT LANGUAGE="JavaScript">
function initializeControl()
{
if (hoopscontrol.DLinProgress == true)
{
setTimeout("initializeControl()",100)
}
else
{
hoopscontrol.NoOrbit = true
hoopscontrol.SetOperator("HOpCameraPan")
hoopscontrol.SetProjectionModeOrthographic()
}
}
</SCRIPT>
</HEAD>
<BODY>
<OBJECT name = "hoopscontrol" classid ="clsid:AD5F3C4B-BD73-11D5-838B-0050042DF1E4" width="500" Height="500">
<PARAM name="Filename" value="drawing.hsf">
<PARAM name="AllowMenu" value=1>
</OBJECT>
<SCRIPT LANGUAGE="JavaScript">
initializeControl()
</SCRIPT>
</BODY>
</HTML>

There is another example web page which does some sophisticated scripting of the ATL control in the <VISUALIZE>/demo/atl/Hoops3dStreamCtrl/html directory.

3.1 Java Script Interaction

The HOOPS 3D Stream Control exposes events that when fired can be handled by a Javascript. The five different events implemented within the control are:

  • OnBeginLoad
  • OnEndLoad
  • OnSelect
  • OnUpdateWidget
  • OnModelStructureParsed

The following HTML shows how to handle an event raised by the Hoops 3D Stream Control with Javascript:

<HTML>
<HEAD>
<SCRIPT LANGUAGE="JavaScript">
function loadfile()
{
atltest.Filename = "drawing.hsf";
}
</SCRIPT>
<SCRIPT FOR="atltest" EVENT="OnEndLoad()" LANGUAGE="JavaScript">
alert("OnEndLoad event");
</SCRIPT>
</HEAD>
<BODY>
<OBJECT name = "atltest" id="atltest"
classid ="clsid:AD5F3C4B-BD73-11D5-838B-0050042DF1E4"
width=600 height=500 >
</OBJECT>
<INPUT TYPE="button" VALUE="Load File" onclick="loadfile()">
</BODY>
</HTML>

This html file creates a button that when pressed loads a file. When the file is done loading, the OnEndLoad event is raised; the script, which displays a simple message, is run. This example shows an alternative to using the DLinProgress property to verify if the file has finished loading. New events can be added to the HOOPS 3D Stream Control using the established structure.


4.0 Customizing the ATL Control

Customizing the control itself refers to modifying items such as it's right-click pop up menu, the capabilities associated with the menu, and it's exposed COM interface. Developers who wish to perform this level of customization should have ATL programming experience.

Customizing the control itself refers to modifying items such as it's right-click pop up menu, the capabilities associated with the menu, and it's exposed COM interface. Developers who wish to perform this level of customization should have ATL programming experience.

Another aspect of customization, independent of whether you've modified/enhanced the control's source code, is to 'brand' it as your own custom control. Each ActiveX control is identified by a unique GUID and associated 'classid'. Since the provided sample ATL control is strictly for demonstration purposes, you are not suppose to redistribute or mirror it for commercial purposes. Therefore, if you want to create your own custom control and make it available to end-users, you will need to modify the GUID/classid. This is achieved using a GUID utility program that can be run from the windows command prompt. Contact Tech Soft 3D support if/when you desire to brand a custom control as your own.