NaviLibrary::Navi

NaviLibrary::Navi Class Reference

#include <Navi.h>

List of all members.

Public Member Functions

void navigateTo (const std::string &url)
void navigateTo (const std::string &url, const NaviData &naviData)
void navigateBack ()
void navigateForward ()
void navigateStop ()
void navigateRefresh ()
bool canNavigateBack ()
bool canNavigateForward ()
std::string evaluateJS (std::string script, const NaviUtilities::Args &args=NaviUtilities::Args())
Navi * addEventListener (NaviEventListener *newListener)
Navi * removeEventListener (NaviEventListener *removeListener)
Navi * bind (const std::string &naviDataName, const NaviDelegate &callback, const NaviUtilities::Strings &keys=NaviUtilities::Strings())
Navi * unbind (const std::string &naviDataName, const NaviDelegate &callback=NaviDelegate())
Navi * setForceMaxUpdate (bool forceMaxUpdate)
Navi * setIgnoreBounds (bool ignoreBounds=true)
Navi * setIgnoreTransparent (bool ignoreTrans, float threshold=0.05)
Navi * setMask (std::string maskFileName, std::string groupName=Ogre::ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME)
Navi * setMaxUPS (unsigned int maxUPS=0)
Navi * setMovable (bool isMovable=true)
Navi * setOpacity (float opacity)
Navi * setPosition (const NaviPosition &naviPosition)
Navi * resetPosition ()
Navi * hide (bool fade=false, unsigned short fadeDurationMS=300)
Navi * show (bool fade=false, unsigned short fadeDurationMS=300)
Navi * focus ()
Navi * moveNavi (int deltaX, int deltaY)
void getExtents (unsigned short &width, unsigned short &height)
int getRelativeX (int absX)
int getRelativeY (int absY)
bool isMaterialOnly ()
Ogre::PanelOverlayElement * getInternalPanel ()
std::string getName ()
std::string getMaterialName ()
bool getVisibility ()
void getDerivedUV (Ogre::Real &u1, Ogre::Real &v1, Ogre::Real &u2, Ogre::Real &v2)
void injectMouseMove (int xPos, int yPos)
void injectMouseWheel (int relScroll)
void injectMouseDown (int xPos, int yPos)
void injectMouseUp (int xPos, int yPos)

Detailed Description

The core class of NaviLibrary, a browser window rendered to a dynamic texture.

Member Function Documentation

void Navi::navigateTo ( const std::string &  url  ) 

Navigates this Navi to a certain URL.

Parameters:
url The URL (Web Address) to navigate to.
Note:
You may use local:// and resource:// specifiers for the URL.

void Navi::navigateTo ( const std::string &  url,
const NaviData &  naviData 
)

Navigates this Navi to a certain URL along with encoded NaviData.

Parameters:
url The URL (Web Address) to navigate to.
naviData The NaviData to send to the page.
Note:
You may use local:// and resource:// specifiers for the URL.

This method of sending NaviData has been deprecated, use JS evaluation instead.

void Navi::navigateBack (  ) 

Navigates this Navi backwards through its page history, if possible.

void Navi::navigateForward (  ) 

Navigates this Navi forwards through its page history, if possible.

void Navi::navigateStop (  ) 

Immediately halts the loading of the current page, if one is loading.

void NaviLibrary::Navi::navigateRefresh (  ) 

Reloads the page that this Navi has been navigated to.

bool Navi::canNavigateBack (  ) 

Returns whether or not this Navi can navigate further backwards through its page history.

bool Navi::canNavigateForward (  ) 

Returns whether or not this Navi can navigate further forwards through its page history.

std::string Navi::evaluateJS ( std::string  script,
const NaviUtilities::Args &  args = NaviUtilities::Args() 
)

Evaluates Javascript in the context of the current page and returns the result.

