Skip to content
This repository
Browse code

more work on basic widget reference

--HG--
branch : feature-sphinx
  • Loading branch information...
commit 51832b9938c9f37ff93e3a9ba0b0523c98767e8e 1 parent 756944c
Ian Ward authored July 15, 2012
22  docs/reference/widget.rst
Source Rendered
@@ -10,9 +10,10 @@ Widget
10 10
 ~~~~~~
11 11
 
12 12
 .. autoclass:: Widget
  13
+   :private-members: _invalidate, _emit
13 14
 
14  
-Basic Widgets
15  
--------------
  15
+Basic Widget Classes
  16
+--------------------
16 17
 
17 18
 Text
18 19
 ~~~~
@@ -24,8 +25,8 @@ Edit
24 25
 
25 26
 .. autoclass:: Edit
26 27
 
27  
-Decoration Widgets
28  
-------------------
  28
+Decoration Widget Classes
  29
+-------------------------
29 30
 
30 31
 AttrMap
31 32
 ~~~~~~~
@@ -57,8 +58,8 @@ SolidFill
57 58
 
58 59
 .. autoclass:: SolidFill
59 60
 
60  
-Container Widgets
61  
------------------
  61
+Container Widget Classes
  62
+------------------------
62 63
 
63 64
 Frame
64 65
 ~~~~~
@@ -94,3 +95,12 @@ Overlay
94 95
 ~~~~~~~
95 96
 
96 97
 .. autoclass:: Overlay
  98
+
  99
+Deprecated Widget Classes
  100
+-------------------------
  101
+
  102
+.. autoclass:: FlowWidget
  103
+
  104
+.. autoclass:: BoxWidget
  105
+
  106
+.. autoclass:: FixedWidget
131  urwid/widget.py
@@ -226,7 +226,7 @@ class Widget(object):
226 226
     .. attribute:: _command_map
227 227
        :annotation: = urwid.command_map
228 228
 
229  
-       A shared :class:`urwid.CommandMap` instance. May be redefined
  229
+       A shared :class:`CommandMap` instance. May be redefined
230 230
        in subclasses or widget instances.
231 231
 
232 232
     .. method:: render(size, focus=False)
@@ -236,7 +236,8 @@ class Widget(object):
236 236
           This method is not implemented in :class:`.Widget` but
237 237
           must be implemented by any concrete subclass
238 238
 
239  
-       :param size: one of the following:
  239
+       :param size: One of the following,
  240
+                    *maxcol* and *maxrow* are integers > 0:
240 241
 
241 242
                     (*maxcol*, *maxrow*)
242 243
                       for box sizing -- the parent chooses the exact
@@ -246,14 +247,12 @@ class Widget(object):
246 247
                       for flow sizing -- the parent chooses only the
247 248
                       number of columns for this widget
248 249
 
249  
-                    ``None``
  250
+                    ()
250 251
                       for fixed sizing -- this widget is a fixed size
251 252
                       which can't be adjusted by the parent
252  
-
253  
-                    *maxcol* and *maxrow* are integers > 0.
254 253
        :type size: widget size
255  
-       :param focus: set to True if this widget or one of its children
256  
-                     is in focus
  254
+       :param focus: Set to ``True`` if this widget or one of its children
  255
+                     is in focus.
257 256
        :type focus: bool
258 257
 
259 258
        :returns: A :class:`Canvas` subclass instance containing the
@@ -292,7 +291,7 @@ class Widget(object):
292 291
 
293 292
        See :meth:`Widget.render` for parameter details.
294 293
 
295  
-       :returns: the number of rows required for this widget given a number
  294
+       :returns: The number of rows required for this widget given a number
296 295
                  of columns in *size*
297 296
 
298 297
        This is the method flow widgets use to communicate their size to other
@@ -316,7 +315,9 @@ class Widget(object):
316 315
        .. note::
317 316
 
318 317
           This method is not implemented in :class:`.Widget` but
319  
-          must be implemented by any selectable widget.  See :meth:`.selectable`.
  318
+          must be implemented by any selectable widget.
  319
+          See :meth:`.selectable`.
  320
+
320 321
        :param size: See :meth:`Widget.render` for details.
321 322
        :type size: widget size
322 323
        :param key: a single keystroke value
@@ -350,18 +351,18 @@ class Widget(object):
350 351
 
351 352
        :param size: See :meth:`Widget.render` for details.
