document the wxIntXX/wxFloatXX/wxCharXX types; add some comments to wxKeyCode docs

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

diff --git a/interface/wx/textctrl.h b/interface/wx/textctrl.h
index 2e8f2cd1c649f4b7cfad41d72b1fe4a3eff1fa43..e9ac22eab8e2122bcdbb97491fa6dc02b40a9b66 100644 (file)
--- a/interface/wx/textctrl.h
+++ b/interface/wx/textctrl.h
@@ -7,9 +7,8 @@
 /////////////////////////////////////////////////////////////////////////////
 
 
 /////////////////////////////////////////////////////////////////////////////
 
 

-

 /**
 /**

-    The following values can be passed to wxTextAttr::SetAlignment to determine paragraph alignment.
+    One of the following values can be passed to wxTextAttr::SetAlignment to determine paragraph alignment.

 */
 enum wxTextAttrAlignment
 {
 */
 enum wxTextAttrAlignment
 {


@@ -32,55 +31,75 @@ enum wxTextAttrFlags
 {
     wxTEXT_ATTR_TEXT_COLOUR          = 0x00000001,
     wxTEXT_ATTR_BACKGROUND_COLOUR    = 0x00000002,
 {
     wxTEXT_ATTR_TEXT_COLOUR          = 0x00000001,
     wxTEXT_ATTR_BACKGROUND_COLOUR    = 0x00000002,

+

     wxTEXT_ATTR_FONT_FACE            = 0x00000004,
     wxTEXT_ATTR_FONT_SIZE            = 0x00000008,
     wxTEXT_ATTR_FONT_WEIGHT          = 0x00000010,
     wxTEXT_ATTR_FONT_ITALIC          = 0x00000020,
     wxTEXT_ATTR_FONT_UNDERLINE       = 0x00000040,
     wxTEXT_ATTR_FONT_ENCODING        = 0x02000000,
     wxTEXT_ATTR_FONT_FACE            = 0x00000004,
     wxTEXT_ATTR_FONT_SIZE            = 0x00000008,
     wxTEXT_ATTR_FONT_WEIGHT          = 0x00000010,
     wxTEXT_ATTR_FONT_ITALIC          = 0x00000020,
     wxTEXT_ATTR_FONT_UNDERLINE       = 0x00000040,
     wxTEXT_ATTR_FONT_ENCODING        = 0x02000000,

+    wxTEXT_ATTR_FONT_FAMILY          = 0x04000000,
+
+    /**
+        Defined as the combination of all @c wxTEXT_ATTR_FONT_* values above.
+    */

     wxTEXT_ATTR_FONT = \
         ( wxTEXT_ATTR_FONT_FACE | wxTEXT_ATTR_FONT_SIZE | wxTEXT_ATTR_FONT_WEIGHT | \
     wxTEXT_ATTR_FONT = \
         ( wxTEXT_ATTR_FONT_FACE | wxTEXT_ATTR_FONT_SIZE | wxTEXT_ATTR_FONT_WEIGHT | \

-            wxTEXT_ATTR_FONT_ITALIC | wxTEXT_ATTR_FONT_UNDERLINE | wxTEXT_ATTR_FONT_ENCODING ),
+            wxTEXT_ATTR_FONT_ITALIC | wxTEXT_ATTR_FONT_UNDERLINE | wxTEXT_ATTR_FONT_ENCODING | wxTEXT_ATTR_FONT_FAMILY ),

 
     wxTEXT_ATTR_ALIGNMENT            = 0x00000080,
     wxTEXT_ATTR_LEFT_INDENT          = 0x00000100,
     wxTEXT_ATTR_RIGHT_INDENT         = 0x00000200,
     wxTEXT_ATTR_TABS                 = 0x00000400,
 
     wxTEXT_ATTR_ALIGNMENT            = 0x00000080,
     wxTEXT_ATTR_LEFT_INDENT          = 0x00000100,
     wxTEXT_ATTR_RIGHT_INDENT         = 0x00000200,
     wxTEXT_ATTR_TABS                 = 0x00000400,

-

     wxTEXT_ATTR_PARA_SPACING_AFTER   = 0x00000800,
     wxTEXT_ATTR_PARA_SPACING_BEFORE  = 0x00001000,
     wxTEXT_ATTR_LINE_SPACING         = 0x00002000,
     wxTEXT_ATTR_CHARACTER_STYLE_NAME = 0x00004000,
     wxTEXT_ATTR_PARAGRAPH_STYLE_NAME = 0x00008000,
     wxTEXT_ATTR_LIST_STYLE_NAME      = 0x00010000,
     wxTEXT_ATTR_PARA_SPACING_AFTER   = 0x00000800,
     wxTEXT_ATTR_PARA_SPACING_BEFORE  = 0x00001000,
     wxTEXT_ATTR_LINE_SPACING         = 0x00002000,
     wxTEXT_ATTR_CHARACTER_STYLE_NAME = 0x00004000,
     wxTEXT_ATTR_PARAGRAPH_STYLE_NAME = 0x00008000,
     wxTEXT_ATTR_LIST_STYLE_NAME      = 0x00010000,

+

     wxTEXT_ATTR_BULLET_STYLE         = 0x00020000,
     wxTEXT_ATTR_BULLET_NUMBER        = 0x00040000,
     wxTEXT_ATTR_BULLET_TEXT          = 0x00080000,
     wxTEXT_ATTR_BULLET_NAME          = 0x00100000,
     wxTEXT_ATTR_BULLET_STYLE         = 0x00020000,
     wxTEXT_ATTR_BULLET_NUMBER        = 0x00040000,
     wxTEXT_ATTR_BULLET_TEXT          = 0x00080000,
     wxTEXT_ATTR_BULLET_NAME          = 0x00100000,

+
+    /**
+        Defined as the combination of all @c wxTEXT_ATTR_BULLET_* values above.
+    */
+    wxTEXT_ATTR_BULLET = \
+        ( wxTEXT_ATTR_BULLET_STYLE | wxTEXT_ATTR_BULLET_NUMBER | wxTEXT_ATTR_BULLET_TEXT | \
+          wxTEXT_ATTR_BULLET_NAME ),
+

     wxTEXT_ATTR_URL                  = 0x00200000,
     wxTEXT_ATTR_PAGE_BREAK           = 0x00400000,
     wxTEXT_ATTR_EFFECTS              = 0x00800000,
     wxTEXT_ATTR_OUTLINE_LEVEL        = 0x01000000,
 
     /**
     wxTEXT_ATTR_URL                  = 0x00200000,
     wxTEXT_ATTR_PAGE_BREAK           = 0x00400000,
     wxTEXT_ATTR_EFFECTS              = 0x00800000,
     wxTEXT_ATTR_OUTLINE_LEVEL        = 0x01000000,
 
     /**

-        Character and paragraph combined styles
+        Combines the styles @c wxTEXT_ATTR_FONT, @c wxTEXT_ATTR_EFFECTS, @c wxTEXT_ATTR_BACKGROUND_COLOUR,
+        @c wxTEXT_ATTR_TEXT_COLOUR, @c wxTEXT_ATTR_CHARACTER_STYLE_NAME, @c wxTEXT_ATTR_URL.

     */
 
     wxTEXT_ATTR_CHARACTER = \
     */
 
     wxTEXT_ATTR_CHARACTER = \

-        (wxTEXT_ATTR_FONT|wxTEXT_ATTR_FONT_ENCODING|wxTEXT_ATTR_EFFECTS| \
+        (wxTEXT_ATTR_FONT|wxTEXT_ATTR_EFFECTS| \

             wxTEXT_ATTR_BACKGROUND_COLOUR|wxTEXT_ATTR_TEXT_COLOUR|wxTEXT_ATTR_CHARACTER_STYLE_NAME|wxTEXT_ATTR_URL),
 
             wxTEXT_ATTR_BACKGROUND_COLOUR|wxTEXT_ATTR_TEXT_COLOUR|wxTEXT_ATTR_CHARACTER_STYLE_NAME|wxTEXT_ATTR_URL),
 

+    /**
+        Combines all the styles regarding text paragraphs.
+    */

     wxTEXT_ATTR_PARAGRAPH = \
         (wxTEXT_ATTR_ALIGNMENT|wxTEXT_ATTR_LEFT_INDENT|wxTEXT_ATTR_RIGHT_INDENT|wxTEXT_ATTR_TABS|\
             wxTEXT_ATTR_PARA_SPACING_BEFORE|wxTEXT_ATTR_PARA_SPACING_AFTER|wxTEXT_ATTR_LINE_SPACING|\
     wxTEXT_ATTR_PARAGRAPH = \
         (wxTEXT_ATTR_ALIGNMENT|wxTEXT_ATTR_LEFT_INDENT|wxTEXT_ATTR_RIGHT_INDENT|wxTEXT_ATTR_TABS|\
             wxTEXT_ATTR_PARA_SPACING_BEFORE|wxTEXT_ATTR_PARA_SPACING_AFTER|wxTEXT_ATTR_LINE_SPACING|\

-            wxTEXT_ATTR_BULLET_STYLE|wxTEXT_ATTR_BULLET_NUMBER|wxTEXT_ATTR_BULLET_TEXT|wxTEXT_ATTR_BULLET_NAME|\
-            wxTEXT_ATTR_PARAGRAPH_STYLE_NAME|wxTEXT_ATTR_LIST_STYLE_NAME|wxTEXT_ATTR_OUTLINE_LEVEL),
+            wxTEXT_ATTR_BULLET|wxTEXT_ATTR_PARAGRAPH_STYLE_NAME|wxTEXT_ATTR_LIST_STYLE_NAME|wxTEXT_ATTR_OUTLINE_LEVEL),

 
 

+    /**
+        Combines all previous values.
+    */

     wxTEXT_ATTR_ALL = (wxTEXT_ATTR_CHARACTER|wxTEXT_ATTR_PARAGRAPH)
 };
 
 /**
     wxTEXT_ATTR_ALL = (wxTEXT_ATTR_CHARACTER|wxTEXT_ATTR_PARAGRAPH)
 };
 
 /**

-    Styles for wxTextAttr::SetBulletStyle
+    Styles for wxTextAttr::SetBulletStyle. They can be combined together as a bitlist.

 */
 enum wxTextAttrBulletStyle
 {
 */
 enum wxTextAttrBulletStyle
 {


@@ -106,7 +125,7 @@ enum wxTextAttrBulletStyle
 };
 
 /**
 };
 
 /**

-    Styles for wxTextAttr::SetTextEffects().
+    Styles for wxTextAttr::SetTextEffects(). They can be combined together as a bitlist.

 
     Of these, only wxTEXT_ATTR_EFFECT_CAPITALS and wxTEXT_ATTR_EFFECT_STRIKETHROUGH are implemented.
 */
 
     Of these, only wxTEXT_ATTR_EFFECT_CAPITALS and wxTEXT_ATTR_EFFECT_STRIKETHROUGH are implemented.
 */


@@ -126,7 +145,7 @@ enum wxTextAttrEffects
 };
 
 /**
 };
 
 /**

-    Line spacing values; see wxTextAttr::SetLineSpacing().
+    Convenience line spacing values; see wxTextAttr::SetLineSpacing().

 */
 enum wxTextAttrLineSpacing
 {
 */
 enum wxTextAttrLineSpacing
 {


@@ -206,6 +225,27 @@ public:
     */
     wxFont CreateFont() const;
 
     */
     wxFont CreateFont() const;
 

+    /**
+        Copies all defined/valid properties from overlay to current object.
+    */
+    void Merge(const wxTextAttr& overlay);
+
+    /**
+        Creates a new @c wxTextAttr which is a merge of @a base and @a overlay.
+
+        Properties defined in @a overlay take precedence over those in @a base.
+        Properties undefined/invalid in both are undefined in the result.
+    */
+    static wxTextAttr Merge(const wxTextAttr& base,
+                            const wxTextAttr& overlay);
+
+
+    /**
+        @name GetXXX functions
+     */
+
+    //@{
+

     /**
         Returns the alignment flags.
         See ::wxTextAttrAlignment for a list of available styles.
     /**
         Returns the alignment flags.
         See ::wxTextAttrAlignment for a list of available styles.


@@ -295,6 +335,11 @@ public:
     */
     const wxString& GetFontFaceName() const;
 
     */
     const wxString& GetFontFaceName() const;
 

+    /**
+        Returns the font family.
+    */
+    wxFontFamily GetFontFamily() const;
+

     /**
         Returns the font size in points.
     */
     /**
         Returns the font size in points.
     */


@@ -303,7 +348,7 @@ public:
     /**
         Returns the font style.
     */
     /**
         Returns the font style.
     */

-    int GetFontStyle() const;
+    wxFontStyle GetFontStyle() const;

 
     /**
         Returns @true if the font is underlined.
 
     /**
         Returns @true if the font is underlined.


@@ -313,7 +358,7 @@ public:
     /**
         Returns the font weight.
     */
     /**
         Returns the font weight.
     */

-    int GetFontWeight() const;
+    wxFontWeight GetFontWeight() const;

 
     /**
         Returns the left indent in tenths of a millimetre.
 
     /**
         Returns the left indent in tenths of a millimetre.


@@ -394,6 +439,16 @@ public:
     */
     const wxString& GetURL() const;
 
     */
     const wxString& GetURL() const;
 

+    //@}
+
+
+
+    /**
+        @name HasXXX and IsXXX functions
+     */
+
+    //@{
+

     /**
         Returns @true if the attribute object specifies alignment.
     */
     /**
         Returns @true if the attribute object specifies alignment.
     */


@@ -451,6 +506,11 @@ public:
     */
     bool HasFontFaceName() const;
 
     */
     bool HasFontFaceName() const;
 

+    /**
+        Returns @true if the attribute object specifies a font family.
+    */
+    bool HasFontFamily() const;
+

     /**
         Returns @true if the attribute object specifies italic style.
     */
     /**
         Returns @true if the attribute object specifies italic style.
     */


@@ -557,19 +617,14 @@ public:
     */
     bool IsParagraphStyle() const;
 
     */
     bool IsParagraphStyle() const;
 

-    /**
-        Copies all defined/valid properties from overlay to current object.
-    */
-    void Merge(const wxTextAttr& overlay);
+    //@}
+

 
     /**
 
     /**

-        Creates a new @c wxTextAttr which is a merge of @a base and @a overlay.
+        @name SetXXX functions
+     */

 
 

-        Properties defined in @a overlay take precedence over those in @a base.
-        Properties undefined/invalid in both are undefined in the result.
-    */
-    static wxTextAttr Merge(const wxTextAttr& base,
-                            const wxTextAttr& overlay);
+    //@{

 
     /**
         Sets the paragraph alignment. See ::wxTextAttrAlignment enumeration values.
 
     /**
         Sets the paragraph alignment. See ::wxTextAttrAlignment enumeration values.


@@ -641,10 +696,15 @@ public:
     void SetFontEncoding(wxFontEncoding encoding);
 
     /**
     void SetFontEncoding(wxFontEncoding encoding);
 
     /**

-        Sets the paragraph alignment.
+        Sets the font face name.

     */
     void SetFontFaceName(const wxString& faceName);
 
     */
     void SetFontFaceName(const wxString& faceName);
 

+    /**
+        Sets the font family.
+    */
+    void SetFontFamily(wxFontFamily family);
+

     /**
         Sets the font size in points.
     */
     /**
         Sets the font size in points.
     */


@@ -653,7 +713,7 @@ public:
     /**
         Sets the font style (normal, italic or slanted).
     */
     /**
         Sets the font style (normal, italic or slanted).
     */

-    void SetFontStyle(int fontStyle);
+    void SetFontStyle(wxFontStyle fontStyle);

 
     /**
         Sets the font underlining.
 
     /**
         Sets the font underlining.


@@ -663,7 +723,7 @@ public:
     /**
         Sets the font weight.
     */
     /**
         Sets the font weight.
     */

-    void SetFontWeight(int fontWeight);
+    void SetFontWeight(wxFontWeight fontWeight);

 
     /**
         Sets the left indent and left subindent in tenths of a millimetre.
 
     /**
         Sets the left indent and left subindent in tenths of a millimetre.


@@ -772,6 +832,9 @@ public:
     */
     void SetURL(const wxString& url);
 
     */
     void SetURL(const wxString& url);
 

+    //@}
+
+

     /**
         Assignment from a wxTextAttr object.
     */
     /**
         Assignment from a wxTextAttr object.
     */


@@ -1044,7 +1107,7 @@ public:
         @see Create(), wxValidator
     */
     wxTextCtrl(wxWindow* parent, wxWindowID id,
         @see Create(), wxValidator
     */
     wxTextCtrl(wxWindow* parent, wxWindowID id,

-               const wxString& value = "",
+               const wxString& value = wxEmptyString,

                const wxPoint& pos = wxDefaultPosition,
                const wxSize& size = wxDefaultSize,
                long style = 0,
                const wxPoint& pos = wxDefaultPosition,
                const wxSize& size = wxDefaultSize,
                long style = 0,


@@ -1476,6 +1539,9 @@ public:
         Removes the text starting at the first given position up to
         (but not including) the character at the last position.
 
         Removes the text starting at the first given position up to
         (but not including) the character at the last position.
 

+        This function puts the current insertion point position at @a to as a
+        side effect.
+

         @param from
             The first position.
         @param to
         @param from
             The first position.
         @param to


@@ -1487,6 +1553,9 @@ public:
         Replaces the text starting at the first position up to
         (but not including) the character at the last position with the given text.
 
         Replaces the text starting at the first position up to
         (but not including) the character at the last position with the given text.
 

+        This function puts the current insertion point position at @a to as a
+        side effect.
+

         @param from
             The first position.
         @param to
         @param from
             The first position.
         @param to


@@ -1636,7 +1705,7 @@ public:
 
     /**
         Sets the new text control value.
 
     /**
         Sets the new text control value.

-       
+

         It also marks the control as not-modified which means that IsModified()
         would return @false immediately after the call to SetValue().
 
         It also marks the control as not-modified which means that IsModified()
         would return @false immediately after the call to SetValue().
 


@@ -1771,7 +1840,7 @@ public:
         @param ostr
             The C++ stream to redirect, cout is used if it is @NULL
     */
         @param ostr
             The C++ stream to redirect, cout is used if it is @NULL
     */

-    wxStreamToTextRedirector(wxTextCtrl text, ostream* ostr = NULL);
+    wxStreamToTextRedirector(wxTextCtrl *text, ostream* ostr);

 
     /**
         When a wxStreamToTextRedirector object is destroyed, the redirection is ended
 
     /**
         When a wxStreamToTextRedirector object is destroyed, the redirection is ended