diff --git a/doc/sources/guide/firstwidget.rst b/doc/sources/guide/firstwidget.rst index 4e59c05a7..cadf87d6a 100644 --- a/doc/sources/guide/firstwidget.rst +++ b/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 diff --git a/kivy/uix/widget.py b/kivy/uix/widget.py index 8aa3d43e8..8c39a94e0 100644 --- a/kivy/uix/widget.py +++ b/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. '''