mail[Wesnoth-commits] r28658 - in /trunk/src/gui/widgets: event_handler.cpp event_handler.hpp


Others Months | Index by Date | Thread Index
>>   [Date Prev] [Date Next] [Thread Prev] [Thread Next]

Header


Content

Posted by koraq on August 16, 2008 - 23:07:
Author: mordante
Date: Sat Aug 16 23:07:13 2008
New Revision: 28658

URL: http://svn.gna.org/viewcvs/wesnoth?rev=28658&view=rev
Log:
Code and comment cleanup.

Modified:
    trunk/src/gui/widgets/event_handler.cpp
    trunk/src/gui/widgets/event_handler.hpp

Modified: trunk/src/gui/widgets/event_handler.cpp
URL: 
http://svn.gna.org/viewcvs/wesnoth/trunk/src/gui/widgets/event_handler.cpp?rev=28658&r1=28657&r2=28658&view=diff
==============================================================================
--- trunk/src/gui/widgets/event_handler.cpp (original)
+++ trunk/src/gui/widgets/event_handler.cpp Sat Aug 16 23:07:13 2008
@@ -12,10 +12,12 @@
    See the COPYING file for more details.
 */
 
-//! @file event_handler.cpp
-//! Implementation of event_handler.hpp.
-//!
-//! More documentation at the end of the file.
+/**
+ * @file event_handler.cpp
+ * Implementation of event_handler.hpp.
+ *
+ * More documentation at the end of the file.
+ */
 
 #include "gui/widgets/event_handler.hpp"
 
