=================================
``grail.ms3d.mssys`` Module
=================================
.. include:: ../../version.h
.. include:: ref.h



.. contents:: Table of Contents
   :backlinks: top

Overview
========

Provides system level access to the MineSightŪ-3D application. 

Of particular interest is the use of the :d:`stdout` objects provided in
this module that allow you to write data to the message window.

Using Python's print in Embedded Grail
======================================

Python's :f:`print` keyword provides a convenient method for outputting
strings of text to the user. With MineSightŪ Grail Embedded you will be
able output strings of text via the message window from within a Python
script.

Starting with MineSightŪ Grail v3.60-02, all python :f:`print`
statements will be automatically redirected to the MineSightŪ 3-D
Message window when MineSightŪ Grail is executed in an Embedded context.
  
You can re-instate the :d:`sys.stdout` object to its original value at
any time with the following line,

.. Python::

 sys.stdout = sys.__stdout__

Functions
=========

:df:`get_window_handle()`
   *Experimental*. This returns the Microsoft Windows Handle (HWND) for
   the MineSightŪ-3D desktop window.

:df:`redirect_error_to_message_win()`
   If you want to redirect error messages to the message window, call
   this function and all future calls to `sys.stderr` will appear as an
   error within the message window.

:df:`clear_message_win()`
   Will clear the contents of the message window.

Data
====

:d:`stdout`

  A file-like object that provides :f:`write()` to perform standard
  output writes. For example the following line will print a string out
  to the message window,

  .. Python::

    mssys.stdout.write("Hello World!")

  A string will be written out to the message window whenever each time
  this call is made.

  Changes made to this object include,

    - Starting with MineSightŪ Grail v3.60-03 this will be equivalent
      to :d:`sys.stdout`, and the python :f:`print` statement. So the
      following statements are equivalent within an Embedded Script,

       .. Python::

           print "Hello World!"
           sys.stdout.write("Hello World!")
           mssys.stdout.write("Hello World!")

    - Starting with MineSightŪ Grail v4.50-00 the :f:`flush` function
      will no longer have any effect.

:d:`stderr`

  A file-like object that provides :f:`write` and :f:`flush` to perform
  standard error output writes. For example the following line will
  print an error messages out to the message window,

  .. Python::

    mssys.stderr.write("This is an error message!")


  Changes made to this object include,

    - Starting with MineSightŪ Grail v3.60-03 this will be equivalent to
      :d:`sys.stderr` object. So the following statements are equivalent
      within an Embedded Script,

       .. Python::

           sys.stderr.write("This is an error message!")
           mssys.stderr.write("This is an error message!")

    - Starting with MineSightŪ Grail v4.50-00 the :f:`flush` function
      will no longer have any effect.

:d:`stdwarn`

  A file-like object that provides a :f:`write` function to perform
  standard warning output writes. For example the following line will
  print a warning message to the message window,

  .. Python::

     mssys.stdwarn.write("This is a warning message\n")

:d:`IS_DEBUG`
  Is :d:`True` if the MineSightŪ Grail Embedded extensions were compiled in
  debug mode. For internal usage only.
  
:d:`VERSION_INFO`
  A 4 integer long tuple containing the full version number of MS3D.
  
:d:`VERSION`
  A version string for MS3D.