diff --git a/documentation/source/core/index.rst b/documentation/source/core/index.rst index 11597067c..0903f9375 100644 --- a/documentation/source/core/index.rst +++ b/documentation/source/core/index.rst @@ -9,32 +9,10 @@ :mod:`lib` Module ----------------- -.. automodule:: openlp.core.lib - :members: +.. toctree:: + :maxdepth: 2 -:mod:`baselistwithdnd` Submodule -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. automodule:: openlp.core.lib.baselistwithdnd - :members: - -:mod:`event` Submodule -^^^^^^^^^^^^^^^^^^^^^^ - -.. automodule:: openlp.core.lib.event - :members: - -:mod:`eventmanager` Submodule -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. automodule:: openlp.core.lib.eventmanager - :members: - -:mod:`eventreceiver` Submodule -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. automodule:: openlp.core.lib.eventreceiver - :members: + lib :mod:`theme` Submodule ---------------------- diff --git a/openlp/core/lib/__init__.py b/openlp/core/lib/__init__.py index c940bd649..0d1a7180b 100644 --- a/openlp/core/lib/__init__.py +++ b/openlp/core/lib/__init__.py @@ -2,7 +2,9 @@ # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4 """ OpenLP - Open Source Lyrics Projection + Copyright (c) 2008 Raoul Snyman + Portions copyright (c) 2008-2009 Martin Thompson, Tim Bentley, This program is free software; you can redistribute it and/or modify it under @@ -21,15 +23,49 @@ import types from PyQt4 import QtCore, QtGui def translate(context, text): + """ + A special shortcut method to wrap around the Qt4 translation functions. + This abstracts the translation procedure so that we can change it if at a + later date if necessary, without having to redo the whole of OpenLP. + + ``context`` + The translation context, used to give each string a context or a + namespace. + + ``text`` + The text to put into the translation tables for translation. + """ return QtGui.QApplication.translate(context, text, None, QtGui.QApplication.UnicodeUTF8) def file_to_xml(xmlfile): + """ + Open a file and return the contents of the file. + + ``xmlfile`` + The name of the file. + """ return open(xmlfile).read() def str_to_bool(stringvalue): - return stringvalue.strip().lower() in (u'true', u'yes', u'y') + """ + Convert a string version of a boolean into a real boolean. + + ``stringvalue`` + The string value to examine and convert to a boolean type. + """ + return stringvalue.strip().lower() in (u'true', u'yes', u'y', u'1') def buildIcon(icon): + """ + Build a QIcon instance from an existing QIcon, a resource location, or a + physical file location. If the icon is a QIcon instance, that icon is + simply returned. If not, it builds a QIcon instance from the resource or + file name. + + ``icon`` + The icon to build. This can be a QIcon, a resource string in the form + ``:/resource/file.png``, or a file location like ``/path/to/file.png``. + """ ButtonIcon = None if type(icon) is QtGui.QIcon: ButtonIcon = icon @@ -64,15 +100,13 @@ from eventmanager import EventManager from pluginmanager import PluginManager from settingstab import SettingsTab from mediamanageritem import MediaManagerItem -from event import Event -from event import EventType +from event import Event, EventType from xmlrootclass import XmlRootClass from serviceitem import ServiceItem from eventreceiver import Receiver from serviceitem import ServiceItem from toolbar import OpenLPToolbar -from songxmlhandler import SongXMLBuilder -from songxmlhandler import SongXMLParser +from songxmlhandler import SongXMLBuilder, SongXMLParser from themexmlhandler import ThemeXML from renderer import Renderer from rendermanager import RenderManager diff --git a/openlp/core/lib/event.py b/openlp/core/lib/event.py index dcb84ffbb..f87729275 100644 --- a/openlp/core/lib/event.py +++ b/openlp/core/lib/event.py @@ -23,7 +23,13 @@ Place, Suite 330, Boston, MA 02111-1307 USA class EventType(object): """ - Types of events are stored in this class. + An enumeration-style class for event types. + + ``EventType.Default`` + Default event, a non-event. + + ``EventType.LoadServiceItem`` + When a service item is loaded. """ # "Default" event - a non-event Default = 0 diff --git a/openlp/core/lib/mediamanageritem.py b/openlp/core/lib/mediamanageritem.py index 430e4dbfb..bb09d318d 100644 --- a/openlp/core/lib/mediamanageritem.py +++ b/openlp/core/lib/mediamanageritem.py @@ -2,7 +2,9 @@ # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4 """ OpenLP - Open Source Lyrics Projection + Copyright (c) 2008-2009 Raoul Snyman + Portions copyright (c) 2008-2009 Martin Thompson, Tim Bentley This program is free software; you can redistribute it and/or modify it under @@ -30,29 +32,47 @@ class MediaManagerItem(QtGui.QWidget): """ MediaManagerItem is a helper widget for plugins. - None of the following *need* to be used, feel free to override - them cmopletely in your plugin's implementation. Alternatively, call them from your - plugin before or after you've done etra things that you need to. + None of the following *need* to be used, feel free to override them + completely in your plugin's implementation. Alternatively, call them from + your plugin before or after you've done etra things that you need to. - The plugin will be assigned an icon called u':/media/media_' + 'self.ShortPluginName + u'image.png' - which needs to be available in the main resources in order for them to work, you need to have setup + ``icon`` + The plugin will be assigned an icon called ``u':/media/media_' + + self.ShortPluginName + u'image.png'`` which needs to be available in + the main resources in order for them to work, you need to have setup. - self.TranslationContext - self.PluginTextShort # eg 'Image' for the image plugin - self.ConfigSection - where the items in the media manager are stored - this could potentially be self.PluginTextShort.lower() + ``self.TranslationContext`` + This is the "context" for the translation. This allows your plugin to + have it's own set of translatable strings which will not be + overwritten by the system-wide or application-wide translations. - self.OnNewPrompt=u'Select Image(s)' - self.OnNewFileMasks=u'Images (*.jpg *jpeg *.gif *.png *.bmp)' - assumes that the new action is to load a file. If not, override onnew + ``self.PluginTextShort`` + e.g. 'Image' for the image plugin. This is the short text name of your + plugin. This is used for things like the title of the item in the + media manager. - self.ListViewWithDnD_class - there is a base list class with DnD assigned to it (openlp.core.lib.BaseListWithDnD()) - each plugin needs to inherit a class from this and pass that *class* (not an instance) to here - via the ListViewWithDnD_class member + ``self.ConfigSection`` + This is the name of the section in the configuration file where the + configuration settings for your plugin are stored. This could + potentially be self.PluginTextShort.lower(). - self.PreviewFunction - a function which returns a QImage to represent the item (a preview usually) - - no scaling required - that's done later - If this fn is not defined, a default will be used (treat the filename as an image) + ``self.OnNewPrompt`` + e.g. ``u'Select Image(s)'`` + + ``self.OnNewFileMasks`` + e.g. ``u'Images (*.jpg *jpeg *.gif *.png *.bmp)'`` This is the set of + file masks for the plugin's "save" dialog. + + ``self.ListViewWithDnD_class`` + The base list class with DnD assigned to it (which is inherited from + ``openlp.core.lib.BaseListWithDnD``). Each plugin needs to inherit a + class from ``BaseListWithDnD`` and pass that *class* (not an instance) + to here via the ListViewWithDnD_class member. + + ``self.PreviewFunction`` + Returns a QImage to represent the item (a preview usually). No image + scaling is required - that's done later. If this fn is not defined, a + default will be used (treat the filename as an image). """ global log @@ -62,6 +82,9 @@ class MediaManagerItem(QtGui.QWidget): def __init__(self, parent=None, icon=None, title=None): """ Constructor to create the media manager item. + + ``parent`` + The parent object, usually the MediaManager instance. """ QtGui.QWidget.__init__(self) self.parent = parent @@ -83,6 +106,9 @@ class MediaManagerItem(QtGui.QWidget): self.initialise() def retranslateUi(self): + """ + This method pulls in the translation system. + """ pass def addToolbar(self): diff --git a/openlp/core/lib/plugin.py b/openlp/core/lib/plugin.py index 7b306ec76..59ed08e61 100644 --- a/openlp/core/lib/plugin.py +++ b/openlp/core/lib/plugin.py @@ -2,7 +2,9 @@ # vim: autoindent shiftwidth=4 expandtab textwidth=80 """ OpenLP - Open Source Lyrics Projection + Copyright (c) 2008 Raoul Snyman + Portions copyright (c) 2008 Martin Thompson, Tim Bentley, This program is free software; you can redistribute it and/or modify it under @@ -22,7 +24,7 @@ import logging from openlp.core.lib import PluginConfig # why does this not work??? -# from openlp.core.lib import Event, EventType +# from openlp.core.lib import Event, EventType # so I have to do this??? from event import Event, EventType diff --git a/openlp/core/lib/pluginconfig.py b/openlp/core/lib/pluginconfig.py index 3c9d2b70d..0ccdc18f0 100644 --- a/openlp/core/lib/pluginconfig.py +++ b/openlp/core/lib/pluginconfig.py @@ -2,7 +2,9 @@ # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4 """ OpenLP - Open Source Lyrics Projection + Copyright (c) 2008 Raoul Snyman + Portions copyright (c) 2008 -2009 Martin Thompson, Tim Bentley This program is free software; you can redistribute it and/or modify it under @@ -19,6 +21,7 @@ Place, Suite 330, Boston, MA 02111-1307 USA """ import os + from openlp.core.utils import ConfigHelper class PluginConfig(object): diff --git a/openlp/core/lib/pluginmanager.py b/openlp/core/lib/pluginmanager.py index e8eb308a5..345347a1e 100644 --- a/openlp/core/lib/pluginmanager.py +++ b/openlp/core/lib/pluginmanager.py @@ -2,7 +2,9 @@ # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4 """ OpenLP - Open Source Lyrics Projection + Copyright (c) 2008 Raoul Snyman + Portions copyright (c) 2008 - 2009 Martin Thompson, Tim Bentley, This program is free software; you can redistribute it and/or modify it under diff --git a/openlp/core/lib/renderer.py b/openlp/core/lib/renderer.py index 3f389afa7..d1617e8ad 100644 --- a/openlp/core/lib/renderer.py +++ b/openlp/core/lib/renderer.py @@ -2,7 +2,9 @@ # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4 """ OpenLP - Open Source Lyrics Projection + Copyright (c) 2008 Raoul Snyman + Portions copyright (c) 2008-2009 Martin Thompson, Tim Bentley This program is free software; you can redistribute it and/or modify it under diff --git a/openlp/core/lib/rendermanager.py b/openlp/core/lib/rendermanager.py index 6c3d11001..ff4ec6bdd 100644 --- a/openlp/core/lib/rendermanager.py +++ b/openlp/core/lib/rendermanager.py @@ -2,7 +2,9 @@ # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4 """ OpenLP - Open Source Lyrics Projection + Copyright (c) 2008 Raoul Snyman + Portions copyright (c) 2008 - 2009Martin Thompson, Tim Bentley This program is free software; you can redistribute it and/or modify it under @@ -33,7 +35,7 @@ class RenderManager(object): display defense code. """ global log - log=logging.getLogger(u'RenderManager') + log = logging.getLogger(u'RenderManager') log.info(u'RenderManager Loaded') def __init__(self, theme_manager, screen_list, screen_number=0): diff --git a/openlp/core/lib/serviceitem.py b/openlp/core/lib/serviceitem.py index f9dfa2097..4a96a46f4 100644 --- a/openlp/core/lib/serviceitem.py +++ b/openlp/core/lib/serviceitem.py @@ -2,7 +2,9 @@ # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4 """ OpenLP - Open Source Lyrics Projection + Copyright (c) 2008 Raoul Snyman + Portions copyright (c) 2008-2009 Martin Thompson, Tim Bentley This program is free software; you can redistribute it and/or modify it under @@ -32,7 +34,7 @@ class ServiceItem(object): compositor. """ global log - log=logging.getLogger(u'ServiceItem') + log = logging.getLogger(u'ServiceItem') log.info(u'Service Item created') def __init__(self, hostplugin=None): diff --git a/openlp/core/lib/settingsmanager.py b/openlp/core/lib/settingsmanager.py index bc66c2375..5f8afc83f 100644 --- a/openlp/core/lib/settingsmanager.py +++ b/openlp/core/lib/settingsmanager.py @@ -2,7 +2,9 @@ # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4 """ OpenLP - Open Source Lyrics Projection + Copyright (c) 2008 Raoul Snyman + Portions copyright (c) 2008-2009 Martin Thompson, Tim Bentley This program is free software; you can redistribute it and/or modify it under @@ -20,8 +22,9 @@ Place, Suite 330, Boston, MA 02111-1307 USA class SettingsManager(object): """ - Class to control the size of the UI components so they size correctly - This class is created by the main window and then calculates the size of individual components + Class to control the size of the UI components so they size correctly. + This class is created by the main window and then calculates the size of + individual components. """ def __init__(self, screen): self.screen = screen[0] diff --git a/openlp/core/lib/settingstab.py b/openlp/core/lib/settingstab.py index 421d0744d..eeef81230 100644 --- a/openlp/core/lib/settingstab.py +++ b/openlp/core/lib/settingstab.py @@ -2,7 +2,9 @@ # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4 """ OpenLP - Open Source Lyrics Projection + Copyright (c) 2008 Raoul Snyman + Portions copyright (c) 2008 Martin Thompson, Tim Bentley This program is free software; you can redistribute it and/or modify it under @@ -19,6 +21,7 @@ Place, Suite 330, Boston, MA 02111-1307 USA """ from PyQt4 import QtCore, QtGui + from openlp.core.lib import PluginConfig class SettingsTab(QtGui.QWidget): diff --git a/openlp/core/lib/songxmlhandler.py b/openlp/core/lib/songxmlhandler.py index 9cb0bb4e9..d66b11da9 100644 --- a/openlp/core/lib/songxmlhandler.py +++ b/openlp/core/lib/songxmlhandler.py @@ -2,7 +2,9 @@ # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4 """ OpenLP - Open Source Lyrics Projection + Copyright (c) 2008 Raoul Snyman + Portions copyright (c) 2008-2009 Martin Thompson, Tim Bentley, Carsten Tinggaard This program is free software; you can redistribute it and/or modify it under @@ -16,26 +18,25 @@ PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA -from xml.dom.minidom import Document -from xml.etree.ElementTree import ElementTree, XML, dump - - - - - - - - - - """ import logging from xml.dom.minidom import Document from xml.etree.ElementTree import ElementTree, XML, dump -class SongXMLBuilder(): +class SongXMLBuilder(object): """ This class builds the XML used to describe songs. + + The basic XML looks like this:: + + + + + + + + + """ def __init__(self): """ @@ -97,9 +98,21 @@ class SongXMLBuilder(): """ return self.song_xml.toxml(u'utf-8') -class SongXMLParser(): + +class SongXMLParser(object): """ A class to read in and parse a song's XML. + + The basic XML looks like this:: + + + + + + + + + """ global log log = logging.getLogger(u'SongXMLParser') diff --git a/openlp/core/lib/themexmlhandler.py b/openlp/core/lib/themexmlhandler.py index acb451653..ffd4c9464 100644 --- a/openlp/core/lib/themexmlhandler.py +++ b/openlp/core/lib/themexmlhandler.py @@ -2,7 +2,9 @@ # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4 """ OpenLP - Open Source Lyrics Projection + Copyright (c) 2008 Raoul Snyman + Portions copyright (c) 2008-2009 Martin Thompson, Tim Bentley, Carsten Tinggaard This program is free software; you can redistribute it and/or modify it under diff --git a/openlp/core/lib/toolbar.py b/openlp/core/lib/toolbar.py index 0f89abed4..b62c3217f 100644 --- a/openlp/core/lib/toolbar.py +++ b/openlp/core/lib/toolbar.py @@ -2,7 +2,9 @@ # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4 """ OpenLP - Open Source Lyrics Projection + Copyright (c) 2009 Raoul Snyman + Portions copyright (c) 2009 Martin Thompson, Tim Bentley This program is free software; you can redistribute it and/or modify it under diff --git a/openlp/core/lib/xmlrootclass.py b/openlp/core/lib/xmlrootclass.py index 3cd559f62..677a426f0 100644 --- a/openlp/core/lib/xmlrootclass.py +++ b/openlp/core/lib/xmlrootclass.py @@ -2,7 +2,9 @@ # vim: autoindent shiftwidth=4 expandtab textwidth=80 tabstop=4 softtabstop=4 """ OpenLP - Open Source Lyrics Projection + Copyright (c) 2008 Raoul Snyman + Portions copyright (c) 2008 Martin Thompson, Tim Bentley, Carsten Tinggaard This program is free software; you can redistribute it and/or modify it under