/*****************************************************************************
*                                                                            *
*   GETCOLORBARLABEL.SPL  Copyright (C) 2013 DSP Development Corporation     *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:         Randy Race                                               *
*                                                                            *
*   Synopsis:       Returns the label of a colorbar                          *
*                                                                            *
*   Revisions:      21 Oct 2013  RRR  Creation                               *
*                                                                            *
*****************************************************************************/


#if @HELP_GETCOLORBARLABEL

    GETCOLORBARLABEL

    Purpose: Returns the label of a vertical colorbar.

    Syntax:  GETCOLORBARLABEL(win)

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

    Returns: A string, the label of the colorbar. Returns an empty string
             if the window does not contain a colorbar.

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

             clabel = getcolorbarlabel(w1)

             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. The variable "clabel"
             contains the string "Volts".

    Remarks:
             GETCOLORBARLABEL returns an empty (zero length) string if the
             target window does not contain a colorbar.

    See Also:
             Colorbar
             Focus
             Getylabel
             Setcolorbarlabel
#endif


/* returns colorbar label */
getcolorbarlabel(w)
{
        local f, pf, l = "";

        if (argc < 1)
        {
                w = refwindow(w0);
        }

        if (not(iswindow(w))) error("getcolorbarlabel - window required");        

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

                focus(w, f);

                l = getylabel(w);

                focus(w, pf);
        }

        return(l);
}


/* find color bar focus */
getcolorbarlabel_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);
}