[OpenSPARC-T2-DV] / tools / src / nas,5.n2.os.2 / lib / python / lib / python2.4 / site-packages / Pmw / Pmw_1_2 / doc / howtouse.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>How to use Pmw megawidgets</title>
    </head>

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

    <h1 ALIGN="CENTER">How to use Pmw megawidgets</h1>
    
<center><P ALIGN="CENTER">
<IMG SRC = blue_line.gif ALT = "" WIDTH=320 HEIGHT=5>
</p></center>

<dl>
<dt> <h3>Introduction</h3></dt><dd>
<p>
  This document briefly describes the features of the Pmw megawidget
  toolkit and how to use the megawidgets.  Using examples, it
  describes those features common to all Pmw megawidgets.  For a
  description of individual Pmw megawidgets see the
  <a href="refindex.html">reference manuals</a>.
  For complete information on general Pmw megawidget functionality see the
  <a href="MegaArchetype.html">Pmw.MegaArchetype reference manual</a>.
  For a lot more example code, run any of the files in the
  Pmw <code>demos</code> directory.

</p>

<p>
  A simple example of a megawidget is a counter.  This widget
  contains an entry field and two small arrow buttons.  Users may
  enter a value directly into the entry field or they may use the
  buttons to increment and decrement the value displayed without
  having to use the keyboard.  Having this and other megawidgets in
  your toolbox allows you to choose the best graphical interface for
  your application.

</p>
</dd>
<dt> <h3>Getting started</h3></dt><dd>

<b>Initialisation of Pmw</b>
<br>
<p>
  To run the examples in the tutorial, make sure that the
  Pmw <code>lib</code> directory is in <code>sys.path</code>.  You
  should be able to cut and paste the examples into an interactive
  python session, or you can copy them to a file and run the file with
  python.

</p>
<p>
  The following two lines should be entered before any of the
  examples.  These import and initialise Pmw.
  For more information on <code>Pmw.initialise()</code> see the
  <a href="PmwFunctions.html">Pmw functions reference manual</a>.

</p>

<dl>
<dd>
<pre>
import Pmw
root = Pmw.initialise()
</pre>
</dd>
</dl>

<p>
  If necessary, you can have more control over how Tkinter and Pmw are
  initialised by using this form of initialisation:

</p>

<dl>
<dd>
<pre>
import Tkinter
root = Tkinter.Tk()
import Pmw
Pmw.initialise(root)
</pre>
</dd>
</dl>

</dd>
<dt> <h3>Megawidget construction</h3></dt><dd>

<b>Creating a counter</b>
<br>
<p>
  Now that you have the formalities out of the way, you can create and
  pack a counter megawidget (see
  <a href="Counter.html">Pmw.Counter reference manual</a>) using
  its default configuration like this:

</p>

<dl>
<dd>
<pre>
counter1 = Pmw.Counter()
counter1.pack(padx = 10, pady = 10)
</pre>
</dd>
</dl>

<p>
  Now enter a number and click on the arrow buttons to see the number
  increment or decrement.  The result looks something like this:

</p>

<center><P ALIGN="CENTER">
  <IMG SRC = counter1.gif ALT = "Counter 1" WIDTH=220 HEIGHT=46>
</p></center>

<p>
  The above example creates the counter as a child of the root window. 
  If you want to create it as a child of another window (for example,
  a Tkinter.Frame widget called 'frame'), add the parent as an
  argument to the constructor:

</p>

<dl>
<dd>
<pre>
counter1a = Pmw.Counter(frame)
</pre>
</dd>
</dl>

</dd>
<dt> <h3>Methods</h3></dt><dd>
<p>
  Once a megawidget has been created, you can call any of its other
  methods in a similar way to Tk widgets.  The following sets the value
  of the counter and then increments it:
</p>

<dl>
<dd>
<pre>
counter1.setentry(41)
counter1.increment()
</pre>
</dd>
</dl>

</dd>
<dt> <h3>Options</h3></dt><dd>
<p>
  Like any widget, a megawidget may have options to allow it to be
  configured for a particular use.  Options allow the megawidget user
  to modify the appearance and behaviour of the megawidget.  The
  counter megawidget has several such options.  One of them,
  <strong>datatype</strong>, specifies how the counter should count up
  and down, such as, for example, by integers, reals, times or dates. 
  The default value is <strong>'numeric'</strong>, which means the
  counter expects integers to be entered and will support
  incrementing and decrementing by whole numbers.
  
</p>
  
<p>
  Another option is
  <strong>increment</strong>, which specifies how many units should be
  added or subtracted when the counter is incremented or decremented. 
  Using these options, you can create a time counter, supporting the
  format <strong>HH:MM:SS</strong>, and counting in minutes, like
  this (note also the call to the <code>setentry</code> method to set
  the contents of the entry field):

</p>

<dl>
<dd>
<pre>
counter2 = Pmw.Counter(
    datatype = 'time',
    increment = 60)
counter2.setentry('00:00:00')
counter2.pack(padx = 10, pady = 10)
</pre>
</dd>
</dl>

