diguySignal.h

Go to the documentation of this file.

/*********************************************************************
 ** Copyright (c) 1992-2019 VT MAK
 ** All rights reserved. 
 *********************************************************************/

/*********************************************************************
 **
 *t  diguySignal
 **
 *b    Link against: libdiguy
 */

#ifndef __diguySignal_H
#define __diguySignal_H

#ifdef SWIG
%module diguySignal
#else
#define CPLUSPLUS_ONLY
#endif

#ifdef CPLUSPLUS_ONLY

class bdiScenarioSignal;
class diguySignal;

#include <stdio.h> // for NULL
#include <diguy_constants.h>
#include <diguy_typedefs.h>

#endif /* CPLUSPLUS_ONLY */


#include <declspec_diguy.h>

/****************************************************************************/
class BDI_DECLSPEC_diguy diguySignal
{

public:

        /*l
         *b  Description:
         **
         **    Returns the name of the object.  This pointer will
         **    never be NULL.
         **
         *b  Returns:
         **
         **    name of the signal
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        const char* get_name();

        /*l
         *b  Description:
         **
         **    This function sets the name of this object.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int set_name(const char* name);

        /*l
         *b  Description:
         **
         **    Returns the type name of the object.  This pointer will
         **    never be NULL.
         **
         *b  Returns:
         **
         **    type name of the object
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        const char* get_type_name();

        /*l
         *b  Description:
         **
         **    This function resets the signal.  The number of times the signal
         **    has been triggered will be set to 0.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         *-    - Decision Bead
         */
        int reset();

        /*l
         *b  Description:
         **
         **    This function triggers the signal.  If a sound is associated with
         **    the signal, it will be played.  The number of times the signal
         **    has been triggered will be incremented by one.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         *-    - Decision Bead
         */
        int trigger();

        /*l
         *b  Returns:
         **
         **    Returns the number of times this signal has been triggered since
         **    the scenario started or since the last call to reset().
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         *-    - Decision Bead
         */
        int triggered();

        /*l
         *b  Returns:
         **
         **    Returns 1 if the signal has been triggered at least n
         **    times, else returns 0.
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         *-    - Decision Bead
         */
        int triggered_at_least_n_times(int n);

        /*l
         *b  Description:
         **
         **    This function causes the button for this signal to become visible
         **    in the DI-Guy Scenario Signal Palette.
         **
         **    This function is for DI-Guy Scenario only.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int signal_palette_show();

        /*l
         *b  Description:
         **
         **    This function causes the button for this signal to become hidden
         **    in the DI-Guy Scenario Signal Palette.
         **
         **    This function is for DI-Guy Scenario only.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int signal_palette_hide();

        /*l
         *b  Description:
         **
         **    This function returns a flag specifying whether the signal's
         **    button is visible in the DI-Guy Scenario Signal Palette.
         **
         **    This function is for DI-Guy Scenario only.
         **
         *b  Returns:
         **
         **    1 if the signal's button is visible, 0 if not
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int get_is_visible_in_signal_palette();

        /*l
         *b  Description:
         **
         **    This function returns an optional signal description buffer.
         **
         *b  Returns:
         **
         **    pointer to info text
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        const char* get_info_text();

        /*l
         *b  Description:
         **
         **    This function sets an optional signal description buffer.
         **
         *b  Arguments:
         **
         *a    info_text   - text of info
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        void set_info_text(const char* info_text);


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This is an enumeration of the different callbacks
         **    that can be registered with add_callback() and
         **    add_callback_script().
         **
         *b  Usable From:
         **
         *-    - C++
         *-    - Script
         */
        enum {
                CALLBACK_ID_PRE_TRIGGER = 1,
                CALLBACK_ID_POST_TRIGGER
        };

#ifdef CPLUSPLUS_ONLY

        /*l
         *b  Description:
         **
         **    This function adds a user callback.
         **
         *b  Arguments:
         **
         *a    callback        - pointer to function with prototype
         *a                      diguySignalCallback (typedefed above)
         *a    callback_id     - integer id of when this callback is to be called
         *a    callback_params - not currently used; pass NULL
         *a    callback_user_data - pointer for user's own use; DI-Guy will
         *a                         do nothing to the contents of this pointer
         *a                         beyond passing it back when the callback is
         *a                         invoked
         **
         **    callback_id should be one of the following values:
         **
         *i    CALLBACK_ID_PRE_TRIGGER
         **
         **      This callback will be called whenever the trigger() function
         **      is called, whether internally by DI-Guy of explicitly by
         **      the user in C++ or in a script.  It will be called before
         **      the default handler of the function.
         **
         **      There are no parameters for this callback.
         **
         *i    CALLBACK_ID_POST_TRIGGER
         **
         **      This callback will be called whenever the trigger() function
         **      is called, whether internally by DI-Guy of explicitly by
         **      the user in C++ or in a script.  It will be called after
         **      the default handler of the function.
         **
         **      There are no parameters for this callback.
         **
         *i    Callback Return Values:
         **
         **    Callbacks return a value of type diguyCallbackReturn,
         **    which will be DIGUY_CALLBACK_STOP or DIGUY_CALLBACK_CONTINUE.
         **    If the callback returns DIGUY_CALLBACK_STOP, the default handler
         **    of the function will not be called; the callback is asserting
         **    that it has done everything necessary for the function call.
         **    If the callback returns DIGUY_CALLBACK_CONTINUE, the default
         **    handler for the function will be called after the callback.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         */
        int add_callback(int callback_id,
                diguySignalCallback* callback,
                void* callback_params = 0,
                void* callback_user_data = 0);