Parameters:
script The Javascript to evaluate/execute.
args An optional vector of MultiValues that will be used in the translation of a templated string of Javascript.
Returns:
If the action succeeds, this will return the result as a string (regardless of internal Javascript datatype), otherwise this returns an empty string.
Note:
For example: 
        myNavi->evaluateJS("$('myElement').setHTML('<b>Hello!</b>')");

        // The following are examples of templated evaluation:
        myNavi->evaluateJS("newCharacter(?, ?, ?)", Args(name)(age)(naviData["motto"]));
        myNavi->evaluateJS("addChatMessage(?, ?)", Args(nickname)(someWideString));
        myNavi->evaluateJS("$(?).setHTML(?)", Args("helloLabel")("Hello world!"));
        myNavi->evaluateJS("?(?, ?)", Args("myFunction")(firstVar)(secondVar));
        myNavi->evaluateJS("$(?).SetVariable(?, ?)", Args("myFlashID")("flashVariable")(favoriteColor));

Strings in the Args of templated evaluation will automatically be quoted/escaped. Wide Strings will be encoded with NaviUtilities::encodeURIComponent and then wrapped in the Javascript decoding function: "decodeURIComponent(xxx)".

Navi * Navi::addEventListener ( NaviEventListener *  newListener  ) 

Subscribes a NaviEventListener to listen for events from this Navi.

Parameters:
newListener The NaviEventListener to add.

Navi * Navi::removeEventListener ( NaviEventListener *  removeListener  ) 

Un-subscribes a NaviEventListener from this Navi.

Parameters:
removeListener The NaviEventListener to remove.

Navi * Navi::bind ( const std::string &  naviDataName,
const NaviDelegate &  callback,
const NaviUtilities::Strings &  keys = NaviUtilities::Strings() 
)

Binds the reception of a NaviData object to a delegate function (callback).

Parameters:
naviDataName The name of the NaviData to bind the callback to.
callback The NaviDelegate to bind to. Functions must return a 'void' and have one argument: 'const NaviData &naviData' 
        // Example declaration of a compatible function (static function):
        void myStaticFunction(const NaviData& naviData)
        {
                // Handle the naviData here
        }

        // Example declaration of a compatible function (member function):
        void MyClass::myMemberFunction(const NaviData& naviData)
        {
                // Handle the naviData here
        }

        // NaviDelegate (member function) instantiation:
        NaviDelegate callback(this, &MyClass::myMemberFunction); // within a class
        NaviDelegate callback2(pointerToClassInstance, &MyClass::myMemberFunction);

        // NaviDelegate (static function) instantiation:
        NaviDelegate callback(&myStaticFunction);
keys An optional string vector containing the keys to ensure. See NaviData::ensure (second overload).
Note:
It is highly advised to use NaviUtilities::Strings to invoke the 'keys' parameter.
An example of usage: 
        chatNavi->bind("messageSent", NaviDelegate(this, &NaviDemo::messageSent), Strings("nick")("message"));

Navi * Navi::unbind ( const std::string &  naviDataName,
const NaviDelegate &  callback = NaviDelegate() 
)

Un-binds a certain NaviDelegate from a certain NaviData.

Parameters:
naviDataName The name of the NaviData to unbind.
callback The specific NaviDelegate to unbind. This is optional, if it is left blank, all bindings to 'naviDataName' will be released.

Navi * Navi::setForceMaxUpdate ( bool  forceMaxUpdate  ) 

Toggles between auto-updating and force-updating.

Parameters:
forceMaxUpdate Navis normally only update when the page has changed, to override this functionality set this parameter to 'True' to make this Navi 'force update' using the value of the parameter 'maxUpdatesPerSec'. This is useful as a work-around for rendering embedded Flash applications. Note: if 'maxUpdatesPerSec' is 0, this Navi will try to 'force update' every single chance it gets (not recommended). Set this to 'False' to make this Navi update only when the page changes (auto-updating).

Navi * Navi::setIgnoreBounds ( bool  ignoreBounds = true  ) 

Normally, mouse movement is only injected into a specific Navi from NaviManager if the mouse is within the boundaries of a Navi and over an opaque area (not transparent). This behavior may be detrimental to certain Navis, for example an animated 'dock' with floating icons on a transparent background: the mouse-out event would never be invoked on each icon because the Navi only received mouse movement input over opaque areas. Use this function to makes this Navi always inject mouse movement, regardless of boundaries or transparency.