352 353
        :type size: widget size
353  
-       :param event: values such as ``'mouse press'``, ``'ctrl mouse press'``,
  354
+       :param event: Values such as ``'mouse press'``, ``'ctrl mouse press'``,
354 355
                      ``'mouse relase'``, ``'meta mouse release'``,
355 356
                      ``'mouse drag'``
356 357
        :type size: mouse event
357 358
        :param button: 1 through 5 for press events, often 0 for release events
358 359
                       (which button was released is often not known)
359 360
        :type button: int
360  
-       :param col: column of the event, 0 is the left edge of this widget
  361
+       :param col: Column of the event, 0 is the left edge of this widget
361 362
        :type col: int
362  
-       :param row: row of the event, 0 it the top row of this widget
  363
+       :param row: Row of the event, 0 it the top row of this widget
363 364
        :type row: int
364  
-       :param focus: set to True if this widget or one of its children
  365
+       :param focus: Set to ``True`` if this widget or one of its children
365 366
                      is in focus
366 367
        :type focus: bool
367 368
 
@@ -441,20 +442,10 @@ class Widget(object):
441 442
                  *row*, ``False`` otherwise
442 443
     """
443 444
     __metaclass__ = WidgetMeta
444  
-    """attributed :class:`WidgetMeta`"""
445 445
 
446 446
     _selectable = False
447  
-    """whether or not this is a selectable widget"""
448  
-
449 447
     _sizing = frozenset([FLOW, BOX, FIXED])
450  
-    """sizing-type of this widget: one of 'flow', 'box' or 'fixed'"""
451  
-
452 448
     _command_map = command_map
453  
-    """attributed :class:`urwid.CommandMap`
454  
-
455  
-       This is a shared :class:`urwid.CommandMap` instance,
456  
-       which means... TODO
457  
-    """
458 449
 
459 450
     def _invalidate(self):
460 451
         """
@@ -472,16 +463,17 @@ def _emit(self, name, *args):
472 463
 
473 464
     def selectable(self):
474 465
         """
475  
-        Return ``True`` if this is a widget that is designed to take the focus,
476  
-        i.e. it contains something the user might want to interact with.
  466
+        :returns: ``True`` if this is a widget that is designed to take the
  467
+                  focus, i.e. it contains something the user might want to
  468
+                  interact with, ``False`` otherwise,
477 469
 
478  
-        This default implementation returns ``self._selectable`` and
479  
-        :attr:`_selectable` is set to ``False``.  Subclasses may leave these
480  
-        is if the are not selectable, or if they are always selectable they may
  470
+        This default implementation returns :attr:`._selectable`.
  471
+        Subclasses may leave these is if the are not selectable,
  472
+        or if they are always selectable they may
481 473
         set the :attr:`_selectable` class variable to ``True``.
482 474
 
483  
-        If this method returns ``True`` then the :meth:`keypress` method must be
484  
-        implemented.
  475
+        If this method returns ``True`` then the :meth:`.keypress` method
  476
+        must be implemented.
485 477
 
486 478
         Returning ``False`` does not guarantee that this widget will never be in
487 479
         focus, only that this widget will usually be skipped over when changing
@@ -492,9 +484,9 @@ def selectable(self):
492 484
 
493 485
     def sizing(self):
494 486
         """
495  
-        Return a frozenset including one or more of ``'box'``, ``'flow'`` and
496  
-        ``'fixed'``.  Default implementation returns the value of
497  
-        :attr:`._sizing`, which for this class includes all three.
  487
+        :returns: A frozenset including one or more of ``'box'``, ``'flow'`` and
  488
+                  ``'fixed'``.  Default implementation returns the value of
  489
+                  :attr:`._sizing`, which for this class includes all three.
498 490
 
499 491
         The sizing modes returned indicate the modes that may be
500 492
         supported by this widget, but is not sufficient to know
@@ -508,15 +500,15 @@ def sizing(self):
508 500
 
509 501
         If ``'flow'`` is among the values returned then the other
510 502
         methods in this widget must be able to accept a
511  
-        single-element tuple ``(maxcol,)`` to their ``size``
  503
+        single-element tuple (*maxcol*,)`` to their ``size``
512 504
         parameter, and the :meth:`rows` method must be defined.
513 505
 
514 506
         If ``'box'`` is among the values returned then the other
515 507
         methods must be able to accept a two-element tuple
