Testing the Appearance of Styles: Chimara Reference Manual

Testing the Appearance of Styles

Testing the Appearance of Styles — Finding out how the library displays your style hints

Functions

glui32	glk_style_distinguish ()
glui32	glk_style_measure ()

Includes

#include <libchimara/glk.h>

Description

You can suggest the appearance of a window's style before the window is created; after the window is created, you can test the style's actual appearance. These functions do not test the style hints; they test the attribute of the style as it appears to the player.

Note that although you cannot change the appearance of a window's styles after the window is created, the library can. A platform may support dynamic preferences, which allow the player to change text formatting while your program is running.

Changes that affect window size (such as font size changes) will be signalled by an evtype_Arrange event. However, more subtle changes (such as text color differences) are not signalled. If you test the appearance of styles at the beginning of your program, you must keep in mind the possibility that the player will change them later.

Functions

glk_style_distinguish ()

glui32
glk_style_distinguish (winid_t win,
                       glui32 styl1,
                       glui32 styl2);

Decides whether two styles are visually distinguishable in the given window. The exact meaning of this is left for the library to determine.

Chimara

Currently, all styles of one window are assumed to be mutually distinguishable.

Parameters

win	The window in which the styles are to be distinguished.
styl1	The first style to be distinguished from the second style.
styl2	The second style to be distinguished from the first style.

Returns

TRUE (1) if the two styles are visually distinguishable. If they are not, it returns FALSE (0).

glk_style_measure ()

glui32
glk_style_measure (winid_t win,
                   glui32 styl,
                   glui32 hint,
                   glui32 *result);

Tries to test an attribute of one style in the given window win . The library may not be able to determine the attribute; if not, this returns FALSE (0). If it can, it returns TRUE (1) and stores the value in the location pointed at by result .

As usual, it is legal for result to be NULL, although fairly pointless.

The meaning of the value depends on the hint which was tested:

`stylehint_Indentation`, `stylehint_ParaIndentation`	The indentation and paragraph indentation. These are in a metric which is platform-dependent. Most likely either characters or pixels.
`stylehint_Justification`	One of the constants `stylehint_just_LeftFlush`, `stylehint_just_LeftRight`, `stylehint_just_Centered`, or `stylehint_just_RightFlush`.
`stylehint_Size`	The font size. Again, this is in a platform-dependent metric. Pixels, points, or simply 1 if the library does not support varying font sizes.
`stylehint_Weight`	1 for heavy-weight fonts (boldface), 0 for normal weight, and -1 for light-weight fonts.
`stylehint_Oblique`	1 for oblique fonts (italic), or 0 for normal angle.
`stylehint_Proportional`	1 for proportional-width fonts, or 0 for fixed-width.
`stylehint_TextColor`, `stylehint_BackColor`	These are values from 0x00000000 to 0x00FFFFFF, encoded as described in Suggesting the Appearance of Styles.
`stylehint_ReverseColor`	0 for normal printing, 1 if the foreground and background colors are reversed.

Signed values, such as the stylehint_Weight value, are cast to glui32. They may be cast to glsi32 to be dealt with in a more natural context.

Parameters

win	The window from which to take the style.
styl	The style to perform the measurement on.
hint	The stylehint to measure.
result	Address to write the result to.

Returns

TRUE upon successul retrieval, otherwise FALSE.