/*****************************************************************************
*                                                                            *
*   SETONPLOTCALC.SPL Copyright (C) 2024 DSP Development Corporation         *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:      Randy Race                                                  *
*                                                                            *
*   Synopsis:    Sets window propagation based on series plotting.           *
*                                                                            *
*   Revisions:   29 Apr 2024  RRR  Creation                                  *
*                                                                            *
*****************************************************************************/


#if @HELP_SETONPLOTCALC

    SETONPLOTCALC

    Purpose: Sets a parent window to update dependent windows whenever the
             parent window plots.

    Syntax:  SETONPLOTCALC(win, on_off)

              win    - Optional. Zero or more windows, the parent windows.
                       Defaults to current window.

              on_off - An integer, the setonplotcalc mode.
              
                         0: setonplotcalc OFF (default)

                         1: setonplotcalc ON

    Returns: A positive integer if SETONPLOTCALC is active for the window,
             else 0.

    Example:
             setonplotcalc(w1, 1);

             W1: gnorm(10000, 1/10000)
             W2: integ(w1)

             The onplotcalc mode is activated for W1. 

             W1 contains 10000 samples of normally distributed random noise.

             W2 integrates the data in W1.

             Each time W1 plots due to scrolling, mousing or coordinate
             manipulation, W2 updates by computing the integration of
             the time segment displayed in W1. For example:

             setx(w1, 0.1, 0.2)

             W2 automatically updates and computes the integral of the segment
             in W1 between 0.1 and 0.2 seconds.

    Example:
             setonplotcalc(w1, 1);

             W1: gnorm(10000, 1/10000);
             W2: integ(w1);
             W3: spectrum(w2);

             loglog(w3);


             The onplotcalc mode is activated for W1.

             W1 contains 10000 samples of normally distributed random noise.

             W2 integrates the data in W1.

             W3 computes the frequency domain spectrum of W2 displayed with
             log-log scales.

             Each time W1 plots due to scrolling, mousing or coordinate
             manipulation, W2 updates by computing the integration of
             the time segment displayed in W1. W3 automatically
             updates whenever W2 changes. Thus, whenever W1 plots, the
             integral of the displayed segment is computed and the
             spectrum of the integral segment is computed.

    Remarks:
             A parent window normally updates child (i.e. dependent)
             windows any time the data in the parent window changes. 
             SETONPLOTCALC causes the parent window to trigger updates of
             its child windows each time the parent window plots. 
             Additionally, child windows are presented only with the
             portion of the parent that is currently displayed. This
             design allows for automatic processing of dependent windows
             by scrolling through the parent window.

             The header of a window with SETONPLOTCALC set displays in a
             different color.

             SETONPLOTCALC with no ON_OFF argument returns a positive value
             if the current or input window has SETONPLOTCALC set, or 0 if
             SETONPLOTCALC is not set.

    See Also:
             Ascale
             Calc
             Yscale
#endif