516  
-        ``(maxcol, maxrow)`` to their size paramter.
  508
+        (*maxcol*, *maxrow*) to their size paramter.
517 509
 
518 510
         If ``'fixed'`` is among the values returned then the other
519  
-        methods must be able to accept an empty tuple ``()`` to
  511
+        methods must be able to accept an empty tuple () to
520 512
         their size parameter, and the :meth:`pack` method must
521 513
         be defined.
522 514
         """
@@ -524,21 +516,27 @@ def sizing(self):
524 516
 
525 517
     def pack(self, size, focus=False):
526 518
         """
527  
-        Return a "packed" size ``(maxcol, maxrow)`` for this widget, a minimum
  519
+        See :meth:`Widget.render` for parameter details.
  520
+
  521
+        :returns: A "packed" size (*maxcol*, *maxrow*) for this widget
  522
+
  523
+        Calculate and return a minimum
528 524
         size where all content could still be displayed. Fixed widgets must
529 525
         implement this method and return their size when ``()`` is passed as the
530 526
         *size* parameter.
531 527
 
532 528
         This default implementation returns the *size* passed, or the *maxcol*
533  
-        passed and the value of :meth:`rows` as the *maxrow* when ``(maxcol,)``
  529
+        passed and the value of :meth:`rows` as the *maxrow* when (*maxcol*,)
534 530
         is passed as the *size* parameter.
535 531
 
536  
-        This is a new method that hasn't been fully implemented across the
537  
-        standard widget types. In particular it has not yet been implemented for
538  
-        container widgets.
  532
+        .. note::
539 533
 
540  
-        :class:`.Text` widgets :meth:`have implemented this method
541  
-        <.Text.pack>`. You can use :meth:`pack` to calculate the minumum
  534
+           This is a new method that hasn't been fully implemented across the
  535
+           standard widget types. In particular it has not yet been
  536
+           mplemented for container widgets.
  537
+
  538
+        :class:`Text` widgets have implemented this method.
  539
+        You can use :meth:`Text.pack` to calculate the minumum
542 540
         columns and rows required to display a text widget without wrapping,
543 541
         or call it iteratively to calculate the minimum number of columns
544 542
         required to display the text wrapped into a target number of rows.
@@ -557,24 +555,25 @@ def pack(self, size, focus=False):
557 555
         return size
558 556
 
559 557
     base_widget = property(lambda self:self, doc="""
560  
-        Step through decoration widgets and return the one at the
561  
-        base.  This default implementation is equivalent to self.
  558
+        Read-only property that steps through decoration widgets
  559
+        and returns the one at the base.  This default implementation
  560
+        returns self.
562 561
         """)
563 562
 
564 563
     focus = property(lambda self:None, doc="""
565  
-        Container widgets' implementations will give their child
566  
-        widget that is in focus.  This default implementation is
567  
-        always None, indicating that this widget has no children.
  564
+        Read-only property returning the child widget in focus for
  565
+        container widgets.  This default implementation
  566
+        always returns ``None``, indicating that this widget has no children.
568 567
         """)
569 568
 
570 569
     def _not_a_container(self, val=None):
571 570
         raise IndexError(
572 571
             "No focus_position, %r is not a container widget" % self)
573 572
     focus_position = property(_not_a_container, _not_a_container, doc="""
574  
-        raises IndexError.  This default property makes accessing
575  
-        .focus_position on non-container widgets fail in the same
576  
-        way it would when accesing .focus_position on an empty
577  
-        container.
  573
+        Property for reading and setting the focus position for
  574
+        container widgets. This default implementation raises
  575
+        :exc:`IndexError`, making normal widgets fail the same way
  576
+        accessing :attr:`.focus_position` on an empty container widget would.
578 577
         """)
579 578
 
580 579
     def __repr__(self):
@@ -693,7 +692,7 @@ class Divider(Widget):
693 692
     def __init__(self,div_char=u" ",top=0,bottom=0):
694 693
         """
695 694
         :param div_char: character to repeat across line
696  
-        :type div_char: string
  695
+        :type div_char: bytes or unicode
697 696
 
698 697
         :param top: number of blank lines above
699 698
         :type top: int
@@ -764,7 +763,7 @@ class SolidFill(BoxWidget):
764 763
     def __init__(self, fill_char=" "):
765 764
         """
766 765
         :param fill_char: character to fill area with
767  
-        :type fill_char: string
  766
+        :type fill_char: bytes or unicode
768 767
 
