diguyViewLabel.h

Go to the documentation of this file.

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

/*********************************************************************/
#ifndef __diguyViewLabel_H
#define __diguyViewLabel_H

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

#ifdef CPLUSPLUS_ONLY
class bdiGraphicsLabel;

#include <stdio.h> // for NULL definition
#include <diguy_constants.h>
#include <diguy_typedefs.h>
class diguyViewLabel;


#endif


/****************************************************************************/
typedef int diguyViewLabelJustification;
enum {
        DIGUY_GRAPHICS_LABEL_JUSTIFIED_LEFT   = 0,
        DIGUY_GRAPHICS_LABEL_JUSTIFIED_BOTTOM = 0,
        DIGUY_GRAPHICS_LABEL_JUSTIFIED_RIGHT  = 1,
        DIGUY_GRAPHICS_LABEL_JUSTIFIED_TOP    = 1,
        DIGUY_GRAPHICS_LABEL_JUSTIFIED_CENTER = 2
};

#include <declspec_diguy.h>


/****************************************************************************/
class BDI_DECLSPEC_diguy diguyViewLabel
{

public:

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


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    Sets the text on the label.
         */
        void set_text(const char* text);

        /*l
         *b  Description:
         **
         **    Returns the text on the label.
         **
         *b  Returns:
         **
         **    pointer to NULL-terminated string
         */
        const char* get_text();

        /*l
         *b  Description:
         **
         **    Sets the font to use.
         */
        int set_font(const char* name);

        /*l
         *b  Description:
         **
         **    Returns the font set by set_font.
         **
         *b  Returns:
         **
         **    NULL or pointer to NULL-terminated string
         */
        const char* get_font();

        /*l
         *b  Description:
         **
         **    Similar to set_background_color(), but sets the color
         **    of the label text.
         **
         **    Default color is solid white (1, 1, 1, 1).
         */
        void set_text_color(float r, float g, float b, float a,
                float interp_time = 0.0f);

        /*l
         *b  Description:
         **
         **    Similar to set_background_color(), but sets the shadow color
         **    of the label text.
         **
         **    Default color is solid black (0, 0, 0, 1).
         */
        void set_text_shadow_color(float r, float g, float b, float a,
                float interp_time = 0.0f);

        /*l
         *b  Description:
         **
         **    Enables or disables text shadow.  Default is 0 (disabled).
         **
         *b  Arguments:
         **
         *a    text_shadow_enabled - pass 1 to enable shadow, 0 to disable
         */
        void set_text_shadow_enabled(int text_shadow_enabled);

        /*l
         *b  Description:
         **
         **    Sets how the label text is justified, possible values are:
         **
         **     - DIGUY_GRAPHICS_LABEL_JUSTIFIED_LEFT
         **     - DIGUY_GRAPHICS_LABEL_JUSTIFIED_RIGHT
         **     - DIGUY_GRAPHICS_LABEL_JUSTIFIED_CENTER
         **
         **    Depending on how the flag is set the text will either draw flowing
         **    to the right of the current x. The left of the current x or
         **    centered above x.
         */
        void set_text_justification(diguyViewLabelJustification just);

        /*l
         *b  Description:
         **
         **    Returns how the text on the label is being justified.
         **
         *b  Returns:
         **
         **    One of the following values:
         **
         *-     - DIGUY_GRAPHICS_LABEL_JUSTIFIED_LEFT
         *-     - DIGUY_GRAPHICS_LABEL_JUSTIFIED_RIGHT
         *-     - DIGUY_GRAPHICS_LABEL_JUSTIFIED_CENTER
         */
        diguyViewLabelJustification get_text_justification();

        /*l
         *b  Description:
         **
         **    Adds an x offset to the text part of the label.
         */
        void set_text_offset_x(int offset);

        /*l
         *b  Returns:
         **
         **    returns the x offset of the text part of the label.
         */
        int get_text_offset_x();

        /*l
         *b  Description:
         **
         **    Adds a y offset to the text part of the label.
         */
        void set_text_offset_y(int offset);

