From f475eef643d97a4005f7a2050618a578017fc299 Mon Sep 17 00:00:00 2001 From: Jeff Pittman Date: Thu, 5 Jul 2012 06:02:33 -0500 Subject: [PATCH] Added several short notes about keeping the design of the Widget class simple and lean, explaining to the new developer that derived classes and custom widgets implement such properties as background_color. --- doc/sources/guide/firstwidget.rst | 11 +++++++++++ kivy/uix/widget.py | 8 ++++++++ 2 files changed, 19 insertions(+) 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. '''