Better documentation for the default parameters values.

[wxWidgets.git] / interface / wx / font.h

diff --git a/interface/wx/font.h b/interface/wx/font.h
index c814de2baae65577c1bb68e7b3a35c47108e9fee..dab6d19b2a2bb4c4abc7b0f56cfcf9872b29918d 100644 (file)
--- a/interface/wx/font.h
+++ b/interface/wx/font.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of wxFont
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxFont
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 
 /////////////////////////////////////////////////////////////////////////////
 
 


@@ -36,11 +36,10 @@ enum wxFontFamily
     /// See also wxFont::IsFixedWidth() for an easy way to test for monospace property.
     wxFONTFAMILY_TELETYPE = wxTELETYPE,
 
     /// See also wxFont::IsFixedWidth() for an easy way to test for monospace property.
     wxFONTFAMILY_TELETYPE = wxTELETYPE,
 

-    /// Returned by wxFont::GetFamily() when the face name of the font cannot
-    /// be classified into one of the previous wxFontFamily values.
-    wxFONTFAMILY_UNKNOWN = wxFONTFAMILY_MAX,
-
-    wxFONTFAMILY_MAX
+    wxFONTFAMILY_MAX,
+    /// Invalid font family value, returned by wxFont::GetFamily() when the
+    /// font is invalid for example.
+    wxFONTFAMILY_UNKNOWN = wxFONTFAMILY_MAX

 };
 
 /**
 };
 
 /**


@@ -72,6 +71,27 @@ enum wxFontWeight
     wxFONTWEIGHT_MAX
 };
 
     wxFONTWEIGHT_MAX
 };
 

+/**
+    Symbolic font sizes.
+
+    The elements of this enum correspond to CSS absolute size specifications,
+    see http://www.w3.org/TR/CSS21/fonts.html#font-size-props
+
+    @see wxFont::SetSymbolicSize()
+
+    @since 2.9.2
+ */
+enum wxFontSymbolicSize
+{
+    wxFONTSIZE_XX_SMALL = -3,   //!< Extra small.
+    wxFONTSIZE_X_SMALL,         //!< Very small.
+    wxFONTSIZE_SMALL,           //!< Small.
+    wxFONTSIZE_MEDIUM,          //!< Normal.
+    wxFONTSIZE_LARGE,           //!< Large.
+    wxFONTSIZE_X_LARGE,         //!< Very large.
+    wxFONTSIZE_XX_LARGE         //!< Extra large.
+};
+

 /**
     The font flag bits for the new font ctor accepting one combined flags word.
 */
 /**
     The font flag bits for the new font ctor accepting one combined flags word.
 */


@@ -92,8 +112,10 @@ enum wxFontFlag
     wxFONTFLAG_ANTIALIASED      = 1 << 4,
     wxFONTFLAG_NOT_ANTIALIASED  = 1 << 5,
 
     wxFONTFLAG_ANTIALIASED      = 1 << 4,
     wxFONTFLAG_NOT_ANTIALIASED  = 1 << 5,
 

-    /// underlined/strikethrough flags (default: no lines)
+    /// Underlined style (not underlined by default).

     wxFONTFLAG_UNDERLINED       = 1 << 6,
     wxFONTFLAG_UNDERLINED       = 1 << 6,

+
+    /// Strike-through style (only supported in wxMSW and wxGTK currently).

     wxFONTFLAG_STRIKETHROUGH    = 1 << 7,
 
     /// the mask of all currently used flags
     wxFONTFLAG_STRIKETHROUGH    = 1 << 7,
 
     /// the mask of all currently used flags


@@ -237,17 +259,13 @@ enum wxFontEncoding
     /// (this is used by wxEncodingConverter and wxUTFFile only for now)
     wxFONTENCODING_UNICODE,
 
     /// (this is used by wxEncodingConverter and wxUTFFile only for now)
     wxFONTENCODING_UNICODE,
 

-    // alternative names for Far Eastern encodings
-    // Chinese

     wxFONTENCODING_GB2312 = wxFONTENCODING_CP936, //!< Simplified Chinese
     wxFONTENCODING_BIG5 = wxFONTENCODING_CP950,   //!< Traditional Chinese
     wxFONTENCODING_GB2312 = wxFONTENCODING_CP936, //!< Simplified Chinese
     wxFONTENCODING_BIG5 = wxFONTENCODING_CP950,   //!< Traditional Chinese

-
-        // Japanese (see http://zsigri.tripod.com/fontboard/cjk/jis.html)
-    wxFONTENCODING_SHIFT_JIS = wxFONTENCODING_CP932 //!< Shift JIS
+    wxFONTENCODING_SHIFT_JIS = wxFONTENCODING_CP932, //!< Shift JIS
+    wxFONTENCODING_EUC_KR = wxFONTENCODING_CP949 //!< Korean

 };
 
 
 };
 
 

