NaviLibrary Overview
From NaviWiki
Contents |
What is Navi?
How can Navi help?
The solution was simple: wouldn't it be cool if we could just make the GUI with HTML?
With the NaviLibrary, you can!
Utilizing the LLMozLib library (an awesome wrapper that allows us to embed Gecko, Mozilla's rendering engine) we are able to render a browser window to a texture. NaviLibrary handles the rest.
Before we go any further, a 'Navi' is essentially a GUI Window. It is the simple combination of a rendered browser window, an Ogre Overlay, and an optional alpha mask and/or color-key. The word 'Navi' both refers to the actual library and the Dynamic GUI Window you can create with it, a 'Navi'. To create a 'Navi' with the 'Navi' library, all you have to do is:
- Write a page. You will need to know some very basic javascript.
- Tell NaviManager about your new 'Navi' and the size you want it to be.
- Register a class to handle events AND/OR bind NaviData to specific functions
- Inject mouse input from your favorite Input library.
That's it!
Features
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!).
So just what can Navi do?
- 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.
NaviData
NaviData is the elegant message-passing system that you may use to pass data from your Ogre Application to your Navi Page and vice-versa.
The inner-workings are pretty ingenious but they effectively allow you to serialize and deserialize groups of dynamic 'parameters' (either a String, Integer, or Float) that may be queried for value and name on both ends.
Navi provides you with a Javascript library to embed in your pages if you wish to use the NaviData system.
The common usage of NaviData is to send data/events from a page to the application. Check out Tutorial 2 for more info.
Flash
LLMozLib has limited support for Flash applications and cannot (at this time) inject inputs into Flash objects. This does not stop us from watching (and listening, LLMozLib hooks into your sound system) to Flash applications!
The trick is that internally we are not notified of changes to Flash objects and so we must 'force' several updates a second if we are to watch Flash video/animation.
NaviManager effortlessly allows you to 'Force-Update' a Navi, just specify the Updates Per Second you wish a specific Navi to force-update. (About 18 times per second is usually enough to watch Youtube video without a hitch)
XUL
XUL (pronounced 'Zool', rhymes with cool; XML User-interface Language) is a cross-platform language for describing user interfaces of applications. Obviously in the context of what Navi is, this is just way too cool. The syntax is very simple and straightforward and everything can be modified by CSS and Javascript.
I highly recommend looking into XUL more if you're interested in learning new technology.
There are a few slight problems with XUL in Navi right now, specifically 'pop-up' menus and 'pop-up' color-pickers rendering outside the actual Render Window. Other than that, XUL works flawlessly, feel free to navigate to some XUL examples in the Navi Demo. (Or if you're using a Firefox that has XUL support, check this out!).
Limitations?
License
I am releasing Navi under the LGPL (GNU Lesser General Public License) with two stipulations:
- Any changes to the Navi library must be made available to me
- If you use it in a project, tell me about it! :)
The Bad
- Navis cannot be resized. Navi likes to stay crisp and clean (and fast!) and doesn't believe in bilinear filtering.
- Alpha Masks must be either the same size or bigger than the Navi it is masking. Again, bilinear filtering is expensive and also Navi is committed to being pixel-perfect (fuzzy edges on a Mask is not pretty). If you apply an Alpha Mask that is larger than the Navi it is applied to, it will not stretch; instead it will be applied starting at the top-left corner of the Alpha Mask texture.
