InterfaceAction documentation

src/calibre/gui2/actions/__init__.py

@@ -13,14 +13,49 @@ from calibre.gui2 import Dispatcher
 
 class InterfaceAction(QObject):
 
+    '''
+    A plugin representing an "action" that can be taken in the graphical user
+    interface. All the items in the toolbar and context menus are implemented
+    by these plugins.
+
+    Note that this class is the base class for these plugins, however, to
+    integrate the plugin with calibre's plugin system, you have to make a
+    wrapper class that references the actual plugin. See the
+    :mod:`calibre.customize.builtins` module for examples.
+
+    If two :class:`InterfaceAction` objects have the same name, the one with higher
+    priority takes precedence.
+
+    Sub-classes should implement the :meth:`genesis` and
+    :meth:`location_selected` methods.
+
+    Once initialized, this plugin has access to the main calibre GUI via the
+    :attr:`gui` member. You can access other plugins by name, for example::
+
+        self.gui.iactions['Save To Disk']
+
+    The QAction specified by :attr:`action_spec` is automatically create and
+    made available as ``self.qaction``.
+
+    '''
+
+    #: The plugin name. If two plugins with the same name are present, the one
+    #: with higher priority takes precedence.
     name = 'Implement me'
+
+    #: The plugin priority. If two plugins with the same name are present, the one
+    #: with higher priority takes precedence.
     priority = 1
-    positions = frozenset([])
+
+    #: The menu popup type for when this plugin is added to a toolbar
     popup_type = QToolButton.MenuButtonPopup
+
+    #: Whether this action should be auto repeated when its shortcut
+    #: key is held down.
     auto_repeat = False
 
     #: Of the form: (text, icon_path, tooltip, keyboard shortcut)
-    #: icon, tooltip and keybard shortcut can be None
+    #: icon, tooltip and keyboard shortcut can be None
     #: shortcut must be a translated string if not None
     action_spec = ('text', 'icon', None, None)
 
@@ -56,8 +91,20 @@ class InterfaceAction(QObject):
         return action
 
     def genesis(self):
+        '''
+        Setup this plugin. Only called once during initialization. self.gui is
+        available. The action secified by :attr:`action_spec` is available as
+        ``self.qaction``.
+        '''
         pass
 
     def location_selected(self, loc):
+        '''
+        Called whenever the book list being displayed in calibre changes.
+        Currently values for loc are: ``library, main, card and cardb``.
+
+        This method should enable/disable this action and its sub actions as
+        appropriate for the location.
+        '''
         pass