UI

From H3D.org

Jump to: navigation, search

Contents

Introduction

UI is a toolkit for haptic 3D-widgets in H3DAPI.

UI contains nodes for creating widgets, such as buttons and sliders, which can be positioned in 3D space. The widgets are activated with a haptics device or a mouse.

The existing UI nodes are:

  • Frame - A frame in which widgets can be placed. It works similar to a grouping node but also uses a H3DLayoutManagerNode for layout of the contained widgets.
  • GridInfo - Gives information to the GridLayoutManager about which position in the grid a widget is to be positioned in.
  • GridLayoutManager - Puts all widgets in a grid and lets each widget decide through the GridInfo node where on the grid it should be located and how many cells it should span.
  • Label - A widget with text on it.
  • PopupMenu - A menu that pops up when pressing a button.
  • Sliderbar - Allows a user to control a floating point value by a slider bar.
  • TouchButton - A button that changes state when it activated.

Installation on Windows

UI binaries are included with an installation of H3DAPI 2.2 or H3DViewer 2.2 and will load as a plugin in H3DViewer.

Building from source

To build UI on Windows follow these steps.

  1. Obtain the source code. For example through te full H3D package.
  2. Install version 2.6.0 or later of CMake. Go to the cmake homepage to download and install that program.
  3. Start CMake GUI. Put the search path to CMakeLists.txt (UI\build) in the first text box in this GUI. Put the search path to where the generate projects will be build in the second text box, for example UI\build\vc10 (if visual studio 10 should be used). Press the Configure button and choose the compiler for which CMake will generate build files. Then wait while CMake tries to detect what libraries are installed on your system. It might be so that the Configure button will have to be pressed again after the first configure run. If everything went fine then the "OK" button should light up and when it is pressed the project files will be generated. If CMake could not find all libraries then these paths can be manually specified. All such paths are advanced variables so the "show advanced" checkbox must be active.
  4. Open the projects and start building. When generating project files for Microsoft Visual Studio the project file to open is the solution file generated.
  5. When the UI library finished building build the INSTALL project once. This will copy library files and binary files to a bin and lib folder in the location set by CMAKE_INSTALL_PREFIX. The value of this variable can be seen in the CMake GUI. On a default installation this will be UI\bin. This default location is the location in which the provided examples will look for the binaries for UI. Note that the ImportLibrary statement in the examples are commented out and the examples needs to be modified when testing with H3DLoad. When testing with H3DViewer simply add the UI as a plugin to H3DViewer and then run the examples.

Installation on GNU/Linux

To build UI on Linux follow these steps.

  1. Build and install H3DAPI.
  2. If you did not install UI as a debian package then download the source for UI.
  3. To generate the make files use the terminal and change folder to the UI/build folder. Create a new folder and navigate to that folder then write:
    cmake ../

    To build UI write: (tip: write "make -j3" if you have a core duo, and "make -j5" for quads: faster)
    make

    To install UI write:
    sudo make install

    UI header and libraries are now installed on your system.
  4. To test the examples with H3DViewer by adding the UI as a plugin to H3DViewer and then load examples.
  5. To test the examples with H3DLoad uncomment the ImportLibrary statement in the x3d files and then load the file with H3DLoad.

Installation on Mac OS

If a build on Mac OS is desired a similar procedure as for GNU/Linux can be used provided that the gnu compiler is used.

A short UI tutorial

UI is distributed with a couple of example x3d files. These files might be the easiest way to figure out how to specify scene using the UI nodes. Each one of the example x3d files can be loaded with H3DViewer if UI is added as a plugin to H3DViewer.

Here we will show a simple example which shows a button and a slider bar. All widget nodes are child nodes and can therefore be placed inside a transform or group node just like other child nodes. It is however quite convenient to use the Frame node for specific positioning of the contained nodes. The frame, like all other widget nodes have a desiredSize field which is the size that the author of the scene wants the Frame to have.

<Frame desiredSize="0.1 0.05 0.001">
</Frame>
 

