avoid infinite recursion for richtooltops, (hopefully) fixes #15070

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

diff --git a/interface/wx/control.h b/interface/wx/control.h
index c319132a0e01f7818658ddc04a6c200d0d8174bd..2fd28f3c917163527fc52b5c156433f47d37a7fa 100644 (file)
--- a/interface/wx/control.h
+++ b/interface/wx/control.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of wxControl
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxControl
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

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

 /////////////////////////////////////////////////////////////////////////////
 
 /**
 /////////////////////////////////////////////////////////////////////////////
 
 /**


@@ -86,6 +86,44 @@ enum wxEllipsizeMode
 class wxControl : public wxWindow
 {
 public:
 class wxControl : public wxWindow
 {
 public:

+
+    /**
+        Constructs a control.
+
+        @param parent
+            Pointer to a parent window.
+        @param id
+            Control identifier. If wxID_ANY, will automatically create an identifier.
+        @param pos
+            Control position. wxDefaultPosition indicates that wxWidgets
+            should generate a default position for the control.
+        @param size
+            Control size. wxDefaultSize indicates that wxWidgets should generate
+            a default size for the window. If no suitable size can  be found, the
+            window will be sized to 20x20 pixels so that the window is visible but
+            obviously not correctly sized.
+        @param style
+            Control style. For generic window styles, please see wxWindow.
+        @param name
+            Control name.
+    */
+   wxControl(wxWindow *parent, wxWindowID id,
+             const wxPoint& pos = wxDefaultPosition,
+             const wxSize& size = wxDefaultSize, long style = 0,
+             const wxValidator& validator = wxDefaultValidator,
+             const wxString& name = wxControlNameStr);
+
+    /**
+       Default constructor to allow 2-phase creation.
+    */
+    wxControl();
+    
+    bool Create(wxWindow *parent, wxWindowID id,
+            const wxPoint& pos = wxDefaultPosition,
+            const wxSize& size = wxDefaultSize, long style = 0,
+            const wxValidator& validator = wxDefaultValidator,
+            const wxString& name = wxControlNameStr);
+

     /**
         Simulates the effect of the user issuing a command to the item.
 
     /**
         Simulates the effect of the user issuing a command to the item.
 


@@ -114,6 +152,47 @@ public:
     */
     wxString GetLabelText() const;
 
     */
     wxString GetLabelText() const;
 

+    /**
+        Determine the size needed by the control to leave the given area for
+        its text.
+
+        This function is mostly useful with control displaying short amounts of
+        text that can be edited by the user, e.g. wxTextCtrl, wxComboBox,
+        wxSearchCtrl etc. Typically it is used to size these controls for the
+        maximal amount of input they are supposed to contain, for example:
+        @code
+            // Create a control for post code entry.
+            wxTextCtrl* postcode = new wxTextCtrl(this, ...);
+
+            // And set its initial and minimal size to be big enough for
+            // entering 5 digits.
+            postcode->SetInitialSize(
+                postcode->GetSizeFromTextSize(
+                    postcode->GetTextExtent("99999")));
+        @endcode
+
+        Currently this method is only implemented for wxTextCtrl, wxComboBox
+        and wxChoice in wxMSW and wxGTK.
+
+        @param xlen The horizontal extent of the area to leave for text, in
+            pixels.
+        @param ylen The vertical extent of the area to leave for text, in
+            pixels. By default -1 meaning that the vertical component of the
+            returned size should be the default height of this control.
+        @return The size that the control should have to leave the area of the
+            specified size for its text. May return wxDefaultSize if this
+            method is not implemented for this particular control under the
+            current platform.
+
+        @since 2.9.5
+     */
+    wxSize GetSizeFromTextSize(int xlen, int ylen = -1) const;
+
+    /**
+        @overload
+    */
+    wxSize GetSizeFromTextSize(const wxSize& tsize) const;
+

     /**
         Sets the control's label.
 
     /**
         Sets the control's label.
 


@@ -121,7 +200,7 @@ public:
         following character is a @e mnemonic for this control and can be used to
         activate it from the keyboard (typically by using @e Alt key in
         combination with it). To insert a literal ampersand character, you need
         following character is a @e mnemonic for this control and can be used to
         activate it from the keyboard (typically by using @e Alt key in
         combination with it). To insert a literal ampersand character, you need

-        to double it, i.e. use use "&&". If this behaviour is undesirable, use
+        to double it, i.e. use "&&". If this behaviour is undesirable, use

         SetLabelText() instead.
     */
     void SetLabel(const wxString& label);
         SetLabelText() instead.
     */
     void SetLabel(const wxString& label);


