SALLDHMF commented 5 years ago

Hello! In my current project, I use ESP32 and display with ILI9341. I would like to use your library, but - as a beginner - I have a lot of trouble with that. Is there somewhere documentation that describes the operation of all library functions? Eg: tft.drawString (.....) has four parameters, but what? What is the text datum? ... Of course, I will laboriously find explanations in the examples. But if there is documentation, it will be easier and faster.

Tomasz

Bodmer commented 5 years ago

Writing support documentation has been on my "To Do" list for a long time. It would take many hours to do this and at the moment I am busy with paid work. I can help with more specific questions that have short answers!

SALLDHMF commented 5 years ago

I understand you. Years ago, I wrote a lot of code. These were Pascal and assembler times :-). I quickly learned to comment very accurately at the time of writing. I know that in the future I won't have time for this.

Yes. I have a specific problem, although I don't know if it will be a "short answer" ;-)

With the help of your library, I can use several types of fonts. I can't handle them. The examples show the use of different types, but never all at once. Sometimes the files needed to use them are in the sample script folders. I can't handle setting up my own script with Local custom fonts, Free Fonts, TrueType fonts....

There are also many ways to use them:

tft.setTextSize (1);
tft.setTextColor (TFT_GREEN, TFT_BLACK);
tft.setFreeFont (MYFONT32)

tft.drawString ("rpm", 5, 20, 2);
tft.drawString (TEST_TEXT, 160, 140, GFXFF);
tft.print ("AAAA");

It's probably not all font functions. Which fonts does it apply to?

I would be grateful if you could help me learn how to use fonts.

Bodmer commented 5 years ago

I have sympathy for you as there are so many options.

The library is based on an old (2015) version of the Adafruit_ILI9341 + GFX library. At he time the library only had a very simple small 7x5 bitmap font which was not nice when scaled up and used on TFTs, so I created a new font format and published the library for the humble UNO here. This introduced the concept of numbered fonts. The original Adafruit bitmap being Font 1. The ones I added were Fonts 2, 4, 6, 7 and 8. Each one having increasing size and font 7 being a 7 segment font. To use say font 4 you then just use: tft.setFont(4); // The 4 is the font tft.drawString ("Testing 1234", xpos, ypos);

An alternative to these two lines is: tft.drawString ("Testing 1234", xpos, ypos, 4); // The 4 is the font

The "TFT_Rainbow_one_lib" example would be a good one to look at.

Adafruit finally decided to add a new font format that I call Free Fonts. To retain compatibility with the Adafruit library I added these. To use these fonts you need to use for example:

tft.setFreeFont (MYFONT32); // Select the free font tft.drawString ("Testing 1234", xpos, ypos); // The font number is missing here to use the Free Font

Unfortunately the Free Fonts do not render well in small sizes as they tend to have jagged edges due to stray pixels on curves (usually 8's look terrible). Since the ESP8266 and ESP32 have SPIFFS I had a light bulb moment and realised that anti-aliased fonts could be accommodated. To use these you have to load the font first as shown in Font Demo 1,2,3,4. For example:

tft.loadFont(AA_FONT_SMALL); // Must load the font first tft.drawString ("Testing 1234", xpos, ypos);

After you have unloaded the font the previous bitmap font methods can be used: tft.unloadFont();

I know this can be confusing but this is down to the way the library has evolved. The drawString(...) and font formatting (tft.setDatum(...) etc) will work with any of the fonts.

The Adafruit font rendering is a little crude, you have to use tft.setCursor(x,y) then tft.print(...). I wanted to be able to set the text datum, so for example text could easily be drawn in the middle of a box. So I introduced the drawString() function and the setDatum() function. Because short numbers and strings do not fully over-write larger one drawn on screen previously I added the setTextPadding(pixel_width) function. To use this you must define both foreground text colours and background ones.

I will try to create an example this weekwnd that supports all the fonts but I cannot guarantee I will find the time so it is worth experimenting. If you tell me exactly what you wish to display and which font you want to use then I can give you some guidance.

SALLDHMF commented 5 years ago

I am very, very grateful to you for these clarifications. It's worth putting them on Git for others.

tablatronix commented 4 years ago

Ditto, I am trying to figure out exactly how the text datum and drawstring functions work, but I am still not understanding it. The example could be made a little clearer for now as an alternative.

There just seems to be too many conditionals. If smooth font , padding, etc.

"Normally strings are printed relative to the top left corner but this can be changed with the setTextDatum() function. "

Top left corner of what? Doesn't the adafruit library use bottom left corner for glyph fonts?

Also what is drawRightString, drawCenterString ? Deprecated, but still in the string align examples..

I tried enabling PADDING_DEBUG, but still not seeing any change or borders.. , or any difference using different textDatums..

I guess I will play with the string align example, but it needs some comments or serial prints I think.

tablatronix commented 4 years ago

Ok I think I get it now. I think it is a just a confusing example. The font is too big, the 88,69 is confusing, the duplicated deprecated functions are unnecessary, the dot is the origin of the text draw box, aka the drawstring posx/posy origins, the text datum is the transform for the direction aka align.

Why not add a method to pass in the alignment to the function also, instead of a global toggle?

I will rewrite this to be a little cleared and PR it.

Bodmer commented 4 years ago

I think the "Free_Font_Demo" example will help you. This part of the sketch shows the datum marker on the screen and the text.

tablatronix commented 4 years ago

I will check that one out.

This was also confusing in the stringalign sketch, invisible stuff

  tft.setTextColor(TFT_BLACK);
  tft.drawString("X",160,180,2);

tablatronix commented 4 years ago

oh that is perfect, much better example of textDatum Thanks!

khanguslee commented 4 years ago

Just wanted to add that your library is very useful! However, the documentation of the library is quite hard for a beginner. Would you take PRs on simple documentation even if it was not the complete set of methods that your library provides?

Bodmer commented 4 years ago

Thanks. I have created a separate empty repository for the time being so you can push PR's there.