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;
};
_______________________________________________
Wesnoth-commits mailing list
[email protected]
https://mail.gna.org/listinfo/wesnoth-commits
