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