"Juicy Fonts" - User Function Library v1.0

Command Reference


Available commands:




jf_load_font(filename$)

Parameters

filename$ - Specifies the font image file to be loaded. This must include the file type extension (.png/.tga/.bmp). The associated metrics file (.jfm) must also reside in the same directory as the font image.

Description

Loads the specified font image and associated metrics into memory.

This function returns the handle of the successfully loaded font. The handle should be assigned to a variable so that you can specify the font for use with the other commands in this library.

Index




jf_free_font(font_handle)

Parameters

font_handle - Handle of a previously loaded font.

Description

Removes the specified font from memory meaning that it can no longer be used.

Note: if you have created any static text objects (see jf_create_text) that use the specified font, they will also need to be independantly freed with jf_free_text.

Index




jf_text(font_handle,x,y,text$[,align_x][,align_y][,wrap_width])

Parameters

font_handle - Handle of font to be used.
x,y - Screen coords to align the text to.
text$ - The text to be displayed.
align_x - (Optional) Specifies how the text should be horizontally aligned:
0 : Left justify text. (Default)
1 : Centre text.
2 : Right justify text.
align_y - (Optional) Specifies how the text should be vertically aligned:
0 : Align to top of text. (Default)
1 : Align to centre of text.
2 : Align to bottom of text.
wrap_width - (Optional) Specifies width to word wrap the text to. Defaults to no word wrap - i.e. all text is displayed on a single line.

Description

Draws the specified text using the specified font. All text is drawn to the currently set buffer.

Note: if you need to display the same text at the same position every time the display is updated (such as menu options), it is recommended you use jf_create_text and jf_draw_text instead, as it's faster.

Index




jf_create_text(font_handle,x,y,text$[,align_x][,align_y][,wrap_width])

Parameters

font_handle - Handle of font to be used.
x,y - Screen coords to align the text to.
text$ - The text to be displayed.
align_x - (Optional) Specifies how the text should be horizontally aligned:
0 : Left justify text. (Default)
1 : Centre text.
2 : Right justify text.
align_y - (Optional) Specifies how the text should be vertically aligned:
0 : Align to top of text. (Default)
1 : Align to centre of text.
2 : Align to bottom of text.
wrap_width - (Optional) Specifies width to word wrap the text to. Defaults to no word wrap - i.e. all text will be displayed on a single line.

Description

Creates a "static text object", using the specified text and font. This text can then be quickly drawn whenever needed by calling jf_draw_text. This is useful for when you need to display the same text at the same position every time the display is updated (such as menu options). Doing so is faster than continually calling jf_text because that command needs to calculate the positions of all text characters every time it's called, whereas this is only done once, when jf_create_text is called.

This function returns the handle of the created text object. The handle should be assigned to a variable so that you can specify which text object to use with the other commands in this library.

Index




jf_draw_text(text_handle)

Parameters

text_handle - Handle of the static text to be drawn.

Description

Draws the text of a static text object, previously created with jf_create_text. All text is drawn to the currently set buffer.

Index




jf_free_text(text_handle)

Parameters

text_handle - Handle of static text object previously created with jf_create_text.

Description

Removes the specified static text object from memory meaning that it can no longer be used.

Index




jf_font_width(font_handle)

Parameters

font_handle - Handle of the font to find the width of.

Description

This function returns the pixel width of the font - i.e. the widest character frame in the font image.

Index




jf_font_height(font_handle)

Parameters

font_handle - Handle of the font to find the height of.

Description

This function returns the pixel height of the font - i.e. the height of all character frames in the font image.

Index




jf_font_string(font_handle,string$)

Parameters

font_handle - Handle of the font to check the string against.
string$ - String to be converted.

Description

Removes all characters from a string that aren't present in the given font.

This function returns a converted version of string$ that contains valid font characters only.

Index




jf_measure_text(font_handle,text$[,wrap_width])

Parameters

font_handle - Handle of font to be used.
text$ - The text to be measured.
wrap_width - (Optional) Specifies width to word wrap the text to. Defaults to no word wrap - i.e. all text is considered to be on a single line.

Description

