diguyInteractionMachine.h

Go to the documentation of this file.

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


#ifndef __diguyInteractionMachine_H
#define __diguyInteractionMachine_H


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

#ifdef CPLUSPLUS_ONLY
class bdiScenarioInteractionMachine;
class diguyCharacter;
#endif


#include <declspec_diguy.h>

/*********************************************************************/
class BDI_DECLSPEC_diguy diguyInteractionMachine
{

public:

/*****************************************************************************
 **
 *2  General Functions
 **
 */

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

        /*l
         *b  Description:
         **
         **    This function begins the interaction.
         **
         **    The interaction UI will appear in DI-Guy Scenario.
         **
         **    The interaction can be ended by calling end_interaction(), or by
         **    the current state being changed to "end" through an input
         **    selection or a call to set_current_state().
         **
         *b  Arguments:
         **
         *a    initial_state - initial state that interaction will
         *a                    be in
         *a    initial_input - initial input that will be returned
         *a                    by get_last_selected_input() in the
         *a                    first state
         **
         **    By default, initial state will be "begin".
         **    By default, initial input will be "begin".
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int begin_interaction(const char* initial_state = NULL,
                const char* initial_input = NULL);

        /*l
         *b  Description:
         **
         **    This function ends the interaction.
         **
         **    The interaction UI will be hidden in DI-Guy Scenario.
         **
         **    Note that this call does not run the entry script of the "end"
         **    state.  Call set_current_state("end") to end the interaction
         **    and run the entry script of the "end" state when doing so.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int end_interaction();

        /*l
         *b  Returns:
         **
         **    1 if interaction is active and visible, 0 if not
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int get_interaction_is_active();

        /*l
         *b  Description:
         **
         **    This function sets whether the scenario is paused while the
         **    interaction is active.
         **
         **    If the scenario is to be paused, the current playback mode
         **    will be saved when the interaction begins, the playback
         **    mode will be changed to DIGUY_SCENARIO_PLAYBACK_MODE_STOP,
         **    and the original playback mode will be restored when the
         **    interaction ends.
         **
         **    If the scenario is not to be paused, beginning and ending
         **    the interaction will have no effect on the playback mode.
         **
         **    The default is to not pause the scenario.
         **
         *b  Arguments:
         **
         *a    pause_while_active - pass 1 to pause scenario when interaction
         *a                         is active, 0 to not change playback mode
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        void set_pause_scenario_while_active(int pause_while_active);

        /*l
         *b  Returns:
         **
         **    1 if playback mode will be paused, 0 if not
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int get_pause_scenario_while_active();

        /*l
         *b  Description:
         **
         **    This function resets the interaction to a clean state.
         **    It will:
         **
         *-    - set the initial heading to ""
         *-    - set the initial info text to ""
         *-    - remove all inputs
         *-    - reset ui appearances
         *-    - set all other parameters to default values
         *-
         *-    It will also do an implicit reset() call.
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        void reinitialize();

        /*l
         *b  Description:
         **
         **    This function resets the interaction to a reset state.
         **    It will:
         **
         *-    - set the UI appearance text to initial_ui_appearance
         *-    - set the heading to be initial_heading
         *-    - set the info text to initial_info
         *-    - set the current state to "begin"
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        void reset();

        /*l
         *b  Description:
         **
         **    This function stores a pointer to the passed character
         **    in the interaction machine.  Access to the character is
         **    then possible in state scripts by calling
         **    get_interaction_subject().
         **
         *b  Arguments:
         **
         *a    interaction_subject - pointer to character that is to
         *a                          by the interaction's primary subject
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        void set_interaction_subject(diguyCharacter* interaction_subject);

        /*l
         *b  Returns:
         **
         **    value set by set_interaction_subject()
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        diguyCharacter* get_interaction_subject();


/*****************************************************************************
 **
 *2  UI Functions
 **
 */