        /*l
         *b  Description:
         **
         **    This function removes a user callback.  All callbacks matching
         **    the specified callback_id and callback function will be removed.
         **
         *b  Arguments:
         **
         *a    callback_id     - integer id of when this callback is to be called
         *a    callback        - pointer to function with prototype
         *a                      diguySignalCallback (typedefed above)
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         */
        int remove_callback(int callback_id,
                diguySignalCallback* callback);

        /*l
         *b  Description:
         **
         **    This function removes a user callback.  All callbacks matching
         **    the specified callback_id and callback_user_data pointer will
         **    be removed.
         **
         *b  Arguments:
         **
         *a    callback_id        - integer id of when this callback is to be called
         *a    callback_user_data - pointer for user's own use
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         */
        int remove_callback_with_user_data(int callback_id,
                void* callback_user_data);

#endif /* CPLUSPLUS_ONLY */

        /*l
         *b  Description:
         **
         **    This function adds a user callback script.  Callback scripts can
         **    be removed with remove_callback_script().
         **
         **    See diguyCharacter::add_callback_script() for an example
         **    of use.
         **
         *b  Arguments:
         **
         *a    callback_id          - integer id of the callback
         *a    callback_script      - script text of callback to be added
         *a    callback_script_type - the type of script contained in
         *a                           callback_script
         **
         **    If NULL is passed for callback_script_type, a default script type
         **    will be derived based on the default script interpreter of the
         **    scenario.
         **
         *i  Lua specific:
         **
         **    When the script is called, the object for which it is being called
         **    will be in the callback_object global.
         **
         **    To pass NULL when calling from a lua script, use nil.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int add_callback_script(int callback_id,
                const char* callback_script,
                const char* callback_script_type = NULL);

        /*l
         *b  Description:
         **
         **    This function removes a user callback script previously added with
         **    add_callback_script().
         **
         **    See diguyCharacter::remove_callback_script() for an example
         **    of use.
         **
         *b  Arguments:
         **
         *a    callback_id          - integer id of the callback
         *a    callback_script      - script text of callback previously added
         *a    callback_script_type - the type of script contained in
         *a                           callback_script
         **
         **    If NULL is passed for callback_script, all callback
         **    scripts whose ids match callback_id and whose types match
         **    callback_script_type will be removed.
         **
         **    If NULL is passed for callback_script_type, a default script type
         **    will be derived based on the default script interpreter of the
         **    scenario.
         **
         *i  Lua specific:
         **
         **    To pass NULL when calling from a lua script, use nil.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int remove_callback_script(int callback_id,
                const char* callback_script,
                const char* callback_script_type = NULL);


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function maps the event handler with the given name
         **    to a callback id.  This mapping will be saved in the .dss
         **    file and restored when the .dss file is loaded.
         **
         **    Mappings can also be made via the DI-Guy Scenario UI.
         **
         **    The event handler is one of the following:
         **
         *-      - a signal callback function registered by
         *-        diguyScenario::register_signal_event_handler() or
         *-        diguyScenario::register_signal_event_handler_from_library()
         *-      - a script registered by
         *-        diguyScenario::register_signal_event_handler_script()
         *-      - a Script, Decision, or Library Function in the scenario
         *-        whose "Event Type" is "Signal"
         **
         *b  Arguments:
         **
         *a    callback_id        - integer id of callback
         *a    handler_name       - name of the event handler to map
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int map_event_handler_to_callback_id(int callback_id,
                const char* handler_name);

        /*l
         *b  Description:
         **
         **    This function unmaps the event handler with the given name
         **    from a callback id.
         **
         *b  Arguments:
         **
         *a    callback_id        - integer id of callback
         *a    handler_name       - name of the event handler to map
         *a    unmap_all_matches  - pass 0 to unmap only the first match,
         *a                         pass 1 to unmap all matches
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int unmap_event_handler_from_callback_id(int callback_id,
                const char* handler_name,
                int unmap_all_matches = 0);


#ifdef CPLUSPLUS_ONLY

        bdiScenarioSignal* get_scripted_object() {return m_signal;}

private:

        /*l
         **    A private constructor.
         */
        diguySignal(bdiScenarioSignal* signal);

        /*l
         **    A pointer to internal data.
         */
        bdiScenarioSignal* m_signal;

        friend class bdiScenarioSignal;

#endif /* CPLUSPLUS_ONLY */

};

#endif /* __diguySignal_H */