Zen API

- Home
- Help Topics
- Types by Category
- All Types
- Files

All Classes Files Functions Variables Typedefs Macros Groups Pages
kEvent.h
Go to the documentation of this file.
1 /**
2 * @file kEvent.h
3 * @brief Declares the kEvent type.
4 *
5 * @internal
6 * Copyright (C) 2012-2014 by LMI Technologies Inc.
7 * Licensed under the MIT License.
8 * Redistributed files must retain the above copyright notice.
9 */
10 #ifndef K_API_EVENT_H
11 #define K_API_EVENT_H
12
13 #include <kApi/kApiDef.h>
14
15 kBeginHeader()
16
17 /**
18 * @class kEvent
19 * @extends kObject
20 * @ingroup kApi-Utils
21 * @brief Represents a list of callbacks.
22 */
23 //typedef kObject kEvent; --forward-declared in kApiDef.x.h
24
25 /**
26 * Constructs a kEvent object.
27 *
28 * @public @memberof kEvent
29 * @param evnt Event object.
30 * @param allocator Memory allocator (or kNULL for default).
31 * @return Operation status.
32 */
33 kFx(kStatus) kEvent_Construct(kEvent* evnt, kAlloc allocator);
34
35 /**
36 * Adds a listener to the event.
37 *
38 * @public @memberof kEvent
39 * @param evnt Event object.
40 * @param function Listener callback function.
41 * @param receiver Listener callback context.
42 * @return Operation status.
43 */
44 kFx(kStatus) kEvent_Add(kEvent evnt, kCallbackFx function, kPointer receiver);
45
46 /**
47 * Removes a listener from the event.
48 *
49 * @public @memberof kEvent
50 * @param evnt Event object.
51 * @param function Listener callback function.
52 * @param receiver Listener callback context.
53 * @return Operation status.
54 */
55 kFx(kStatus) kEvent_Remove(kEvent evnt, kCallbackFx function, kPointer receiver);
56
57 /**
58 * Removes all listeners from the event.
59 *
60 * @public @memberof kEvent
61 * @param evnt Event object.
62 * @return Operation status.
63 */
64 kFx(kStatus) kEvent_Clear(kEvent evnt);
65
66 /**
67 * Notifies all event listeners.
68 *
69 * @public @memberof kEvent
70 * @param evnt Event object.
71 * @param sender Sender of event notification.
72 * @param args Arguments for event notification.
73 * @return Operation status.
74 */
75 kFx(kStatus) kEvent_Notify(kEvent evnt, kPointer sender, void* args);
76
77 /**
78 * Count of event listeners.
79 *
80 * @public @memberof kEvent
81 * @param evnt Event object.
82 * @return Listener count.
83 */
84 kFx(kSize) kEvent_Count(kEvent evnt);
85
86 /**
87 * Gets the internal list of event listeners.
88 *
89 * This function is provided to support optimizations, and should not normally be used. The list returned
90 * by this function should be treated as read-only.
91 *
92 * @public @memberof kEvent
93 * @param evnt Event object.
94 * @return Listener list -- kList<kCallback>.
95 */
96 kFx(kList) kEvent_Listeners(kEvent evnt);
97
98 #define kEvent_Listeners_(EV) kxEvent_Listeners_(EV) ///< Macro version of kEvent_Listeners.
99
100 kEndHeader()
101
102 #include <kApi/Utils/kEvent.x.h>
103
104 #endif
kEvent::kEvent_Add
kStatus kEvent_Add(kEvent evnt, kCallbackFx function, kPointer receiver)
Adds a listener to the event.
kEvent::kEvent_Construct
kStatus kEvent_Construct(kEvent *evnt, kAlloc allocator)
Constructs a kEvent object.
kCallbackFx
kStatus(kCall * kCallbackFx)(kPointer receiver, kPointer sender, void *args)
Callback signature for a generic event handler.
Definition: kApiDef.h:1030
kPointer
Represents a void pointer.
kSize
Represents an unsigned integer that can store a pointer address.
kAlloc
Abstract base class for memory allocator types.
kEvent
Represents a list of callbacks.
kEvent::kEvent_Count
kSize kEvent_Count(kEvent evnt)
Count of event listeners.
kApiDef.h
Essential API declarations.
kEvent::kEvent_Listeners
kList kEvent_Listeners(kEvent evnt)
Gets the internal list of event listeners.
kEvent::kEvent_Notify
kStatus kEvent_Notify(kEvent evnt, kPointer sender, void *args)
Notifies all event listeners.
kList
Represents a doubly-linked list.
kEvent::kEvent_Remove
kStatus kEvent_Remove(kEvent evnt, kCallbackFx function, kPointer receiver)
Removes a listener from the event.
kStatus
Represents an enumeration of error codes.
kEvent::kEvent_Clear
kStatus kEvent_Clear(kEvent evnt)
Removes all listeners from the event.