Merge pull request #553 from geojeff/simple_design_of_widget

Added several short notes about keeping the design of the Widget class s...

doc/sources/guide/firstwidget.rst

@@ -314,6 +314,17 @@ Here's what happens:
       the button is pressed and then released) to the callback we just
       defined.
 
+.. note::
+   The Kivy Widget class, by design, is kept simple. There are no general
+   properties such as background color and border color. Instead, the examples
+   and documentation illustrate how to easily handle such simple things
+   yourself, as we have done here, setting the color for the canvas, and 
+   drawing the shape. From a simple start, you can move to more elaborate
+   customization. Higher-level built-in widgets, deriving from Widget, such
+   as Button, do have convenience properties such as background_color, but
+   these vary by widget. Use the API docs to see what is offered by a widget,
+   and subclass if you need to add more functionality.
+
 Congratulations! You've written your first Kivy widget. Obviously this was
 just a quick introduction. There is much more to discover. We suggest
 taking a short break to let what you just learned sink in. Maybe draw some

kivy/uix/widget.py

@@ -536,5 +536,13 @@ class Widget(EventDispatcher):
 
     The canvas is a graphics object that contains all the drawing instructions
     for the graphical representation of the widget.
+
+    There are no general properties for the Widget class, such as background
+    color, to keep the design simple and lean. Some derived classes, such as
+    Button, do add such convenience properties, but generally the developer is
+    responsible for implementing the graphics representation for a custom
+    widget from the ground up. See the derived widget classes for patterns to
+    follow and extend.
+
     See :class:`~kivy.graphics.Canvas` for more information about the usage.
     '''