@@ -138,6 +217,172 @@ public:
      */
     void SetLabelText(const wxString& text);
 
      */
     void SetLabelText(const wxString& text);
 

+    // NB: when writing docs for the following function remember that Doxygen
+    //     will always expand HTML entities (e.g. ") and thus we need to
+    //     write e.g. "<" to have in the output the "<" string.
+
+    /**
+        Sets the controls label to a string using markup.
+
+        Simple markup supported by this function can be used to apply different
+        fonts or colours to different parts of the control label when supported.
+        If markup is not supported by the control or platform, it is simply
+        stripped and SetLabel() is used with the resulting string.
+
+        For example,
+        @code
+            wxStaticText *text;
+            ...
+            text->SetLabelMarkup("<b>&amp;Bed</b> &amp;mp; "
+                                 "<span foreground='red'>breakfast</span> "
+                                 "available <big>HERE</big>");
+        @endcode
+        would show the string using bold, red and big for the corresponding
+        words under wxGTK but will simply show the string "Bed &amp; breakfast
+        available HERE" on the other platforms. In any case, the "B" of "Bed"
+        will be underlined to indicate that it can be used as a mnemonic for
+        this control.
+
+        The supported tags are:
+        <TABLE>
+            <TR>
+                <TD><b>Tag</b></TD>
+                <TD><b>Description</b></TD>
+            </TR>
+            <TR>
+                <TD>&lt;b&gt;</TD>
+                <TD>bold text</TD>
+            </TR>
+            <TR>
+                <TD>&lt;big&gt;</TD>
+                <TD>bigger text</TD>
+            </TR>
+            <TR>
+                <TD>&lt;i&gt;</TD>
+                <TD>italic text</TD>
+            </TR>
+            <TR>
+                <TD>&lt;s&gt;</TD>
+                <TD>strike-through text</TD>
+            </TR>
+            <TR>
+                <TD>&lt;small&gt;</TD>
+                <TD>smaller text</TD>
+            </TR>
+            <TR>
+                <TD>&lt;tt&gt;</TD>
+                <TD>monospaced text</TD>
+            </TR>
+            <TR>
+                <TD>&lt;u&gt;</TD>
+                <TD>underlined text</TD>
+            </TR>
+            <TR>
+                <TD>&lt;span&gt;</TD>
+                <TD>generic formatter tag, see the table below for supported
+                attributes.
+                </TD>
+            </TR>
+        </TABLE>
+
+        Supported @c &lt;span&gt; attributes:
+        <TABLE>
+            <TR>
+                <TD><b>Name</b></TD>
+                <TD><b>Description</b></TD>
+            </TR>
+            <TR>
+                <TD>foreground, fgcolor, color</TD>
+                <TD>Foreground text colour, can be a name or RGB value.</TD>
+            </TR>
+            <TR>
+                <TD>background, bgcolor</TD>
+                <TD>Background text colour, can be a name or RGB value.</TD>
+            </TR>
+            <TR>
+                <TD>font_family, face</TD>
+                <TD>Font face name.</TD>
+            </TR>
+            <TR>
+                <TD>font_weight, weight</TD>
+                <TD>Numeric value in 0..900 range or one of "ultralight",
+                "light", "normal" (all meaning non-bold), "bold", "ultrabold"
+                and "heavy" (all meaning bold).</TD>
+            </TR>
+            <TR>
+                <TD>font_style, style</TD>
+                <TD>Either "oblique" or "italic" (both with the same meaning)
+                or "normal".</TD>
+            </TR>
+            <TR>
+                <TD>size</TD>
+                <TD>The font size can be specified either as "smaller" or
+                "larger" relatively to the current font, as a CSS font size
+                name ("xx-small", "x-small", "small", "medium", "large",
+                "x-large" or "xx-large") or as a number giving font size in
+                1024th parts of a point, i.e. 10240 for a 10pt font.</TD>
+            </TR>
+        </TABLE>
+
+        This markup language is a strict subset of Pango markup (described at
+        http://library.gnome.org/devel/pango/unstable/PangoMarkupFormat.html)
+        and any tags and span attributes not documented above can't be used
+        under non-GTK platforms.
+
+        Also note that you need to escape the following special characters:
+        <TABLE>
+            <TR>
+                <TD><b>Special character</b></TD>
+                <TD><b>Escape as</b></TD>
+            </TR>
+            <TR>
+                <TD>@c &amp;</TD>
+                <TD>@c &amp;amp; or as @c &amp;&amp;</TD>
+            </TR>
+            <TR>
+                <TD>@c &apos;</TD>
+                <TD>@c &amp;apos;</TD>
+            </TR>
+            <TR>
+                <TD>@c &quot;</TD>
+                <TD>@c &amp;quot;</TD>
+            </TR>
+            <TR>
+                <TD>@c &lt;</TD>
+                <TD>@c &amp;lt;</TD>
+            </TR>
+            <TR>
+                <TD>@c &gt;</TD>
+                <TD>@c &amp;gt;</TD>
+            </TR>
+        </TABLE>
+
+        The non-escaped ampersand @c &amp; characters are interpreted as
+        mnemonics as with wxControl::SetLabel.
+
+
+        @param markup
+            String containing markup for the label. It may contain markup tags
+            described above and newline characters but currently only wxGTK and
+            wxOSX support multiline labels with markup, the generic
+            implementation (also used in wxMSW) only handles single line markup
+            labels. Notice that the string must be well-formed (e.g. all tags
+            must be correctly closed) and won't be shown at all otherwise.
+        @return
+            @true if the new label was set (even if markup in it was ignored)
+            or @false if we failed to parse the markup. In this case the label
+            remains unchanged.
+
+
+        Currently wxButton supports markup in all major ports (wxMSW, wxGTK and
+        wxOSX/Cocoa) while wxStaticText supports it in wxGTK and wxOSX and its
+        generic version (which can be used under MSW if markup support is
+        required). Extending support to more controls is planned in the future.
+
+        @since 2.9.2
+    */
+    bool SetLabelMarkup(const wxString& markup);
+

 
 public:     // static functions
     
 
 public:     // static functions
     