        /*l
         *b  Description:
         **
         **    This function updates the visible interaction UI in
         **    DI-Guy Scenario.  May calls that change visible settings of
         **    the UI will not take effect until this function is called.
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int update_ui();

        /*l
         *b  Description:
         **
         **    This enumeration lists the indices used for
         **    various UI appearance calls.  These indices should
         **    be used when calling:
         **
         *-    - set_initial_ui_appearance()
         *-    - set_ui_appearance()
         *-    - set_heading_color_bg()
         *-    - set_heading_color_fg()
         *-    - set_heading_font()
         **
         **    and equivalent functions for info and inputs.
         **
         **    Each UI appearance can have different colors and font
         **    settings, potentially giving the scenario user a
         **    visual cue that the interaction is showing a conversation,
         **    showing generation information, or providing an important
         **    notification,
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        enum {
                UI_APPEARANCE_CONVERSATION = 0,
                UI_APPEARANCE_INFO,
                UI_APPEARANCE_NOTIFICATION,
                UI_APPEARANCE_3,
                UI_APPEARANCE_4,

                UI_APPEARANCE_COUNT
        };

        /*l
         *b  Description:
         **
         **    This function sets the UI appearance that will be used
         **    after a begin_interaction() or reset() call.
         **
         **    The default is UI_APPEARANCE_CONVERSATION.
         **
         *b  Arguments:
         **
         *a    initial_ui_appearance - initial UI appearance
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int set_initial_ui_appearance(int initial_ui_appearance);

        /*l
         *b  Returns:
         **
         **    initial UI appearance as set by set_initial_ui_appearance()
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int get_initial_ui_appearance();

        /*l
         *b  Description:
         **
         **    This function sets the current UI appearance that should be
         **    used for the interaction.
         **
         **    The new setting will not take effect until the next call
         **    to update_ui().
         **
         **    Call update_ui() for new setting to take effect.
         **
         *b  Arguments:
         **
         *a    ui_appearance - new current UI appearance
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int set_ui_appearance(int ui_appearance);

        /*l
         *b  Returns:
         **
         **    current UI appearance; default is value returned by
         **    get_initial_ui_appearance()
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int get_ui_appearance();


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function sets the heading text that will be shown after
         **    after a begin_interaction() or reset() call.
         **
         **    The default is "", or show nothing.
         **
         *b  Arguments:
         **
         *a    initial_heading - initial heading text
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        void set_initial_heading(const char* initial_heading);

        /*l
         *b  Returns:
         **
         **    initial heading text as set by set_initial_heading()
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        const char* get_initial_heading();

        /*l
         *b  Description:
         **
         **    This function sets the current heading text that will be
         **    shown.
         **
         **    Call update_ui() for new setting to take effect.
         **
         *b  Arguments:
         **
         *a    heading - heading text to be shown
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        void set_heading(const char* heading);

        /*l
         *b  Returns:
         **
         **    current heading text as set by set_heading()
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        const char* get_heading();

        /*l
         *b  Description:
         **
         **    This function sets whether the heading will be visible.
         **
         **    Call update_ui() for new setting to take effect.
         **
         *b  Arguments:
         **
         *a    heading_visible - 1 for visible, 0 for invisible
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        void set_heading_visible(int heading_visible);

        /*l
         *b  Returns:
         **
         **    whether heading is visible
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int get_heading_visible();

        /*l
         *b  Description:
         **
         **    This function sets the background color of the heading.
         **
         **    Call update_ui() for new setting to take effect.
         **
         *b  Arguments:
         **
         *a    ui_appearance - which UI appearance this changes
         *a    r, g, b, a    - RGBA colors, from 0.0 to 1.0
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        void set_heading_color_bg(int ui_appearance,
                float r,
                float g,
                float b,
                float a = 1.0f);

        /*l
         *b  Description:
         **
         **    This function sets the foreground/font color of the heading.
         **
         **    Call update_ui() for new setting to take effect.
         **
         *b  Arguments:
         **
         *a    ui_appearance - which UI appearance this changes
         *a    r, g, b, a    - RGBA colors, from 0.0 to 1.0
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        void set_heading_color_fg(int ui_appearance,
                float r,
                float g,
                float b,
                float a = 1.0f);

        /*l
         *b  Description:
         **
         **    This function sets the font characteristics of the heading.
         **
         **    Call update_ui() for new setting to take effect.
         **
         *b  Arguments:
         **
         *a    ui_appearance   - which UI appearance this changes
         *a    font_family     - font family
         *a    font_point_size - point size of font
         *a    font_is_bold    - pass 1 for bold, 0 for normal
         *a    font_is_italic  - pass 1 for italic, 0 for normal
         **
         **    On Windows, the default font family is ""MS Shell Dlg",
         **    and the default point size is 10.
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        void set_heading_font(int ui_appearance,
                const char* font_family,
                int font_point_size,
                int font_is_bold = 0,
                int font_is_italic = 0);


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    Similar to set_initial_heading(), but for info instead.
         **
         **    Note that the info text can use simple HTML-style tags. For
         **    example:
         *>
         *-      - for a paragraph break: <p>
         *-      - for bold text: <b>bold</b>
         *-      - for underlined text: <u>bold</u>
         *-      - for italicized text: <i>bold</i>
         *<
         **
         **    The default is "", or show nothing.
         */
        void set_initial_info(const char* initial_info);

        /*l
         *b  Description:
         **
         **    Similar to get_initial_heading(), but for info instead.
         */
        const char* get_initial_info();

        /*l
         *b  Description:
         **
         **    Similar to set_heading(), but for info instead.
         */
        void set_info(const char* info);

        /*l
         *b  Description:
         **
         **    Similar to get_heading(), but for info instead.
         */
        const char* get_info();