@@ -35,6 +37,16 @@
 
 namespace gui2{
 
+/**
+ * SDL_AddTimer() callback for the hover event.
+ *
+ * When this callback is called it pushes a new hover event in the event 
queue.
+ *
+ * @param interval                The time parameter of SDL_AddTimer.
+ * @param param                   Pointer to parameter structure.
+ *
+ * @returns                       The new timer interval, 0 to stop.
+ */
 static Uint32 hover_callback(Uint32 /*interval*/, void *param)
 {
        DBG_G_E << "Pushing hover event in queue.\n";
@@ -54,7 +66,17 @@
        return 0;
 }
 
-static Uint32 popup_callback(Uint32 /*interval*/, void*)
+/**
+ * SDL_AddTimer() callback for the popup event.
+ *
+ * This event makes sure the popup is removed again.
+ *
+ * @param interval                The time parameter of SDL_AddTimer.
+ * @param param                   Pointer to parameter structure.
+ *
+ * @returns                       The new timer interval, 0 to stop.
+ */
+static Uint32 popup_callback(Uint32 /*interval*/, void* /*param*/)
 {
        DBG_G_E << "Pushing popup removal event in queue.\n";
 
@@ -73,11 +95,12 @@
        return 0;
 }
 
-//! At construction we should get the state and from that moment on we keep
-//! track of the changes ourselves, not yet sure what happens when an input
-//! blocker is used.
+/**
+ * @todo At construction we should get the state and from that moment on we
+ * keep track of the changes ourselves, not yet sure what happens when an 
input
+ * blocker is used.
+ */
 tevent_handler::tevent_handler() :
-       // fixme get state at construction
        events::handler(false), // don't join we haven't created a context yet
        event_context_(),
        mouse_x_(-1),
@@ -130,8 +153,8 @@
 
                        mouse_x_ = event.motion.x;
                        mouse_y_ = event.motion.y;
-                       mouse_over =
-                               
find_widget(get_window().client_position(tpoint(mouse_x_, mouse_y_)), true);
+                       mouse_over = find_widget(get_window().
+                               client_position(tpoint(mouse_x_, mouse_y_)), 
true);
 
                        mouse_move(event, mouse_over);
 
@@ -141,8 +164,8 @@
 
                        mouse_x_ = event.button.x;
                        mouse_y_ = event.button.y;
-                       mouse_over =
-                               
find_widget(get_window().client_position(tpoint(mouse_x_, mouse_y_)), true);
+                       mouse_over = find_widget(get_window().
+                               client_position(tpoint(mouse_x_, mouse_y_)), 
true);
 
                        switch(event.button.button) {
                                case SDL_BUTTON_LEFT : 
@@ -171,8 +194,8 @@
 
                        mouse_x_ = event.button.x;
                        mouse_y_ = event.button.y;
-                       mouse_over =
-                               
find_widget(get_window().client_position(tpoint(mouse_x_, mouse_y_)), true);
+                       mouse_over = find_widget(get_window().
+                               client_position(tpoint(mouse_x_, mouse_y_)), 
true);
 
                        switch(event.button.button) {
 
@@ -245,6 +268,7 @@
 
 void tevent_handler::add_to_keyboard_chain(twidget* widget) 
 { 
+       assert(widget);
        assert(
                std::find(keyboard_focus_chain_.begin(), 
keyboard_focus_chain_.end(), widget) 
                == keyboard_focus_chain_.end());
@@ -254,6 +278,7 @@
 
 void tevent_handler::remove_from_keyboard_chain(twidget* widget)
 {
+       assert(widget);
        std::vector<twidget*>::iterator itor = std::find(
                keyboard_focus_chain_.begin(), keyboard_focus_chain_.end(), 
widget);
 
@@ -262,7 +287,7 @@
        }               
 }
 
-void tevent_handler::show_tooltip(const t_string& tooltip, const unsigned 
timeout)
+void tevent_handler::show_tooltip(const t_string& message, const unsigned 
timeout)
 {
        DBG_G_E << "Event: show tooltip.\n";
 
@@ -274,7 +299,8 @@
 
        tooltip_ = mouse_focus_;
 
-       do_show_tooltip(get_window().client_position(tpoint(mouse_x_, 
mouse_y_)), tooltip);
+       do_show_tooltip(
+               get_window().client_position(tpoint(mouse_x_, mouse_y_)), 
message);
 
        if(timeout) {
                SDL_AddTimer(timeout, popup_callback, 0);
@@ -292,7 +318,7 @@
        do_remove_tooltip();
 }
 
-void tevent_handler::show_help_popup(const t_string& help_popup, const 
unsigned timeout)
+void tevent_handler::show_help_popup(const t_string& message, const unsigned 
timeout)
 {
        DBG_G_E << "Event: show help popup.\n";
 
@@ -311,7 +337,8 @@
 
        help_popup_ = mouse_focus_;
 
-       do_show_help_popup(get_window().client_position(tpoint(mouse_x_, 
mouse_y_)), help_popup);
+       do_show_help_popup(
+               get_window().client_position(tpoint(mouse_x_, mouse_y_)), 
message);
 
        if(timeout) {
                SDL_AddTimer(timeout, popup_callback, 0);
@@ -339,22 +366,6 @@
        mouse_over->mouse_enter(*this);
 
        set_hover();
-}
-
-void tevent_handler::mouse_hover(const SDL_Event& event, twidget* 
/*mouse_over*/)
-{
-       const unsigned hover_id = *static_cast<unsigned*>(event.user.data1);
-       delete static_cast<unsigned*>(event.user.data1);
-
-       if(!hover_pending_ || hover_id != hover_id_) {
-               return;
-       }
-       
-       assert(mouse_focus_);
-
-       mouse_focus_->mouse_hover(*this);
-
-       had_hover_ = true;
 }
 
 void tevent_handler::mouse_move(const SDL_Event& event, twidget* mouse_over)
@@ -382,7 +393,25 @@
        }
 }
 
-void tevent_handler::mouse_leave(const SDL_Event& /*event*/, twidget* 
/*mouse_over*/)
+void tevent_handler::mouse_hover(
+               const SDL_Event& event, twidget* /*mouse_over*/)
+{
+       const unsigned hover_id = *static_cast<unsigned*>(event.user.data1);
+       delete static_cast<unsigned*>(event.user.data1);
+
+       if(!hover_pending_ || hover_id != hover_id_) {
+               return;
+       }
+       
+       assert(mouse_focus_);
+
+       mouse_focus_->mouse_hover(*this);
+
+       had_hover_ = true;
+}
+
+void tevent_handler::mouse_leave(
+               const SDL_Event& /*event*/, twidget* /*mouse_over*/)
 {
        assert(mouse_focus_);
 
@@ -396,7 +425,8 @@
        mouse_focus_ = 0;
 }
 
-void tevent_handler::mouse_button_down(const SDL_Event& /*event*/, twidget* 
mouse_over, tmouse_button& button)
+void tevent_handler::mouse_button_down(
+               const SDL_Event& /*event*/, twidget* mouse_over, 
tmouse_button& button)
 {
        if(button.is_down) {
                WRN_G_E << "In 'button down' for button '" << button.name 
@@ -424,7 +454,8 @@
        }
 }
 
-void tevent_handler::mouse_button_up(const SDL_Event& event, twidget* 
mouse_over, tmouse_button& button)
+void tevent_handler::mouse_button_up(
+       const SDL_Event& event, twidget* mouse_over, tmouse_button& button)
 {
        if(!button.is_down) {
                WRN_G_E << "In 'button up' for button '" << button.name 

Modified: trunk/src/gui/widgets/event_handler.hpp
URL: 
http://svn.gna.org/viewcvs/wesnoth/trunk/src/gui/widgets/event_handler.hpp?rev=28658&r1=28657&r2=28658&view=diff
==============================================================================
--- trunk/src/gui/widgets/event_handler.hpp (original)
+++ trunk/src/gui/widgets/event_handler.hpp Sat Aug 16 23:07:13 2008
@@ -12,8 +12,10 @@
    See the COPYING file for more details.
 */
 
-//! @file event_handler.hpp
-//! Contains the information with an event.
+/**
+ * @file event_handler.hpp
+ * Contains the information with an event.
+ */
 
 #ifndef GUI_WIDGETS_EVENT_INFO_HPP_INCLUDED
 #define GUI_WIDGETS_EVENT_INFO_HPP_INCLUDED
@@ -30,19 +32,24 @@
 
 class twindow;
 
+/** The event handler class for the widget library. */
 class tevent_handler : public events::handler
 {
 public:
        tevent_handler();
 
-       virtual ~tevent_handler() { leave(); }
-
+       ~tevent_handler() { leave(); }
+
+       /** Inherited from events::handler. */
        void process_events() { events::pump(); }
 
-       //! Implement events::handler::handle_event().
+       /** Inherited from events::handler. */
        void handle_event(const SDL_Event& event);
 
+       /** Returns the main window. */
        virtual twindow& get_window() = 0;
+
+       /** Returns the main window. */
        virtual const twindow& get_window() const = 0;
 
        /** See twidget::find_widget() for the description. */
@@ -53,26 +60,82 @@
        virtual const twidget* find_widget(const tpoint& coordinate, 
                const bool must_be_active) const = 0;
 
+       /** 
+        * Captures the mouse input.
+        *
+        * When capturing the widget that has the mouse focus does the 
capturing.
+        *
+        * @param capture             Set or release the capturing.
+        */
        void mouse_capture(const bool capture = true);
+
+       /**
+        * Captures the keyboard input.
+        *
+        * @param widget              The widget which should capture the 
keyboard.
+        *                            Sending NULL releases the capturing.
+        */
        void keyboard_capture(twidget* widget) { keyboard_focus_ = widget; }
 
-       /** Adds the widget to the chain, widgets may only be added once. */
+       /** 
+        * Adds the widget to the keyboard chain.
+        *
+        * @param widget              The widget to add to the chain. The 
widget
+        *                            should be valid widget, which hasn't 
been
+        *                            added to the chain yet.
+        */
        void add_to_keyboard_chain(twidget* widget);
 
-       /** Remove the widget (if in the vector) from the chain. */
+       /** 
+        * Remove the widget from the keyborad chain.
+        *
+        * @parameter widget          The widget to be removed from the chain.
+        */
        void remove_from_keyboard_chain(twidget* widget);
 
+       /** Return the current mouse position. */
        tpoint get_mouse() const;
 
-       //! We impement the handling of the tip, but call the do functions
-       //! which are virtual.
-       void show_tooltip(const t_string& tooltip, const unsigned timeout);
+       /**
+        * Shows a tooltip.
+        *
+        * A tooltip is a small shortly visible item which is meant to show 
the user
+        * extra information. It shows after a short time hovering over a 
widget and
+        * automatically disappears again after a while. Only one tooltip or 
help
+        * message can be active at a time.
+        *
+        * @param message             The message to show.
+        * @param timeout             The time the tooltip is shown, 0 means
+        *                            forever.
+        */
+       void show_tooltip(const t_string& message, const unsigned timeout);
+
+       /** Removes the currently shown tooltip. */
        void remove_tooltip();
-       void show_help_popup(const t_string& help_popup, const unsigned 
timeout);
+
+       /**
+        * Shows a help message.
+        *
+        * A help message is like a tooltip, but in general contains more 
info and
+        * the user needs to trigger it (most of the time with the F1 button).
+        *
+        * @param message             The message to show.
+        * @param timeout             The time the help message is shown, 0 
means
+        *                            forever.
+        */
+       void show_help_popup(const t_string& message, const unsigned timeout);
+
+       /** Removes the currently show tooltip. */
        void remove_help_popup();
 
 private:
 
+       /** 
+        * A mouse button.
+        *
+        * The class tracks the state of the mouse button and which functions 
to
+        * invoke upon state changes.
+        * */
        struct tmouse_button {
                
                tmouse_button(const std::string& name, 
@@ -92,53 +155,68 @@
                                is_down(false)
                        {}
 
-               //! The time of the last click used for double clicking.
+               /** The time of the last click used for double clicking. */
                Uint32 last_click_stamp;
 
-               //! If the mouse isn't captured we need to verify the up
-               //! is on the same widget as the down so we send a proper
-               //! click, also needed to send the up to the right widget.
+               /**
+                * If the mouse isn't captured we need to verify the up is on 
the same
+                * widget as the down so we send a proper click, also needed 
to send the
+                * up to the right widget.
+                */
                twidget* focus;
 
-               //! used for debug messages.
+               /** used for debug messages. */
                const std::string name;
 
-               //! Pointers to member functions, this way we can call the 
proper
-               //! function indirect without writing a case for which button 
to
-               //! use.
+               /**
+                * Pointers to member functions, this way we can call the 
proper
+                * function indirect without writing a case for which button 
to
+                * use.
+                */
                void (tevent_executor::*down) (tevent_handler&);
                void (tevent_executor::*up) (tevent_handler&);
                void (tevent_executor::*click) (tevent_handler&);
                void (tevent_executor::*double_click) (tevent_handler&);
                bool (tevent_executor::*wants_double_click) () const;
 
-               //! Is the button down?
+               /** Is the button down? */
                bool is_down;
        };
 
-       //! we create a new event context so we're always modal.
-       //! Maybe this has to change, but not sure yet.
+       /**
+        * We create a new event context so we're always modal. Maybe this 
has to
+        * change, but not sure yet.
+        */
        events::event_context event_context_;
 
-       int mouse_x_;                      //! The current mouse x.
-       int mouse_y_;                      //! The current mouse y.
-
-       tmouse_button left_;
-       tmouse_button middle_;
-       tmouse_button right_;
-
-       bool hover_pending_;                       //! Is there a hover event 
pending?
-       unsigned hover_id_;                //! Id of the pending hover event.
-       SDL_Rect hover_box_;               //! The area the mouse can move 
in, moving outside
-                                          //! invalidates the pending hover 
event.
-    bool had_hover_;                   //! A widget only gets one hover 
event per enter cycle. 
-
-       //! The widget that created the tooltip / tooltip.
+       int mouse_x_;                      /**< The current mouse x. */
+       int mouse_y_;                      /**< The current mouse y. */
+
+       tmouse_button left_;               /**< The left mouse button. */
+       tmouse_button middle_;             /**< The middle mouse button. */
+       tmouse_button right_;              /**< The right mouse button. */
+
+       bool hover_pending_;                       /**< Is there a hover 
event pending? */
+       unsigned hover_id_;                /**< Id of the pending hover 
event. */
+       SDL_Rect hover_box_;               /**< The area the mouse can move 
in,
+                                                                             
  *   moving outside invalidates the
+                                                                             
  *   pending hover event.
+                                                                             
  */
+                                                                          
+       bool had_hover_;                   /**< A widget only gets one hover 
event
+                                           *   per enter cycle.
+                                                                             
  */
+
+       /** The widget of the currently active tooltip. */
        twidget* tooltip_;
+
+       /** The widget of the currently active help popup. */
        twidget* help_popup_;
 
-
+    /** The widget that currently has the moue focus. */
        twidget* mouse_focus_;
+
+       /** Did the current widget capture the focus? */
        bool mouse_captured_;
 
        /** The widget that holds the keyboard focus. */
@@ -156,23 +234,116 @@
         */
        std::vector<twidget*> keyboard_focus_chain_;
 
+       /**
+        * Set of functions that handle certain events and sends them to the 
proper
+        * widget. These functions are called by the SDL event handling 
functions.
+        */
+
+       /**
+        * Called when the mouse enters a widget.
+        *
+        * @param event               The SDL_Event which was triggered.
+        * @param mouse_over          The widget that should receive the 
event.
+        */
        void mouse_enter(const SDL_Event& event, twidget* mouse_over);
+
+       /**
+        * Called when the mouse moves over a widget.
+        *
+        * @param event               The SDL_Event which was triggered.
+        * @param mouse_over          The widget that should receive the 
event.
+        */
        void mouse_move(const SDL_Event& event, twidget* mouse_over);
+
+       /**
+        * Called when a widget should raises a hover event.
+        *
+        * @param event               The SDL_Event which was triggered.
+        * @param mouse_over          The widget that should receive the 
event.
+        */
        void mouse_hover(const SDL_Event& event, twidget* mouse_over);
+
+       /**
+        * Called when the mouse leaves a widget.
+        *
+        * @param event               The SDL_Event which was triggered.
+        * @param mouse_over          The widget that should receive the 
event.
+        */
        void mouse_leave(const SDL_Event& event, twidget* mouse_over);
 
-
-       void mouse_button_down(const SDL_Event& event, twidget* mouse_over, 
tmouse_button& button);
-       void mouse_button_up(const SDL_Event& event, twidget* mouse_over, 
tmouse_button& button);
+       /**
+        * Called when a mouse button is pressed on a widget.
+        *
+        * @param event               The SDL_Event which was triggered.
+        * @param mouse_over          The widget that should receive the 
event. This
+        *                            widget can be NULL and capturing the 
mouse
+        *                            can send the event to another widget.
+        * @param button              The button which was used to generate 
the event.
+        */
+       void mouse_button_down(
+               const SDL_Event& event, twidget* mouse_over, tmouse_button& 
button);
+
+       /**
+        * Called when a mouse button is released.
+        *
+        * @param event               The SDL_Event which was triggered.
+        * @param mouse_over          The widget that should receive the 
event. This
+        *                            widget can be NULL and capturing the 
mouse
+        *                            can send the event to another widget.
+        * @param button              The button which was used to generate 
the event.
+        */
+       void mouse_button_up(
+               const SDL_Event& event, twidget* mouse_over, tmouse_button& 
button);
+
+       /**
+        * Called when a mouse click is generated.
+        *
+        * Note if the widget wants a double click a double click might be 
send or
+        * the click might be delayed to wait for a double click.
+        *
+        * @param widget              The widget that should receive the 
event.
+        * @param button              The button which was used to generate 
the event.
+        */
        void mouse_click(twidget* widget, tmouse_button& button);
 
+       /**
+        * Raises a hover request.
+        *
+        * @param test_on_widget      Do we need to test whether we're on a 
widget.
+        */
        void set_hover(const bool test_on_widget = false);
 
+       /**
+        * A key has been pressed.
+        *
+        * @param event               The SDL_Event which was triggered.
+        */
        void key_down(const SDL_Event& event);
 
-       virtual void do_show_tooltip(const tpoint& location, const t_string& 
tooltip) = 0;
+       /** 
+        * The function to do the real job of showing the tooltip.
+        *
+        * @param location            The location in the window where to 
show the
+        *                            tooltip.
+        * @param tooltip             The message to show.
+        */
+       virtual void do_show_tooltip(
+               const tpoint& location, const t_string& tooltip) = 0;
+
+       /** Function to do the real removal of the tooltip. */
        virtual void do_remove_tooltip() = 0;
-       virtual void do_show_help_popup(const tpoint& location, const 
t_string& help_popup) = 0;
+
+       /** 
+        * The function to do the real job of showing the help popup.
+        *
+        * @param location            The location in the window where to 
show the
+        *                            help popup.
+        * @param help_popup          The message to show.
+        */
+       virtual void do_show_help_popup(
+               const tpoint& location, const t_string& help_popup) = 0;
+
+       /** Function to do the real removal of the help popup. */
        virtual void do_remove_help_popup() = 0;
 };
 




Related Messages


Powered by MHonArc, Updated Sat Aug 16 23:21:25 2008