/* This file is part of Navi, a library that allows developers to embed movable 'Navis' (Dynamic, HTML/JS/CSS-Driven GUI Overlays) within an Ogre3D application. Copyright (C) 2007 Adam J. Simmons http://www.agelessanime.com/Navi/ This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA */ #pragma once #include #include #include #include #include #include "NaviData.h" #include "NaviEventListener.h" namespace NaviLibrary { class Navi; /** * Enumerates relative NaviPositions. Used by NaviManager::createNavi */ enum NaviPosition { Left, TopLeft, TopCenter, TopRight, Right, BottomRight, BottomCenter, BottomLeft, Center }; /** * Enumerates internal mouse button IDs. Used by NaviManager::injectMouseDown, NaviManager::injectMouseUp */ enum MouseButtonID { LeftMouseButton = 0, RightMouseButton, MiddleMouseButton }; /** * Supreme dictator and Singleton: NaviManager * * The class you will need to go to for all your Navi-related needs. */ class NaviManager { friend Navi; // Our very close friend <3 bool startedUp; std::string localNaviDirectory; std::map activeNavis; Navi* focusedNavi; int hiddenWindowID; std::map::iterator iter; Ogre::RenderWindow* renderWindow; int mouseXPos, mouseYPos; bool mouseButtonRDown; unsigned short zOrderCounter; /** * Private Constructor/Destructor * Please use NaviManager::Get to get the NaviManager Singleton */ NaviManager(); ~NaviManager(); /** * Private utility functions perform various literal tasks */ void focusNavi(int x, int y); std::vector& getNavisAtPoint(int x, int y); std::vector& getNavis(); void deFocusAllNavis(); public: /// ----- STUFF YOU CAN ACCESS STARTS HERE ----- /// /** * Gets the NaviManager Singleton, this is the only way to access NaviManager. * * @return A reference to the NaviManager Singleton. */ static NaviManager& Get(); /** * Starts up the NaviManager and internal LLMozLib library. * * @param _renderWindow The Ogre::RenderWindow to render Navis to * * @param _localNaviDirectory By default, "local://" means something like: * "C:\MyApplicationDirectory\NaviLocal\" but by changing * this parameter, you can change "NaviLocal" to something else. * * @throws Ogre::Exception::ERR_INTERNAL_ERROR Throws this when LLMozLib fails initialization */ void Startup(Ogre::RenderWindow* _renderWindow, std::string _localNaviDirectory = "NaviLocal"); /** * Gives each active Navi a chance to update, each may or may not update their internal textures * based on various conditions. */ void Update(); /** * Destroys any active Navis and shuts down the LLMozLib library. */ void Shutdown(); /** * Creates a Navi. (You MUST call Startup() before this.) * * @param naviName The name of the Navi, used to refer to a specific Navi in subsequent calls. * * @param homepage The default starting page for a Navi. You may use local:// here to refer to * the local Navi directory (See NaviManager::Startup) * * @param left For absolute positioned Navis, how many pixels from the Left of the screen to * initially place the Navi. * * @param top For absolute positioned Navis, how many pixels from the Top of the screen to * initially place the Navi. * * @param width The width of the Navi. MUST be a power of 2 (e.g. 128, 256, 512, 1024) * Technically you may be able to use a number that is divisible by 16 but * please be mindful of the 2^n texture size limitation of certain video cards * * @param height The height of the Navi. MUST be a power of 2 (e.g. 128, 256, 512, 1024) * Technically you may be able to use a number that is divisible by 16 but * please be mindful of the 2^n texture size limitation of certain video cards * * @param isMovable Whether or not this absolutely positioned Navi is movable (right-click-drag to move) * * @param maxUpdatesPerSec This parameter limits the number of updates per second to a specific * integer. To use no limiting, leave this parameter as '0'. This limiting is * useful if, for example, you had some very hyperactive Javascript * that animated a moving ball. Without update limiting, Navi will try to update * itself at every possible moment: this is great for very smooth animation but * bad for the overall framerate. * * @param forceMaxUpdate Navi normally only updates when the page has changed, to override this functionality * set this parameter to 'True' to make 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, Navi will try to 'force update' * every single chance it gets (not recommended). * * @param zOrder Sets the starting Z-Order for this Navi; Navis with higher Z-Orders will be on top of other * Navis. To auto-increment this value for every successive Navi, leave this parameter as '0'. * * @param opacity Sets the starting Opacity of the Navi. * Ex. 1.0000 = Fully opaque * Ex. 0.5000 = Half opaque * Ex. 0.0000 = Totally transparent * * @throws Ogre::Exception::ERR_RT_ASSERTION_FAILED Throws this if NaviManager::Startup is not called prior to this. */ void createNavi(std::string naviName, std::string homepage, unsigned short left, unsigned short top, unsigned short width, unsigned short height, bool isMovable = true, unsigned int maxUpdatesPerSec = 0, bool forceMaxUpdate = false, unsigned short zOrder = 0, float opacity = 1.0); /** * Creates a Navi. (You MUST call Startup() before this.) * * @param naviName The name of the Navi, used to refer to a specific Navi in subsequent calls. * * @param homepage The default starting page for a Navi. You may use local:// here to refer to * the local Navi directory (See NaviManager::Startup) * * @param position The relative position of the Navi. Relatively positioned Navis are not movable * however they automatically move to the correct relative coordinates when the window * is resized. Possible values include: Left, TopLeft, TopCenter, TopRight, Right, * BottomRight, BottomCenter, BottomLeft, and Center. * * @param width The width of the Navi. MUST be a power of 2 (e.g. 128, 256, 512, 1024) * Technically you may be able to use a number that is divisible by 16 but * please be mindful of the 2^n texture size limitation of certain video cards * * @param height The height of the Navi. MUST be a power of 2 (e.g. 128, 256, 512, 1024) * Technically you may be able to use a number that is divisible by 16 but * please be mindful of the 2^n texture size limitation of certain video cards * * @param maxUpdatesPerSec This parameter limits the number of updates per second to a specific * integer. To use no limiting, leave this parameter as '0'. This limiting is * useful if, for example, you had some very hyperactive Javascript * that animated a moving ball. Without update limiting, Navi will try to update * itself at every possible moment: this is great for very smooth animation but * bad for the overall framerate. * * @param forceMaxUpdate Navi normally only updates when the page has changed, to override this functionality * set this parameter to 'True' to make 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, Navi will try to 'force update' * every single chance it gets (not recommended). * * @param zOrder Sets the starting Z-Order for this Navi; Navis with higher Z-Orders will be on top of other * Navis. To auto-increment this value for every successive Navi, leave this parameter as '0'. * * @param opacity Sets the starting Opacity of the Navi. * Ex. 1.0000 = Fully opaque * Ex. 0.5000 = Half opaque * Ex. 0.0000 = Totally transparent * * @throws Ogre::Exception::ERR_RT_ASSERTION_FAILED Throws this if NaviManager::Startup is not called prior to this. */ void createNavi(std::string naviName, std::string homepage, NaviPosition position, unsigned short width, unsigned short height, unsigned int maxUpdatesPerSec = 0, bool forceMaxUpdate = false, unsigned short zOrder = 0, float opacity = 1.0); /** * Changes the page of the Navi to a supplied URL String. * * @param naviName The name of the Navi to do this to * * @param url The URL to navigate to. You may use the "local://" protocol here. */ void navigateNaviTo(std::string naviName, std::string url); /** * Changes the page of the Navi to a supplied URL String and sends NaviData to the page. * * @param naviName The name of the Navi to do this to. * * @param url The URL to navigate to. You may use the "local://" protocol here. * * @param naviData The NaviData to send. */ void navigateNaviTo(std::string naviName, std::string url, NaviData &naviData); /** * Returns whether or not the page of the Navi can navigate backwards * * @param naviName The name of the Navi to do this to. */ bool canNavigateBack(std::string naviName); /** * Navigates the page of the Navi backwards, if possible * * @param naviName The name of the Navi to do this to. */ void navigateNaviBack(std::string naviName); /** * Returns whether or not the page of the Navi can navigate forwards * * @param naviName The name of the Navi to do this to. */ bool canNavigateForward(std::string naviName); /** * Navigates the page of the Navi forwards, if possible * * @param naviName The name of the Navi to do this to. */ void navigateNaviForward(std::string naviName); /** * If a Navi's page is loading, stops the load * * @param naviName The name of the Navi to do this to. */ void navigateNaviStop(std::string naviName); /** * Destroys a Navi. * * @param naviName The name of the Navi to do this to. */ void destroyNavi(std::string naviName); /** * Sets the default color to use between changing pages, the default is White if you never call this. * * @param naviName The name of the Navi to do this to. * * @param red The Red color value as a float; maximum 1.0, minimum 0.0. * @param green The Green color value as a float; maximum 1.0, minimum 0.0. * @param blue The Blue color value as a float; maximum 1.0, minimum 0.0. */ void setNaviBackgroundColor(std::string naviName, float red = 1.0f, float green = 1.0f, float blue = 1.0f); /** * Changes the Opacity of a Navi to a provided float. * * @param naviName The name of the Navi to do this to. * * @param opacity The Opacity value as a float. * Fully Opaque = 1.0, Fully Transparent = 0.0. */ void setNaviOpacity(std::string naviName, float opacity = 1.0f); /** * Sets the filename of the Alpha Mask Image. Navi will use the alpha channel values of the provided image * to mask a Navi dynamically. * * @param naviName The name of the Navi to do this to. * * @param 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 ("") * * @param groupName The Resource Group to find the Alpha Mask Image filename. * * @throws 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. */ void setNaviMask(std::string naviName, std::string maskFileName, std::string groupName = Ogre::ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME); /** * Limits the number of times per second a Navi may update. * * @param naviName The name of the Navi to do this to. * * @param maxUPS The maximum number of times per second a Navi can update. Set this to '0' to use * no update limiting. * * If the current Navi is set to 'Force Max Updates', this value is used as the number * of updates per second to actually do. */ void setMaxUpdatesPerSec(std::string naviName, unsigned int maxUPS = 0); /** * Toggles between auto-updating and force-updating. * * @param naviName The name of the Navi to do this to. * * @param forceMaxUpdate Navi normally only updates when the page has changed, to override this functionality * set this parameter to 'True' to make 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, Navi will try to 'force update' * every single chance it gets (not recommended). * * Set this to 'False' to make Navi update only when the page changes (auto-updating). */ void setForceMaxUpdate(std::string naviName, bool forceMaxUpdate = false); /** * Checks whether or not a Navi is focused/selected. * * @return True if a Navi is focused, False otherwise. */ bool isAnyNaviFocused(); /** * Gets the name of the currently focused/selected Navi. * * @return If a Navi is focused, returns the name of the Navi. Otherwise it returns an empty string (""). */ std::string getFocusedNaviName(); /** * Injects absolute mouse coordinates into NaviManager. Used to generally keep track of where the mouse * is for things like moving Navis around, telling the internal pages of each Navi where the mouse is and * where the user has clicked, etc. * * @param xPos The absolute X-Value of the mouse. * @param yPos The absolute Y-Value of the mouse. * * @return Returns True if the injected coordinate is over a Navi, False otherwise. */ bool injectMouseMove(int xPos, int yPos); /** * Injects mouse wheel events into NaviManager. Used to scroll the focused Navi. * * @param 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". * * @return Returns True if the mouse wheel was scrolled while a Navi was focused, False otherwise. */ bool injectMouseWheel(int relScroll); /** * Injects mouse down events into NaviManager. Used to know when the user has pressed a mouse button * and which button they used. * * @param buttonID The ID of the button that was pressed. Left = 0, Right = 1, Middle = 2. * * @return Returns True if the mouse went down over a Navi, False otherwise. */ bool injectMouseDown(int buttonID); /** * Injects mouse up events into NaviManager. Used to know when the user has released a mouse button * and which button they used. * * @param buttonID The ID of the button that was released. Left = 0, Right = 1, Middle = 2. * * @return Returns True if the mouse went up while a Navi was focused, False otherwise. */ bool injectMouseUp(int buttonID); /** * Subscribes a NaviEventListener to listen for events from a certain Navi. * * @param naviName The name of the Navi to do this to. * * @param newListener The address of the NaviEventListener. */ void addNaviEventListener(std::string naviName, NaviEventListener* newListener); /** * Un-subscribes a NaviEventListener from a certain Navi. * * @param naviName The name of the Navi to do this to. * * @param newListener The address of the NaviEventListener to remove. */ void removeNaviEventListener(std::string naviName, NaviEventListener* removeListener); }; }