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     Flags used by wxControl::Ellipsize function.
  11 */
  12 enum wxEllipsizeFlags
  13 {
  14     /// With this flag when calculating the size of the passed string, mnemonics
  15     /// characters (see wxControl::SetLabel) will be automatically reduced to a
  16     /// single character.
  17     /// This leads to correct calculations only if the string passed to Ellipsize()
  18     /// will be used with wxControl::SetLabel. If you don't want ampersand to
  19     /// be interpreted as mnemonics (e.g. because you use wxControl::SetLabelText)
  20     /// then don't use this flag.
  21     wxELLIPSIZE_PROCESS_MNEMONICS = 1,
  22
  23     /// This flag tells wxControl::Ellipsize to calculate the width of tab
  24     /// characters @c '\\t' as 6 spaces.
  25     wxELLIPSIZE_EXPAND_TAB = 2,
  26
  27     /// The default flags for wxControl::Ellipsize.
  28     wxELLIPSIZE_DEFAULT_FLAGS = wxELLIPSIZE_PROCESS_MNEMONICS|wxELLIPSIZE_EXPAND_TAB
  29 };
  30
  31
  32 /**
  33     The different ellipsization modes supported by the
  34     wxControl::Ellipsize function.
  35 */
  36 enum wxEllipsizeMode
  37 {
  38     /// Put the ellipsis at the start of the string, if the string needs ellipsization.
  39     wxELLIPSIZE_START,
  40
  41     /// Put the ellipsis in the middle of the string, if the string needs ellipsization.
  42     wxELLIPSIZE_MIDDLE,
  43
  44     /// Put the ellipsis at the end of the string, if the string needs ellipsization.
  45     wxELLIPSIZE_END
  46 };
  47
  48 /**
  49     @class wxControl
  50
  51     This is the base class for a control or "widget".
  52
  53     A control is generally a small window which processes user input and/or
  54     displays one or more item of data.
  55
  56     @beginEventEmissionTable{wxClipboardTextEvent}
  57     @event{EVT_TEXT_COPY(id, func)}
  58            Some or all of the controls content was copied to the clipboard.
  59     @event{EVT_TEXT_CUT(id, func)}
  60            Some or all of the controls content was cut (i.e. copied and
  61            deleted).
  62     @event{EVT_TEXT_PASTE(id, func)}
  63            Clipboard content was pasted into the control.
  64     @endEventTable
  65
  66     @library{wxcore}
  67     @category{ctrl}
  68
  69     @see wxValidator
  70 */
  71 class wxControl : public wxWindow
  72 {
  73 public:
  74     /**
  75         Simulates the effect of the user issuing a command to the item.
  76
  77         @see wxCommandEvent
  78     */
  79     virtual void Command(wxCommandEvent& event);
  80
  81     /**
  82         Replaces parts of the @a label string with ellipsis, if needed, so
  83         that it doesn't exceed @a maxWidth.
  84
  85         @param label
  86             The string to ellipsize
  87         @param dc
  88             The DC used to retrieve the character widths through the
  89             wxDC::GetPartialTextExtents() function.
  90         @param mode
  91             The ellipsization modes. See ::wxEllipsizeMode.
  92         @param maxWidth
  93             The maximum width of the returned string in pixels.
  94         @param flags
  95             One or more of the ::wxEllipsize
  96     */
  97     static wxString Ellipsize(const wxString& label, const wxDC& dc,
  98                               wxEllipsizeMode mode, int maxWidth,
  99                               int flags = wxELLIPSIZE_DEFAULT_FLAGS);
 100
 101     /**
 102         Returns the control's text.
 103
 104         @note The returned string contains mnemonics ("&" characters) if it has
 105               any, use GetLabelText() if they are undesired.
 106     */
 107     wxString GetLabel() const;
 108
 109     /**
 110         Returns the control's label without mnemonics.
 111     */
 112     wxString GetLabelText() const;
 113
 114     /**
 115         Returns the given @a label string without mnemonics ("&" characters).
 116     */
 117     static wxString GetLabelText(const wxString& label);
 118
 119     /**
 120         Removes the mnemonics ("&" characters) from the given string.
 121     */
 122     static wxString RemoveMnemonics(const wxString& str);
 123
 124     /**
 125         Escape the special mnemonics characters ("&") in the given string.
 126
 127         This function can be helpful if you need to set the controls label to a
 128         user-provided string. If the string contains ampersands, they wouldn't
 129         appear on the display but be used instead to indicate that the
 130         character following the first of them can be used as a control mnemonic.
 131         While this can sometimes be desirable (e.g. to allow the user to
 132         configure mnemonics of the controls), more often you will want to use
 133         this function before passing a user-defined string to SetLabel().
 134         Alternatively, if the label is entirely user-defined, you can just call
 135         SetLabelText() directly -- but this function must be used if the label
 136         is a combination of a part defined by program containing the control
 137         mnemonics and a user-defined part.
 138
 139         @param text
 140             The string such as it should appear on the display.
 141         @return
 142             The same string with the ampersands in it doubled.
 143      */
 144     static wxString EscapeMnemonics(const wxString& text);
 145
 146     /**
 147         Sets the item's text.
 148
 149         Any "&" characters in the @a label are special and indicate that the
 150         following character is a @e mnemonic for this control and can be used to
 151         activate it from the keyboard (typically by using @e Alt key in
 152         combination with it). To insert a literal ampersand character, you need
 153         to double it, i.e. use use "&&". If this behaviour is undesirable, use
 154         SetLabelText() instead.
 155     */
 156     void SetLabel(const wxString& label);
 157
 158     /**
 159         Sets the item's text to exactly the given string.
 160
 161         Unlike SetLabel(), this function shows exactly the @a text passed to it
 162         in the control, without interpreting ampersands in it in any way.
 163         Notice that it means that the control can't have any mnemonic defined
 164         for it using this function.
 165
 166         @see EscapeMnemonics()
 167      */
 168     void SetLabelText(const wxString& text);
 169 };
 170