interface/wx/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
  12     A button is a control that contains a text string, and is one of the most
  13     common elements of a GUI.
  14
  15     It may be placed on a @ref wxDialog "dialog box" or on a @ref wxPanel panel,
  16     or indeed on 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{wxCommandEvent}
  35     @event{EVT_BUTTON(id, func)}
  36            Process a wxEVT_COMMAND_BUTTON_CLICKED event, when the button is clicked.
  37     @endEventTable
  38
  39     @library{wxcore}
  40     @category{ctrl}
  41     <!-- @appearance{button.png} -->
  42
  43     @see wxBitmapButton
  44 */
  45 class wxButton : public wxControl
  46 {
  47 public:
  48     /**
  49         Default ctor.
  50     */
  51     wxButton();
  52
  53     /**
  54         Constructor, creating and showing a button.
  55
  56         The preferred way to create standard buttons is to use default value of
  57         @a label. If no label is supplied and @a id is one of standard IDs from
  58         @ref page_stockitems "this list", a standard label will be used.
  59
  60         In addition to that, 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 label
  67             Text to be displayed on the button.
  68         @param pos
  69             Button position.
  70         @param size
  71             Button size. If the default size is specified then the button is sized
  72             appropriately for the text.
  73         @param style
  74             Window style. See wxButton class description.
  75         @param validator
  76             Window validator.
  77         @param name
  78             Window name.
  79
  80         @see Create(), wxValidator
  81     */
  82     wxButton(wxWindow* parent, wxWindowID id,
  83              const wxString& label = wxEmptyString,
  84              const wxPoint& pos = wxDefaultPosition,
  85              const wxSize& size = wxDefaultSize,
  86              long style = 0,
  87              const wxValidator& validator = wxDefaultValidator,
  88              const wxString& name = wxButtonNameStr);
  89
  90     /**
  91         Destructor, destroying the button.
  92     */
  93     virtual ~wxButton();
  94
  95     /**
  96         Button creation function for two-step creation.
  97         For more details, see wxButton().
  98     */
  99     bool Create(wxWindow* parent, wxWindowID id,
 100                 const wxString& label = 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         Returns the default size for the buttons. It is advised to make all the dialog
 109         buttons of the same size and this function allows to retrieve the (platform and
 110         current font dependent size) which should be the best suited for this.
 111     */
 112     static wxSize GetDefaultSize();
 113
 114     /**
 115         Returns the string label for the button.
 116
 117         @see SetLabel()
 118     */
 119     wxString GetLabel() const;
 120
 121     /**
 122         This sets the button to be the default item in its top-level window
 123         (e.g. the panel or the dialog box containing it).
 124
 125         As normal, pressing return causes the default button to be depressed when
 126         the return key is pressed.
 127
 128         See also wxWindow::SetFocus() which sets the keyboard focus for windows
 129         and text panel items, and wxTopLevelWindow::SetDefaultItem().
 130
 131         @remarks Under Windows, only dialog box buttons respond to this function.
 132
 133         @return the old default item (possibly NULL)
 134     */
 135     virtual wxWindow* SetDefault();
 136
 137     /**
 138         Sets the string label for the button.
 139
 140         @param label
 141             The label to set.
 142     */
 143     void SetLabel(const wxString& label);
 144 };
 145