wxRuby Documentation Home

# Wx::Font

A font is an object which determines the appearance of text. Fonts are
used for drawing text to a device context, and setting the appearance of
a window’s text. You can retrieve the current system font settings with
SystemSettings.

SystemSettings

Note that because this class wraps a platform-specific GUI resource, you
shouldn’t create instances of it until the app is running; ie until
after you have called App#main_loop or App.run.

## Derived from

GDIObject

Object

## Constants

The possible constant values for the family parameter of Font
constructor are (the old names are for compatibility only):

FONTFAMILY_DEFAULT = DEFAULT, FONTFAMILY_DECORATIVE = DECORATIVE, FONTFAMILY_ROMAN = ROMAN, FONTFAMILY_SCRIPT = SCRIPT, FONTFAMILY_SWISS = SWISS, FONTFAMILY_MODERN = MODERN, FONTFAMILY_TELETYPE = TELETYPE, FONTFAMILY_MAX

The possible values for the weight parameter are (the old names
are for compatibility only):

FONTWEIGHT_NORMAL = NORMAL, FONTWEIGHT_LIGHT = LIGHT, FONTWEIGHT_BOLD = BOLD, FONTWEIGHT_MAX

The font flags which can be used during the font creation are:

1. no special flags: font with default weight/slant/anti-aliasing
   FONTFLAG_DEFAULT = 0,

1. slant flags (default: no slant)
   FONTFLAG_ITALIC = 1 << 0,
   FONTFLAG_SLANT = 1 << 1,

1. weight flags (default: medium)
   FONTFLAG_LIGHT = 1 << 2,
   FONTFLAG_BOLD = 1 << 3,

1. anti-aliasing flag: force on or off (default: the current system default)
   FONTFLAG_ANTIALIASED = 1 << 4,
   FONTFLAG_NOT_ANTIALIASED = 1 << 5,

1. underlined/strikethrough flags (default: no lines)
   FONTFLAG_UNDERLINED = 1 << 6,
   FONTFLAG_STRIKETHROUGH = 1 << 7,

The known font encodings are:

FONTENCODING_SYSTEM = -1, // system default FONTENCODING_DEFAULT, // current default encoding // ISO8859 standard defines a number of single-byte charsets FONTENCODING_ISO8859_1, // West European (Latin1) FONTENCODING_ISO8859_2, // Central and East European (Latin2) FONTENCODING_ISO8859_3, // Esperanto (Latin3) FONTENCODING_ISO8859_4, // Baltic (old) (Latin4) FONTENCODING_ISO8859_5, // Cyrillic FONTENCODING_ISO8859_6, // Arabic FONTENCODING_ISO8859_7, // Greek FONTENCODING_ISO8859_8, // Hebrew FONTENCODING_ISO8859_9, // Turkish (Latin5) FONTENCODING_ISO8859_10, // Variation of Latin4 (Latin6) FONTENCODING_ISO8859_11, // Thai FONTENCODING_ISO8859_12, // doesn’t exist currently, but put it // here anyhow to make all ISO8859 // consecutive numbers FONTENCODING_ISO8859_13, // Baltic (Latin7) FONTENCODING_ISO8859_14, // Latin8 FONTENCODING_ISO8859_15, // Latin9 (a.k.a. Latin0, includes euro) FONTENCODING_ISO8859_MAX, // Cyrillic charset soup (see http://czyborra.com/charsets/cyrillic.html) FONTENCODING_KOI8, // we don’t support any of KOI8 variants FONTENCODING_ALTERNATIVE, // same as MS-DOS CP866 FONTENCODING_BULGARIAN, // used under Linux in Bulgaria // what would we do without Microsoft? They have their own encodings // for DOS FONTENCODING_CP437, // original MS-DOS codepage FONTENCODING_CP850, // CP437 merged with Latin1 FONTENCODING_CP852, // CP437 merged with Latin2 FONTENCODING_CP855, // another cyrillic encoding FONTENCODING_CP866, // and another one // and for Windows FONTENCODING_CP874, // WinThai FONTENCODING_CP1250, // WinLatin2 FONTENCODING_CP1251, // WinCyrillic FONTENCODING_CP1252, // WinLatin1 FONTENCODING_CP1253, // WinGreek (8859-7) FONTENCODING_CP1254, // WinTurkish FONTENCODING_CP1255, // WinHebrew FONTENCODING_CP1256, // WinArabic FONTENCODING_CP1257, // WinBaltic (same as Latin 7) FONTENCODING_CP12_MAX, FONTENCODING_UTF7, // UTF-7 Unicode encoding FONTENCODING_UTF8, // UTF-8 Unicode encoding FONTENCODING_UNICODE, // Unicode – currently used only by // EncodingConverter class FONTENCODING_MAX

