Alamchu - ZiYueCommentary/BlitzToolbox GitHub Wiki

[!WARNING] Alamchu is underdeveloped for now. The features which it should have aren't fully implemented yet.

[!Important] Alamchu is a Blitz3D TSS exclusive library.

It contains Userlib Exception Capturing for handling errors. This feature will help developers to catch and handle exceptions, but in non-Blitz3D-TSS-engine, throws "Unknown runtime exception", even exceptions that shouldn't crash the program.

Alamchu is a text layout engine library for displaying multi-language text, powered by Pango.

The name "Alamchu" comes from Arabic al-ʻĀlam (العالم, 'world') and Chinese chu (聚, 'unity'). Stands for "Great Unity of the People of the World".

Glossary

Font Description

A FontDescription describes a font in an implementation-independent manner.

See also: https://docs.gtk.org/Pango/type_func.FontDescription.from_string.html

Font Configuration

A FontConfiguation assists Pango in creating a font description by demand from Blitz3D programs. Basically, FontConfiguration is a FontDescription without SIZE, VARIATIONS, and FEATURES.

Default font

The default font of Alamchu will be created when the program launches. It supports displaying all languages.

The default font cannot be deleted by Pango_FreeFont. It will be deleted when the program exits only.

Loading fonts

Alamchu supports loading system-installed fonts only. If Alamchu cannot find the specific font on the computer, it will create another default font with your configuration.

• Pango_LoadFont requires a font configuration and a Blitz3D font size.
• Pango_LoadFontEx requires a font description. Note that decimal-number-font-size is different from Blitz3D. Approximately, $PangoSize = BlitzSize - 5$

Deleting fonts

When a Pango font is no longer needed, you can use Pango_FreeFont to delete it. Note that the default font cannot be deleted.

When the program terminates, Alamchu will delete all remaining Pango fonts automatically.

Rendering texts

Use Pango_Text to render a text. Alamchu shares the same buffer with Blitz3D's Text. It means that Pango_Text will render texts to where Text will. If you want to render texts to a specific buffer, invoke Pango_Text_.

Note that texts are not anti-aliased and can be wrapped by line feed.

Function List

Function	Description
Pango_DefaultFont%()	See Default font.
Pango_LoadFont%(font_conf$, size%)	See Loading fonts.
Pango_LoadFontEx%(font_desc$)	See Loading fonts.
Pango_SetFont(font%)	Self-explanatory.
Pango_StringWidth%(str$)	Self-explanatory.
Pango_StringHeight%(str$)	Self-explanatory.
Pango_Text(x%, y%, text$, align_x% = PANGO_TEXT_LEFT, align_y% = PANGO_TEXT_TOP)	See Rendering texts.
Pango_FreeFont(font%)	See Deleting fonts.