diff --git a/openlp/__init__.py b/openlp/__init__.py index 1a348a0df..98d19aecc 100644 --- a/openlp/__init__.py +++ b/openlp/__init__.py @@ -22,3 +22,6 @@ # with this program; if not, write to the Free Software Foundation, Inc., 59 # # Temple Place, Suite 330, Boston, MA 02111-1307 USA # ############################################################################### +""" +The :mod:`openlp` module contains all the project produced OpenLP functionality +""" diff --git a/openlp/core/__init__.py b/openlp/core/__init__.py index 1a348a0df..5b2bbe056 100644 --- a/openlp/core/__init__.py +++ b/openlp/core/__init__.py @@ -22,3 +22,9 @@ # with this program; if not, write to the Free Software Foundation, Inc., 59 # # Temple Place, Suite 330, Boston, MA 02111-1307 USA # ############################################################################### +""" +The :mod:`core` module provides all core application functions + +All the core functions of the OpenLP application including the GUI, settings, +logging and a plugin framework are contained within the openlp.core module. +""" diff --git a/openlp/core/lib/mediamanageritem.py b/openlp/core/lib/mediamanageritem.py index 928d73152..1d2c6bd41 100644 --- a/openlp/core/lib/mediamanageritem.py +++ b/openlp/core/lib/mediamanageritem.py @@ -319,8 +319,7 @@ class MediaManagerItem(QtGui.QWidget): def initialise(self): """ Implement this method in your descendent media manager item to - do any UI or other initialisation. This method is called - automatically. + do any UI or other initialisation. This method is called automatically. """ pass @@ -361,8 +360,7 @@ class MediaManagerItem(QtGui.QWidget): def validate(self, file, thumb): """ - Validates to see if the file still exists or - thumbnail is up to date + Validates to see if the file still exists or thumbnail is up to date """ if os.path.exists(file): filedate = os.stat(file).st_mtime diff --git a/openlp/core/lib/pluginmanager.py b/openlp/core/lib/pluginmanager.py index 95bf3971c..d9ae40845 100644 --- a/openlp/core/lib/pluginmanager.py +++ b/openlp/core/lib/pluginmanager.py @@ -22,7 +22,9 @@ # with this program; if not, write to the Free Software Foundation, Inc., 59 # # Temple Place, Suite 330, Boston, MA 02111-1307 USA # ############################################################################### - +""" +Provide plugin management +""" import os import sys import logging diff --git a/openlp/core/lib/serviceitem.py b/openlp/core/lib/serviceitem.py index 9fe7ac060..6f27ddf34 100644 --- a/openlp/core/lib/serviceitem.py +++ b/openlp/core/lib/serviceitem.py @@ -22,6 +22,10 @@ # with this program; if not, write to the Free Software Foundation, Inc., 59 # # Temple Place, Suite 330, Boston, MA 02111-1307 USA # ############################################################################### +""" +The :mod:`serviceitem` provides the service item functionality including the +type and capability of an item. +""" import logging import os @@ -43,6 +47,9 @@ class ServiceItemType(object): Command = 3 class ItemCapabilities(object): + """ + Provides an enumeration of a serviceitem's capabilities + """ AllowsPreview = 1 AllowsEdit = 2 AllowsMaintain = 3 @@ -85,9 +92,21 @@ class ServiceItem(object): self.cache = [] def add_capability(self, capability): + """ + Add an ItemCapability to a ServiceItem + + ``capability`` + The capability to add + """ self.capabilities.append(capability) def is_capable(self, capability): + """ + Tell the caller if a ServiceItem has a capability + + ``capability`` + The capability to test for + """ return capability in self.capabilities def addIcon(self, icon): @@ -304,22 +323,40 @@ class ServiceItem(object): return self._uuid != other._uuid def is_media(self): + """ + Confirms if the ServiceItem is media + """ return ItemCapabilities.RequiresMedia in self.capabilities def is_command(self): + """ + Confirms if the ServiceItem is a command + """ return self.service_item_type == ServiceItemType.Command def is_image(self): + """ + Confirms if the ServiceItem is an image + """ return self.service_item_type == ServiceItemType.Image def uses_file(self): + """ + Confirms if the ServiceItem uses a file + """ return self.service_item_type == ServiceItemType.Image or \ self.service_item_type == ServiceItemType.Command def is_text(self): + """ + Confirms if the ServiceItem is text + """ return self.service_item_type == ServiceItemType.Text def get_frames(self): + """ + Returns the frames for the ServiceItem + """ if self.service_item_type == ServiceItemType.Text: return self._display_frames else: diff --git a/openlp/core/lib/songxmlhandler.py b/openlp/core/lib/songxmlhandler.py index acb75609b..76b01e376 100644 --- a/openlp/core/lib/songxmlhandler.py +++ b/openlp/core/lib/songxmlhandler.py @@ -22,6 +22,20 @@ # with this program; if not, write to the Free Software Foundation, Inc., 59 # # Temple Place, Suite 330, Boston, MA 02111-1307 USA # ############################################################################### +""" +The :mod:`songxmlhandler` module provides the XML functionality for songs + +The basic XML is of the format:: + + + + + + + + + +""" import logging @@ -34,17 +48,6 @@ log = logging.getLogger(__name__) class SongXMLBuilder(object): """ This class builds the XML used to describe songs. - - The basic XML looks like this:: - - - - - - - - - """ log.info(u'SongXMLBuilder Loaded') @@ -113,17 +116,6 @@ class SongXMLBuilder(object): class SongXMLParser(object): """ A class to read in and parse a song's XML. - - The basic XML looks like this:: - - - - - - - - - """ log.info(u'SongXMLParser Loaded') diff --git a/openlp/core/theme/theme.py b/openlp/core/theme/theme.py index 3232abc4e..7bc705fcb 100644 --- a/openlp/core/theme/theme.py +++ b/openlp/core/theme/theme.py @@ -22,6 +22,12 @@ # with this program; if not, write to the Free Software Foundation, Inc., 59 # # Temple Place, Suite 330, Boston, MA 02111-1307 USA # ############################################################################### +""" +OpenLP version 1 theme handling + +Provides reference data, a default v1 XML theme and class wrapper for +processing version 1 themes in OpenLP version 2. +""" from xml.etree.ElementTree import ElementTree, XML from PyQt4 import QtGui @@ -54,51 +60,106 @@ BLANK_STYLE_XML = \ ''' class Theme(object): + """ + Provide a class wrapper storing data from an XML theme + + ``name`` + Theme name + + ``BackgroundMode`` + The behaviour of the background. Valid modes are: + - 0 - Transparent + - 1 - Opaque + + ``BackgroundType`` + The content of the background. Valid types are: + - 0 - solid color + - 1 - gradient color + - 2 - image + + ``BackgroundParameter1`` + Extra information about the background. The contents of this attribute + depend on the BackgroundType: + - image: image filename + - gradient: start color + - solid: color + + ``BackgroundParameter2`` + Extra information about the background. The contents of this attribute + depend on the BackgroundType: + - image: border color + - gradient: end color + - solid: N/A + + ``BackgroundParameter3`` + Extra information about the background. The contents of this attribute + depend on the BackgroundType: + - image: N/A + - gradient: The direction of the gradient. Valid entries are: + - 0 -> vertical + - 1 -> horizontal + - solid: N/A + + ``FontName`` + Name of the font to use for the main font. + + ``FontColor`` + The color for the main font + + ``FontProportion`` + The size of the main font + + ``FontUnits`` + The units for FontProportion, either or + + ``Shadow`` + The shadow type to apply to the main font. + - 0 - no shadow + - non-zero - use shadow + + ``ShadowColor`` + Color for the shadow + + ``Outline`` + The outline to apply to the main font + - 0 - no outline + - non-zero - use outline + + ``OutlineColor`` + Color for the outline (or None if Outline is 0) + + ``HorizontalAlign`` + The horizontal alignment to apply to text. Valid alignments are: + - 0 - left align + - 1 - right align + - 2 - centre align + + ``VerticalAlign`` + The vertical alignment to apply to the text. Valid alignments are: + - 0 - top align + - 1 - bottom align + - 2 - centre align + + ``WrapStyle`` + The wrap style to apply to the text. Valid styles are: + - 0 - normal + - 1 - lyrics + """ def __init__(self, xml): - """ stores the info about a theme - attributes: - name : theme name + """ + Initialise a theme with data from xml - BackgroundMode : 1 - Transparent - 1 - Opaque - - BackgroundType : 0 - solid color - 1 - gradient color - 2 - image - - BackgroundParameter1 : for image - filename - for gradient - start color - for solid - color - BackgroundParameter2 : for image - border colour - for gradient - end color - for solid - N/A - BackgroundParameter3 : for image - N/A - for gradient - 0 -> vertical, 1 -> horizontal - - FontName : name of font to use - FontColor : color for main font - FontProportion : size of font - FontUnits : whether size of font is in or - - Shadow : 0 - no shadow, non-zero use shadow - ShadowColor : color for drop shadow - Outline : 0 - no outline, non-zero use outline - OutlineColor : color for outline (or None for no outline) - - HorizontalAlign : 0 - left align - 1 - right align - 2 - centre align - VerticalAlign : 0 - top align - 1 - bottom align - 2 - centre align - WrapStyle : 0 - normal - 1 - lyrics + ``xml`` + The data to initialise the theme with """ # init to defaults self._set_from_XML(BLANK_STYLE_XML) self._set_from_XML(xml) def _get_as_string(self): + """ + Return single line string representation of a theme + """ theme_strings = [] keys = dir(self) keys.sort() @@ -108,6 +169,12 @@ class Theme(object): return u''.join(theme_strings) def _set_from_XML(self, xml): + """ + Set theme class attributes with data from XML + + ``xml`` + The data to apply to the theme + """ root = ElementTree(element=XML(xml)) iter = root.getiterator() for element in iter: @@ -146,8 +213,12 @@ class Theme(object): setattr(self, element.tag, val) def __str__(self): + """ + Provide Python string representation for the class (multiline output) + """ theme_strings = [] for key in dir(self): if key[0:1] != u'_': theme_strings.append(u'%30s : %s' % (key, getattr(self, key))) return u'\n'.join(theme_strings) + diff --git a/openlp/core/ui/__init__.py b/openlp/core/ui/__init__.py index 76b84503e..e104a2ec6 100644 --- a/openlp/core/ui/__init__.py +++ b/openlp/core/ui/__init__.py @@ -22,6 +22,9 @@ # with this program; if not, write to the Free Software Foundation, Inc., 59 # # Temple Place, Suite 330, Boston, MA 02111-1307 USA # ############################################################################### +""" +The :mod:`ui` module provides the core user interface for OpenLP +""" class HideMode(object): """ diff --git a/openlp/core/ui/displaytab.py b/openlp/core/ui/displaytab.py index 6fe9f16e2..3ddbb8b08 100644 --- a/openlp/core/ui/displaytab.py +++ b/openlp/core/ui/displaytab.py @@ -29,16 +29,19 @@ from openlp.core.lib import SettingsTab, Receiver, translate class DisplayTab(SettingsTab): """ - Class documentation goes here. + Provide the UI for managing display related settings """ def __init__(self, screens): """ - Constructor + Initialise the display tab from a SettingsTab """ self.screens = screens SettingsTab.__init__(self, u'Display') def setupUi(self): + """ + Set up the UI widgets to show the settings + """ self.tabTitleVisible = translate(u'DisplayTab', u'Displays') self.layoutWidget = QtGui.QWidget(self) self.layoutWidget.setGeometry(QtCore.QRect(0, 40, 241, 79)) @@ -158,6 +161,9 @@ class DisplayTab(SettingsTab): QtCore.SIGNAL(u'stateChanged(int)'), self.onOverrideCheckBoxChanged) def retranslateUi(self): + """ + Provide i18n support for this UI + """ self.setWindowTitle(translate(u'DisplayTab', u'Amend Display Settings')) self.CurrentGroupBox.setTitle( translate(u'DisplayTab', u'Default Settings')) @@ -179,6 +185,9 @@ class DisplayTab(SettingsTab): translate(u'DisplayTab', u'Override Output Display')) def load(self): + """ + Load current display settings + """ settings = QtCore.QSettings() settings.beginGroup(self.settingsSection) self.Xpos.setText(unicode(self.screens.current[u'size'].x())) @@ -209,6 +218,9 @@ class DisplayTab(SettingsTab): self.amend_display = True def save(self): + """ + Save chosen settings + """ settings = QtCore.QSettings() settings.beginGroup(self.settingsSection) settings.setValue('x position', QtCore.QVariant(self.XposEdit.text())) diff --git a/openlp/core/ui/maindisplay.py b/openlp/core/ui/maindisplay.py index 5e8db4934..a3c444097 100644 --- a/openlp/core/ui/maindisplay.py +++ b/openlp/core/ui/maindisplay.py @@ -133,7 +133,6 @@ class MainDisplay(DisplayWidget): self.display_alert = QtGui.QLabel(self) self.display_alert.setScaledContents(True) self.primary = True - self.displayBlank = False self.blankFrame = None self.frame = None QtCore.QObject.connect(Receiver.get_receiver(), @@ -280,15 +279,15 @@ class MainDisplay(DisplayWidget): self.display_alert.setPixmap(frame) self.moveToTop() - def frameView(self, frame, transition=False): + def frameView(self, frame, transition=False, display=True): """ Called from a slide controller to display a frame if the alert is in progress the alert is added on top ``frame`` Image frame to be rendered """ - log.debug(u'frameView %d' % (self.displayBlank)) - if not self.displayBlank: + log.debug(u'frameView %d' % (display)) + if display: if transition: if self.frame is not None: self.display_text.setPixmap( @@ -314,8 +313,7 @@ class MainDisplay(DisplayWidget): self.setVisible(True) self.showFullScreen() else: - self.waitingFrame = frame - self.waitingFrameTrans = transition + self.storeText = QtGui.QPixmap.fromImage(frame[u'main']) class VideoDisplay(Phonon.VideoWidget): """ diff --git a/openlp/core/ui/mainwindow.py b/openlp/core/ui/mainwindow.py index c65fa2ec0..3caef90c5 100644 --- a/openlp/core/ui/mainwindow.py +++ b/openlp/core/ui/mainwindow.py @@ -356,7 +356,7 @@ class Ui_MainWindow(object): """ MainWindow.mainTitle = translate(u'MainWindow', u'OpenLP 2.0') MainWindow.language = translate(u'MainWindow', u'English') - MainWindow.defaultThemeText = translate(u'MainWindow', + MainWindow.defaultThemeText = translate(u'MainWindow', u'Default Theme: ') MainWindow.setWindowTitle(MainWindow.mainTitle) self.FileMenu.setTitle(translate(u'MainWindow', u'&File')) @@ -456,7 +456,7 @@ class Ui_MainWindow(object): u'Set the interface language to %1').arg(item.objectName())) self.ToolsAddToolItem.setText(translate(u'MainWindow', u'Add &Tool...')) self.ToolsAddToolItem.setStatusTip( - translate(u'MainWindow', + translate(u'MainWindow', u'Add an application to the list of tools')) self.action_Preview_Panel.setText( translate(u'MainWindow', u'&Preview Pane')) @@ -652,15 +652,13 @@ class MainWindow(QtGui.QMainWindow, Ui_MainWindow): """ settings = QtCore.QSettings() settings.beginGroup(self.generalSettingsSection) - if settings.value(u'screen blank', QtCore.QVariant(False)).toBool() \ - and settings.value(u'blank warning', QtCore.QVariant(False)).toBool(): - self.LiveController.onBlankDisplay(True) - QtGui.QMessageBox.question(self, - translate(u'MainWindow', u'OpenLP Main Display Blanked'), - translate(u'MainWindow', - u'The Main Display has been blanked out'), - QtGui.QMessageBox.StandardButtons(QtGui.QMessageBox.Ok), - QtGui.QMessageBox.Ok) + if settings.value(u'screen blank', QtCore.QVariant(False)).toBool(): + self.LiveController.mainDisplaySetBackground() + if settings.value(u'blank warning', QtCore.QVariant(False)).toBool(): + QtGui.QMessageBox.question(self, + translate(u'MainWindow', u'OpenLP Main Display Blanked'), + translate(u'MainWindow', + u'The Main Display has been blanked out')) settings.endGroup() def versionThread(self): diff --git a/openlp/core/ui/mediadockmanager.py b/openlp/core/ui/mediadockmanager.py index 782383cd4..7d81b5f23 100644 --- a/openlp/core/ui/mediadockmanager.py +++ b/openlp/core/ui/mediadockmanager.py @@ -28,11 +28,25 @@ import logging log = logging.getLogger(__name__) class MediaDockManager(object): - + """ + Provide a repository for MediaManagerItems + """ def __init__(self, media_dock): + """ + Initialise the media dock + """ self.media_dock = media_dock def add_dock(self, media_item, icon, weight): + """ + Add a MediaManagerItem to the dock + + ``media_item`` + The item to add to the dock + + ``icon`` + An icon for this dock item + """ log.info(u'Adding %s dock' % media_item.title) self.media_dock.addItem(media_item, icon, media_item.title) @@ -53,6 +67,12 @@ class MediaDockManager(object): self.media_dock.addItem(media_item, icon, media_item.title) def remove_dock(self, name): + """ + Removes a MediaManagerItem from the dock + + ``name`` + The item to remove + """ log.debug(u'remove %s dock' % name) for dock_index in range(0, self.media_dock.count()): if self.media_dock.widget(dock_index): diff --git a/openlp/core/ui/screen.py b/openlp/core/ui/screen.py index 69dd915d2..f620e7d00 100644 --- a/openlp/core/ui/screen.py +++ b/openlp/core/ui/screen.py @@ -22,7 +22,10 @@ # with this program; if not, write to the Free Software Foundation, Inc., 59 # # Temple Place, Suite 330, Boston, MA 02111-1307 USA # ############################################################################### - +""" +The :mod:`screen` module provides management functionality for a machines' +displays +""" import logging import copy @@ -46,12 +49,18 @@ class ScreenList(object): self.monitor_number = 0 def add_screen(self, screen): + """ + Add a screen to the list of known screens + """ if screen[u'primary']: self.current = screen self.screen_list.append(screen) self.display_count += 1 def screen_exists(self, number): + """ + Confirms a screen is known + """ for screen in self.screen_list: if screen[u'number'] == number: return True diff --git a/openlp/core/ui/servicemanager.py b/openlp/core/ui/servicemanager.py index baf26fde8..de344a44d 100644 --- a/openlp/core/ui/servicemanager.py +++ b/openlp/core/ui/servicemanager.py @@ -38,7 +38,9 @@ from openlp.core.ui import ServiceNoteForm, ServiceItemEditForm from openlp.core.utils import AppLocation class ServiceManagerList(QtGui.QTreeWidget): - + """ + Set up key bindings and mouse behaviour for the service list + """ def __init__(self, parent=None, name=None): QtGui.QTreeWidget.__init__(self, parent) self.parent = parent diff --git a/openlp/core/ui/settingsform.py b/openlp/core/ui/settingsform.py index f923c9d7d..dfd1d5a7d 100644 --- a/openlp/core/ui/settingsform.py +++ b/openlp/core/ui/settingsform.py @@ -22,7 +22,9 @@ # with this program; if not, write to the Free Software Foundation, Inc., 59 # # Temple Place, Suite 330, Boston, MA 02111-1307 USA # ############################################################################### - +""" +The :mod:`settingsform` provides a user interface for the OpenLP settings +""" import logging from PyQt4 import QtGui @@ -33,8 +35,13 @@ from settingsdialog import Ui_SettingsDialog log = logging.getLogger(__name__) class SettingsForm(QtGui.QDialog, Ui_SettingsDialog): - + """ + Provide the form to manipulate the settings for OpenLP + """ def __init__(self, screens, mainWindow, parent=None): + """ + Initialise the settings form + """ QtGui.QDialog.__init__(self, parent) self.setupUi(self) # General tab @@ -48,16 +55,25 @@ class SettingsForm(QtGui.QDialog, Ui_SettingsDialog): self.addTab(u'Display', self.DisplayTab) def addTab(self, name, tab): + """ + Add a tab to the form + """ log.info(u'Adding %s tab' % tab.tabTitle) self.SettingsTabWidget.addTab(tab, tab.tabTitleVisible) def insertTab(self, tab, location): + """ + Add a tab to the form at a specific location + """ log.debug(u'Inserting %s tab' % tab.tabTitle) #13 : There are 3 tables currently and locations starts at -10 self.SettingsTabWidget.insertTab( location + 13, tab, tab.tabTitleVisible) def removeTab(self, name): + """ + Remove a tab from the form + """ log.debug(u'remove %s tab' % name) for tab_index in range(0, self.SettingsTabWidget.count()): if self.SettingsTabWidget.widget(tab_index): @@ -65,10 +81,16 @@ class SettingsForm(QtGui.QDialog, Ui_SettingsDialog): self.SettingsTabWidget.removeTab(tab_index) def accept(self): + """ + Process the form saving the settings + """ for tab_index in range(0, self.SettingsTabWidget.count()): self.SettingsTabWidget.widget(tab_index).save() return QtGui.QDialog.accept(self) def postSetUp(self): + """ + Run any post-setup code for the tabs on the form + """ for tab_index in range(0, self.SettingsTabWidget.count()): self.SettingsTabWidget.widget(tab_index).postSetUp() diff --git a/openlp/core/ui/slidecontroller.py b/openlp/core/ui/slidecontroller.py index fc77166e5..6e8ba8b22 100644 --- a/openlp/core/ui/slidecontroller.py +++ b/openlp/core/ui/slidecontroller.py @@ -120,6 +120,7 @@ class SlideController(QtGui.QWidget): self.serviceItem = None self.Panel = QtGui.QWidget(parent.ControlSplitter) self.slideList = {} + self.canDisplay = True # Layout for holding panel self.PanelLayout = QtGui.QVBoxLayout(self.Panel) self.PanelLayout.setSpacing(0) @@ -651,6 +652,12 @@ class SlideController(QtGui.QWidget): self.PreviewListWidget.selectRow(index) self.onSlideSelected() + def mainDisplaySetBackground(self): + """ + Allow the main display to blank the main display at startup time + """ + self.blankButton.setChecked(True) + def onSlideBlank(self): """ Handle the slidecontroller blank event @@ -670,6 +677,7 @@ class SlideController(QtGui.QWidget): log.debug(u'onBlankDisplay %d' % checked) self.hideButton.setChecked(False) self.themeButton.setChecked(False) + self.canDisplay = not checked QtCore.QSettings().setValue( self.parent.generalSettingsSection + u'/screen blank', QtCore.QVariant(checked)) @@ -687,6 +695,7 @@ class SlideController(QtGui.QWidget): log.debug(u'onThemeDisplay %d' % checked) self.blankButton.setChecked(False) self.hideButton.setChecked(False) + self.canDisplay = False if checked: Receiver.send_message(u'maindisplay_hide', HideMode.Theme) self.blankPlugin(True) @@ -701,6 +710,7 @@ class SlideController(QtGui.QWidget): log.debug(u'onHideDisplay %d' % checked) self.blankButton.setChecked(False) self.themeButton.setChecked(False) + self.canDisplay = False if checked: Receiver.send_message(u'maindisplay_hide', HideMode.Screen) self.hidePlugin(True) @@ -710,7 +720,7 @@ class SlideController(QtGui.QWidget): def blankPlugin(self, blank): """ - Blank the display screen. + Blank the display screen within a plugin if required. """ if self.serviceItem is not None: if blank: @@ -770,7 +780,7 @@ class SlideController(QtGui.QWidget): log.log( 15, u'Slide Rendering took %4s' % (time.time() - before)) if self.isLive: - self.mainDisplay.frameView(frame, True) + self.mainDisplay.frameView(frame, True, self.canDisplay) self.selectedRow = row Receiver.send_message(u'slidecontroller_%s_changed' % self.typePrefix, row) diff --git a/openlp/core/ui/splashscreen.py b/openlp/core/ui/splashscreen.py index b13c3c8c4..d964ed610 100644 --- a/openlp/core/ui/splashscreen.py +++ b/openlp/core/ui/splashscreen.py @@ -30,7 +30,7 @@ class SplashScreen(object): def __init__(self, version): self.splash_screen = QtGui.QSplashScreen() self.setupUi() - self.message = self.splash_screen.translate( + self.message = translate( u'Splashscreen', u'Starting')\ + '..... ' + version @@ -59,7 +59,7 @@ class SplashScreen(object): def retranslateUi(self): self.splash_screen.setWindowTitle( - self.splash_screen.translate(u'Splashscreen', u'Splash Screen')) + translate(u'Splashscreen', u'Splash Screen')) def show(self): self.splash_screen.show() diff --git a/openlp/core/ui/thememanager.py b/openlp/core/ui/thememanager.py index 41c2a9360..1d60d264f 100644 --- a/openlp/core/ui/thememanager.py +++ b/openlp/core/ui/thememanager.py @@ -121,6 +121,10 @@ class ThemeManager(QtGui.QWidget): QtCore.QVariant(u'')).toString()) def changeGlobalFromTab(self, themeName): + """ + Change the global theme when it is changed through the Themes settings + tab + """ log.debug(u'changeGlobalFromTab %s', themeName) for count in range (0, self.ThemeListWidget.count()): #reset the old name @@ -136,6 +140,10 @@ class ThemeManager(QtGui.QWidget): self.ThemeListWidget.item(count).setText(name) def changeGlobalFromScreen(self, index = -1): + """ + Change the global theme when a theme is double clicked upon in the + Theme Manager list + """ log.debug(u'changeGlobalFromScreen %s', index) selected_row = self.ThemeListWidget.currentRow() for count in range (0, self.ThemeListWidget.count()): @@ -159,12 +167,20 @@ class ThemeManager(QtGui.QWidget): self.pushThemes() def onAddTheme(self): + """ + Loads a new theme with the default settings and then launches the theme + editing form for the user to make their customisations. + """ theme = self.createThemeFromXml(self.baseTheme(), self.path) self.amendThemeForm.loadTheme(theme) self.saveThemeName = u'' self.amendThemeForm.exec_() def onEditTheme(self): + """ + Loads the settings for the theme that is to be edited and launches the + theme editing form so the user can make their changes. + """ item = self.ThemeListWidget.currentItem() if item: theme = self.getThemeData( @@ -175,6 +191,9 @@ class ThemeManager(QtGui.QWidget): self.amendThemeForm.exec_() def onDeleteTheme(self): + """ + Delete a theme + """ self.global_theme = unicode(QtCore.QSettings().value( self.settingsSection + u'/global theme', QtCore.QVariant(u'')).toString()) @@ -262,6 +281,11 @@ class ThemeManager(QtGui.QWidget): zip.close() def onImportTheme(self): + """ + Opens a file dialog to select the theme file(s) to import before + attempting to extract OpenLP themes from those files. This process + will load both OpenLP version 1 and version 2 themes. + """ files = QtGui.QFileDialog.getOpenFileNames( self, translate(u'ThemeManager', u'Select Theme Import File'), SettingsManager.get_last_dir(self.settingsSection), u'Theme (*.*)') @@ -311,12 +335,24 @@ class ThemeManager(QtGui.QWidget): self.pushThemes() def pushThemes(self): + """ + Notify listeners that the theme list has been updated + """ Receiver.send_message(u'theme_update_list', self.getThemes()) def getThemes(self): + """ + Return the list of loaded themes + """ return self.themelist def getThemeData(self, themename): + """ + Returns a theme object from an XML file + + ``themename`` + Name of the theme to load from file + """ log.debug(u'getthemedata for theme %s', themename) xml_file = os.path.join(self.path, unicode(themename), unicode(themename) + u'.xml') @@ -326,6 +362,12 @@ class ThemeManager(QtGui.QWidget): return self.createThemeFromXml(xml, self.path) def checkThemesExists(self, dir): + """ + Check a theme directory exists and if not create it + + ``dir`` + Theme directory to make sure exists + """ log.debug(u'check themes') if not os.path.exists(dir): os.mkdir(dir) @@ -388,7 +430,10 @@ class ThemeManager(QtGui.QWidget): def checkVersion1(self, xmlfile): """ - Am I a version 1 theme + Check if a theme is from OpenLP version 1 + + ``xmlfile`` + Theme XML to check the version of """ log.debug(u'checkVersion1 ') theme = xmlfile @@ -400,9 +445,13 @@ class ThemeManager(QtGui.QWidget): def migrateVersion122(self, xml_data): """ - Called by convert the xml data from version 1 format - to the current format. - New fields are defaulted but the new theme is useable + Convert the xml data from version 1 format to the current format. + + New fields are loaded with defaults to provide a complete, working + theme containing all compatible customisations from the old theme. + + ``xml_data`` + Version 1 theme to convert """ theme = Theme(xml_data) newtheme = ThemeXML() @@ -510,11 +559,20 @@ class ThemeManager(QtGui.QWidget): return frame def getPreviewImage(self, theme): + """ + Return an image representing the look of the theme + + ``theme`` + The theme to return the image for + """ log.debug(u'getPreviewImage %s ', theme) image = os.path.join(self.path, theme + u'.png') return image def baseTheme(self): + """ + Provide a base theme with sensible defaults + """ log.debug(u'base theme created') newtheme = ThemeXML() newtheme.new_document(unicode(translate(u'ThemeManager', u'New Theme'))) @@ -528,6 +586,12 @@ class ThemeManager(QtGui.QWidget): return newtheme.extract_xml() def createThemeFromXml(self, theme_xml, path): + """ + Return a theme object using information parsed from XML + + ``theme_xml`` + The XML data to load into the theme + """ theme = ThemeXML() theme.parse(theme_xml) self.cleanTheme(theme) @@ -535,6 +599,11 @@ class ThemeManager(QtGui.QWidget): return theme def cleanTheme(self, theme): + """ + Clean a theme loaded from an XML file by removing stray whitespace and + making sure parameters are the correct type for the theme object + attributes + """ theme.background_color = theme.background_color.strip() theme.background_direction = theme.background_direction.strip() theme.background_endColor = theme.background_endColor.strip() diff --git a/openlp/core/utils/__init__.py b/openlp/core/utils/__init__.py index 8cbf7657a..512e15f06 100644 --- a/openlp/core/utils/__init__.py +++ b/openlp/core/utils/__init__.py @@ -22,13 +22,16 @@ # with this program; if not, write to the Free Software Foundation, Inc., 59 # # Temple Place, Suite 330, Boston, MA 02111-1307 USA # ############################################################################### +""" +The :mod:`utils` module provides the utility libraries for OpenLP +""" import os import sys import logging import urllib2 -from datetime import datetime +from datetime import datetime from PyQt4 import QtCore import openlp diff --git a/openlp/plugins/__init__.py b/openlp/plugins/__init__.py index 1a348a0df..213c15d47 100644 --- a/openlp/plugins/__init__.py +++ b/openlp/plugins/__init__.py @@ -22,3 +22,6 @@ # with this program; if not, write to the Free Software Foundation, Inc., 59 # # Temple Place, Suite 330, Boston, MA 02111-1307 USA # ############################################################################### +""" +The :mod:`plugins` module provides all the project produced plugins +""" diff --git a/openlp/plugins/alerts/__init__.py b/openlp/plugins/alerts/__init__.py index 1a348a0df..cb376ec38 100644 --- a/openlp/plugins/alerts/__init__.py +++ b/openlp/plugins/alerts/__init__.py @@ -22,3 +22,7 @@ # with this program; if not, write to the Free Software Foundation, Inc., 59 # # Temple Place, Suite 330, Boston, MA 02111-1307 USA # ############################################################################### +""" +The :mod:`alerts` module provides the Alerts plugin for producing impromptu +on-screen announcements during a service +""" diff --git a/openlp/plugins/alerts/forms/alertform.py b/openlp/plugins/alerts/forms/alertform.py index 04028fc1b..012f195d1 100644 --- a/openlp/plugins/alerts/forms/alertform.py +++ b/openlp/plugins/alerts/forms/alertform.py @@ -32,11 +32,11 @@ from alertdialog import Ui_AlertDialog class AlertForm(QtGui.QDialog, Ui_AlertDialog): """ - Class documentation goes here. + Provide UI for the alert system """ def __init__(self, manager, parent): """ - Constructor + Initialise the alert form """ self.manager = manager self.parent = parent @@ -103,6 +103,9 @@ class AlertForm(QtGui.QDialog, Ui_AlertDialog): self.loadList() def onSaveClick(self): + """ + Save an alert + """ if self.item_id: alert = self.manager.get_alert(self.item_id) alert.text = unicode(self.AlertTextEdit.text()) @@ -113,7 +116,9 @@ class AlertForm(QtGui.QDialog, Ui_AlertDialog): self.onNewClick() def onTextChanged(self): - #Data has changed by editing it so potential storage required + """ + Enable save button when data has been changed by editing the form + """ self.SaveButton.setEnabled(True) def onDoubleClick(self): diff --git a/openlp/plugins/bibles/__init__.py b/openlp/plugins/bibles/__init__.py index 1a348a0df..ca5ff7508 100644 --- a/openlp/plugins/bibles/__init__.py +++ b/openlp/plugins/bibles/__init__.py @@ -22,3 +22,7 @@ # with this program; if not, write to the Free Software Foundation, Inc., 59 # # Temple Place, Suite 330, Boston, MA 02111-1307 USA # ############################################################################### +""" +The :mod:`bibles' modules provides the Bible plugin to enable OpenLP to display +scripture +""" diff --git a/openlp/plugins/bibles/bibleplugin.py b/openlp/plugins/bibles/bibleplugin.py index cfc6aa361..bfaa535a9 100644 --- a/openlp/plugins/bibles/bibleplugin.py +++ b/openlp/plugins/bibles/bibleplugin.py @@ -71,7 +71,7 @@ class BiblePlugin(Plugin): self.ImportBibleItem.setObjectName(u'ImportBibleItem') import_menu.addAction(self.ImportBibleItem) self.ImportBibleItem.setText( - import_menu.translate(u'BiblesPlugin.BiblePlugin', u'&Bible')) + translate(u'BiblesPlugin.BiblePlugin', u'&Bible')) # Signals and slots QtCore.QObject.connect(self.ImportBibleItem, QtCore.SIGNAL(u'triggered()'), self.onBibleImportClick) @@ -81,7 +81,7 @@ class BiblePlugin(Plugin): self.ExportBibleItem = QtGui.QAction(export_menu) self.ExportBibleItem.setObjectName(u'ExportBibleItem') export_menu.addAction(self.ExportBibleItem) - self.ExportBibleItem.setText(export_menu.translate( + self.ExportBibleItem.setText(translate( u'BiblesPlugin.BiblePlugin', u'&Bible')) self.ExportBibleItem.setVisible(False) diff --git a/openlp/plugins/songs/forms/__init__.py b/openlp/plugins/songs/forms/__init__.py index 6c6d4161d..e12ba048c 100644 --- a/openlp/plugins/songs/forms/__init__.py +++ b/openlp/plugins/songs/forms/__init__.py @@ -23,58 +23,6 @@ # Temple Place, Suite 330, Boston, MA 02111-1307 USA # ############################################################################### -from openlp.core.lib import translate - -class VerseType(object): - Verse = 0 - Chorus = 1 - Bridge = 2 - PreChorus = 3 - Intro = 4 - Ending = 5 - Other = 6 - - @staticmethod - def to_string(verse_type): - if verse_type == VerseType.Verse: - return translate(u'VerseType', u'Verse') - elif verse_type == VerseType.Chorus: - return translate(u'VerseType', u'Chorus') - elif verse_type == VerseType.Bridge: - return translate(u'VerseType', u'Bridge') - elif verse_type == VerseType.PreChorus: - return translate(u'VerseType', u'Pre-Chorus') - elif verse_type == VerseType.Intro: - return translate(u'VerseType', u'Intro') - elif verse_type == VerseType.Ending: - return translate(u'VerseType', u'Ending') - elif verse_type == VerseType.Other: - return translate(u'VerseType', u'Other') - - @staticmethod - def from_string(verse_type): - verse_type = verse_type.lower() - if verse_type == unicode(VerseType.to_string(VerseType.Verse)).lower(): - return VerseType.Verse - elif verse_type == \ - unicode(VerseType.to_string(VerseType.Chorus)).lower(): - return VerseType.Chorus - elif verse_type == \ - unicode(VerseType.to_string(VerseType.Bridge)).lower(): - return VerseType.Bridge - elif verse_type == \ - unicode(VerseType.to_string(VerseType.PreChorus)).lower(): - return VerseType.PreChorus - elif verse_type == \ - unicode(VerseType.to_string(VerseType.Intro)).lower(): - return VerseType.Intro - elif verse_type == \ - unicode(VerseType.to_string(VerseType.Ending)).lower(): - return VerseType.Ending - elif verse_type == \ - unicode(VerseType.to_string(VerseType.Other)).lower(): - return VerseType.Other - from authorsform import AuthorsForm from topicsform import TopicsForm from songbookform import SongBookForm diff --git a/openlp/plugins/songs/forms/editversedialog.py b/openlp/plugins/songs/forms/editversedialog.py index d70d5c5b4..086f4c416 100644 --- a/openlp/plugins/songs/forms/editversedialog.py +++ b/openlp/plugins/songs/forms/editversedialog.py @@ -26,7 +26,7 @@ from PyQt4 import QtCore, QtGui from openlp.core.lib import translate -from openlp.plugins.songs.forms import VerseType +from openlp.plugins.songs.lib import VerseType class Ui_EditVerseDialog(object): def setupUi(self, EditVerseDialog): diff --git a/openlp/plugins/songs/forms/editverseform.py b/openlp/plugins/songs/forms/editverseform.py index 56bb5de91..77e069e25 100644 --- a/openlp/plugins/songs/forms/editverseform.py +++ b/openlp/plugins/songs/forms/editverseform.py @@ -28,7 +28,7 @@ import logging from PyQt4 import QtCore, QtGui -from openlp.plugins.songs.forms import VerseType +from openlp.plugins.songs.lib import VerseType from editversedialog import Ui_EditVerseDialog diff --git a/openlp/plugins/songs/forms/songmaintenancedialog.py b/openlp/plugins/songs/forms/songmaintenancedialog.py index 81403bbe0..68ae105ca 100644 --- a/openlp/plugins/songs/forms/songmaintenancedialog.py +++ b/openlp/plugins/songs/forms/songmaintenancedialog.py @@ -31,7 +31,7 @@ class Ui_SongMaintenanceDialog(object): def setupUi(self, SongMaintenanceDialog): SongMaintenanceDialog.setObjectName(u'SongMaintenanceDialog') SongMaintenanceDialog.setWindowModality(QtCore.Qt.ApplicationModal) - SongMaintenanceDialog.resize(486, 361) + SongMaintenanceDialog.resize(582, 361) self.DialogLayout = QtGui.QVBoxLayout(SongMaintenanceDialog) self.DialogLayout.setSpacing(8) self.DialogLayout.setMargin(8) @@ -50,10 +50,10 @@ class Ui_SongMaintenanceDialog(object): sizePolicy.setHeightForWidth( self.TypeListWidget.sizePolicy().hasHeightForWidth()) self.TypeListWidget.setSizePolicy(sizePolicy) - self.TypeListWidget.setViewMode(QtGui.QListView.IconMode) - self.TypeListWidget.setIconSize(QtCore.QSize(112, 100)) + self.TypeListWidget.setViewMode(QtGui.QListView.ListMode) + self.TypeListWidget.setIconSize(QtCore.QSize(32, 32)) self.TypeListWidget.setMovement(QtGui.QListView.Static) - self.TypeListWidget.setMaximumWidth(118) + self.TypeListWidget.setMaximumWidth(172) self.TypeListWidget.setSpacing(0) self.TypeListWidget.setSortingEnabled(False) self.TypeListWidget.setUniformItemSizes(True) diff --git a/openlp/plugins/songs/lib/__init__.py b/openlp/plugins/songs/lib/__init__.py index bbb9260c6..6c637ea9e 100644 --- a/openlp/plugins/songs/lib/__init__.py +++ b/openlp/plugins/songs/lib/__init__.py @@ -23,10 +23,77 @@ # Temple Place, Suite 330, Boston, MA 02111-1307 USA # ############################################################################### +from openlp.core.lib import translate + +class VerseType(object): + """ + VerseType provides an enumeration for the tags that may be associated + with verses in songs. + """ + Verse = 0 + Chorus = 1 + Bridge = 2 + PreChorus = 3 + Intro = 4 + Ending = 5 + Other = 6 + + @staticmethod + def to_string(verse_type): + """ + Return a string for a given VerseType + + ``verse_type`` + The type to return a string for + """ + if verse_type == VerseType.Verse: + return translate(u'VerseType', u'Verse') + elif verse_type == VerseType.Chorus: + return translate(u'VerseType', u'Chorus') + elif verse_type == VerseType.Bridge: + return translate(u'VerseType', u'Bridge') + elif verse_type == VerseType.PreChorus: + return translate(u'VerseType', u'Pre-Chorus') + elif verse_type == VerseType.Intro: + return translate(u'VerseType', u'Intro') + elif verse_type == VerseType.Ending: + return translate(u'VerseType', u'Ending') + elif verse_type == VerseType.Other: + return translate(u'VerseType', u'Other') + + @staticmethod + def from_string(verse_type): + """ + Return the VerseType for a given string + + ``verse_type`` + The string to return a VerseType for + """ + verse_type = verse_type.lower() + if verse_type == unicode(VerseType.to_string(VerseType.Verse)).lower(): + return VerseType.Verse + elif verse_type == \ + unicode(VerseType.to_string(VerseType.Chorus)).lower(): + return VerseType.Chorus + elif verse_type == \ + unicode(VerseType.to_string(VerseType.Bridge)).lower(): + return VerseType.Bridge + elif verse_type == \ + unicode(VerseType.to_string(VerseType.PreChorus)).lower(): + return VerseType.PreChorus + elif verse_type == \ + unicode(VerseType.to_string(VerseType.Intro)).lower(): + return VerseType.Intro + elif verse_type == \ + unicode(VerseType.to_string(VerseType.Ending)).lower(): + return VerseType.Ending + elif verse_type == \ + unicode(VerseType.to_string(VerseType.Other)).lower(): + return VerseType.Other + from manager import SongManager from songstab import SongsTab from mediaitem import SongMediaItem from sofimport import SofImport from oooimport import OooImport from songimport import SongImport - diff --git a/openlp/plugins/songs/lib/songimport.py b/openlp/plugins/songs/lib/songimport.py index fa016729d..f3926425e 100644 --- a/openlp/plugins/songs/lib/songimport.py +++ b/openlp/plugins/songs/lib/songimport.py @@ -28,8 +28,8 @@ import string from PyQt4 import QtGui from openlp.core.lib import SongXMLBuilder +from openlp.plugins.songs.lib import VerseType from openlp.plugins.songs.lib.models import Song, Author, Topic, Book -from openlp.plugins.songs.forms import VerseType class SongImport(object): """ diff --git a/openlp/plugins/songs/songsplugin.py b/openlp/plugins/songs/songsplugin.py index f311d7072..dad471043 100644 --- a/openlp/plugins/songs/songsplugin.py +++ b/openlp/plugins/songs/songsplugin.py @@ -94,10 +94,10 @@ class SongsPlugin(Plugin): # Main song import menu item - will eventually be the only one self.SongImportItem = QtGui.QAction(import_menu) self.SongImportItem.setObjectName(u'SongImportItem') - self.SongImportItem.setText(import_menu.translate( + self.SongImportItem.setText(translate( u'SongsPlugin.SongsPlugin', u'&Song')) self.SongImportItem.setToolTip( - import_menu.translate(u'SongsPlugin.SongsPlugin', + translate(u'SongsPlugin.SongsPlugin', u'Import songs using the import wizard.')) import_menu.addAction(self.SongImportItem) # Songs of Fellowship import menu item - will be removed and the @@ -105,14 +105,14 @@ class SongsPlugin(Plugin): self.ImportSofItem = QtGui.QAction(import_menu) self.ImportSofItem.setObjectName(u'ImportSofItem') self.ImportSofItem.setText( - import_menu.translate(u'SongsPlugin.SongsPlugin', + translate(u'SongsPlugin.SongsPlugin', u'Songs of Fellowship (temp menu item)')) self.ImportSofItem.setToolTip( - import_menu.translate(u'SongsPlugin.SongsPlugin', + translate(u'SongsPlugin.SongsPlugin', u'Import songs from the VOLS1_2.RTF, sof3words' \ + u'.rtf and sof4words.rtf supplied with the music books')) self.ImportSofItem.setStatusTip( - import_menu.translate(u'SongsPlugin.SongsPlugin', + translate(u'SongsPlugin.SongsPlugin', u'Import songs from the VOLS1_2.RTF, sof3words' \ + u'.rtf and sof4words.rtf supplied with the music books')) import_menu.addAction(self.ImportSofItem) @@ -121,15 +121,15 @@ class SongsPlugin(Plugin): self.ImportOooItem = QtGui.QAction(import_menu) self.ImportOooItem.setObjectName(u'ImportOooItem') self.ImportOooItem.setText( - import_menu.translate(u'SongsPlugin.SongsPlugin', + translate(u'SongsPlugin.SongsPlugin', u'Generic Document/Presentation Import ' u'(temp menu item)')) self.ImportOooItem.setToolTip( - import_menu.translate(u'SongsPlugin.SongsPlugin', + translate(u'SongsPlugin.SongsPlugin', u'Import songs from ' u'Word/Writer/Powerpoint/Impress')) self.ImportOooItem.setStatusTip( - import_menu.translate(u'SongsPlugin.SongsPlugin', + translate(u'SongsPlugin.SongsPlugin', u'Import songs from ' u'Word/Writer/Powerpoint/Impress')) import_menu.addAction(self.ImportOooItem) @@ -169,9 +169,9 @@ class SongsPlugin(Plugin): except: log.exception('Could not import SoF file') QtGui.QMessageBox.critical(None, - self.ImportSongMenu.translate(u'SongsPlugin.SongsPlugin', + translate(u'SongsPlugin.SongsPlugin', u'Import Error'), - self.ImportSongMenu.translate(u'SongsPlugin.SongsPlugin', + translate(u'SongsPlugin.SongsPlugin', u'Error importing Songs of ' u'Fellowship file.\nOpenOffice.org must be installed' u' and you must be using an unedited copy of the RTF' diff --git a/openlp/plugins/songusage/songusageplugin.py b/openlp/plugins/songusage/songusageplugin.py index 35d86a16a..7cc75f764 100644 --- a/openlp/plugins/songusage/songusageplugin.py +++ b/openlp/plugins/songusage/songusageplugin.py @@ -59,24 +59,24 @@ class SongUsagePlugin(Plugin): self.toolsMenu = tools_menu self.SongUsageMenu = QtGui.QMenu(tools_menu) self.SongUsageMenu.setObjectName(u'SongUsageMenu') - self.SongUsageMenu.setTitle(tools_menu.translate( + self.SongUsageMenu.setTitle(translate( u'SongUsagePlugin.SongUsagePlugin', u'&Song Usage')) #SongUsage Delete self.SongUsageDelete = QtGui.QAction(tools_menu) self.SongUsageDelete.setText( - tools_menu.translate(u'SongUsagePlugin.SongUsagePlugin', + translate(u'SongUsagePlugin.SongUsagePlugin', u'&Delete recorded data')) self.SongUsageDelete.setStatusTip( - tools_menu.translate(u'SongUsagePlugin.SongUsagePlugin', + translate(u'SongUsagePlugin.SongUsagePlugin', u'Delete song usage to specified date')) self.SongUsageDelete.setObjectName(u'SongUsageDelete') #SongUsage Report self.SongUsageReport = QtGui.QAction(tools_menu) self.SongUsageReport.setText( - tools_menu.translate(u'SongUsagePlugin.SongUsagePlugin', + translate(u'SongUsagePlugin.SongUsagePlugin', u'&Extract recorded data')) self.SongUsageReport.setStatusTip( - tools_menu.translate(u'SongUsagePlugin.SongUsagePlugin', + translate(u'SongUsagePlugin.SongUsagePlugin', u'Generate report on Song Usage')) self.SongUsageReport.setObjectName(u'SongUsageReport') #SongUsage activation @@ -85,10 +85,10 @@ class SongUsagePlugin(Plugin): self.SongUsageStatus.setIcon(SongUsageIcon) self.SongUsageStatus.setCheckable(True) self.SongUsageStatus.setChecked(False) - self.SongUsageStatus.setText(tools_menu.translate( + self.SongUsageStatus.setText(translate( u'SongUsagePlugin.SongUsagePlugin', u'Song Usage Status')) self.SongUsageStatus.setStatusTip( - tools_menu.translate(u'SongUsagePlugin.SongUsagePlugin', + translate(u'SongUsagePlugin.SongUsagePlugin', u'Start/Stop live song usage recording')) self.SongUsageStatus.setShortcut(u'F4') self.SongUsageStatus.setObjectName(u'SongUsageStatus')