Next / Previous / Contents / Shipman's homepage

6. class PageTurner

Here is the start of the actual widget class, and the formal declaration of its exported and private attributes and methods.

pageturner.py
# - - - - -   c l a s s   P a g e T u r n e r   - - - - -

class PageTurner(Frame):
    """Widget to allow user to page through a set of content pages.

      Exports:
        PageTurner ( master=None, size=None ):
          [ (master is the containing widget) and
            (size is a (width, height) tuple to get a fixed
            page viewing area of that size, or None for one
            that automatically resizes for each page) ->
              return a new PageTurner widget with those attributes
              and no content pages ]
        .pageNoEntry:       [ displays the current page number ]
        .nPagesLabel:       [ displays the number of pages ]
        .prevButton:        [ the 'Previous page' button ]
        .nextButton:        [ the 'Next page' button ]
        .headFrame:
          [ a Frame inside self for displaying page headings, if any ]
        .bodyFrame:
          [ a Frame inside self for displaying the current
            content page, if any ]
        .addPage ( f ):
          [ f is a Frame ->
              self  :=  self with f added as its next content page ]
        .setPageNo ( n ):
          [ n is a positive integer ->
             if n < (number of content pages) ->
               self  :=  self displaying page n (counting from 1)
             else -> I ]

Having described the exported interface, the balance of the documentation string for the class is a list of the contained widgets and other miscellaneous private attributes.

pageturner.py
      Included widgets:
        .__buttonFrame:     [ frame containing all operating controls ]

      Invariants:
        .__size:
          [ the size argument passed to the constructor ]
        .__pageList:
          [ a list whose members are the content pages in viewing
            order ]
        .__pageNo:
           [ if self contains any pages ->
               current page number, counting from 1
             else -> 0 ]
        .__pageNoVar:
          [ the StringVar associated with self.pageNoEntry.  Invariant:
            if len(self.__pageList) == 0 -> 0
            else -> self.__pageNo ]
        .__nPagesVar:
          [ the StringVar associated with self.nPagesLabel ]
    """

All the internal control widgets such as .nextButton, the “Next page” button, are exported so that you can configure such attributes as their fonts and colors by using the universal Tkinter widget method .configure(). Obviously this gives the caller the ability to break encapsulation rather heavily, so it would be prudent to change only superficial attributes of the control (such as background) and not critical operational attriubutes like command.

Here's the way the widgets are gridded in a PageTurner widget:

For the gridding of the controls inside the .__buttonFrame, see Section 9, “PageTurner.__createButtons(): Create the controls”.