@@ -149,9 +394,8 @@ public:     // static functions
     /**
         Returns the given @a str string without mnemonics ("&" characters).
         
     /**
         Returns the given @a str string without mnemonics ("&" characters).
         

-        @note This function is identic to GetLabelText() and is provided both for symmetry
-              with the wxStaticText::RemoveMarkup() function and to allow to write more
-              readable code (since this function has a more descriptive name respect GetLabelText()).
+        @note This function is identical to GetLabelText() and is provided
+              mostly for symmetry with EscapeMnemonics().

     */
     static wxString RemoveMnemonics(const wxString& str);
 
     */
     static wxString RemoveMnemonics(const wxString& str);
 


@@ -179,11 +423,11 @@ public:     // static functions
 
     /**
         Replaces parts of the @a label string with ellipsis, if needed, so
 
     /**
         Replaces parts of the @a label string with ellipsis, if needed, so

-        that it doesn't exceed @a maxWidth.
-        
-        Note that this functions is guaranteed to always returns a string
-        whose rendering on the given DC takes less than @a maxWidth pixels
-        in horizontal.
+        that it fits into @a maxWidth pixels if possible.
+
+        Note that this function does @em not guarantee that the returned string
+        will always be shorter than @a maxWidth; if @a maxWidth is extremely
+        small, ellipsized text may be larger.

 
         @param label
             The string to ellipsize
 
         @param label
             The string to ellipsize