Calculates the width, height and number of lines that would be used if the given text was displayed using the given font. This is useful for working out where text needs to be positioned on-screen, etc.

This function returns the text's measurements via the global variables jf_text_width, jf_text_height and jf_text_lines.

Index




jf_set_line_spacing(font_handle,spacing)

Parameters

font_handle - Handle of font to be affected.
spacing - Number of pixel rows to use when spacing.

Description

Specifies the number of pixel rows to use when spacing apart word wrapped lines of text, displayed using the given font. The amount specified will be in addition to the default spacing - i.e. the specified font's height. As such, negative values can be used to squash lines together, but only up to a maximum value of the font's height. You can find a font's current line spacing with jf_get_line_spacing.

Index




jf_get_line_spacing(font_handle)

Parameters

font_handle - Handle of font to find line spacing of.

Description

Each font can be set to use a certain number of pixel rows when spacing apart word wrapped lines of text. This amount is in addition to the default spacing - i.e. the specified font's height. As such, negative values can be used to squash lines together, but only up to a maximum value of the font's height. A font's line spacing can be changed at any time with jf_set_line_spacing.

This function returns the additional line spacing currently set for the specified font.

Index




jf_set_ignore_shadow(font_handle,state)

Parameters

font_handle - Handle of font to be affected.
state - True to ignore the shadow when spacing. False to include the shadow when spacing.

Description

Specifies whether or not to ignore the given font's shadow (if any) when spacing characters apart on-screen. By ignoring the shadow, characters can overlap the shadow of the adjacent character, which is sometimes more aesthetically pleasing. This command will only have an effect on fonts that have a shadow that extends to the left/right of the main character face. You can find a font's current shadow state with jf_get_ignore_shadow.

Note: a font's default shadow state is determined when the font is exported from the Juicy Fonts editor. Specifically, the default state matches the state of the "Ignore Shadow" button in the editor, at the time the font was exported. However, this command allows you override the default setting, if you so wish.

Index




jf_get_ignore_shadow(font_handle)

Parameters

font_handle - Handle of font to return the shadow state of.

Description

Each font is set to either include or ignore the shadow (if any) when spacing characters apart on-screen. By ignoring the shadow, characters can overlap the shadow of the adjacent character, which is sometimes more aesthetically pleasing. A font's shadow state can be changed at any time with jf_set_ignore_shadow.

This function returns the shadow state currently set for the specified font. This will be True if the font's shadow is currently set to be ignored, or False otherwise.

Note: a font's default shadow state is determined when the font is exported from the Juicy Fonts editor. Specifically, the default state matches the state of the "Ignore Shadow" button in the editor, at the time the font was exported.

Index




jf_set_kern_align(font_handle,state)

Parameters

font_handle - Handle of font to be affected.
state - True to include the font's kerning. False to ignore the font's kerning.

Description

Specifies whether or not to include kerning when aligning text using the given font to specific screen coordinates. In practical terms, you will probably only want to include kerning when displaying lines of left/right justified text that use a fixed width font. Doing so will ensure that all characters are vertically aligned with the characters in the lines above/below. You can find a font's current kern alignment state with jf_get_kern_align.

Note: a font's default kern alignment state is determined when the font is exported from the Juicy Fonts editor. If the font is fixed width (all characters' widths - including kerning - are equal), it uses kern alignment by default, otherwise it does not. However, this command allows you override the default setting, if you so wish.

Index




jf_get_kern_align(font_handle)

Parameters

font_handle - Handle of font to return the kern alignment state of.

Description

Each font is set to either include or ignore kerning when aligning text to specific screen coordinates. Kerning is usually only set to be included when displaying lines of left/right justified text that use a fixed width font, as doing so will ensure that all characters are vertically aligned with the characters in the lines above/below. However, a font's kern alignment state can be changed at any time with jf_set_kern_align.

This function returns the kern alignment state currently set for the specified font. This will be True if the font is currently set to use kern aligment, or False otherwise.

Note: a font's default kern alignment state is determined when the font is exported from the Juicy Fonts editor. If the font is fixed width (all characters' widths - including kerning - are equal), it uses kern alignment by default, otherwise it does not.

Index




Copyright © Chris Chadwick 2006