| 1 | ///////////////////////////////////////////////////////////////////////////// |
| 2 | // Name: font.h |
| 3 | // Purpose: topic overview |
| 4 | // Author: wxWidgets team |
| 5 | // RCS-ID: $Id$ |
| 6 | // Licence: wxWindows licence |
| 7 | ///////////////////////////////////////////////////////////////////////////// |
| 8 | |
| 9 | /** |
| 10 | |
| 11 | @page overview_font wxFont Overview |
| 12 | |
| 13 | @tableofcontents |
| 14 | |
| 15 | A font is an object which determines the appearance of text, primarily when |
| 16 | drawing text to a window or device context. A font is determined by the |
| 17 | following parameters (not all of them have to be specified, of course): |
| 18 | |
| 19 | @beginDefList |
| 20 | @itemdef{Point size, This is the standard way of referring to text size.} |
| 21 | @itemdef{Family, |
| 22 | Supported families are: |
| 23 | @b wxDEFAULT, @b wxDECORATIVE, @b wxROMAN, @b wxSCRIPT, @b wxSWISS, @b wxMODERN. |
| 24 | @b wxMODERN is a fixed pitch font; the others are either fixed or variable pitch.} |
| 25 | @itemdef{Style, The value can be @b wxNORMAL, @b wxSLANT or @b wxITALIC.} |
| 26 | @itemdef{Weight, The value can be @b wxNORMAL, @b wxLIGHT or @b wxBOLD.} |
| 27 | @itemdef{Underlining, The value can be @true or @false.} |
| 28 | @itemdef{Face name, |
| 29 | An optional string specifying the actual typeface to be used. If @NULL, |
| 30 | a default typeface will chosen based on the family.} |
| 31 | @itemdef{Encoding, |
| 32 | The font encoding (see @b wxFONTENCODING_XXX |
| 33 | constants and the @ref overview_fontencoding for more details)} |
| 34 | @endDefList |
| 35 | |
| 36 | Specifying a family, rather than a specific typeface name, ensures a degree of |
| 37 | portability across platforms because a suitable font will be chosen for the |
| 38 | given font family, however it doesn't allow to choose a font precisely as the |
| 39 | parameters above don't suffice, in general, to identify all the available fonts |
| 40 | and this is where using the native font descriptions may be helpful - see |
| 41 | below. |
| 42 | |
| 43 | Under Windows, the face name can be one of the installed fonts on the user's |
| 44 | system. Since the choice of fonts differs from system to system, either choose |
| 45 | standard Windows fonts, or if allowing the user to specify a face name, store |
| 46 | the family name with any file that might be transported to a different Windows |
| 47 | machine or other platform. |
| 48 | |
| 49 | @see wxFont, wxFontDialog |
| 50 | |
| 51 | @note There is currently a difference between the appearance of fonts on the |
| 52 | two platforms, if the mapping mode is anything other than wxMM_TEXT. |
| 53 | Under X, font size is always specified in points. Under MS Windows, the |
| 54 | unit for text is points but the text is scaled according to the current |
| 55 | mapping mode. However, user scaling on a device context will also scale |
| 56 | fonts under both environments. |
| 57 | |
| 58 | |
| 59 | |
| 60 | @section overview_font_nativeinfo Native Font Information |
| 61 | |
| 62 | An alternative way of choosing fonts is to use the native font description. |
| 63 | This is the only acceptable solution if the user is allowed to choose the font |
| 64 | using the wxFontDialog because the selected font cannot |
| 65 | be described using only the family name and so, if only family name is stored |
| 66 | permanently, the user would almost surely see a different font in the program |
| 67 | later. |
| 68 | |
| 69 | Instead, you should store the value returned by wxFont::GetNativeFontInfoDesc and pass |
| 70 | it to wxFont::SetNativeFontInfo later to recreate exactly the same font. |
| 71 | |
| 72 | Note that the contents of this string depends on the platform and shouldn't be |
| 73 | used for any other purpose (in particular, it is not meant to be shown to the |
| 74 | user). Also please note that although the native font information is currently |
| 75 | implemented for Windows and Unix (GTK+ and Motif) ports only, all the methods |
| 76 | are available for all the ports and should be used to make your program work |
| 77 | correctly when they are implemented later. |
| 78 | |
| 79 | */ |