        /*l
         *b  Returns:
         **
         **    returns the y offset of the text part of the label.
         */
        int get_text_offset_y();


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    Sets the x location of the label.  Positive numbers are
         **    relative to the left side of the screen; negative numbers
         **    are relative to the right side of the screen.
         **
         **    The optional interp_time argument will make the label
         **    animate to its new location.
         **
         *b  Arguments:
         **
         *a    screen_x_offset - x offset in pixels
         *a    interp_time     - amount of time in seconds used to
         *a                      shift to new position
         */
        void set_x(float screen_x_offset,
                float interp_time = 0.0f);

        /*l
         *b  Description:
         **
         **    Gets the x location of the label.
         **
         **    Note: this will return the current x value, not the desired one.
         */
        float get_x();

        /*l
         *b  Description:
         **
         **    Sets the y location of the label.  Positive numbers are
         **    relative to the bottom of the screen; negative numbers
         **    are relative to the top of the screen.
         **
         **    The optional interp_time argument will make the label
         **    animate to its new location.
         **
         *b  Arguments:
         **
         *a    screen_y_offset - y offset in pixels
         *a    interp_time     - amount of time in seconds used to
         *a                      shift to new position
         */
        void set_y(float screen_y_offset,
                float interp_time = 0.0f);

        /*l
         *b  Description:
         **
         **    Gets the y location of the label.
         **
         **    Note: this will return the current y value, not the desired one.
         */
        float get_y();

        /*l
         *b  Description:
         **
         **    Sets the position of the label in world space.
         **
         *b  Arguments:
         **
         *a    x, y, z - coordinates in world space
         */
        void set_world_xyz(float x, float y, float z);

        /*l
         *b  Description:
         **
         **    Gets the position of the label in world space.
         */
        void get_world_xyz(float* x, float* y, float* z);

        /*l
         *b  Description:
         **
         **    Sets if having a negative value wraps to the other side of the
         **    viewport.  Defaults to 1.
         **
         *b  Arguments:
         **
         *a    wrap - 1 if x should wrap; 0 if not
         */
        void set_negative_wraps_x(int wrap);

        /*l
         *b  Returns:
         **
         **    1 if x wraps its offset when negative
         */
        int get_negative_wraps_x();

        /*l
         *b  Description:
         **
         **    Sets if having a negative value wraps to the other side of the
         **    viewport.  Defaults to 1.
         **
         *b  Arguments:
         **
         *a    wrap - 1 if y should wrap; 0 if not
         */
        void set_negative_wraps_y(int wrap);

        /*l
         *b  Returns:
         **
         **    1 if y wraps its offset when negative
         */
        int get_negative_wraps_y();

        /*l
         *b  Description:
         **
         **    Sets how the label is positioned relative to the window, possible
         **    values are:
         **
         *-     - DIGUY_GRAPHICS_LABEL_JUSTIFIED_LEFT
         *-     - DIGUY_GRAPHICS_LABEL_JUSTIFIED_RIGHT
         *-     - DIGUY_GRAPHICS_LABEL_JUSTIFIED_CENTER
         **
         **    Depending on how the flag is set the x offset will be measured from
         **    the right of the screen, the left or from the center of the window.
         */
        void set_window_justification_x(diguyViewLabelJustification just);

        /*l
         *b  Returns:
         **
         **   label's x positioning parameter described above
         */
        diguyViewLabelJustification get_window_justification_x();

        /*l
         *b  Description:
         **
         **    Sets how the label is positioned relative to the window.  Possible
         **    values are:
         **
         *-     - DIGUY_GRAPHICS_LABEL_JUSTIFIED_BOTTOM
         *-     - DIGUY_GRAPHICS_LABEL_JUSTIFIED_TOP
         *-     - DIGUY_GRAPHICS_LABEL_JUSTIFIED_CENTER
         **
         **    Depending on how the flag is set the y offset will be measured from
         **    the bottom of the screen, from the top or from the center of the
         **    window.
         */
        void set_window_justification_y(diguyViewLabelJustification just);

        /*l
         *b  Returns:
         **
         **   label's y positioning parameter described above
         */
        diguyViewLabelJustification get_window_justification_y();

        /*l
         *b  Description:
         **
         **    Adds a screen-space x offset to the final position of the label.
         */
        void set_offset_x(int offset);

