Logo Search packages:      
Sourcecode: adonthell version File versions  Download package

event.h

Go to the documentation of this file.
/*
   $Id: event.h,v 1.34 2003/02/23 23:14:34 ksterker Exp $

   Copyright (C) 2000/2001/2002/2003 Kai Sterker <kaisterker@linuxgames.com>
   Part of the Adonthell Project http://adonthell.linuxgames.com

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License.
   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY.

   See the COPYING file for more details.
*/

/**
 * @file   event.h
 * @author Kai Sterker <kaisterker@linuxgames.com>
 * 
 * @brief  Declares the %event class.
 * 
 */

#ifndef EVENT_H__
#define EVENT_H__

#include "callback.h"
#include "py_object.h"
#include "py_callback.h"

class event_list;

/**
 * Directory where %event scripts reside.
 */ 
00035 #define EVENTS_DIR "game_events."

#ifndef SWIG
/**
 * Available %event types.
 */ 
enum
{
    ENTER_EVENT     = 0,            // Characters reach a new tile
    LEAVE_EVENT     = 1,            // Characters leave a tile
    TIME_EVENT      = 2,            // Certain point in gametime reached
    ACTION_EVENT    = 3,            // Character "acts" on a square 
    MAX_EVENTS      = 4
};

/**
 * Available 'actions', i.e. what happens when the event occurs
 */
enum
{
    ACTION_NOTHING  = 0,
    ACTION_SCRIPT   = 1,
    ACTION_PYFUNC   = 2,
    ACTION_CPPFUNC  = 3
};
#endif // SWIG
    
/**
 * Base class for events. You can create your own %event types that can
 * be handled by the event_list and event_handler by inheriting from
 * this class.
 *
 * Events are used to notify when certain things happen during the game.
 * They may either execute the "run" method of an exclusive %python script
 * or a simple %python callback defined elsewhere.
 */ 