        /*l
         *b  Description:
         **
         **    Similar to set_heading_visible(), but for info instead.
         */
        void set_info_visible(int info_visible);

        /*l
         *b  Description:
         **
         **    Similar to get_heading_visible(), but for info instead.
         */
        int get_info_visible();

        /*l
         *b  Description:
         **
         **    Similar to get_heading_visible(), but for info instead.
         */
        void set_info_color_bg(int ui_appearance,
                float r,
                float g,
                float b,
                float a = 1.0f);

        /*l
         *b  Description:
         **
         **    Similar to set_heading_color_fg(), but for info instead.
         */
        void set_info_color_fg(int ui_appearance,
                float r,
                float g,
                float b,
                float a = 1.0f);

        /*l
         *b  Description:
         **
         **    Similar to set_heading_font(), but for info instead.
         */
        void set_info_font(int ui_appearance,
                const char* font_family,
                int font_point_size,
                int font_is_bold = 0,
                int font_is_italic = 0);


/*****************************************************************************/
        /*l
         *b  Returns:
         **
         **    number of states in the interaction machine
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int get_num_states();

        /*l
         *b  Returns:
         **
         **    string id of state with given index; the returned pointer will
         **    never be NULL
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        const char* get_state_id_at_index(int index);

        /*l
         *b  Description:
         **
         **    This function removes all existing states from the interaction
         **    machine.
         **
         **    Default new states named "begin" and "end" are then automatically
         **    added.  These default states do not have an entry script, but one
         **    can be added later with the set_state_entry_script() or
         **    set_begin_state_entry_script() functions.
         **
         **    More new states can be added using the add_state() function.
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        void clear_states();

        /*l
         *b  Description:
         **
         **    This function adds a new state to the interaction machine.  Each
         **    state must have a unique state_id (name of the state).
         **
         *b  Arguments:
         **
         *a    state_id      - name of the new state
         *a    entry_script  - script text that will be run every time this
         *a                    new state is entered
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int add_state(const char* state_id,
                const char* entry_script);

        /*l
         *b  Description:
         **
         **    This function removes the specified state from the interaction
         **    machine.
         **
         **    The required "begin" and "end" states cannot be removed.
         **
         *b  Arguments:
         **
         *a    state_id  - name of state to remove
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int remove_state(const char* state_id);

        /*l
         *b  Description:
         **
         **    This function renames the specified state.  Each state must
         **    have a unique state_id (name of the state).
         **
         **    The required "begin" and "end" states cannot be renamed.
         **
         *b  Arguments:
         **
         *a    old_state_id  - name of state to rename
         *a    new_state_id  - new name of state
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int rename_state(const char* old_state_id, const char* new_state_id);

        /*l
         *b  Description:
         **
         **    This function sets the entry script of this state.  Each time
         **    the specified state is entered, the entry script will be run.
         **
         *b  Arguments:
         **
         *a    state_id     - name of state to modify
         *a    entry_script - new entry script
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int set_state_entry_script(const char* state_id,
                const char* entry_script);

        /*l
         *b  Description:
         **
         **    This function sets the entry script of the required "begin"
         **    state.
         **
         *b  Arguments:
         **
         *a    entry_script - new entry script
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int set_begin_state_entry_script(const char* entry_script);

        /*l
         *b  Description:
         **
         **    This function returns the current state the interaction machine
         **    is in.
         **
         *b  Returns:
         **
         **    name of current state; the returned should never be NULL
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        const char* get_current_state();

        /*l
         *b  Description:
         **
         **    This function sets the current state of the interaction machine.
         **    The entry script of the new state will be run by default, but
         **    can optionally be skipped.
         **
         **    If the new state is "end", the interaction will end, as
         **    if the end_interaction() call is made, once the entry script of
         **    the "end" state entry script is run.
         **
         *b  Arguments:
         **
         *a    new_current_state  - new current state
         *a    run_entry_script   - pass 1 to run the new state's entry script,
         *a                         0 to not
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        void set_current_state(const char* new_current_state,
                int run_entry_script = 1);


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function removes all inputs from the interaction machine.
         **    New inputs can be added by calling add_input().
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        void clear_inputs();

        /*l
         *b  Description:
         **
         **    This function adds a new input to the interaction machine.  Each
         **    input must have a unique input_id (name of the input).
         **
         **    If the resulting state is "end", the interaction will end, as
         **    if the end_interaction() call is made, once the entry script of
         **    the "end" state entry script is run.
         **
         *b  Arguments:
         **
         *a    input_id        - name of the new input
         *a    input_string    - text that will be shown in the UI
         *a    resulting_state - state id of the state the interaction machine
         *a                      will change to if this new input is selected
         *a    int_param_0     - an optional integer parameter that can be
         *a                      interpreted in the new state's entry script
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int add_input(const char* input_id,
                const char* input_string,
                const char* resulting_state = "",
                int int_param_0 = 0);

        /*l
         *b  Description:
         **
         **    This function removes the specified input.
         **
         *b  Arguments:
         **
         *a    input_id  - name of input to rename
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int remove_input(const char* input_id);

        /*l
         *b  Returns:
         **
         **    how many inputs there are
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int get_num_inputs();

        /*l
         *b  Returns:
         **
         **    input id of the input at the specified index; see
         **    add_input()
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        const char* get_input_id(int index);

        /*l
         *b  Returns:
         **
         **    input string of the specified input; see add_input()
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        const char* get_input_string(const char* input_id);

        /*l
         *b  Returns:
         **
         **    resulting state of the specified input; see add_input()
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        const char* get_input_resulting_state(const char* input_id);

        /*l
         *b  Returns:
         **
         **    integer parameter 0 of the specified input; see add_input()
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int get_input_int_param_0(const char* input_id);

        /*l
         *b  Description:
         **
         **    This function "manually" selects the specified input.  Most of
         **    the time inputs are selected via the UI.
         **
         **    A side effect of selecting an input is almost always that the
         **    interaction machine will be put into a new state.
         **
         *b  Arguments:
         **
         *a    input_id  - input id of input that should be selected
         **
         **    The passed input id must be a current available input of the
         **    interaction machine.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int select_input(const char* input_id);

        /*l
         *b  Returns:
         **
         **    input id of the last selected input; state entry scripts can
         **    use this information to make decisions based on how the state
         **    was entered
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        const char* get_last_selected_input();

        /*l
         *b  Description:
         **
         **    This function sets the name of the scenario-level variable in
         **    which the name of the last selected input will be recorded.
         **    State entry scripts can then read determine which input
         **    caused the interaction machine to entry the state.
         **
         *b  Arguments:
         **
         *a    last_input_variable  - name of scenario-level variable
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        void set_last_input_variable(const char* last_input_variable);

        /*l
         *b  Returns:
         **
         **    name of last input variable; empty string ("") if there is
         **    none
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        const char* get_last_input_variable();

        /*l
         *b  Description:
         **
         **    This function sets whether the inputs section of the UI will
         **    be visible.  The inputs will be visible by default.
         **
         *b  Arguments:
         **
         *a    visible  - pass 1 to make inputs visible; 0 to not
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        void set_inputs_visible(int visible);

        /*l
         *b  Returns:
         **
         **    whether the inputs section of the UI will be visible
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int get_inputs_visible();

        /*l
         *b  Description:
         **
         **    This function sets whether a "shortcut" for each input will be
         **    visible in the UI, before the input text.
         **
         **    Currently the shortcuts are limited to numbers; the first input
         **    will be prefixed by "1.", the second by "2.", etc.
         **
         **    Input shortcuts are visible by default.
         **
         *b  Arguments:
         **
         *a    visible  - pass 1 to make shortcuts visible; 0 to not
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        void set_input_shortcuts_visible(int visible);

        /*l
         *b  Returns:
         **
         **    whether the input shortcuts will be visible in the UI
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int get_input_shortcuts_visible();

        /*l
         *b  Description:
         **
         **    Similar to set_heading_font(), but for inputs instead.
         */
        void set_inputs_font(int ui_appearance,
                const char* font_family,
                int font_point_size,
                int font_is_bold = 0,
                int font_is_italic = 0);

