Add documentation for AbstractWindow

docs/source/enable/abstract_window.rst

@@ -0,0 +1,28 @@
+Top-level Windows
+=================
+When a component is shown on screen via a GUI toolkit, its :attr:`window` trait
+contains an instance of :class:`~.AbstractWindow` which serves as a delegate
+between the underlying window system and the component.
+
+For the most part, code doesn't need to interact with the underlying window.
+However one common exception is tools which want to set a custom cursor. This
+is accomplished via the :py:meth:`set_pointer` method.
+
+AbstractWindow
+--------------
+The following methods are the public interface of :class:`AbstractWindow`.
+
+.. automethod:: enable.abstract_window.AbstractWindow.get_pointer_position
+  :noindex:
+
+.. automethod:: enable.abstract_window.AbstractWindow.redraw
+  :noindex:
+
+.. automethod:: enable.abstract_window.AbstractWindow.set_mouse_owner
+  :noindex:
+
+.. automethod:: enable.abstract_window.AbstractWindow.set_pointer
+  :noindex:
+
+.. automethod:: enable.abstract_window.AbstractWindow.set_tooltip
+  :noindex:

docs/source/index.rst

@@ -4,24 +4,25 @@ Enable Documentation
 .. toctree::
   :maxdepth: 2
 
-  kiva/overview.rst
-  kiva/backends.rst
-  kiva/fonts.rst
-  kiva/compiled_path.rst
-  kiva/images.rst
-  kiva/state.rst
-  kiva/quickref.rst
-  kiva_tutorial/index.rst
-
-  enable/overview.rst
-  enable/constraints_layout.rst
-  enable/key_events.rst
-  enable/basic_tools.rst
-  enable/drag_and_drop.rst
-  enable/undo_redo.rst
-  enable/toolkit_selection.rst
-
-  credits.rst
+  kiva/overview
+  kiva/backends
+  kiva/fonts
+  kiva/compiled_path
+  kiva/images
+  kiva/state
+  kiva/quickref
+  kiva_tutorial/index
+
+  enable/overview
+  enable/abstract_window
+  enable/constraints_layout
+  enable/key_events
+  enable/basic_tools
+  enable/drag_and_drop
+  enable/undo_redo
+  enable/toolkit_selection
+
+  credits
 
 API Documentation
 -----------------

enable/abstract_window.py

@@ -168,7 +168,14 @@ def _window_paint(self, event):
         raise NotImplementedError
 
     def set_pointer(self, pointer):
-        "Sets the current cursor shape"
+        """ Sets the current cursor shape.
+
+        Parameters
+        ----------
+        pointer: str
+            The name of the cursor shape. Valid values are in
+            :py:attr:`enable.toolkit_constants.pointer_names`
+        """
         raise NotImplementedError
 
     def set_timer_interval(self, component, interval):
@@ -184,7 +191,13 @@ def screen_to_window(self, x, y):
         raise NotImplementedError
 
     def get_pointer_position(self):
-        "Returns the current pointer position in local window coordinates"
+        """ Returns the current pointer position in local window coordinates.
+
+        Returns
+        -------
+        (x, y) : tuple
+            The x,y position of the mouse
+        """
         raise NotImplementedError
 
     # ------------------------------------------------------------------------
@@ -245,7 +258,20 @@ def component_bounds_updated(self, event):
         pass
 
     def set_mouse_owner(self, mouse_owner, transform=None, history=None):
-        "Handle the 'mouse_owner' being changed"
+        """ Handle the 'mouse_owner' being changed
+
+        Parameters
+        ----------
+        mouse_owner : :class:`Component` or None
+            The new "mouse owner" component. This component will receive all
+            key and mouse events until a new mouse owner is set.
+        transform : 3x3 :class:`ndarray` or None
+            An affine transform which is applied to events before dispatch
+        history : list of :class:`Interactor` or None
+            A list of interactors which is used to build a tranform
+            (via :py:meth:`get_event_transform`) to be applied to events before
+            dispatch.
+        """
         if mouse_owner is None:
             self._release_mouse()
             self.mouse_owner = None
@@ -452,8 +478,14 @@ def _handle_drag_event(self, event_name, event, set_focus=False):
 
         return drag_event.handled
 
-    def set_tooltip(self, components):
-        "Set the window's tooltip (if necessary)"
+    def set_tooltip(self, tooltip):
+        """ Set the window's tooltip (if necessary)
+
+        Parameters
+        ----------
+        tooltip : str
+            The tooltip text.
+        """
         raise NotImplementedError
 
     def redraw(self):