        /*l
         *b  Returns:
         **
         **    returns the x offset of the label.
         */
        int get_offset_x();

        /*l
         *b  Description:
         **
         **    Adds a screen-space y offset to the final position of the label.
         */
        void set_offset_y(int offset);

        /*l
         *b  Returns:
         **
         **    returns the y offset of the label.
         */
        int get_offset_y();

        /*l
         *b  Description:
         **
         **    Sets the minimum width of the label.  The default is 0,
         **    which will size the label width to fit the label text or bar
         **    graph.
         **
         *b  Arguments:
         **
         *a    min_x - minimum width, in pixels
         */
        void set_minimum_width(int min_x);

        /*l
         *b  Returns:
         **
         **    minimum width of the label, as set by set_minimum_width()
         */
        int get_minimum_width();

        /*l
         *b  Description:
         **
         **    Similar to set_minimum_width(), but sets minimum label height.
         */
        void set_minimum_height(int min_y);

        /*l
         *b  Description:
         **
         **    Similar to set_minimum_height(), but returns minimum label height.
         */
        int get_minimum_height();

        /*l
         *b  Returns:
         **
         **    the current label width
         */
        int get_width();

        /*l
         *b  Returns:
         **
         **    the current label height
         */
        int get_height();

        /*l
         *b  Description:
         **
         **    Turns the label into a full-window overlay.  This can be useful
         **    for things like Heads-Up Displays (HUDs).
         **
         **    If there is a background image (see set_background_image()), the
         **    image will be scaled to fit the entire screen.
         **
         **    Default is 0 (not full-window).
         **    Note: turning a label into a full window will automatically make
         **    it non-clickable.
         **
         *b  Arguments:
         **
         *a    full_window - pass 1 for full-window, 0 for not full-window
         */
        void set_full_window(int full_window);

        /*l
         *b  Returns:
         **
         **    whether label is full-window, as set by set_full_window()
         */
        int get_full_window();

        /*l
         *b  Description:
         **
         **    Resets the parameters of the label to the values from the
         **    constructor.
         */
        void reset();

        /*l
         *b  Description:
         **
         **    Sets the visibility of a label.  Default is 1 (visible).
         **
         *b  Arguments:
         **
         *a    visible - pass 1 to make label visible, 0 for invisible
         */
        void set_visible(int visible);

        /*l
         *b  Returns:
         **
         **    visibility of label, as set by set_visible()
         */
        int get_visible();


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    Sets the color of the label background.
         **
         **    The optional interp_time argument will make the label gradually
         **    shift to its new color.
         **
         *b  Arguments:
         **
         *a    r, g, b, a  - RGBA values of new color, between 0.0 and 1.0
         *a    interp_time - amount of time in seconds used to shift to
         *a                  new color
         **
         **    Default color is translucent blue (0, 0, 0.3, 0.7).
         */
        void set_background_color(float r, float g, float b, float a,
                float interp_time = 0.0f);

        /*l
         *b  Description:
         **
         **    Sets the background image of the label.  The file will
         **    be looked for in $DIGUY/custom/geometry/rgb first,
         **    then in $DIGUY/geometry/rgb.
         **
         **    The default is no background image.
         */
        void set_background_image(const char* filename);

        /*l
         *b  Description:
         **
         **    Enables or disables label background.  Default is 1 (enabled).
         **
         *b  Arguments:
         **
         *a    background_enabled - pass 1 to enable shadow, 0 to disable
         */
        void set_background_enabled(int background_enabled);


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    Similar to set_border_color(), but sets the border color of the
         **    label background.
         **
         **    Default color is translucent white (1, 1, 1, 0.7).
         *a    r, g, b, a  - RGBA values of new color, between 0.0 and 1.0
         *a    interp_time - amount of time in seconds used to shift to
         *a                  new color
         */
        void set_border_color(float r, float g, float b, float a,
                float interp_time = 0.0f);

        /*l
         *b  Description:
         **
         **    Sets the margin, of the label.  Default is 6 pixels.
         **
         *b  Arguments:
         **
         *a    margin_size - margin size in pixels
         */
        void set_margin_size(int margin_size);

