How To


Note: a WebGL-enabled browser is needed to run the demos presented below. Please refer to this page for a quick HOWTO or click here to test your browser.


Description

This page shows the utilities provided to modify and personalize the 3DHOP viewer interface and aspect.


CANVAS personalization

Click to run live demo
Introducing the 3DHOP user interface

Set Up

3DHOP is provided as an HTML element, and thus it follows the rules that govern this kind of entity: i.e. is possible to modify the style through a CSS file or to manage the user interaction using scripting methods.
However with the aim to facilitate the setting and the personalization of the viewer environment, 3DHOP provides a couple of tools able to make easier the work of less experienced users, without preventing advanced users from modifying interface and adding functionality.
These tools operate on two different sides of the viewer: the interface and the external aspect. Let's start to observe what has been done concerning the first issue.

To improve the 3DHOP usability experience together with the basic version of the viewer we provide an useful toolbar. This toolbar, recognizable by the "toolbar" identification tag, is no more than a simple HTML element, superimposed on the CANVAS (using the "absolute" value for the CSS position property), and defined inside the proper 3DHOP DIV element, in this way:

<div id="3dhop" class="tdhop" onmousedown="if (event.preventDefault) event.preventDefault()">
 <div id="toolbar">
  <img id="home"       title="Home"                  src="skins/dark/home.png"   /><br/> 
  <img id="zoomin"     title="Zoom In"               src="skins/dark/zoomin.png" /><br/>
  <img id="zoomout"    title="Zoom Out"              src="skins/dark/zoomout.png"/><br/>
  <img id="light_on"   title="Disable Light Control" src="skins/dark/light_on.png" 
                                                          style="position:absolute; visibility:hidden;"/>
  <img id="light"      title="Enable Light Control"  src="skins/dark/light.png"  /><br/>
  <img id="full_on"    title="Exit Full Screen"      src="skins/dark/full_on.png" 
                                                          style="position:absolute; visibility:hidden;"/>
  <img id="full"       title="Full Screen"           src="skins/dark/full.png"   />
 </div>
 <canvas id="draw-canvas" style="background-image: url(skins/light/background.png)"/>
</div>

As can be seen in the code in the above box, the toolbar in his basic appearance is formed by four button icons (represented by HTML images), related with the appropriate actions by their tag id.
The actions specification occurs then in a JavaScript function (called "actionsToolbar") placed in an express scripting block:

function actionsToolbar(action) {
  if(action=='home')
    presenter.resetTrackball();
  else if(action=='zoomin') 
    presenter.zoomIn();
  else if(action=='zoomout') 
    presenter.zoomOut(); 
  else if(action=='light' || action=='light_on') { 
    presenter.enableLightTrackball(!presenter.isLightTrackballEnabled()); lightSwitch(); } 
  else if(action=='full'  || action=='full_on') 
    fullscreenSwitch(); 
}

From the above code is easy to see that in the method which drives the toolbar actions, basically we have just connected the toolbar button id tags ("home", "zoomin", "zoomout", …) with the appropriate function provided by our viewer ("resetTrackball()", "zoomIn()", "zoomOut()", …).
Thanks to this structure, highly schematic and easy to understand, the toolbar functionalities initially given can be freely modified by the user just adding or removing HTML buttons (i.e. images) from the "toolbar" DIV earlier defined, and then consequently changing the id-action associations placed in the "actionsToolbar" JavaScript function (of course several other action methods are provided further those shown here, a complete list of whom can be found in the documentation section).
However this toolbar is only one of the possible interfaces achievable, in reality the CANVAS interaction methods provided by 3D Hop and previously listed, can be used in multiple ways, changing the performing mode, or using different HTML elements whom connect them (like for example text links placed along the Web page, or more broadly, any other HTML element that user likes).

Well, as said at the beginning, another possible personalization of our viewer regards his external aspect. Two immediate methods are provided to the user, avoiding him to edit the elements style properties inline in the HTML code or in the CSS file.
The proposed functions have an effect on the CANVAS size and on the toolbar DIV positioning, and can be used to modify the default given values after the viewer initialization and setup, as shown below:

$(document).ready(function(){
  init3dhop();

  setup3dhop();
  
  resizeCanvas(800,600);

  moveToolbar(20,20);  
});

As is easy to imagine "resizeCanvas" set in the CANVAS size (full browser by default), taking in input the news horizontal and vertical sides dimensions (in pixels).
The methods deputy to move the toolbar DIV around the screen is instead "moveToolbar". His displacement is related to the 3DHOP position in the page, in fact the function takes as input the horizontal and vertical shift (still in pixels) from the left-up corner of the CANVAS (notice that the toolbar movement is not confined in the viewer space, but can overcome his edges).

These last two function conclude the discussion about the 3DHOP interface and aspect personalization. Reassuming our viewer is provides by default with a toolbar as interface and with two express methods to modify its appearance in the web page. To exploit these features it is only necessary to add to the base code the toolbar instantiation (both HTML and JavaScript side), while the aspect related functions are directly available (without addictions needed) …and you are done!

The complete sources of this example are provided together the 3DHOP code in the download section.

If you want instead to learn more about how to load the 3D models inside 3DHOP please click here and go to the next HOWTO.