<p>
  Many megawidget options can be modified using the
  <code>configure()</code> method.  For example, you can change the
  value of the <strong>increment</strong> option to 10 minutes like
  this:

</p>

<dl>
<dd>
<pre>
counter2.configure(increment = 60 * 10)
</pre>
</dd>
</dl>

<b>Initialisation options</b>
<br>
<p>
  Some megawidget options can only be set when creating the megawidget.
  These options can not be set by calling the <code>configure()</code>
  method, but they can be queried in all the usual ways.  For example,
  the counter has an <strong>orient</strong> initialisation option
  which specifies whether the arrow buttons should appear to the
  left and right of the entry field (<strong>'horizontal'</strong>)
  or above and below (<strong>'vertical'</strong>).  You can create a
  numeric counter with arrow buttons above and below the entry
  field like this:

</p>

<dl>
<dd>
<pre>
counter3 = Pmw.Counter(orient = 'vertical')
counter3.pack(padx = 10, pady = 10)
</pre>
</dd>
</dl>

<b>Querying options</b>
<br>
<p>
  You can query the value of megawidget options (initialisation or
  not) in similar ways as for normal Tkinter widgets.  For example,
  the following code prints the values of some of the counter options.

</p>

<dl>
<dd>
<pre>
print counter3.cget('increment')
    --> 1
print counter3.configure('orient')
    --> ('orient', 'orient', 'Orient', 'horizontal', 'vertical')
</pre>
</dd>
</dl>

<p>
  When a Tk widget option is queried, its value is always
  returned as a string, regardless of the type used when setting the
  option.  However, when a Pmw megawidget option is queried, a
  reference to the object used when setting the option is returned. 
  In other words it is not always a string.  For example, the type
  returned by <code>cget('increment')</code> above was integer.

</p>

</dd>
<dt> <h3>Components</h3></dt><dd>
<p>
  Megawidgets are made up of other widgets, which we call
  <em>components</em>.  Each component is known by a logical name and
  may be either a simple Tk widget, or may itself be a megawidget. 
  Pmw gives the megawidget user access to not only the functionality
  supported directly by the megawidget through its options and methods,
  but also to the components of the megawidget and their options and
  methods.  To access a component directly, use the
  <code>component()</code> method.  For example, to call method
  <strong>doit</strong> of component <strong>comp</strong>
  of megawidget <strong>mega</strong>:

  </p>

<dl>
<dd>
<pre>
mega.component('comp').doit()
</pre>
</dd>
</dl>

<b>Component options</b>
<br>
<p>
  There is a short-hand way to access the options of components, by
  using the notation <em>component_option</em>.  This allows, for
  example, a counter megawidget to be configured with different
  colored backgrounds for each of its arrow button components (these
  components are called <strong>downarrow</strong> and
  <strong>uparrow</strong>):

</p>

<dl>
<dd>
<pre>
counter2.configure(
    downarrow_background = 'green',
    uparrow_background = 'red')
</pre>
</dd>
</dl>

<b>The hull</b>
<br>
<p>
  All megawidgets are enclosed in a containing widget which is created
  automatically by the Pmw base classes.  For normal megawidgets the
  container is a Tkinter Frame widget.  For megawidgets which are
  toplevel windows, the container is a Tkinter Toplevel widget.  The
  containing widget is accessible as the <strong>hull</strong>
  component.

</p>

<p>
  To access options of the containing widget use the form
  <strong>hull_</strong><em>option</em>.  For example to create a
  counter megawidget with a wide sunken border around it: 

</p>

<dl>
<dd>
<pre>
counter4 = Pmw.Counter(
    hull_relief = 'sunken',
    hull_borderwidth = 5 
)
</pre>
</dd>
</dl>


<b>The interior</b>
<br>
<p>
  Some megawidgets, such as Dialog and LabeledWidget, also have a
  frame into which users can pack other widgets.  This frame may be a
  component but can also be accessed with the <code>interior()</code>
  method.  For the Pmw.MegaToplevel and Pmw.MegaWidget classes, the
  interior widget is the same as the hull widget.  For other
  megawidgets, the hull is the outer, containing widget and the
  interior is the empty frame which can be used to extend the
  megawidget by including extra internal widgets.

</p>

<b>Sub components and aliases</b>
<br>
<p>
  Components may themselves be megawidgets and so their
  (sub-)components can be referred to using the notation
  <em>component_sub-component</em>.  For example, the
  <strong>entryfield</strong> component of the counter is a
  Pmw.EntryField megawidget (which handles the input validation).  In
  turn, this has a Tkinter.Entry component named
  <strong>entry</strong>.  Therefore, you can change the background of
  the counter's Tkinter.Entry widget with:

</p>

<dl>
<dd>
<pre>
counter2.configure(entryfield_entry_background = 'yellow')
</pre>
</dd>
</dl>

<p>
  Most component path names (like <strong>entryfield_entry</strong>)
  have a shorter <strong>alias</strong> defined for them.  In this
  case, you can use the equivalent:

</p>

<dl>
<dd>
<pre>
counter2.configure(entry_background = 'yellow')
</pre>
</dd>
</dl>