## Predefined font constants

Note that with the exception of `WX::NULL_FONT`, these are not defined
until the App’s main loop has begun.

- `Wx::NULL_FONT`
- `Wx::NORMAL_FONT`
- `Wx::SMALL_FONT`
- `Wx::ITALIC_FONT`
- `Wx::SWISS_FONT`

## See also

Font overview, DC#set_font, DC#draw_text, DC#get_text_extent, FontDialog, SystemSettings

## Methods

### Class Methods

- Font#get_default_encoding
- Font#get_default_encoding_name
- Font.new

### Instance Methods

- Font#is_fixed_width

- Font#get_face_name
- Font#get_family
- Font#get_native_font_info_desc
- Font#get_native_font_info_user_desc
- Font#get_point_size
- Font#get_style
- Font#get_underlined
- Font#get_weight
- Font#new
- Font#is_ok
- Font#set_default_encoding
- Font#set_face_name
- Font#set_family
- Font#set_native_font_info
- Font#set_native_font_info_user_desc
- Font#set_point_size
- Font#set_style
- Font#set_underlined
- Font#set_weight

## Class Methods

### Font.get_default_encoding

Integer get_default_encoding()

Returns an integer constant identifying the current application’s
default encoding. This is set by the OS, and may be changed by using
set_default_encoding

#### See also

get_default_encoding_name

### Font.get_default_encoding_name

String get_default_encoding_name()

Returns the name of the current application’s default encoding. This is
returned as a string suitable for use with Ruby’s ‘iconv’ library.

#### See also

Font encoding overview,

### Font.new

Font.new(%(arg-type)Font% font)

Copy constructor, uses reference counting.

Font.new(%(arg-type)Integer% pointSize, FontFamily family, Integer style, FontWeight weight, Boolean underline = false, String faceName = "", FontEncoding encoding = FONTENCODING_DEFAULT) Font.new(%(arg-type)Size% pixelSize, FontFamily family, Integer style, FontWeight weight, Boolean underline = false, String faceName = "", FontEncoding encoding = FONTENCODING_DEFAULT)

Creates a font object with the specified attributes.

#### Parameters

- pointSize Size in points.
- pixelSize Size in pixels: this is directly supported only under MSW
  currently where this constructor can be used directly, under other platforms a
  font with the closest size to the given one is found using binary search and
  the static New method must be used.
- family Font family, a generic way of referring to fonts without specifying actual facename. One of:

FONTFAMILY_DEFAULT | Chooses a default font.
FONTFAMILY_DECORATIVE | A decorative font.
FONTFAMILY_ROMAN | A formal, serif font.
FONTFAMILY_SCRIPT | A handwriting font.
FONTFAMILY_SWISS | A sans-serif font.
FONTFAMILY_MODERN | A fixed pitch font.
FONTFAMILY_TELETYPE | A teletype font.

- style One of FONTSTYLE_NORMAL, FONTSTYLE_SLANT and FONTSTYLE_ITALIC.
- weight Font weight, sometimes also referred to as font boldness. One of:

FONTWEIGHT_NORMAL | Normal font.
FONTWEIGHT_LIGHT | Light font.
FONTWEIGHT_BOLD | Bold font.

