#!/usr/bin/python -tt
#=======================================================================
#                        General Documentation

"""Single-procedure module.

   See procedure docstring for description.
"""

#-----------------------------------------------------------------------
#                       Additional Documentation
#
# RCS Revision Code:
#   $Id: window.py,v 1.2 2004/02/21 02:21:15 jlin Exp $
#
# Modification History:
# - 20 Jan 2004:  Original by Johnny Lin, Computation Institute,
#   University of Chicago.  Passed minimally passably reasonable 
#   tests.
#
# Notes:
# - Written for Python 2.2.
# - For dependencies see the import statements in the file.
#
# Copyright (c) 2004 by Johnny Lin.  For licensing, distribution 
# conditions, contact information, and additional documentation see
# the URL http://www.johnny-lin.com/py_pkgs/IaGraph/Doc/.
#=======================================================================




#---------------- Module General Import and Declarations ---------------

#- Set package version number:

import IaGraph_version
__version__ = IaGraph_version.version
del IaGraph_version




#------------------------------- Function ------------------------------

def window( nwindow ):
    """Set the active canvas to a specified window number.

    Use this routine if you want to plot onto another window.  You
    can also use this routine to make a previously defined canvas
    active so you can overplot to it or create a new plot in its
    window.

    Method Arguments:
    * nwindow:  The window number specifying the canvas to make the
      active canvas.  Integer.

    Output:
    * The active canvas is set to the window number given in argument
      nwindow.  The system variable specifying the window number (i.e.
      active_canvas_num) is set to nwindow.
    * If there is a previously defined active canvas it is moved to the 
      inactive canvases dictionary (system variable inactive_canvases).
      It remains displayed in its existing window.
    * The names of the base graphics method and templates for the 
      active canvas and inactive canvases are stored in corresponding
      system variables suffixed by base_gm and base_tpl.
    * If the canvas specified by nwindow is already defined, that 
      canvas is made the active canvas; if not the active canvas is 
      set to an empty list (and the base graphics method and template
      names set to empty strings).

    Example:  A contour plot is made in window 0 (default), then a
    second contour plot is made in window 1.  Then a line plot is
    made in window 0, overwriting the original contour plot.  Window
    1 is left unchanged:
      import Numeric as N
      from contour import contour
      from plot import plot
      x = N.arange(29) * 10.0
      y = N.arange(21) * 10.0 - 100.0
      data = N.outerproduct( N.sin(y*N.pi/360.), N.cos((x-140.)*N.pi/360.))
      contour(data, x, y, title='Example 1')
      window(1)
      contour(data, x, y, title='Example 2')
      window(0)
      plot(N.arange(10), N.sin(N.arange(10)/N.pi), title='Example 3')
    """


    #- Import module, set system variable object, access key
    #  system variables as local variables:

    import IaGraph

    sysvar = IaGraph.Sysvar()
    active_canvas              = sysvar.__class__.active_canvas
    active_canvas_base_gm      = sysvar.__class__.active_canvas_base_gm
    active_canvas_base_tpl     = sysvar.__class__.active_canvas_base_tpl
    active_canvas_num          = sysvar.__class__.active_canvas_num
    inactive_canvases          = sysvar.__class__.inactive_canvases
    inactive_canvases_base_gm  = sysvar.__class__.inactive_canvases_base_gm
    inactive_canvases_base_tpl = sysvar.__class__.inactive_canvases_base_tpl


    #- If there is an existing non-null active canvas, first store 
    #  related variables in the inactive_canvases* dictionaries then.
    #  If the window specified by nwindow exists already, make that 
    #  (and related variables) the active canvas (and remove the
    #  entries from the inactive canvases dictionaries); if it doesn't 
    #  exist, the active canvas is an empty list and related variables
    #  are empty strings.  Set the active canvas number to nwindow:

    if active_canvas != []:
        inactive_canvases[active_canvas_num] = active_canvas
        inactive_canvases_base_gm[active_canvas_num] = active_canvas_base_gm
        inactive_canvases_base_tpl[active_canvas_num] = active_canvas_base_tpl

    if inactive_canvases.has_key(nwindow):
        active_canvas = inactive_canvases[nwindow]
        active_canvas_base_gm  = inactive_canvases_base_gm[nwindow]
        active_canvas_base_tpl = inactive_canvases_base_tpl[nwindow]
        del inactive_canvases[nwindow]
        del inactive_canvases_base_gm[nwindow]
        del inactive_canvases_base_tpl[nwindow]
    else:
        active_canvas = []
        active_canvas_base_gm = ''
        active_canvas_base_tpl = ''

    active_canvas_num = nwindow


    #- Replace system variables with local copies and delete local
    #  copies:

    sysvar.__class__.active_canvas              = active_canvas
    sysvar.__class__.active_canvas_base_gm      = active_canvas_base_gm
    sysvar.__class__.active_canvas_base_tpl     = active_canvas_base_tpl
    sysvar.__class__.active_canvas_num          = active_canvas_num
    sysvar.__class__.inactive_canvases          = inactive_canvases
    sysvar.__class__.inactive_canvases_base_gm  = inactive_canvases_base_gm
    sysvar.__class__.inactive_canvases_base_tpl = inactive_canvases_base_tpl

    del active_canvas
    del active_canvas_base_gm
    del active_canvas_base_tpl
    del active_canvas_num
    del inactive_canvases
    del inactive_canvases_base_gm
    del inactive_canvases_base_tpl




# ===== end file =====