/*****************************************************************************
*                                                                            *
*   DISP.SPL     Copyright (C) 2014 DSP Development Corporation              *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:      Randy Race                                                  *
*                                                                            *
*   Synopsis:    Displays a value in a pop-up box                            *
*                                                                            *
*   Revisions:   11 Dec 2014  RRR  Creation                                  *
*                                                                            *
*****************************************************************************/


#if @HELP_DISP

    DISP

    Purpose: Displays a value as text in a pop-up box.

    Syntax:  DISP(val, "title")

                 val  - A string, series or scalar. The value to display.
                        Defaults to the current window.

              "title" - Optional. A string, the title for the pop-up box.
                        Defaults to "disp".


    Returns: A string if the result is assigned to a variable, else a
             pop-up box is displayed.

    Example:
             disp(pi/2)

             Displays 1.570796 in a pop-up box.

    Example:
             W1: rand(10)

             disp(W1, "Random Array")

             Displays the values of the 10x10 random array in a pop-up box.
             The title of the pop-up box is "Random Array".

    Example:
             t = disp(rand(3));
             viewtext(t)

             Variable t contains the values of the 3x3 random matrix as
             a table of text values. The values are displayed by the
             VIEWTEXT function.

    Remarks:
             DISP converts the input parameter to a string and displays
             the result in a pop-up box. If the result is assigned to
             a variable, the values of a series or array or converted
             to a text table.

             See ECHO to display the input in the status line.

    See Also:
             ECHO
             MESSAGE
             PRINTF 
             SPRINTF
             VIEWTEXT
#endif


/* display input value */
disp(val, title)
{
        if (argc < 2)
        {
                title = "disp";

                if (argc < 1)
                {
                        val   = refwindow(w0);
                        title = sprintf("W%d", getwnum(w0));
                }
                else
                {
                        title = iswindow(val) ? sprintf("W%d", getwnum(val)) : "disp";
                }
        }

        if (outargc > 0)
        {
                /* return value as text */
                return(evaltostr("val"));
        }
        else
        {
                /* view in a popup box */
                viewtext(evaltostr("val"), title);
        }
}