        /*l
         *b  Description:
         **
         **    Similar to set_heading_color_bg(), but for inputs instead.
         */
        void set_inputs_color_bg(int ui_appearance,
                float r,
                float g,
                float b,
                float a = 1.0f);

        /*l
         *b  Description:
         **
         **    Similar to set_heading_color_fg(), but for inputs instead.
         */
        void set_inputs_color_fg(int ui_appearance,
                float r,
                float g,
                float b,
                float a = 1.0f);


/****************************************************************************/
/****************************************************************************/
/****************************************************************************/
/****************************************************************************/
/****************************************************************************/
/****************************************************************************/

        // use set_ui_appearance() instead
        int set_current_settings_index(int current_settings_index);

        // set set_begin_state_entry_script() instead
        void set_input_response_script(const char* script);

#ifdef CPLUSPLUS_ONLY

        bdiScenarioInteractionMachine* get_scripted_object() {return m_scripted_object;}

private:

        /*l
         **    A private constructor.
         */
        diguyInteractionMachine(bdiScenarioInteractionMachine* scripted_object);

        /*l
         **    A private destructor.
         */
        virtual ~diguyInteractionMachine();

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

        friend class bdiScenarioInteractionMachine;

#endif

};


#endif /* __diguyInteractionMachine_H */


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