The Battle for Wesnoth  1.15.1+dev
timer.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2009 - 2018 by Mark de Wever <koraq@xs4all.nl>
3  Part of the Battle for Wesnoth Project https://www.wesnoth.org/
4 
5  This program is free software; you can redistribute it and/or modify
6  it under the terms of the GNU General Public License as published by
7  the Free Software Foundation; either version 2 of the License, or
8  (at your option) any later version.
9  This program is distributed in the hope that it will be useful,
10  but WITHOUT ANY WARRANTY.
11 
12  See the COPYING file for more details.
13 */
14 
15 /**
16  * @file
17  * Contains the gui2 timer routines.
18  *
19  * This code avoids the following problems with the sdl timers:
20  * - the callback must be a C function with a fixed signature.
21  * - the callback needs to push an event in the event queue, between the
22  * pushing and execution of that event the timer can't be stopped. (Makes
23  * sense since the timer has expired, but not what the user wants.)
24  *
25  * With these functions it's possible to remove the event between pushing in
26  * the queue and the actual execution. Since the callback is a std::function
27  * object it's possible to make the callback as fancy as wanted.
28  */
29 
30 #pragma once
31 
32 #include "utils/functional.hpp"
33 
34 #include <SDL2/SDL_types.h>
35 
36 namespace gui2
37 {
38 
39 /**
40  * Adds a new timer.
41  *
42  * @param interval The timer interval in ms.
43  * @param callback The function to call when the timer expires,
44  * the id send as parameter is the id of the
45  * timer.
46  * @param repeat If true the timer will restart after it
47  * expires.
48  *
49  * @returns The id of the timer.
50  * @retval [0] Failed to create a timer.
51  */
52 std::size_t add_timer(const uint32_t interval,
53  const std::function<void(std::size_t id)>& callback,
54  const bool repeat = false);
55 
56 /**
57  * Removes a timer.
58  *
59  * It's save to remove a timer in its own callback, only the value returned
60  * might not be accurate. The destruction is postponed until the execution is
61  * finished and the return value is whether the postponing was successful.
62  *
63  * @param id The id of the timer to remove, this is the id
64  * returned by add_timer.
65  *
66  * @returns Status, false if the timer couldn't be
67  * removed.
68  */
69 bool remove_timer(const std::size_t id);
70 
71 /**
72  * Executes a timer.
73  *
74  * @note this function is only meant to be executed by the event handling
75  * system.
76  *
77  * @param id The id of the timer to execute, this is the
78  * id returned by add_timer.
79  *
80  * @returns Status, false if the timer couldn't be
81  * executed.
82  */
83 bool execute_timer(const std::size_t id);
84 
85 } // namespace gui2
Generic file dialog.
Definition: field-fwd.hpp:22
std::size_t add_timer(const uint32_t interval, const std::function< void(std::size_t id)> &callback, const bool repeat)
Adds a new timer.
Definition: timer.cpp:126
bool execute_timer(const std::size_t id)
Executes a timer.
Definition: timer.cpp:200
bool remove_timer(const std::size_t id)
Removes a timer.
Definition: timer.cpp:167