From 7cf2d8d7395423284bb941297230b7c7ad2b261f Mon Sep 17 00:00:00 2001 From: John Wiggins Date: Mon, 15 Mar 2021 12:56:50 +0100 Subject: [PATCH 1/2] Add documentation for AbstractWindow --- docs/source/enable/abstract_window.rst | 28 +++++++++++++++++ docs/source/index.rst | 37 ++++++++++++----------- enable/abstract_window.py | 42 +++++++++++++++++++++++--- 3 files changed, 84 insertions(+), 23 deletions(-) create mode 100644 docs/source/enable/abstract_window.rst diff --git a/docs/source/enable/abstract_window.rst b/docs/source/enable/abstract_window.rst new file mode 100644 index 000000000..bd286926c --- /dev/null +++ b/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: diff --git a/docs/source/index.rst b/docs/source/index.rst index 25c4c91d0..f379e14da 100644 --- a/docs/source/index.rst +++ b/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 ----------------- diff --git a/enable/abstract_window.py b/enable/abstract_window.py index ea5ed88ff..47fa22e8d 100644 --- a/enable/abstract_window.py +++ b/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): From c501f6bc8a48abe6fa27c3ee84b73dc68bc89887 Mon Sep 17 00:00:00 2001 From: John Wiggins Date: Mon, 15 Mar 2021 14:22:02 +0100 Subject: [PATCH 2/2] PR feedback --- docs/source/enable/abstract_window.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/enable/abstract_window.rst b/docs/source/enable/abstract_window.rst index bd286926c..132fa5fd7 100644 --- a/docs/source/enable/abstract_window.rst +++ b/docs/source/enable/abstract_window.rst @@ -1,7 +1,7 @@ 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 +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.