Updated documentation for label.py to clarify usage for background

[kmatch98]

@FoamyGuy Here are my collection of thoughts on updates for the learn guide for adafruit_display_text\label.py. I just realized that maybe this belongs in a separate repository with the learn guides, but I couldn't identify the location. If you know an alternate location, let me know. If you have time to review this list, please add your suggestions and then we can discuss how you want to coordinate or divvy-up any work on the learn guide.

Documentation updates:

• Briefly describe differences in font typefaces: Fixed width vs variable width (proportional). We can handle both! Explain that BuiltinFont's terminalio.FONT can be used with a TileGrid resource-efficiently since it is a fixed-size font. (There is an open issue over in circuitpython about using TileGrid with BuiltinFont (issue Add TileGrid example that uses the built in font to display text circuitpython#2566.)

• Define the baseline position (halfway up the M glyph). There is already an image in the current learn guide. Indicate that is is mostly important if you are formatting multiple lines of text and they need to align. Define ascenders/descenders, since this useful for understanding the background options.

• anchor_point and anchor_position: reference the candy hearts example

Explain background size options:

• background_tight = False (default): Background dimensions include room for ascenders and descenders for the font, even if the text does not have any ascenders/descenders. [Note: Ascenders and descender dimensions are sampled from these letters: M, j, ' (apostrophe)]

• background_tight = True: Background dimensions are set with the minimum bounding box for the text.

• padding_*: adds (positive numbers) or subtracts (negative numbers) this many pixels from the bounding box on the specified side (_top, _bottom, _left, _right)

Special tips on BDF loaded fonts:

• Explain how to reduce BDF font file size: Remove any extraneous glyphs manually with a text editor
• Reference the Adobe BDF format definition for loaded fonts in BDF format: Document here

[FoamyGuy]

Sorry it took me a bit until I got back to this. I think this is a good place to coordinate for now. Other folks can chime in if they have idea's and we'll close the issue once the edits to the guide pages are complete.

There is a learn guide repo but it contains mostly projects and sample code used in learn guides. Not the content of the guide pages.

These all look like they'd be great additions to the current guide pages. I will work on making some minimal sample code to illustrate the background size options and get some screenshots taken so we can show examples of how they different options affect the look.

I can get make images illustrating how the origin point works with multi-line text strings while I'm at it.

[jposada202020]

@FoamyGuy I was looking into @kmatch98 description and the examples that he mentions here. taking into account the work being done in https://github.com/adafruit/Adafruit_CircuitPython_DisplayIO_Layout/issues/3
Maybe we can at least the documentation done here based on the work from kmatch98. And then when the display framework is merged it will be easier to incorporate to it. I can work in the doc/learning guide based on that if kmatch has not already done all the work if required.

[FoamyGuy]

@jposada202020 I am definitely on board with that idea. One thing that would be great is adding a few more examples that will illustrate some of the features that are less documented. We can use screenshots from those examples in the guide page once it gets created. Perhaps this example: https://github.com/adafruit/Adafruit_CircuitPython_Display_Text/blob/master/examples/display_text_background_color_padding.py could be modified a bit to illustrate the usage of background_tight and padding values. The code in there now is essentially a test case that we noticed a bug with at some point. It's a tad more of a test that proves the bug is fixed rather than an example meant to show how to use something as is.

[kmatch98]

For completeness, I thought I would add a few more text-related items to the features that need documentation. I don’t have any experience with editing learn guides but let me know if you want any contribution from my end.

Since the issue was raised above, @FoamyGuy and @jepler have added several other features:

• ascent and descent properties of the font files to help improve ability to keep a common baseline.
• variable sized background box for bitmap_label (I think this is still in development)
• better word wrapping capability based on letter count or by pixel width of the label
• ability to use .PCF font format (this is from a sister library https://github.com/adafruit/Adafruit_CircuitPython_Bitmap_Font)

[FoamyGuy]

All really great suggestions! Thank you @kmatch98

I have access and experience modifying the learn guides so I can go in and make those final edits when we are ready to do them.

I think the best way to collaborate on it will be working on examples and writing into txt or md files for now. Those can be checked in to a branch somewhere that we can all see, or posted on threads like this one.

Then when it's finalized I can go in and put it into the actual guides system.

I think we want to try to get at least one example that illustrates each feature. That way we can include screenshots of them in the guide, and embed the github code links to those examples in the guides.

[jposada202020]

Good, I worked already in the examples to illustrate the following:

• background_tight = False
  

• background_tight = True
  

• padding parameters
  

Based on https://github.com/adafruit/Adafruit_CircuitPython_Display_Text/blob/master/examples/display_text_background_color_padding.py
I will need to make the screen shots
I could work during the weekend in the draft version, and maybe we can discuss/edit/correct/add/remove after. I will need to read also the new points that @kmatch98 mentioned. I have not looked at those yet.

[FoamyGuy]

@jposada202020 Awesome! Thank you for working on this. Check out BitmapSaver library if you haven't already for saving screenshots: https://github.com/adafruit/Adafruit_CircuitPython_BitmapSaver

My PyGameDisplay driver is good for screenshots as well on PC, but does require a bit more setup

[jposada202020]

Thanks @FoamyGuy I have alread done the setup with your PyGameDisplay driver. I will use that one.

[jposada202020]

@FoamyGuy @kmatch98 Included the proposal for the guide/doc, I just want to go too far into this if this is not good. Let me know if this make any sense.

Also, in doing this, I have a proposal to change the library to solve issues #100 and #103. The proposal will add a new parameter call yoffset that will mask/unmask the offset value calculated with get_ascend_descend function and probably let us solve those issue, it will need some tinkering for the background box as this value is also used there. Label change proposal and Code example are here
https://github.com/jposada202020/Displaytextoffset
Thanks,

Label Library

The label library allows us to publish certain text into a display. There are different label parameters that allow us to set up the font, position, background characteristics among others.
A Label is an artifact of an organized set of tilegrids.

Label position

There are different ways to set up the label position in the display. This includes:

• x, y coordinates
• Anchor point
• Anchor position coordinates

x, y coordinates

x, y coordinates allows to define the label position. When setting text location using the x and y properties, you are setting the
origin point. It is located relative to the text as shown below.

Anchor Points

The anchor_point property of the label is a (x, y) tuple. The values range from 0 to 1 with x being the horizontal and y being the vertical. The origin is in the upper left corner. A value of 0 is at the origin. A value of 1 is all the way to the right/down.

Anchor Position

The label position on the display could be located using the anchored_position property.
The values are actual screen coordinates in pixels and defined by a tuple representing (x, y) coordinates

TileGrid Position

When you create a text label, the library will create an imaginary box that encloses all the glyphs in the text. All the glyphs
present within the text will be located inside this box.
This box is calculated inside the library taking into account the glyphs ascent and descent values in a particular text.
When no text is provided the library will use the characters "M j ' " to calculate the boundingbox

Ascend

Is a value in pixels of the upper portion that extends from the median of a particular glyph

Descend

Is a value in pixels of the bottom portion that extends from the median of a particular glyph

Advanced text positioning

Label text positioning is calculated inside the private function

def _update_text()

Positioning in the y-axis is calculated as follows:

position_y = y - glyph.height - glyph.dy + y_offset

• glyph.height: glyph height value
• glyph.dy: glyph distance in the y axe from
  the glyph origin
• y_offset: Bounding box middle point. This is
  calculated with the Label library function def _get_ascent_descent

Label Background

Label background is an imaginary box that enclose the label. We can define the color and size of this box to create different cool effects.
This library allows defining different characteristics for the label background:

• background_tight
• padding_top (bottom|left|right)

###Background tight
When we declare background_tight as True the background box will correspond exactly to the label boundingbox
When False the ascent and descent will be added to the boundingbox dimensions.

###Padding
Value in pixels of the background shift to the boundingbox dimensions values.

Other Topics

Builtin Font

When a font is not specified in Label parameters, CircuitPython uses the default font builtin. This is included in the core library fontio.

import fontio
from adafruit_display_text import label

display = board.DISPLAY
main_group = displayio.Group()

text = "CircuitPython"
text_area = label.Label(fontio.BuiltinFont(), text=text, color=0x0000FF, background_color=0xFFAA00)

Optimize Font File Size (Manually)

You could use a text editor to remove glyphs from a .bdf file. BDF files are just text!

Open a BDF file and search for “asciitilde” — this is usually the highest plain-ASCII-value glyph we want to preserve. A few lines down there will be an “ENDCHAR” line.

Delete everything after the ENDCHAR line, then add a line containing ENDFONT. That’s it! Save the file, which is usually just a small fraction of the original size.

You won’t get any accented characters or special punctuation this way, so it’s not always the right thing for every situation. For the
majority of plain-text programs though, this can really help stretch your CIRCUITPY drive space!

[FoamyGuy]

On first read through all of this looks great! Thanks for taking the time to get this out @jposada202020. Over the weekend I'll take a deeper dive into this and start moving it into a draft page in the learn guide so we can get some feedback from kattni and/or anne.

[jposada202020]

This is just a note to remind to include in the new documentation some mention regarding the Base alignment after discussion in discord. Also it would be a good to explain to people the space distance.

[jposada202020]

Ascci representation the Ascent/Descent for read the docs, i cannot seem to paste it here the right way

[jposada202020]

I review the box and update the text
source here: https://github.com/jposada202020/Test_Images/blob/main/version2.py
Updated version up the above post: https://github.com/jposada202020/Test_Images/blob/main/label_documentation.md
Please review and add, I am technical service person and not too much a teacher, so I simplified a lot everything because I start from the base that people will know a little, but for this I do not think is the case, so I am aware that changes are needed. Thanks

[FoamyGuy]

The new guide for display_text library went live today! https://learn.adafruit.com/circuitpython-display_text-library

[kmatch98]

Super awesome. @FoamyGuy and @jposada202020 thanks for all your additions and documentation to make this even more useful for folks!

[jposada202020]

@FoamyGuy Amazing guide. Nice graphics!!! and very detailed explanations, every possible parameter was described and account for. Excelent work here!

[ladyada]

yes! its great, good work :)