Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 1e8af47

Browse files
farizafariza
committed
Adding doc to base methods
1 parent b4d5fcf commit 1e8af47

5 files changed

Lines changed: 363 additions & 33 deletions

File tree

‎doc/api/backend_tools_api.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
2+
:mod:`matplotlib.backend_tools`
3+
================================
4+
5+
.. automodule:: matplotlib.backend_tools
6+
:members:
7+
:undoc-members:
8+
:show-inheritance:

‎doc/api/index_backend_api.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ backends
55
.. toctree::
66

77
backend_bases_api.rst
8+
backend_tools_api.rst
89
backend_gtkagg_api.rst
910
backend_qt4agg_api.rst
1011
backend_wxagg_api.rst

‎lib/matplotlib/backend_bases.py‎

Lines changed: 204 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,14 @@
2525
the 'show' callable is then set to Show.__call__, inherited from
2626
ShowBase.
2727
28+
:class:`NavigationBase`
29+
The base class for the Navigation class that makes the bridge between
30+
user interaction (key press, toolbar clicks, ..) and the actions in
31+
response to the user inputs.
32+
33+
:class:`ToolbarBase`
34+
The base class for the Toolbar class of each interactive backend.
35+
2836
"""
2937

3038
from __future__ import (absolute_import, division, print_function,
@@ -3218,6 +3226,25 @@ def set_history_buttons(self):
32183226

32193227

32203228
class NavigationBase(object):
3229+
""" Helper class that groups all the user interactions for a FigureManager
3230+
3231+
Attributes
3232+
----------
3233+
canvas : `FigureCanvas` instance
3234+
toolbar : `Toolbar` instance that is controlled by this `Navigation`
3235+
keypresslock : `LockDraw` to direct the `canvas` key_press_event
3236+
movelock: `LockDraw` to direct the `canvas` motion_notify_event
3237+
presslock: `LockDraw` to direct the `canvas` button_press_event
3238+
releaselock: `LockDraw` to direct the `canvas` button_release_event
3239+
canvaslock: shortcut to `canvas.widgetlock`
3240+
3241+
Notes
3242+
--------_
3243+
The following methos are for implementation pourposes and not for user use
3244+
For these reason they are defined as **_methodname** (private)
3245+
3246+
.. automethod:: _toolbar_callback
3247+
"""
32213248
_default_cursor = cursors.POINTER
32223249
_default_tools = [tools.ToolToggleGrid,
32233250
tools.ToolToggleFullScreen,
@@ -3286,13 +3313,43 @@ def _get_toolbar(self, toolbar, canvas):
32863313
return toolbar
32873314

32883315
def get_active(self):
3316+
"""Get the active tools
3317+
3318+
Returns
3319+
----------
3320+
A dictionary with the following elements
3321+
* `toggled`: The currently toggled Tool or None
3322+
* `instances`: List of the currently active tool instances
3323+
that are registered with Navigation
3324+
3325+
"""
32893326
return {'toggled': self._toggled, 'instances': self._instances.keys()}
32903327

32913328
def get_tool_keymap(self, name):
3329+
"""Get the keymap associated with a tool
3330+
3331+
Parameters
3332+
----------
3333+
name : string
3334+
Name of the Tool
3335+
3336+
Returns
3337+
----------
3338+
Keymap : list of keys associated with the Tool
3339+
"""
32923340
keys = [k for k, i in self._keys.items() if i == name]
32933341
return keys
32943342

32953343
def set_tool_keymap(self, name, *keys):
3344+
"""Set the keymap associated with a tool
3345+
3346+
Parameters
3347+
----------
3348+
name : string
3349+
Name of the Tool
3350+
keys : keys to associated with the Tool
3351+
"""
3352+
32963353
if name not in self._tools:
32973354
raise AttributeError('%s not in Tools' % name)
32983355

@@ -3308,50 +3365,79 @@ def set_tool_keymap(self, name, *keys):
33083365
self._keys[k] = name
33093366

33103367
def unregister(self, name):
3368+
"""Unregister the tool from the active instances
3369+
3370+
Notes
3371+
-----
3372+
This method is used by `PersistentTools` to remove the reference kept
3373+
by `Navigation`.
3374+
3375+
It is usually called by the `deactivate` method or during
3376+
destroy if it is a graphical Tool.
3377+
3378+
If called, next time the `Tool` is used it will be reinstantiated instead
3379+
of using the existing instance.
3380+
"""
33113381
if self._toggled == name:
33123382
self._handle_toggle(name, from_toolbar=False)
33133383
if name in self._instances:
33143384
del self._instances[name]
33153385

33163386
def remove_tool(self, name):
3387+
"""Remove tool from the `Navigation`
3388+
3389+
Parameters
3390+
----------
3391+
name : string
3392+
Name of the Tool
3393+
"""
33173394
self.unregister(name)
33183395
del self._tools[name]
33193396
keys = [k for k, v in self._keys.items() if v == name]
33203397
for k in keys:
33213398
del self._keys[k]
33223399

33233400
if self.toolbar:
3324-
self.toolbar.remove_toolitem(name)
3401+
self.toolbar._remove_toolitem(name)
3402+
3403+
def add_tool(self, tool):
3404+
"""Add tool to `Navigation`
33253405
3326-
def add_tool(self, callback_class):
3327-
tool = self._get_cls_to_instantiate(callback_class)
3328-
name = tool.name
3406+
Parameters
3407+
----------
3408+
tool : string or `Tool` class
3409+
Reference to find the class of the Tool to be added
3410+
"""
3411+
tool_cls = self._get_cls_to_instantiate(tool)
3412+
name = tool_cls.name
33293413
if name is None:
3330-
warnings.warn('Tools need a name to be added, it is used as ID')
3414+
warnings.warn('tool_clss need a name to be added, it is used '
3415+
'as ID')
33313416
return
33323417
if name in self._tools:
3333-
warnings.warn('A tool with the same name already exist, not added')
3418+
warnings.warn('A tool_cls with the same name already exist, '
3419+
'not added')
33343420

33353421
return
33363422

3337-
self._tools[name] = tool
3338-
if tool.keymap is not None:
3339-
for k in validate_stringlist(tool.keymap):
3423+
self._tools[name] = tool_cls
3424+
if tool_cls.keymap is not None:
3425+
for k in validate_stringlist(tool_cls.keymap):
33403426
if k in self._keys:
33413427
warnings.warn('Key %s changed from %s to %s' %
33423428
(k, self._keys[k], name))
33433429
self._keys[k] = name
33443430

3345-
if self.toolbar and tool.position is not None:
3431+
if self.toolbar and tool_cls.position is not None:
33463432
basedir = os.path.join(rcParams['datapath'], 'images')
3347-
if tool.image is not None:
3348-
fname = os.path.join(basedir, tool.image + '.png')
3433+
if tool_cls.image is not None:
3434+
fname = os.path.join(basedir, tool_cls.image + '.png')
33493435
else:
33503436
fname = None
3351-
self.toolbar.add_toolitem(name, tool.description,
3437+
self.toolbar._add_toolitem(name, tool_cls.description,
33523438
fname,
3353-
tool.position,
3354-
tool.toggle)
3439+
tool_cls.position,
3440+
tool_cls.toggle)
33553441

33563442
def _get_cls_to_instantiate(self, callback_class):
33573443
if isinstance(callback_class, basestring):
@@ -3401,7 +3487,18 @@ def _get_instance(self, name):
34013487

34023488
return self._instances[name]
34033489

3404-
def toolbar_callback(self, name):
3490+
def _toolbar_callback(self, name):
3491+
"""Callback for the `Toolbar`
3492+
3493+
All Toolbar implementations have to call this method to signal that a
3494+
toolitem was clicked on
3495+
3496+
Parameters
3497+
----------
3498+
name : string
3499+
Name of the tool that was activated (click) by the user using the
3500+
toolbar
3501+
"""
34053502
tool = self._tools[name]
34063503
if tool.toggle:
34073504
self._handle_toggle(name, from_toolbar=True)
@@ -3414,7 +3511,7 @@ def toolbar_callback(self, name):
34143511
def _handle_toggle(self, name, event=None, from_toolbar=False):
34153512
#toggle toolbar without callback
34163513
if not from_toolbar and self.toolbar:
3417-
self.toolbar.toggle(name, False)
3514+
self.toolbar._toggle(name, False)
34183515

34193516
instance = self._get_instance(name)
34203517
if self._toggled is None:
@@ -3427,7 +3524,7 @@ def _handle_toggle(self, name, event=None, from_toolbar=False):
34273524

34283525
else:
34293526
if self.toolbar:
3430-
self.toolbar.toggle(self._toggled, False)
3527+
self.toolbar._toggle(self._toggled, False)
34313528

34323529
self._get_instance(self._toggled).deactivate(None)
34333530
instance.activate(None)
@@ -3437,6 +3534,7 @@ def _handle_toggle(self, name, event=None, from_toolbar=False):
34373534
a.set_navigate_mode(self._toggled)
34383535

34393536
def list_tools(self):
3537+
"""Print the list the tools controlled by `Navigation`"""
34403538
print ('_' * 80)
34413539
print ("{0:20} {1:50} {2}".format('Name (id)', 'Tool description',
34423540
'Keymap'))
@@ -3583,29 +3681,113 @@ def draw_rubberband(self, event, x0, y0, x1, y1):
35833681

35843682

35853683
class ToolbarBase(object):
3684+
"""Base class for `Toolbar` implementation
3685+
3686+
Attributes
3687+
----------
3688+
manager : `FigureManager` instance that integrates this `Toolbar`
3689+
3690+
Notes
3691+
-----
3692+
The following methos are for implementation pourposes and not for user use.
3693+
For these reason they are defined as **_methodname** (private)
3694+
3695+
.. automethod:: _toggle
3696+
.. automethod:: _add_toolitem
3697+
.. automethod:: _remove_toolitem
3698+
"""
35863699
def __init__(self, manager):
35873700
self.manager = manager
35883701

3589-
def add_toolitem(self, name, description, image_file, position,
3702+
def _add_toolitem(self, name, description, image_file, position,
35903703
toggle):
3704+
"""Add a toolitem to the toolbar
3705+
3706+
The callback associated with the button click event,
3707+
must be **EXACTLY** `self.manager.navigation._toolbar_callback(name)`
3708+
3709+
Parameters
3710+
----------
3711+
name : string
3712+
Name of the tool to add, this is used as ID and as default label
3713+
of the buttons
3714+
description : string
3715+
Description of the tool, used for the tooltips
3716+
image_file : string
3717+
Filename of the image for the button or `None`
3718+
position : integer
3719+
Position of the toolitem within the other toolitems
3720+
if -1 at the End
3721+
toggle : bool
3722+
* `True` : The button is a toggle (change the pressed/unpressed
3723+
state between consecutive clicks)
3724+
* `False` : The button is a normal button (returns to unpressed
3725+
state after release)
3726+
"""
35913727
raise NotImplementedError
35923728

35933729
def add_separator(self, pos):
3730+
"""Add a separator
3731+
3732+
Parameters
3733+
----------
3734+
pos : integer
3735+
Position where to add the separator within the toolitems
3736+
if -1 at the end
3737+
"""
35943738
pass
35953739

35963740
def set_message(self, s):
35973741
"""Display a message on toolbar or in status bar"""
35983742
pass
35993743

3600-
def toggle(self, name, callback=False):
3744+
def _toggle(self, name, callback=False):
3745+
"""Toogle a button
3746+
3747+
Parameters
3748+
----------
3749+
name : string
3750+
Name of the button to toggle
3751+
callback : bool
3752+
* `True`: call the button callback during toggle
3753+
* `False`: toggle the button without calling the callback
3754+
3755+
"""
36013756
#carefull, callback means to perform or not the callback while toggling
36023757
raise NotImplementedError
36033758

3604-
def remove_toolitem(self, name):
3605-
pass
3759+
def _remove_toolitem(self, name):
3760+
"""Remove a toolitem from the `Toolbar`
3761+
3762+
Parameters
3763+
----------
3764+
name : string
3765+
Name of the tool to remove
3766+
3767+
"""
3768+
raise NotImplementedError
36063769

36073770
def move_toolitem(self, pos_ini, pos_fin):
3771+
"""Change the position of a toolitem
3772+
3773+
Parameters
3774+
----------
3775+
pos_ini : integer
3776+
Initial position of the toolitem to move
3777+
pos_fin : integer
3778+
Final position of the toolitem
3779+
"""
36083780
pass
36093781

36103782
def set_toolitem_visibility(self, name, visible):
3783+
"""Change the visibility of a toolitem
3784+
3785+
Parameters
3786+
----------
3787+
name : string
3788+
Name of the `Tool`
3789+
visible : bool
3790+
* `True`: set the toolitem visible
3791+
* `False`: set the toolitem invisible
3792+
"""
36113793
pass

0 commit comments

Comments
 (0)