Using-Enhanced-Font-Interfaces.md

-_Understand and use enhanced LOGFONT and DEVFONT intefaces of MiniGUI 4.0._
+_Understand and use enhanced font intefaces of MiniGUI 4.0._
+
+Table of Contents
 
 ## Overview
 
+In order to support complex or mixed scripts, we tuned and enhanced
+MiniGUI's font interfaces in version 4.0.0.
+
+Before we continue, we need to clarify a few terms and concepts:
+
+- `devfont`: The device font object. It is the underlying object
+   containing the glyphs of all or some characters in specific
+   language or script.
+- `logfont`: A logical font object; it is the real object used by
+   MiniGUI app to render paragraphs, words, or characters.
+
+Generally, a MiniGUI app creates one or more logfonts by specifying
+the family, style, size, and charset/encoding, and calls GDI functions
+to lay out, shape, and render the text.
+
+When creating a logfont object, MiniGUI retrieves the devfonts which
+matched the family, style, size, and character/encoding for the
+requested logfont object in the devfonts base, which is loaded in
+the start stage of MiniGUI.
+
+However, one logfont object does not always correspond to a
+devfont object, but rather to multiple devfont objects.
+
+For example, when we want to show a text like below:
+
+```
+“对暴徒仁慈就是对良民的残忍”
+    -- Vincent Wei
+```
+
+It is well known that, a font is often designed for a particular
+language/script or a few similar languages/scripts.
+So MiniGUI may retrieve the glyphs for the characters in the first line
+(they are all in Chinese) in a font file named `宋体.ttf`, while in another
+font file named `Arial.ttf` for characters in the second line (they
+are all in English).
+
+Therefore, a logfont object actually corresponds to a collection of
+devfont objects, which match the logfont's family, style, size, and
+charset/encoding.
+
+Before version 4.0.0, a logfont object can be represented by one or
+two devfont objects. Therefore, MiniGUI can easily handle standard
+languages/scripts, like Chinese, Japanese, English (Latin).
+
+However, when we want to handle a text in the complex and mixed scripts
+like Arabic and Indic, the old logfont/devfont facility will not work.
+
+Therefore, we tuned and enhanced the font interfaces in version 4.0.0.
+
+### Changes of Font Name
+
+You know that we often use a string to specify a devfont or logfont:
+
+
+
+The styles of LOGFONT changed.
+
+* Add new rendering style:
+  1. `FS_RENDER_ANY`: Not specified.
+  1. `FS_RENDER_MONO`:
+  1. `FS_RENDER_GREY`:
+  1. `FS_RENDER_SUBPIXEL`:
+* Some old styles are deprecated:
+  1. `FS_WEIGHT_BOOK`; use `FS_RENDER_GREY` instead.
+  1. `FS_WEIGHT_SUBPIXEL`; use `FS_RENDER_SUBPIXEL` instead.
+* Introduced or redefined the weight styles to follow OpenType specification:
+  1. `FONT_WEIGHT_ANY`: Not specified.
+  1. `FONT_WEIGHT_THIN`: Thin.
+  1. `FONT_WEIGHT_EXTRA_LIGHT`: Extra light (Ultra Light).
+  1. `FONT_WEIGHT_LIGHT`: Light.
+  1. `FONT_WEIGHT_REGULAR`: Regular (Normal).
+  1. `FONT_WEIGHT_MEDIUM`: Medium.
+  1. `FONT_WEIGHT_DEMIBOLD`: Demi Bold (Semi Bold)
+  1. `FONT_WEIGHT_BOLD`: Bold.
+  1. `FONT_WEIGHT_EXTRA_BOLD`: Extra Bold (Ultra Bold).
+  1. `FONT_WEIGHT_BLACK`: Black (Heavy).
+* Introduce the new decoration styles and replace
+`FONT_UNDERLINE_LINE` and `FONT_STRUCKOUT_LINE` with them:
+  1. `FONT_DECORATE_ANY`: Not specified.
+  1. `FONT_DECORATE_NONE`: None.
+  1. `FONT_DECORATE_UNDERLINE`: glyphs are underscored.
+  1. `FONT_DECORATE_STRUCKOUT`: glyphs are overstruck.
+  1. `FONT_DECORATE_US`: Both `FONT_DECORATE_UNDERLINE`
+and `FONT_DECORATE_STRUCKOUT`.
+  1. `FONT_DECORATE_OUTLINE`: Outline (hollow) glyphs.
+  1. `FONT_DECORATE_REVERSE`: Reserved for future. Glyphs have their
+foreground and background reversed.
+* The following style are deprecated:
+  1. `FONT_OTHER_LCDPORTRAIT`
+  1. `FONT_OTHER_LCDPORTRAITKERN`
+
+For a new app, you should use the new function `CreateLogFontEx` to
+create a LOGFONT, and specify the weight and rendering method of the glyph.
+
+For the back-compatibility, you can still use `CreateLogFont` to create a new
+LOGFONT. However, `FS_WEIGHT_BOOK` will be treated `FS_WEIGHT_REGULAR` and
+`FS_RENDER_GREY`, while `FS_WEIGHT_SUBPIXEL` will be treated
+`FS_WEIGHT_REGULAR` and `FS_RENDER_SUBPIXEL`.
+
+You can still use `CreateLogFontByName` to create a new LOGFONT.
+But the style string in the font name changed from
+
+    <weight><slant><flipping><other><underline><struckout>
+
+to
+
+    <weight><slant><flipping><other><decoration><rendering>
+
+Note that `<underline>` and `<struckout>` are merged to `<decoration>`
+in order to keep the style string is still 6-character long.
+
+Consequently, if you want to use the rendering method SUPIXEL for a TTF font,
+please define the logical font name in the following way:
+
+    ttf-Courier-rrncns-*-16-UTF-8
+
+Moreover, the family name of a DEVFONT supports aliases since 4.0.0:
+
+    <fonttype>-<family[,aliase]*>-<styles>-<width>-<height>-<charset[,charset]*>
+
+for example:
+
+    ttf-Arial,Sans Serif-rrncnn-8-16-ISO8859-1,UTF-8
+    ttf-courier,monospace,serif-rrncnn-8-16-ISO8859-1,UTF-8
+
+Note that the length of one DEVFONT name can not exceed 255 bytes.
+
+Since version 4.0.0, you can specify up to 7 family names for a logfont name,
+such as:
+
+    ttf-Courier,宋体,Naskh,SansSerif-rrncns-U-16-UTF-8
+
+In this way, you can specify a logfont to use multiple devfonts
+to render a complex text. This is useful when different glyphs are
+contained in different font files. It is well known that, a font is
+often designed for a particular language/script or a few similar
+languages/scripts.
+
+Since 4.0.0, the previous width field of a logfont name is used for
+the glyph orientation:
+
+- 'U': Glyphs stand upright (default).
+- 'S': Glyphs are rotated 90 degrees clockwise (sideways).
+- 'D': Glyphs are upside-down.
+- 'L': Glyphs are rotated 90 degrees counter-clockwise (sideways left).
+
 ## Key Points