X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/544229d1069a20ca4c81fac6059aa4d92d8559ef..134198f1b773199b5506c302bf9510831d0319f5:/docs/latex/wx/font.tex diff --git a/docs/latex/wx/font.tex b/docs/latex/wx/font.tex index 8986f71f8e..f456343766 100644 --- a/docs/latex/wx/font.tex +++ b/docs/latex/wx/font.tex @@ -4,6 +4,13 @@ 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. +This class uses \helpref{reference counting and copy-on-write}{trefcount} +internally so that assignments between two instances of this class are very +cheap. You can therefore use actual objects instead of pointers without +efficiency problems. If an instance of this class is changed it will create +its own data internally so that other instances, which previously shared the +data using the reference counting, are not affected. + You can retrieve the current system font settings with \helpref{wxSystemSettings}{wxsystemsettings}. \helpref{wxSystemSettings}{wxsystemsettings} @@ -17,10 +24,14 @@ You can retrieve the current system font settings with \helpref{wxSystemSettings +\wxheading{Library} + +\helpref{wxCore}{librarieslist} + \wxheading{Constants} The possible values for the \arg{family} parameter of \helpref{wxFont -constructor}{wxfontconstr} are (the old names are for compatibility only): +constructor}{wxfontctor} are (the old names are for compatibility only): \begin{verbatim} enum wxFontFamily @@ -36,6 +47,19 @@ enum wxFontFamily }; \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} @@ -146,17 +170,21 @@ wxSWISS\_FONT} \latexignore{\rtfignore{\wxheading{Members}}} -\membersection{wxFont::wxFont}\label{wxfontconstr} +\membersection{wxFont::wxFont}\label{wxfontctor} \func{}{wxFont}{\void} Default constructor. -\func{}{wxFont}{\param{int}{ pointSize}, \param{wxFontFamily}{ family}, \param{int}{ style}, \param{int}{ weight}, +\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{int}{ weight}, +\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}} @@ -175,29 +203,37 @@ the static \helpref{New}{wxfontnew} method must be used.} \twocolwidtha{5cm} \begin{twocollist}\itemsep=0pt -\twocolitem{{\bf wxDEFAULT}}{Chooses a default font.} -\twocolitem{{\bf wxDECORATIVE}}{A decorative font.} -\twocolitem{{\bf wxROMAN}}{A formal, serif font.} -\twocolitem{{\bf wxSCRIPT}}{A handwriting font.} -\twocolitem{{\bf wxSWISS}}{A sans-serif font.} -\twocolitem{{\bf wxMODERN}}{A fixed pitch font.} +\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 wxNORMAL}, {\bf wxSLANT} and {\bf wxITALIC}.} +\docparam{style}{One of {\bf wxFONTSTYLE\_NORMAL}, {\bf wxFONTSTYLE\_SLANT} and {\bf wxFONTSTYLE\_ITALIC}.} -\docparam{weight}{One of {\bf wxNORMAL}, {\bf wxLIGHT} and {\bf wxBOLD}.} +\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 the empty string, -a default typeface will chosen based on the family.} +\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 +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.} @@ -218,17 +254,15 @@ See also \helpref{wxDC::SetFont}{wxdcsetfont}, \helpref{wxDC::DrawText}{wxdcdraw and \helpref{wxDC::GetTextExtent}{wxdcgettextextent}. -\membersection{wxFont::\destruct{wxFont}} +\membersection{wxFont::\destruct{wxFont}}\label{wxfontdtor} \func{}{\destruct{wxFont}}{\void} Destructor. +See \helpref{reference-counted object destruction}{refcountdestruct} for more info. \wxheading{Remarks} -The destructor may not delete the underlying font object of the native windowing -system, since wxFont uses a reference counting system for efficiency. - 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 @@ -239,7 +273,7 @@ application data structure, and there is a risk of double deletion. \constfunc{bool}{IsFixedWidth}{\void} -Returns {\tt true} if the font is a fixed width (or monospaced) font, +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. @@ -251,7 +285,7 @@ Returns the current application's default encoding. \wxheading{See also} -\helpref{Font encoding overview}{wxfontencodingoverview}, +\helpref{Font encoding overview}{wxfontencodingoverview}, \helpref{SetDefaultEncoding}{wxfontsetdefaultencoding} @@ -269,9 +303,9 @@ typeface information. \membersection{wxFont::GetFamily}\label{wxfontgetfamily} -\constfunc{int}{GetFamily}{\void} +\constfunc{wxFontFamily}{GetFamily}{\void} -Gets the font family. See \helpref{wxFont::wxFont}{wxfontconstr} for a list of valid +Gets the font family. See \helpref{wxFont::SetFamily}{wxfontsetfamily} for a list of valid family identifiers. \wxheading{See also} @@ -283,12 +317,26 @@ family identifiers. \constfunc{wxString}{GetNativeFontInfoDesc}{\void} -Returns the platform-dependent string completely describing this font or an -empty string if the font wasn't constructed using the native font description. +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::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} @@ -306,7 +354,7 @@ Gets the point size. \constfunc{int}{GetStyle}{\void} -Gets the font style. See \helpref{wxFont::wxFont}{wxfontconstr} for a list of valid +Gets the font style. See \helpref{wxFont::wxFont}{wxfontctor} for a list of valid styles. \wxheading{See also} @@ -327,9 +375,9 @@ Returns true if the font is underlined, false otherwise. \membersection{wxFont::GetWeight}\label{wxfontgetweight} -\constfunc{int}{GetWeight}{\void} +\constfunc{wxFontWeight}{GetWeight}{\void} -Gets the font weight. See \helpref{wxFont::wxFont}{wxfontconstr} for a list of valid +Gets the font weight. See \helpref{wxFont::wxFont}{wxfontctor} for a list of valid weight identifiers. \wxheading{See also} @@ -339,32 +387,32 @@ weight identifiers. \membersection{wxFont::New}\label{wxfontnew} -\func{static wxFont *}{New}{\param{int}{ pointSize}, \param{wxFontFamily}{ family}, \param{int}{ style}, \param{int}{ weight}, +\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}, +\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{int}{ weight}, +\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}, +\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}{wxfontconstr} and return a new font object allocated on the heap. +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::Ok}\label{wxfontok} +\membersection{wxFont::IsOk}\label{wxfontisok} -\constfunc{bool}{Ok}{\void} +\constfunc{bool}{IsOk}{\void} Returns {\tt true} if this object is a valid font, {\tt false} otherwise. @@ -377,15 +425,16 @@ Sets the default font encoding. \wxheading{See also} -\helpref{Font encoding overview}{wxfontencodingoverview}, +\helpref{Font encoding overview}{wxfontencodingoverview}, \helpref{GetDefaultEncoding}{wxfontgetdefaultencoding} \membersection{wxFont::SetFaceName}\label{wxfontsetfacename} -\func{void}{SetFaceName}{\param{const wxString\& }{faceName}} +\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} @@ -405,7 +454,7 @@ and then for a font belonging to the same family. \membersection{wxFont::SetFamily}\label{wxfontsetfamily} -\func{void}{SetFamily}{\param{int}{ family}} +\func{void}{SetFamily}{\param{wxFontFamily}{ family}} Sets the font family. @@ -415,12 +464,13 @@ Sets the font family. \twocolwidtha{5cm} \begin{twocollist}\itemsep=0pt -\twocolitem{{\bf wxDEFAULT}}{Chooses a default font.} -\twocolitem{{\bf wxDECORATIVE}}{A decorative font.} -\twocolitem{{\bf wxROMAN}}{A formal, serif font.} -\twocolitem{{\bf wxSCRIPT}}{A handwriting font.} -\twocolitem{{\bf wxSWISS}}{A sans-serif font.} -\twocolitem{{\bf wxMODERN}}{A fixed pitch font.} +\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} @@ -430,12 +480,44 @@ Sets the font family. \membersection{wxFont::SetNativeFontInfo}\label{wxfontsetnativefontinfo} -\func{void}{SetNativeFontInfo}{\param{const wxString\& }{info}} +\func{bool}{SetNativeFontInfo}{\param{const wxString\& }{info}} -Creates the font corresponding to the given native font description string -which must have been previously returned by +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. +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} @@ -461,7 +543,7 @@ Sets the font style. \wxheading{Parameters} -\docparam{style}{One of {\bf wxNORMAL}, {\bf wxSLANT} and {\bf wxITALIC}.} +\docparam{style}{One of {\bf wxFONTSTYLE\_NORMAL}, {\bf wxFONTSTYLE\_SLANT} and {\bf wxFONTSTYLE\_ITALIC}.} \wxheading{See also} @@ -485,13 +567,20 @@ Sets underlining. \membersection{wxFont::SetWeight}\label{wxfontsetweight} -\func{void}{SetWeight}{\param{int}{ weight}} +\func{void}{SetWeight}{\param{wxFontWeight}{ weight}} Sets the font weight. \wxheading{Parameters} -\docparam{weight}{One of {\bf wxNORMAL}, {\bf wxLIGHT} and {\bf wxBOLD}.} +\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} @@ -502,24 +591,21 @@ Sets the font weight. \func{wxFont\&}{operator $=$}{\param{const wxFont\& }{font}} -Assignment operator, using reference counting. Returns a reference -to `this'. +Assignment operator, using \helpref{reference counting}{trefcount}. \membersection{wxFont::operator $==$}\label{wxfontequals} \func{bool}{operator $==$}{\param{const wxFont\& }{font}} -Equality operator. Two fonts are equal if they contain pointers -to the same underlying font data. It does not compare each attribute, -so two independently-created fonts using the same parameters will -fail the test. +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. Two fonts are not equal if they contain pointers -to different underlying font data. It does not compare each attribute. +Inequality operator. +See \helpref{reference-counted object comparison}{refcountequality} for more info.