annotate lout/signal.hh @ 2048:5060d415a85a

clickable menu items (even those introducing submenus) MUST have callbacks I clicked on the "Panel size" item itself instead of any of the options in its submenu, and: Segfault!
author corvid <corvid@lavabit.com>
date Thu, 26 May 2011 02:51:18 +0000
parents e048ab285d1e
children
rev   line source
347
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
1 #ifndef __LOUT_SIGNALS_HH__
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
2 #define __LOUT_SIGNALS_HH__
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
3
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
4 #include "object.hh"
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
5 #include "container.hh"
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
6
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
7 /**
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
8 * \brief This namespace provides base classes to define signals.
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
9 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
10 * By using signals, objects may be connected at run-time, e.g. a general
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
11 * button widget may be connected to another application-specific object,
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
12 * which reacts on the operations on the button by the user. In this case,
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
13 * the button e.g. defines a signal "clicked", which is "emitted" each
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
14 * time the user clicks on the button. After the application-specific
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
15 * object has been connected to this signal, a specific method of it will
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
16 * be called each time, this button emits the "clicked" signal.
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
17 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
18 * Below, we will call the level, on which signals are defined, the
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
19 * "general level", and the level, on which the signals are connected,
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
20 * the "caller level".
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
21 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
22 * <h3>Defining Signals</h3>
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
23 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
24 * Typically, signals are grouped. To define a signal group \em bar for your
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
25 * class \em Foo, you have to define two classes, the emitter and the
1147
e048ab285d1e spelling
Jeremy Henty <onepoint@starurchin.org>
parents: 930
diff changeset
26 * receiver (BarEmitter and BarReceiver), and instantiate the emitter:
347
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
27 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
28 * \dot
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
29 * digraph G {
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
30 * node [shape=record, fontname=Helvetica, fontsize=10];
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
31 * edge [arrowhead="none", arrowtail="empty", labelfontname=Helvetica,
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
32 * labelfontsize=10, color="#404040", labelfontcolor="#000080"];
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
33 * fontname=Helvetica; fontsize=10;
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
34 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
35 * subgraph cluster_signal {
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
36 * style="dashed"; color="#000080"; fontname=Helvetica; fontsize=10;
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
37 * label="signal";
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
38 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
39 * Emitter [color="#a0a0a0", URL="\ref signal::Emitter"];
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
40 * Receiver [color="#a0a0a0", URL="\ref signal::Receiver"];
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
41 * }
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
42 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
43 * subgraph cluster_foo {
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
44 * style="dashed"; color="#000080"; fontname=Helvetica; fontsize=10;
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
45 * label="General (foo)";
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
46 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
47 * Foo;
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
48 * BarEmitter;
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
49 * BarReceiver [color="#a0a0a0"];
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
50 * }
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
51 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
52 * Emitter -> BarEmitter;
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
53 * Receiver -> BarReceiver;
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
54 * Foo -> BarEmitter [arrowhead="open", arrowtail="none",
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
55 * headlabel="1", taillabel="1"];
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
56 * }
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
57 * \enddot
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
58 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
59 * <center>[\ref uml-legend "legend"]</center>
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
60 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
61 * BarEmitter (class and instance) may be kept private, but BarReceiver must
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
62 * be public, since the caller of Foo must create a sub class of it. For
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
63 * BarEmitter, several methods must be implemented, see signal::Emitter for
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
64 * details. In BarReceiver, only some virtual abstract methods are defined,
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
65 * which the caller must implement. In this case, it is recommended to define
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
66 * a connectBar(BarReceiver*) method in Foo, which is delegated to the
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
67 * BarEmitter.
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
68 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
69 * <h3>Connecting to Signals</h3>
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
70 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
71 * A caller, which wants to connect to a signal, must define a sub class of
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
72 * the receiver, and implement the virtual methods. A typical design looks
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
73 * like this:
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
74 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
75 * \dot
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
76 * digraph G {
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
77 * node [shape=record, fontname=Helvetica, fontsize=10];
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
78 * edge [arrowhead="open", arrowtail="none", labelfontname=Helvetica,
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
79 * labelfontsize=10, color="#404040", labelfontcolor="#000080"];
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
80 * fontname=Helvetica; fontsize=10;
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
81 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
82 * subgraph cluster_foo {
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
83 * style="dashed"; color="#000080"; fontname=Helvetica; fontsize=10;
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
84 * label="Generall (foo)";
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
85 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
86 * BarReceiver [color="#a0a0a0"];
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
87 * }
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
88 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
89 * subgraph cluster_qix {
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
90 * style="dashed"; color="#000080"; fontname=Helvetica; fontsize=10;
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
91 * label="Caller (qix)";
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
92 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
93 * Qix;
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
94 * QixBarReceiver;
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
95 * }
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
96 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
97 * BarReceiver -> QixBarReceiver [arrowhead="none", arrowtail="empty"];
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
98 * QixBarReceiver -> Qix [headlabel="1", taillabel="*"];
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
99 * }
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
100 * \enddot
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
101 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
102 * <center>[\ref uml-legend "legend"]</center>
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
103 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
104 * (We skip "baz" in the canon, for better readability.)
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
105 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
106 * Here, the QixBarReceiver is connected to the Qix, so that the signals can
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
107 * be delegated to the Qix. Notice that the receiver gets automatically
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
108 * disconnected, when deleted (see signal::Receiver::~Receiver).
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
109 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
110 * <h3>Void and Boolean Signals</h3>
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
111 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
112 * In the simplest case, signal emitting involves calling a list of
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
113 * signal receivers (void signals). For boolean signals, the receivers return
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
114 * a boolean value, and the result of the signal emission (the return value of
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
115 * signal::Emitter::emitBool) returns the disjunction of the values returned
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
116 * by the receivers. Typically, a receiver states with its return value,
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
117 * whether the signal was used in any way, the resulting return value so
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
118 * indicates, whether at least one receiver has used the signal.
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
119 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
120 * In Dw, events are processed this way. In the simplest case, they are
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
121 * delegated to the parent widget, if the widget does not process them (by
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
122 * returning false). As an addition, signals are emitted, and if a receiver
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
123 * processes the event, this is handled the same way, as if the widget itself
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
124 * would have processed it.
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
125 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
126 * Notice, that also for boolean signals, all receivers are called, even
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
127 * after one receiver has already returned true.
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
128 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
129 * <h3>Memory Management</h3>
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
130 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
131 * <h4>Emitters</h4>
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
132 *
1147
e048ab285d1e spelling
Jeremy Henty <onepoint@starurchin.org>
parents: 930
diff changeset
133 * Emitters are typically instantiated one, for one object emitting the
347
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
134 * signals. In the example above, the class Foo will contain a field
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
135 * "BarEmitter barEmitter" (not as a pointer, "BarEmitter *barEmitter").
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
136 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
137 * <h4>Receivers</h4>
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
138 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
139 * It is important, that a emitter never deletes a receiver, it just removes
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
140 * them from the receivers list. Likewise, when a receiver is deleted, it
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
141 * unconnects itself from all emitters. (The same receiver instance can indeed
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
142 * be connected to multiple emitters.) So, the caller has to care about
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
143 * deleting receivers.
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
144 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
145 * In the example above, something like that will work:
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
146 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
147 * \code
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
148 * class Qix
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
149 * {
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
150 * private:
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
151 * class QixBarReceiver
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
152 * {
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
153 * public:
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
154 * Qix *qix;
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
155 * // ...
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
156 * };
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
157 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
158 * QixBarReceiver barReceiver;
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
159 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
160 * // ...
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
161 * };
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
162 * \endcode
930
b277eed3119c whitespace cleanup: 's/ +$//g'
Jorge Arellano Cid <jcid@dillo.org>
parents: 347
diff changeset
163 *
347
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
164 * The constructor of Qix should then set \em qix:
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
165 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
166 * \code
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
167 * Qix::Qix ()
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
168 * {
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
169 * barReceiver.qix = this.
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
170 * // ...
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
171 * }
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
172 * \endcode
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
173 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
174 * After this, &\em barReceiver can be connected to all instances of
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
175 * BarEmitter, also multiple times.
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
176 */
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
177 namespace lout {
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
178
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
179 namespace signal {
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
180
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
181 class Receiver;
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
182
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
183 /**
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
184 * \brief The base class for signal emitters.
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
185 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
186 * If defining a signal group, a sub class of this class must be defined,
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
187 * with
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
188 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
189 * <ul>
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
190 * <li> a definition of the different signals (as enumeration),
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
191 * <li> an implementation of signal::Emitter::emitToReceiver,
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
192 * <li> wrappers for signal::Emitter::emitVoid and signal::Emitter::emitBool,
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
193 * respectively (one for each signal), and
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
194 * <li> a wrapper for signal::Emitter::connect.
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
195 * </ul>
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
196 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
197 * There are two representations of signals:
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
198 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
199 * <ul>
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
200 * <li> In the \em unfolded representation, the signal itself is represented
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
201 * by the method itself (in the emitter or the receiver), and the
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
202 * arguments are represented as normal C++ types.
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
203 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
204 * <li> \em Folding signals means to represent the signal itself by an integer
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
205 * number (enumeration), and translate the arguments in an object::Object*
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
206 * array. (If a given argument is not an instance of object::Object*,
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
207 * the wrappers in ::object can be used.)
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
208 * </ul>
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
209 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
210 * \sa ::signal
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
211 */
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
212 class Emitter: public object::Object
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
213 {
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
214 friend class Receiver;
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
215
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
216 private:
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
217 container::typed::List <Receiver> *receivers;
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
218
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
219 void unconnect (Receiver *receiver);
930
b277eed3119c whitespace cleanup: 's/ +$//g'
Jorge Arellano Cid <jcid@dillo.org>
parents: 347
diff changeset
220
347
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
221 protected:
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
222 void emitVoid (int signalNo, int argc, Object **argv);
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
223 bool emitBool (int signalNo, int argc, Object **argv);
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
224 void connect(Receiver *receiver);
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
225
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
226 /**
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
227 * \brief A sub class must implement this for a call to a single
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
228 * receiver.
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
229 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
230 * This methods gets the signal in a \em folded representation, it has
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
231 * to unfold it, and pass it to a single receiver. For boolean signals,
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
232 * the return value of the receiver must be returned, for void signals,
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
233 * the return value is discarded.
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
234 */
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
235 virtual bool emitToReceiver (Receiver *receiver, int signalNo,
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
236 int argc, Object **argv) = 0;
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
237
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
238 public:
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
239 Emitter();
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
240 ~Emitter();
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
241
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
242 void intoStringBuffer(misc::StringBuffer *sb);
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
243 };
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
244
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
245 /**
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
246 * \brief The base class for signal receiver base classes.
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
247 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
248 * If defining a signal group, a sub class of this class must be defined,
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
249 * in which only the abstract signal methods must be defined.
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
250 *
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
251 * \sa ::signal
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
252 */
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
253 class Receiver: public object::Object
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
254 {
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
255 friend class Emitter;
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
256
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
257 private:
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
258 container::typed::List<Emitter> *emitters;
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
259
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
260 void connectTo(Emitter *emitter);
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
261 void unconnectFrom(Emitter *emitter);
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
262
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
263 public:
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
264 Receiver();
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
265 ~Receiver();
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
266
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
267 void intoStringBuffer(misc::StringBuffer *sb);
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
268 };
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
269
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
270 /**
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
271 * \brief An observed object has a signal emitter, which tells the
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
272 * receivers, when the object is deleted.
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
273 */
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
274 class ObservedObject
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
275 {
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
276 public:
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
277 class DeletionReceiver: public signal::Receiver
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
278 {
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
279 public:
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
280 virtual void deleted (ObservedObject *object) = 0;
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
281 };
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
282
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
283 private:
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
284 class DeletionEmitter: public signal::Emitter
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
285 {
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
286 protected:
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
287 bool emitToReceiver (signal::Receiver *receiver, int signalNo,
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
288 int argc, Object **argv);
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
289
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
290 public:
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
291 inline void connectDeletion (DeletionReceiver *receiver)
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
292 { connect (receiver); }
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
293
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
294 void emitDeletion (ObservedObject *obj);
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
295 };
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
296
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
297 DeletionEmitter deletionEmitter;
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
298
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
299 public:
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
300 virtual ~ObservedObject();
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
301
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
302 inline void connectDeletion (DeletionReceiver *receiver)
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
303 { deletionEmitter.connectDeletion (receiver); }
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
304 };
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
305
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
306 } // namespace signal
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
307
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
308 } // namespace lout
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
309
e5955ab8dafb - Moved the dw2 tree into dillo2's tree.
jcid
parents:
diff changeset
310 #endif // __LOUT_SIGNALS_HH__