        /*l
         *b  Description:
         **
         **    Sets if the border should be visible.  Default is 1 (enabled).
         **
         *b  Arguments:
         **
         *a    border_enabled - pass 1 to enable, 0 to disable
         */
        void set_border_enabled(int border_enabled);


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    Enables bar graph functionality for this label.  Note that this
         **    doesn't automatically turn off text or background image.
         **
         **    Label position and minimum sizes should be set before this
         **    is called.
         **
         *b  Arguments:
         **
         *a    num_lines           - number of lines/bars that will be shown
         *a    lines_are_vertical  - pass 1 for lines to go bottom to top,
         *a                          0 for lines to go left to right
         *a    line_thickness      - line thickness, in pixels
         *a    space_between_lines - space between lines, in pixels
         *a    derive_minimum_label_size - derive and set the minimum label size,
         *a                          as if set_minimum_width() and
         *a                          set_minimum_height() were called to fit
         *a                          this bar graph
         */
        void enable_bar_graph(int num_lines,
                int lines_are_vertical = 1,
                int line_thickness = 10,
                int space_between_lines = 2,
                int derive_minimum_label_size = 1);

        /*l
         *b  Description:
         **
         **    Disables bar graph functionality for this label.  Bar graph lines
         **    will no longer be visible.
         */
        void disable_bar_graph();

        /*l
         *b  Returns:
         **
         **   number of bars/lines in bar graph
         */
        int get_bar_graph_num_lines();

        /*l
         *b  Returns:
         **
         **   1 if lines to go bottom to top, 0 if lines to go left to right
         */
        int get_bar_graph_lines_are_vertical();

        /*l
         *b  Description:
         **
         **    Sets the color of the specified line.
         */
        void set_bar_graph_line_color(int line_number,
                float r, float g, float b, float a);

        /*l
         *b  Description:
         **
         **    Sets how much of the usable space (bottom to top for vertical
         **    lines, left to right for horizontal lines) a line will take up
         **    at its maximum length.
         **
         *b  Arguments:
         **
         *a    line_number - line to change
         *a    ratio       - how much of the line to display, from 0 (none) to
         *a                  1 (all)
         **
         **    For example, if, based on the label height, the bar graph has at
         **    most 20 pixels to show each line, passing 0.5 for ratio will
         **    fill 10 pixels with the line color, while passing 1.0 for ratio
         **    will fill all 20 pixels.
         */
        void set_bar_graph_line_magnitude_ratio(int line_number, float ratio);

        /*l
         *b  Description:
         **
         **    Similar to set_bar_graph_line_magnitude_ratio(), but sets the
         **    length of the line based on absolute pixels.
         **
         **    Note that care should be taken to not overrun the current height
         **    or width of the label when using this function.
         **
         *b  Arguments:
         **
         *a    line_number - line to change
         *a    pixels      - line length in pixels
         */
        void set_bar_graph_line_magnitude_pixels(int line_number, int pixels);


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    Sets if a label is temporary.  Temporary labels are destroyed on
         **    scenario reset, and will not re-appear unless they are recreated.
         **
         **    Pass 1 to make label temporary, 0 to make it permanent.
         */
        void set_is_temporary(int temporary);

        /*l
         *b  Returns:
         **
         **    1 if a label is temporary, 0 if not; see set_is_temporary()
         */
        int get_is_temporary();

        /*l
         *b  Description:
         **
         **    Sets how far away the label will be drawn.
         **
         *b  Arguments:
         **
         *a    draw_limit - -1 to always draw, otherwise will draw till draw_limit
         *a                 is reached
         */
        void set_draw_limit(float draw_limit);

        /*l
         *b  Description:
         **
         **    Gets how far away the label will be drawn.
         **    Defaults to -1 which always draws.
         */
        float get_draw_limit();

        /*l
         *b  Description:
         **
         **    Sets if the label is clickable with the mouse.
         **
         **    For character labels this is the equivalent of clicking on the
         **    character itself, and can trigger the CALLBACK_ID_IGUY_INTERACT
         **    callback.
         **
         **    For screen labels it triggers CALLBACK_ID_USER_SELECTED on mouse
         **    down, and CALLBACK_ID_USER_UNSELECTED on mouse up.
         **
         **    By default labels are clickable.
         **
         *b  Arguments:
         **
         *a    is_clickable - pass 1 to enable, 0 to disable
         */
        void set_is_clickable(int is_clickable);