<b>Changing the python class of a component</b>
<br>
<p>
  Each megawidget component is an instance of some python class.  The
  default class of each component is given in the reference manual. 
  By using the special <strong>pyclass</strong> component option, you
  can specify a different python class to use when creating the
  component.  For example, to create a Pmw.Counter megawidget which
  has a Tkinter.Button as its label, rather than the default
  Tkinter.Label:

</p>

<dl>
<dd>
<pre>
counter5 = Pmw.Counter(
        labelpos = 'w',
        label_text = 'Hello',
        label_pyclass = Tkinter.Button
)

</pre>
</dd>
</dl>

</dd>
<dt> <h3>Forwarding methods</h3></dt><dd>
<p>
  Since a Pmw megawidget is a normal python class, it both inherits
  methods from its base classes and also may have other methods
  defined for it in the usual way.
  Pmw also supports a third way that a megawidget may gain methods -
  by 'forwarding' methods to one or more of its subwidgets.  This is 
  also known as 'delegating'. 
  For example, a Pmw.Counter megawidget delegates the methods related
  to its Pmw.EntryField component, <strong>entryfield</strong>, to the
  component.  It does not have to explicitely define methods which
  call the component methods.
  This is why we can call <strong>counter2.setentry()</strong> - since
  <strong>setentry()</strong> is a method of the Pmw.EntryField
  component, it is available to the Pmw.Counter.

</p>
<p>
  Methods already defined by a class or its base classes take
  precedence over delegated methods.  For example, Pmw.Counter
  inherits a <strong>cget</strong> method from Pmw.MegaArchetype. 
  Therefore, this method is not delegated to the <strong>cget</strong>
  method of Pmw.EntryField.

</p>
  
</dd>
<dt> <h3>Extending Pmw megawidgets</h3></dt><dd>

<p>
  There are several ways of extending Pmw megawidgets.  Firstly, the
  flexibility of the options and components allows the widget's
  appearance and behaviour to be greatly modified.  Secondly, widgets
  of the user's choice can be added inside some megawidgets by using
  the interior() method.  The Pmw classes MegaToplevel, MegaWidget,
  Dialog and LabeledWidget are particularly designed to be extended in
  this way.  For example, to create a dialog window containing a
  counter:

</p>

<dl>
<dd>
<pre>
dialog = Pmw.Dialog(
        title = 'Counter dialog',
        buttons = ('OK', 'Cancel'))
interior = dialog.interior()
counter = Pmw.Counter(interior)
counter.pack(padx = 20, pady = 20)
</pre>
</dd>
</dl>

<center><P ALIGN="CENTER">
  <IMG SRC = counter2.gif ALT = "Counter 2" WIDTH=266 HEIGHT=126>
</p></center>

<p>
  A third way to extend megawidgets is to inherit from (or subclass)
  them.  See <a href="howtobuild.html">How to build Pmw
  megawidgets</a> for information on how to use inheritance to extend
  a megawidget by adding new options.  For simpler cases, where new
  methods are to be added to an existing megawidget and/or the default
  values for some options are to be changed, normal subclassing can be
  used.  For example, to create new classes based on a Pmw.Counter,
  one with a new method <code>getminutes()</code> and one with a
  default datatype of 'time' and a white entry background:

</p>

<dl>
<dd>
<pre>
class MinuteCounter1(Pmw.Counter):

    def getminutes(self):
	return Pmw.timestringtoseconds(self.getvalue()) / 60

class MinuteCounter2(Pmw.Counter):

    def __init__(self, parent = None, **kw):
        kw['datatype'] = 'time'
        kw['entry_background'] = 'white'
        kw['entryfield_value'] = '00:00:00'
        kw['increment'] = 60
	apply(Pmw.Counter.__init__, (self, parent), kw)
</pre>
</dd>
</dl>

</dd>
<dt> <h2>A quick example</h2></dt><dd>
<p>
  The following code is a small example of how to use Pmw megawidgets. 
  It is a complete program which displays three ways for the user to
  enter a value -  using an up-down counter, an entry field with
  validation and a dropdown combobox.

</p>
<dl>
<dd>
<pre>
import Pmw
root = Pmw.initialise(fontScheme = 'pmw1')

counter = Pmw.Counter(
        label_text = 'Counter:',
        labelpos = 'w',
        entryfield_value = '00:00:00',
        entryfield_validate = 'time',
        datatype='time',
        increment=5*60,
)
counter.pack(fill = 'x', padx = 10, pady = 10)

entry = Pmw.EntryField(
        label_text = 'Real entry:',
        labelpos = 'w',
        value = '+2.9979e+8',
        validate = 'real',
)
entry.pack(fill = 'x', padx = 10, pady = 10)

combo = Pmw.ComboBox(
        label_text = 'ComboBox:',
        labelpos = 'w',
        scrolledlist_items = map(str, range(20))
)
combo.pack(fill = 'x', padx = 10, pady = 10)

# Make the labels line up neatly
Pmw.alignlabels((counter, entry, combo))

root.title('Pmw megawidgets example')
root.mainloop()
</pre>
</dd>
</dl>