- underline The value can be true or false. At present this has an effect on Windows and Motif 2.x only.
- faceName An optional string specifying the actual typeface to be used. If it is an empty string,
  a default typeface will be chosen based on the family.
- encoding An encoding which may be one of

FONTENCODING_SYSTEM | Default system encoding.
FONTENCODING_DEFAULT | Default application encoding: thisis the encoding set by calls to"set_default_encoding":#Font_setdefaultencoding and which may be set to,say, KOI8 to create all fonts by default with KOI8 encoding. Initially, thedefault application encoding is the same as default system encoding.
FONTENCODING_ISO8859_1…15 | ISO8859 encodings.
FONTENCODING_KOI8 | The standard Russian encoding for Internet.
FONTENCODING_CP1250…1252 | Windows encodings similar to ISO8859 (but not identical).

If the specified encoding isn’t available, no font is created
(see also font encoding overview).

#### Remarks

If the desired font does not exist, the closest match will be chosen.
Under Windows, only scalable TrueType fonts are used.

See also DC#set_font, DC#draw_text
and DC#get_text_extent.

### Font#set_default_encoding

set_default_encoding(%(arg-type)FontEncoding% encoding)

Sets the default font encoding, passing a valid `Wx::FONTENCODING_XX` constant.

#### See also

Font encoding overview,
get_default_encoding

### Font#set_default_encoding_name

set_default_encoding(%(arg-type)FontEncoding% encoding)

Sets the default font encoding, passing an encoding name.

#### See also

Font encoding overview,
get_default_encoding

## Instance Methods

### Font#is_fixed_width

Boolean is_fixed_width()

Returns `true` if the font is a fixed width (or monospaced) font,
`false` if it is a proportional one or font is invalid.

### Font#get_face_name

String get_face_name()

Returns the typeface name associated with the font, or the empty string if there is no
typeface information.

#### See also

Font#set_face_name

### Font#get_family

FontFamily get_family()

Gets the font family. See Font#set_family for a list of valid
family identifiers.

#### See also

Font#set_family

### Font#get_native_font_info_desc

String get_native_font_info_desc()

Returns the platform-dependent string completely describing this font.
Returned string is always non-empty.
Note that the returned string is not meant to be shown or edited by the user: a typical
use of this function is for serializing in string-form a Font object.

#### See also

Font#set_native_font_info,Font#get_native_font_info_user_desc

### Font#get_native_font_info_user_desc

String get_native_font_info_user_desc()

Returns a user-friendly string for this font object. Returned string is always non-empty.
Some examples of the formats of returned strings (which are platform-dependent) are in set_native_font_info_user_desc.

#### See also

Font#get_native_font_info_desc

### Font#get_point_size

Integer get_point_size()

Gets the point size.

#### See also

Font#set_point_size

### Font#get_style

Integer get_style()

Gets the font style. See Font.new for a list of valid
styles.

#### See also

Font#set_style

### Font#get_underlined

Boolean get_underlined()

Returns true if the font is underlined, false otherwise.

#### See also

Font#set_underlined

### Font#get_weight

FontWeight get_weight()

Gets the font weight. See Font.new for a list of valid
weight identifiers.

#### See also

Font#set_weight

### Font#new

Font new(%(arg-type)Integer% pointSize, FontFamily family, Integer style, FontWeight weight, Boolean underline = false, String faceName = "", FontEncoding encoding = FONTENCODING_DEFAULT) Font new(%(arg-type)Integer% pointSize, FontFamily family, Integer flags = `FONTFLAG_DEFAULT`, String faceName = "", FontEncoding encoding = FONTENCODING_DEFAULT) Font new(%(arg-type)Size% pixelSize, FontFamily family, Integer style, FontWeight weight, Boolean underline = false, String faceName = "", FontEncoding encoding = FONTENCODING_DEFAULT) Font new(%(arg-type)Size% pixelSize, FontFamily family, Integer flags = `FONTFLAG_DEFAULT`, String faceName = "", FontEncoding encoding = FONTENCODING_DEFAULT)

