=================================
``grail.images`` Module
=================================
.. include:: ..\version.h
.. include:: ..\Library_Reference\lib-reference.h

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

--------
Overview
--------

The images module provides you with the ability to get standard images
that can be used in your dialogs. The list of available images for this
version of MineSight(r) Grail are defined in the Images_ section below.

---------
Functions
---------

:df:`build_cache_file([path])`
    Generates a file that contains a dictionary called :d:`IMAGE_CACHE` where
    the key is an :a:`imageName` from the :file:`grail\\_images` and the
    values are base 64 encoded strings.
    
    The :a:`path` is optional and currently defaults to the
    :file:`grail\\_images_cache.py`. This file is used by this module.

:df:`get_desc(imageName)`
    Returns the description of the :a:`imageName` if a description is
    defined. If no description is defined, this returns a blank string.

:df:`get_path(imageName)`
    Returns the full fle path to the :a:`imageName`. For example if the
    :a:`imageName` was :d:`OPENx16.gif`, this would return something like,
    :file:`c:\\winexe\\grail\\_image_files\\OPENx16.gif`.
    
    .. Note::
    
       That if having a base 64 encoded version of the :a:`imageName` is
       your goal, then the :f:`get_str` function has the potential to be
       more efficient since we will have already pre-loaded a set of
       :a:`imageName` strings.
    
:df:`get_str(imageName)`
    Returns a base 64 encoded string that represents the :a:`imageName`.
    The library will have a pre-load version of the :a:`imageName` . This means
    that calls to :f:`get_str` will be more efficient than loading
    from the file via :f:`get_path`.    
    
:df:`get_TkPhotoImage(imageName, *args, **kws)`
    Convience function that returns a :c:`Tkinter.PhotoImage` class based
    on the supplied :a:`imageName`. This can be attached to a Tkinter
    widget to generate an icon. For example, the following code snippet
    will create a button with the `OPENx16.gif`_ image.
    
    .. Python::
    
        import Tkinter
        from grail import images

        root = Tkinter.Tk()
        graphic = images.get_TkPhotoImage("OPENx16.gif")
        button = Tkinter.Button(root, image=graphic)
        button.pack()
        root.mainloop()

    If you have **not** started ``Tkinter`` before calling this function, you
    will generate a :e:`RuntimeError`. The Tkinter "root" needs to be defined
    prior to calling this function.

    .. Note:: 

       This function, and Tkinter, should only be used with the GIF images.


        
:df:`list_image_names([include, exclude])`
    Returns a list of all valid :a:`imageNames`. You are able to apply a filter
    by creating a pattern list in the :a:`include` and :a:`exclude`
    lists. The default values for the include and exclude lists are
    as follows,
    
    ============ ==============
    List Name    Value
    ============ ==============
    :a:`include` :d:`["*.*"]`
    :a:`exclude` :d:`["*.txt"]`
    ============ ==============
    
    you can use the :d:`IMAGE_INCLUDE_LIST` list to get a default listing
    of images to include.
   
------
Images
------

The images are accessible by their file names. Each of the available
images are defined below.

.. The following file is generated by the build script based on the
.. contents of the grail\_image_files directory.

.. include:: image-listing.h