        /*l
         *b  Returns:
         **
         **    1 if label responds to mouse clicks, 0 if not; see
         **    set_is_clickable()
         */
        int get_is_clickable();

        /*l
         *b  Description:
         **
         **    Sets if the label is "noise".
         **
         **    The textures of noise labels with be shifted every frame.
         **
         **    By default labels not noise.
         **
         *b  Arguments:
         **
         *a    is_noise - pass 1 to enable, 0 to disable
         */
        void set_is_noise(int is_noise);

        /*l
         *b  Returns:
         **
         **    1 if label textures shift every frame, 0 if not; see
         **    set_is_noise()
         */
        int get_is_noise();

        /*l
         *b  Resturs:
         **
         **    NULL-terminated string "label"
         */
        const char* get_type_name();

        /*l
         *b  Description:
         **
         **    This is an enumeration of the different callbacks that can be
         **    registered with add_callback() and add_callback_script().
         */
        enum {
                CALLBACK_ID_USER_SELECTED = 1,
                CALLBACK_ID_USER_UNSELECTED,
                CALLBACK_ID_IGUY_INTERACT,
                CALLBACK_ID_MOUSE_DOWN,
                CALLBACK_ID_MOUSE_UP,
                CALLBACK_ID_LEFT_CLICK,
                CALLBACK_ID_RIGHT_CLICK,
                CALLBACK_ID_MIDDLE_CLICK,
                CALLBACK_ID_DOUBLE_CLICK,
                CALLBACK_ID_BEGIN_DRAG,
                CALLBACK_ID_END_DRAG
        };

        /*l
         *b  Description:
         **
         **    This function adds a user callback script.  Callback scripts can
         **    be removed with remove_callback_script().
         **
         *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  lua Example:
         **
         *e     ------------------------------------------------------------------------------
         *e     local on_clicked_callback = [[
         *e     
         *e         local la_name = callback_object:get_name();
         *e         bdi_log_print(BDI_LOG_WARN, "Calling on_click for label ".. la_name .. "'.\n");
         *e     
         *e     ]]
         *e     ------------------------------------------------------------------------------
         *e     
         *e     label:add_callback_script(diguyViewLabel_CALLBACK_ID_USER_UNSELECTED,
         *e         on_clicked_callback,
         *e         "lua");
         */
        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().
         **
         *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  Lua Example:
         **
         *e     --
         *e     -- Remove all callback scripts with id
         *e     --  diguyViewLabel_CALLBACK_ID_USER_UNSELECTED
         *e     --
         *e     label:remove_callback_script(diguyViewLabel_CALLBACK_ID_USER_UNSELECTED,
         *e         nil,
         *e         "lua");
         */
        int remove_callback_script(int callback_id,
                const char* callback_script,
                const char* callback_script_type = NULL);


#ifdef CPLUSPLUS_ONLY

        /*l
         *b  Description:
         **
         **    This function adds a user callback.  Callbacks can be removed
         **    with remove_callback() or remove_callback_with_user_data().
         **
         *b  Arguments:
         **
         *a    callback        - pointer to function with prototype
         *a                      diguyViewLabelCallback (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
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         */
        int add_callback(int callback_id,
                diguyViewLabelCallback* callback,
                void* callback_params = NULL,
                void* callback_user_data = NULL);

        /*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                      diguyViewLabelCallback (typedefed above)
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         */
        int remove_callback(int callback_id,
                diguyViewLabelCallback* callback);

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

        bdiGraphicsLabel* get_scripted_object() {return m_label;}

private:

        /*l
         **  A private constructor.
         */
        diguyViewLabel(bdiGraphicsLabel* label);

        /*l
         **  A pointer to internal data.
         */
        bdiGraphicsLabel* m_label;

        friend class bdiGraphicsLabel;

#endif

};

#endif /* __diguyViewFog_H */