Difference between revisions of "LOADFONT"

From QB64 Wiki
Jump to navigation Jump to search
imported>Clippy
m
imported>SMcNeill
(style guidelines; adds information about OTF fonts (valid since versions prior to 1.000))
 
(23 intermediate revisions by 2 users not shown)
Line 1: Line 1:
The '''_LOADFONT''' function returns a font handle for a TrueType font (.TTF).
{{DISPLAYTITLE:_LOADFONT}}
The [[_LOADFONT]] function loads a TrueType font (.TTF) or an OpenType font (.OTF) file in a specific size and style and returns a [[LONG]] font handle.




{{PageSyntax}}
{{PageSyntax}}
: handle& = {{KW|_LOADFONT}} (''TTF_filename$'', ''size%''[, "MONOSPACE|, BOLD|, ITALIC|, UNDERLINE|, DONTBLEND"])
: {{Parameter|handle&}} = [[_LOADFONT]]({{Parameter|fontFileName$}}, {{Parameter|size%}}[, "{MONOSPACE|, BOLD|, ITALIC|, UNDERLINE|, UNICODE|, DONTBLEND}"])




{{PageDescription}}
{{PageDescription}}
* The assigned [[LONG]] font ''handle'' variable return value designates a font style to be used somewhere in a program.
* The assigned [[LONG]] font {{Parameter|handle&}} variable return value designates a font style to be used somewhere in a program. Valid handle values are greater than 0 ('''{{Parameter|handle&}} > 0''').
* ''TTF_filename$'' is the filename of '''truetype''' fonts only. Can include the path to the font file. Best to include font files with a program.
* {{Parameter|fontFileName$}} is the filename of a TrueType or OpenType font. Can include the path to the font file. Best practice is to include font files with a program.
* ''Size'' is the height of the font. Font sizes can be found using the [[_FONTHEIGHT]] function. Font ''size''s also affect [[SCREEN (statement)|SCREEN]] sizes!
* If no path is specified for {{Parameter|fontFileName$}} and the font file isn't in the same folder as the resulting binary, QB64 attempts to load from the default ''C:\Windows\Fonts'' path.
* ''Style'' parameter(s) used, if any, are literal(in quotes) or variable text parameters. '''"Monospace" has limited font file selections.'''
* {{Parameter|size%}} is the [[INTEGER]] height of the font. If the size is too large or small an [[ERROR Codes|error]] will occur.
* '''"DONTBLEND"''' turns off [[_ALPHA]] blending of fonts. This can also be done with the [[_DONTBLEND]] statement.
* Optional comma separated ''style'' parameter(s) used are literal [[STRING]]s (in quotes) or can be contained in variable(s).
* You can pass different font styles using different predefined [[STRING]] variable lists. You '''can''' include an empty style string!
** '''"MONOSPACE"''' loads a font with all characters occupying the same width. Results may be too spaced out for fonts that aren't designed for monospace use.
* '''Always check that font handle values are greater than 0 before using them or [[ERROR Codes|illegal function errors]] may occur!'''
** '''"BOLD", "ITALIC"''' or '''"UNDERLINE"''' create bold, italic or underlined fonts when available in font.
* '''NOTE: SCREEN 0 can only use ONE font on a screen page! Thus a style like underline would affect the entire page.'''
***(valid for QB64 versions prior to 1.000).
* [[_FONTWIDTH]] can only measure MONOSPACE fonts! '''"MONOSPACE" cannot be used on a variable width font.'''
***For '''QB64 1.000 or later''', you must specify the proper file name according to the desired attributes. For example, Courier New is in font '''cour.ttf''' while Courier New Bold is in font '''courbd.ttf''', as shipped with Windows.
** '''"UNICODE"''' loads Unicode fonts such as ''cyberbit.ttf'' which is included in the QB64 downloads.
** '''"DONTBLEND"''' turns off [[_ALPHA]] blending of fonts. This can also be done with the [[_DONTBLEND]] statement.
:* You can pass different font styles using different predefined [[STRING]] variable lists. You '''can''' include an empty style string.
* '''Always check that font handle values are greater than 0 ('''{{Parameter|handle&}} > 0''') before using them or [[ERROR Codes|illegal function errors]] may occur.'''
* '''NOTE: SCREEN 0 can only use ONE font on a screen page. Thus a style like underline would affect the entire page.'''
* Font sizes can be found using the [[_FONTHEIGHT]] function. Font ''size''s can also affect [[SCREEN (statement)|SCREEN]] sizes.
* [[_FONTWIDTH]] can only measure monospaced fonts. '''"MONOSPACE" can be used to load a variable width font as a monospace font.'''
* [[_PRINTWIDTH]] can measure the width of a string of text in '''graphics modes only'''. Use one character to get the font's width.
* [[_PRINTWIDTH]] can measure the width of a string of text in '''graphics modes only'''. Use one character to get the font's width.