Parameters:
ignoreBounds Whether or not this Navi should ignore bounds/transparency when injecting mouse movement.
Note:
The occlusivity of each Navi will still be respected, mouse movement will not be injected if another Navi is occluding this Navi.

Navi * Navi::setIgnoreTransparent ( bool  ignoreTrans,
float  threshold = 0.05 
)

Using alpha-masking/color-keying doesn't just affect the visuals of a Navi; by default, Navis 'ignore' mouse movement/clicks over 'transparent' areas of a Navi (Areas with opacity less than 5%). You may disable this behavior or redefine the 'transparent' threshold of opacity to something else other than 5%.

Parameters:
ignoreTrans Whether or not this Navi should ignore 'transparent' areas when mouse-picking.
defineThreshold Areas with opacity less than this percent will be ignored (if ignoreTrans is true, of course). Default is 5% (0.05).

Navi * Navi::setMask ( std::string  maskFileName,
std::string  groupName = Ogre::ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME 
)

Masks the alpha channel of this Navi with that of a provided image.

Parameters:
maskFileName The filename of the Alpha Mask Image. The Alpha Mask Image MUST have a width greater than or equal to the Navi width and it MUST have a height greater than or equal to the Navi height. Alpha Mask Images larger than the Navi will not be stretched, instead Navi will take Alpha values starting from the Top-Left corner of the Alpha Mask Image. To reset Navi to use no Alpha Mask Image, simply provide an empty String ("").
groupName The Resource Group to find the Alpha Mask Image filename.
Exceptions:
Ogre::Exception::ERR_INVALIDPARAMS Throws this if the width or height of the Alpha Mask Image is less than the width or height of the Navi it is applied to.

Navi * Navi::setMaxUPS ( unsigned int  maxUPS = 0  ) 

Adjusts the number of times per second this Navi may update.

Parameters:
maxUPS The maximum number of times per second this Navi can update. Set this to '0' to use no update limiting. If this Navi is force-updating (see Navi::setForceMaxUpdate), this value is used as the number of updates per second to actually do.

Navi * Navi::setMovable ( bool  isMovable = true  ) 

Toggles whether or not this Navi is movable. (not applicable to NaviMaterials)

Parameters:
isMovable Whether or not this Navi should be movable.

Navi * Navi::setOpacity ( float  opacity  ) 

Changes the overall opacity of this Navi to a certain percentage.

Parameters:
opacity The opacity percentage as a float. Fully Opaque = 1.0, Fully Transparent = 0.0.

Navi * Navi::setPosition ( const NaviPosition &  naviPosition  ) 

Sets the default position of this Navi to a new position and then moves the Navi to that position. (not applicable to NaviMaterials)

Parameters:
naviPosition The new NaviPosition to set the Navi to.

Navi * Navi::resetPosition (  ) 

Resets the position of this Navi to its default position. (not applicable to NaviMaterials)

Navi * Navi::hide ( bool  fade = false,
unsigned short  fadeDurationMS = 300 
)

Hides this Navi.

Parameters:
fade Whether or not to fade this Navi down. (Optional, default is false)
fadeDurationMS If fading, the number of milliseconds to fade for.

Navi * Navi::show ( bool  fade = false,
unsigned short  fadeDurationMS = 300 
)

Shows this Navi.

Parameters:
fade Whether or not to fade the Navi up. (Optional, default is false)
fadeDurationMS If fading, the number of milliseconds to fade for.

Navi * Navi::focus (  ) 

'Focuses' this Navi by popping it to the front of all other Navis. (not applicable to NaviMaterials)

Navi * Navi::moveNavi ( int  deltaX,
int  deltaY 
)

Moves this Navi by relative amounts. (not applicable to NaviMaterials or non-movable Navis)

Parameters:
deltaX The relative X amount to move this Navi by. Positive amounts move it right.
deltaY The relative Y amount to move this Navi by. Positive amounts move it down.

