interface/wx/commandlinkbutton.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/commandlinkbutton.h
   3 // Purpose:     interface of wxCommandLinkButton
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxCommandLinkButton
  11
  12     Objects of this class are similar in appearance to the normal wxButtons but
  13     to the links in a web page in functionality.
  14
  15     Pressing such button usually results in switching to another window of the
  16     program and so they can be used as a replacement for the "Next" button in a
  17     multi-page dialog (such as wxWizard), for example.
  18
  19     Their advantage compared to the ordinary wxButtons is that they emphasize
  20     the action of switching the window and also that they allow to give more
  21     detailed explanation to the user because, in addition to the short button
  22     label, they also show a longer description string.
  23
  24     The short, title-like, part of the label is called the <em>main label</em>
  25     and the longer description is the <em>note</em>. Both of them can be set
  26     and queried independently using wxCommandLinkButton-specific methods such
  27     as SetMainLabel() or GetNote() or also via SetLabel() and GetLabel()
  28     methods inherited from wxButton. When using the latter, the main label and
  29     the note are concatenated into a single string using a new line character
  30     between them (notice that the note part can have more new lines in it).
  31
  32     wxCommandLinkButton generates the same event as wxButton but doesn't
  33     support any of wxButton-specific styles nor adds any new styles of its own.
  34
  35     Currently this class uses native implementation under Windows Vista and
  36     later versions and a generic implementation for the other platforms and
  37     earlier Windows versions.
  38
  39     @since 2.9.2
  40
  41     @library{wxadv}
  42     @category{ctrl}
  43     @appearance{commandlinkbutton.png}
  44
  45     @see wxButton, wxBitmapButton
  46 */
  47 class wxCommandLinkButton : public wxButton
  48 {
  49 public:
  50     /**
  51         Default constructor.
  52
  53         Use Create() to really create the control.
  54     */
  55     wxCommandLinkButton();
  56
  57     /**
  58         Constructor really creating a command Link button.
  59
  60         The button will be decorated with stock icons under GTK+ 2.
  61
  62         @param parent
  63             Parent window. Must not be @NULL.
  64         @param id
  65             Button identifier. A value of wxID_ANY indicates a default value.
  66         @param mainLabel
  67             First line of text on the button, typically the label of an action
  68             that will be made when the button is pressed.
  69         @param note
  70             Second line of text describing the action performed when the button
  71             is pressed.
  72         @param pos
  73             Button position.
  74         @param size
  75             Button size. If the default size is specified then the button is sized
  76             appropriately for the text.
  77         @param style
  78             Window style. See wxButton class description.
  79         @param validator
  80             Window validator.
  81         @param name
  82             Window name.
  83
  84         @see Create(), wxValidator
  85     */
  86     wxCommandLinkButton(wxWindow* parent, wxWindowID id,
  87                         const wxString& mainLabel = wxEmptyString,
  88                         const wxString& note = wxEmptyString,
  89                         const wxPoint& pos = wxDefaultPosition,
  90                         const wxSize& size = wxDefaultSize,
  91                         long style = 0,
  92                         const wxValidator& validator = wxDefaultValidator,
  93                         const wxString& name = wxButtonNameStr);
  94
  95     /**
  96         Button creation function for two-step creation.
  97         For more details, see wxCommandLinkButton().
  98     */
  99     bool Create(wxWindow* parent, wxWindowID id,
 100                 const wxString& mainLabel = wxEmptyString,
 101                 const wxString& note = wxEmptyString,
 102                 const wxPoint& pos = wxDefaultPosition,
 103                 const wxSize& size = wxDefaultSize,
 104                 long style = 0,
 105                 const wxValidator& validator = wxDefaultValidator,
 106                 const wxString& name = wxButtonNameStr);
 107
 108     /**
 109         Sets a new main label and note for the button.
 110
 111         Neither of the arguments can be empty, if you need to change just the
 112         label or just the note, use SetMainLabel() or SetNote() instead of this
 113         function.
 114
 115         @param mainLabel
 116             New main label to use.
 117         @param note
 118             New note to use.
 119     */
 120     void SetMainLabelAndNote(const wxString& mainLabel, const wxString& note);
 121
 122     /**
 123         Sets the string label and note for the button.
 124
 125         @param label
 126             The label and note to set, with the two separated
 127             by the first newline or none to set a blank note.
 128     */
 129     virtual void SetLabel(const wxString& label);
 130
 131     /**
 132         Returns the string label for the button.
 133
 134         @see SetLabel()
 135
 136         @return
 137             A string with the main label and note concatenated
 138             together with a newline separating them.
 139     */
 140     wxString GetLabel() const;
 141
 142     /**
 143         Changes the main label.
 144
 145         @param mainLabel
 146             New main label to use.
 147     */
 148     void SetMainLabel(const wxString& mainLabel);
 149
 150     /**
 151         Changes the note.
 152
 153         @param note
 154             New note to use.
 155     */
 156     void SetNote(const wxString& note);
 157
 158     /**
 159         Returns the current main label.
 160
 161         @return
 162             Main label currently displayed.
 163     */
 164     wxString GetMainLabel() const;
 165
 166     /**
 167         Returns the currently used note.
 168
 169         @return
 170             Note currently displayed.
 171     */
 172     wxString GetNote() const;
 173 };