These functions take the same parameters as Font
constructor and return a new font object allocated on the heap.

Using `New()` is currently the only way to directly create a font with
the given size in pixels on platforms other than MSW.

### Font#is_ok

Boolean is_ok()

Returns `true` if this object is a valid font, `false` otherwise.

### Font#set_face_name

Boolean set_face_name(%(arg-type)String% faceName)

Sets the facename for the font.
Returns if the given face name exists; otherwise.

#### Parameters

- faceName A valid facename, which should be on the end-user’s system.

#### Remarks

To avoid portability problems, don’t rely on a specific face, but specify the font family
instead or as well. A suitable font will be found on the end-user’s system. If both the
family and the facename are specified, Widgets will first search for the specific face,
and then for a font belonging to the same family.

#### See also

Font#get_face_name, Font#set_family

### Font#set_family

set_family(%(arg-type)FontFamily% family)

Sets the font family.

#### Parameters

- family One of:

FONTFAMILY_DEFAULT | Chooses a default font.
FONTFAMILY_DECORATIVE | A decorative font.
FONTFAMILY_ROMAN | A formal, serif font.
FONTFAMILY_SCRIPT | A handwriting font.
FONTFAMILY_SWISS | A sans-serif font.
FONTFAMILY_MODERN | A fixed pitch font.
FONTFAMILY_TELETYPE | A teletype font.

#### See also

Font#get_family, Font#set_face_name

### Font#set_native_font_info

Boolean set_native_font_info(%(arg-type)String% info)

Creates the font corresponding to the given native font description string and returns if
the creation was successful.
which must have been previously returned by
get_native_font_info_desc. If the string is
invalid, font is unchanged. This function is typically used for de-serializing a Font
object previously saved in a string-form.

#### See also

Font#set_native_font_info_user_desc

### Font#set_native_font_info_user_desc

Boolean set_native_font_info_user_desc(%(arg-type)String% info)

Creates the font corresponding to the given native font description string and returns if
the creation was successful.
Unlike set_native_font_info, this function accepts
strings which are user-friendly.
Examples of accepted string formats are:

Generic syntax | Example
on | GTK2: @$[FACE-NAME]$ $[bold]$ $[oblique | italic]$ $[POINTSIZE]$@Monospace bold 10
on | MSW: @$[light | bold]$ $[italic]$ $[FACE-NAME]$ $[POINTSIZE]$ $[ENCODING]$@Tahoma 10 WINDOWS-1252
on | Mac: FIXMEFIXME

For more detailed information about the allowed syntaxes you can look at the documentation of the native API used for font-rendering (e.g. pango_font_description_from_stringhttp://developer.gnome.org/doc/API/2.0/pango/pango-Fonts.html\#pango-font-description-from-string).

#### See also

Font#set_native_font_info

### Font#set_point_size

set_point_size(%(arg-type)Integer% pointSize)

Sets the point size.

#### Parameters

- pointSize Size in points.

#### See also

Font#get_point_size

### Font#set_style

set_style(%(arg-type)Integer% style)

Sets the font style.

#### Parameters

- style One of FONTSTYLE_NORMAL, FONTSTYLE_SLANT and FONTSTYLE_ITALIC.

#### See also

Font#get_style

### Font#set_underlined

set_underlined(%(arg-type)Boolean% underlined)

Sets underlining.

#### Parameters

- underlining true to underline, false otherwise.

#### See also

Font#get_underlined

### Font#set_weight

set_weight(%(arg-type)FontWeight% weight)

Sets the font weight.

#### Parameters

- weight One of:

FONTWEIGHT_NORMAL | Normal font.
FONTWEIGHT_LIGHT | Light font.
FONTWEIGHT_BOLD | Bold font.

#### See also

Font#get_weight

[This page automatically generated from the Textile source at 2023-06-09 00:45:36 +0000]