00071 class event
{
public:
    /**
     * Constructor. Needs to be called by any derived class!
     */
    event ();

    /** 
     * Destructor.
     */ 
    virtual ~event ();

    /**
     * Cleanup. Clears script and its arguments. 
     */
    void clear ();    
    
    /**
     * @name Member access
     */
    //@{
    /**
     * Get the event's type.
     *
     * @return type of the %event
     */
00098     u_int8 type () const
    { 
        return Type;
    }

    /**
     * Get the event's id.
     *
     * @return id of the %event.
     */
00108     const string & id () const
    {
        return Id;
    }
    
    /**
     * Assign an id to the %event, so it may be retrieved from an
     * event_list later on, without having a pointer to it.
     *
     * @param id a string to identify the %event.
     */
00119     void set_id (const string & id)
    {
        Id = id;
    }
    
    /**
     * Test whether the %event is registered with the %event handler.
     *
     * @return \c true if this is the case, \c false otherwise.
     */
00129     bool registered () const
    {
        return Registered;
    }
#ifndef SWIG    
    /**
     * Set whether the %event is registered with the %event handler.
     *
     * @param reg Set to \c true if it is, to \c false otherwise.
     */
00139     void set_registered (bool reg)
    {
        Registered = reg;
    }
    
    /**
     * Tell the whether it is kept in an %event_list.
     *
     * @param list The %event_list this event has been added to.
     */
    void set_list (event_list *list);
#endif // SWIG    
    /**
     * Return whether this event should be repeated.
     *
     * @return the number of times this event should be repeated or
     *      -1 in case it should be repeated unlimited times.
     */
00157     s_int32 repeat () const
    {
        return Repeat;
    }
    
    /**
     * Set whether this event should be repeated. A number greater than 0
     * will execute the event that many times, a number less than 0 will
     * repeat the event forever. A number equal to 0 won't repeat the event.
     *
     * @param count How often the event should be repeated.
     */
00169     void set_repeat (s_int32 count)
    {
        Repeat = count;
    }
    //@}
    
    /**
     * @name Event Handling
     */
    //@{
    
    /**
     * Execute the associated python script or callback.
     * 
     * @param evnt The %event that triggered the execution.
     *
     * @return The number of times the %event needs to be repeated.
     */ 
    virtual s_int32 execute (const event* evnt) = 0;

    /** 
     * Compare two events for equality.
     * 
     * @param evnt pointer to the %event to compare with.
     * @return \e true if the events are equal, \e false otherwise.
     */
    virtual bool equals (const event* evnt) = 0;

    //@}
    
    /** 
     * Sets a script to be executed whenever the event occurs.
     * 
     * @param filename filename of the script to set.
     * @param args The arguments to pass to the script's constructor
     */
    void set_script (string filename, PyObject * args = NULL);
    
    /**
     * Sets a python function/method to be executed whenever the
     * %event occurs.
     *
     * @warning the callback won't be saved with the %event. It
     * must be restored by the event's owner.
     *
     * @param callback The function or method to call.
     * @param args Additional arguments to pass to the callback.
     */
    void set_callback (PyObject *callback, PyObject *args = NULL);
     
#ifndef SWIG
    /**
     * Sets a C function/C++ method to be executed whenever the
     * %event occurs.
     *
     * @warning the callback won't be saved with the %event. It
     * must be restored by the event's owner.
     *
     * @param callback The callback, a function with no arguments
     *      returning void
     */
    void set_callback (const Functor0 & callback);
#endif // SWIG

    /**
     * @name Pausing / Resuming execution
     */
    //@{
    
    /**
     * Disable the %event temporarily. As long as it in this state, the
     * event will neither be executed, nor will its repeat-count change.
     * As long as the %event is paused, it will be removed from its
     * %event handler.
     */
    virtual void pause ();
    
    /**
     * Re-enable an %event that has been paused. Re-registers it with
     * its %event handler.
     */
    virtual void resume ();

    /**
     * Check whether the %event is temporarily disabled or not.
     * @return \b true if it is paused, \b false otherwise.                     
     */
00256     bool is_paused () const
    {
        return Paused;
    }
    //@}

    /**
     * @name Loading / Saving
     */
    //@{

    /** 
     * Saves the basic %event %data (such as the type or script data)
     * to a file. Call this method from the derived class.
     * 
     * @param out file where to save the %event.
     */ 
    virtual void put_state (ogzstream& out) const;
    
    /** 
     * Loads the basic %event %date from a file. Call this method from 
     * the derived class.
     * 
     * @param in file to load the %event from.
     * @return \e true if the %event could be loaded, \e false otherwise
     */
    virtual bool get_state (igzstream& in);

    //@}
    
protected:
#ifndef SWIG
    /**
     * Decrease the event's repeat count and return the number of repeats 
     * left. If the repeat-count reaches 0, the %event will be destroyed.
     *
     * @return the number of times this event should be repeated or
     *      -1 in case it should be repeated unlimited times.
     */
    s_int32 do_repeat ();

    /**
     * @name Basic Event Data
     */
    //@{
    
    /**
     * Event type - see enum above.
     */ 
00305     u_int8 Type;

    /**
     * (Optional) Id of the event
     */
00310     string Id;
    
    /**
     * What happens if the event occurs - see enum above.
     */
00315     u_int8 Action;
    
    /**
     * Whether the %event is registered with the %event handler.
     */
00320     bool Registered;
    
    /**
     * Whether the %event temporarily disabled or not. 
     */
00325     bool Paused;
    
    /**
     * Defines how often the %event should be repeated. <b>0</b> means
     * never, <b>-1</b> means infinitely and <b>n</b> (n > 0) means 
     * exactly n times.
     */
00332     s_int32 Repeat;
    
    /**
     * The Python script accociated with this %event. It is executed
     * whenever the %event gets triggered.
     */
00338     py_object *Script; 

    /**
     * The arguments passed to the script. This needs to be a PyTuple
     * or NULL if there are no arguments.
     */
00344     PyObject *Args;
    
    /**
     * Python callback that may be executed instead of the script.
     */
00349     py_callback *PyFunc;
    
    /**
     * C++ callback that may be executed when the %event gets triggered.
     */
00354     Functor0 Callback;
    
    /**
     * The event_list this event is kept in.
     */
00359     event_list *List;
    //@}
#endif // SWIG
};

#endif // EVENT_H__

Generated by  Doxygen 1.6.0   Back to index