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 3D Stream Control is an ATL-based ActiveX control 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.

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 and ATL technology.

1.1 Compiling and Linking

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 Visual Studio Project files for rebuilding with Visual C++.

1.2 Supported Platforms

The ATL based HOOPS/ActiveX Integration is supported on all major Windows XP/Vista/Win7/Win8 platforms (Windows 8 ‘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 object in Microsoft Word 2007

In Microsoft Word 2007, the 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 third checkbox which reads "Show Developer tab in the Ribbon." Then press the "OK" button to apply the changes and exit the dialog.

word_07_optssmall.png

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."

word_07_activex_controlsmall.png

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.

word_07_3d_stream_control.png

2.0 Experimenting with the HOOPS 3D Stream Control

To install the HOOPS 3D Stream Control on your system, you can automatically download it by visiting the streaming gallery at hoops3d.com. Alternately, you can manually build/install the control from the source included with HOOPS/3dAF which is located in /demo/atl/Hoops3dStream/source. 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.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 webpages can access exposed methods/properties of the HOOPS 3D Stream Control. Properties include stock properties which can only be accessed when the control is first references in a webpage, 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:

Developers who want to customizing the control's source code should only do so if they are experienced with ATL development and HOOPS/3dAF. The control's core class is documented in the Reference Manual entry for CHoops3dStreamCtrl. Refer to Section 4.0 down below for more details.

Sample HTML pages:

The assembly.html sample embeds the ATL control into a webpage, 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' popup 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 rendermode to 'shaded' (the control's right-click popup menu allows this to be changed)
  • Explicity turns on the visiblity 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 webpage, 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' popup 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 'HOpCameraPan'.
  • 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 webpage which does some sophisticated scripting of the ATL control in the <hoops>/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 java script. 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 java script:

<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 popup 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 gui/classid. This is achieved using a GUID utlility program that can be run from the windows command prompt. Contact Techsoft3D support if/when you desire to brand a custom control as your own.