X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/3da9cffc79cd41b5f1d0c517c8c945596751e86f..9e9574fe45b176ee74bba8fad7574cf9906145d1:/interface/wx/control.h diff --git a/interface/wx/control.h b/interface/wx/control.h index b7792221df..2c0f8f74e7 100644 --- a/interface/wx/control.h +++ b/interface/wx/control.h @@ -2,7 +2,6 @@ // Name: control.h // Purpose: interface of wxControl // Author: wxWidgets team -// RCS-ID: $Id$ // Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// @@ -86,6 +85,46 @@ enum wxEllipsizeMode 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 validator + Control validator. + @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. @@ -114,6 +153,47 @@ public: */ 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. @@ -121,7 +201,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 - 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); @@ -146,10 +226,9 @@ public: 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 - (currently only wxStaticText under GTK+ 2). If markup is not supported - by the control or platform, it is simply stripped and SetLabel() is - used with the resulting string. + 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 @@ -284,15 +363,22 @@ public: @param markup - String containing markup for the label. It may contain newline - characters and the markup tags described above. + 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. - Note that the string must be well-formed (e.g. all tags must be correctly - closed) and won't be shown at all otherwise. + + 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 */