interface/wx/control.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        control.h
   3 // Purpose:     interface of wxControl
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     The different ellipsization modes supported by the
  11     wxControl::Ellipsize function.
  12 */
  13 enum wxEllipsizeMode
  14 {
  15     wxELLIPSIZE_START,
  16     wxELLIPSIZE_MIDDLE,
  17     wxELLIPSIZE_END
  18 };
  19
  20 /**
  21     @class wxControl
  22
  23     This is the base class for a control or "widget".
  24
  25     A control is generally a small window which processes user input and/or
  26     displays one or more item of data.
  27
  28     @library{wxcore}
  29     @category{ctrl}
  30
  31     @see wxValidator
  32 */
  33 class wxControl : public wxWindow
  34 {
  35 public:
  36     /**
  37         Simulates the effect of the user issuing a command to the item.
  38
  39         @see wxCommandEvent
  40     */
  41     virtual void Command(wxCommandEvent& event);
  42
  43     /**
  44         Replaces parts of the @a label string with ellipsis, if needed, so
  45         that it doesn't exceed @a maxWidth.
  46
  47         @param label
  48             The string to ellipsize
  49         @param dc
  50             The DC used to retrieve the character widths through the
  51             wxDC::GetPartialTextExtents() function.
  52         @param mode
  53             The ellipsization modes. See ::wxEllipsizeMode.
  54         @param maxWidth
  55             The maximum width of the returned string in pixels.
  56     */
  57     static wxString Ellipsize(const wxString& label, const wxDC& dc,
  58                               wxEllipsizeMode mode, int maxWidth);
  59
  60     /**
  61         Returns the control's text.
  62
  63         @note The returned string contains mnemonics ("&" characters) if it has
  64               any, use GetLabelText() if they are undesired.
  65     */
  66     wxString GetLabel() const;
  67
  68     /**
  69         Returns the control's label without mnemonics.
  70     */
  71     wxString GetLabelText() const;
  72
  73     /**
  74         Returns the given @a label string without mnemonics ("&" characters).
  75     */
  76     static wxString GetLabelText(const wxString& label);
  77
  78     /**
  79         Removes the mnemonics ("&" characters) from the given string.
  80     */
  81     static wxString RemoveMnemonics(const wxString& str);
  82
  83     /**
  84         Escape the special mnemonics characters ("&") in the given string.
  85
  86         This function can be helpful if you need to set the controls label to a
  87         user-provided string. If the string contains ampersands, they wouldn't
  88         appear on the display but be used instead to indicate that the
  89         character following the first of them can be used as a control mnemonic.
  90         While this can sometimes be desirable (e.g. to allow the user to
  91         configure mnemonics of the controls), more often you will want to use
  92         this function before passing a user-defined string to SetLabel().
  93         Alternatively, if the label is entirely user-defined, you can just call
  94         SetLabelText() directly -- but this function must be used if the label
  95         is a combination of a part defined by program containing the control
  96         mnemonics and a user-defined part.
  97
  98         @param text
  99             The string such as it should appear on the display.
 100         @return
 101             The same string with the ampersands in it doubled.
 102      */
 103     static wxString EscapeMnemonics(const wxString& text);
 104
 105     /**
 106         Sets the item's text.
 107
 108         Any "&" characters in the @a label are special and indicate that the
 109         following character is a @e mnemonic for this control and can be used to
 110         activate it from the keyboard (typically by using @e Alt key in
 111         combination with it). To insert a literal ampersand character, you need
 112         to double it, i.e. use use "&&". If this behaviour is undesirable, use
 113         SetLabelText() instead.
 114     */
 115     void SetLabel(const wxString& label);
 116
 117     /**
 118         Sets the item's text to exactly the given string.
 119
 120         Unlike SetLabel(), this function shows exactly the @a text passed to it
 121         in the control, without interpreting ampersands in it in any way.
 122         Notice that it means that the control can't have any mnemonic defined
 123         for it using this function.
 124
 125         @see EscapeMnemonics()
 126      */
 127     void SetLabelText(const wxString& text);
 128 };
 129