Added a lot of comments to functions in the source code

This commit is contained in:
Veronica K. B. Olsen
2020-05-24 16:42:28 +02:00
parent e1ce93416c
commit c865dbd59b
21 changed files with 273 additions and 82 deletions
+9 -1
View File
@@ -69,10 +69,14 @@ class PagedDialog(QDialog):
return
def addTab(self, tabWidget, tabLabel):
"""Forwards the adding of tabs to the QTabWidget.
"""
self._tabBox.addTab(tabWidget, tabLabel)
return
def addControls(self, buttonBar):
"""Adds a button bar to the dialog.
"""
self._buttonBox.addWidget(buttonBar)
return
@@ -85,12 +89,16 @@ class VerticalTabBar(QTabBar):
return
def tabSizeHint(self, theIndex):
"""Returns a transposed size hint for the rotated bar.
"""
tSize = QTabBar.tabSizeHint(self, theIndex)
tSize.transpose()
return tSize
def paintEvent(self, theEvent):
"""Custom implementation of the label painter that rotates the
label 90 degrees.
"""
pObj = QStylePainter(self)
oObj = QStyleOptionTab()
+4 -2
View File
@@ -69,11 +69,15 @@ class QConfigLayout(QGridLayout):
return
def setHelpText(self, intRow, theText):
"""Set the text for the help label.
"""
if intRow in self._itemMap:
self._itemMap[intRow]["help"].setText(theText)
return
def setLabelText(self, intRow, theText):
"""Set the text for the main label.
"""
if intRow in self._itemMap:
self._itemMap[intRow]["label"].setText(theText)
return
@@ -85,7 +89,6 @@ class QConfigLayout(QGridLayout):
def addGroupLabel(self, theLabel):
"""Adds a text label to separate groups of settings.
"""
if isinstance(theLabel, QLabel):
qLabel = theLabel
elif isinstance(theLabel, str):
@@ -107,7 +110,6 @@ class QConfigLayout(QGridLayout):
def addRow(self, theLabel, theWidget, helpText=None, theUnit=None):
"""Add a label and a widget as a new row of the grid.
"""
thisEntry = {
"label" : None,
"help" : None,
-1
View File
@@ -97,7 +97,6 @@ class QSwitch(QAbstractButton):
def paintEvent(self, event):
"""Drawing the switch itself.
"""
qPaint = QPainter(self)
qPaint.setRenderHint(QPainter.Antialiasing, True)
qPaint.setPen(Qt.NoPen)
+20 -19
View File
@@ -143,31 +143,33 @@ class GuiDocDetails(QFrame):
self.pCountData.setAlignment(Qt.AlignRight)
# Assemble
self.mainBox.addWidget(self.labelName, 0, 0, 1, 1)
self.mainBox.addWidget(self.labelFlag, 0, 1, 1, 1)
self.mainBox.addWidget(self.labelData, 0, 2, 1, 3)
self.mainBox.addWidget(self.labelName, 0, 0, 1, 1, Qt.AlignTop)
self.mainBox.addWidget(self.labelFlag, 0, 1, 1, 1, Qt.AlignTop)
self.mainBox.addWidget(self.labelData, 0, 2, 1, 3, Qt.AlignTop)
self.mainBox.addWidget(self.statusName, 1, 0, 1, 1)
self.mainBox.addWidget(self.statusFlag, 1, 1, 1, 1)
self.mainBox.addWidget(self.statusData, 1, 2, 1, 1)
self.mainBox.addWidget(self.cCountName, 1, 3, 1, 1)
self.mainBox.addWidget(self.cCountData, 1, 4, 1, 1)
self.mainBox.addWidget(self.statusName, 1, 0, 1, 1, Qt.AlignTop)
self.mainBox.addWidget(self.statusFlag, 1, 1, 1, 1, Qt.AlignTop)
self.mainBox.addWidget(self.statusData, 1, 2, 1, 1, Qt.AlignTop)
self.mainBox.addWidget(self.cCountName, 1, 3, 1, 1, Qt.AlignTop)
self.mainBox.addWidget(self.cCountData, 1, 4, 1, 1, Qt.AlignTop)
self.mainBox.addWidget(self.className, 2, 0, 1, 1)
self.mainBox.addWidget(self.classFlag, 2, 1, 1, 1)
self.mainBox.addWidget(self.classData, 2, 2, 1, 1)
self.mainBox.addWidget(self.wCountName, 2, 3, 1, 1)
self.mainBox.addWidget(self.wCountData, 2, 4, 1, 1)
self.mainBox.addWidget(self.className, 2, 0, 1, 1, Qt.AlignTop)
self.mainBox.addWidget(self.classFlag, 2, 1, 1, 1, Qt.AlignTop)
self.mainBox.addWidget(self.classData, 2, 2, 1, 1, Qt.AlignTop)
self.mainBox.addWidget(self.wCountName, 2, 3, 1, 1, Qt.AlignTop)
self.mainBox.addWidget(self.wCountData, 2, 4, 1, 1, Qt.AlignTop)
self.mainBox.addWidget(self.layoutName, 3, 0, 1, 1)
self.mainBox.addWidget(self.layoutFlag, 3, 1, 1, 1)
self.mainBox.addWidget(self.layoutData, 3, 2, 1, 1)
self.mainBox.addWidget(self.pCountName, 3, 3, 1, 1)
self.mainBox.addWidget(self.pCountData, 3, 4, 1, 1)
self.mainBox.addWidget(self.layoutName, 3, 0, 1, 1, Qt.AlignTop)
self.mainBox.addWidget(self.layoutFlag, 3, 1, 1, 1, Qt.AlignTop)
self.mainBox.addWidget(self.layoutData, 3, 2, 1, 1, Qt.AlignTop)
self.mainBox.addWidget(self.pCountName, 3, 3, 1, 1, Qt.AlignTop)
self.mainBox.addWidget(self.pCountData, 3, 4, 1, 1, Qt.AlignTop)
self.mainBox.setColumnStretch(0,0)
self.mainBox.setColumnStretch(1,0)
self.mainBox.setColumnStretch(2,1)
self.mainBox.setColumnStretch(3,0)
self.mainBox.setColumnStretch(4,0)
logger.debug("DocDetails initialisation complete")
@@ -180,7 +182,6 @@ class GuiDocDetails(QFrame):
def updateViewBox(self, tHandle):
"""Populate the details box from a given handle.
"""
nwItem = self.theProject.projTree[tHandle]
if nwItem is None:
+28 -12
View File
@@ -141,7 +141,6 @@ class GuiDocEditor(QTextEdit):
"""Clear the current document and reset all document related
flags and counters.
"""
self.nwDocument.clearDocument()
self.setReadOnly(True)
self.clear()
@@ -167,7 +166,6 @@ class GuiDocEditor(QTextEdit):
settings. This function is both called when the editor is
created, and when the user changes the main editor preferences.
"""
# Some Constants
self.nonWord = "\"'"
self.nonWord += "".join(self.mainConf.fmtDoubleQuotes)
@@ -241,7 +239,6 @@ class GuiDocEditor(QTextEdit):
document is new (empty string), we set up the editor for editing
the file.
"""
theDoc = self.nwDocument.openDocument(tHandle, showStatus=showStatus)
if theDoc is None:
# There was an io error
@@ -319,7 +316,6 @@ class GuiDocEditor(QTextEdit):
Config.textFixedW is enabled or we're in Zen mode. Otherwise,
just ensure the margins are set correctly.
"""
if self.mainConf.textFixedW or self.theParent.isZenMode:
vBar = self.verticalScrollBar()
if vBar.isVisible():
@@ -376,6 +372,10 @@ class GuiDocEditor(QTextEdit):
##
def setDocumentChanged(self, bValue):
"""Keeps track of the document changed variable, and ensures
that the corresponding icon on the status bar shows the same
status.
"""
self.docChanged = bValue
self.theParent.statusBar.setDocumentStatus(self.docChanged)
return self.docChanged
@@ -437,7 +437,6 @@ class GuiDocEditor(QTextEdit):
If the spell check mode (theMode) is not defined (None), then
toggle the current status saved in this class.
"""
if theMode is None:
theMode = not self.spellCheck
@@ -460,7 +459,6 @@ class GuiDocEditor(QTextEdit):
currently loaded text. The fastest way to do this, at least as
of Qt 5.13, is to clear the text and put it back.
"""
logger.verbose("Running spell checker")
if self.spellCheck:
bfTime = time()
@@ -481,6 +479,12 @@ class GuiDocEditor(QTextEdit):
##
def docAction(self, theAction):
"""Perform an action on the current document based on an action
flag. This is just a single entry point wrapper function to
ensure all the feature functions get the correct information
passed to it without having to consider the internal logic of
this class when calling these actions from other classes.
"""
logger.verbose("Requesting action: %s" % theAction.name)
if not self.theParent.hasProject:
logger.error("No project open")
@@ -537,9 +541,14 @@ class GuiDocEditor(QTextEdit):
return True
def isEmpty(self):
"""Wrapper function to check if the current document is empty.
"""
return self.qDocument.isEmpty()
def revealLocation(self):
"""Tell the user where on the file system the file in the editor
is saved.
"""
if self.theHandle is not None:
msgBox = QMessageBox()
msgBox.information(self, "File Location", (
@@ -568,7 +577,6 @@ class GuiDocEditor(QTextEdit):
However, we don't want to spend a lot of time in this function
as it is triggered on every keypress when typing.
"""
self.hasSelection = self.textCursor().hasSelection()
if keyEvent.modifiers() == Qt.ShiftModifier:
@@ -628,7 +636,6 @@ class GuiDocEditor(QTextEdit):
"""Triggered by right click to open the context menu. Also
triggered by the Ctrl+. shortcut.
"""
if not self.spellCheck:
return
@@ -667,7 +674,11 @@ class GuiDocEditor(QTextEdit):
return
@pyqtSlot("QTextCursor", str)
def _correctWord(self, theCursor, theWord):
"""Slot for the spell check context menu triggering the
replacement of a word with the word from the dictionary.
"""
xPos = theCursor.selectionStart()
theCursor.beginEditBlock()
theCursor.removeSelectedText()
@@ -677,7 +688,11 @@ class GuiDocEditor(QTextEdit):
self.setTextCursor(theCursor)
return
@pyqtSlot("QTextCursor")
def _addWord(self, theCursor):
"""Slot for the spell check context menu triggered when the user
wants to add a word to the project dictionary.
"""
theWord = theCursor.selectedText().strip().strip(self.nonWord)
logger.debug("Added '%s' to project dictionary" % theWord)
self.theDict.addWord(theWord)
@@ -729,7 +744,6 @@ class GuiDocEditor(QTextEdit):
tag and can tell the document viewer to try and find and load
the file where the tag is defined.
"""
if theCursor is None:
theCursor = self.textCursor()
@@ -772,13 +786,15 @@ class GuiDocEditor(QTextEdit):
return
def _openSpellContext(self):
"""Opens the spell check context menu at the current point of
the cursor.
"""
self._openContextMenu(self.cursorRect().center())
return
def _docAutoReplace(self, theBlock):
"""Autoreplace text elements based on main configuration.
"""
if not theBlock.isValid():
return
@@ -870,7 +886,6 @@ class GuiDocEditor(QTextEdit):
def _formatBlock(self, docAction):
"""Changes the block format of the block under the cursor.
"""
theCursor = self.textCursor()
theBlock = theCursor.block()
if not theBlock.isValid():
@@ -949,6 +964,8 @@ class GuiDocEditor(QTextEdit):
return
def _makeSelection(self, selMode):
"""Wrapper function to select a word based on a selection mode.
"""
theCursor = self.textCursor()
theCursor.clearSelection()
theCursor.select(selMode)
@@ -1025,7 +1042,6 @@ class GuiDocEditor(QTextEdit):
"""Create the spell checking object based on the spellTool
setting in config.
"""
if self.mainConf.spellTool == "enchant":
from nw.core.spellcheck import NWSpellEnchant
self.theDict = NWSpellEnchant()
-1
View File
@@ -79,7 +79,6 @@ class GuiDocTitleBar(QLabel):
"""Sets the document title from the handle, or alternatively,
set the whole document path.
"""
self.setText("")
self.theHandle = tHandle
if tHandle is None:
+42 -5
View File
@@ -105,13 +105,19 @@ class GuiDocTree(QTreeWidget):
##
def clearTree(self):
"""Clear the GUI content and the related maps.
"""
self.clear()
self.theMap = {}
self.orphRoot = None
return
def newTreeItem(self, itemType, itemClass):
"""Add new item to the tree, with a given itemType and
itemClass, and attach it to the selected handle. Also make sure
the item is added in a place it can be added, and that other
meta data is set correctly to ensure a valid project tree.
"""
pHandle = self.getSelectedHandle()
if not self.theParent.hasProject:
@@ -274,7 +280,6 @@ class GuiDocTree(QTreeWidget):
function only asks for confirmation once, and calls the regular
deleteItem function for each document in the Trash folder.
"""
trashHandle = self.theProject.projTree.trashRoot()
logger.debug("Emptying Trash folder")
@@ -315,7 +320,6 @@ class GuiDocTree(QTreeWidget):
that to save memory. Items not in the tree are not saved to the
project file, so a loaded project will be clean anyway.
"""
if tHandle is None:
tHandle = self.getSelectedHandle()
@@ -446,6 +450,13 @@ class GuiDocTree(QTreeWidget):
return
def propagateCount(self, tHandle, theCount, nDepth=0):
"""Recursive function setting the word count for a given item,
and propagating that count upwards in the tree until reaching a
root item. This function is more efficient than recalculating
everything each time the word count is updated, but is also
prone to diverging from the true values if the counts are not
properly reported to the function.
"""
tItem = self._getTreeItem(tHandle)
if tItem is not None:
tItem.setText(self.C_COUNT,str(theCount))
@@ -460,6 +471,12 @@ class GuiDocTree(QTreeWidget):
return
def projectWordCount(self):
"""Sum up the word counts for all root items and set the
relevant values in the project and on the status bar. This call
is a fast way of getting this number, and depends on the
propagateCount function being called when it should to maintain
the correct count.
"""
nWords = 0
for n in range(self.topLevelItemCount()):
tItem = self.topLevelItem(n)
@@ -472,6 +489,11 @@ class GuiDocTree(QTreeWidget):
return
def buildTree(self):
"""Build the entire project tree from scratch. This depends on
the save project item iterator in the project class which will
always make sure items with a parent have had their parent item
sent first.
"""
self.clear()
for nwItem in self.theProject.getProjectItems():
self._addTreeItem(nwItem)
@@ -517,11 +539,16 @@ class GuiDocTree(QTreeWidget):
##
def _getTreeItem(self, tHandle):
"""Returns the QTreeWidgetItem of a given item handle.
"""
if tHandle in self.theMap.keys():
return self.theMap[tHandle]
return None
def _scanChildren(self, theList, theItem, theIndex):
"""This is a recursive function returning all items in a tree
starting at a given QTreeWidgetItem.
"""
tHandle = theItem.text(self.C_HANDLE)
nwItem = self.theProject.projTree[tHandle]
nwItem.setExpanded(theItem.isExpanded())
@@ -532,7 +559,9 @@ class GuiDocTree(QTreeWidget):
return theList
def _addTreeItem(self, nwItem):
"""Create a QTreeWidgetItem from an NWItem and add it to the
project tree.
"""
tHandle = nwItem.itemHandle
pHandle = nwItem.parHandle
tClass = nwItem.itemClass
@@ -591,6 +620,9 @@ class GuiDocTree(QTreeWidget):
return trItem
def _addOrphanedRoot(self):
"""Add the special Orphaned Files root item to hold non-root
items with no parent set.
"""
if self.orphRoot is None:
newItem = QTreeWidgetItem([""]*4)
newItem.setText(self.C_NAME, "Orphaned Files")
@@ -604,6 +636,8 @@ class GuiDocTree(QTreeWidget):
return
def _cleanOrphanedRoot(self):
"""Remove the special Orphaned Files root folder if it is empty.
"""
if self.orphRoot is not None:
if self.orphRoot.childCount() == 0:
self.takeTopLevelItem(self.indexOfTopLevelItem(self.orphRoot))
@@ -615,7 +649,6 @@ class GuiDocTree(QTreeWidget):
in the project is consistent with the treeView. Also move the
word count over to the new parent tree.
"""
trItemS = self._getTreeItem(tHandle)
nwItemS = self.theProject.projTree[tHandle]
trItemP = trItemS.parent()
@@ -636,6 +669,10 @@ class GuiDocTree(QTreeWidget):
return True
def _moveOrphanedItem(self, tHandle, dHandle):
"""Move an Orphaned Item to a new dHandle parent item. This
function will set all the missing meta data based on the meta
data of the destination item.
"""
trItemS = self._getTreeItem(tHandle)
nwItemS = self.theProject.projTree[tHandle]
nwItemD = self.theProject.projTree[dHandle]
+17 -5
View File
@@ -88,7 +88,6 @@ class GuiDocViewer(QTextBrowser):
def initViewer(self):
"""Set editor settings from main config.
"""
self._makeStyleSheet()
# Set Font
@@ -122,7 +121,6 @@ class GuiDocViewer(QTextBrowser):
def loadText(self, tHandle):
"""Load text into the viewer from an item handle.
"""
tItem = self.theProject.projTree[tHandle]
if tItem is None:
logger.warning("Item not found")
@@ -153,11 +151,16 @@ class GuiDocViewer(QTextBrowser):
return True
def reloadText(self):
"""Reload the text in the current document.
"""
self.loadText(self.theHandle)
return
def loadFromTag(self, theTag):
"""Load text in the document from a reference given by a meta
tag rather than a known handle. This function depends on the
index being up to date.
"""
logger.debug("Loading document from tag '%s'" % theTag)
if theTag in self.theParent.theIndex.tagIndex.keys():
@@ -175,6 +178,9 @@ class GuiDocViewer(QTextBrowser):
return True
def docAction(self, theAction):
"""Wrapper function for various document actions on the current
document.
"""
logger.verbose("Requesting action: %s" % theAction.name)
if self.theHandle is None:
logger.error("No document open")
@@ -225,6 +231,9 @@ class GuiDocViewer(QTextBrowser):
##
def _makeSelection(self, selMode):
"""Wrapper function for making a selection based on a specific
selection mode.
"""
theCursor = self.textCursor()
theCursor.clearSelection()
theCursor.select(selMode)
@@ -232,7 +241,8 @@ class GuiDocViewer(QTextBrowser):
return
def _linkClicked(self, theURL):
"""Slot for a link in the document being clicked.
"""
theLink = theURL.url()
tHandle = None
onLine = 0
@@ -256,7 +266,9 @@ class GuiDocViewer(QTextBrowser):
return
def _makeStyleSheet(self):
"""Generate an appropriate style sheet for the document viewer,
based on the current syntax highlighter theme,
"""
styleSheet = (
"body {{"
" color: rgb({tColR},{tColG},{tColB});"
+4
View File
@@ -67,11 +67,15 @@ class GuiNoticeBar(QFrame):
return
def showNote(self, theNote):
"""Show the note on the noticebar.
"""
self.noteLabel.setText("<b>Note:</b> %s" % theNote)
self.setVisible(True)
return
def hideNote(self):
"""Clear the noticebar and hide it.
"""
self.noteLabel.setText("")
self.setVisible(False)
return
-4
View File
@@ -125,7 +125,6 @@ class GuiProjectOutline(QTreeWidget):
"""Clear the tree and header and set the default values for the
columns arrays.
"""
self.clear()
self.setColumnCount(1)
self.setHeaderLabel(nwLabels.OUTLINE_COLS[nwOutline.TITLE])
@@ -150,7 +149,6 @@ class GuiProjectOutline(QTreeWidget):
what data to load, and if necessary, force a rebuild of the
tree.
"""
# If it's the first time, we always build
if self.firstView or self.firstView and overRide:
self._loadHeaderState()
@@ -229,7 +227,6 @@ class GuiProjectOutline(QTreeWidget):
"""Load the state of the main tree header, that is, column order
and column width.
"""
# Load whatever we saved last time, regardless of wether it
# contains the correct names or number of columns. The names
# must be valid though.
@@ -280,7 +277,6 @@ class GuiProjectOutline(QTreeWidget):
save the current width of hidden columns though. This preserves
the last known width in case they're unhidden again.
"""
# If we haven't built the tree, there is nothing to save.
if self.lastBuild == 0:
return
+17
View File
@@ -98,6 +98,9 @@ class GuiSearchBar(QFrame):
##
def setSearchText(self, theText):
"""Open the search bar and set the search text to the text
provided, if any.
"""
if not self.isVisible():
self.setVisible(True)
self.searchBox.setText(theText)
@@ -106,15 +109,21 @@ class GuiSearchBar(QFrame):
return True
def setReplaceText(self, theText):
"""Set the replace text.
"""
self._replaceVisible(True)
self.replaceBox.setFocus()
self.replaceBox.setText(theText)
return True
def getSearchText(self):
"""Return the current search text.
"""
return self.searchBox.text()
def getReplaceText(self):
"""Return the current replace text.
"""
return self.replaceBox.text()
##
@@ -122,11 +131,15 @@ class GuiSearchBar(QFrame):
##
def _doClose(self):
"""Hide the search/replace bar.
"""
self._replaceVisible(False)
self.setVisible(False)
return
def _doSearch(self):
"""Call the search action function for the document editor.
"""
modKey = qApp.keyboardModifiers()
if modKey == Qt.ShiftModifier:
self.theParent.docEditor.docAction(nwDocAction.GO_PREV)
@@ -135,10 +148,14 @@ class GuiSearchBar(QFrame):
return
def _doReplace(self):
"""Call the replace action function for the document editor.
"""
self.theParent.docEditor.docAction(nwDocAction.REPL_NEXT)
return
def _replaceVisible(self, isVisible):
"""Set the visibility of all the replace widgets.
"""
self.replaceLabel.setVisible(isVisible)
self.replaceBox.setVisible(isVisible)
self.replaceButton.setVisible(isVisible)
+10 -1
View File
@@ -94,7 +94,9 @@ class GuiDocViewDetails(QWidget):
return
def refreshReferences(self, tHandle):
"""Update the current list of document references from the
project index.
"""
self.currHandle = tHandle
if self.isSticky.isChecked():
@@ -117,12 +119,17 @@ class GuiDocViewDetails(QWidget):
##
def _linkClicked(self, theLink):
"""Capture the link-click and forward it to the document viewer
class for handling.
"""
if len(theLink) == 18:
tHandle = theLink[-13:]
self.theParent.viewDocument(tHandle)
return
def _doShowHide(self, chState):
"""Toggle the expand/collapse of the panel.
"""
self.scrollBox.setVisible(chState)
self.mainConf.setShowRefPanel(chState)
if chState:
@@ -132,6 +139,8 @@ class GuiDocViewDetails(QWidget):
return
def _doSticky(self, chState):
"""Toggle the sticky feature of the references.
"""
if not chState and self.currHandle is not None:
self.refreshReferences(self.currHandle)
return
+10 -2
View File
@@ -75,6 +75,9 @@ class GuiDocHighlighter(QSyntaxHighlighter):
return
def initHighlighter(self):
"""Initialise the syntax highlighter, setting all the colour
rules and building the regexes.
"""
logger.debug("Setting up highlighting rules")
@@ -205,14 +208,21 @@ class GuiDocHighlighter(QSyntaxHighlighter):
##
def setDict(self, theDict):
"""Set the dictionary object for spell check underlines lookup.
"""
self.theDict = theDict
return True
def setSpellCheck(self, theMode):
"""Enable/disable the real time spell checker.
"""
self.spellCheck = theMode
return True
def setHandle(self, theHandle):
"""Set the handle of the currently highlighted document. This is
needed for the index lookup for validating tags and references.
"""
self.theHandle = theHandle
return True
@@ -226,7 +236,6 @@ class GuiDocHighlighter(QSyntaxHighlighter):
is significantly faster than running the regex checks we use for
text paragraphs.
"""
if self.theHandle is None or not theText:
return
@@ -317,7 +326,6 @@ class GuiDocHighlighter(QSyntaxHighlighter):
"""Generate a valid character format to be applied to the text
that is to be highlighted.
"""
theFormat = QTextCharFormat()
if fmtCol is not None:
-2
View File
@@ -51,7 +51,6 @@ class OptionState():
def loadSettings(self):
"""Load the options dictionary from the project settings file.
"""
if self.theProject.projMeta is None:
return False
@@ -76,7 +75,6 @@ class OptionState():
def saveSettings(self):
"""Save the options dictionary to the project settings file.
"""
if self.theProject.projMeta is None:
return False
+3 -1
View File
@@ -45,7 +45,9 @@ class WordCounter(QThread):
return
def run(self):
"""Overloaded run function for the word counter, forwarding the
call to the function that does the actual counting.
"""
theText = self.theParent.getText()
cC, wC, pC = countWords(theText)