Pmw/Pmw_1_2/doc/dynamicloader.html

   1
   2     <html>
   3     <head>
   4     <meta name="description" content="Pmw - a toolkit for building high-level compound widgets in Python">
   5     <meta name="content" content="python, megawidget, mega widget, compound widget, gui, tkinter">
   6     <title>Dynamic loader</title>
   7     </head>
   8
   9     <body bgcolor="#ffffff" text="#000000" link="#0000ee"
  10         vlink="551a8b" alink="ff0000">
  11
  12     <h1 ALIGN="CENTER">Dynamic loader</h1>
  13
  14 <p>
  15     There are two aspects of Pmw, unrelated to megawidgets, that
  16     require special attention.  Firstly, Pmw is made up of many
  17     sub-modules, potentially making access to its various classes and
  18     functions cumbersome for the user.  Secondly, Pmw is regularly
  19     being modified and added to, thus requiring the release of new
  20     versions.  Therefore, techniques for making access to the
  21     sub-modules easy and efficient and for dealing with the different
  22     versions have been developed.  These techniques are incorporated
  23     into the dynamic loader which Pmw creates when it is first
  24     imported.</p>
  25
  26 <p>    The first purpose of the loader is to give access to all Pmw classes
  27     and functions through a single entry point, the <strong>Pmw.</strong> prefix.  For
  28     example, to access the ComboBox class (which resides in one of the
  29     sub-modules of Pmw), you just have to use <code>Pmw.ComboBox</code>.  Without
  30     the loader, this would be a more complicated reference, such as,
  31     hypothetically, <code>Pmw.PmwComboBox.ComboBox</code>.</p>
  32
  33 <p>    The second purpose of the loader is to delay the importing of the
  34     sub-modules until they are needed.  This improves the startup time
  35     of applications which only use a few Pmw megawidgets.  It also
  36     allows more megawidgets to be added to the library without slowing
  37     down applications which do not use them.</p>
  38
  39 <p>    The third purpose of the loader is to allow a script using Pmw to
  40     specify which version of Pmw it requires.  This allows an
  41     application to continue working correctly even after newer releases
  42     of Pmw have been made which are not compatible with the version
  43     expected by the application.  Several versions of Pmw can be
  44     installed at once, with the actual version used being specified by
  45     each application.  In addition, the loader can be configured to
  46     search in one or more alpha versions of Pmw.  These versions may
  47     contain new megawidgets, or new versions of existing megawidgets,
  48     that are currently not in the base releases.</p>
  49
  50 <p>    Several functions are available to set and query the version of
  51     Pmw being used.  These are <code>Pmw.setversion()</code> and
  52     <code>Pmw.setalphaversions()</code> which specify the version and alpha
  53     versions (if any) to use for this session; <code>Pmw.version()</code> which
  54     returns the version(s) being used by this session; and
  55     <code>Pmw.installedversions()</code> which returns the version(s) of Pmw
  56     currently installed.  These are described in the
  57     <a href="PmwFunctions.html">Pmw functions reference manual</a>.</p>
  58
  59 <p>    When Pmw is first imported, an instance of PmwLoader is created
  60     and placed into <code>sys.modules['Pmw']</code>.  From that point on, any
  61     reference to attributes of the Pmw 'module' is handled by the
  62     loader.  The real Pmw package is stored in <code>sys.modules['_Pmw']</code>.</p>
  63
  64 <p>    The loader searches the Pmw package base directory for
  65     sub-directories with the prefixes <code>Pmw_</code> and <code>Alpha_</code>, which
  66     contain Pmw base releases and alpha releases.  The version numbers
  67     are given by the part of the directory name following the prefix.
  68     These versions are available for use and are those returned by the
  69     <code>Pmw.installedversions</code> function.  The initial version is set to
  70     the base release with the greatest version number.  When the first
  71     reference to a Pmw class or function is made, the loader reads the
  72     files named <strong>Pmw.def</strong> in the current base version directory and
  73     also in the alpha directories (if any).  These files list all the
  74     classes and functions supported by the version.  Pmw attributes
  75     are first searched for in the alpha directories and then in the
  76     base version directory.  The first directory which supports the
  77     reference is used.  In this way, alpha versions override base
  78     versions.</p>
  79
  80 <p>    The directory <code>Alpha_99_9_example</code> contains a simple example of
  81     how to structure an alpha version.  The following code can be used
  82     to request that the alpha version be used and then creates an
  83     instance of a new megawidget defined in the alpha version.</p>
  84
  85 <dl><dd><pre> import Pmw
  86  Pmw.setalphaversions('99.9.example')
  87
  88  # Create a standard message dialog using the base Pmw version.
  89  ordinary = Pmw.MessageDialog(
  90      message_text = 'Ordinary\nPmw Dialog')
  91
  92  # Create an example dialog using the alpha Pmw version.
  93  alpha = Pmw.AlphaExample()</pre></dd></dl>
  94
  95 <p>    <strong>Freezing Pmw</strong></p>
  96
  97 <p>    Since the dynamic loader requires that Pmw be installed at run
  98     time, it can not be used when <em>freezing</em> Pmw.  In this case, a
  99     single module containing all Pmw code is required, which can then
 100     be frozen with the rest of the application's modules.  The
 101     <code>bundlepmw.py</code> script in the Pmw <code>bin</code> directory can be used to
 102     create such a file.  This script concatenates (almost) all Pmw
 103     megawidget files into a single file, <code>Pmw.py</code>, which it writes to
 104     the current directory.  The script is called like this:</p>
 105
 106 <dl><dd><pre> bundlepmw.py [-noblt] [-nocolor] /path/to/Pmw/Pmw_X_X_X/lib</pre></dd></dl>
 107
 108 <p>    The last argument should be the path to the <code>lib</code> directory of the
 109     required version of Pmw.  By default, the <code>Pmw.py</code> file imports
 110     the <code>PmwBlt</code> and <code>PmwColor</code> modules and so, to freeze an
 111     application using Pmw, you will need to copy the files <code>PmwBlt.py</code>
 112     and <code>PmwColor.py</code> to the application directory before freezing.</p>
 113
 114 <p>    If you are sure that your application does not use any of the
 115     <code>Pmw.Blt</code> or <code>Pmw.Color</code> functions, you can use the <code>-noblt</code> or
 116     <code>-nocolor</code> options.  In this case <code>Pmw.py</code> will be modified so
 117     that it does not import these module(s) and so will not need to be
 118     included when freezing the application.</p>
 119
 120 <p>    If your application only uses a few Pmw megawidgets, you can
 121     remove the references to the usused ones in the <code>files</code> list in
 122     the <code>bundlepmw.py</code> code.  To make the change, take a copy of the
 123     script and modify it.  This will make the <code>Pmw.py</code> file smaller.
 124     However, be sure that you do not delete megawidgets that are
 125     components or base classes of megawidgets that you use.</p>
 126
 127 <p></p>
 128
 129
 130
 131     <center><P ALIGN="CENTER">
 132     <IMG SRC = blue_line.gif ALT = "" WIDTH=320 HEIGHT=5>
 133     </p></center>
 134
 135
 136     <font size=-1>
 137     <center><P ALIGN="CENTER">
 138     Pmw 1.2 -
 139      5 Aug 2003
 140      - <a href="index.html">Home</a>
 141
 142     </p></center>
 143     </font>
 144
 145     </body>
 146     </html>
 147