-

 /**
     @class wxFont
 
 /**
     @class wxFont
 


@@ -287,7 +305,7 @@ public:
     wxFont(const wxFont& font);
 
     /**
     wxFont(const wxFont& font);
 
     /**

-        Creates a font object with the specified attributes.
+        Creates a font object with the specified attributes and size in points.

 
         @param pointSize
             Size in points. See SetPointSize() for more info.
 
         @param pointSize
             Size in points. See SetPointSize() for more info.


@@ -333,7 +351,7 @@ public:
            wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 
     /**
            wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 
     /**

-        Creates a font object with the specified attributes.
+        Creates a font object with the specified attributes and size in pixels.

 
         @param pixelSize
             Size in pixels. See SetPixelSize() for more info.
 
         @param pixelSize
             Size in pixels. See SetPixelSize() for more info.


@@ -378,6 +396,25 @@ public:
            const wxString& faceName = wxEmptyString,
            wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 
            const wxString& faceName = wxEmptyString,
            wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 

+    /**
+        Creates a font object using font flags.
+
+        This constructor is similar to the constructors above except it
+        specifies the font styles such as underlined, italic, bold, ... in a
+        single @a flags argument instead of using separate arguments for them.
+        This parameter can be a combination of ::wxFontFlag enum elements.
+        The meaning of the remaining arguments is the same as in the other
+        constructors, please see their documentation for details.
+
+        Notice that this constructor provides the only way of creating fonts
+        with strike-through style.
+
+        @since 2.9.4
+     */
+    wxFont(int pointSize, wxFontFamily family, int flags,
+           const wxString& faceName = wxEmptyString,
+           wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
+

     /**
         Constructor from font description string.
 
     /**
         Constructor from font description string.
 


@@ -385,7 +422,12 @@ public:
         If @a fontdesc is invalid the font remains uninitialized, i.e. its IsOk() method
         will return @false.
      */
         If @a fontdesc is invalid the font remains uninitialized, i.e. its IsOk() method
         will return @false.
      */

-    wxFont(const wxString& fontdesc);
+    wxFont(const wxString& nativeInfoString);
+
+    /**
+       Construct font from a native font info structure.
+    */
+    wxFont(const wxNativeFontInfo& nativeInfo);

 
     /**
         Destructor.
 
     /**
         Destructor.


@@ -425,16 +467,17 @@ public:
     virtual wxString GetFaceName() const;
 
     /**
     virtual wxString GetFaceName() const;
 
     /**

-        Gets the font family.
+        Gets the font family if possible.
+

         As described in ::wxFontFamily docs the returned value acts as a rough,
         basic classification of the main font properties (look, spacing).
 
         If the current font face name is not recognized by wxFont or by the
         As described in ::wxFontFamily docs the returned value acts as a rough,
         basic classification of the main font properties (look, spacing).
 
         If the current font face name is not recognized by wxFont or by the

-        underlying system, @c wxFONTFAMILY_UNKNOWN is returned.
+        underlying system, @c wxFONTFAMILY_DEFAULT is returned.

 
 

-        Note that currently this function is rather unreliable (@c wxFONTFAMILY_UNKNOWN
-        is returned in too many cases) and not particularly useful.
-        Font families mostly make sense only for font creation; see SetFamily().
+        Note that currently this function is not very precise and so not
+        particularly useful. Font families mostly make sense only for font
+        creation, see SetFamily().

 
         @see SetFamily()
     */
 
         @see SetFamily()
     */


@@ -442,7 +485,9 @@ public:
 
     /**
         Returns the platform-dependent string completely describing this font.
 
     /**
         Returns the platform-dependent string completely describing this font.

-        Returned string is always non-empty.
+
+        Returned string is always non-empty unless the font is invalid (in
+        which case an assert is triggered).

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


@@ -453,7 +498,9 @@ public:
 
     /**
         Returns a user-friendly string for this font object.
 
     /**
         Returns a user-friendly string for this font object.

-        Returned string is always non-empty.
+
+        Returned string is always non-empty unless the font is invalid (in
+        which case an assert is triggered).

 
         The string does not encode all wxFont infos under all platforms;
         e.g. under wxMSW the font family is not present in the returned string.
 
         The string does not encode all wxFont infos under all platforms;
         e.g. under wxMSW the font family is not present in the returned string.


@@ -465,6 +512,8 @@ public:
     */
     wxString GetNativeFontInfoUserDesc() const;
 
     */
     wxString GetNativeFontInfoUserDesc() const;
 

+    const wxNativeFontInfo *GetNativeFontInfo() const;
+

     /**
         Gets the point size.
 
     /**
         Gets the point size.
 


@@ -497,6 +546,15 @@ public:
     */
     virtual bool GetUnderlined() const;
 
     */
     virtual bool GetUnderlined() const;
 

+    /**
+        Returns @true if the font is stricken-through, @false otherwise.
+
+        @see SetStrikethrough()
+
+        @since 2.9.4
+     */
+    virtual bool GetStrikethrough() const;
+

     /**
         Gets the font weight. See ::wxFontWeight for a list of valid weight identifiers.
 
     /**
         Gets the font weight. See ::wxFontWeight for a list of valid weight identifiers.
 


@@ -526,48 +584,159 @@ public:
     /**
         @name Similar fonts creation
 
     /**
         @name Similar fonts creation
 

-        The functions in this section create a font similar to the given one
-        but with its weight, style or size changed.
+        The functions in this section either modify the font in place or create
+        a new font similar to the given one but with its weight, style or size
+        changed.

      */
     //@{
 
     /**
      */
     //@{
 
     /**

-        Return a bold version of this font.
+        Returns a bold version of this font.
+
+        @see MakeBold()
+
+        @since 2.9.1
+     */
+    wxFont Bold() const;
+
+    /**
+        Returns an italic version of this font.
+
+        @see MakeItalic()
+
+        @since 2.9.1
+     */
+    wxFont Italic() const;
+
+    /**
+        Returns a larger version of this font.
+
+        The font size is multiplied by @c 1.2, the factor of @c 1.2 being
+        inspired by the W3C CSS specification.
+
+        @see MakeLarger(), Smaller(), Scaled()
+
+        @since 2.9.1
+     */
+    wxFont Larger() const;
+
+    /**
+        Returns a smaller version of this font.
+
+        The font size is divided by @c 1.2, the factor of @c 1.2 being
+        inspired by the W3C CSS specification.
+
+        @see MakeSmaller(), Larger(), Scaled()
+
+        @since 2.9.1

      */
      */

-    wxFont MakeBold() const;
+    wxFont Smaller() const;

 
     /**
 
     /**

-        Return an italic version of this font.
+        Returns underlined version of this font.
+
+        @see MakeUnderlined()
+
+        @since 2.9.2

      */
      */

-    wxFont MakeItalic() const;
+    wxFont Underlined() const;

 
     /**
 
     /**

-        Return a larger version of this font.
+        Returns stricken-through version of this font.
+
+        Currently stricken-through fonts are only supported in wxMSW and wxGTK.

 
 

-        The font size is multiplied by CSS specification inspired factor of @c
-        1.2.
+        @see MakeStrikethrough()

 
 

-        @see MakeSmaller(), Scale()
+        @since 2.9.4

      */
      */

-    wxFont MakeLarger() const;
+    wxFont Strikethrough() const;

 
     /**
 
     /**

-        Return a smaller version of this font.
+        Changes this font to be bold.

 
 

-        The font size is divided by CSS specification inspired factor of @c
-        1.2.
+        @see Bold()

 
 

-        @see MakeLarger(), Scale()
+        @since 2.9.1

      */
      */

-    wxFont MakeSmaller() const;
+    wxFont& MakeBold();

 
     /**
 
     /**

-        Return a scaled version of this font.
+        Changes this font to be italic.
+
+        @see Italic()
+
+        @since 2.9.1
+     */
+    wxFont& MakeItalic();
+
+    /**
+        Changes this font to be larger.
+
+        The font size is multiplied by @c 1.2, the factor of @c 1.2 being
+        inspired by the W3C CSS specification.
+
+        @see Larger(), MakeSmaller(), Scale()
+
+        @since 2.9.1
+     */
+    wxFont& MakeLarger();
+
+    /**
+        Changes this font to be smaller.
+
+        The font size is divided by @c 1.2, the factor of @c 1.2 being
+        inspired by the W3C CSS specification.
+
+        @see Smaller(), MakeLarger(), Scale()
+
+        @since 2.9.1
+     */
+    wxFont& MakeSmaller();
+
+    /**
+        Changes this font to be underlined.
+
+        @see Underlined()
+
+        @since 2.9.2
+     */
+    wxFont& MakeUnderlined();
+
+    /**
+        Changes this font to be stricken-through.
+
+        Currently stricken-through fonts are only supported in wxMSW and wxGTK.
+
+        @see Strikethrough()
+
+        @since 2.9.4
+    */
+    wxFont& MakeStrikethrough();
+
+    /**
+        Changes the size of this font.

 
         The font size is multiplied by the given factor (which may be less than
         1 to create a smaller version of the font).
 
         The font size is multiplied by the given factor (which may be less than
         1 to create a smaller version of the font).

+
+        @see Scaled(), MakeLarger(), MakeSmaller()
+
+        @since 2.9.1

      */
      */

-    wxFont Scale(float x) const;
+    wxFont& Scale(float x);
+
+    /**
+        Returns a scaled version of this font.
+
+        The font size is multiplied by the given factor (which may be less than
+        1 to create a smaller version of the font).
+
+        @see Scale(), Larger(), Smaller()
+
+        @since 2.9.1
+     */
+    wxFont Scaled(float x) const;

 
     //@}
 
 
     //@}
 


@@ -664,6 +833,8 @@ public:
     */
     bool SetNativeFontInfoUserDesc(const wxString& info);
 
     */
     bool SetNativeFontInfoUserDesc(const wxString& info);
 

+    void SetNativeFontInfo(const wxNativeFontInfo& info);
+        

     /**
         Sets the point size.
 
     /**
         Sets the point size.
 


@@ -702,6 +873,28 @@ public:
     */
     virtual void SetStyle(wxFontStyle style);
 
     */
     virtual void SetStyle(wxFontStyle style);
 

+    /**
+        Sets the font size using a predefined symbolic size name.
+
+        This function allows to change font size to be (very) large or small
+        compared to the standard font size.
+
+        @see SetSymbolicSizeRelativeTo().
+
+        @since 2.9.2
+     */
+    void SetSymbolicSize(wxFontSymbolicSize size);
+
+    /**
+        Sets the font size compared to the base font size.
+
+        This is the same as SetSymbolicSize() except that it uses the given
+        font size as the normal font size instead of the standard font size.
+
+        @since 2.9.2
+     */
+    void SetSymbolicSizeRelativeTo(wxFontSymbolicSize size, int base);
+

     /**
         Sets underlining.
 
     /**
         Sets underlining.
 


@@ -712,6 +905,20 @@ public:
     */
     virtual void SetUnderlined(bool underlined);
 
     */
     virtual void SetUnderlined(bool underlined);
 

+    /**
+        Sets strike-through attribute of the font.
+
+        Currently stricken-through fonts are only supported in wxMSW and wxGTK.
+
+        @param strikethrough
+            @true to add strike-through style, @false to remove it.
+
+        @see GetStrikethrough()
+
+        @since 2.9.4
+    */
+    virtual void SetStrikethrough(bool strikethrough);
+

     /**
         Sets the font weight.
 
     /**
         Sets the font weight.
 


@@ -790,6 +997,11 @@ public:
                        int flags = wxFONTFLAG_DEFAULT,
                        const wxString& faceName = wxEmptyString,
                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
                        int flags = wxFONTFLAG_DEFAULT,
                        const wxString& faceName = wxEmptyString,
                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);

+
+    
+    static wxFont *New(const wxNativeFontInfo& nativeInfo);
+    static wxFont *New(const wxString& nativeInfoString);
+

     //@}
 };
 
     //@}
 };
 


@@ -804,25 +1016,25 @@ wxFont wxNullFont;
 
     @see wxSystemSettings
 */
 
     @see wxSystemSettings
 */

-wxFont wxNORMAL_FONT;
+wxFont* wxNORMAL_FONT;

 
 /**
     A font using the @c wxFONTFAMILY_SWISS family and 2 points smaller than
     ::wxNORMAL_FONT.
 */
 
 /**
     A font using the @c wxFONTFAMILY_SWISS family and 2 points smaller than
     ::wxNORMAL_FONT.
 */

-wxFont wxSMALL_FONT;
+wxFont* wxSMALL_FONT;

 
 /**
     A font using the @c wxFONTFAMILY_ROMAN family and @c wxFONTSTYLE_ITALIC style and
     of the same size of ::wxNORMAL_FONT.
 */
 
 /**
     A font using the @c wxFONTFAMILY_ROMAN family and @c wxFONTSTYLE_ITALIC style and
     of the same size of ::wxNORMAL_FONT.
 */

-wxFont wxITALIC_FONT;
+wxFont* wxITALIC_FONT;

 
 /**
     A font identic to ::wxNORMAL_FONT except for the family used which is
     @c wxFONTFAMILY_SWISS.
 */
 
 /**
     A font identic to ::wxNORMAL_FONT except for the family used which is
     @c wxFONTFAMILY_SWISS.
 */

-wxFont wxSWISS_FONT;
+wxFont* wxSWISS_FONT;

 
 
 /**
 
 
 /**