void Navi::getExtents ( unsigned short &  width,
unsigned short &  height 
)

Retrieves the width and height that this Navi was created with.

Parameters:
[out] width The unsigned short that will be used to store the retrieved width.
[out] height The unsigned short that will be used to store the retrieved height.

int Navi::getRelativeX ( int  absX  ) 

Transforms an X-coordinate in screen-space to that of this Navi's relative space.

Parameters:
absX The X-coordinate in screen-space to transform.
Returns:
The X-coordinate in this Navi's relative space.

int Navi::getRelativeY ( int  absY  ) 

Transforms a Y-coordinate in screen-space to that of this Navi's relative space.

Parameters:
absX The Y-coordinate in screen-space to transform.
Returns:
The Y-coordinate in this Navi's relative space.

bool Navi::isMaterialOnly (  ) 

Returns whether or not this Navi was created as a NaviMaterial.

Ogre::PanelOverlayElement * Navi::getInternalPanel (  ) 

Gets a pointer to the Ogre::OverlayContainer (Panel) that is used internally for this Navi. (not applicable to NaviMaterials)

Returns:
If the Navi is found and it is NOT a NaviMaterial, returns a pointer to the Panel, otherwise 0 is returned.

std::string Navi::getName (  ) 

Returns the name of this Navi.

std::string Navi::getMaterialName (  ) 

Returns the name of the Ogre::Material used internally by this Navi.

bool Navi::getVisibility (  ) 

Returns whether or not this Navi is currently visible. (See Navi::hide and Navi::show)

void Navi::getDerivedUV ( Ogre::Real &  u1,
Ogre::Real &  v1,
Ogre::Real &  u2,
Ogre::Real &  v2 
)

Gets the derived UV's of this Navi's internal texture. On certain systems we must compensate for lack of NPOT-support on the videocard by using the next-highest POT texture. Normal Navi's compensate their UV's accordingly however NaviMaterials will need to adjust their own by use of this function.

Parameters:
[out] u1 The Ogre::Real that will be used to store the retrieved u1-coordinate.
[out] v1 The Ogre::Real that will be used to store the retrieved v1-coordinate.
[out] u2 The Ogre::Real that will be used to store the retrieved u2-coordinate.
[out] v2 The Ogre::Real that will be used to store the retrieved v2-coordinate.

void Navi::injectMouseMove ( int  xPos,
int  yPos 
)

Injects the mouse's current coordinates (in this Navi's own local coordinate space, see Navi::getRelativeX and Navi::getRelativeY) into this Navi.

Parameters:
xPos The X-coordinate of the mouse, relative to this Navi's origin.
yPos The Y-coordinate of the mouse, relative to this Navi's origin.

void Navi::injectMouseWheel ( int  relScroll  ) 

Injects mouse wheel events into this Navi.

Parameters:
relScroll The relative Scroll-Value of the mouse.
Note:
To inject this using OIS: on a OIS::MouseListener::MouseMoved event, simply inject "arg.state.Z.rel" of the "MouseEvent".

void Navi::injectMouseDown ( int  xPos,
int  yPos 
)

Injects mouse down events into this Navi. You must supply the current coordinates of the mouse in this Navi's own local coordinate space. (see Navi::getRelativeX and Navi::getRelativeY)

Parameters:
xPos The absolute X-Value of the mouse, relative to this Navi's origin.
yPos The absolute Y-Value of the mouse, relative to this Navi's origin.

void Navi::injectMouseUp ( int  xPos,
int  yPos 
)

Injects mouse up events into this Navi. You must supply the current coordinates of the mouse in this Navi's own local coordinate space. (see Navi::getRelativeX and Navi::getRelativeY)

Parameters:
xPos The absolute X-Value of the mouse, relative to this Navi's origin.
yPos The absolute Y-Value of the mouse, relative to this Navi's origin.

The documentation for this class was generated from the following files:
Generated on Tue Jun 10 22:33:20 2008 for NaviLibrary by  doxygen 1.5.3