NaviLibrary        
Page actions
Print

What is Navi?

It all started with a single question: Couldn't we just make GUI's using HTML?

A few months later and a lot of tinkering with Gecko and LLMozLib, NaviLibrary answered: yes.

The beauty of using NaviLibrary is that the languages used (HTML, CSS, JS) are stable, widely-documented, and popular. The learning curve is shallow (as opposed to having to learn a proprietary syntax), development goes fast due to fast-prototyping (plethora of WYSIWYG editors), and existing web design talent is easy to find (heck, who doesn't know HTML nowadays?).

Navi is so much more than just your average -GUI solution, because we are essentially embedding Gecko (think Firefox), almost everything you can do with Web 2.0 you can do inside an Ogre3D application. Yahoo's UI library, Dojo, MooTools, SVG, XUL, AJAX, Flash (more on that later), you name it. Thanks to LLMozLib and Mozilla, Navi can do it (and you can too!).

Features

  • Movable - Navis are movable. Simply right-click and drag to move a Navi around the window.
  • Alpha-Masking - Navis can dynamically be masked using an alpha-mask.
  • Color-Keying - Navis can be also make use of dynamic color-keying to replace a certain color with another color + opacity. As of v1.2, Navi can also do 'fuzzy' color-keying (with subsequent calculation of relative opacity based on color distance of individual pixels)!
  • Dynamic Opacity - Navis can change opacity easily and dynamically.
  • Transparency affects interaction - If a user hovers their mouse or clicks in an area of a Navi that is transparent (less than 5% opacity) the input will not be registered. Your alpha-mask/color-key/opacity settings actually affect how a user interacts with a Navi!
  • Absolute and Relative Positioning - Navis can be absolutely and relatively positioned on the screen. Relatively positioned (Top-Left, Top-Center, Top-Right, Right, Bottom-Right, Bottom-Center, Bottom-Left, Left, Center)

Navis are not able to be moved however they dynamically reposition themselves when the render window is resized.

  • Smart Input Injection - NaviManager manages and translates all mouse input for you. When injecting inputs, a boolean return value may specify, for example, whether the current mouse position is over a Navi or not.
  • Efficient - Navis are very efficient; they are smart enough to only update their internal texture when something on the page has changed.
  • Update Limiting - If you find that Navi updates too often (pages with animated javascript may cause the page to update over-actively), you may limit the number of Updates per Second.
  • Z-Order Popping - Navis change Z-Order and move on top of other Navis when they are selected.
  • No Need for Key Injection - There is no need to inject keyboard input because internally, LLMozLib captures such input and relays it to Gecko for you. Hold down keys while a textbox is focused and the key will repeat. Ctrl+C and Ctrl+V to copy and paste all work like normal.
  • Programmatic Navi Page Creation - Thanks to DataURI's, you may create the pages that a Navi can navigate to at runtime. Simply define a string with all the HTML in it (escaping where necessary). You may use "local://" and "resource://" (see below) specifiers inside this HTML string to refer to other resources.
  • Local Specifiers - Navi can be pointed to local directories through use of the 'local://' prefix. Local means relative to the 'NaviPages' folder of the directory of the running executable. You can tell the NaviManager to point 'local://' to another folder if you wish.
  • Ogre Resource Utilization - Again thanks to DataURI's, you can use an Ogre Resource (.html/.js/.css/.jpg/etc.) as a Navi page or use the "local://" and "resource://GroupName/FileName.ext" specifiers inside 'parsed' pages (programmatic pages and pages loaded from an Ogre Resource). If speed is your main concern, it's still best to just use the regular "NaviLocal" method.
  • Javascript Evaluation - You can execute/evaluate arbitrary Javascript in the context of the page that the Navi is currently navigated to! This is incredibly useful and makes updating/accessing page content a breeze.
  • NaviMaterials - NaviMaterials are simply Ogre Materials (the above API call returns the name of the Ogre Material) that you can apply to any Ogre Entity of your choosing. They act just like any other Navi except that they lack an overlay. The only catch is that you must handle all mouse input injection into these NaviMaterials. If you're looking to embed a Navi inside of another Ogre3D -GUI library, you may derive a TexturePtr from this material and apply it to anything you like.
  • The Web at your Fingertips - Navi opens up an entire new dimension to Ogre3D Applications: the Internet. Use AJAX to fetch/send data without the need of an extra networking library, use Javascript to validate and extend the functionality of your Navi pages, use Flash to show video clips, etc! Get creative, get smart, get Navi.

Example Usage

Calling a javascript function from inside Ogre: 

//Passing a function to a Navi object pointer named NaviWidget.
 NaviWidget->evaluateJS("nameOfJavascriptFunction(?)",Args("ExampleParam"));



MadMark has graciously provided Lua bindings for NaviLibrary. Please go here for more information.

XUL

XML User Interface Language

One being the ability to skin the Mozilla-engine it with CSS, so the "native" scrollbars and widgets can blend perfectly with your UI without you having to write your own scrollbars in JS, and the other one, which I am only beginning to explore is the use of XUL. It gives you access to a whole set of ready made "native" skinnable widgets and dialogues with a nice performance gain compared to selfmade DHTML widgets, and you don't have to reinvent the wheel over and over. I would go as far as to say the use of XUL within Navi could be a solid alternate to the use of native GUIs outside the renderwindow. XUL is also what firefox, mozilla & plugins are using for their own GUI. --Nauk

Benchmark: Comparing a treeview control 

Rendering Speed            DHTML Tree        XUL Tree
    Small Tree (20 nodes)      30 ms             15ms
    Medium Tree (200 nodes)    421 ms            62 ms
    Large Tree (2000 nodes)    4400 ms           650 ms


Alias: Navi

History Source