diff options
Diffstat (limited to 'src/guichan/include/guichan/gui.hpp')
| -rw-r--r-- | src/guichan/include/guichan/gui.hpp | 505 |
1 files changed, 505 insertions, 0 deletions
diff --git a/src/guichan/include/guichan/gui.hpp b/src/guichan/include/guichan/gui.hpp new file mode 100644 index 000000000..17d49c979 --- /dev/null +++ b/src/guichan/include/guichan/gui.hpp @@ -0,0 +1,505 @@ +/* _______ __ __ __ ______ __ __ _______ __ __ + * / _____/\ / /\ / /\ / /\ / ____/\ / /\ / /\ / ___ /\ / |\/ /\ + * / /\____\// / // / // / // /\___\// /_// / // /\_/ / // , |/ / / + * / / /__ / / // / // / // / / / ___ / // ___ / // /| ' / / + * / /_// /\ / /_// / // / // /_/_ / / // / // /\_/ / // / | / / + * /______/ //______/ //_/ //_____/\ /_/ //_/ //_/ //_/ //_/ /|_/ / + * \______\/ \______\/ \_\/ \_____\/ \_\/ \_\/ \_\/ \_\/ \_\/ \_\/ + * + * Copyright (c) 2004 - 2008 Olof Naessén and Per Larsson + * + * + * Per Larsson a.k.a finalman + * Olof Naessén a.k.a jansem/yakslem + * + * Visit: http://guichan.sourceforge.net + * + * License: (BSD) + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * 3. Neither the name of Guichan nor the names of its contributors may + * be used to endorse or promote products derived from this software + * without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED + * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF + * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#ifndef GCN_GUI_HPP +#define GCN_GUI_HPP + +#include <list> +#include <deque> + +#include "guichan/keyevent.hpp" +#include "guichan/mouseevent.hpp" +#include "guichan/mouseinput.hpp" +#include "guichan/platform.hpp" + +namespace gcn +{ + class FocusHandler; + class Graphics; + class Input; + class KeyListener; + class Widget; + + // The following comment will appear in the doxygen main page. + /** + * @mainpage + * @section Introduction + * This documentation is mostly intended as a reference to the API. If you want to get started with Guichan, we suggest you check out the programs in the examples directory of the Guichan release. + * @n + * @n + * This documentation is, and will always be, work in progress. If you find any errors, typos or inconsistencies, or if you feel something needs to be explained in more detail - don't hesitate to tell us. + */ + + /** + * Contains a Guichan GUI. This is the core class of Guichan to which + * implementations of back ends are passed, to make Guichan work with + * a specific library, and to where the top widget (root widget of GUI) + * is added. If you want to be able to have more then one widget in your + * GUI, the top widget should be a container. + * + * A Gui object cannot work properly without passing back end + * implementations to it. A Gui object must have an implementation of a + * Graphics and an implementation of Input. + * + * NOTE: A complete GUI also must have the ability to load images. + * Images are loaded with the Image class, so to make Guichan + * able to load images an implementation of ImageLoader must be + * passed to Image. + * + * @see Graphics, Input, Image + */ + class GCN_CORE_DECLSPEC Gui + { + public: + + /** + * Constructor. + */ + Gui(); + + /** + * Destructor. + */ + virtual ~Gui(); + + /** + * Sets the top widget. The top widget is the root widget + * of the GUI. If you want a GUI to be able to contain more + * than one widget the top widget should be a container. + * + * @param top The top widget. + * @see Container + * @since 0.1.0 + */ + virtual void setTop(Widget* top); + + /** + * Gets the top widget. The top widget is the root widget + * of the GUI. + * + * @return The top widget. NULL if no top widget has been set. + * @since 0.1.0 + */ + virtual Widget* getTop() const; + + /** + * Sets the graphics object to use for drawing. + * + * @param graphics The graphics object to use for drawing. + * @see getGraphics, AllegroGraphics, HGEGraphics, + * OpenLayerGraphics, OpenGLGraphics, SDLGraphics + * @since 0.1.0 + */ + virtual void setGraphics(Graphics* graphics); + + /** + * Gets the graphics object used for drawing. + * + * @return The graphics object used for drawing. NULL if no + * graphics object has been set. + * @see setGraphics, AllegroGraphics, HGEGraphics, + * OpenLayerGraphics, OpenGLGraphics, SDLGraphics + * @since 0.1.0 + */ + virtual Graphics* getGraphics() const; + + /** + * Sets the input object to use for input handling. + * + * @param input The input object to use for input handling. + * @see getInput, AllegroInput, HGEInput, OpenLayerInput, + * SDLInput + * @since 0.1.0 + */ + virtual void setInput(Input* input); + + /** + * Gets the input object being used for input handling. + * + * @return The input object used for handling input. NULL if no + * input object has been set. + * @see setInput, AllegroInput, HGEInput, OpenLayerInput, + * SDLInput + * @since 0.1.0 + */ + virtual Input* getInput() const; + + /** + * Performs logic of the GUI. By calling this function all logic + * functions down in the GUI heirarchy will be called. When logic + * is called for Gui, user input will be handled. + * + * @see Widget::logic + * @since 0.1.0 + */ + virtual void logic(); + + /** + * Draws the GUI. By calling this funcion all draw functions + * down in the GUI hierarchy will be called. When draw is called + * the used Graphics object will be initialised and drawing of + * the top widget will commence. + * + * @see Widget::draw + * @since 0.1.0 + */ + virtual void draw(); + + /** + * Focuses none of the widgets in the Gui. + * + * @since 0.1.0 + */ + virtual void focusNone(); + + /** + * Sets tabbing enabled, or not. Tabbing is the usage of + * changing focus by utilising the tab key. + * + * @param tabbing True if tabbing should be enabled, false + * otherwise. + * @see isTabbingEnabled + * @since 0.1.0 + */ + virtual void setTabbingEnabled(bool tabbing); + + /** + * Checks if tabbing is enabled. + * + * @return True if tabbing is enabled, false otherwise. + * @see setTabbingEnabled + * @since 0.1.0 + */ + virtual bool isTabbingEnabled(); + + /** + * Adds a global key listener to the Gui. A global key listener + * will receive all key events generated from the GUI and global + * key listeners will receive the events before key listeners + * of widgets. + * + * @param keyListener The key listener to add. + * @see removeGlobalKeyListener + * @since 0.5.0 + */ + virtual void addGlobalKeyListener(KeyListener* keyListener); + + /** + * Removes global key listener from the Gui. + * + * @param keyListener The key listener to remove. + * @throws Exception if the key listener hasn't been added. + * @see addGlobalKeyListener + * @since 0.5.0 + */ + virtual void removeGlobalKeyListener(KeyListener* keyListener); + + protected: + /** + * Handles all mouse input. + * + * @since 0.6.0 + */ + virtual void handleMouseInput(); + + /** + * Handles key input. + * + * @since 0.6.0 + */ + virtual void handleKeyInput(); + + /** + * Handles mouse moved input. + * + * @param mouseInput The mouse input to handle. + * @since 0.6.0 + */ + virtual void handleMouseMoved(const MouseInput& mouseInput); + + /** + * Handles mouse pressed input. + * + * @param mouseInput The mouse input to handle. + * @since 0.6.0 + */ + virtual void handleMousePressed(const MouseInput& mouseInput); + + /** + * + * Handles mouse wheel moved down input. + * + * @param mouseInput The mouse input to handle. + * @since 0.6.0 + */ + virtual void handleMouseWheelMovedDown(const MouseInput& mouseInput); + + /** + * Handles mouse wheel moved up input. + * + * @param mouseInput The mouse input to handle. + * @since 0.6.0 + */ + virtual void handleMouseWheelMovedUp(const MouseInput& mouseInput); + + /** + * Handles mouse released input. + * + * @param mouseInput The mouse input to handle. + * @since 0.6.0 + */ + virtual void handleMouseReleased(const MouseInput& mouseInput); + + /** + * Handles modal focus. Modal focus needs to be checked at + * each logic iteration as it might be necessary to distribute + * mouse entered or mouse exited events. + * + * @since 0.8.0 + */ + virtual void handleModalFocus(); + + /** + * Handles modal mouse input focus. Modal mouse input focus needs + * to be checked at each logic iteration as it might be necessary to + * distribute mouse entered or mouse exited events. + * + * @since 0.8.0 + */ + virtual void handleModalMouseInputFocus(); + + /** + * Handles modal focus gained. If modal focus has been gained it might + * be necessary to distribute mouse entered or mouse exited events. + * + * @since 0.8.0 + */ + virtual void handleModalFocusGained(); + + /** + * Handles modal mouse input focus gained. If modal focus has been + * gained it might be necessary to distribute mouse entered or mouse + * exited events. + * + * @since 0.8.0 + */ + virtual void handleModalFocusReleased(); + + /** + * Distributes a mouse event. + * + * @param type The type of the event to distribute, + * @param button The button of the event (if any used) to distribute. + * @param x The x coordinate of the event. + * @param y The y coordinate of the event. + * @param fource indicates whether the distribution should be forced or not. + * A forced distribution distributes the event even if a widget + * is not enabled, not visible, another widget has modal + * focus or another widget has modal mouse input focus. + * Default value is false. + * @param toSourceOnly indicates whether the distribution should be to the + * source widget only or to it's parent's mouse listeners + * as well. + * + * @since 0.6.0 + */ + virtual void distributeMouseEvent(Widget* source, + int type, + int button, + int x, + int y, + bool force = false, + bool toSourceOnly = false); + + /** + * Distributes a key event. + * + * @param keyEvent The key event to distribute. + + * @since 0.6.0 + */ + virtual void distributeKeyEvent(KeyEvent& keyEvent); + + /** + * Distributes a key event to the global key listeners. + * + * @param keyEvent The key event to distribute. + * + * @since 0.6.0 + */ + virtual void distributeKeyEventToGlobalKeyListeners(KeyEvent& + keyEvent); + + /** + * Gets the widget at a certain position. + * + * @return The widget at a certain position. + * @since 0.6.0 + */ + virtual Widget* getWidgetAt(int x, int y); + + /** + * Gets the source of the mouse event. + * + * @return The source widget of the mouse event. + * @since 0.6.0 + */ + virtual Widget* getMouseEventSource(int x, int y); + + /** + * Gets the source of the key event. + * + * @return The source widget of the key event. + * @since 0.6.0 + */ + virtual Widget* getKeyEventSource(); + + /** + * Holds the top widget. + */ + Widget* mTop; + + /** + * Holds the graphics implementation used. + */ + Graphics* mGraphics; + + /** + * Holds the input implementation used. + */ + Input* mInput; + + /** + * Holds the focus handler for the Gui. + */ + FocusHandler* mFocusHandler; + + /** + * True if tabbing is enabled, false otherwise. + */ + bool mTabbing; + + /** + * Typedef. + */ + typedef std::list<KeyListener*> KeyListenerList; + + /** + * Typedef. + */ + typedef KeyListenerList::iterator KeyListenerListIterator; + + /** + * Holds the global key listeners of the Gui. + */ + KeyListenerList mKeyListeners; + + /** + * True if shift is pressed, false otherwise. + */ + bool mShiftPressed; + + /** + * True if meta is pressed, false otherwise. + */ + bool mMetaPressed; + + /** + * True if control is pressed, false otherwise. + */ + bool mControlPressed; + + /** + * True if alt is pressed, false otherwise. + */ + bool mAltPressed; + + /** + * Holds the last mouse button pressed. + */ + unsigned int mLastMousePressButton; + + /** + * Holds the last mouse press time stamp. + */ + int mLastMousePressTimeStamp; + + /** + * Holds the last mouse x coordinate. + */ + int mLastMouseX; + + /** + * Holds the last mouse y coordinate. + */ + int mLastMouseY; + + /** + * Holds the current click count. Used to keep track + * of clicks for a the last pressed button. + */ + int mClickCount; + + /** + * Holds the last button used when a drag of a widget + * was initiated. Used to be able to release a drag + * when the same button is released. + */ + int mLastMouseDragButton; + + /** + * Holds a stack with all the widgets with the mouse. + * Used to properly distribute mouse events. + */ + std::deque<Widget*> mWidgetWithMouseQueue; + }; +} + +#endif // end GCN_GUI_HPP + +/* yakslem - "Women, it's a constant struggle." + * finalman - "Yes, but sometimes they succeed with their guesses." + * yaklsem - "...eh...I was talking about love." + * finalman - "Oh...ok..." + * An awkward silence followed. + */ |