search

adafruit / Adafruit-GFX-Library

Adafruit GFX graphics core Arduino library, this is the 'core' class that all our other graphics libraries derive from
https://learn.adafruit.com/adafruit-gfx-graphics-library
Other
2.36k stars 1.54k forks source link

Added getTextBounds() optional arguments xF and yF. #430

Open tedtoal opened 1 year ago

tedtoal commented 1 year ago

There are extensive comments in getTextBounds() header in the .cpp file.

The arguments are pointers to places to return values, just like several already-existing arguments to the function. They have default values of NULL, so that if they are not specified in the call, no value is returned for them. Therefore, no change is needed to existing code.

The change applies to all platforms. It has no known limitations.

The reason for this change has to do with the idiosyncrasies of the way the code writes character data to the device. That is accomplished by calling the device setCursor() function to set the position to be written, then calling the device print() function. However, there is no clear relationship between the initial cursor position that is set, and the upper-left (or lower-left) corner of the resulting text boundary box. This is because the font data is specified in a way that allows it to start either slightly left or right of the cursor position, and in addition, the cursor y-position is not necessarily the position of the bottom of the text string, but instead is the position of the text BASELINE, ignoring character DESCENDERS (as on "g" for example).

More directly, the reason for this is that a user of the code might want to JUSTIFY a string, left or right or centered, top or bottom or centered. This cannot be done with the code as it was. The new arguments provide additional information about the size of the text string, that allow it to be properly justified. Previously the function reported the correct string width and height, but it did not report the data needed to set the initial cursor position so that the string would appear where you wanted it.

I tried hard to put in clear comments in the header section of getTextBounds(), but this is such a baffling and obscure issue that I just had to do my best and leave it at that.

tedtoal commented 1 year ago

One other comment. I renamed the arguments (x1, y1) of getTextBounds() to (xL, yT), to make it clear these are the left and top coordinates of the bounding box.

tedtoal commented 1 year ago

Great, I hope you can incorporate the changes, thanks!