769 768
         >>> SolidFill(u'8')
770 769
         <SolidFill box widget '8'>
@@ -900,11 +899,11 @@ def get_text(self):
900 899
         return self._text, self._attrib
901 900
 
902 901
     text = property(lambda self:self.get_text()[0], doc="""
903  
-        read-only property returning the complete bytes/unicode content
  902
+        Read-only property returning the complete bytes/unicode content
904 903
         of this widget
905 904
         """)
906 905
     attrib = property(lambda self:self.get_text()[1], doc="""
907  
-        read-only property returning the run-length encoded display
  906
+        Read-only property returning the run-length encoded display
908 907
         attributes of this widget
909 908
         """)
910 909
 
@@ -1196,7 +1195,7 @@ def get_text(self):
1196 1195
             return self._caption + self._edit_text, self._attrib
1197 1196
         else:
1198 1197
             return self._caption + (self._mask * len(self._edit_text)), self._attrib
1199  
-    
  1198
+
1200 1199
     def set_text(self, markup):
1201 1200
         """
1202 1201
         Not supported by Edit widget.
@@ -1219,7 +1218,7 @@ def set_text(self, markup):
1219 1218
     def get_pref_col(self, size):
1220 1219
         """
1221 1220
         Return the preferred column for the cursor, or the
1222  
-        current cursor x value.  May also return 'left' or 'right'
  1221
+        current cursor x value.  May also return ``'left'`` or ``'right'``
1223 1222
         to indicate the leftmost or rightmost column available.
1224 1223
 
1225 1224
         This method is used internally and by other widgets when
@@ -1229,7 +1228,7 @@ def get_pref_col(self, size):
1229 1228
         >>> size = (10,)
1230 1229
         >>> Edit().get_pref_col(size)
1231 1230
         0
1232  
-        >>> e = Edit("","word")
  1231
+        >>> e = Edit(u"", u"word")
1233 1232
         >>> e.get_pref_col(size)
1234 1233
         4
1235 1234
         >>> e.keypress(size, 'left')
@@ -1238,7 +1237,7 @@ def get_pref_col(self, size):
1238 1237
         >>> e.keypress(size, 'end')
1239 1238
         >>> e.get_pref_col(size)
1240 1239
         'right'
1241  
-        >>> e = Edit("","2\\nwords")
  1240
+        >>> e = Edit(u"", u"2\\nwords")
1242 1241
         >>> e.keypress(size, 'left')
1243 1242
         >>> e.keypress(size, 'up')
1244 1243
         >>> e.get_pref_col(size)
@@ -1371,7 +1370,9 @@ def get_edit_text(self):
1371 1370
         """
1372 1371
         return self._edit_text
1373 1372
 
1374  
-    edit_text = property(get_edit_text, set_edit_text)
  1373
+    edit_text = property(get_edit_text, set_edit_text, doc="""
  1374
+        Read-only property returning the edit text for this widget.
  1375
+        """)
1375 1376
 
1376 1377
     def insert_text(self, text):
1377 1378
         """
@@ -1647,7 +1648,7 @@ def get_line_translation(self, maxcol, ta=None ):
1647 1648
 
1648 1649
     def get_cursor_coords(self, size):
1649 1650
         """
1650  
-        Return the (x,y) coordinates of cursor within widget.
  1651
+        Return the (*x*, *y*) coordinates of cursor within widget.
1651 1652
 
1652 1653
         >>> Edit("? ","yes").get_cursor_coords((10,))
1653 1654
         (5, 0)
@@ -1660,7 +1661,7 @@ def get_cursor_coords(self, size):
1660 1661
 
1661 1662
     def position_coords(self,maxcol,pos):
1662 1663
         """
1663  
-        Return (x,y) coordinates for an offset into self.edit_text.
  1664
+        Return (*x*, *y*) coordinates for an offset into self.edit_text.
1664 1665
         """
1665 1666
 
1666 1667
         p = pos + len(self.caption)
@@ -1669,10 +1670,6 @@ def position_coords(self,maxcol,pos):
1669 1670
         return x,y
1670 1671
 
1671 1672
 
1672  
-
1673  
-
1674  
-
1675  
-
1676 1673
 class IntEdit(Edit):
1677 1674
     """Edit widget for integer values"""
1678 1675
 

0 notes on commit 51832b9

Please sign in to comment.
Something went wrong with that request. Please try again.