Imitation is the sincerest form of flattery, and we will imitate the clock design from Android 4.1 Jelly Bean. The distinctive feature of this design is the font weight contrast. Until it was changed in version 4.4 KitKat, the default clock used to look like this:

Clock in Jelly Bean flavor of Android, as seen on the lock screen.

The font used is Roboto, Google's Android font that superseded the Droid font family in Android 4.0 Ice Cream Sandwich.

Roboto is free for commercial use and available under the permissive Apache License. It can be downloaded from Google Fonts or from the excellent Font Squirrel library at http://www.fontsquirrel.com/fonts/roboto.

When it comes to the typography, Kivy defaults to Droid Sans—Google's earlier font. It's easy to replace Droid with a custom font, as Kivy allows us to specify the font_name property for textual widgets (in this case, Label).

In the simplest case when we have just one font variant, it is possible to assign a .ttf filename directly in the definition of a widget:

Label:
    font_name: 'Lobster.ttf'

For the aforementioned design, however, we want different font weights, so this approach won't cut it. The reason being, every variation of a font (for example, bold or italic) commonly lives in a separate file, and we can only assign one filename to the font_name property.

Our use case, involving more than one .ttf file, is better covered by a LabelBase.register static method. It accepts the following arguments (all optional), exemplified by the Roboto font family:

# In Python code
LabelBase.register(name="Roboto",
    fn_regular="Roboto-Regular.ttf",
    fn_bold="Roboto-Bold.ttf",
    fn_italic="Roboto-Italic.ttf",
    fn_bolditalic="Roboto-BoldItalic.ttf")

After this invocation, it becomes possible to set the font_name property of a widget to the name of the previously registered font family, Roboto in this case.

This approach has two limitations to be aware of:

The six font weights of Roboto font

The second point forces us to choose which font styles we will use in our application as we can't just throw in all 12, which is a bad idea anyway as it would lead to a hefty increase in file size, up to 1.7 megabytes in the case of Roboto family.

For this particular app, we only need two styles: a lighter one (Roboto-Thin.ttf) and a heavier one (Roboto-Medium.ttf), which we assign to fn_regular and fn_bold respectively:

from kivy.core.text import LabelBase

LabelBase.register(name='Roboto',
                   fn_regular='Roboto-Thin.ttf',
                   fn_bold='Roboto-Medium.ttf')

This code should be placed right after the __name__ == '__main__' line in main.py, as it needs to run before the interface is created from the Kivy language definition. By the time the app class is instantiated, it might already be too late to perform basic initialization like this. This is why we have to do it in advance.

Now that we have a custom font in place, all that's left is to assign it to our Label widget. This can be done with the help of the following code:

# In clock.kv
Label:
    text: '00:00:00'
    font_name: 'Roboto'
    font_size: 60

The most popular and universally used markup language out there is undoubtedly HTML. Kivy, on the other hand, implements a variant of BBCode, a markup language once used to format posts on many message boards. Visible distinction from HTML is that BBCode uses square brackets as tag delimiters.

The following tags are available in Kivy:

Let's return to our project. To achieve the desired formatting (hours in bold and the rest of the text in fn_regular thin font), we can use the following code:

Label:
    text: '[b]00[/b]:00:00'
    markup: True

Kivy's BBCode flavor works only if we also set the markup property of a widget to True, as shown in the preceding code. Otherwise, you will literally see the string [b]…[/b] displayed on the screen, and that's clearly not desired.

Note that if we wanted to make the whole text bold, there is no need to enclose everything in [b]…[/b] tags; we could just set the bold property of the widget to True. The same applies to italic, color, font name, and size—pretty much everything can be configured globally to affect the whole widget without touching markup.

In this section, we will adjust the window background color. Window background (the "clear color" of OpenGL renderer) is a property of a global Window object. In order to change it, we add this code right after the __name__ == '__main__' line in main.py:

from kivy.core.window import Window
from kivy.utils import get_color_from_hex

Window.clearcolor = get_color_from_hex('#101216')

The get_color_from_hex function is not strictly required, but it's nice as it allows us to use CSS-style (#RRGGBB) colors instead of (R, G, B) tuples throughout our code. And using CSS colors is preferable for at least the following two reasons:

We will talk more about design-related features of Kivy later on. Meanwhile, let's make our application actually show the time.

