removed @NULL,@true,@false tags from the function prototypes; fixed * and & displacing in the prototypes; changed @param as discussed on wx-dev; use @see instead of @sa; better indentation for @returns,@remarks,@see paragraphs; other misc fixes

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52407 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
2008-03-09 12:33:59 +00:00
parent 0aaf0255e4
commit 4cc4bfafe5
256 changed files with 8880 additions and 10701 deletions
--- a/interface/font.h
+++ b/interface/font.h
@@ -41,7 +41,7 @@
    wxSWISS_FONT

    @seealso
-    @ref overview_wxfontoverview "wxFont overview", wxDC::SetFont, wxDC::DrawText,
+    @ref overview_wxfontoverview, wxDC::SetFont, wxDC::DrawText,
    wxDC::GetTextExtent, wxFontDialog, wxSystemSettings
 */
 class wxFont : public wxGDIObject
@@ -52,134 +52,226 @@ public:
        Creates a font object with the specified attributes.
        
        @param pointSize
-        Size in points.
-        
+            Size in points.
        @param 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.
-        
+            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.
        @param family
-        Font family, a generic way of referring to fonts without specifying actual
+            Font family, a generic way of referring to fonts without specifying actual
        facename. One of:
        
        
-        wxFONTFAMILY_DEFAULT
        
        
-        Chooses a default font.
-        
-        wxFONTFAMILY_DECORATIVE
        
        
-        A decorative font.
        
-        wxFONTFAMILY_ROMAN
+            wxFONTFAMILY_DEFAULT
        
        
-        A formal, serif font.
-        
-        wxFONTFAMILY_SCRIPT
        
        
-        A handwriting font.
-        
-        wxFONTFAMILY_SWISS
+            Chooses a default font.
        
        
-        A sans-serif font.
-        
-        wxFONTFAMILY_MODERN
        
        
-        A fixed pitch font.
        
-        wxFONTFAMILY_TELETYPE
+            wxFONTFAMILY_DECORATIVE
        
        
-        A teletype font.
        
+        
+            A decorative font.
+        
+        
+        
+        
+        
+            wxFONTFAMILY_ROMAN
+        
+        
+        
+        
+            A formal, serif font.
+        
+        
+        
+        
+        
+            wxFONTFAMILY_SCRIPT
+        
+        
+        
+        
+            A handwriting font.
+        
+        
+        
+        
+        
+            wxFONTFAMILY_SWISS
+        
+        
+        
+        
+            A sans-serif font.
+        
+        
+        
+        
+        
+            wxFONTFAMILY_MODERN
+        
+        
+        
+        
+            A fixed pitch font.
+        
+        
+        
+        
+        
+            wxFONTFAMILY_TELETYPE
+        
+        
+        
+        
+            A teletype font.
        @param style
-        One of wxFONTSTYLE_NORMAL, wxFONTSTYLE_SLANT and wxFONTSTYLE_ITALIC.
-        
+            One of wxFONTSTYLE_NORMAL, wxFONTSTYLE_SLANT and wxFONTSTYLE_ITALIC.
        @param weight
-        Font weight, sometimes also referred to as font boldness. One of:
+            Font weight, sometimes also referred to as font boldness. One of:
        
        
-        wxFONTWEIGHT_NORMAL
        
        
-        Normal font.
-        
-        wxFONTWEIGHT_LIGHT
        
        
-        Light font.
        
-        wxFONTWEIGHT_BOLD
+            wxFONTWEIGHT_NORMAL
        
        
-        Bold font.
        
+        
+            Normal font.
+        
+        
+        
+        
+        
+            wxFONTWEIGHT_LIGHT
+        
+        
+        
+        
+            Light font.
+        
+        
+        
+        
+        
+            wxFONTWEIGHT_BOLD
+        
+        
+        
+        
+            Bold font.
        @param underline
-        The value can be @true or @false. At present this has an effect on Windows and
-        Motif 2.x only.
-        
+            The value can be @true or @false. At present this has an effect on Windows
+        and Motif 2.x only.
        @param 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.