<center><P ALIGN="CENTER">
  <IMG SRC = example1.gif ALT = "Example 1" WIDTH=321 HEIGHT=140>
</p></center>

</dd>
<dt> <h3>Another example</h3></dt><dd>
<p>
  The following also shows how to use Pmw megawidgets.  It displays a
  RadioSelect megawidget and an exit button packed into the root
  window.

</p>

<dl>
<dd>
<pre>
import Tkinter
import Pmw

def callback(tag):
    # This is called whenever the user clicks on a
    # button in the RadioSelect widget.
    print tag, 'was pressed.'

# Initialise Tkinter and Pmw.
root = Pmw.initialise(fontScheme = 'pmw1')
root.title('Pmw RadioSelect demonstration')

# Create and pack a RadioSelect widget.
radio = Pmw.RadioSelect(
        command = callback,
        labelpos = 'w',
        label_text = 'Food group:')
radio.pack(padx = 20, pady = 20)

# Add some buttons to the RadioSelect.
for text in ('Fruit', 'Vegetables', 'Cereals', 'Legumes'):
    radio.add(text)
radio.invoke('Vegetables')

# Create an exit button.
exit = Tkinter.Button(text = 'Exit', command = root.destroy)
exit.pack(pady = 20)

# Let's go.
root.mainloop()
</pre>
</dd>
</dl>

<center><P ALIGN="CENTER">
  <IMG SRC = example2.gif ALT = "Example 2" WIDTH=503 HEIGHT=158>
</p></center>

</dd>
<dt> <h3>Using the Tk option database</h3></dt><dd>
<p>
  There are several ways to use the Tk option database to customise a
  Pmw application.  Firstly you can customise all the basic Tk widgets
  in the usual way.  For example, to set the background of all
  Tkinter.Label widgets (whether a megawidget component or not):

</p>

<dl>
<dd>
<pre>
root.option_add('*Label.background', 'pink')
</pre>
</dd>
</dl>

<p>
  To set the background of all Pmw.EntryField <strong>label</strong>
  components:

</p>

<dl>
<dd>
<pre>
root.option_add('*EntryField.Label.background', 'green')
</pre>
</dd>
</dl>

<p>
  To set the background of all Pmw.EntryField components, including
  the <strong>hull</strong> component:

</p>

<dl>
<dd>
<pre>
root.option_add('*EntryField*background', 'blue')
</pre>
</dd>
</dl>

<p>
  The above option settings affect basic Tk widgets and, since it is
  built into the Tk widgets, this functionality is always available. 
  However, to be able to use the Tk option database to set the default
  values for Pmw megawidget options, <code>Pmw.initialise()</code>
  must be called with <code>useTkOptionDb = 1</code>.  If this is not
  done, Pmw does not query the Tk option database for megawidget
  option defaults.  This is the default behaviour because there is a
  slight performance penalty for using the Tk option database.

</p>

<p>
  Assuming <code>useTkOptionDb</code> has been set, the default
  buttonbox position of all Pmw.Dialog megawidgets can be changed
  with:

</p>

<dl>
<dd>
<pre>
root.option_add('*Dialog.buttonboxpos', 'e')
</pre>
</dd>
</dl>

<p>
  To set the label position of all Pmw.EntryField megawidgets, thus giving
  them a <strong>label</strong> component by default:

</p>

<dl>
<dd>
<pre>
root.option_add('*EntryField.labelpos', 'w')
</pre>
</dd>
</dl>

</dd>
</dl>


    <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
86530b38 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>How to use Pmw megawidgets</title>
	7	</head>
	8
	9	<body bgcolor="#ffffff" text="#000000" link="#0000ee"
	10	vlink="551a8b" alink="ff0000">
	11
	12	<h1 ALIGN="CENTER">How to use Pmw megawidgets</h1>
	13
	14	<center><P ALIGN="CENTER">
	15	<IMG SRC = blue_line.gif ALT = "" WIDTH=320 HEIGHT=5>
	16	</p></center>
	17
	18	<dl>
	19	<dt> <h3>Introduction</h3></dt><dd>
	20	<p>
	21	This document briefly describes the features of the Pmw megawidget
	22	toolkit and how to use the megawidgets. Using examples, it
	23	describes those features common to all Pmw megawidgets. For a
	24	description of individual Pmw megawidgets see the
	25	<a href="refindex.html">reference manuals</a>.
	26	For complete information on general Pmw megawidget functionality see the
	27	<a href="MegaArchetype.html">Pmw.MegaArchetype reference manual</a>.
	28	For a lot more example code, run any of the files in the
	29	Pmw <code>demos</code> directory.
	30
	31	</p>
	32
	33	<p>
	34	A simple example of a megawidget is a counter. This widget
	35	contains an entry field and two small arrow buttons. Users may
	36	enter a value directly into the entry field or they may use the
	37	buttons to increment and decrement the value displayed without
	38	having to use the keyboard. Having this and other megawidgets in
	39	your toolbox allows you to choose the best graphical interface for
	40	your application.
	41
	42	</p>
	43	</dd>
	44	<dt> <h3>Getting started</h3></dt><dd>
	45
	46	<b>Initialisation of Pmw</b>
	47	<br>
	48	<p>
	49	To run the examples in the tutorial, make sure that the
	50	Pmw <code>lib</code> directory is in <code>sys.path</code>. You
	51	should be able to cut and paste the examples into an interactive
	52	python session, or you can copy them to a file and run the file with
	53	python.
	54
	55	</p>
	56	<p>
	57	The following two lines should be entered before any of the
	58	examples. These import and initialise Pmw.
	59	For more information on <code>Pmw.initialise()</code> see the
	60	<a href="PmwFunctions.html">Pmw functions reference manual</a>.
	61
	62	</p>
	63
	64	<dl>
