COW cleanup patch (1583966):

[wxWidgets.git] / docs / latex / wx / font.tex

\section{\class{wxFont}}\label{wxfont}

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 \helpref{wxSystemSettings}{wxsystemsettings}.

\helpref{wxSystemSettings}{wxsystemsettings}

\wxheading{Derived from}

\helpref{wxGDIObject}{wxgdiobject}\\
\helpref{wxObject}{wxobject}

\wxheading{Include files}

<wx/font.h>

\wxheading{Constants}

The possible values for the \arg{family} parameter of \helpref{wxFont
constructor}{wxfontctor} are (the old names are for compatibility only):

\begin{verbatim}
enum wxFontFamily
{
    wxFONTFAMILY_DEFAULT = wxDEFAULT,
    wxFONTFAMILY_DECORATIVE = wxDECORATIVE,
    wxFONTFAMILY_ROMAN = wxROMAN,
    wxFONTFAMILY_SCRIPT = wxSCRIPT,
    wxFONTFAMILY_SWISS = wxSWISS,
    wxFONTFAMILY_MODERN = wxMODERN,
    wxFONTFAMILY_TELETYPE = wxTELETYPE,
    wxFONTFAMILY_MAX
};
\end{verbatim}

The possible values for the \arg{weight} parameter are (the old names
are for compatibility only):

\begin{verbatim}
enum wxFontWeight
{
    wxFONTWEIGHT_NORMAL = wxNORMAL,
    wxFONTWEIGHT_LIGHT = wxLIGHT,
    wxFONTWEIGHT_BOLD = wxBOLD,
    wxFONTWEIGHT_MAX
};
\end{verbatim}

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

\begin{verbatim}
enum
{
    // no special flags: font with default weight/slant/anti-aliasing
    wxFONTFLAG_DEFAULT          = 0,

    // slant flags (default: no slant)
    wxFONTFLAG_ITALIC           = 1 << 0,
    wxFONTFLAG_SLANT            = 1 << 1,

    // weight flags (default: medium)
    wxFONTFLAG_LIGHT            = 1 << 2,
    wxFONTFLAG_BOLD             = 1 << 3,

    // anti-aliasing flag: force on or off (default: the current system default)
    wxFONTFLAG_ANTIALIASED      = 1 << 4,
    wxFONTFLAG_NOT_ANTIALIASED  = 1 << 5,

    // underlined/strikethrough flags (default: no lines)
    wxFONTFLAG_UNDERLINED       = 1 << 6,
    wxFONTFLAG_STRIKETHROUGH    = 1 << 7,
};
\end{verbatim}

The known font encodings are:

\begin{verbatim}
enum wxFontEncoding
{
    wxFONTENCODING_SYSTEM = -1,     // system default
    wxFONTENCODING_DEFAULT,         // current default encoding

    // ISO8859 standard defines a number of single-byte charsets
    wxFONTENCODING_ISO8859_1,       // West European (Latin1)
    wxFONTENCODING_ISO8859_2,       // Central and East European (Latin2)
    wxFONTENCODING_ISO8859_3,       // Esperanto (Latin3)
    wxFONTENCODING_ISO8859_4,       // Baltic (old) (Latin4)
    wxFONTENCODING_ISO8859_5,       // Cyrillic
    wxFONTENCODING_ISO8859_6,       // Arabic
    wxFONTENCODING_ISO8859_7,       // Greek
    wxFONTENCODING_ISO8859_8,       // Hebrew
    wxFONTENCODING_ISO8859_9,       // Turkish (Latin5)
    wxFONTENCODING_ISO8859_10,      // Variation of Latin4 (Latin6)
    wxFONTENCODING_ISO8859_11,      // Thai
    wxFONTENCODING_ISO8859_12,      // doesn't exist currently, but put it
                                    // here anyhow to make all ISO8859
                                    // consecutive numbers
    wxFONTENCODING_ISO8859_13,      // Baltic (Latin7)
    wxFONTENCODING_ISO8859_14,      // Latin8
    wxFONTENCODING_ISO8859_15,      // Latin9 (a.k.a. Latin0, includes euro)
    wxFONTENCODING_ISO8859_MAX,

    // Cyrillic charset soup (see http://czyborra.com/charsets/cyrillic.html)
    wxFONTENCODING_KOI8,            // we don't support any of KOI8 variants
    wxFONTENCODING_ALTERNATIVE,     // same as MS-DOS CP866
    wxFONTENCODING_BULGARIAN,       // used under Linux in Bulgaria

