/[adonthell]/adonthell/src/event/listener.h
ViewVC logotype

Diff of /adonthell/src/event/listener.h

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.7 by ksterker, Tue Mar 8 09:41:47 2005 UTC revision 1.8 by ksterker, Fri Jun 3 17:29:13 2005 UTC
# Line 1  Line 1 
1  /*  /*
2     $Id$     $Id$
3    
4     Copyright (C) 2004/2005 Kai Sterker <kaisterker@linuxgames.com>     Copyright (C) 2004/2005 Kai Sterker <kaisterker@linuxgames.com>
5     Part of the Adonthell Project http://adonthell.linuxgames.com     Part of the Adonthell Project http://adonthell.linuxgames.com
6    
7     Adonthell is free software; you can redistribute it and/or modify     Adonthell is free software; you can redistribute it and/or modify
8     it under the terms of the GNU General Public License as published by     it under the terms of the GNU General Public License as published by
9     the Free Software Foundation; either version 2 of the License, or     the Free Software Foundation; either version 2 of the License, or
10     (at your option) any later version.     (at your option) any later version.
11    
12     Adonthell is distributed in the hope that it will be useful,     Adonthell is distributed in the hope that it will be useful,
13     but WITHOUT ANY WARRANTY; without even the implied warranty of     but WITHOUT ANY WARRANTY; without even the implied warranty of
14     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
15     GNU General Public License for more details.     GNU General Public License for more details.
16    
17     You should have received a copy of the GNU General Public License     You should have received a copy of the GNU General Public License
18     along with Adonthell; if not, write to the Free Software     along with Adonthell; if not, write to the Free Software
19     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
20  */  */
21    
22  /**  /**
23   * @file   event/listener.h   * @file   event/listener.h
24   * @author Kai Sterker <kaisterker@linuxgames.com>   * @author Kai Sterker <kaisterker@linuxgames.com>
25   *   *
26   * @brief  Declares the %listener class.   * @brief  Declares the %listener class.
27   *   *
28   */   */
29    
30  #ifndef EVENT_LISTENER_H  #ifndef EVENT_LISTENER_H
31  #define EVENT_LISTENER_H  #define EVENT_LISTENER_H
32    
33  #include "python/method.h"  #include "python/method.h"
34  #include "event/event.h"  #include "event/event.h"
35    
36  namespace events  namespace events
37  {  {
38      class factory;      class factory;
39    
40      /**      /**
41       * An %event %listener contains a callback to a %python %method that it       * An %event %listener contains a callback to a %python %method that it
42       * will execute when the event occurs that the %listener is waiting       * will execute when the event occurs that the %listener is waiting
43       * for. A %listener is usually created by a certain %event %factory and will       * for. A %listener is usually created by a certain %event %factory and will
44       * be destroyed if the %factory is destroyed. That way, it's not neccessary       * be destroyed if the %factory is destroyed. That way, it's not neccessary
45       * to keep track of every single %listener. Instead, a few factories can       * to keep track of every single %listener. Instead, a few factories can
46       * be used to create groups of listeners that can be disposed together.       * be used to create groups of listeners that can be disposed together.
47       */       */
48      class listener      class listener
49      {      {
50      public:      public:
51          /**          /**
52           * Create a new listener, which listens to the given event.           * Create a new listener, which listens to the given event.
53           */           */
54          listener (factory *f, event *e);          listener (factory *f, event *e);
55                    
56          /**          /**
57           * Destroy the %listener. Automatically removes it from           * Destroy the %listener. Automatically removes it from
58           * the %event %manager and %factory if required.           * the %event %manager and %factory if required.
59           */           */
60          ~listener ();          ~listener ();
61                    
62          /**          /**
63           * @name Member access           * @name Member access
64           */           */
65          //@{          //@{
66          /**          /**
67           * Get type of associated %event.           * Get type of associated %event.
68           * @return type of associated %event           * @return type of associated %event
69           */           */
70          u_int8 type () const          u_int8 type () const
71          {          {
72              return Event->type ();              return Event->type ();
73          }          }
74                    
75          /**          /**
76           * Get the %event this 5listener waits for.           * Get the %event this 5listener waits for.
77           * @return %event attached to the %listener.           * @return %event attached to the %listener.
78           */           */
79          const event * get_event () const          const event * get_event () const
80          {          {
81              return Event;              return Event;
82          }          }
83                    
84          /**          /**
85           * Get the event's id.           * Get the event's id.
86           * @return id of the %event.           * @return id of the %event.
87           */           */
88          const string & id () const          const string & id () const
89          {          {
90              return Id;              return Id;
91          }          }
92                    
93          /**          /**
94           * Assign an id to the %event, so it may be retrieved from an           * Assign an id to the %event, so it may be retrieved from an
95           * event_list later on, without having a pointer to it.           * event_list later on, without having a pointer to it.
96           *           *
97           * @param id a string to identify the %event.           * @param id a string to identify the %event.
98           */           */
99          void set_id (const string & id)          void set_id (const string & id)
100          {          {
101              Id = id;              Id = id;
102          }          }
103    
104          /**          /**
105           * Deleting a %listener from Python side can cause problems.           * Deleting a %listener from Python side can cause problems.
106           * Instead, it should be marked as deletable with this method.           * Instead, it should be marked as deletable with this method.
107           * It will then be deleted on C++ side as soon as possible.           * It will then be deleted on C++ side as soon as possible.
108           */           */
109          void destroy ()          void destroy ()
110          {          {
111              Event->set_repeat (0);              Event->set_repeat (0);
112          }          }
113                    
114          /**          /**
115           * Check whether the %listener is marked for deletion.           * Check whether the %listener is marked for deletion.
116           */           */
117          bool is_destroyed () const          bool is_destroyed () const
118          {          {
119              return Event->repeat () == 0;              return Event->repeat () == 0;
120          }          }
121                    
122  // these are internal methods that shouldn't be exported by SWIG!  // these are internal methods that shouldn't be exported by SWIG!
123  #ifndef SWIG  #ifndef SWIG
124          /**          /**
125           * Return whether the %listener is registered with the %event %manager.           * Return whether the %listener is registered with the %event %manager.
126           * @return \c true if this is the case, \c false otherwise.           * @return \c true if this is the case, \c false otherwise.
127           */           */
128          bool is_registered () const          bool is_registered () const
129          {          {
130              return Registered;              return Registered;
131          }          }
132                    
133          /**          /**
134           * This method is called by the %event %manager when the %listerner           * This method is called by the %event %manager when the %listerner
135           * is added to or removed from it. If the %listener is still added           * is added to or removed from it. If the %listener is still added
136           * when it is being destroyed, it will be automatically removed from           * when it is being destroyed, it will be automatically removed from
137           * the %manager.           * the %manager.
138           *           *
139           * @param state pass \c true if %listener is being connected, \c false otherwise           * @param state pass \c true if %listener is being connected, \c false otherwise
140           */           */
141          void set_registered (bool state)          void set_registered (bool state)
142          {          {
143              Registered = state;              Registered = state;
144          }          }
145  #endif // SWIG  #endif // SWIG
146          //@}          //@}
147                    
148          /**          /**
149           * Sets a python method to be executed whenever an           * Sets a python method to be executed whenever an
150           * %event occurs that this listener listens to.           * %event occurs that this listener listens to.
151           *           *
152           * @param file Name of the script to load.           * @param file Name of the script to load.
153           * @param classname Name of the class containing the callback.           * @param classname Name of the class containing the callback.
154           * @param callback Name of the method to call.           * @param callback Name of the method to call.
155           * @param args Additional arguments to pass to the callback.           * @param args Additional arguments to pass to the callback.
156           * @return \b false if connecting the callback failed, \b true otherwise.           * @return \b false if connecting the callback failed, \b true otherwise.
157           */           */
158          bool connect_callback (const string & file, const string & classname,          bool connect_callback (const string & file, const string & classname,
159              const string & callback, PyObject *args = NULL);              const string & callback, PyObject *args = NULL);
160            
161          /**          /**
162           * Execute the associated python script or callback.           * Execute the associated python script or callback.
163           *           *
164           * @param evnt The %event that triggered the execution.           * @param evnt The %event that triggered the execution.
165           * @return The number of times the %event needs to be repeated.           * @return The number of times the %event needs to be repeated.
166           */           */
167          s_int32 raise_event (const event* evnt);          s_int32 raise_event (const event* evnt);
168    
169          /**          /**
170           * Check whether the given %event matches the %event attached to           * Check whether the given %event matches the %event attached to
171           * the %listener.           * the %listener.
172           * @param e %event to compare with the attached %event.           * @param e %event to compare with the attached %event.
173           * @return \b true if events compare equal, \b false otherwise.           * @return \b true if events compare equal, \b false otherwise.
174           */           */
175          bool equals (const event *e) const          bool equals (const event *e) const
176          {          {
177              return Event->equals (e);              return Event->equals (e);
178          }          }
179                    
180          /**          /**
181           * @name Pausing / Resuming execution           * @name Pausing / Resuming execution
182           */           */
183          //@{                  //@{        
184          /**          /**
185           * Disable the %event temporarily. As long as it in this state, the           * Disable the %event temporarily. As long as it in this state, the
186           * event will neither be executed, nor will its repeat-count change.           * event will neither be executed, nor will its repeat-count change.
187           * As long as the %event is paused, it will be removed from its           * As long as the %event is paused, it will be removed from its
188           * %event handler.           * %event handler.
189           */           */
190          void pause (const u_int16 & level = 1);          void pause (const u_int16 & level = 1);
191                    
192          /**          /**
193           * Re-enable an %event that has been paused. Re-registers it with           * Re-enable an %event that has been paused. Re-registers it with
194           * its %event handler.           * its %event handler.
195           */           */
196          void resume ();          void resume ();
197            
198          /**          /**
199           * Check whether the %event is temporarily disabled or not.           * Check whether the %event is temporarily disabled or not.
200           * @return \b true if it is paused, \b false otherwise.                               * @return \b true if it is paused, \b false otherwise.                    
201           */           */
202          bool is_paused () const          bool is_paused () const
203          {          {
204              return (Paused > 0);              return (Paused > 0);
205          }          }
206          //@}          //@}
207    
208          /**          /**
209           * @name Loading / Saving           * @name Loading / Saving
210           */           */
211          //@{          //@{
212          /**          /**
213           * Flattens the %event %listener to the given stream.           * Flattens the %event %listener to the given stream.
214           *           *
215           * @param out stream where to add the %event %listener.           * @param out stream where to add the %event %listener.
216           */           */
217          void put_state (base::flat& out) const;          void put_state (base::flat& out) const;
218                    
219          /**          /**
220           * Loads the %event %listener from given stream.           * Loads the %event %listener from given stream.
221           *           *
222           * @param in stream to load the %event %listener from.           * @param in stream to load the %event %listener from.
223           */           */
224          bool get_state (base::flat& in);          bool get_state (base::flat& in);
225          //@}          //@}
226    
227  #ifndef SWIG  #ifndef SWIG
228          /**          /**
229           * Allow %listener to be passed as python argument           * Allow %listener to be passed as python argument
230           */           */
231          GET_TYPE_NAME(events::listener)          GET_TYPE_NAME(events::listener)
232  #endif // SWIG  #endif // SWIG
233    
234      private:      private:
235          /**          /**
236           * (Optional) Id of the event           * (Optional) Id of the event
237           */           */
238          string Id;          string Id;
239                    
240          /**          /**
241           * Whether the %listener is registered with the %event %manager           * Whether the %listener is registered with the %event %manager
242           */           */
243          bool Registered;          bool Registered;
244                    
245          /**          /**
246           * Whether the %listener is temporarily disabled or not           * Whether the %listener is temporarily disabled or not
247           */           */
248          u_int16 Paused;          u_int16 Paused;
249                    
250          /**          /**
251           * The callback connected to this %listener           * The callback connected to this %listener
252           */           */
253          python::method *Method;          python::method *Method;
254                    
255          /**          /**
256           * Arguments to pass to the method           * Arguments to pass to the method
257           */           */
258          PyObject *Args;          PyObject *Args;
259                    
260          /**          /**
261           * The %event this %listener will react to.           * The %event this %listener will react to.
262           */           */
263          event *Event;          event *Event;
264                    
265          /**          /**
266           * The %event %factory that created this listener.           * The %event %factory that created this listener.
267           */           */
268          factory *Factory;          factory *Factory;
269      };      };
270  }  }
271    
272  #endif // EVENT_LISTENER_H  #endif // EVENT_LISTENER_H

Legend:
Removed from v.1.7  
changed lines
  Added in v.1.8

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26