diff -r 0516f6548ca6 -r cd90bfdc1247 UI/CodeDocumentationViewer.py
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/UI/CodeDocumentationViewer.py Sat Oct 14 20:07:08 2017 +0200
@@ -0,0 +1,183 @@
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2017 Detlev Offenbach <detlev@die-offenbachs.de>
+#
+
+"""
+Module implementing a widget to show some source code information provided by
+plug-ins.
+"""
+
+from __future__ import unicode_literals
+
+from PyQt5.QtCore import pyqtSlot, pyqtSignal
+from PyQt5.QtWidgets import QWidget
+
+from .Ui_CodeDocumentationViewer import Ui_CodeDocumentationViewer
+
+import Preferences
+
+
+class CodeDocumentationViewer(QWidget, Ui_CodeDocumentationViewer):
+ """
+ Class implementing a widget to show some source code information provided
+ by plug-ins.
+ """
+ providerAdded = pyqtSignal()
+
+ def __init__(self, parent=None):
+ """
+ Constructor
+
+ @param parent reference to the parent widget
+ @type QWidget
+ """
+ super(CodeDocumentationViewer, self).__init__(parent)
+ self.setupUi(self)
+
+ self.__ui = parent
+
+ self.__providers = {}
+ self.__selectedProvider = ""
+ self.__disabledProvider = "disabled"
+
+ self.__shuttingDown = False
+ self.__startingUp = True
+
+ self.__noDocumentationString = self.tr("No documentation available")
+ self.__disabledString = self.tr(
+ "No source code documentation provider has been registered or"
+ " this function has been disabled.")
+
+ self.providerComboBox.addItem(self.tr("<disabled>"), "disabled")
+
+ def finalizeSetup(self):
+ """
+ Public method to finalize the setup of the documentation viewer.
+ """
+ self.__startingUp = False
+ provider = Preferences.Prefs.settings.value(
+ "CodeDocumentationViewer/Provider", "disabled")
+ if provider in self.__providers:
+ index = self.providerComboBox.findData(provider)
+ else:
+ index = 0
+ self.providerComboBox.setCurrentIndex(index)
+
+ def registerProvider(self, providerName, providerDisplay, provider):
+ """
+ Public method register a source docu provider.
+
+ @param providerName name of the provider (must be unique)
+ @type str
+ @param providerDisplay visible name of the provider
+ @type str
+ @param provider function to be called to determine source docu
+ @type function
+ @exception KeyError raised if a provider with the given name was
+ already registered
+ """
+ if providerName in self.__providers:
+ raise KeyError(
+ "Provider '{0}' already registered.".format(providerName))
+
+ self.__providers[providerName] = provider
+ self.providerComboBox.addItem(providerDisplay, providerName)
+
+ def unregisterProvider(self, providerName):
+ """
+ Public method register a source docu provider.
+
+ @param providerName name of the provider (must be unique)
+ @type str
+ """
+ if providerName in self.__providers:
+ if providerName == self.__selectedProvider:
+ self.providerComboBox.setCurrentIndex(0)
+
+ del self.__providers[providerName]
+ index = self.providerComboBox.findData(providerName)
+ self.providerComboBox.removeItem(index)
+
+ def showInfo(self, editor):
+ """
+ Public method to request code documentation data from a provider.
+
+ @param editor reference to the editor to request code docu for
+ @type Editor
+ """
+ if self.__selectedProvider != self.__disabledProvider:
+ self.contents.clear()
+ self.__providers[self.__selectedProvider](editor)
+
+ def documentationReady(self, documentationInfo):
+ """
+ Public method to provide the documentation info to the viewer.
+
+ If documentationInfo is a dictionary, it should contains these keys
+ and data:
+
+ name: the name of the inspected object
+ argspec: its argspec
+ note: A phrase describing the type of object (function or method) and
+ the module it belongs to.
+ docstring: its documentation string
+
+ @param documentationInfo dictionary containing the source docu data
+ @type dict or str
+ """
+ self.__ui.activateCodeDocumentationViewer(switchFocus=False)
+
+ if not documentationInfo:
+ fullText = self.__noDocumentationString
+ elif isinstance(documentationInfo, str):
+ fullText = documentationInfo
+ elif isinstance(documentationInfo, dict):
+ name = documentationInfo["name"]
+ if name:
+ title = "".join(["=" * len(name), "\n", name, "\n",
+ "=" * len(name), "\n\n"])
+ else:
+ title = ""
+
+ if documentationInfo["argspec"]:
+ definition = self.tr("Definition: {0}{1}\n").format(
+ name, documentationInfo["argspec"])
+ else:
+ definition = ''
+
+ if documentationInfo["note"]:
+ note = self.tr("Info: {0}\n\n----\n\n").format(
+ documentationInfo["note"])
+ else:
+ note = ""
+
+ fullText = "".join([title, definition, note,
+ documentationInfo['docstring']])
+
+ self.contents.setPlainText(fullText)
+
+ @pyqtSlot(int)
+ def on_providerComboBox_currentIndexChanged(self, index):
+ """
+ Private slot to handle the selection of a provider.
+
+ @param index index of the selected provider
+ @type int
+ """
+ if not self.__shuttingDown and not self.__startingUp:
+ provider = self.providerComboBox.itemData(index)
+ if provider == self.__disabledProvider:
+ self.documentationReady(self.__disabledString)
+ elif provider in self.__providers:
+ Preferences.Prefs.settings.setValue(
+ "CodeDocumentationViewer/Provider", provider)
+ self.__selectedProvider = provider
+
+ def shutdown(self):
+ """
+ Public method to perform shutdown actions.
+ """
+ self.__shuttingDown = True
+ Preferences.Prefs.settings.setValue(
+ "CodeDocumentationViewer/Provider", self.__selectedProvider)
