dirtywords

commit

1381fe8016564aca420e853b585c767599df2dd6

parent

db624306159eed0c0f32c2faceef1799d11cf6d7

Author

Tobias Bengfort <tobias.bengfort@gmx.net>

Date

2014-10-07 19:29

further improve docs

Diffstat

1 files changed, 39 insertions, 12 deletions

diff --git a/dirtywords/base.py b/dirtywords/base.py

@@ -1,27 +1,51 @@
   -1     1 """
   -1     2 dirtywords is based on multiple implementations of the :py:class:`Core` class.
   -1     3 On top of that, the :py:class:`Screen`-API is implemented. This is what you
   -1     4 work with most of the time.
   -1     5 
   -1     6 The screen API is accompanied by :py:class:`Window` (a screen implementation
   -1     7 that uses an existing screen object rather than an external framework) and
   -1     8 :py:class:`AttrString` for easy string formatting.
   -1     9 
   -1    10 A new core implementation should be derived from :py:class:`Screen` and
   -1    11 must provide implementations for all low-level functions.  It may also provide
   -1    12 optimised implementations of high-level functionality.
   -1    13 
   -1    14 """
   -1    15 
   -1    16 
    1    17 from time import time
    2    18 
    3    19 
    4    20 class AttrString(unicode):
    5    21     """Unicode string with additional attributes.
    6    22 
    7    -1     emph
    8    -1         (bool) emphasis
    9    -1     strong
   10    -1         (bool) strong emphasis
   11    -1     underline
   12    -1         (bool) underline text
   13    -1     fg_color
   14    -1         (r, g, b) foreground color
   15    -1     bg_color
   16    -1         (r, g, b) background color
   -1    23     Rather than specifying formatting information with :py:meth:`Core.putstr`,
   -1    24     it is saved with the string object itself. This way the formatting can be
   -1    25     used for further computation before printing it to the screen.
   -1    26 
   -1    27     :py:class:`AttrString` is derived from :py:class:`unicode`. You need to
   -1    28     take care of proberly decoding byte-strings yourself.
   -1    29 
   -1    30     ========= ========= ================
   -1    31     name      type      description
   -1    32     ========= ========= ================
   -1    33     emph      bool      emphasis
   -1    34     strong    bool      strong emphasis
   -1    35     underline bool      underline text
   -1    36     fg_color  (r, g, b) foreground color
   -1    37     bg_color  (r, g, b) background color
   -1    38     ========= ========= ================
   17    39 
   18    40     Example::
   19    41 
   20    -1         AttrString(u'hello world!', strong=True, fg_color=(0, 255, 0))
   -1    42         AttrString(u'Hello World!', strong=True, fg_color=(0, 255, 0))
   -1    43 
   21    44 
   22    45     """
   23    46 
   24    47     def __new__(cls, s, **kwargs):
   -1    48         # TODO: there should be a TypeError on invalid kwarg
   25    49         self = super(AttrString, cls).__new__(cls, s)
   26    50         self.set_attrs(s, **kwargs)
   27    51         return self
@@ -94,7 +118,7 @@ class Core(object):
   94   118 
   95   119 
   96   120 class Screen(Core):
   97    -1     """Additional utility functions for :py:class:`Core`."""
   -1   121     """Additional text interface utilities build on top of :py:class:`Core`."""
   98   122 
   99   123     def __init__(self, height, width):
  100   124         super(Screen, self).__init__(height, width)
@@ -219,6 +243,9 @@ class Window(Screen):
  219   243         self.y = y
  220   244         self.x = x
  221   245 
   -1   246     def getch(self, blocking=True):
   -1   247         return self.parent.getch(blocking=blocking)
   -1   248 
  222   249     def get_key_events(self):
  223   250         return self.parent.get_key_events()
  224   251