    // what would we do without Microsoft? They have their own encodings
        // for DOS
    wxFONTENCODING_CP437,           // original MS-DOS codepage
    wxFONTENCODING_CP850,           // CP437 merged with Latin1
    wxFONTENCODING_CP852,           // CP437 merged with Latin2
    wxFONTENCODING_CP855,           // another cyrillic encoding
    wxFONTENCODING_CP866,           // and another one
        // and for Windows
    wxFONTENCODING_CP874,           // WinThai
    wxFONTENCODING_CP1250,          // WinLatin2
    wxFONTENCODING_CP1251,          // WinCyrillic
    wxFONTENCODING_CP1252,          // WinLatin1
    wxFONTENCODING_CP1253,          // WinGreek (8859-7)
    wxFONTENCODING_CP1254,          // WinTurkish
    wxFONTENCODING_CP1255,          // WinHebrew
    wxFONTENCODING_CP1256,          // WinArabic
    wxFONTENCODING_CP1257,          // WinBaltic (same as Latin 7)
    wxFONTENCODING_CP12_MAX,

    wxFONTENCODING_UTF7,            // UTF-7 Unicode encoding
    wxFONTENCODING_UTF8,            // UTF-8 Unicode encoding

    wxFONTENCODING_UNICODE,         // Unicode - currently used only by
                                    // wxEncodingConverter class

    wxFONTENCODING_MAX
};
\end{verbatim}

\wxheading{Predefined objects}

Objects:

{\bf wxNullFont}

Pointers:

{\bf wxNORMAL\_FONT\\
wxSMALL\_FONT\\
wxITALIC\_FONT\\
wxSWISS\_FONT}

\wxheading{See also}

\helpref{wxFont overview}{wxfontoverview}, \helpref{wxDC::SetFont}{wxdcsetfont},\rtfsp
\helpref{wxDC::DrawText}{wxdcdrawtext}, \helpref{wxDC::GetTextExtent}{wxdcgettextextent},\rtfsp
\helpref{wxFontDialog}{wxfontdialog}, \helpref{wxSystemSettings}{wxsystemsettings}

\latexignore{\rtfignore{\wxheading{Members}}}


\membersection{wxFont::wxFont}\label{wxfontctor}

\func{}{wxFont}{\void}

Default constructor.

\func{}{wxFont}{\param{const wxFont\&}{ font}}

Copy constructor, uses \helpref{reference counting}{trefcount}.

\func{}{wxFont}{\param{int}{ pointSize}, \param{wxFontFamily}{ family}, \param{int}{ style}, \param{wxFontWeight}{ weight},
 \param{const bool}{ underline = false}, \param{const wxString\& }{faceName = ""},
 \param{wxFontEncoding }{encoding = wxFONTENCODING\_DEFAULT}}

\func{}{wxFont}{\param{const wxSize\&}{ pixelSize}, \param{wxFontFamily}{ family}, \param{int}{ style}, \param{wxFontWeight}{ weight},
 \param{const bool}{ underline = false}, \param{const wxString\& }{faceName = ""},
 \param{wxFontEncoding }{encoding = wxFONTENCODING\_DEFAULT}}

Creates a font object with the specified attributes.

\wxheading{Parameters}

\docparam{pointSize}{Size in points.}

\docparam{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 \helpref{New}{wxfontnew} method must be used.}

