Merge pull request matplotlib#22170 from ericpre/add_docstring_example_polygon_selector

Add example to polygon selector docstring showing how to set vertices programmatically

Author: QuLogic

examples/widgets/polygon_selector_demo.py

@@ -1,7 +1,7 @@
 """
-================
-Polygon Selector
-================
+=======================================================
+Select indices from a collection using polygon selector
+=======================================================
 
 Shows how one can select indices of a polygon interactively.
 """

examples/widgets/polygon_selector_simple.py

@@ -0,0 +1,46 @@
+"""
+================
+Polygon Selector
+================
+
+Shows how to create a polygon programmatically or interactively
+"""
+
+import matplotlib.pyplot as plt
+from matplotlib.widgets import PolygonSelector
+
+###############################################################################
+#
+# To create the polygon programmatically
+fig, ax = plt.subplots()
+fig.show()
+
+selector = PolygonSelector(ax, lambda *args: None)
+
+# Add three vertices
+selector.verts = [(0.1, 0.4), (0.5, 0.9), (0.3, 0.2)]
+
+
+###############################################################################
+#
+# To create the polygon interactively
+
+fig2, ax2 = plt.subplots()
+fig2.show()
+
+selector2 = PolygonSelector(ax2, lambda *args: None)
+
+print("Click on the figure to create a polygon.")
+print("Press the 'esc' key to start a new polygon.")
+print("Try holding the 'shift' key to move all of the vertices.")
+print("Try holding the 'ctrl' key to move a single vertex.")
+
+
+#############################################################################
+#
+# .. admonition:: References
+#
+#    The use of the following functions, methods, classes and modules is shown
+#    in this example:
+#
+#    - `matplotlib.widgets.PolygonSelector`

lib/matplotlib/widgets.py

@@ -3611,6 +3611,7 @@ class PolygonSelector(_SelectorWidget):
 
     Examples
     --------
+    :doc:`/gallery/widgets/polygon_selector_simple`
     :doc:`/gallery/widgets/polygon_selector_demo`
 
     Notes