RAMSES	Systems Ecology
Start         Modules:   A-Z   Function   Layer        QuickRefs:   DM   AuxLib   AuxLibE   SciLib   EasyMW   MW   ISIS   RMSLib

DEFINITION MODULE MapViewer;

  (*******************************************************************

    Module  MapViewer     (Version 1.1)

      Copyright (c) 1999-2006 by Andreas Fischlin and ETH Zurich.

    Purpose   Manages a window to display regions which are
              defined and output by ArcInfo (GIS) data bases.
              A mini GIS functionality available within RAMSES.

    Remarks   A data base file as generated by ArcInfo needs
              some minor adjustments at the begin of each
              file to conform fully to the format required
              by this module.  The syntax is described exactly
              in module RegArcHdlr from RAMSES ScienceLib.


    Programming

      o Design
        Andreas Fischlin          16/06/1999

      o Implementation
        Andreas Fischlin          16/06/1999


    ETH Zurich
    Systems Ecology
    CHN E 35.1
    Universitaetstrasse 16
    8092 Zurich
    SWITZERLAND

    URLs:
        <mailto:RAMSES@env.ethz.ch>
        <http://www.sysecol.ethz.ch>
        <http://www.sysecol.ethz.ch/SimSoftware/RAMSES>


    Last revision of definition:  07/07/1999  AF

  *******************************************************************)


  (******************************************)
  (*#####   Management of Map Viewer   #####*)
  (******************************************)

  (*=====   Usage   =====*)

  PROCEDURE MakeMapViewer;
  PROCEDURE MapViewerExists(): BOOLEAN;
  PROCEDURE DiscardMapViewer;


  (*

     A simple program module allows you to work with
     maps as exported by ARC/INFO and view them using the
     MapViewer package:

        MODULE ViewMaps;

          (* DM core *)
          FROM DMMaster IMPORT RunDialogMachine;

          (* ScienceLib *)
          FROM MapViewer IMPORT MakeMapViewer;
          FROM RegArcHdlr IMPORT UseRegionArcHandler;

        BEGIN (* ViewMaps *)
          UseRegionArcHandler;
          MakeMapViewer;
          RunDialogMachine;
        END ViewMaps.

     The result is a fully functional, interactive application
     featuring a menu which allows you load and view regions and
     arcs from disk (ASCII map files written in ARC/INFO format)
     and view the data in a window.

  *)


  (*=====   Customization   =====*)

  PROCEDURE EditPreferences;
  PROCEDURE EditMenuAppearance;
  PROCEDURE ResetToFactorySettings;

  PROCEDURE DefineMenuAppearance(      title, aliasChars: ARRAY OF CHAR;     sepEditMenu: BOOLEAN);
  PROCEDURE RetrieveMenuAppearance(VAR title, aliasChars: ARRAY OF CHAR; VAR sepEditMenu: BOOLEAN);
    (*
      For aliasChars use the sequence of menu commands (this varies
      depending on sepEditMenu).  Use " " (blank) for a command
      without an alias char.  Argument sepEditMenu specifies wether
      the edit commands (copy, cut, and paste, see routines CopyMap,
      CutMap, PasteMap) are to be offered separately via the standard
      edit menu (see module DMClipboard) or wether they will be
      offered as part of the region viewer's menu.  Default
      sepEditMenu = FALSE. The use of option sepEditMenu = FALSE
      allows for using MapViewer as an extension of an application
      which already offers the Edit menu an uses it for its own
      purposes (e.g. ModelWorks' standard user interface).  On the
      other hand, option sepEditMenu = TRUE allows for using
      MapViewer in conjunction with the standard menu Edit.
      MapViewer will then install a standard Edit menu separately
      via module DMClipboard.  Implementation restriction: If you
      change the title of the menu while it's already in use, it will
      be removed and reappear at the end of the menu bar.  Similarily
      a change of the option sepEditMenu may move the relative
      position of the of the region viewer's menu and the Edit menu.
      Note: sepEditMenu is stored as a mode and treated also as a
      preference and will influence the menu appearance from one
      execution of the map viewer to the next one.
    *)
  PROCEDURE SetPreferences(    omitLegend, drawRegNames, transpNames,
                               preserveProp, sepEditMenu, globalAbout: BOOLEAN);
  PROCEDURE GetPreferences(VAR omitLegend, drawRegNames, transpNames,
                               preserveProp, sepEditMenu, globalAbout: BOOLEAN);
    (*
      - omitLegend
          Draw maps without a legend listing any object such as regions or
          arcs to leave more space for the actual map within the Viewer's
          window.  Factory setting omitLegend = FALSE.

      - drawRegNames
          Regions are drawn with their names near the center.
          Factory setting drawRegNames = TRUE.

      - transpNames
          Any names are drawn transparently, i.e. without a white background.
          Factory setting transpNames = FALSE.

      - preserveProp
          Preserve proportions of map while drawing it in the map viewer's
          window. Factory setting preserveProp = FALSE.

      - sepEditMenu
          Standard edit commands such as copy, cut, paste etc.  are used
          in a separate menu entitled "Edit" (see also routines
          EditMenuAppearance, DefineMenuAppearance, and
          RetrieveMenuAppearance).
          Factory setting sepEditMenu = FALSE.

      - globalAbout
          Add a menu command in the the map viewer's menu which allows
          to display a package about command.
          Factory setting globalAbout = TRUE.
    *)


  (*=====   Error Retrieval   =====*)

  PROCEDURE GetLastMVResCode(): INTEGER;
    (*
      Returns the result code of last operation performed by
      the map viewer package.  Note, this routine returns
      DMLanguage.allOk if no error was encountered.  It returns
      also result codes for operations by the high level
      handler modules such as RegArcHdlr.
    *)


  (*************************************)
  (*#####   Map Viewer's Window   #####*)
  (*************************************)

  (*=====   Management of map window   =====*)

  PROCEDURE ShowMapWindow;
  PROCEDURE PlaceMapWindow(x,y,w,h: INTEGER; forceOnTop: BOOLEAN);
  PROCEDURE GetMapWindowPlace(VAR x,y,w,h: INTEGER; VAR isOpen,isOnTop: BOOLEAN);
  PROCEDURE HideMapWindow;

  (*=====   Drawing in map window   =====*)

  PROCEDURE SelectMapWindowForOutput;
  PROCEDURE DrawMap;
  PROCEDURE ClearMap;

  (*=====   Clipboard Support   =====*)

  PROCEDURE CopyMap;
  PROCEDURE CutMap;
  PROCEDURE PasteMap;

  (*=====   Scaling & Draw Region   =====*)

  PROCEDURE SetDrawRegion(xmin,xmax,ymin,ymax: REAL);
    (*
      Allows to determine the draw region as given by the
      coordinates xmin, xmax, ymin, ymax.  The draw region is
      used to scale any region for drawing.  If you use only
      the autoscaling mechanism of this module, there is no
      need to set the draw region, since it is automatically
      set equal to the base region (see e.g. routine
      DrawRegions from RegArcHdlr etc.).
    *)
  PROCEDURE GetDrawRegion(VAR xmin,xmax,ymin,ymax: REAL);
  PROCEDURE ForgetDrawRegion;
    (*
      Forgets the current definition of draw region.  Any
      subsequent drawing done by module RegArcHdlr etc. will
      cause an auto scaling; e.g. the base region will be used
      as current drawing region (see module RegArcHdlr).
    *)

END MapViewer.