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     @library{wxcore}
  57     @category{ctrl}
  58
  59     @see wxValidator
  60 */
  61 class wxControl : public wxWindow
  62 {
  63 public:
  64     /**
  65         Simulates the effect of the user issuing a command to the item.
  66
  67         @see wxCommandEvent
  68     */
  69     virtual void Command(wxCommandEvent& event);
  70
  71     /**
  72         Replaces parts of the @a label string with ellipsis, if needed, so
  73         that it doesn't exceed @a maxWidth.
  74
  75         @param label
  76             The string to ellipsize
  77         @param dc
  78             The DC used to retrieve the character widths through the
  79             wxDC::GetPartialTextExtents() function.
  80         @param mode
  81             The ellipsization modes. See ::wxEllipsizeMode.
  82         @param maxWidth
  83             The maximum width of the returned string in pixels.
  84         @param flags
  85             One or more of the ::wxEllipsize
  86     */
  87     static wxString Ellipsize(const wxString& label, const wxDC& dc,
  88                               wxEllipsizeMode mode, int maxWidth,
  89                               int flags = wxELLIPSIZE_DEFAULT_FLAGS);
  90
  91     /**
  92         Returns the control's text.
  93
  94         @note The returned string contains mnemonics ("&" characters) if it has
  95               any, use GetLabelText() if they are undesired.
  96     */
  97     wxString GetLabel() const;
  98
  99     /**
 100         Returns the control's label without mnemonics.
 101     */
 102     wxString GetLabelText() const;
 103
 104     /**
 105         Returns the given @a label string without mnemonics ("&" characters).
 106     */
 107     static wxString GetLabelText(const wxString& label);
 108
 109     /**
 110         Removes the mnemonics ("&" characters) from the given string.
 111     */
 112     static wxString RemoveMnemonics(const wxString& str);
 113
 114     /**
 115         Escape the special mnemonics characters ("&") in the given string.
 116
 117         This function can be helpful if you need to set the controls label to a
 118         user-provided string. If the string contains ampersands, they wouldn't
 119         appear on the display but be used instead to indicate that the
 120         character following the first of them can be used as a control mnemonic.
 121         While this can sometimes be desirable (e.g. to allow the user to
 122         configure mnemonics of the controls), more often you will want to use
 123         this function before passing a user-defined string to SetLabel().
 124         Alternatively, if the label is entirely user-defined, you can just call
 125         SetLabelText() directly -- but this function must be used if the label
 126         is a combination of a part defined by program containing the control
 127         mnemonics and a user-defined part.
 128
 129         @param text
 130             The string such as it should appear on the display.
 131         @return
 132             The same string with the ampersands in it doubled.
 133      */
 134     static wxString EscapeMnemonics(const wxString& text);
 135
 136     /**
 137         Sets the item's text.
 138
 139         Any "&" characters in the @a label are special and indicate that the
 140         following character is a @e mnemonic for this control and can be used to
 141         activate it from the keyboard (typically by using @e Alt key in
 142         combination with it). To insert a literal ampersand character, you need
 143         to double it, i.e. use use "&&". If this behaviour is undesirable, use
 144         SetLabelText() instead.
 145     */
 146     void SetLabel(const wxString& label);
 147
 148     /**
 149         Sets the item's text to exactly the given string.
 150
 151         Unlike SetLabel(), this function shows exactly the @a text passed to it
 152         in the control, without interpreting ampersands in it in any way.
 153         Notice that it means that the control can't have any mnemonic defined
 154         for it using this function.
 155
 156         @see EscapeMnemonics()
 157      */
 158     void SetLabelText(const wxString& text);
 159 };
 160