3 <title>gui.widget</title>
4 <style type='text/css'><!--
6 border: 1px solid black;
41 .wiki h1, .wiki h2, .wiki h3, .wiki h4, .wiki h5, .wiki h6 {
45 border-bottom: 1px solid #bbbbbb;
73 .wiki code, .wiki pre {
76 border: 1px dashed #888888;
81 border-top: 1px solid #888888;
82 border-left: 1px solid #888888;
83 border-spacing: 0px; border-collapse: collapse;
86 border-bottom: 1px solid #888888;
87 border-right: 1px solid #888888;
92 border-bottom: 1px solid #888888;
93 border-right: 1px solid #888888;
104 <table cellpadding=8><tr><td>
105 <a href='http://www.imitationpickles.org/pgu/'><img src='skin/logo.gif' alt="Phil's pyGame Utilities" border=0></a>
106 <td style='font-size:48px'>Documentation
111 <hr width=500 align=center>
113 <table width='100%'><tr><td valign=top width=120 style='padding-right:6px;border-right: 1px solid black;'>
114 <a href='index.html'>Overview</a><br><br>
115 <strong>Scripts</strong><br>
116 <a href="tileedit.html">tileedit</a>
117 | <a href="leveledit.html">leveledit</a>
118 | <a href="tganew.html">tganew</a>
119 | <a href="levelfancy.html">levelfancy</a>
121 <strong>Reference</strong><br>
122 <a href="algo.html">algo</a>
123 | <a href="ani.html">ani</a>
124 | <a href="engine.html">engine</a>
125 | <a href="fonts.html">fonts</a>
126 | <a href="high.html">high</a>
127 | <a href="html.html">html</a>
128 | <a href="layout.html">layout</a>
129 | <a href="text.html">text</a>
130 | <a href="timer.html">timer</a>
131 | <a href="vid.html">vid</a>
133 <strong>Tutorials</strong><br>
134 <a href="tilevid1.html">1</a>
135 | <a href="tilevid2.html">2</a>
136 | <a href="tilevid3.html">3</a>
137 | <a href="tilevid4.html">4</a>
138 | <a href="tilevid5.html">5</a>
140 <strong>GUI Ref.</strong><br>
141 <a href="gui.theme.html">theme</a>
142 | <a href="gui.style.html">style</a>
143 | <a href="gui.widget.html">widget</a>
144 | <a href="gui.surface.html">surface</a>
145 | <a href="gui.const.html">const</a>
147 <strong>Containers</strong><br>
148 <a href="gui.container.html">container</a>
149 | <a href="gui.app.html">app</a>
150 | <a href="gui.table.html">table</a>
151 | <a href="gui.document.html">document</a>
152 | <a href="gui.area.html">area</a>
154 <strong>Forms</strong><br>
155 <a href="gui.form.html">form</a>
156 | <a href="gui.group.html">group</a>
158 <strong>Widgets</strong><br>
159 <a href="gui.basic.html">basic</a>
160 | <a href="gui.button.html">button</a>
161 | <a href="gui.input.html">input</a>
162 | <a href="gui.keysym.html">keysym</a>
163 | <a href="gui.slider.html">slider</a>
164 | <a href="gui.select.html">select</a>
165 | <a href="gui.misc.html">misc</a>
167 <strong>Other</strong><br>
168 <a href="gui.menus.html">menus</a>
169 | <a href="gui.dialog.html">dialog</a>
171 <strong>Tutorials</strong><br>
172 <a href="gui1.html">1</a>
173 | <a href="gui2.html">2</a>
174 | <a href="gui3.html">3</a>
175 | <a href="gui4.html">4</a>
176 | <a href="gui5.html">5</a>
177 | <a href="gui6.html">6</a>
178 | <a href="gui7.html">7</a>
179 | <a href="gui8.html">8</a>
180 | <a href="gui9.html">9</a>
181 | <a href="gui10.html">10</a>
184 <td valign=top style='padding-left:6px;'>
187 <table class='sections' align=right>
188 <tr><th>sections</th>
189 <tr><td class='h1'><a href='#Widget'>Widget</a>
190 <tr><td class='h2'><a href='#Widget.__init__'>Widget.__init__</a>
191 <tr><td class='h2'><a href='#Widget.focus'>Widget.focus</a>
192 <tr><td class='h2'><a href='#Widget.blur'>Widget.blur</a>
193 <tr><td class='h2'><a href='#Widget.open'>Widget.open</a>
194 <tr><td class='h2'><a href='#Widget.close'>Widget.close</a>
195 <tr><td class='h2'><a href='#Widget.is_hovering'>Widget.is_hovering</a>
196 <tr><td class='h2'><a href='#Widget.resize'>Widget.resize</a>
197 <tr><td class='h2'><a href='#Widget.chsize'>Widget.chsize</a>
198 <tr><td class='h2'><a href='#Widget.update'>Widget.update</a>
199 <tr><td class='h2'><a href='#Widget.paint'>Widget.paint</a>
200 <tr><td class='h2'><a href='#Widget.repaint'>Widget.repaint</a>
201 <tr><td class='h2'><a href='#Widget.repaintall'>Widget.repaintall</a>
202 <tr><td class='h2'><a href='#Widget.reupdate'>Widget.reupdate</a>
203 <tr><td class='h2'><a href='#Widget.next'>Widget.next</a>
204 <tr><td class='h2'><a href='#Widget.previous'>Widget.previous</a>
205 <tr><td class='h2'><a href='#Widget.get_abs_rect'>Widget.get_abs_rect</a>
206 <tr><td class='h2'><a href='#Widget.connect'>Widget.connect</a>
207 <tr><td class='h2'><a href='#Widget.send'>Widget.send</a>
208 <tr><td class='h2'><a href='#Widget.event'>Widget.event</a>
209 <tr><td class='h2'><a href='#Widget.get_toplevel'>Widget.get_toplevel</a>
210 <tr><td class='h2'><a href='#Widget.collidepoint'>Widget.collidepoint</a>
222 Base class for all PGU graphical objects.
224 Example - Creating your own Widget:
226 class Draw(gui.Widget):
228 # Paint the pygame.Surface
232 # Update the pygame.Surface and return the update rects
233 return [pygame.Rect(0,0,self.rect.w,self.rect.h)]
236 # Handle the pygame.Event
239 def resize(self,width=None,height=None):
240 # Return the width and height of this widget
244 <a name="Widget.__init__">
245 <h3>Widget.__init__</h3>
247 Create a new Widget instance given the style parameters.
250 decorate -- whether to call theme.decorate(self) to allow the
251 theme a chance to decorate the widget. (default is true)
252 style -- a dict of style parameters.
253 x, y -- position parameters
254 width, height -- size parameters
255 align, valign -- alignment parameters, passed along to style
256 font -- the font to use with this widget
257 color -- the color property, if applicable
258 background -- the widget used to paint the background
259 cls -- class name as used by Theme
260 name -- name of widget as used by Form. If set, will call
261 form.add(self,name) to add the widget to the most recently
263 focusable -- True if this widget can receive focus via Tab, etc.
265 disabled -- True of this widget is disabled (defaults is False)
266 value -- initial value
270 <a name="Widget.focus">
271 <h3>Widget.focus</h3>
275 <a name="Widget.blur">
280 <a name="Widget.open">
283 Open this widget as a modal dialog.
285 <a name="Widget.close">
286 <h3>Widget.close</h3>
288 Close this widget, if it is currently an open dialog.
290 <a name="Widget.is_hovering">
291 <h3>Widget.is_hovering</h3>
293 Returns true if the mouse is hovering over this widget.
295 <a name="Widget.resize">
296 <h3>Widget.resize</h3>
298 Resize this widget and all sub-widgets, returning the new size.
300 This should be implemented by a subclass.
304 <a name="Widget.chsize">
305 <h3>Widget.chsize</h3>
307 Signal that this widget has changed its size.
309 <a name="Widget.update">
310 <h3>Widget.update</h3>
312 Updates the surface and returns a rect list of updated areas
314 This should be implemented by a subclass.
318 <a name="Widget.paint">
319 <h3>Widget.paint</h3>
321 Render this widget onto the given surface
323 This should be implemented by a subclass.
327 <a name="Widget.repaint">
328 <h3>Widget.repaint</h3>
330 Request a repaint of this Widget.
332 <a name="Widget.repaintall">
333 <h3>Widget.repaintall</h3>
335 Request a repaint of all Widgets.
337 <a name="Widget.reupdate">
338 <h3>Widget.reupdate</h3>
340 Request a reupdate of this Widget.
342 <a name="Widget.next">
345 Pass focus to next Widget.
347 Widget order determined by the order they were added to their container.
351 <a name="Widget.previous">
352 <h3>Widget.previous</h3>
354 Pass focus to previous Widget.
356 Widget order determined by the order they were added to their container.
360 <a name="Widget.get_abs_rect">
361 <h3>Widget.get_abs_rect</h3>
363 Returns the absolute rect of this widget on the App screen.
365 <a name="Widget.connect">
366 <h3>Widget.connect</h3>
368 Connect an event code to a callback function.
370 Note that there may be multiple callbacks per event code.
374 fnc -- callback function
375 *values -- values to pass to callback.
377 Please note that callbacks may also have "magicaly" parameters.
380 _event -- receive the event
381 _code -- receive the event code
382 _widget -- receive the sending widget
389 w.connect(gui.CLICK,onclick,'PGU Button Clicked')
393 <a name="Widget.send">
396 Send a code, event callback trigger.
398 <a name="Widget.event">
399 <h3>Widget.event</h3>
401 Called when an event is passed to this object.
403 Please note that if you use an event, returning the value True
404 will stop parent containers from also using the event. (For example, if
405 your widget handles TABs or arrow keys, and you don't want those to
406 also alter the focus.)
408 This should be implemented by a subclass.
412 <a name="Widget.get_toplevel">
413 <h3>Widget.get_toplevel</h3>
415 Returns the top-level widget (usually the Desktop) by following the
416 chain of 'container' references.
418 <a name="Widget.collidepoint">
419 <h3>Widget.collidepoint</h3>
421 Test if the given point hits this widget. Over-ride this function
422 for more advanced collision testing.
429 <hr width=500 align=center>
430 <div align='center'>all content (c) 2006 Phil Hassey - <a href='http://www.imitationpickles.org/pgu/'>Phil's pyGame Utilities</a></div>