interface/button.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        button.h
   3 // Purpose:     interface of wxButton
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxButton
  11     @wxheader{button.h}
  12
  13     A button is a control that contains a text string,
  14     and is one of the most common elements of a GUI. It may be placed on a
  15     @ref overview_wxdialog "dialog box" or panel(), or indeed
  16     almost any other window.
  17
  18     @beginStyleTable
  19     @style{wxBU_LEFT}:
  20            Left-justifies the label. Windows and GTK+ only.
  21     @style{wxBU_TOP}:
  22            Aligns the label to the top of the button. Windows and GTK+ only.
  23     @style{wxBU_RIGHT}:
  24            Right-justifies the bitmap label. Windows and GTK+ only.
  25     @style{wxBU_BOTTOM}:
  26            Aligns the label to the bottom of the button. Windows and GTK+ only.
  27     @style{wxBU_EXACTFIT}:
  28            Creates the button as small as possible instead of making it of the
  29            standard size (which is the default behaviour ).
  30     @style{wxBORDER_NONE}:
  31            Creates a flat button. Windows and GTK+ only.
  32     @endStyleTable
  33
  34     @beginEventTable
  35     @event{EVT_BUTTON(id, func)}:
  36            Process a wxEVT_COMMAND_BUTTON_CLICKED event, when the button is
  37            clicked.
  38     @endEventTable
  39
  40     @library{wxcore}
  41     @category{ctrl}
  42     @appearance{button.png}
  43
  44     @see wxBitmapButton
  45 */
  46 class wxButton : public wxControl
  47 {
  48 public:
  49     //@{
  50     /**
  51         Constructor, creating and showing a button.
  52         The preferred way to create standard buttons is to use default value of
  53         @e label. If no label is supplied and @a id is one of standard IDs from
  54         @ref overview_stockitems "this list", standard label will be used. In addition
  55         to
  56         that, the button will be decorated with stock icons under GTK+ 2.
  57
  58         @param parent
  59             Parent window. Must not be @NULL.
  60         @param id
  61             Button identifier. A value of wxID_ANY indicates a default value.
  62         @param label
  63             Text to be displayed on the button.
  64         @param pos
  65             Button position.
  66         @param size
  67             Button size. If the default size is specified then the button is sized
  68             appropriately for the text.
  69         @param style
  70             Window style. See wxButton.
  71         @param validator
  72             Window validator.
  73         @param name
  74             Window name.
  75
  76         @see Create(), wxValidator
  77     */
  78     wxButton();
  79     wxButton(wxWindow* parent, wxWindowID id,
  80              const wxString& label = wxEmptyString,
  81              const wxPoint& pos = wxDefaultPosition,
  82              const wxSize& size = wxDefaultSize,
  83              long style = 0,
  84              const wxValidator& validator = wxDefaultValidator,
  85              const wxString& name = "button");
  86     //@}
  87
  88     /**
  89         Destructor, destroying the button.
  90     */
  91     ~wxButton();
  92
  93     /**
  94         Button creation function for two-step creation. For more details, see
  95         wxButton().
  96     */
  97     bool Create(wxWindow* parent, wxWindowID id,
  98                 const wxString& label = wxEmptyString,
  99                 const wxPoint& pos = wxDefaultPosition,
 100                 const wxSize& size = wxDefaultSize,
 101                 long style = 0,
 102                 const wxValidator& validator,
 103                 const wxString& name = "button");
 104
 105     /**
 106         Returns the default size for the buttons. It is advised to make all the dialog
 107         buttons of the same size and this function allows to retrieve the (platform and
 108         current font dependent size) which should be the best suited for this.
 109     */
 110     wxSize GetDefaultSize();
 111
 112     /**
 113         Returns the string label for the button.
 114
 115         @returns The button's label.
 116
 117         @see SetLabel()
 118     */
 119     wxString GetLabel() const;
 120
 121     /**
 122         This sets the button to be the default item for the panel or dialog
 123         box.
 124
 125         @remarks Under Windows, only dialog box buttons respond to this function.
 126                   As normal under Windows and Motif, pressing return
 127                  causes the default button to be depressed when the
 128                  return key is pressed. See also wxWindow::SetFocus
 129                  which sets the keyboard focus for windows and text
 130                  panel items, and wxTopLevelWindow::SetDefaultItem.
 131     */
 132     void SetDefault();
 133
 134     /**
 135         Sets the string label for the button.
 136
 137         @param label
 138             The label to set.
 139     */
 140     void SetLabel(const wxString& label);
 141 };
 142