diguyVariable.h

Go to the documentation of this file.

/*********************************************************************
 ** Copyright (c) 1992-2015 VT MAK
 ** 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
         **
         *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:
         **
         **    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.
         **
         *b  Returns:
         **
         **    pointer of type diguyScenario
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        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.
         **
         *b  Returns:
         **
         **    pointer of type diguyCharacter; NULL if this variable is
         **    not a character variable
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        diguyCharacter* get_character();

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

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

        /*l
         *b  Description:
         **
         **    Returns the value of the variable as a floating point number.
         **
         *b  Returns:
         **
         **    value of the variable
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        float get_value_as_float();

        /*l
         *b  Description:
         **
         **    Returns the value of the variable as a string.  This pointer will
         **    never be NULL.
         **
         *b  Returns:
         **
         **    value of the variable
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        const char* get_value_as_string();

        /*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
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         *-    - Decision Bead
         */
        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
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         *-    - Decision Bead
         */
        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
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         *-    - Decision Bead
         */
        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
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         *-    - Decision Bead
         */
        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
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         *-    - Decision Bead
         */
        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
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         *-    - Decision Bead
         */
        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
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         *-    - Decision Bead
         */
        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
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         *-    - Decision Bead
         */
        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
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         *-    - Decision Bead
         */
        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
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         *-    - Decision Bead
         */
        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
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         *-    - Decision Bead
         */
        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
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         *-    - Decision Bead
         */
        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
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         *-    - Decision Bead
         */
        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
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         *-    - Decision Bead
         */
        int less_than_string(const char* value);

        /*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
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        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
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        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
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        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
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        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
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int set_initial_value_as_string(const char* initial_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
         **
         *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

        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 */