From 244f94f0028f7cbdfa3b96306c19cafe5511c91f Mon Sep 17 00:00:00 2001 From: Eugenio Parodi Date: Tue, 8 Mar 2022 11:19:53 +0000 Subject: [PATCH] Added Checkbox documentation and refined doc structure --- Makefile | 2 ++ TermTk/TTkCore/constant.py | 9 +++++- TermTk/TTkWidgets/button.py | 12 +++++--- TermTk/TTkWidgets/checkbox.py | 58 ++++++++++++++++++++++++++++++++++- docs/MDNotes/Resources.md | 10 ++++-- docs/sphynx.001.signal.patch | 19 ++++++++++++ 6 files changed, 100 insertions(+), 10 deletions(-) create mode 100644 docs/sphynx.001.signal.patch diff --git a/Makefile b/Makefile index 010f9d60..b922c924 100644 --- a/Makefile +++ b/Makefile @@ -4,6 +4,8 @@ python3 -m venv .venv . .venv/bin/activate ; \ pip install -r docs/requirements.txt + # Add "Signal" option in the method domains + patch -p0 < docs/sphynx.001.signal.patch # Regen requirements; # pip freeze > docs/requirements.txt diff --git a/TermTk/TTkCore/constant.py b/TermTk/TTkCore/constant.py index 12f15502..b6ae689f 100644 --- a/TermTk/TTkCore/constant.py +++ b/TermTk/TTkCore/constant.py @@ -87,6 +87,13 @@ class TTkConstant: ScrollBarAlwaysOn = ScrollBarPolicy.ScrollBarAlwaysOn class CheckState: + ''' This class type is used to describe the check status. + + .. autosummary:: + Unchecked + PartiallyChecked + Checked + ''' Unchecked = 0x00 PartiallyChecked = 0x01 Checked = 0x02 @@ -693,4 +700,4 @@ class TTkConstant: # Alias to TTkConstant -class TTkK(TTkConstant): pass \ No newline at end of file +class TTkK(TTkConstant): pass diff --git a/TermTk/TTkWidgets/button.py b/TermTk/TTkWidgets/button.py index b5019fe2..aade8a55 100644 --- a/TermTk/TTkWidgets/button.py +++ b/TermTk/TTkWidgets/button.py @@ -43,12 +43,12 @@ class TTkButton(TTkWidget): [ Text ] - The TTkWidget class is the base class of all user interface objects + Demo: `formwidgets.py `_ :param str text: the text shown on the button, defaults to "" :type text: str, optional :param bool border: the border of the button, defaults to "False" - :type text: str, optional + :type border: bool, optional :param TTkColor color: the color of the border of the button, defaults to :class:`~TermTk.TTkGui.theme.TTkTheme.buttonTextColor` :type color: :class:`~TermTk.TTkCore.color.TTkColor`, optional :param TTkColor borderColor: the color of the border of the button, defaults to :class:`~TermTk.TTkGui.theme.TTkTheme.buttonBorderColor` @@ -57,11 +57,13 @@ class TTkButton(TTkWidget): ''' __slots__ = ( - '_text', '_border', '_pressed', 'clicked', '_keyPressed', + '_text', '_border', '_pressed', '_keyPressed', '_borderColor', '_textColor', '_borderColorClicked', '_textColorClicked', '_borderColorFocus', '_textColorFocus' - '_borderColorDisabled','_textColorDisabled' + '_borderColorDisabled','_textColorDisabled', + # Signals + 'clicked' ) def __init__(self, *args, **kwargs): @@ -162,4 +164,4 @@ class TTkButton(TTkWidget): def text(self, text): self._text = text self.setMinimumSize(len(text), 1) - self.update() \ No newline at end of file + self.update() diff --git a/TermTk/TTkWidgets/checkbox.py b/TermTk/TTkWidgets/checkbox.py index 175c41d6..2fb61c80 100644 --- a/TermTk/TTkWidgets/checkbox.py +++ b/TermTk/TTkWidgets/checkbox.py @@ -29,7 +29,52 @@ from TermTk.TTkCore.color import TTkColor from TermTk.TTkWidgets.widget import * class TTkCheckbox(TTkWidget): - __slots__ = ('_checked', '_text', 'clicked', 'stateChanged', ) + ''' + **Checked** + :: + + [X]CheckBox + + **Unchecked** + :: + + [ ]CheckBox + + Demo: `formwidgets.py `_ + + :param str text: the text shown on the checkbox, defaults to "" + :type text: str, optional + :param bool checked: Checked status, defaults to "False" + :type checked: bool, optional + + **Signals** + + Signals: + + .. py:method:: clicked(checked) + :signal: + + This signal is emitted when the button is activated + + :param checked: True if checked otherwise False + :type checked: bool + + .. py:method:: stateChanged(state) + :signal: + + This signal is emitted whenever the checkbox's state changes, i.e., whenever the user checks or unchecks it. + + :param state: state of the checkbox + :type state: :class:`~TermTk.TTkCore.constant.TTkConstant.CheckState` + + .. + + ''' + __slots__ = ( + '_checked', '_text', + # Signals + 'clicked', 'stateChanged' + ) def __init__(self, *args, **kwargs): TTkWidget.__init__(self, *args, **kwargs) self._name = kwargs.get('name' , 'TTkCheckbox' ) @@ -43,12 +88,23 @@ class TTkCheckbox(TTkWidget): self.setFocusPolicy(TTkK.ClickFocus + TTkK.TabFocus) def checkState(self): + ''' Retrieve the state of the checkbox + + :return: :class:`~TermTk.TTkCore.constant.TTkConstant.CheckState` : the checkbox status + ''' if self._checked: return TTkK.Checked else: return TTkK.Unchecked def setCheckState(self, state): + ''' Sets the checkbox's check state. + + :param state: state of the checkbox + :type state: :class:`~TermTk.TTkCore.constant.TTkConstant.CheckState` + ''' + + self._checked = state == TTkK.Checked self.update() diff --git a/docs/MDNotes/Resources.md b/docs/MDNotes/Resources.md index 9bcfb059..6492699f 100644 --- a/docs/MDNotes/Resources.md +++ b/docs/MDNotes/Resources.md @@ -1,4 +1,3 @@ - ## Python Refactoring * From [sourcery](https://sourcery.ai/blog)'s [Blog](https://sourcery.ai/blog/) [explaining-refactorings-1](https://sourcery.ai/blog/explaining-refactorings-1/) @@ -16,7 +15,12 @@ https://en.wikipedia.org/wiki/Halfwidth_and_fullwidth_forms https://en.wikipedia.org/wiki/Halfwidth_and_Fullwidth_Forms_(Unicode_block) - ## Terminal #### Hyperlink -https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda \ No newline at end of file +https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda + +## Sphinx Doc +#### Domains - docstring syntax +https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-py-class +#### ReStructuredText +https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#explicit-markup-blocks \ No newline at end of file diff --git a/docs/sphynx.001.signal.patch b/docs/sphynx.001.signal.patch new file mode 100644 index 00000000..a4346281 --- /dev/null +++ b/docs/sphynx.001.signal.patch @@ -0,0 +1,19 @@ +--- .venv/lib/python3.8/site-packages/sphinx/domains/python.py 2022-03-08 11:00:06.152347159 +0000 ++++ .venv/lib/python3.8/site-packages/sphinx/domains/python.py 2022-03-08 11:03:07.292940495 +0000 +@@ -795,6 +795,7 @@ + + option_spec = PyObject.option_spec.copy() + option_spec.update({ ++ 'signal': directives.flag, + 'abstractmethod': directives.flag, + 'async': directives.flag, + 'classmethod': directives.flag, +@@ -813,6 +814,8 @@ + prefix = [] + if 'final' in self.options: + prefix.append('final') ++ if 'signal' in self.options: ++ prefix.append('signal') + if 'abstractmethod' in self.options: + prefix.append('abstract') + if 'async' in self.options: