mirror of
https://github.com/google/pebble.git
synced 2025-03-16 01:01:20 +00:00
208 lines
6.6 KiB
Markdown
208 lines
6.6 KiB
Markdown
|
---
|
||
|
# Copyright 2025 Google LLC
|
||
|
#
|
||
|
# Licensed under the Apache License, Version 2.0 (the "License");
|
||
|
# you may not use this file except in compliance with the License.
|
||
|
# You may obtain a copy of the License at
|
||
|
#
|
||
|
# http://www.apache.org/licenses/LICENSE-2.0
|
||
|
#
|
||
|
# Unless required by applicable law or agreed to in writing, software
|
||
|
# distributed under the License is distributed on an "AS IS" BASIS,
|
||
|
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||
|
# See the License for the specific language governing permissions and
|
||
|
# limitations under the License.
|
||
|
|
||
|
title: Fonts
|
||
|
description: |
|
||
|
How to use built-in system fonts, or add your own font resources to a project.
|
||
|
guide_group: app-resources
|
||
|
order: 3
|
||
|
platform_choice: true
|
||
|
---
|
||
|
|
||
|
|
||
|
## Using Fonts
|
||
|
|
||
|
Text drawn in a Pebble app can be drawn using a variety of built-in fonts or a
|
||
|
custom font specified as a project resource.
|
||
|
|
||
|
Custom font resources must be in the `.ttf` (TrueType font) format. When the app
|
||
|
is built, the font file is processed by the SDK according to the `compatibility`
|
||
|
(See [*Font Compatibility*](#font-compatibility)) and `characterRegex`
|
||
|
fields (see [*Choosing Font Characters*](#choosing-font-characters)), the latter
|
||
|
of which is a standard Python regex describing the character set of the
|
||
|
resulting font.
|
||
|
|
||
|
|
||
|
## System Fonts
|
||
|
|
||
|
All of the built-in system fonts are available to use with
|
||
|
``fonts_get_system_font()``. See {% guide_link app-resources/system-fonts %} for
|
||
|
a complete list with sample images. Examples of using a built-in system font in
|
||
|
code are [shown below](#using-a-system-font).
|
||
|
|
||
|
|
||
|
### Limitations
|
||
|
|
||
|
There are limitations to the Bitham, Roboto, Droid and LECO fonts, owing to the
|
||
|
memory space available on Pebble, which only contain a subset of the default
|
||
|
character set.
|
||
|
|
||
|
* Roboto 49 Bold Subset - contains digits and a colon.
|
||
|
* Bitham 34/42 Medium Numbers - contain digits and a colon.
|
||
|
* Bitham 18/34 Light Subset - only contains a few characters and is not suitable
|
||
|
for displaying general text.
|
||
|
* LECO Number sets - suitable for number-only usage.
|
||
|
|
||
|
|
||
|
## Using a System Font
|
||
|
|
||
|
Using a system font is the easiest choice when displaying simple text. For more
|
||
|
advanced cases, a custom font may be advantageous. A system font can be obtained
|
||
|
at any time, and the developer is not responsible for destroying it when they
|
||
|
are done with it. Fonts can be used in two modes:
|
||
|
|
||
|
```c
|
||
|
// Use a system font in a TextLayer
|
||
|
text_layer_set_font(s_text_layer, fonts_get_system_font(FONT_KEY_GOTHIC_24));
|
||
|
```
|
||
|
|
||
|
```c
|
||
|
// Use a system font when drawing text manually
|
||
|
graphics_draw_text(ctx, text, fonts_get_system_font(FONT_KEY_GOTHIC_24), bounds,
|
||
|
GTextOverflowModeWordWrap, GTextAlignmentCenter, NULL);
|
||
|
```
|
||
|
|
||
|
|
||
|
## Adding a Custom Font
|
||
|
|
||
|
{% platform local %}
|
||
|
After placing the font file in the project's `resources` directory, the custom
|
||
|
font can be added to a project as `font` `type` item in the `media` array in
|
||
|
`package.json`. The `name` field's contents will be made available at compile
|
||
|
time with `RESOURCE_ID_` at the front, and must end with the desired font size.
|
||
|
For example:
|
||
|
|
||
|
```js
|
||
|
"resources": {
|
||
|
"media": [
|
||
|
{
|
||
|
"type": "font",
|
||
|
"name": "EXAMPLE_FONT_20",
|
||
|
"file": "example_font.ttf"
|
||
|
}
|
||
|
]
|
||
|
}
|
||
|
```
|
||
|
{% endplatform %}
|
||
|
|
||
|
{% platform cloudpebble %}
|
||
|
To add a custom font file to your project, click 'Add New' in the Resources
|
||
|
section of the sidebar. Set the 'Resource Type' to 'TrueType font', and upload
|
||
|
the file using the 'Choose file' button. Choose an 'Identifier', which will be
|
||
|
made available at compile time with `RESOURCE_ID_` at the front. This must end
|
||
|
with the desired font size ("EXAMPLE_FONT_20", for example).
|
||
|
|
||
|
Configure the other options as appropriate, then hit 'Save' to save the
|
||
|
resource.
|
||
|
{% endplatform %}
|
||
|
|
||
|
{% alert important %}
|
||
|
The maximum recommended font size is 48.
|
||
|
{% endalert %}
|
||
|
|
||
|
|
||
|
## Using a Custom Font
|
||
|
|
||
|
Unlike a system font, a custom font must be loaded and unloaded by the
|
||
|
developer. Once this has been done, the font can easily be used in a similar
|
||
|
manner.
|
||
|
|
||
|
When the app initializes, load the font from resources using the generated
|
||
|
`RESOURCE_ID`:
|
||
|
|
||
|
```c
|
||
|
// Declare a file-scope variable
|
||
|
static GFont s_font;
|
||
|
```
|
||
|
|
||
|
```c
|
||
|
// Load the custom font
|
||
|
s_font = fonts_load_custom_font(
|
||
|
resource_get_handle(RESOURCE_ID_EXAMPLE_FONT_20));
|
||
|
```
|
||
|
|
||
|
The font can now be used in two modes - with a ``TextLayer``, or when drawing
|
||
|
text manually in a ``LayerUpdateProc``:
|
||
|
|
||
|
```c
|
||
|
// Use a custom font in a TextLayer
|
||
|
text_layer_set_font(s_text_layer, s_font);
|
||
|
```
|
||
|
|
||
|
```c
|
||
|
// Use a custom font when drawing text manually
|
||
|
graphics_draw_text(ctx, text, s_font, bounds, GTextOverflowModeWordWrap,
|
||
|
GTextAlignmentCenter, NULL);
|
||
|
```
|
||
|
|
||
|
|
||
|
## Font Compatibility
|
||
|
|
||
|
The font rendering process was improved in SDK 2.8. However, in some cases this
|
||
|
may cause the appearance of custom fonts to change slightly. To revert to the
|
||
|
old rendering process, add `"compatibility": "2.7"` to your font's object in the
|
||
|
`media` array (shown above) in `package.json` or set the 'Compatibility'
|
||
|
property in the font's resource view in CloudPebble to '2.7 and earlier'.
|
||
|
|
||
|
|
||
|
## Choosing Font Characters
|
||
|
|
||
|
By default, the maximum number of supported characters is generated for a font
|
||
|
resource. In most cases this will be far too many, and can bloat the size of the
|
||
|
app. To optimize the size of your font resources you can use a standard regular
|
||
|
expression (or 'regex') string to limit the number of characters to only those
|
||
|
you require.
|
||
|
|
||
|
The table below outlines some example regular expressions to use for limiting
|
||
|
font character sets in common watchapp scenarios:
|
||
|
|
||
|
| Expression | Result |
|
||
|
|------------|--------|
|
||
|
| `[ -~]` | ASCII characters only. |
|
||
|
| `[0-9]` | Numbers only. |
|
||
|
| `[0-9 ]` | Numbers and spaces only. |
|
||
|
| `[a-zA-Z]` | Letters only. |
|
||
|
| `[a-zA-Z ]` | Letters and spaces only. |
|
||
|
| `[0-9:APM ]` | Time strings only (e.g.: "12:45 AM"). |
|
||
|
| `[0-9:A-Za-z ]` | Time and date strings (e.g.: "12:43 AM Wednesday 3rd March 2015". |
|
||
|
| `[0-9:A-Za-z° ]` | Time, date, and degree symbol for temperature gauges. |
|
||
|
| `[0-9°CF ]` | Numbers and degree symbol with 'C' and 'F' for temperature gauges. |
|
||
|
|
||
|
{% platform cloudpebble %}
|
||
|
Open the font's configuration screen under 'Resources', then enter the desired
|
||
|
regex in the 'Characters' field. Check the preview of the new set of characters,
|
||
|
then choose 'Save'.
|
||
|
{% endplatform %}
|
||
|
|
||
|
{% platform local %}
|
||
|
Add the `characterRegex` key to any font objects in `package.json`'s
|
||
|
`media` array.
|
||
|
|
||
|
```js
|
||
|
"media": [
|
||
|
{
|
||
|
"characterRegex": "[:0-9]",
|
||
|
"type": "font",
|
||
|
"name": "EXAMPLE_FONT",
|
||
|
"file": "example_font.ttf"
|
||
|
}
|
||
|
]
|
||
|
```
|
||
|
{% endplatform %}
|
||
|
|
||
|
Check out
|
||
|
[regular-expressions.info](http://www.regular-expressions.info/tutorial.html)
|
||
|
to learn more about how to use regular expressions.
|