Line 22: Line 30:
* Multiple fonts will require multiple font variable handles unless used and freed consecutively.
* Multiple fonts will require multiple font variable handles unless used and freed consecutively.
* Font handles with values greater than 0 that are '''no longer used''' should be freed using [[_FREEFONT]].  
* Font handles with values greater than 0 that are '''no longer used''' should be freed using [[_FREEFONT]].  
* Predefined '''QB64''' font handle numbers can be substituted before freeing a font handle:
* '''Predefined QB64''' font handle numbers can be substituted before freeing a font handle:
**'''_FONT 8 ''' - default font for [[SCREEN (statement)|SCREEN]] 1, 2, 7, 8 or 13
**'''_FONT 8 ''' - default font for [[SCREEN (statement)|SCREEN]] 1, 2, 7, 8 or 13
**'''_FONT 14''' - default font for [[SCREEN (statement)|SCREEN]] 9 or 10
**'''_FONT 14''' - default font for [[SCREEN (statement)|SCREEN]] 9 or 10
**'''_FONT 16''' - default font for [[SCREEN (statement)|SCREEN]] 0 ({{KW|WIDTH}} 80, 25 text only), 11 or 12
**'''_FONT 16''' - default font for [[SCREEN (statement)|SCREEN]] 0 ([[WIDTH]] 80, 25 text only), 11 or 12
**'''_FONT 9, 15''' and '''17''' are the double width versions of 8, 14 and 16 respectively in text '''SCREEN 0 only'''.
**'''_FONT 9, 15''' and '''17''' are the double width versions of 8, 14 and 16 respectively in text '''SCREEN 0 only'''.
* Once the font is changed to a predefined value, the font handle value can be freed using [[_FREEFONT]] for another font type.
* Once the font is changed to a predefined value, the font handle value can be freed using [[_FREEFONT]] for another font type.
* Font handle values of -1 (load failure) '''do not''' need to be freed! '''An [[ERROR Codes|error]] will occur if you try to free invalid handles!'''
* Font handle values of -1 (load failure) '''do not''' need to be freed. '''An [[ERROR Codes|error]] will occur if you try to free invalid handles.'''




<center> '''Font File Specs'''</center>
<center> '''Font File Specs'''</center>
* Windows users should find '''TTF''' font files in the C:\WINDOWS\FONTS folder, but don't depend on unusual ones being there.  
* Windows users should find '''TTF''' font files in the C:\WINDOWS\FONTS folder, but don't depend on unusual ones being there.  
* '''Check the font file name! The name in the "viewer" is NOT necessarily the file's name! Use the name in properties!'''
* '''Check the font file name. The name in the "viewer" is not necessarily the file's name. Use the name in properties (right click a font listed and choose Properties in the contextual menu)'''
* If a program is on a different drive than Windows, [[ENVIRON$]]("SYSTEMROOT") will return the path to the "WINDOWS" folder. Normally "C:\WINDOWS". Then add the "\FONTS\" folder and the font '''.TTF''' filename to the path [[STRING]].
* If a program is on a different drive than Windows, [[ENVIRON$]]("SYSTEMROOT") will return the path to the "WINDOWS" folder. Normally "C:\WINDOWS". Then add the "\FONTS\" folder and the font '''.TTF''' filename to the path [[STRING]].