If the above scene is loaded nothing will be displayed, since the Frame is simply a container and nothing else. To actually show something a button is added. In this case a TouchButton which toggles on release is added. The text on the button is "Button" and the contained FontStyle node determines how the text font, size and position.

<Frame desiredSize="0.1 0.05 0.001">
  <TouchButton DEF="BUTTON" buttonMode="TOGGLE_RELEASE" text="Button">
    <FontStyle size="0.014" justify='"MIDDLE", "MIDDLE"' />
  </TouchButton>
</Frame>

Next a SliderBar is added and some properties of the SliderBar and its text is set.

<Frame desiredSize="0.1 0.05 0.001">
  <TouchButton DEF="BUTTON" buttonMode="TOGGLE_RELEASE" text="Button">
    <FontStyle size="0.014" justify='"MIDDLE", "MIDDLE"' />
  </TouchButton>
  <SliderBar DEF="SLIDERBAR" text="Slider" valueRange="0 100" value="4"
             stepLength="0.01" markerColor="1 0 0" textColor="0 1 0">
    <FontStyle size="0.016" justify='"MIDDLE", "MIDDLE"' />
  </SliderBar>
</Frame>

In order to position the TouchButton and SliderBar relative to each other the GridInfo node is used. The padding field simply decides how much space there should be around a children of the Frame while the column and columnSpan fields decide where they should be positioned. The column field is set to 1 for the TouchButton in order to position it in the second column. For the SliderBar the sticky field is used to make the SliderBar stretch and fill all the space assigned to it. The columnSpan field is in this case used to make the SliderBar span three columns which will place the TouchButton at the horizontal center.

<Frame desiredSize="0.1 0.05 0.001">
  <TouchButton DEF="BUTTON" buttonMode="TOGGLE_RELEASE" text="Button">
    <FontStyle size="0.014" justify='"MIDDLE", "MIDDLE"' />
    <GridInfo padding="0.001 0.001" column="1"/>
  </TouchButton>
  <SliderBar DEF="SLIDERBAR" text="Slider" valueRange="0 100" value="4"
             stepLength="0.01" markerColor="1 0 0" textColor="0 1 0">
    <FontStyle size="0.016" justify='"MIDDLE", "MIDDLE"' />
    <GridInfo sticky="W+E+N+S" padding="0.001 0.001" columnSpan="3"/>
  </SliderBar>
</Frame>

The last thing to do is to give the TouchButton some kind of functionality. In this case we simply route the state field to the horizontal field of the SliderBar. Which means that when the TouchButton is enabled the slider will be a horizontal slider, otherwise it is a vertical slider.

<?xml version="1.0" encoding="utf-8"?>
<X3D profile='H3DAPI' version='1.4'>
  <Scene>
  <Frame desiredSize="0.1 0.05 0.001">
    <TouchButton DEF="BUTTON" buttonMode="TOGGLE_RELEASE" text="Button">
      <FontStyle size="0.014" justify='"MIDDLE", "MIDDLE"' />
      <GridInfo padding="0.001 0.001" column="1"/>
    </TouchButton>
    <SliderBar DEF="SLIDERBAR" text="Slider" valueRange="0 100" value="4"
               stepLength="0.01" markerColor="1 0 0" textColor="0 1 0">
      <FontStyle size="0.016" justify='"MIDDLE", "MIDDLE"' />
      <GridInfo sticky="W+E+N+S" padding="0.001 0.001" columnSpan="3"/>
    </SliderBar>
  </Frame>
 
  <ROUTE fromNode="BUTTON" fromField="state"
         toNode="SLIDERBAR" toField="horizontal" />
</Scene>
</X3D>

Note that the widgets in this example are very ugly. To improve the appearance of the widgets simply add textures to them. How this is done can be see in the examples that are distributed with the UI source or H3DAPI windows installation.

Tweaking UI

Adding new nodes to UI is just like adding new nodes to H3DAPI. Figure out which node class to inherit from, specify fields and a database object and add fields to the database. Figure out which virtual functions to override in order to get the needed functionality.

If you implement new nodes that you think would be useful for the entire H3D community then by all means supply the code to www.h3d.org through the bug tracker.

Personal tools
go to