/*****************************************************************************
*                                                                            *
*   SETCOLORBARLABEL.SPL  Copyright (C) 2013 DSP Development Corporation     *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:         Randy Race                                               *
*                                                                            *
*   Synopsis:       Sets the label of a colorbar                             *
*                                                                            *
*   Revisions:      21 Oct 2013  RRR  Creation                               *
*                   28 Oct 2013  RRR  default to Z label                     *
*                                                                            *
*****************************************************************************/


#if @HELP_SETCOLORBARLABEL

    SETCOLORBARLABEL

    Purpose: Sets the label of a vertical colorbar.

    Syntax:  SETCOLORBARLABEL(win, mode, "label")

                    win - Optional. A window, the target window. Defaults to
                          the current window.

                   mode - Optional. An integer, the label mode:

                            0: do not display colorbar label
                            1: display colorbar label (default)

                  label - Optional. A string, the colorbar label. Defaults
                          to the Z axis label of the source window data.

    Returns: Nothing, the colorbar label is displayed or removed from the
             plot.

    Example:
             W1: spline2(randn(5), 10);setplottype(3);setzunits("V");colorbar;setcolorbarlabel(1)

             W1 contains a 41x41 array. The array is displayed as an image and
             the Z units are set to "Volts". A colorbar is added and the
             label of the colorbar is set to the Z units.

    Example:
             W1: spline2(randn(5), 10);setplottype(3);colorbar

             setcolorbarlabel(W1, "Z Force in Newtons");

             W1 contains an array displayed as an image. A colorbar is added
             and the label of the colorbar is set to "Z Force in Newtons".


    Example:
             setcolorbarlabel(W1, 0)

             Removes the label of a the colorbar in W1 if it exists.

    Remarks:
             SETCOLORBARLABEL requires that a COLORBAR is present in the
             target window.

             Use SETCOLORBARLABEL(win, 1, "") to reset the colorbar label
             display to the Z units of the source data.

    See Also:
             Colorbar
             Focus
             Getcolorbarlabel
             Ylabel
#endif


/* set the label of a colorbar */
setcolorbarlabel(argv)
{
        local val, w, i, lab, v, f, pf, ylab;

        val = 1;
        lab = "";
        w   = refwindow(w0);
        
        loop (i = 1.. argc)
        {
                v = getargv(i);

                if (iswindow(v))
                {
                        w = refwindow(v);
                }
                else if (isstring(v))
                {
                        lab = v;
                }
                else if (isscalar(v))
                {
                        val = v;
                }
        }

        if ((f = setcolorbarlabel_focus(w)) > 0)
        {
                /* save current focus and set to colorbar */
                pf = getfocus(w);

                /* default label - z label or z units */
                ylab = getzlabel(w);

                focus(w, f);

                if (val)
                {
                        if (strlen(lab) > 0)
                        {
                                /* user defined label */
                                ylabel(w, lab);
                        }
                        else
                        {
                                /* clear label - reset to units */
                                clearylabel(w);
                                ylabel(ylab);
                        }

                        /* turn on label */
                        scales(w, 14);
                }
                else
                {
                        /* shut off label */
                        scales(w, 10);
                }

                /* restore focus */
                focus(w, pf);
        }
}


/* find color bar focus */
setcolorbarlabel_focus(w)
{
        local n, i, pf, f = 0;

        if ((n = numfocus(w)) > 1)
        {
                pf = getfocus(w);
                focus(w, 1);

                loop (i = 2..n)
                {
                        if (getcomment(w, i) == "Color Legend")
                        {
                                /* found it */
                                f = i;
                                break;
                        }
                }

                focus(w, pf);
        }

        return(f);
}