65	<dd>
66	<pre>
67	import Pmw
68	root = Pmw.initialise()
69	</pre>
70	</dd>
71	</dl>
72
73	<p>
74	If necessary, you can have more control over how Tkinter and Pmw are
75	initialised by using this form of initialisation:
76
77	</p>
78
79	<dl>
80	<dd>
81	<pre>
82	import Tkinter
83	root = Tkinter.Tk()
84	import Pmw
85	Pmw.initialise(root)
86	</pre>
87	</dd>
88	</dl>
89
90	</dd>
91	<dt> <h3>Megawidget construction</h3></dt><dd>
92
93	<b>Creating a counter</b>
94	<br>
95	<p>
96	Now that you have the formalities out of the way, you can create and
97	pack a counter megawidget (see
98	<a href="Counter.html">Pmw.Counter reference manual</a>) using
99	its default configuration like this:
100
101	</p>
102
103	<dl>
104	<dd>
105	<pre>
106	counter1 = Pmw.Counter()
107	counter1.pack(padx = 10, pady = 10)
108	</pre>
109	</dd>
110	</dl>
111
112	<p>
113	Now enter a number and click on the arrow buttons to see the number
114	increment or decrement. The result looks something like this:
115
116	</p>
117
118	<center><P ALIGN="CENTER">
119	<IMG SRC = counter1.gif ALT = "Counter 1" WIDTH=220 HEIGHT=46>
120	</p></center>
121
122	<p>
123	The above example creates the counter as a child of the root window.
124	If you want to create it as a child of another window (for example,
125	a Tkinter.Frame widget called 'frame'), add the parent as an
126	argument to the constructor:
127
128	</p>
129
130	<dl>
131	<dd>
132	<pre>
133	counter1a = Pmw.Counter(frame)
134	</pre>
135	</dd>
136	</dl>
137
138	</dd>
139	<dt> <h3>Methods</h3></dt><dd>
140	<p>
141	Once a megawidget has been created, you can call any of its other
142	methods in a similar way to Tk widgets. The following sets the value
143	of the counter and then increments it:
144	</p>
145
146	<dl>
147	<dd>
148	<pre>
149	counter1.setentry(41)
150	counter1.increment()
151	</pre>
152	</dd>
153	</dl>
154
155	</dd>
156	<dt> <h3>Options</h3></dt><dd>
157	<p>
158	Like any widget, a megawidget may have options to allow it to be
159	configured for a particular use. Options allow the megawidget user
160	to modify the appearance and behaviour of the megawidget. The
161	counter megawidget has several such options. One of them,
162	<strong>datatype</strong>, specifies how the counter should count up
163	and down, such as, for example, by integers, reals, times or dates.
164	The default value is <strong>'numeric'</strong>, which means the
165	counter expects integers to be entered and will support
166	incrementing and decrementing by whole numbers.
167
168	</p>
169
170	<p>
171	Another option is
172	<strong>increment</strong>, which specifies how many units should be
173	added or subtracted when the counter is incremented or decremented.
174	Using these options, you can create a time counter, supporting the
175	format <strong>HH:MM:SS</strong>, and counting in minutes, like
176	this (note also the call to the <code>setentry</code> method to set
177	the contents of the entry field):
178
179	</p>
180
181	<dl>
182	<dd>
183	<pre>
184	counter2 = Pmw.Counter(
185	datatype = 'time',
186	increment = 60)
187	counter2.setentry('00:00:00')
188	counter2.pack(padx = 10, pady = 10)
189	</pre>
190	</dd>
191	</dl>
192
193	<p>
194	Many megawidget options can be modified using the
195	<code>configure()</code> method. For example, you can change the
196	value of the <strong>increment</strong> option to 10 minutes like
197	this:
198
199	</p>
200
201	<dl>
202	<dd>
203	<pre>
204	counter2.configure(increment = 60 * 10)
205	</pre>
206	</dd>
207	</dl>
208
209	<b>Initialisation options</b>
210	<br>
211	<p>
212	Some megawidget options can only be set when creating the megawidget.
213	These options can not be set by calling the <code>configure()</code>
214	method, but they can be queried in all the usual ways. For example,
215	the counter has an <strong>orient</strong> initialisation option
216	which specifies whether the arrow buttons should appear to the
217	left and right of the entry field (<strong>'horizontal'</strong>)
218	or above and below (<strong>'vertical'</strong>). You can create a
219	numeric counter with arrow buttons above and below the entry
220	field like this:
221
222	</p>
223
224	<dl>
225	<dd>
226	<pre>
227	counter3 = Pmw.Counter(orient = 'vertical')
228	counter3.pack(padx = 10, pady = 10)
229	</pre>
230	</dd>
231	</dl>
232
233	<b>Querying options</b>
234	<br>
235	<p>
236	You can query the value of megawidget options (initialisation or
237	not) in similar ways as for normal Tkinter widgets. For example,
238	the following code prints the values of some of the counter options.
239
240	</p>
241
242	<dl>
243	<dd>
244	<pre>
245	print counter3.cget('increment')
246	--> 1
247	print counter3.configure('orient')
248	--> ('orient', 'orient', 'Orient', 'horizontal', 'vertical')
249	</pre>
250	</dd>
251	</dl>
252
253	<p>
254	When a Tk widget option is queried, its value is always
255	returned as a string, regardless of the type used when setting the
256	option. However, when a Pmw megawidget option is queried, a
257	reference to the object used when setting the option is returned.
258	In other words it is not always a string. For example, the type
259	returned by <code>cget('increment')</code> above was integer.
260
261	</p>
262
263	</dd>
264	<dt> <h3>Components</h3></dt><dd>
265	<p>
266	Megawidgets are made up of other widgets, which we call
267	<em>components</em>. Each component is known by a logical name and
268	may be either a simple Tk widget, or may itself be a megawidget.
269	Pmw gives the megawidget user access to not only the functionality
270	supported directly by the megawidget through its options and methods,
271	but also to the components of the megawidget and their options and
272	methods. To access a component directly, use the
273	<code>component()</code> method. For example, to call method
274	<strong>doit</strong> of component <strong>comp</strong>
275	of megawidget <strong>mega</strong>:
276
277	</p>
278
279	<dl>
280	<dd>
281	<pre>
282	mega.component('comp').doit()
283	</pre>
284	</dd>
285	</dl>
286
287	<b>Component options</b>
288	<br>
289	<p>
290	There is a short-hand way to access the options of components, by
291	using the notation <em>component_option</em>. This allows, for
292	example, a counter megawidget to be configured with different
293	colored backgrounds for each of its arrow button components (these
294	components are called <strong>downarrow</strong> and
295	<strong>uparrow</strong>):
296
297	</p>
298
299	<dl>
300	<dd>
301	<pre>
302	counter2.configure(
303	downarrow_background = 'green',
304	uparrow_background = 'red')
305	</pre>
306	</dd>
307	</dl>
308
309	<b>The hull</b>
310	<br>
311	<p>
312	All megawidgets are enclosed in a containing widget which is created
313	automatically by the Pmw base classes. For normal megawidgets the
314	container is a Tkinter Frame widget. For megawidgets which are
315	toplevel windows, the container is a Tkinter Toplevel widget. The
316	containing widget is accessible as the <strong>hull</strong>
317	component.
318
319	</p>
320
321	<p>
322	To access options of the containing widget use the form
323	<strong>hull_</strong><em>option</em>. For example to create a
324	counter megawidget with a wide sunken border around it:
325
326	</p>
327
328	<dl>
329	<dd>
330	<pre>
331	counter4 = Pmw.Counter(
332	hull_relief = 'sunken',
333	hull_borderwidth = 5
334	)
335	</pre>
336	</dd>
337	</dl>
338
339
340	<b>The interior</b>
341	<br>
342	<p>
343	Some megawidgets, such as Dialog and LabeledWidget, also have a
344	frame into which users can pack other widgets. This frame may be a
345	component but can also be accessed with the <code>interior()</code>
346	method. For the Pmw.MegaToplevel and Pmw.MegaWidget classes, the
347	interior widget is the same as the hull widget. For other
348	megawidgets, the hull is the outer, containing widget and the
349	interior is the empty frame which can be used to extend the
350	megawidget by including extra internal widgets.
351
352	</p>
353
354	<b>Sub components and aliases</b>
355	<br>
356	<p>
357	Components may themselves be megawidgets and so their
358	(sub-)components can be referred to using the notation
359	<em>component_sub-component</em>. For example, the
360	<strong>entryfield</strong> component of the counter is a
361	Pmw.EntryField megawidget (which handles the input validation). In
362	turn, this has a Tkinter.Entry component named
363	<strong>entry</strong>. Therefore, you can change the background of
364	the counter's Tkinter.Entry widget with:
365
366	</p>
367
368	<dl>
369	<dd>
370	<pre>
371	counter2.configure(entryfield_entry_background = 'yellow')
372	</pre>
373	</dd>
374	</dl>
375
376	<p>
377	Most component path names (like <strong>entryfield_entry</strong>)
378	have a shorter <strong>alias</strong> defined for them. In this
379	case, you can use the equivalent:
380
381	</p>
382
383	<dl>
384	<dd>
385	<pre>
386	counter2.configure(entry_background = 'yellow')
387	</pre>
388	</dd>
389	</dl>
390
391	<b>Changing the python class of a component</b>
392	<br>
393	<p>
394	Each megawidget component is an instance of some python class. The
395	default class of each component is given in the reference manual.
396	By using the special <strong>pyclass</strong> component option, you
397	can specify a different python class to use when creating the
398	component. For example, to create a Pmw.Counter megawidget which
399	has a Tkinter.Button as its label, rather than the default
400	Tkinter.Label:
401
402	</p>
403
404	<dl>
405	<dd>
406	<pre>
407	counter5 = Pmw.Counter(
408	labelpos = 'w',
409	label_text = 'Hello',
410	label_pyclass = Tkinter.Button
411	)
412
413	</pre>
414	</dd>
415	</dl>
416
417	</dd>
418	<dt> <h3>Forwarding methods</h3></dt><dd>
419	<p>
420	Since a Pmw megawidget is a normal python class, it both inherits
421	methods from its base classes and also may have other methods
422	defined for it in the usual way.
423	Pmw also supports a third way that a megawidget may gain methods -
424	by 'forwarding' methods to one or more of its subwidgets. This is
425	also known as 'delegating'.
426	For example, a Pmw.Counter megawidget delegates the methods related
427	to its Pmw.EntryField component, <strong>entryfield</strong>, to the
428	component. It does not have to explicitely define methods which
429	call the component methods.
430	This is why we can call <strong>counter2.setentry()</strong> - since
431	<strong>setentry()</strong> is a method of the Pmw.EntryField
432	component, it is available to the Pmw.Counter.
433
434	</p>
435	<p>
436	Methods already defined by a class or its base classes take
437	precedence over delegated methods. For example, Pmw.Counter
438	inherits a <strong>cget</strong> method from Pmw.MegaArchetype.
439	Therefore, this method is not delegated to the <strong>cget</strong>
440	method of Pmw.EntryField.
441
442	</p>
443
444	</dd>
445	<dt> <h3>Extending Pmw megawidgets</h3></dt><dd>
446
447	<p>
448	There are several ways of extending Pmw megawidgets. Firstly, the
449	flexibility of the options and components allows the widget's
450	appearance and behaviour to be greatly modified. Secondly, widgets
451	of the user's choice can be added inside some megawidgets by using
452	the interior() method. The Pmw classes MegaToplevel, MegaWidget,
453	Dialog and LabeledWidget are particularly designed to be extended in
454	this way. For example, to create a dialog window containing a
455	counter:
456
457	</p>
458
459	<dl>
460	<dd>
461	<pre>
462	dialog = Pmw.Dialog(
463	title = 'Counter dialog',
464	buttons = ('OK', 'Cancel'))
465	interior = dialog.interior()
466	counter = Pmw.Counter(interior)
467	counter.pack(padx = 20, pady = 20)
468	</pre>
469	</dd>
470	</dl>
471
472	<center><P ALIGN="CENTER">
473	<IMG SRC = counter2.gif ALT = "Counter 2" WIDTH=266 HEIGHT=126>
474	</p></center>
475
476	<p>
477	A third way to extend megawidgets is to inherit from (or subclass)
478	them. See <a href="howtobuild.html">How to build Pmw
479	megawidgets</a> for information on how to use inheritance to extend
480	a megawidget by adding new options. For simpler cases, where new
481	methods are to be added to an existing megawidget and/or the default
482	values for some options are to be changed, normal subclassing can be
483	used. For example, to create new classes based on a Pmw.Counter,
484	one with a new method <code>getminutes()</code> and one with a
485	default datatype of 'time' and a white entry background:
486
487	</p>
488
489	<dl>
490	<dd>
491	<pre>
492	class MinuteCounter1(Pmw.Counter):
493
494	def getminutes(self):
495	return Pmw.timestringtoseconds(self.getvalue()) / 60
496
497	class MinuteCounter2(Pmw.Counter):
498
499	def __init__(self, parent = None, **kw):
500	kw['datatype'] = 'time'
501	kw['entry_background'] = 'white'
502	kw['entryfield_value'] = '00:00:00'
503	kw['increment'] = 60
504	apply(Pmw.Counter.__init__, (self, parent), kw)
505	</pre>
506	</dd>
507	</dl>
508
509	</dd>
510	<dt> <h2>A quick example</h2></dt><dd>
511	<p>
512	The following code is a small example of how to use Pmw megawidgets.
513	It is a complete program which displays three ways for the user to
514	enter a value - using an up-down counter, an entry field with
515	validation and a dropdown combobox.
516
517	</p>
518	<dl>
519	<dd>
520	<pre>
521	import Pmw
522	root = Pmw.initialise(fontScheme = 'pmw1')
523
524	counter = Pmw.Counter(
525	label_text = 'Counter:',
526	labelpos = 'w',
527	entryfield_value = '00:00:00',
528	entryfield_validate = 'time',
529	datatype='time',
530	increment=5*60,
531	)
532	counter.pack(fill = 'x', padx = 10, pady = 10)
533
534	entry = Pmw.EntryField(
535	label_text = 'Real entry:',
536	labelpos = 'w',
537	value = '+2.9979e+8',
538	validate = 'real',
539	)
540	entry.pack(fill = 'x', padx = 10, pady = 10)
541
542	combo = Pmw.ComboBox(
543	label_text = 'ComboBox:',
544	labelpos = 'w',
545	scrolledlist_items = map(str, range(20))
546	)
547	combo.pack(fill = 'x', padx = 10, pady = 10)
548
549	# Make the labels line up neatly
550	Pmw.alignlabels((counter, entry, combo))
551
552	root.title('Pmw megawidgets example')
553	root.mainloop()
554	</pre>
555	</dd>
556	</dl>
557
558	<center><P ALIGN="CENTER">
559	<IMG SRC = example1.gif ALT = "Example 1" WIDTH=321 HEIGHT=140>
560	</p></center>
561
562	</dd>
563	<dt> <h3>Another example</h3></dt><dd>
564	<p>
565	The following also shows how to use Pmw megawidgets. It displays a
566	RadioSelect megawidget and an exit button packed into the root
567	window.
568
569	</p>
570
571	<dl>
572	<dd>
573	<pre>
574	import Tkinter
575	import Pmw
576
577	def callback(tag):
578	# This is called whenever the user clicks on a
579	# button in the RadioSelect widget.
580	print tag, 'was pressed.'
581
582	# Initialise Tkinter and Pmw.
583	root = Pmw.initialise(fontScheme = 'pmw1')
584	root.title('Pmw RadioSelect demonstration')
585
586	# Create and pack a RadioSelect widget.
587	radio = Pmw.RadioSelect(
588	command = callback,
589	labelpos = 'w',
590	label_text = 'Food group:')
591	radio.pack(padx = 20, pady = 20)
592
593	# Add some buttons to the RadioSelect.
594	for text in ('Fruit', 'Vegetables', 'Cereals', 'Legumes'):
595	radio.add(text)
596	radio.invoke('Vegetables')
597
598	# Create an exit button.
599	exit = Tkinter.Button(text = 'Exit', command = root.destroy)
600	exit.pack(pady = 20)
601
602	# Let's go.
603	root.mainloop()
604	</pre>
605	</dd>
606	</dl>
607
608	<center><P ALIGN="CENTER">
609	<IMG SRC = example2.gif ALT = "Example 2" WIDTH=503 HEIGHT=158>
610	</p></center>
611
612	</dd>
613	<dt> <h3>Using the Tk option database</h3></dt><dd>
614	<p>
615	There are several ways to use the Tk option database to customise a
616	Pmw application. Firstly you can customise all the basic Tk widgets
617	in the usual way. For example, to set the background of all
618	Tkinter.Label widgets (whether a megawidget component or not):
619
620	</p>
621
622	<dl>
623	<dd>
624	<pre>
625	root.option_add('*Label.background', 'pink')
626	</pre>
627	</dd>
628	</dl>
629
630	<p>
631	To set the background of all Pmw.EntryField <strong>label</strong>
632	components:
633
634	</p>
635
636	<dl>
637	<dd>
638	<pre>
639	root.option_add('*EntryField.Label.background', 'green')
640	</pre>
641	</dd>
642	</dl>
643
644	<p>
645	To set the background of all Pmw.EntryField components, including
646	the <strong>hull</strong> component:
647
648	</p>
649
650	<dl>
651	<dd>
652	<pre>
653	root.option_add('EntryFieldbackground', 'blue')
654	</pre>
655	</dd>
656	</dl>
657
658	<p>
659	The above option settings affect basic Tk widgets and, since it is
660	built into the Tk widgets, this functionality is always available.
661	However, to be able to use the Tk option database to set the default
662	values for Pmw megawidget options, <code>Pmw.initialise()</code>
663	must be called with <code>useTkOptionDb = 1</code>. If this is not
664	done, Pmw does not query the Tk option database for megawidget
665	option defaults. This is the default behaviour because there is a
666	slight performance penalty for using the Tk option database.
667
668	</p>
669
670	<p>
671	Assuming <code>useTkOptionDb</code> has been set, the default
672	buttonbox position of all Pmw.Dialog megawidgets can be changed
673	with:
674
675	</p>
676
677	<dl>
678	<dd>
679	<pre>
680	root.option_add('*Dialog.buttonboxpos', 'e')
681	</pre>
682	</dd>
683	</dl>
684
685	<p>
686	To set the label position of all Pmw.EntryField megawidgets, thus giving
687	them a <strong>label</strong> component by default:
688
689	</p>
690
691	<dl>
692	<dd>
693	<pre>
694	root.option_add('*EntryField.labelpos', 'w')
695	</pre>
696	</dd>
697	</dl>
698
699	</dd>
700	</dl>
701
702
703	<center><P ALIGN="CENTER">
704	<IMG SRC = blue_line.gif ALT = "" WIDTH=320 HEIGHT=5>
705	</p></center>
706
707
708	<font size=-1>
709	<center><P ALIGN="CENTER">
710	Pmw 1.2 -
711	5 Aug 2003
712	- <a href="index.html">Home</a>
713
714	</p></center>
715	</font>
716
717	</body>
718	</html>
719