diguyViewLabel.h

Go to the documentation of this file.

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