diguySignal.h

Go to the documentation of this file.

/*********************************************************************
 ** Copyright (c) 1992-2022 MAK Technologies, Inc.
 ** 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
    */
   const char* get_name();

   /*l
    *b  Description:
    **
    **    This function sets the name of this object.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   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
    */
   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
    */
   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
    */
   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
    */
   int get_is_visible_in_signal_palette();

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

   /*l
    *b  Description:
    **
    **    This function sets an optional signal description buffer.
    **
    *b  Arguments:
    **
    *a    info_text   - text of info
    */
   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
    */
   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
    */
   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 */