To access the Label widget that holds time, we will give it a unique identifier (id). Later, we can easily look up widgets based on their id property—again, a concept which is very similar to web development.

Modify clock.kv by adding the following:

Label:
    id: time

That's it! Now we can access this Label widget from our code directly using the root.ids.time notation (root in our case is BoxLayout).

Updates to the ClockApp class include the addition of a method to display time, update_time, which looks like this:

def update_time(self, nap):
    self.root.ids.time.text = strftime('[b]%H[/b]:%M:%S')

Now let's schedule the update function to run once per second after the program starts:

def on_start(self):
    Clock.schedule_interval(self.update_time, 1)

If we run the application right now, we'll see that the time displayed is being updated every second. To paraphrase Neil Armstrong, that is one small step for mankind, but a sizable leap for a Kivy beginner.

It's worth noting how the argument to strftime combines Kivy's BBCode-like tags described earlier with the function-specific C-style format directives. For the unfamiliar, here's a quick and incomplete reference on strftime formatting essentials:

Instead of hardcoding an ID for each widget that we need to access from Python code, we can also create a property and assign it in a Kivy language file. The motivation for doing so is mostly the DRY principle and cleaner naming, at a cost of a few more lines of code.

Such a property can be defined as follows:

# In main.py
from kivy.properties import ObjectProperty
from kivy.uix.boxlayout import BoxLayout

class ClockLayout(BoxLayout):
    time_prop = ObjectProperty(None)

In this code fragment, we make a new root widget class for our application based on BoxLayout. It has a custom property, time_prop, which is going to reference Label we need to address from Python code.

Additionally, in the Kivy language file, clock.kv, we have to bind this property to a corresponding id. Custom properties look and behave no different from the default ones and use exactly the same syntax:

ClockLayout:
    time_prop: time

    Label:
        id: time

This code makes the Label widget accessible from the Python code without knowing the widget's ID, using the newly defined property, root.time_prop.text = "demo".

The described approach is more portable than the previously shown one and it eliminates the need to keep widget identifiers from the Kivy language file in sync with the Python code, for example, when refactoring. Otherwise, the choice between relying on properties and accessing widgets from Python via root.ids is a matter of coding style.

Later in this book, we'll explore more advanced usage of Kivy properties, facilitating nearly effortless data binding.

Stacking three widgets into BoxLayout normally makes every widget a third of the available size. Since we don't want buttons to be this big compared to clock displays, we can add a height property to the horizontal (inner) BoxLayout and set its vertical size_hint property to None.

The size_hint property is a tuple of two values, affecting the widget's width and height. We will discuss the impact that size_hint has on different layouts in the next few chapters; right now, let's just say that if we want to use absolute numbers for width or height, we have to set size_hint to None accordingly; otherwise, assigning size won't work as the widget will continue to compute its own size instead of using the values that we'll provide.

After updating the clock.kv file to account for stopwatch display and controls, it should look similar to the following (note the hierarchy of the layouts):

BoxLayout:
    orientation: 'vertical'

    Label:
        id: time
        text: '[b]00[/b]:00:00'
        font_name: 'Roboto'
        font_size: 60
        markup: True

    BoxLayout:
        height: 90
        orientation: 'horizontal'
        padding: 20
        spacing: 20
        size_hint: (1, None)

        Button:
            text: 'Start'
            font_name: 'Roboto'
            font_size: 25
            bold: True

        Button:
            text: 'Reset'
            font_name: 'Roboto'
            font_size: 25
            bold: True

    Label:
        id: stopwatch
        text: '00:00.[size=40]00[/size]'
        font_name: 'Roboto'
        font_size: 60
        markup: True

If we run the code now, we'll notice that buttons don't fill all the available space inside BoxLayout. This effect is achieved using the padding and spacing properties of the layout. Padding acts very similar to CSS, pushing children (in our case, buttons) away from the edges of the layout, while spacing controls the distance between adjacent children. Both properties default to zero, aiming at maximum widget density.

This layout works but has one serious problem: the code is very repetitive. Every change we may want to make has to be done in a number of places throughout the file, and it's very easy to miss one of them and thus introduce an inconsistent change.

<p><font face="Helvetica">Part 1</font></p>
<p><font face="Helvetica">Part 2</font></p>

p {font-family: Helvetica}

<p style="font-family: Times">Part 3</p>

In Kivy, there is no need to use a different file for our aggregate styles or class rules, like it's usually done in web development. We just add to the clock.kv file a definition like the following, outside of BoxLayout:

