doc: added ref and anchor example

kivy/uix/label.py

@@ -96,6 +96,53 @@ For prettier rendering, you could add a color for the reference. Replace the
 
     'Hello [ref=world][color=0000ff]World[/color][/ref]'
 
+Usage example
+-------------
+
+The following example marks the anchors and references contained in a label::
+
+    from kivy.app import App
+    from kivy.uix.label import Label
+    from kivy.clock import Clock
+    from kivy.graphics import Color, Rectangle
+
+
+    class TestApp(App):
+
+        @staticmethod
+        def get_x(label, ref_x):
+            """ Return the x value of the ref/anchor relative to the canvas """
+            return label.center_x - label.texture_size[0] * 0.5 + ref_x
+
+        @staticmethod
+        def get_y(label, ref_y):
+            """ Return the y value of the ref/anchor relative to the canvas """
+            # Note the inversion of direction, as y values start at the top of
+            # the texture and increase downwards
+            return label.center_y + label.texture_size[1] * 0.5 - ref_y
+
+        def show_marks(self, label):
+
+            # Indicate the position of the anchors with a red top marker
+            for name, anc in label.anchors.items():
+                with label.canvas:
+                    Color(1, 0, 0)
+                    Rectangle(pos=(self.get_x(label, anc[0]),
+                                   self.get_y(label, anc[1])),
+                              size=(3, 3))
+
+            # Draw a green surround around the refs. Note the sizes y inversion
+            for name, boxes in label.refs.items():
+                for box in boxes:
+                    with label.canvas:
+                        Color(0, 1, 0, 0.25)
+                        Rectangle(pos=(self.get_x(label, box[0]),
+                                       self.get_y(label, box[1])),
+                                  size=(box[2] - box[0],
+                                        box[1] - box[3]))
+
+    TestApp().run()
+
 '''
 
 __all__ = ('Label', )