/*****************************************************************************
*                                                                            *
*   SERXLABEL.SPL   Copyright (C) 2015 DSP Development Corporation           *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:         Randy Race                                               *
*                                                                            *
*   Synopsis:       Labels the X axis with the series name and units         *
*                                                                            *
*   Revisions:      27 Apr 2015  RRR  Creation                               *
*                                                                            *
*****************************************************************************/


#if @HELP_SERXLABEL

    SERXLABEL

    Purpose:  Labels the X axis with the series name and units.

    Syntax:   SERXLABEL(win1, win2, ..., winN, nameonly, fullname, fmt)

                     winN - Optional. Zero or more windows. Defaults to the
                            current window.

                 nameonly - Optional. An integer, display name only.

                              0: Display both name and units (default).
      
                              1: Display name only.
    
                 fullname - Optional. An integer, display full dataset and
                            series name.

                              0: Display series name (default).
      
                              1: Display full Dataset series name.

                      fmt - Optional. An integer, the units grouping format.

                              0: Enclose the units in ()'s (default).
  
                              1: Enclose the units in []'s.

    Returns:  Nothing, the X axis is labeled with the series name and
              (optionally) units.

    Example:
              W1: RUN1.1.ANALOG1;serxlabel

              Labels the X axis with the series name and units.

    Remarks:
              If the series in the window is a derived series, the
              series name is defaulted.

              See COMXLABEL to label the X axis with the series comment
              and units.

    See Also:
              Comlabel
              Comxlabel
              Comxylabel
              Comylabel
              Getlabel
              Label
              Serylabel
#endif


static wnum = -1;


/* label X axis with series name and units */
serxlabel(w, seronly, fullname, fmt)
{
        local sname, j, foc, fmtstr, pmode;

        (w, seronly, fullname, fmt) = serxlabel_parse_args(w, seronly, fullname, fmt);

        /* force window */
        w = castwindow(w);

        foc  = getfocus(w);
        wnum = getwnum(w);

        /* disable plotting */
        pmode = plotmode(w, 0);

        /* label each overlay */
        loop (j = 1..numfocus())
        {
                focus(w, j);

                /* series name */
                sname = fullname ? getseriesname(j) : getshortname(j);

                /* add units unless name only */
                fmtstr = "%s " + comlabfmt(fmt);
                sname  = seronly ? sname : sprintf(fmtstr, sname, comunit(gethunits(w, j)));

                /* label */
                xlabel(w, sname);

                /* scales */
                xlabel_set_scales(w, j);
        }

        focus(w, foc);
        wnum = -1;

        if (pmode)
        {
                /* plot it */
                plotmode(w, 1, 1);
        }
}


/* error handler - restores plot mode */        
serxlabel_error(errnum, errmes)
{
        if (wnum != -1)
        {
                plotmode(castwindow(wnum), 1, 1);
                wnum = -1;
        }

        error(errmes);
}


/* parse args */
serxlabel_parse_args(w, seronly, fullname, fmt)
{
        local ww, ss, fn, ft;

        ww = ss = fn = ft = {};

        if (argc == 4)
        {
                ww = refwindow(w);
                ss = seronly;
                fn = fullname;
                ft = fmt;
        }

        if (argc == 3)
        {
                if (iswindow(w))
                {
                        ww = refwindow(w);
                        ss = seronly;
                        fn = fullname;
                }
                else
                {
                        ss = w;
                        fn = seronly;
                        ft = fullname;
                }
        }

        if (argc == 2)
        {
                if (iswindow(w))
                {
                        ww = refwindow(w);
                        ss = seronly;
                }
                else
                {
                        ss = w;
                        fn = seronly;
                        ww = {};
                }
        }
        else if (argc == 1)
        {
                if (iswindow(w))
                {
                        ww = refwindow(w);
                }
                else
                {
                        ss = w;
                        ww = {};
                }
        }
        else
        {
                ww = refwindow(w0);
        }


        if (not(iswindow(ww)))
        {
                ww = refwindow(w0);
        }

        if (isempty(ss))
        {
                ss = 0;
        }

        if (isempty(fn))
        {
                fn = 0;
        }

        if (isempty(ft))
        {
                ft = 0;
        }

        return(getwnum(ww), ss, fn, ft);
}