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