<Label>:
    font_name: 'Roboto'
    font_size: 60
    markup: True

This is a class rule; it acts similar to a CSS selector described in the previous information box. Every Label derives all the properties from the <Label> class rule. (Note the angle brackets.)

Now we can remove the font_name, font_size, and markup properties from each individual Label. As a general rule, always strive to move every repeated definition into a class. This is a well-known best practice called don't repeat yourself (DRY). Changes like the one shown in the previous code snippet may seem trivial in a toy project like this but will make our code much cleaner and more maintainable in a long run.

If we want to override a property of one of the widgets, just add it as usual. Immediate properties take precedence over those inherited from the class definition.

<RobotoButton@Button>:
    font_name: 'Roboto'
    font_size: 25
    bold: True

RobotoButton:
    text: 'Start'

The motivation for a good scaling algorithm is simple: it's almost impossible to provide pixel-perfect graphics for every button, especially for the problematic ones that contain (varying amounts of) text. Scaling images uniformly is simple to implement but yields results that are mediocre at best, partly because of the aspect ratio distortion.

Non-uniform 9-patch scaling, on the other hand, produces uncompromising quality. The idea is to split the image into static and scalable parts. The following image is a hypothetical scalable button. The middle part (shown in yellow) is the working area, and everything else is a border:

The red zones can be stretched in one dimension, while the blue zones (corners) are always left intact. This is evident from the following screenshot:

Corners, shown in blue, are fully static and may contain virtually anything. Borders, shown in red, are scalable in one dimension (top and bottom sides can be stretched horizontally, and left and right sides can be stretched vertically). The only part of the image that will be uniformly resized is the inner rectangle, the working area, shown in yellow; it is therefore common to paint it with a flat color. It will also contain text that's assigned to the button, if any.

For this tutorial, we will use a simple flat button with a 1-pixel border. We can reuse this texture for all buttons or choose a different one, for example, for the Reset button. A button texture for the normal state with flat color and 1-pixel border is shown as follows:

The corresponding texture for the pressed state—an inversion of the preceding image—is shown as follows:

Now, to apply the 9-patch magic, we need to tell Kivy the size of borders that have limited scalability, as discussed previously (the image will be scaled uniformly by default). Let's revisit the clock.kv file and add the following properties:

<RobotoButton@Button>:
    background_normal: 'button_normal.png'
    background_down: 'button_down.png'
    border: (2, 2, 2, 2)

The border property values are ordered just like in CSS: top, right, bottom, and left (that is, clockwise starting from the top). Unlike CSS, we can't supply just one value for all sides; at least in the current Kivy version (1.8), the notation border: 2 results in error.

Also note that while the visible border is just one pixel wide, we're assigning the border property of customized buttons to 2. This is due to the texture-stretching behavior of the renderer: if pixel colors from both sides of the "cut line" don't match, the result will be a gradient, and we want solid color.

In the class rules overview, we mentioned that the property declared on an instance of a widget takes precedence over the class rule's property with the same name. This can be used to selectively override background_*, border or any other attribute, for example, assigning another texture while reusing the border width definition:

RobotoButton:
    text: 'Reset'
    background_normal: 'red_button_normal.png'
    background_down: 'red_button_down.png'

Now our buttons are stylized, but they still don't do anything. The next step towards our goal is making the stopwatch work.

For the main time display, formatting is easy because the standard library function strftime provides us with a number of readily available primitives to convert a datetime object into a readable string representation, according to the provided format string.

This function has a number of limitations:

The former datetime limitation can be easily circumvented: we could cast our sw_seconds variable to datetime. But the latter deficiency makes this unnecessary, as we want to end our notation with fractions of a second (exact to 0.01 sec), so strftime formatting just won't cut it. Hence, we implement our own time formatting.

minutes, seconds = divmod(self.sw_seconds, 60)

minutes = self.sw_seconds / 60
seconds = self.sw_seconds % 60

int(seconds * 100 % 100)

def update_time(self, nap):
    self.sw_seconds += nap
    minutes, seconds = divmod(self.sw_seconds, 60)
    self.root.ids.stopwatch.text = (
        '%02d:%02d.[size=40]%02d[/size]' %
        (int(minutes), int(seconds),
         int(seconds * 100 % 100)))

Clock.schedule_interval(self.update_time, 0)