interface/wx/commandlinkbutton.h

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