[OpenSPARC-T2-SAM] / sam-t2 / devtools / v8plus / lib / python2.4 / site-packages / Pmw / Pmw_1_2 / doc / dynamicloader.html


    <html>
    <head>
    <meta name="description" content="Pmw - a toolkit for building high-level compound widgets in Python">
    <meta name="content" content="python, megawidget, mega widget, compound widget, gui, tkinter">
    <title>Dynamic loader</title>
    </head>

    <body bgcolor="#ffffff" text="#000000" link="#0000ee"
	vlink="551a8b" alink="ff0000">

    <h1 ALIGN="CENTER">Dynamic loader</h1>
    
<p>
    There are two aspects of Pmw, unrelated to megawidgets, that
    require special attention.  Firstly, Pmw is made up of many
    sub-modules, potentially making access to its various classes and
    functions cumbersome for the user.  Secondly, Pmw is regularly
    being modified and added to, thus requiring the release of new
    versions.  Therefore, techniques for making access to the
    sub-modules easy and efficient and for dealing with the different
    versions have been developed.  These techniques are incorporated
    into the dynamic loader which Pmw creates when it is first
    imported.</p>

<p>    The first purpose of the loader is to give access to all Pmw classes
    and functions through a single entry point, the <strong>Pmw.</strong> prefix.  For
    example, to access the ComboBox class (which resides in one of the
    sub-modules of Pmw), you just have to use <code>Pmw.ComboBox</code>.  Without
    the loader, this would be a more complicated reference, such as,
    hypothetically, <code>Pmw.PmwComboBox.ComboBox</code>.</p>

<p>    The second purpose of the loader is to delay the importing of the
    sub-modules until they are needed.  This improves the startup time
    of applications which only use a few Pmw megawidgets.  It also
    allows more megawidgets to be added to the library without slowing
    down applications which do not use them.</p>

<p>    The third purpose of the loader is to allow a script using Pmw to
    specify which version of Pmw it requires.  This allows an
    application to continue working correctly even after newer releases
    of Pmw have been made which are not compatible with the version
    expected by the application.  Several versions of Pmw can be
    installed at once, with the actual version used being specified by
    each application.  In addition, the loader can be configured to
    search in one or more alpha versions of Pmw.  These versions may
    contain new megawidgets, or new versions of existing megawidgets,
    that are currently not in the base releases.</p>

<p>    Several functions are available to set and query the version of
    Pmw being used.  These are <code>Pmw.setversion()</code> and
    <code>Pmw.setalphaversions()</code> which specify the version and alpha
    versions (if any) to use for this session; <code>Pmw.version()</code> which
    returns the version(s) being used by this session; and
    <code>Pmw.installedversions()</code> which returns the version(s) of Pmw
    currently installed.  These are described in the
    <a href="PmwFunctions.html">Pmw functions reference manual</a>.</p>

<p>    When Pmw is first imported, an instance of PmwLoader is created
    and placed into <code>sys.modules['Pmw']</code>.  From that point on, any
    reference to attributes of the Pmw 'module' is handled by the
    loader.  The real Pmw package is stored in <code>sys.modules['_Pmw']</code>.</p>

<p>    The loader searches the Pmw package base directory for
    sub-directories with the prefixes <code>Pmw_</code> and <code>Alpha_</code>, which
    contain Pmw base releases and alpha releases.  The version numbers
    are given by the part of the directory name following the prefix. 
    These versions are available for use and are those returned by the
    <code>Pmw.installedversions</code> function.  The initial version is set to
    the base release with the greatest version number.  When the first
    reference to a Pmw class or function is made, the loader reads the
    files named <strong>Pmw.def</strong> in the current base version directory and
    also in the alpha directories (if any).  These files list all the
    classes and functions supported by the version.  Pmw attributes
    are first searched for in the alpha directories and then in the
    base version directory.  The first directory which supports the
    reference is used.  In this way, alpha versions override base
    versions.</p>

<p>    The directory <code>Alpha_99_9_example</code> contains a simple example of
    how to structure an alpha version.  The following code can be used
    to request that the alpha version be used and then creates an
    instance of a new megawidget defined in the alpha version.</p>

<dl><dd><pre> import Pmw
 Pmw.setalphaversions('99.9.example')

 # Create a standard message dialog using the base Pmw version.
 ordinary = Pmw.MessageDialog(
     message_text = 'Ordinary\nPmw Dialog')

 # Create an example dialog using the alpha Pmw version.
 alpha = Pmw.AlphaExample()</pre></dd></dl>

<p>    <strong>Freezing Pmw</strong></p>

<p>    Since the dynamic loader requires that Pmw be installed at run
    time, it can not be used when <em>freezing</em> Pmw.  In this case, a
    single module containing all Pmw code is required, which can then
    be frozen with the rest of the application's modules.  The
    <code>bundlepmw.py</code> script in the Pmw <code>bin</code> directory can be used to
    create such a file.  This script concatenates (almost) all Pmw
    megawidget files into a single file, <code>Pmw.py</code>, which it writes to
    the current directory.  The script is called like this:</p>

<dl><dd><pre> bundlepmw.py [-noblt] [-nocolor] /path/to/Pmw/Pmw_X_X_X/lib</pre></dd></dl>

<p>    The last argument should be the path to the <code>lib</code> directory of the
    required version of Pmw.  By default, the <code>Pmw.py</code> file imports
    the <code>PmwBlt</code> and <code>PmwColor</code> modules and so, to freeze an
    application using Pmw, you will need to copy the files <code>PmwBlt.py</code>
    and <code>PmwColor.py</code> to the application directory before freezing.</p>

<p>    If you are sure that your application does not use any of the
    <code>Pmw.Blt</code> or <code>Pmw.Color</code> functions, you can use the <code>-noblt</code> or
    <code>-nocolor</code> options.  In this case <code>Pmw.py</code> will be modified so
    that it does not import these module(s) and so will not need to be
    included when freezing the application.</p>

<p>    If your application only uses a few Pmw megawidgets, you can
    remove the references to the usused ones in the <code>files</code> list in
    the <code>bundlepmw.py</code> code.  To make the change, take a copy of the
    script and modify it.  This will make the <code>Pmw.py</code> file smaller. 
    However, be sure that you do not delete megawidgets that are
    components or base classes of megawidgets that you use.</p>

<p></p>


    <center><P ALIGN="CENTER">
    <IMG SRC = blue_line.gif ALT = "" WIDTH=320 HEIGHT=5>
    </p></center>
    

    <font size=-1>
    <center><P ALIGN="CENTER">
    Pmw 1.2 -
     5 Aug 2003
     - <a href="index.html">Home</a>
    
    </p></center>
    </font>

    </body>
    </html>
Commit	Line	Data
920dae64 AT	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