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, and is one of the most
  14     common elements of a GUI.
  15
  16     It may be placed on a @ref wxDialog "dialog box" or on a @ref wxPanel panel,
  17     or indeed on almost any other window.
  18
  19     @beginStyleTable
  20     @style{wxBU_LEFT}
  21            Left-justifies the label. Windows and GTK+ only.
  22     @style{wxBU_TOP}
  23            Aligns the label to the top of the button. Windows and GTK+ only.
  24     @style{wxBU_RIGHT}
  25            Right-justifies the bitmap label. Windows and GTK+ only.
  26     @style{wxBU_BOTTOM}
  27            Aligns the label to the bottom of the button. Windows and GTK+ only.
  28     @style{wxBU_EXACTFIT}
  29            Creates the button as small as possible instead of making it of the
  30            standard size (which is the default behaviour ).
  31     @style{wxBORDER_NONE}
  32            Creates a flat button. Windows and GTK+ only.
  33     @endStyleTable
  34
  35     @beginEventTable{wxCommandEvent}
  36     @event{EVT_BUTTON(id, func)}
  37            Process a wxEVT_COMMAND_BUTTON_CLICKED event, when the button is 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         Default ctor.
  51     */
  52     wxButton();
  53
  54     /**
  55         Constructor, creating and showing a button.
  56
  57         The preferred way to create standard buttons is to use default value of
  58         @a label. If no label is supplied and @a id is one of standard IDs from
  59         @ref page_stockitems "this list", a standard label will be used.
  60
  61         In addition to that, the button will be decorated with stock icons under GTK+ 2.
  62
  63         @param parent
  64             Parent window. Must not be @NULL.
  65         @param id
  66             Button identifier. A value of wxID_ANY indicates a default value.
  67         @param label
  68             Text to be displayed on the button.
  69         @param pos
  70             Button position.
  71         @param size
  72             Button size. If the default size is specified then the button is sized
  73             appropriately for the text.
  74         @param style
  75             Window style. See wxButton class description.
  76         @param validator
  77             Window validator.
  78         @param name
  79             Window name.
  80
  81         @see Create(), wxValidator
  82     */
  83     wxButton(wxWindow* parent, wxWindowID id,
  84              const wxString& label = wxEmptyString,
  85              const wxPoint& pos = wxDefaultPosition,
  86              const wxSize& size = wxDefaultSize,
  87              long style = 0,
  88              const wxValidator& validator = wxDefaultValidator,
  89              const wxString& name = wxButtonNameStr);
  90
  91     /**
  92         Destructor, destroying the button.
  93     */
  94     virtual ~wxButton();
  95
  96     /**
  97         Button creation function for two-step creation.
  98         For more details, see wxButton().
  99     */
 100     bool Create(wxWindow* parent, wxWindowID id,
 101                 const wxString& label = 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         Returns the default size for the buttons. It is advised to make all the dialog
 110         buttons of the same size and this function allows to retrieve the (platform and
 111         current font dependent size) which should be the best suited for this.
 112     */
 113     static wxSize GetDefaultSize();
 114
 115     /**
 116         Returns the string label for the button.
 117
 118         @see SetLabel()
 119     */
 120     wxString GetLabel() const;
 121
 122     /**
 123         This sets the button to be the default item in its top-level window
 124         (e.g. the panel or the dialog box containing it).
 125
 126         As normal, pressing return causes the default button to be depressed when
 127         the return key is pressed.
 128
 129         See also wxWindow::SetFocus() which sets the keyboard focus for windows
 130         and text panel items, and wxTopLevelWindow::SetDefaultItem().
 131
 132         @remarks Under Windows, only dialog box buttons respond to this function.
 133
 134         @return the old default item (possibly NULL)
 135     */
 136     virtual wxWindow* SetDefault();
 137
 138     /**
 139         Sets the string label for the button.
 140
 141         @param label
 142             The label to set.
 143     */
 144     void SetLabel(const wxString& label);
 145 };
 146