TODO items for PLIB as of Version 0.7.1

:Author:        Peter A. Donis
:Last Updated:  14 April 2011

Planned Features
----------------

- Add Python 3.0 version (will be found on PyPI as
  the ``plib3`` package).

- Add Win32 (using the PyWin32 extensions) to the list
  of toolkits supported by ``plib.gui``.

- Add Cocoa (Mac OS X GUI framework) to the list of
  toolkits supported by ``plib.gui``.

- Add find/replace functionality to ``PEditControl``.

- Add image and movie display widgets to ``plib.gui``.

- Add an HTML browser widget to ``plib.gui``.

- Change code in ``plib.gui.specs`` and associated
  machinery elsewhere in ``plib.gui`` so that the GUI
  modules are not imported when the specs module is
  imported, but only when specific widgets are actually
  instantiated.

- Need a better built-in way to add new constants to
  ``plib.gui.defs`` and adjust the variables in
  ``plib.gui.common`` appropriately (the current
  incantations needed are in ``scrips-edit.py`` and
  are too hackish). This will also fix a bug where
  overriding labels or icons for the standard actions
  does so everywhere, including standard dialogs
  where that is not desired.

- Is tri-state check box support really needed? Or
  can it be factored out into a separate class
  (``PTriStateCheckBox``)?

- Add center/right justify options to ``PTextLabel``
  (maybe also vertical alignment options).

- The status bar "custom widgets" may be too much;
  may only need to allow more text fields after the
  first, with some way of getting/setting the text.
  Also, add an example program that demonstrates the
  status bar functionality.

- Add a ``WEB`` (or ``WWW``) GUI toolkit that allows the
  same declarative method of specifying a GUI to be used
  in web applications.

- Publish and enforce standard interfaces for widget events
  (each toolkit does them a bit differently, need to hide
  this under a common layer).

- Make sure that coverage is complete for common widget
  methods.

- Enforce consistent ordering of base classes for widgets.

- Enforce consistent handling of class and instance variables
  (e.g., the ``_parent`` variable should be set in the same
  place for all widgets)--this applies particularly to the
  GTK toolkit (lots of cruft in there).

- Find a way to have the actual GUI widgets (from the chosen
  toolkit) take their docstrings from the base widgets (which
  define the API).

- When Python adds the capability, have the ``ModuleProxy``
  class provide a ``__dir__`` method (or whatever the final
  mechanism is) so that it can provide more information about
  what attributes are available.

- Is there a way to refactor the ``PLIB.XML`` sub-package so
  that DTD generation is an overlay that can be imported only
  when it is needed?

- Enforce common conventions for method and attribute names.

- Make ``plib.test`` importable as a package (currently when
  I try this it breaks the automatic inclusion of doctest
  test files, so that needs to be figured out first).

- Add test coverage for the ``plib.stdlib.options`` module.

- Add test coverage for any other modules not covered.

Bugs/Workaround Fixes
---------------------

- In KDE 3, displaying dialogs sometimes causes a segfault
  when there is a NotifierClient in use; other than that, what
  conditions trigger the segfault are not entirely clear, nor
  are they entirely consistent (e.g., for a while I saw them
  on my KDE 3.5.10 machine, but not on a KDE 3.5.5 one; but
  after some more code adjustments the pattern reversed???),
  so no workaround is implemented yet. The cause is probably
  some interaction between the dialog's local event loop and
  the socket notifier, since the segfault never appears if
  there is no notifier in use.

- In later KDE 3 and Qt 3 versions (KDE 3.5.10, Qt 3.3.8 on the
  machine where I've observed this), the mechanisms for adding
  toolbar separators that work in earlier versions appear to
  no longer work. (Note: This is not always observed; it seems
  to depend on the Linux distribution, so it may be a bug in
  some distros' Qt packages.)

- The Qt 3 list view widget header column alignment doesn't
  work; there doesn't appear to be any API to do it. The table
  widget column alignment also doesn't work in Qt 3, for either
  the header *or* the widget itself; again, there doesn't seem
  to be any API to do it.

- There appears to be no way to get an entire row of the Qt 3
  table widget to repaint itself when the text color changes
  (it repaints fine when the background color changes).

- In Qt 4 on Windows, it's even weirder: the text color change
  repaints fine, and so does the background color change,
  *except* for the first table row! ???

- Read-only widgets are still in the tab order in Qt/KDE
  (disabled widgets aren't, but the point of read-only widgets
  is to not have user input but look normal, not greyed out).

- Setting background color doesn't appear to work correctly for
  all Qt/KDE 4 widgets.

- Some KDE standard actions don't appear to behave
  consistently with the documentation.

- The wxWidgets "stock" item behavior seems inconsistent;
  the stock item doesn't always override a custom caption
  and image for menu and toolbar items, even though it
  should based on comparison with the corresponding GTK
  code.

- The wx list view column alignment doesn't work (there is an
  API function but it appears to be broken).

- The wx table column alignment doesn't work (there appears
  to be an API function but no documentation about what the
  alignment arguments should be; experimentation has not yet
  figured this out).