{{PageExamples}}
''Example 1:'' You need to know that if you are in a text mode (such as SCREEN 0 - the default) then you will only be able to use mono-spaced (fixed width) fonts.
''Example 1:'' You need to know that if you are in a text mode (such as SCREEN 0 - the default) then you will only be able to use mono-spaced (fixed width) fonts.
{{CodeStart}}
{{CodeStart}}
rootpath$ = {{Cl|ENVIRON$}}("SYSTEMROOT")          'normally "C:\WINDOWS"
rootpath$ = {{Cl|ENVIRON$}}("SYSTEMROOT")          'normally "C:\WINDOWS"
fontfile$ = rootpath$ + "\Fonts\cour.ttf"  'TTF file in Windows  
fontfile$ = rootpath$ + "\Fonts\cour.ttf"  'TTF file in Windows  
style$ = "monospace, italic, bold"          'font style is not case sensitive
style$ = "monospace"          'font style is not case sensitive
f& ={{Cl|_LOADFONT}}(fontfile$, 30, style$)
f& ={{Cl|_LOADFONT}}(fontfile$, 30, style$)
{{Cl|_FONT}} f&
{{Cl|_FONT}} f&
Line 50: Line 58:
{{OutputStart}}
{{OutputStart}}


'''''Hello!'''''
Hello!


{{OutputEnd}}
{{OutputEnd}}
Line 61: Line 69:


{{CodeStart}}
{{CodeStart}}
i& ={{Cl|_NEWIMAGE}}(800,600,32)
i& ={{Cl|_NEWIMAGE}}(800,600,32)
{{Cl|SCREEN (statement)|SCREEN}} i&
{{Cl|SCREEN (statement)|SCREEN}} i&
Line 67: Line 74:
f& ={{Cl|_LOADFONT}}("C:\Windows\Fonts\times.ttf", 25)  'normal style
f& ={{Cl|_LOADFONT}}("C:\Windows\Fonts\times.ttf", 25)  'normal style
{{Cl|PRINT}} "Hello!"
{{Cl|PRINT}} "Hello!"
{{CodeEnd}}
{{OutputStart}}Hello!
{{OutputEnd}}
:''Note:'' You can load a fixed width font file without using the "monospace" option and it will be treated as variable width. This can be useful because LOCATE treats the horizontal position as an offset in pixels for variable width fonts.


{{CodeEnd}}
''Example 3:'' Loading a [[Unicode]] font, ''cyberbit.ttf'', which was downloaded with QB64:
{{CodeStart}}{{Cl|SCREEN}} 12


{{OutputStart}}
{{Cl|DECLARE DYNAMIC LIBRARY|DECLARE CUSTOMTYPE LIBRARY}} 'Directory Information using KERNEL32 provided by Dav
    {{Cl|FUNCTION}} GetModuleFileNameA& ({{Cl|BYVAL}} hModule {{Cl|AS}} {{Cl|LONG}}, lpFileName {{Cl|AS}} {{Cl|STRING}}, {{Cl|BYVAL}} nSize {{Cl|AS}} {{Cl|LONG}})
    {{Cl|FUNCTION}} GetModuleFileNameW& ({{Cl|BYVAL}} hModule {{Cl|AS}} {{Cl|LONG}}, lpFileName {{Cl|AS}} {{Cl|STRING}}, {{Cl|BYVAL}} nSize {{Cl|AS}} {{Cl|LONG}})
{{Cl|DECLARE LIBRARY|END DECLARE}}


  Hello!
'=== SHOW CURRENT PROGRAM
FileName$ = {{Cl|SPACE$}}(512)


{{OutputEnd}}
Result = GetModuleFileNameA(0, FileName$, {{Cl|LEN}}(FileName$))
{{Cl|IF...THEN|IF}} Result {{Cl|THEN}} {{Cl|PRINT}} "CURRENT PROGRAM (ASCII): "; {{Cl|LEFT$}}(FileName$, Result)


'load a unicode font
f = {{Cl|_LOADFONT}}("cyberbit.ttf", 24, "UNICODE")
{{Cl|_FONT}} f
Result = GetModuleFileNameW(0, FileName$, {{Cl|LEN}}(FileName$) \ 2)
{{Cl|LOCATE}} 2, 1
{{Cl|PRINT}} QuickCP437toUTF32$("CURRENT PROGRAM (UTF): ") + QuickUTF16toUTF32$({{Cl|LEFT$}}(FileName$, Result * 2))
{{Cl|_FONT}} 16 'restore CP437 font


:''Note:'' You can load a fixed width font file without using the "monospace" option and it will be treated as variable width. This can be useful because LOCATE treats the horizontal position as an offset in pixels for variable width fonts.
{{Cl|FUNCTION}} QuickCP437toUTF32$ (a$)
b$ = {{Cl|STRING$}}({{Cl|LEN}}(a$) * 4, 0)
{{Cl|FOR...NEXT|FOR}} i = 1 {{Cl|TO}} {{Cl|LEN}}(a$)
    {{Cl|ASC}}(b$, i * 4 - 3) = {{Cl|ASC}}(a$, i)
{{Cl|NEXT}}
QuickCP437toUTF32$ = b$
{{Cl|END FUNCTION}}