-        
+            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.
        @param encoding
-        An encoding which may be one of
-        
-        wxFONTENCODING_SYSTEM
+            An encoding which may be one of
        
        
-        Default system encoding.
-        
-        wxFONTENCODING_DEFAULT
        
        
-        Default application encoding: this
-        is the encoding set by calls to
-        SetDefaultEncoding 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.
-        
-        wxFONTENCODING_ISO8859_1...15
        
        
-        ISO8859 encodings.
        
-        wxFONTENCODING_KOI8
+            wxFONTENCODING_SYSTEM
        
        
-        The standard Russian encoding for Internet.
-        
-        wxFONTENCODING_CP1250...1252
        
        
-        Windows encodings similar to ISO8859 (but not identical).
+            Default system encoding.
        
-        If the specified encoding isn't available, no font is created
-        (see also font encoding overview).
+        
+        
+        
+        
+            wxFONTENCODING_DEFAULT
+        
+        
+        
+        
+            Default application encoding: this
+            is the encoding set by calls to
+            SetDefaultEncoding 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.
+        
+        
+        
+        
+        
+            wxFONTENCODING_ISO8859_1...15
+        
+        
+        
+        
+            ISO8859 encodings.
+        
+        
+        
+        
+        
+            wxFONTENCODING_KOI8
+        
+        
+        
+        
+            The standard Russian encoding for Internet.
+        
+        
+        
+        
+        
+            wxFONTENCODING_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.
+                 chosen. Under Windows, only scalable TrueType fonts are
+                 used.
    */
    wxFont();
    wxFont(const wxFont& font);
    wxFont(int pointSize, wxFontFamily family, int style,
           wxFontWeight weight,
-           const bool underline = @false,
+           const bool underline = false,
           const wxString& faceName = "",
           wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
    wxFont(const wxSize& pixelSize, wxFontFamily family,
           int style, wxFontWeight weight,
-           const bool underline = @false,
+           const bool underline = false,
           const wxString& faceName = "",
           wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
    //@}
@@ -190,19 +282,17 @@ public:
        more info.
        
        @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.
+                 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.
    */
    ~wxFont();

    /**
        Returns the current application's default encoding.
        
-        @sa @ref overview_wxfontencodingoverview "Font encoding overview",
-              SetDefaultEncoding()
+        @see @ref overview_wxfontencodingoverview, SetDefaultEncoding()
    */
    static wxFontEncoding GetDefaultEncoding();

@@ -211,7 +301,7 @@ public:
        there is no
        typeface information.
        
-        @sa SetFaceName()
+        @see SetFaceName()
    */
    wxString GetFaceName();

@@ -219,7 +309,7 @@ public:
        Gets the font family. See SetFamily() for a list of valid
        family identifiers.
        
-        @sa SetFamily()
+        @see SetFamily()
    */
    wxFontFamily GetFamily();

@@ -230,7 +320,7 @@ public:
        typical
        use of this function is for serializing in string-form a wxFont object.
        
-        @sa SetNativeFontInfo(),GetNativeFontInfoUserDesc()
+        @see SetNativeFontInfo(),GetNativeFontInfoUserDesc()
    */
    wxString GetNativeFontInfoDesc();

@@ -240,14 +330,14 @@ public:
        Some examples of the formats of returned strings (which are platform-dependent)
        are in SetNativeFontInfoUserDesc().
        
-        @sa GetNativeFontInfoDesc()
+        @see GetNativeFontInfoDesc()
    */
    wxString GetNativeFontInfoUserDesc();

    /**
        Gets the point size.
        
-        @sa SetPointSize()
+        @see SetPointSize()
    */
    int GetPointSize();

@@ -255,14 +345,14 @@ public:
        Gets the font style. See wxFont() for a list of valid
        styles.
        
-        @sa SetStyle()
+        @see SetStyle()
    */
    int GetStyle();

    /**
        Returns @true if the font is underlined, @false otherwise.
        
-        @sa SetUnderlined()
+        @see SetUnderlined()
    */
    bool GetUnderlined();

@@ -270,7 +360,7 @@ public:
        Gets the font weight. See wxFont() for a list of valid
        weight identifiers.
        
-        @sa SetWeight()
+        @see SetWeight()
    */
    wxFontWeight GetWeight();

@@ -283,45 +373,42 @@ public:
    /**
        Returns @true if this object is a valid font, @false otherwise.
    */
-#define bool IsOk()     /* implementation is private */
+    bool IsOk();

    //@{
    /**
        These functions take the same parameters as @ref ctor() wxFont
        constructor and return a new font object allocated on the heap.
-        
        Using @c New() is currently the only way to directly create a font with
        the given size in pixels on platforms other than wxMSW.
    */
-    static wxFont * New(int pointSize, wxFontFamily family,
-                        int style,
-                        wxFontWeight weight,
-                        const bool underline = @false,
-                        const wxString& faceName = "",
-                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
-    static wxFont * New(int pointSize, wxFontFamily family,
-                        int flags = wxFONTFLAG_DEFAULT,
-                        const wxString& faceName = "",
-                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
-    static wxFont * New(const wxSize& pixelSize,
-                        wxFontFamily family,
-                        int style,
-                        wxFontWeight weight,
-                        const bool underline = @false,
-                        const wxString& faceName = "",
-                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
-    static wxFont * New(const wxSize& pixelSize,
-                        wxFontFamily family,
-                        int flags = wxFONTFLAG_DEFAULT,
-                        const wxString& faceName = "",
-                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
+    static wxFont* New(int pointSize, wxFontFamily family, int style,
+                       wxFontWeight weight,
+                       const bool underline = false,
+                       const wxString& faceName = "",
+                       wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
+    static wxFont* New(int pointSize, wxFontFamily family,
+                       int flags = wxFONTFLAG_DEFAULT,
+                       const wxString& faceName = "",
+                       wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
+    static wxFont* New(const wxSize& pixelSize,
+                       wxFontFamily family,
+                       int style,
+                       wxFontWeight weight,
+                       const bool underline = false,
+                       const wxString& faceName = "",
+                       wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
+    static wxFont* New(const wxSize& pixelSize,
+                       wxFontFamily family,
+                       int flags = wxFONTFLAG_DEFAULT,
+                       const wxString& faceName = "",
+                       wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
    //@}

    /**
        Sets the default font encoding.
        
-        @sa @ref overview_wxfontencodingoverview "Font encoding overview",
-              GetDefaultEncoding()
+        @see @ref overview_wxfontencodingoverview, GetDefaultEncoding()
    */
    static void SetDefaultEncoding(wxFontEncoding encoding);

@@ -330,16 +417,16 @@ public:
        Returns @true if the given face name exists; @false otherwise.
        
        @param faceName
-        A valid facename, which should be on the end-user's system.
+            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,
-                   wxWidgets will first search for the specific face,
-                   and then for a font belonging to the same family.
+                 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.
        
-        @sa GetFaceName(), SetFamily()
+        @see GetFaceName(), SetFamily()
    */
    bool SetFaceName(const wxString& faceName);

@@ -347,45 +434,88 @@ public:
        Sets the font family.
        
        @param family
-        One of:
+            One of:
        
        
-        wxFONTFAMILY_DEFAULT
        
        
-        Chooses a default font.
-        
-        wxFONTFAMILY_DECORATIVE
        
        
-        A decorative font.
        
-        wxFONTFAMILY_ROMAN
+            wxFONTFAMILY_DEFAULT
        
        
-        A formal, serif font.
-        
-        wxFONTFAMILY_SCRIPT
        
        
-        A handwriting font.
-        
-        wxFONTFAMILY_SWISS
+            Chooses a default font.
        
        
-        A sans-serif font.
-        
-        wxFONTFAMILY_MODERN
        
        
-        A fixed pitch font.
        
-        wxFONTFAMILY_TELETYPE
+            wxFONTFAMILY_DECORATIVE
        
        
-        A teletype font.
        
-        @sa GetFamily(), SetFaceName()
+        
+            A decorative font.
+        
+        
+        
+        
+        
+            wxFONTFAMILY_ROMAN
+        
+        
+        
+        
+            A formal, serif font.
+        
+        
+        
+        
+        
+            wxFONTFAMILY_SCRIPT
+        
+        
+        
+        
+            A handwriting font.
+        
+        
+        
+        
+        
+            wxFONTFAMILY_SWISS
+        
+        
+        
+        
+            A sans-serif font.
+        
+        
+        
+        
+        
+            wxFONTFAMILY_MODERN
+        
+        
+        
+        
+            A fixed pitch font.
+        
+        
+        
+        
+        
+            wxFONTFAMILY_TELETYPE
+        
+        
+        
+        
+            A teletype font.
+        
+        @see GetFamily(), SetFaceName()
    */
    void SetFamily(wxFontFamily family);

@@ -399,7 +529,7 @@ public:
        a wxFont
        object previously saved in a string-form.
        
-        @sa SetNativeFontInfoUserDesc()
+        @see SetNativeFontInfoUserDesc()
    */
    bool SetNativeFontInfo(const wxString& info);

@@ -411,31 +541,26 @@ public:
        strings which are user-friendly.
        Examples of accepted string formats are:
        
-        
        Generic syntax
        
-        
        Example
        
        on @b wxGTK2: @c [FACE-NAME] [bold] [oblique|italic] [POINTSIZE]
        
-        
        Monospace bold 10
        
        on @b wxMSW: @c [light|bold] [italic] [FACE-NAME] [POINTSIZE] [ENCODING]
        
-        
        Tahoma 10 WINDOWS-1252
        
        on @b wxMac: FIXME
        
-        
        FIXME
        
        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_string).
        
-        @sa SetNativeFontInfo()
+        @see SetNativeFontInfo()
    */
    bool SetNativeFontInfoUserDesc(const wxString& info);

@@ -443,9 +568,9 @@ public:
        Sets the point size.
        
        @param pointSize
-        Size in points.
+            Size in points.
        
-        @sa GetPointSize()
+        @see GetPointSize()
    */
    void SetPointSize(int pointSize);

@@ -453,9 +578,9 @@ public:
        Sets the font style.
        
        @param style
-        One of wxFONTSTYLE_NORMAL, wxFONTSTYLE_SLANT and wxFONTSTYLE_ITALIC.
+            One of wxFONTSTYLE_NORMAL, wxFONTSTYLE_SLANT and wxFONTSTYLE_ITALIC.
        
-        @sa GetStyle()
+        @see GetStyle()
    */
    void SetStyle(int style);

@@ -463,9 +588,9 @@ public:
        Sets underlining.
        
        @param underlining
-        @true to underline, @false otherwise.
+            @true to underline, @false otherwise.
        
-        @sa GetUnderlined()
+        @see GetUnderlined()
    */
    void SetUnderlined(const bool underlined);

@@ -473,25 +598,44 @@ public:
        Sets the font weight.
        
        @param weight
-        One of:
+            One of:
        
        
-        wxFONTWEIGHT_NORMAL
        
        
-        Normal font.
-        
-        wxFONTWEIGHT_LIGHT
        
        
-        Light font.
        
-        wxFONTWEIGHT_BOLD
+            wxFONTWEIGHT_NORMAL
        
        
-        Bold font.
        
-        @sa GetWeight()
+        
+            Normal font.
+        
+        
+        
+        
+        
+            wxFONTWEIGHT_LIGHT
+        
+        
+        
+        
+            Light font.
+        
+        
+        
+        
+        
+            wxFONTWEIGHT_BOLD
+        
+        
+        
+        
+            Bold font.
+        
+        @see GetWeight()
    */
    void SetWeight(wxFontWeight weight);