interface/button.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        button.h
   3 // Purpose:     documentation for wxButton class
   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     @seealso
  45     wxBitmapButton
  46 */
  47 class wxButton : public wxControl
  48 {
  49 public:
  50     //@{
  51     /**
  52         Constructor, creating and showing a button.
  53
  54         The preferred way to create standard buttons is to use default value of
  55         @e label. If no label is supplied and @e id is one of standard IDs from
  56         @ref overview_stockitems "this list", standard label will be used. In addition
  57         to
  58         that, the button will be decorated with stock icons under GTK+ 2.
  59
  60         @param parent
  61         Parent window. Must not be @NULL.
  62
  63         @param id
  64         Button identifier. A value of wxID_ANY indicates a default value.
  65
  66         @param label
  67         Text to be displayed on the button.
  68
  69         @param pos
  70         Button position.
  71
  72         @param size
  73         Button size. If the default size is specified then the button is sized
  74         appropriately for the text.
  75
  76         @param style
  77         Window style. See wxButton.
  78
  79         @param validator
  80         Window validator.
  81
  82         @param name
  83         Window name.
  84
  85         @sa Create(), wxValidator
  86     */
  87     wxButton();
  88     wxButton(wxWindow* parent, wxWindowID id,
  89              const wxString& label = wxEmptyString,
  90              const wxPoint& pos = wxDefaultPosition,
  91              const wxSize& size = wxDefaultSize,
  92              long style = 0,
  93              const wxValidator& validator = wxDefaultValidator,
  94              const wxString& name = "button");
  95     //@}
  96
  97     /**
  98         Destructor, destroying the button.
  99     */
 100     ~wxButton();
 101
 102     /**
 103         Button creation function for two-step creation. For more details, see
 104         wxButton().
 105     */
 106     bool Create(wxWindow* parent, wxWindowID id,
 107                 const wxString& label = wxEmptyString,
 108                 const wxPoint& pos = wxDefaultPosition,
 109                 const wxSize& size = wxDefaultSize,
 110                 long style = 0,
 111                 const wxValidator& validator,
 112                 const wxString& name = "button");
 113
 114     /**
 115         Returns the default size for the buttons. It is advised to make all the dialog
 116         buttons of the same size and this function allows to retrieve the (platform and
 117         current font dependent size) which should be the best suited for this.
 118     */
 119     wxSize GetDefaultSize();
 120
 121     /**
 122         Returns the string label for the button.
 123
 124         @returns The button's label.
 125
 126         @sa SetLabel()
 127     */
 128     wxString GetLabel();
 129
 130     /**
 131         This sets the button to be the default item for the panel or dialog
 132         box.
 133
 134         @remarks Under Windows, only dialog box buttons respond to this function.
 135                     As normal under Windows and Motif, pressing return
 136                    causes the default button to be depressed when the
 137                    return key is pressed. See also wxWindow::SetFocus
 138                    which sets the keyboard focus for windows and text
 139                    panel items, and wxTopLevelWindow::SetDefaultItem.
 140     */
 141     void SetDefault();
 142
 143     /**
 144         Sets the string label for the button.
 145
 146         @param label
 147         The label to set.
 148     */
 149     void SetLabel(const wxString& label);
 150 };