- The wxWidgets tab widget is firing a tab changed
  event on shutdown, after the status bar has been
  deleted (causes exception in ``pxmlview.py``--currently
  a hack is being used to mask this).

- The wx window background colors seem all messed up with
  certain color schemes in effect.

- The wx and GTK edit controls don't appear to have APIs for
  some of the desired functionality in the ``pnotepad``
  example program.

- The tab key doesn't move between controls in wx and GTK.

- The wx and GTK table widgets don't appear to give good sizing
  information for a main window to wrap to them as a client.

- The GTK top window doesn't set its coordinates in the
  settings file correctly; it always returns 0, 0 for its
  left, top coordinates. (GTK in general seems to make it
  very fscking difficult to get information that would seem
  pretty basic and is easy to get in other toolkits.)

- The GTK message dialog doesn't work correctly
  with OK/Cancel buttons; both buttons appear to
  return the "OK" response.

- The GTK file open/save dialogs won't open; need
  bug fix (parent window of dialog seems incorrect).

- The current GUI layout code does not support setting
  different margins for top/bottom vs. left/right sides
  of a panel; this is because there is no easy way to
  do this in GTK. As a result, currently if margins are
  not set all around, buttons and combos in GTK will
  expand to the edge of their containing panel, which is
  usually not what is wanted. The only workarounds are
  to use margins on all sides (meaning a little extra
  spacing at the edges of panels that contain buttons
  and combos) or to enclose each individual button and
  combo in its own panel (which is messy).

- The GTK list view column alignment and column auto-sizing
  doesn't work.

- The GTK table widget is much too crude. If I can figure
  out workarounds for the quirks of wxWidgets when using
  GTK under the hood, this issue will probably be what
  drives me to drop direct GTK support in ``PLIB.GUI``.

- The forking socket server in ``plib.stdlib.io.blocking``
  doesn't work on Windows. Forking in general on Windows
  is a chancy business, but the basic forking functionality
  in PLIB works OK there; it just coughs and dies whenever
  the forking server tries to fork a request handler.
  (Probably it's because the pickler that is used by the
  multiprocessing module to set up the child process is
  being streched too far, since it's trying to pickle the
  entire server context and then unpickle it in the child
  process for the request handler; the multiprocessing
  module was not really designed for that.) Since I don't
  recommend running servers in general on Windows, much
  less forking ones (the threading server in the PLIB I/O
  library works OK if you simply *must*), I'm not in a
  hurry to fix all this, but it is a current bug. (All of
  the tests involving the forking server are disabled on
  Windows.)

- Various async I/O tests are failing on Windows, for
  reasons that aren't clear; the basic async I/O functionality
  appears to work (at least when tested using the example
  ``echo_server.py`` and ``chat_server.py`` programs).

- All of the "large message" I/O tests fail on Windows
  (i.e., any test where the message being transferred over
  a socket is larger than the socket buffer size). I
  suspect this is because of subtle differences in socket
  semantics on Windows, but haven't been able to pin it
  down. (Windows advocates may wonder why I'm singling out
  Windows here, but the reason is simple: all of the above
  tests and functionality that has problems or bugs on
  Windows, *just works* on *every* other platform I've
  tested on--various flavors of Linux, Mac OS X, and
  FreeBSD, using various Python 2.x versions--2.4, 2.5, 2.6,
  and 2.7. Windows is the *only* OS that requires all these
  extra gymnastics for what is just basic programming
  everywhere else, and then it *still* doesn't always work.)
