Skip to content

Commit

Permalink
improve sphinx docs (#209)
Browse files Browse the repository at this point in the history 
fixing #207
fixing #204
  • Loading branch information
@typemytype
typemytype committed May 8, 2024
1 parent 32ce13d commit 7ec2205
Show file tree
Hide file tree
Showing 7 changed files with 49 additions and 404 deletions.
15 changes: 14 additions & 1 deletion Documentation/source/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,11 @@

# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.autodoc', 'sphinx_rtd_theme']
extensions = [
'sphinx.ext.autodoc',
'sphinx_rtd_theme',
'sphinx.ext.todo'
]

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
Expand Down Expand Up @@ -227,6 +231,15 @@ def __call__(self, *args, **kwargs):
def __getattr__(cls, name):
if name in ('__file__', '__path__'):
return '/dev/null'
elif name == "NSObject":
return object
elif name == "python_method":
def dummyDecorator(func):
def wrapper(*args, **kwargs):
return func(*args, **kwargs)
wrapper.__doc__ = func.__doc__
return wrapper
return dummyDecorator
else:
return Mock

Expand Down
1 change: 1 addition & 0 deletions Documentation/source/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ Windows

objects/Window
objects/FloatingWindow
objects/ModalWindow
objects/Sheet
objects/Drawer

Expand Down
188 changes: 0 additions & 188 deletions Documentation/source/objects/FloatingWindow.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,194 +9,6 @@ FloatingWindow
:inherited-members:
:members:

.. method:: FloatingWindow.assignToDocument(document)

Add this window to the list of windows associated with a document.

**document** should be a *NSDocument* instance.


.. method:: FloatingWindow.setTitle(title)

Set the title in the window's title bar.

**title** should be a string.


.. method:: FloatingWindow.setPosSize(posSize, animate=True)

Set the position and size of the FloatingWindow.

**posSize** A tuple of form *(left, top, width, height)*.


.. method:: FloatingWindow.move(x, y, animate=True)

Move the window by *x* units and *y* units.


.. method:: FloatingWindow.resize(width, height, animate=True)

Change the size of the window to *width* and *height*.


.. method:: FloatingWindow.setDefaultButton(button)

Set the default button in the FloatingWindow.

**button** will be bound to the Return and Enter keys.


.. method:: FloatingWindow.bind(event, callback)

Bind a callback to an event.

**event** A string representing the desired event. The options are:

+-------------------+----------------------------------------------------------------------+
| *"should close"* | Called when the user attempts to close the window. This must return |
| | a bool indicating if the window should be closed or not. |
+-------------------+----------------------------------------------------------------------+
| *"close"* | Called immediately before the window closes. |
+-------------------+----------------------------------------------------------------------+
| *"move"* | Called immediately after the window is moved. |
+-------------------+----------------------------------------------------------------------+
| *"resize"* | Called immediately after the window is resized. |
+-------------------+----------------------------------------------------------------------+
| *"became main"* | Called immediately after the window has become the main window. |
+-------------------+----------------------------------------------------------------------+
| *"resigned main"* | Called immediately after the window has lost its main window status. |
+-------------------+----------------------------------------------------------------------+
| *"became key"* | Called immediately after the window has become the key window. |
+-------------------+----------------------------------------------------------------------+
| *"resigned key"* | Called immediately after the window has lost its key window status. |
+-------------------+----------------------------------------------------------------------+

For more information about main and key windows, refer to the Cocoa `documentation`_ on the subject.

.. _documentation: http://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/WinPanel/Concepts/ChangingMainKeyFloatingWindow.html

**callback** The callback that will be called when the event occurs. It should accept a *sender* argument which will
be the Window that called the callback.::

from vanilla import Window

class WindowBindDemo(object):

def __init__(self):
self.w = Window((200, 200))
self.w.bind("move", self.windowMoved)
self.w.open()

def windowMoved(self, sender):
print("window moved!", sender)

WindowBindDemo()


.. method:: FloatingWindow.unbind(event, callback)

Unbind a callback from an event.

**event** A string representing the desired event.
Refer to *bind* for the options.

**callback** The callback that has been bound to the event.


.. method:: FloatingWindow.addToolbar(toolbarIdentifier, toolbarItems, addStandardItems=True)

Add a toolbar to the FloatingWindow.

**toolbarIdentifier** A string representing a unique name for the toolbar.

**toolbarItems** An ordered list of dictionaries containing the following items:

+-------------------------------+---------------------------------------------------------------------------+
| *itemIdentifier* | A unique string identifier for the item. This is only used internally. |
+-------------------------------+---------------------------------------------------------------------------+
| *label* (optional) | The text label for the item. Defaults to *None*. |
+-------------------------------+---------------------------------------------------------------------------+
| *paletteLabel* (optional) | The text label shown in the customization palette. Defaults to *label*. |
+-------------------------------+---------------------------------------------------------------------------+
| *toolTip* (optional) | The tool tip for the item. Defaults to *label*. |
+-------------------------------+---------------------------------------------------------------------------+
| *imagePath* (optional) | A file path to an image. Defaults to *None*. |
+-------------------------------+---------------------------------------------------------------------------+
| *imageNamed* (optional) | The name of an image already loaded as a `NSImage`_ by the application. |
| | Defaults to *None*. |
+-------------------------------+---------------------------------------------------------------------------+
| *imageObject* (optional) | A `NSImage`_ object. Defaults to *None*. |
+-------------------------------+---------------------------------------------------------------------------+
| *imageTemplate* (optional) | A boolean representing if the image should converted to a template image. |
+-------------------------------+---------------------------------------------------------------------------+
| *selectable* (optional) | A boolean representing if the item is selectable or not. The default |
| | value is *False*. For more information on selectable toolbar items, refer |
| | to Apple's documentation. |
+-------------------------------+---------------------------------------------------------------------------+
| *view* (optional) | A *NSView* object to be used instead of an image. Defaults to *None*. |
+-------------------------------+---------------------------------------------------------------------------+
| *visibleByDefault* (optional) | If the item should be visible by default pass *True* to this argument. |
| | If the item should be added to the toolbar only through the customization |
| | palette, use a value of *False*. Defaults to *True*. |
+-------------------------------+---------------------------------------------------------------------------+

.. _NSImage: http://developer.apple.com/documentation/appkit/nsimage?language=objc

**addStandardItems** A boolean, specifying whether the standard Cocoa toolbar items
should be added. Defaults to *True*. If you set it to *False*, you must specify any
standard items manually in *toolbarItems*, by using the constants from the AppKit module:

+-------------------------------------------+------------------------------------------------------+
| *NSToolbarSeparatorItemIdentifier* | The Separator item. |
+-------------------------------------------+------------------------------------------------------+
| *NSToolbarSpaceItemIdentifier* | The Space item. |
+-------------------------------------------+------------------------------------------------------+
| *NSToolbarFlexibleSpaceItemIdentifier* | The Flexible Space item. |
+-------------------------------------------+------------------------------------------------------+
| *NSToolbarShowColorsItemIdentifier* | The Colors item. Shows the color panel. |
+-------------------------------------------+------------------------------------------------------+
| *NSToolbarShowFontsItemIdentifier* | The Fonts item. Shows the font panel. |
+-------------------------------------------+------------------------------------------------------+
| *NSToolbarCustomizeToolbarItemIdentifier* | The Customize item. Shows the customization palette. |
+-------------------------------------------+------------------------------------------------------+
| *NSToolbarPrintItemIdentifier* | The Print item. Refer to Apple's `NSToolbarItem`_ |
| | documentation for more information. |
+-------------------------------------------+------------------------------------------------------+

.. _NSToolbarItem: https://developer.apple.com/documentation/appkit/nstoolbaritem?language=objc

**displayMode** A string representing the desired display mode for the toolbar.

+-------------+
| "default" |
+-------------+
| "iconLabel" |
+-------------+
| "icon" |
+-------------+
| "label" |
+-------------+

**sizeStyle** A string representing the desired size for the toolbar

+-----------+
| "default" |
+-----------+
| "regular" |
+-----------+
| "small" |
+-----------+

Returns a dictionary containing the created toolbar items, mapped by itemIdentifier.


.. method:: FloatingWindow.removeToolbarItem(itemIdentifier)

Remove a toolbar item by his identifier.

**itemIdentifier** A unique string identifier for the removed item.


.. autoclass:: HUDFloatingWindow
:members:
27 changes: 13 additions & 14 deletions Documentation/source/objects/List.rst
View file
Original file line number Diff line number Diff line change
@@ -1,22 +1,21 @@
.. highlight:: python

=====
List2
=====
====
List
====

.. module:: vanilla2
.. module:: vanilla
.. autoclass:: List
:inherited-members:
:members:

================
List2 Item Cells
================
===============
List Item Cells
===============

.. autofunction:: EditTextList2Cell
.. autofunction:: CheckBoxList2Cell
.. autofunction:: SliderList2Cell
.. autofunction:: PopUpButtonList2Cell
.. autofunction:: ImageList2Cell
.. autofunction:: SegmentedButtonList2Cell
.. autofunction:: ColorWellList2Cell
.. autofunction:: CheckBoxListCell
.. autofunction:: SliderListCell
.. autofunction:: PopUpButtonListCell
.. autofunction:: ImageListCell
.. autofunction:: SegmentedButtonListCell
.. autofunction:: LevelIndicatorListCell
27 changes: 14 additions & 13 deletions Documentation/source/objects/List2.rst
View file
Original file line number Diff line number Diff line change
@@ -1,21 +1,22 @@
.. highlight:: python

====
List
====
=====
List2
=====

.. module:: vanilla
.. autoclass:: List
.. autoclass:: List2
:inherited-members:
:members:

===============
List Item Cells
===============
================
List2 Item Cells
================

.. autofunction:: CheckBoxListCell
.. autofunction:: SliderListCell
.. autofunction:: PopUpButtonListCell
.. autofunction:: ImageListCell
.. autofunction:: SegmentedButtonListCell
.. autofunction:: LevelIndicatorListCell
.. autofunction:: EditTextList2Cell
.. autofunction:: CheckBoxList2Cell
.. autofunction:: SliderList2Cell
.. autofunction:: PopUpButtonList2Cell
.. autofunction:: ImageList2Cell
.. autofunction:: SegmentedButtonList2Cell
.. autofunction:: ColorWellList2Cell
7 changes: 7 additions & 0 deletions Documentation/source/objects/ModalWindow.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,3 +8,10 @@ ModalWindow
.. autoclass:: ModalWindow
:inherited-members:
:members:


.. module:: vanilla
.. autoclass:: vanilla.vanillaWindows.VModalWindow
:inherited-members:
:members:

0 comments on commit 7ec2205

Please sign in to comment.