\docparam{family}{Font family, a generic way of referring to fonts without specifying actual facename. One of:

\twocolwidtha{5cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{{\bf wxFONTFAMILY\_DEFAULT}}{Chooses a default font.}
\twocolitem{{\bf wxFONTFAMILY\_DECORATIVE}}{A decorative font.}
\twocolitem{{\bf wxFONTFAMILY\_ROMAN}}{A formal, serif font.}
\twocolitem{{\bf wxFONTFAMILY\_SCRIPT}}{A handwriting font.}
\twocolitem{{\bf wxFONTFAMILY\_SWISS}}{A sans-serif font.}
\twocolitem{{\bf wxFONTFAMILY\_MODERN}}{A fixed pitch font.}
\twocolitem{{\bf wxFONTFAMILY\_TELETYPE}}{A teletype font.}
\end{twocollist}}

\docparam{style}{One of {\bf wxFONTSTYLE\_NORMAL}, {\bf wxFONTSTYLE\_SLANT} and {\bf wxFONTSTYLE\_ITALIC}.}

\docparam{weight}{Font weight, sometimes also referred to as font boldness. One of:

\twocolwidtha{5cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{{\bf wxFONTWEIGHT\_NORMAL}}{Normal font.}
\twocolitem{{\bf wxFONTWEIGHT\_LIGHT}}{Light font.}
\twocolitem{{\bf wxFONTWEIGHT\_BOLD}}{Bold font.}
\end{twocollist}}

\docparam{underline}{The value can be true or false. At present this has an effect on Windows and Motif 2.x only.}

\docparam{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.}

\docparam{encoding}{An encoding which may be one of
\twocolwidtha{5cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{{\bf wxFONTENCODING\_SYSTEM}}{Default system encoding.}
\twocolitem{{\bf wxFONTENCODING\_DEFAULT}}{Default application encoding: this
is the encoding set by calls to
\helpref{SetDefaultEncoding}{wxfontsetdefaultencoding} and which may be set to,
say, KOI8 to create all fonts by default with KOI8 encoding. Initially, the
default application encoding is the same as default system encoding.}
\twocolitem{{\bf wxFONTENCODING\_ISO8859\_1...15}}{ISO8859 encodings.}
\twocolitem{{\bf wxFONTENCODING\_KOI8}}{The standard Russian encoding for Internet.}
\twocolitem{{\bf wxFONTENCODING\_CP1250...1252}}{Windows encodings similar to ISO8859 (but not identical).}
\end{twocollist}
If the specified encoding isn't available, no font is created
(see also \helpref{font encoding overview}{wxfontencodingoverview}).
}

\wxheading{Remarks}

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

See also \helpref{wxDC::SetFont}{wxdcsetfont}, \helpref{wxDC::DrawText}{wxdcdrawtext}
and \helpref{wxDC::GetTextExtent}{wxdcgettextextent}.


\membersection{wxFont::\destruct{wxFont}}\label{wxfontdtor}

\func{}{\destruct{wxFont}}{\void}

Destructor.
See \helpref{reference-counted object destruction}{refcountdestruct} for more info.

\wxheading{Remarks}

Although all remaining fonts are deleted when the application exits,
the application should try to clean up all fonts itself. This is because
wxWidgets cannot know if a pointer to the font object is stored in an
application data structure, and there is a risk of double deletion.


\membersection{wxFont::IsFixedWidth}\label{wxfontisfixedwidth}

\constfunc{bool}{IsFixedWidth}{\void}

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


\membersection{wxFont::GetDefaultEncoding}\label{wxfontgetdefaultencoding}

\func{static wxFontEncoding}{GetDefaultEncoding}{\void}

Returns the current application's default encoding.

\wxheading{See also}

\helpref{Font encoding overview}{wxfontencodingoverview},
\helpref{SetDefaultEncoding}{wxfontsetdefaultencoding}


\membersection{wxFont::GetFaceName}\label{wxfontgetfacename}

\constfunc{wxString}{GetFaceName}{\void}

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

\wxheading{See also}

\helpref{wxFont::SetFaceName}{wxfontsetfacename}


\membersection{wxFont::GetFamily}\label{wxfontgetfamily}

\constfunc{wxFontFamily}{GetFamily}{\void}

Gets the font family. See \helpref{wxFont::SetFamily}{wxfontsetfamily} for a list of valid
family identifiers.

\wxheading{See also}

\helpref{wxFont::SetFamily}{wxfontsetfamily}


\membersection{wxFont::GetNativeFontInfoDesc}\label{wxfontgetnativefontinfodesc}

\constfunc{wxString}{GetNativeFontInfoDesc}{\void}

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 wxFont object.

\wxheading{See also}

\helpref{wxFont::SetNativeFontInfo}{wxfontsetnativefontinfo},\helpref{wxFont::GetNativeFontInfoUserDesc}{wxfontgetnativefontinfouserdesc}


\membersection{wxFont::GetNativeFontInfoUserDesc}\label{wxfontgetnativefontinfouserdesc}

\func{wxString}{GetNativeFontInfoUserDesc}{\void}

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 \helpref{SetNativeFontInfoUserDesc}{wxfontsetnativefontinfouserdesc}.

\wxheading{See also}

\helpref{wxFont::GetNativeFontInfoDesc}{wxfontgetnativefontinfodesc}


\membersection{wxFont::GetPointSize}\label{wxfontgetpointsize}

\constfunc{int}{GetPointSize}{\void}

Gets the point size.

\wxheading{See also}

\helpref{wxFont::SetPointSize}{wxfontsetpointsize}


\membersection{wxFont::GetStyle}\label{wxfontgetstyle}

\constfunc{int}{GetStyle}{\void}

Gets the font style. See \helpref{wxFont::wxFont}{wxfontctor} for a list of valid
styles.

\wxheading{See also}

\helpref{wxFont::SetStyle}{wxfontsetstyle}


\membersection{wxFont::GetUnderlined}\label{wxfontgetunderlined}

\constfunc{bool}{GetUnderlined}{\void}

Returns true if the font is underlined, false otherwise.

\wxheading{See also}

\helpref{wxFont::SetUnderlined}{wxfontsetunderlined}


\membersection{wxFont::GetWeight}\label{wxfontgetweight}

\constfunc{wxFontWeight}{GetWeight}{\void}

Gets the font weight. See \helpref{wxFont::wxFont}{wxfontctor} for a list of valid
weight identifiers.

\wxheading{See also}

\helpref{wxFont::SetWeight}{wxfontsetweight}


\membersection{wxFont::New}\label{wxfontnew}

\func{static wxFont *}{New}{\param{int}{ pointSize}, \param{wxFontFamily}{ family}, \param{int}{ style}, \param{wxFontWeight}{ weight},
 \param{const bool}{ underline = false}, \param{const wxString\& }{faceName = ""},
 \param{wxFontEncoding }{encoding = wxFONTENCODING\_DEFAULT}}

\func{static wxFont *}{New}{\param{int}{ pointSize}, \param{wxFontFamily}{ family},
 \param{int}{ flags = \texttt{wxFONTFLAG\_DEFAULT}}, \param{const wxString\& }{faceName = ""},
 \param{wxFontEncoding }{encoding = wxFONTENCODING\_DEFAULT}}

\func{static wxFont *}{New}{\param{const wxSize\&}{ pixelSize}, \param{wxFontFamily}{ family}, \param{int}{ style}, \param{wxFontWeight}{ weight},
 \param{const bool}{ underline = false}, \param{const wxString\& }{faceName = ""},
 \param{wxFontEncoding }{encoding = wxFONTENCODING\_DEFAULT}}

\func{static wxFont *}{New}{\param{const wxSize\&}{ pixelSize}, \param{wxFontFamily}{ family},
 \param{int}{ flags = \texttt{wxFONTFLAG\_DEFAULT}}, \param{const wxString\& }{faceName = ""},
 \param{wxFontEncoding }{encoding = wxFONTENCODING\_DEFAULT}}

These functions take the same parameters as \helpref{wxFont
constructor}{wxfontctor} and return a new font object allocated on the heap.

Using \texttt{New()} is currently the only way to directly create a font with
the given size in pixels on platforms other than wxMSW.


\membersection{wxFont::IsOk}\label{wxfontisok}

\constfunc{bool}{IsOk}{\void}

Returns {\tt true} if this object is a valid font, {\tt false} otherwise.


\membersection{wxFont::SetDefaultEncoding}\label{wxfontsetdefaultencoding}

\func{static void}{SetDefaultEncoding}{\param{wxFontEncoding }{encoding}}

Sets the default font encoding.

\wxheading{See also}

\helpref{Font encoding overview}{wxfontencodingoverview},
\helpref{GetDefaultEncoding}{wxfontgetdefaultencoding}


\membersection{wxFont::SetFaceName}\label{wxfontsetfacename}

\func{bool}{SetFaceName}{\param{const wxString\& }{faceName}}

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

\wxheading{Parameters}

\docparam{faceName}{A valid facename, which should be on the end-user's system.}

\wxheading{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, wxWidgets will first search for the specific face,
and then for a font belonging to the same family.

\wxheading{See also}

\helpref{wxFont::GetFaceName}{wxfontgetfacename}, \helpref{wxFont::SetFamily}{wxfontsetfamily}


\membersection{wxFont::SetFamily}\label{wxfontsetfamily}

\func{void}{SetFamily}{\param{wxFontFamily}{ family}}

Sets the font family.

\wxheading{Parameters}

\docparam{family}{One of:

\twocolwidtha{5cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{{\bf wxFONTFAMILY\_DEFAULT}}{Chooses a default font.}
\twocolitem{{\bf wxFONTFAMILY\_DECORATIVE}}{A decorative font.}
\twocolitem{{\bf wxFONTFAMILY\_ROMAN}}{A formal, serif font.}
\twocolitem{{\bf wxFONTFAMILY\_SCRIPT}}{A handwriting font.}
\twocolitem{{\bf wxFONTFAMILY\_SWISS}}{A sans-serif font.}
\twocolitem{{\bf wxFONTFAMILY\_MODERN}}{A fixed pitch font.}
\twocolitem{{\bf wxFONTFAMILY\_TELETYPE}}{A teletype font.}
\end{twocollist}}

\wxheading{See also}

\helpref{wxFont::GetFamily}{wxfontgetfamily}, \helpref{wxFont::SetFaceName}{wxfontsetfacename}


\membersection{wxFont::SetNativeFontInfo}\label{wxfontsetnativefontinfo}

\func{bool}{SetNativeFontInfo}{\param{const wxString\& }{info}}

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

\wxheading{See also}

\helpref{wxFont::SetNativeFontInfoUserDesc}{wxfontsetnativefontinfouserdesc}


\membersection{wxFont::SetNativeFontInfoUserDesc}\label{wxfontsetnativefontinfouserdesc}

\func{bool}{SetNativeFontInfoUserDesc}{\param{const wxString\& }{info}}

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

\twocolwidtha{15cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{Generic syntax}{Example}
\twocolitem{on {\bf wxGTK2}: {\tt $[FACE-NAME]$ $[bold]$ $[oblique|italic]$ $[POINTSIZE]$}}{Monospace bold 10}
\twocolitem{on {\bf wxMSW}: {\tt $[light|bold]$ $[italic]$ $[FACE-NAME]$ $[POINTSIZE]$ $[ENCODING]$}}{Tahoma 10 WINDOWS-1252}
\twocolitem{on {\bf wxMac}: FIXME}{FIXME}
\end{twocollist}

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

\wxheading{See also}

\helpref{wxFont::SetNativeFontInfo}{wxfontsetnativefontinfo}



\membersection{wxFont::SetPointSize}\label{wxfontsetpointsize}

\func{void}{SetPointSize}{\param{int}{ pointSize}}

Sets the point size.

\wxheading{Parameters}

\docparam{pointSize}{Size in points.}

\wxheading{See also}

\helpref{wxFont::GetPointSize}{wxfontgetpointsize}


\membersection{wxFont::SetStyle}\label{wxfontsetstyle}

\func{void}{SetStyle}{\param{int}{ style}}

Sets the font style.

\wxheading{Parameters}

\docparam{style}{One of {\bf wxFONTSTYLE\_NORMAL}, {\bf wxFONTSTYLE\_SLANT} and {\bf wxFONTSTYLE\_ITALIC}.}

\wxheading{See also}

\helpref{wxFont::GetStyle}{wxfontgetstyle}


\membersection{wxFont::SetUnderlined}\label{wxfontsetunderlined}

\func{void}{SetUnderlined}{\param{const bool}{ underlined}}

Sets underlining.

\wxheading{Parameters}

\docparam{underlining}{true to underline, false otherwise.}

\wxheading{See also}

\helpref{wxFont::GetUnderlined}{wxfontgetunderlined}


\membersection{wxFont::SetWeight}\label{wxfontsetweight}

\func{void}{SetWeight}{\param{wxFontWeight}{ weight}}

Sets the font weight.

\wxheading{Parameters}

\docparam{weight}{One of:

\twocolwidtha{5cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{{\bf wxFONTWEIGHT\_NORMAL}}{Normal font.}
\twocolitem{{\bf wxFONTWEIGHT\_LIGHT}}{Light font.}
\twocolitem{{\bf wxFONTWEIGHT\_BOLD}}{Bold font.}
\end{twocollist}}

\wxheading{See also}

\helpref{wxFont::GetWeight}{wxfontgetweight}


\membersection{wxFont::operator $=$}\label{wxfontassignment}

\func{wxFont\&}{operator $=$}{\param{const wxFont\& }{font}}

Assignment operator, using \helpref{reference counting}{trefcount}.


\membersection{wxFont::operator $==$}\label{wxfontequals}

\func{bool}{operator $==$}{\param{const wxFont\& }{font}}

Equality operator.
See \helpref{reference-counted object comparison}{refcountequality} for more info.


\membersection{wxFont::operator $!=$}\label{wxfontnotequals}

\func{bool}{operator $!=$}{\param{const wxFont\& }{font}}

Inequality operator.
See \helpref{reference-counted object comparison}{refcountequality} for more info.