diguyVariable.h

Go to the documentation of this file.

/*********************************************************************
 ** Copyright (c) 1992-2022 MAK Technologies, Inc.
 ** All rights reserved.
 *********************************************************************/

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

#ifndef __diguyVariable_H
#define __diguyVariable_H

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

#ifdef CPLUSPLUS_ONLY

class bdiScenarioVariable;
class diguyCharacter;
class diguyScenario;
class diguyVariable;

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

#endif /* CPLUSPLUS_ONLY */

#include <declspec_diguy.h>

/****************************************************************************/
class BDI_DECLSPEC_diguy diguyVariable
{

public:
/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    Returns the name of the variable.  This pointer will
    **    never be NULL.
    **
    *b  Returns:
    **
    **    name of the variable
    */
   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:
    **
    **    Returns the scenario that this variable belongs to.  This
    **    pointer will never be NULL.  Note that if this variable
    **    belongs to a character, a pointer to the scenario that the
    **    character belongs to will be returned.
    */
   diguyScenario* get_scenario();

   /*l
    *b  Description:
    **
    **    Returns the character that this variable belongs to, if any.
    **    This pointer might be NULL is this variable is not a
    **    character variable.
    */
   diguyCharacter* get_character();

   /*l
    *b  Description:
    **
    **    Copies the contents of the passed variable.
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int copy(diguyVariable* rhs);

   int get_value_as_int();

   float get_value_as_float();

   const char* get_value_as_string();

   /*l
 *b  Description:
 **
 **    Returns the initial value of the variable as an integer.
 **
 *b  Returns:
 **
 **    initial value of the variable
 **
 *b  Callable From:
 **
 *-    - C++
 *-    - Script
 */
   int get_initial_value_as_int();

   /*l
    *b  Description:
    **
    **    Returns the initial value of the variable as a floating point
    **    number.
    **
    *b  Returns:
    **
    **    initial value of the variable
    */
   float get_initial_value_as_float();

   /*l
    *b  Description:
    **
    **    Returns the initial value of the variable as a string.  This
    **    pointer will never be NULL.
    **
    *b  Returns:
    **
    **    initial value of the variable
    */
   const char* get_initial_value_as_string();

   /*l
    *b  Description:
    **
    **    This function sets the initial value as an integer.
    **    The current value will be set to the initial value when the
    **    scenario containing this variable is reset.
    **
    *b  Arguments:
    **
    *a    initial value - new initial value of variable
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int set_initial_value_as_int(int initial_value);

   /*l
    *b  Description:
    **
    **    This function sets the initial value as a floating point number.
    **    The current value will be set to the initial value when the
    **    scenario containing this variable is reset.
    **
    *b  Arguments:
    **
    *a    initial value - new initial value of variable
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int set_initial_value_as_float(float initial_value);

   /*l
    *b  Description:
    **
    **    This function sets the initial value as a string.
    **    The current value will be set to the initial value when the
    **    scenario containing this variable is reset.
    **
    *b  Arguments:
    **
    *a    initial value - new initial value of variable
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int set_initial_value_as_string(const char* initial_value);


/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    This function sets the value as an integer.
    **
    *b  Arguments:
    **
    *a    value - new value of variable
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int set_value_as_int(int value);

   /*l
    *b  Description:
    **
    **    This function sets the value as a floating point number.
    **
    *b  Arguments:
    **
    *a    value - new value of variable
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int set_value_as_float(float value);

   /*l
    *b  Description:
    **
    **    This function sets the value as a string.
    **
    *b  Arguments:
    **
    *a    value - new value of variable
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int set_value_as_string(const char* value);

   /*l
    *b  Description:
    **
    **    This function increments the value as an int.
    **
    *b  Arguments:
    **
    *a    increment_amount - the value by which to increment
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int increment_value_as_int(int increment_amount = 1);

   /*l
    *b  Description:
    **
    **    This function decrements the value as an int.
    **
    *b  Arguments:
    **
    *a    decrement_amount - the value by which to decrement
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int decrement_value_as_int(int decrement_amount = 1);

   /*l
    *b  Returns:
    **
    **    1 if the variable as an int is equal to the passed value;
    **    0 if not
    **
    *b  Arguments:
    **
    *a    value - the value to compare against
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    */
   int equal_to_int(int value);

   /*l
    *b  Returns:
    **
    **    1 if the variable as an int is greater than the passed value;
    **    0 if not
    **
    *b  Arguments:
    **
    *a    value - the value to compare against
    */
   int greater_than_int(int value);

   /*l
    *b  Returns:
    **
    **    1 if the variable as an int is less than the passed value;
    **    0 if not
    **
    *b  Arguments:
    **
    *a    value - the value to compare against
    */
   int less_than_int(int value);

   /*l
    *b  Returns:
    **
    **    1 if the variable as a float is equal to the passed value;
    **    0 if not
    **
    *b  Arguments:
    **
    *a    value - the value to compare against
    */
   int equal_to_float(float value);

   /*l
    *b  Returns:
    **
    **    1 if the variable as a float is greater than the passed value;
    **    0 if not
    **
    *b  Arguments:
    **
    *a    value - the value to compare against
    */
   int greater_than_float(float value);

   /*l
    *b  Returns:
    **
    **    1 if the variable as a float is less than the passed value;
    **    0 if not
    **
    *b  Arguments:
    **
    *a    value - the value to compare against
    */
   int less_than_float(float value);

   /*l
    *b  Returns:
    **
    **    1 if the variable as a string is equal to the passed value;
    **    0 if not
    **
    *b  Arguments:
    **
    *a    value - the value to compare against
    */
   int equal_to_string(const char* value);

   /*l
    *b  Returns:
    **
    **    1 if the variable as a string is alphabetically greater than
    **    the passed value;
    **    0 if not
    **
    *b  Arguments:
    **
    *a    value - the value to compare against
    */
   int greater_than_string(const char* value);

   /*l
    *b  Returns:
    **
    **    1 if the variable as a string is alphabetically less than
    **    the passed value;
    **    0 if not
    **
    *b  Arguments:
    **
    *a    value - the value to compare against
    */
   int less_than_string(const char* value);


/*****************************************************************************/
   /*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_VALUE_CHANGED = 1
   };

#ifdef CPLUSPLUS_ONLY

   /*l
    *b  Description:
    **
    **    This function adds a user callback.
    **
    *b  Arguments:
    **
    *a    callback        - pointer to function with prototype
    *a                      diguyVariableCallback (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_VALUE_CHANGED
    **
    **      This callback will be called whenever the value of the
    **      variable changes.
    **
    **      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,
      diguyVariableCallback* 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                      diguyVariableCallback (typedefed above)
    **
    *b  Returns:
    **
    **    0 on success, -1 on failure
    **
    *b  Callable From:
    **
    *-    - C++
    */
   int remove_callback(int callback_id,
      diguyVariableCallback* 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 variable callback function registered by
    *-        diguyScenario::register_variable_event_handler() or
    *-        diguyScenario::register_variable_event_handler_from_library()
    *-      - a script registered by
    *-        diguyScenario::register_variable_event_handler_script()
    *-      - a Script, Decision, or Library Function in the scenario
    *-        whose "Event Type" is "Variable"
    **
    *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

   bdiScenarioVariable* get_scripted_object() {return m_scripted_object;}

private:

   /*l
    **    A private constructor.
    */
   diguyVariable(bdiScenarioVariable* variable);

   /*l
    **    A pointer to internal data.
    */
   bdiScenarioVariable* m_scripted_object;

   friend class bdiScenarioVariable;

#endif /* CPLUSPLUS_ONLY */

};

#endif /* __diguyVariable_H */