Gamedev Framework (gf)  0.3.0
A C++11 framework for 2D games
Message.h
1 /*
2  * Gamedev Framework (gf)
3  * Copyright (C) 2016 Julien Bernard
4  *
5  * This software is provided 'as-is', without any express or implied
6  * warranty. In no event will the authors be held liable for any damages
7  * arising from the use of this software.
8  *
9  * Permission is granted to anyone to use this software for any purpose,
10  * including commercial applications, and to alter it and redistribute it
11  * freely, subject to the following restrictions:
12  *
13  * 1. The origin of this software must not be misrepresented; you must not
14  * claim that you wrote the original software. If you use this software
15  * in a product, an acknowledgment in the product documentation would be
16  * appreciated but is not required.
17  * 2. Altered source versions must be plainly marked as such, and must not be
18  * misrepresented as being the original software.
19  * 3. This notice may not be removed or altered from any source distribution.
20  */
21 #ifndef GF_MESSAGE_H
22 #define GF_MESSAGE_H
23 
24 #include <functional>
25 
26 #include "Id.h"
27 #include "Portability.h"
28 
29 namespace gf {
30 #ifndef DOXYGEN_SHOULD_SKIP_THIS
31 inline namespace v1 {
32 #endif
33 
34  /**
35  * @ingroup game
36  * @brief The base class for all messages
37  *
38  * gf::Message is the base class for all the messages that are sent to
39  * a message manager. A message must derive from this class and define a
40  * static unique type.
41  *
42  * Here is an example for defining a new message type:
43  *
44  * ~~~{.cc}
45  * struct HeroPosition : public gf::Message {
46  * static const Id type = "HeroPosition"_id; // compile-time definition
47  * gf::Vector2f position;
48  * };
49  * ~~~
50  *
51  * @sa gf::MessageManager, gf::MessageHandler
52  */
53  struct GF_API Message {
54  /**
55  * @brief The default (invalid) type
56  *
57  * It must be redefined in child classes.
58  */
59  static const Id type = InvalidId;
60  };
61 
62  /**
63  * @ingroup game
64  * @brief A message status
65  *
66  * gf::MessageStatus indicates if a handler should be kept by the message
67  * manager or can be removed so that it will not receive any more messages.
68  *
69  * @sa gf::MessageManager, gf::MessageHandler
70  */
71  enum class MessageStatus {
72  Keep, /**< The handler must be kept */
73  Die, /**< The handler can be removed */
74  };
75 
76  /**
77  * @ingroup game
78  * @brief A message handler
79  *
80  * gf::MessageHandler is a function that can be called when a message is
81  * sent in a message handler. It can be a free function:
82  *
83  * ~~~{.cc}
84  * gf::MessageStatus onHeroPosition(gf::Id type, gf::Message *msg) {
85  * assert(type == HeroPosition::type);
86  * auto heroPosition = static_cast<HeroPosition*>(msg);
87  *
88  * // do something with heroPosition->position ...
89  *
90  * return gf::MessageStatus::Keep;
91  * }
92  *
93  * // ...
94  *
95  * gf::MessageHandler handler = onHeroPosition;
96  * ~~~
97  *
98  * It can also be a member function (which is, in fact, the most probable
99  * use case).
100  *
101  * ~~~{.cc}
102  * struct Foo {
103  * gf::MessageStatus onHeroPosition(gf::Id type, gf::Message *msg) {
104  * assert(type == HeroPosition::type);
105  * auto heroPosition = static_cast<HeroPosition*>(msg);
106  *
107  * // do something with heroPosition->position ...
108  *
109  * return gf::MessageStatus::Keep;
110  * }
111  * };
112  *
113  * // ...
114  *
115  * Foo foo;
116  * gf::MessageHandler handler = std::bind(&Foo::onHeroPosition, &foo);
117  * ~~~
118  *
119  * @sa gf::MessageManager, gf::Message, gf::Id
120  */
121  using MessageHandler = std::function<MessageStatus(Id, Message *)>;
122 
123 #ifndef DOXYGEN_SHOULD_SKIP_THIS
124 }
125 #endif
126 }
127 
128 #endif // GF_MESSAGE_H
static const Id type
The default (invalid) type.
Definition: Message.h:59
Definition: Action.h:34
MessageStatus
A message status.
Definition: Message.h:71
The base class for all messages.
Definition: Message.h:53
constexpr Id InvalidId
The invalid id (which is 0)
Definition: Id.h:44
#define GF_API
Definition: Portability.h:35