{{Cl|FUNCTION}} QuickUTF16toUTF32$ (a$)
b$ = {{Cl|STRING$}}({{Cl|LEN}}(a$) * 2, 0)
{{Cl|FOR...NEXT|FOR}} i = 1 {{Cl|TO}} {{Cl|LEN}}(a$) \ 2
    {{Cl|ASC}}(b$, i * 4 - 3) = {{Cl|ASC}}(a$, i * 2 - 1)
    {{Cl|ASC}}(b$, i * 4 - 2) = {{Cl|ASC}}(a$, i * 2)
{{Cl|NEXT}}
QuickUTF16toUTF32$ = b$
{{Cl|END FUNCTION}} '' ''
{{CodeEnd}}




''See also:''
{{PageSeeAlso}}
* [[_FONT]], [[_FONT (function)]]
* [[_FONT]], [[_FONT (function)]]
* [[_FREEFONT]]  
* [[_FREEFONT]]  
Line 87: Line 130:
* [[_PRINTMODE]], [[_PRINTMODE (function)]]
* [[_PRINTMODE]], [[_PRINTMODE (function)]]
* [[_FONTHEIGHT]], [[_FONTWIDTH]]  
* [[_FONTHEIGHT]], [[_FONTWIDTH]]  
* [[Text Using Graphics]] (Demo)
* [[Text Using Graphics]] {{text|(Demo)}}
* [[Windows_Libraries#Font_Dialog_Box|Windows Font Dialog Box]]




{{PageNavigation}}
{{PageNavigation}}

Latest revision as of 13:33, 8 September 2017

The _LOADFONT function loads a TrueType font (.TTF) or an OpenType font (.OTF) file in a specific size and style and returns a LONG font handle.


Syntax

handle& = _LOADFONT(fontFileName$, size%[, "{MONOSPACE|, BOLD|, ITALIC|, UNDERLINE|, UNICODE|, DONTBLEND}"])


Description

  • The assigned LONG font handle& variable return value designates a font style to be used somewhere in a program. Valid handle values are greater than 0 (handle& > 0).
  • fontFileName$ is the filename of a TrueType or OpenType font. Can include the path to the font file. Best practice is to include font files with a program.
  • If no path is specified for fontFileName$ and the font file isn't in the same folder as the resulting binary, QB64 attempts to load from the default C:\Windows\Fonts path.
  • size% is the INTEGER height of the font. If the size is too large or small an error will occur.
  • Optional comma separated style parameter(s) used are literal STRINGs (in quotes) or can be contained in variable(s).
    • "MONOSPACE" loads a font with all characters occupying the same width. Results may be too spaced out for fonts that aren't designed for monospace use.
    • "BOLD", "ITALIC" or "UNDERLINE" create bold, italic or underlined fonts when available in font.
      • (valid for QB64 versions prior to 1.000).
      • For QB64 1.000 or later, you must specify the proper file name according to the desired attributes. For example, Courier New is in font cour.ttf while Courier New Bold is in font courbd.ttf, as shipped with Windows.
    • "UNICODE" loads Unicode fonts such as cyberbit.ttf which is included in the QB64 downloads.
    • "DONTBLEND" turns off _ALPHA blending of fonts. This can also be done with the _DONTBLEND statement.
  • You can pass different font styles using different predefined STRING variable lists. You can include an empty style string.
  • Always check that font handle values are greater than 0 (handle& > 0) before using them or illegal function errors may occur.
  • NOTE: SCREEN 0 can only use ONE font on a screen page. Thus a style like underline would affect the entire page.
  • Font sizes can be found using the _FONTHEIGHT function. Font sizes can also affect SCREEN sizes.
  • _FONTWIDTH can only measure monospaced fonts. "MONOSPACE" can be used to load a variable width font as a monospace font.
  • _PRINTWIDTH can measure the width of a string of text in graphics modes only. Use one character to get the font's width.


Font Handles
  • Multiple fonts will require multiple font variable handles unless used and freed consecutively.
  • Font handles with values greater than 0 that are no longer used should be freed using _FREEFONT.
  • Predefined QB64 font handle numbers can be substituted before freeing a font handle:
    • _FONT 8 - default font for SCREEN 1, 2, 7, 8 or 13
    • _FONT 14 - default font for SCREEN 9 or 10
    • _FONT 16 - default font for SCREEN 0 (WIDTH 80, 25 text only), 11 or 12
    • _FONT 9, 15 and 17 are the double width versions of 8, 14 and 16 respectively in text SCREEN 0 only.
  • Once the font is changed to a predefined value, the font handle value can be freed using _FREEFONT for another font type.
  • Font handle values of -1 (load failure) do not need to be freed. An error will occur if you try to free invalid handles.


Font File Specs
  • Windows users should find TTF font files in the C:\WINDOWS\FONTS folder, but don't depend on unusual ones being there.
  • Check the font file name. The name in the "viewer" is not necessarily the file's name. Use the name in properties (right click a font listed and choose Properties in the contextual menu)
  • If a program is on a different drive than Windows, ENVIRON$("SYSTEMROOT") will return the path to the "WINDOWS" folder. Normally "C:\WINDOWS". Then add the "\FONTS\" folder and the font .TTF filename to the path STRING.


Examples

Example 1: You need to know that if you are in a text mode (such as SCREEN 0 - the default) then you will only be able to use mono-spaced (fixed width) fonts.

rootpath$ = ENVIRON$("SYSTEMROOT") 'normally "C:\WINDOWS" fontfile$ = rootpath$ + "\Fonts\cour.ttf" 'TTF file in Windows style$ = "monospace" 'font style is not case sensitive f& =_LOADFONT(fontfile$, 30, style$) _FONT f& PRINT "Hello!"

Hello!

Note: 30 means each row of text (including vertical spacing) will be exactly 30 pixels high. This may make some program screens larger. If you don't want a style listed just use style$ = "" if using a STRING variable for different calls.


Example 2: In a 32-bit graphics mode you can alpha blend onto the background:

i& =_NEWIMAGE(800,600,32) SCREEN i& COLOR &HC0FFFF00,&H200000FF f& =_LOADFONT("C:\Windows\Fonts\times.ttf", 25) 'normal style PRINT "Hello!"

Hello!


Note: You can load a fixed width font file without using the "monospace" option and it will be treated as variable width. This can be useful because LOCATE treats the horizontal position as an offset in pixels for variable width fonts.


Example 3: Loading a Unicode font, cyberbit.ttf, which was downloaded with QB64:

SCREEN 12 DECLARE CUSTOMTYPE LIBRARY 'Directory Information using KERNEL32 provided by Dav FUNCTION GetModuleFileNameA& (BYVAL hModule AS LONG, lpFileName AS STRING, BYVAL nSize AS LONG) FUNCTION GetModuleFileNameW& (BYVAL hModule AS LONG, lpFileName AS STRING, BYVAL nSize AS LONG) END DECLARE '=== SHOW CURRENT PROGRAM FileName$ = SPACE$(512) Result = GetModuleFileNameA(0, FileName$, LEN(FileName$)) IF Result THEN PRINT "CURRENT PROGRAM (ASCII): "; LEFT$(FileName$, Result) 'load a unicode font f = _LOADFONT("cyberbit.ttf", 24, "UNICODE") _FONT f Result = GetModuleFileNameW(0, FileName$, LEN(FileName$) \ 2) LOCATE 2, 1 PRINT QuickCP437toUTF32$("CURRENT PROGRAM (UTF): ") + QuickUTF16toUTF32$(LEFT$(FileName$, Result * 2)) _FONT 16 'restore CP437 font FUNCTION QuickCP437toUTF32$ (a$) b$ = STRING$(LEN(a$) * 4, 0) FOR i = 1 TO LEN(a$) ASC(b$, i * 4 - 3) = ASC(a$, i) NEXT QuickCP437toUTF32$ = b$ END FUNCTION FUNCTION QuickUTF16toUTF32$ (a$) b$ = STRING$(LEN(a$) * 2, 0) FOR i = 1 TO LEN(a$) \ 2 ASC(b$, i * 4 - 3) = ASC(a$, i * 2 - 1) ASC(b$, i * 4 - 2) = ASC(a$, i * 2) NEXT QuickUTF16toUTF32$ = b$ END FUNCTION


See also



Navigation:
Keyword Reference - Alphabetical
Keyword Reference - By Usage
Main Wiki Page