Add examples

Documentation/source/conf.py

@@ -14,7 +14,8 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys, os
+import sys
+import os
 
 # If your extensions are in another directory, add it here. If the directory
 # is relative to the documentation root, use os.path.abspath to make it
@@ -173,8 +174,7 @@
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, document class [howto/manual]).
 latex_documents = [
-  ('index', 'Vanilla.tex', ur'Vanilla Documentation',
-   ur'Tal Leming', 'manual'),
+  ('index', 'Vanilla.tex', 'Vanilla Documentation', 'Tal Leming', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of

Lib/vanilla/vanillaButton.py

@@ -224,17 +224,22 @@ class ImageButton(SquareButton):
     """
     A button with an image.
 
+    .. image:: /_images/ImageButton.png
+
     ::
 
+        import AppKit
         from vanilla import Window, ImageButton
 
         class ImageButtonDemo:
 
              def __init__(self):
-                 path = "/path/to/an/image"
                  self.w = Window((50, 50))
-                 self.w.button = ImageButton((10, 10, 30, 30), imagePath=path,
-                                    callback=self.buttonCallback)
+                 self.w.button = ImageButton(
+                     (10, 10, 30, 30),
+                     imageNamed=AppKit.NSImageNameRefreshTemplate,
+                    callback=self.buttonCallback
+                    )
                  self.w.open()
 
              def buttonCallback(self, sender):

Lib/vanilla/vanillaDatePicker.py

@@ -25,6 +25,37 @@
 class DatePicker(VanillaBaseControl):
 
     """
+
+    A control for setting date objects
+
+    .. image:: /_images/DatePicker.png
+
+    ::
+
+        from vanilla import DatePicker, Window
+
+        class DatePickerExample:
+            def __init__(self):
+                self.w = Window((300, 180))
+                self.w.datePicker = DatePicker(
+                    (10, 10, -10, -10),
+                    showStepper=True,
+                    mode="graphical",
+                    timeDisplay="hourMinuteSecond",
+                    dateDisplay="yearMonthDay",
+                    callback=self.datePickerCallback,
+                    sizeStyle="regular",
+                )
+
+                self.w.open()
+
+            def datePickerCallback(self, sender):
+                print(sender.get())
+
+
+        DatePickerExample()
+
+
     **posSize** Tuple of form *(left, top, width, height)* or *"auto"*
     representing the position and size of the date picker control.
 

Lib/vanilla/vanillaGradientButton.py

@@ -7,6 +7,34 @@ class GradientButton(ImageButton):
     """
     An image button that initiates an immediate action related to a view.
 
+    .. image:: /_images/GradientButton.png
+
+    ::
+
+        import AppKit
+        from vanilla import GradientButton, Window
+
+
+        class GradientButtonExample:
+            def __init__(self):
+                self.w = Window((80, 80))
+                self.w.gradientButton = GradientButton(
+                    (10, 10, 40, 40),
+                    imageNamed=AppKit.NSImageNameRefreshTemplate,
+                    imagePosition="top",
+                    callback=self.gradientButtonCallback,
+                    sizeStyle="regular",
+                )
+
+                self.w.open()
+
+            def gradientButtonCallback(self, sender):
+                print("gradient button hit!")
+
+
+        GradientButtonExample()
+
+
     **posSize** Tuple of form *(left, top, width, height)* or *"auto"* representing
     the position and size of the button.
 

Lib/vanilla/vanillaGridView.py

@@ -24,6 +24,47 @@ class GridView(VanillaBaseObject):
     """
     A view that allows the placement of other views within a grid.
 
+    .. image:: /_images/GridView.png
+
+    ::
+
+        from vanilla import Button, GridView, Window
+
+        class GridViewExample:
+            def __init__(self):
+                self.w = Window((120, 90))
+
+                self.button1 = Button("auto", "one")
+                self.button2 = Button("auto", "two")
+                self.button3 = Button("auto", "three")
+                self.button4 = Button("auto", "four")
+
+                self.w.gridView = GridView(
+                    (0, 0, 0, 0),
+                    contents=[
+                        dict(
+                            cells=[
+                                dict(view=self.button1),
+                                dict(view=self.button2),
+                            ]
+                        ),
+                        dict(
+                            cells=[
+                                dict(view=self.button3),
+                                dict(view=self.button4),
+                            ]
+                        ),
+                    ],
+                    columnPadding=(4, 4),
+                    rowPadding=(4, 4),
+                )
+
+                self.w.open()
+
+
+        GridViewExample()
+
+
     **posSize** Tuple of form *(left, top, width, height)* or *"auto"* representing
     the position and size of the grid view.
 

Lib/vanilla/vanillaImageView.py

@@ -25,6 +25,30 @@ class ImageView(VanillaBaseObject):
     """
     A view that displays an image.
 
+    .. image:: /_images/ImageView.png
+
+    ::
+
+        import AppKit
+        from vanilla import ImageView, Window
+
+        class ImageViewExample:
+            def __init__(self):
+                self.w = Window((80, 80))
+                self.w.imageView = ImageView(
+                    (10, 10, 40, 40),
+                    horizontalAlignment="center",
+                    verticalAlignment="center",
+                    scale="proportional"
+                )
+                image = AppKit.NSImage.imageWithSystemSymbolName_accessibilityDescription_("pencil.and.outline", "")
+                self.w.imageView.setImage(imageObject=image)
+                self.w.open()
+
+
+        ImageViewExample()
+
+
     **posSize** Tuple of form *(left, top, width, height)* or *"auto"*
     representing the position and size of the view.
 

Lib/vanilla/vanillaStackView.py

@@ -21,9 +21,10 @@
     gravityAreas=AppKit.NSStackViewDistributionGravityAreas
 )
 
+_doc = """A view that allows the creation of a stack of views.
 
-_doc = """
-A view that allows the creation of a stack of views.
+{image}
+{example}
 
 **posSize** Tuple of form *(left, top, width, height)* or *"auto"* representing
 the position and size of the stack view.
@@ -245,7 +246,43 @@ def removeView(self, view):
 
 class HorizontalStackView(_StackView):
 
-    __doc__ = _doc
+    _imageDocStr = """
+    .. image:: /_images/HorizontalStackView.png
+    """
+
+    _exampleDocStr = """
+    ::
+
+        from vanilla import Button, HorizontalStackView, Window
+
+        class HorizontalStackViewExample:
+            def __init__(self):
+                self.w = Window((300, 40))
+
+                self.button1 = Button("auto", "One")
+                self.button2 = Button("auto", "Two")
+                self.button3 = Button("auto", "Three")
+                self.button4 = Button("auto", "Four")
+
+                self.w.horizontalStack = HorizontalStackView(
+                    (0, 0, 0, 0),
+                    views=[
+                        dict(view=self.button1),
+                        dict(view=self.button2),
+                        dict(view=self.button3),
+                        dict(view=self.button4)
+                    ],
+                    spacing=4,
+                    edgeInsets=(4, 4, 4, 4),
+                )
+
+                self.w.open()
+
+
+        HorizontalStackViewExample()
+    """
+
+    __doc__ = _doc.format(image=_imageDocStr, example=_exampleDocStr)
 
     _orientation = NSUserInterfaceLayoutOrientationHorizontal
     _gravities = dict(
@@ -262,7 +299,44 @@ class HorizontalStackView(_StackView):
 
 class VerticalStackView(_StackView):
 
-    __doc__ = _doc
+    _imageDocStr = """
+    .. image:: /_images/VerticalStackView.png
+    """
+
+    _exampleDocStr = """
+    ::
+
+        from vanilla import Button, VerticalStackView, Window
+
+
+        class VerticalStackViewExample:
+            def __init__(self):
+                self.w = Window((80, 300))
+
+                self.button1 = Button("auto", "One")
+                self.button2 = Button("auto", "Two")
+                self.button3 = Button("auto", "Three")
+                self.button4 = Button("auto", "Four")
+
+                self.w.horizontalStack = VerticalStackView(
+                    (0, 0, 0, 0),
+                    views=[
+                        dict(view=self.button1),
+                        dict(view=self.button2),
+                        dict(view=self.button3),
+                        dict(view=self.button4)
+                    ],
+                    spacing=4,
+                    edgeInsets=(4, 4, 4, 4),
+                )
+
+                self.w.open()
+
+
+        VerticalStackViewExample()
+    """
+
+    __doc__ = _doc.format(image=_imageDocStr, example=_exampleDocStr)
 
     _orientation = NSUserInterfaceLayoutOrientationVertical
     _gravities = dict(