a5061ecec5
An effort was started some time ago to consolidate all internal documentation in the git tree. However, this was just an accumulation of files in various formats without any strucutre or way to browse it, which results in no one even knowing that we have docs here. This converts most of the files to restructuredtext and uses Sphinx to generate an HTML browsable user manual (with a table of content and a first attempt to put things in a global hierarchy). There are almost no changes to the documentation content in this commit (some obviously obsolete things were removed). The plan is to get the toolchain up and running to make these docs easily available, and only then see about improving the content. We can migrate some things off the wiki and website, and rework the table of contents to have some more hierarchy levels because currently it's a bit messy. Change-Id: I924ac9dc6e753887ab56f18a09bdb0a1e1793bfd Reviewed-on: https://review.haiku-os.org/c/haiku/+/4370 Reviewed-by: Niels Sascha Reedijk <niels.reedijk@gmail.com>
229 lines
9.1 KiB
ReStructuredText
229 lines
9.1 KiB
ReStructuredText
FontServer class
|
|
################
|
|
|
|
The FontServer provides the base functionality for providing font
|
|
support for the rest of the system and insulates the rest of the server
|
|
from having to deal too much with FreeType.
|
|
|
|
Member Functions
|
|
================
|
|
|
|
+-----------------------------------+-----------------------------------+
|
|
| FontServer(void) | ~FontServer(void) |
|
|
+-----------------------------------+-----------------------------------+
|
|
| void Lock(void) | void Unlock(void) |
|
|
+-----------------------------------+-----------------------------------+
|
|
| void SaveList(void) | status_t ScanDirectory(const char |
|
|
| | \*path) |
|
|
+-----------------------------------+-----------------------------------+
|
|
| FontStyle \*GetFont(font_family | FontInstance |
|
|
| family, font_style face) | \*GetInstance(font_family family, |
|
|
| | font_style face, int16 size, |
|
|
| | int16 rotation, int16 shear) |
|
|
+-----------------------------------+-----------------------------------+
|
|
| int32 CountFamiles(void) | status_t IsInitialized(void) |
|
|
+-----------------------------------+-----------------------------------+
|
|
| int32 CountStyles(font_family | FontStyle \*GetStyle(font_family |
|
|
| family) | family, font_style style) |
|
|
+-----------------------------------+-----------------------------------+
|
|
| void RemoveFamily(const char | FontFamily \*_FindFamily(const |
|
|
| \*family) | char \*name) |
|
|
+-----------------------------------+-----------------------------------+
|
|
| ServerFont \*GetSystemPlain(void) | ServerFont \*GetSystemBold(void) |
|
|
+-----------------------------------+-----------------------------------+
|
|
| ServerFont \*GetSystemFixed(void) | bool SetSystemPlain(const char |
|
|
| | \*family, const char \*style, |
|
|
| | float size) |
|
|
+-----------------------------------+-----------------------------------+
|
|
| void RemoveUnusedFamilies(void) | bool FontsNeedUpdated(void) |
|
|
+-----------------------------------+-----------------------------------+
|
|
|
|
FontServer(void)
|
|
----------------
|
|
|
|
1. Create access semaphore
|
|
2. Call FT_Init_FreeType()
|
|
3. If no error initializing the FreeType library, set init flag to true
|
|
|
|
~FontServer(void)
|
|
-----------------
|
|
|
|
1. Call FT_Done_FreeType()
|
|
|
|
void Lock(void), void Unlock(void)
|
|
----------------------------------
|
|
|
|
These functions simply acquire and release the internal access
|
|
semaphore.
|
|
|
|
void SaveList(void)
|
|
-------------------
|
|
|
|
Saves the list of all scanned and valid font families and styles to
|
|
disk
|
|
|
|
|
|
1. create a BMessage for storing font family data (hereafter, the font message)
|
|
2. create a BMessage for storing a list of font family messages (hereafter, the list message)
|
|
3. create a boolean tuned flag and a boolean fixed flag
|
|
4. Iterate through all families
|
|
|
|
A. for each family, get its name and add its name to the font message as "name"
|
|
B. iterate through the families styles
|
|
|
|
a. get the style's name, and if valid, add it to the font message as "styles"
|
|
b. if IsTuned and IsScalable, set the tuned flag to true
|
|
c. if IsFixedWidth, set the fixed flag to true
|
|
|
|
C. if the tuned flag is set, add a boolean true to the font message as "tuned"
|
|
D. if the fixed flag is set, add a boolean true to the font message as "fixed"
|
|
E. add the font message to the list message as "family"
|
|
F. empty the font message
|
|
|
|
5. Create a BFile from the path definition SERVER_FONT_LIST for Read/Write, creating the file if nonexistent and erasing any existing one
|
|
6. Flatten the list message to the created BFile object
|
|
7. Set the needs_update flag to false
|
|
|
|
|
|
status_t ScanDirectory(const char \*path)
|
|
-----------------------------------------
|
|
|
|
ScanDirectory is where the brunt of the work of the FontServer is done: scan the directory of all fonts which can be loaded.
|
|
|
|
1. Make a BDirectory object pointer at the path parameter. If the init code is not B_OK, return it.
|
|
2. Enter a while() loop, iterating through each entry in the given directory, executing as follows:
|
|
|
|
a. Ensure that the entry is not '.' or '..'
|
|
b. Call FT_New_Face on the entry's full path
|
|
c. If a valid FT_Face is returned, iterate through to see if there are any supported character mappings in the current entry.
|
|
d. If there are no supported character mappings, dump the supported mappings to debug output, call FT_Done_Face(), and continue to the next entry
|
|
e. See if the entry's family has been added to the family list. If it hasn't, create one and add it.
|
|
f. Check to see if the font's style has been added to its family. If so, call FT_Done_Face, and continue to the next entry
|
|
g. If the style has not been added, create a new SFont for that family and face, increment the font count, and continue to the next entry.
|
|
|
|
3. set the needs_update flag to true
|
|
4. Return B_OK
|
|
|
|
Supported character mappings are Windows and Apple Unicode, Windows
|
|
symbol, and Apple Roman character mappings, in order of preference
|
|
from first to last.
|
|
|
|
FontStyle \*GetFont(font_family family, font_style face)
|
|
--------------------------------------------------------
|
|
|
|
Returns an FontStyle object for the specified family and style or NULL
|
|
if not found.
|
|
|
|
1. Call \_FindFamily() for the given family
|
|
2. If non-NULL, call its FindStyle() method
|
|
3. Return the result
|
|
|
|
FontInstance \*GetInstance(font_family family, font_style face, int16 size, int16 rotation, int16 shear)
|
|
--------------------------------------------------------------------------------------------------------
|
|
|
|
Returns a usable instance of a specified font object with specified
|
|
properties.
|
|
|
|
|
|
1. Duplicates and performs the code found in GetFont
|
|
2. Assuming that the FontStyle object is non-NULL, it calls its GetInstance method and returns the result.
|
|
|
|
|
|
int32 CountFamilies(void)
|
|
-------------------------
|
|
|
|
Returns the number of valid font families available to the system.
|
|
|
|
|
|
1. Return the number of items in the family list
|
|
|
|
|
|
status_t IsInitialized(void)
|
|
----------------------------
|
|
|
|
Returns the initialization status variable
|
|
|
|
|
|
int32 CountStyles(font_family family)
|
|
-------------------------------------
|
|
|
|
Returns the number of styles available for a given font family.
|
|
|
|
|
|
1. Call \_FindFamily() to get the appropriate font family
|
|
2. If non-NULL, call its return the result of its CountStyles method
|
|
|
|
FontStyle \*GetStyle(font_family family, font_style style)
|
|
----------------------------------------------------------
|
|
|
|
Gets the FontStyle object of the family, style, and flags.
|
|
|
|
1. Call \_FindFamily() to get the appropriate font family
|
|
2. If non-NULL, call the family's GetStyle method on the font_style parameter and return the result
|
|
3. If family is NULL, return NULL
|
|
|
|
void RemoveFamily(const char \*family)
|
|
--------------------------------------
|
|
|
|
Removes a font family from the family list
|
|
|
|
1. Look up font family in the family list via \_FindFamily()
|
|
2. If it exists, delete it
|
|
|
|
FontFamily \*_FindFamily(const char \*name)
|
|
-------------------------------------------
|
|
|
|
Looks up a FontFamily object based on its family name. Returns NULL if not found.
|
|
|
|
1. Call the family list's find() method.
|
|
2. Return the appropriate FontFamily object or NULL if not found.
|
|
|
|
ServerFont \*GetSystemPlain(void), ServerFont \*GetSystemBold(void), ServerFont \*GetSystemFixed(void)
|
|
------------------------------------------------------------------------------------------------------
|
|
|
|
These return a copy of a pointer to the system-wide ServerFont objects
|
|
which represent the appropriate system font settings. It is the
|
|
responsibility of the caller to delete the object returned. NULL is
|
|
returned if no setting has been set for a particular system font.
|
|
|
|
|
|
bool SetSystemPlain(const char \*family, const char \*style, float size)
|
|
------------------------------------------------------------------------
|
|
|
|
bool SetSystemBold(const char \*family, const char \*style, float size)
|
|
-----------------------------------------------------------------------
|
|
|
|
bool SetSystemFixed(const char \*family, const char \*style, float size)
|
|
------------------------------------------------------------------------
|
|
|
|
|
|
The system fonts settings may be set via these calls by specifying the
|
|
family, style, and size. They return true if everything worked out ok
|
|
and false if not. Settings are not changed if false is returned.
|
|
|
|
1. Call \_FindFamily on the family parameter. if NULL, return false
|
|
2. Call the family's GetStyle member. if NULL, return false
|
|
3. if the appropriate system font pointer is non-NULL, delete it
|
|
4. call the style's Instantiate member with the size parameter
|
|
|
|
|
|
void RemoveUnusedFamilies(void)
|
|
-------------------------------
|
|
|
|
The purpose of this function is to allow for a complete rescan of the
|
|
fonts in the appropriate directories.
|
|
|
|
|
|
1. Iterate through the family list
|
|
|
|
A. Get a family
|
|
B. if it has no dependents, remove it from the list and delete it
|
|
|
|
2. Set the needs_update flag to true
|
|
|
|
|
|
bool FontsNeedUpdated(void)
|
|
---------------------------
|
|
|
|
Returns the value of the needs_update flag
|