libs/gtkmm2/gtk/gtkmm/button.h

   1 // -*- c++ -*-
   2 // Generated by gtkmmproc -- DO NOT MODIFY!
   3 #ifndef _GTKMM_BUTTON_H
   4 #define _GTKMM_BUTTON_H
   5
   6 #include <glibmm.h>
   7
   8 /* $Id$ */
   9
  10 /* box.h
  11  *
  12  * Copyright (C) 1998-2002 The gtkmm Development Team
  13  *
  14  * This library is free software; you can redistribute it and/or
  15  * modify it under the terms of the GNU Library General Public
  16  * License as published by the Free Software Foundation; either
  17  * version 2 of the License, or (at your option) any later version.
  18  *
  19  * This library is distributed in the hope that it will be useful,
  20  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  21  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  22  * Library General Public License for more details.
  23  *
  24  * You should have received a copy of the GNU Library General Public
  25  * License along with this library; if not, write to the Free
  26  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  27  */
  28
  29 #include <gtkmm/bin.h>
  30 #include <gtkmm/stockid.h>
  31
  32
  33 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  34 typedef struct _GtkButton GtkButton;
  35 typedef struct _GtkButtonClass GtkButtonClass;
  36 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  37
  38
  39 namespace Gtk
  40 { class Button_Class; } // namespace Gtk
  41 namespace Gtk
  42 {
  43
  44 namespace Stock { struct BuiltinStockID; }
  45
  46
  47 /** A widget that creates a signal when clicked on.
  48  *
  49  * This widget is generally used with a signal handler that is called when the button is pressed.
  50  * It can hold any valid child widget.  The most commonly used child is the Gtk::Label.
  51  *
  52  * @ingroup Widgets
  53  */
  54
  55 class Button : public Bin
  56 {
  57   public:
  58 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  59   typedef Button CppObjectType;
  60   typedef Button_Class CppClassType;
  61   typedef GtkButton BaseObjectType;
  62   typedef GtkButtonClass BaseClassType;
  63 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  64
  65   virtual ~Button();
  66
  67 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  68
  69 private:
  70   friend class Button_Class;
  71   static CppClassType button_class_;
  72
  73   // noncopyable
  74   Button(const Button&);
  75   Button& operator=(const Button&);
  76
  77 protected:
  78   explicit Button(const Glib::ConstructParams& construct_params);
  79   explicit Button(GtkButton* castitem);
  80
  81 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  82
  83 public:
  84 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  85   static GType get_type()      G_GNUC_CONST;
  86   static GType get_base_type() G_GNUC_CONST;
  87 #endif
  88
  89   ///Provides access to the underlying C GtkObject.
  90   GtkButton*       gobj()       { return reinterpret_cast<GtkButton*>(gobject_); }
  91
  92   ///Provides access to the underlying C GtkObject.
  93   const GtkButton* gobj() const { return reinterpret_cast<GtkButton*>(gobject_); }
  94
  95
  96 public:
  97   //C++ methods used to invoke GTK+ virtual functions:
  98
  99 protected:
 100   //GTK+ Virtual Functions (override these to change behaviour):
 101
 102   //Default Signal Handlers::
 103   virtual void on_pressed();
 104   virtual void on_released();
 105   virtual void on_clicked();
 106   virtual void on_enter();
 107   virtual void on_leave();
 108   virtual void on_activate();
 109
 110
 111 private:
 112
 113 public:
 114
 115   /** Create an empty button.
 116    * With an empty button, you can Gtk::Button::add() a widget
 117    * such as a Gtk::Pixmap or Gtk::Box.
 118    *
 119    * If you just wish to add a Gtk::Label,
 120    * you may want to
 121    * use the Gtk::Button(const Glib::ustring& label) ctor
 122    * directly instead.
 123    */
 124   Button();
 125
 126
 127   /** Simple Push Button with label.
 128    * Create a button with the given label inside. You won't be able
 129    * to add a widget in this button since it already has a Gtk::Label
 130    * in it
 131    */
 132   explicit Button(const Glib::ustring& label, bool mnemonic = false);
 133   explicit Button(const StockID& stock_id);
 134
 135
 136   void pressed();
 137
 138   void released();
 139
 140   void clicked();
 141
 142   void enter();
 143
 144   void leave();
 145
 146
 147   void set_relief(ReliefStyle newstyle);
 148
 149   ReliefStyle get_relief() const;
 150
 151
 152   /** Sets the text of the label of the button to @a str . This text is
 153    * also used to select the stock item if set_use_stock()
 154    * is used.
 155    *
 156    * This will also clear any previously set labels.
 157    * @param label A string.
 158    */
 159   void set_label(const Glib::ustring& label);
 160
 161   /** Fetches the text from the label of the button, as set by
 162    * set_label(). If the label text has not
 163    * been set the return value will be <tt>0</tt>. This will be the
 164    * case if you create an empty button with new() to
 165    * use as a container.
 166    * @return The text of the label widget. This string is owned
 167    * by the widget and must not be modified or freed.
 168    */
 169   Glib::ustring get_label() const;
 170
 171   /** If true, an underline in the text of the button label indicates
 172    * the next character should be used for the mnemonic accelerator key.
 173    * @param use_underline <tt>true</tt> if underlines in the text indicate mnemonics.
 174    */
 175   void set_use_underline(bool use_underline = true);
 176
 177   /** Returns whether an embedded underline in the button label indicates a
 178    * mnemonic. See set_use_underline().
 179    * @return <tt>true</tt> if an embedded underline in the button label
 180    * indicates the mnemonic accelerator keys.
 181    */
 182   bool get_use_underline() const;
 183
 184   /** If true, the label set on the button is used as a
 185    * stock id to select the stock item for the button.
 186    * @param use_stock <tt>true</tt> if the button should use a stock item.
 187    */
 188   void set_use_stock(bool use_stock = true);
 189
 190   /** Returns whether the button label is a stock item.
 191    * @return <tt>true</tt> if the button label is used to
 192    * select a stock item instead of being
 193    * used directly as the label text.
 194    */
 195   bool get_use_stock() const;
 196
 197
 198   /** Sets whether the button will grab focus when it is clicked with the mouse.
 199    * Making mouse clicks not grab focus is useful in places like toolbars where
 200    * you don't want the keyboard focus removed from the main area of the
 201    * application.
 202    *
 203    * Since: 2.4
 204    * @param focus_on_click Whether the button grabs focus when clicked with the mouse.
 205    */
 206   void set_focus_on_click(bool focus_on_click = true);
 207
 208   /** Returns whether the button grabs focus when it is clicked with the mouse.
 209    * See set_focus_on_click().
 210    * @return <tt>true</tt> if the button grabs focus when it is clicked with
 211    * the mouse.
 212    *
 213    * Since: 2.4.
 214    */
 215   bool get_focus_on_click() const;
 216
 217
 218   /** Sets the alignment of the child. This property has no effect unless
 219    * the child is a Gtk::Misc or a Gtk::Aligment.
 220    *
 221    * Since: 2.4
 222    * @param xalign The horizontal position of the child, 0.0 is left aligned,
 223    * 1.0 is right aligned.
 224    * @param yalign The vertical position of the child, 0.0 is top aligned,
 225    * 1.0 is bottom aligned.
 226    */
 227   void set_alignment(float xalign, float yalign);
 228
 229   /** Gets the alignment of the child in the button.
 230    *
 231    * Since: 2.4
 232    * @param xalign Return location for horizontal alignment.
 233    * @param yalign Return location for vertical alignment.
 234    */
 235   void get_alignment(float& xalign, float& yalign);
 236
 237
 238   /** Set the image of @a button  to the given widget. Note that
 239    * it depends on the show-button-images setting whether the
 240    * image will be displayed or not.
 241    *
 242    * Since: 2.6
 243    * @param image A widget to set as the image for the button.
 244    */
 245   void set_image(Widget& image);
 246
 247   /** Gets the widget that is currenty set as the image of @a button .
 248    * This may have been explicitly set by set_image()
 249    * or constructed by new_from_stock().
 250    *
 251    * Since: 2.6
 252    */
 253   Widget* get_image();
 254
 255   /** Gets the widget that is currenty set as the image of @a button .
 256    * This may have been explicitly set by set_image()
 257    * or constructed by new_from_stock().
 258    *
 259    * Since: 2.6
 260    */
 261   const Widget* get_image() const;
 262
 263
 264   Glib::SignalProxy0< void > signal_pressed();
 265
 266
 267   Glib::SignalProxy0< void > signal_released();
 268
 269
 270   Glib::SignalProxy0< void > signal_clicked();
 271
 272
 273   Glib::SignalProxy0< void > signal_enter();
 274
 275
 276   Glib::SignalProxy0< void > signal_leave();
 277
 278
 279   Glib::SignalProxy0< void > signal_activate();
 280
 281
 282   /** Text of the label widget inside the button
 283    *
 284    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 285    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 286    * the value of the property changes.
 287    */
 288   Glib::PropertyProxy<Glib::ustring> property_label() ;
 289
 290 /** Text of the label widget inside the button
 291    *
 292    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 293    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 294    * the value of the property changes.
 295    */
 296   Glib::PropertyProxy_ReadOnly<Glib::ustring> property_label() const;
 297
 298   /** The border relief style.
 299    *
 300    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 301    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 302    * the value of the property changes.
 303    */
 304   Glib::PropertyProxy<ReliefStyle> property_relief() ;
 305
 306 /** The border relief style.
 307    *
 308    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 309    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 310    * the value of the property changes.
 311    */
 312   Glib::PropertyProxy_ReadOnly<ReliefStyle> property_relief() const;
 313
 314   /** If set
 315    *
 316    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 317    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 318    * the value of the property changes.
 319    */
 320   Glib::PropertyProxy<bool> property_use_underline() ;
 321
 322 /** If set
 323    *
 324    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 325    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 326    * the value of the property changes.
 327    */
 328   Glib::PropertyProxy_ReadOnly<bool> property_use_underline() const;
 329
 330   /** If set
 331    *
 332    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 333    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 334    * the value of the property changes.
 335    */
 336   Glib::PropertyProxy<bool> property_use_stock() ;
 337
 338 /** If set
 339    *
 340    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 341    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 342    * the value of the property changes.
 343    */
 344   Glib::PropertyProxy_ReadOnly<bool> property_use_stock() const;
 345
 346   /** Whether the button grabs focus when it is clicked with the mouse.
 347    *
 348    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 349    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 350    * the value of the property changes.
 351    */
 352   Glib::PropertyProxy<bool> property_focus_on_click() ;
 353
 354 /** Whether the button grabs focus when it is clicked with the mouse.
 355    *
 356    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 357    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 358    * the value of the property changes.
 359    */
 360   Glib::PropertyProxy_ReadOnly<bool> property_focus_on_click() const;
 361
 362   /** Horizontal position of child in available space. 0.0 is left aligned
 363    *
 364    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 365    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 366    * the value of the property changes.
 367    */
 368   Glib::PropertyProxy<float> property_xalign() ;
 369
 370 /** Horizontal position of child in available space. 0.0 is left aligned
 371    *
 372    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 373    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 374    * the value of the property changes.
 375    */
 376   Glib::PropertyProxy_ReadOnly<float> property_xalign() const;
 377
 378   /** Vertical position of child in available space. 0.0 is top aligned
 379    *
 380    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 381    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 382    * the value of the property changes.
 383    */
 384   Glib::PropertyProxy<float> property_yalign() ;
 385
 386 /** Vertical position of child in available space. 0.0 is top aligned
 387    *
 388    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 389    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 390    * the value of the property changes.
 391    */
 392   Glib::PropertyProxy_ReadOnly<float> property_yalign() const;
 393
 394   /** Child widget to appear next to the button text.
 395    *
 396    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 397    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 398    * the value of the property changes.
 399    */
 400   Glib::PropertyProxy<Gtk::Widget*> property_image() ;
 401
 402 /** Child widget to appear next to the button text.
 403    *
 404    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 405    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 406    * the value of the property changes.
 407    */
 408   Glib::PropertyProxy_ReadOnly<Gtk::Widget*> property_image() const;
 409
 410
 411 };
 412
 413 /*! A Gtk::Button example.
 414  * Example 1: @link book/buttons/button/buttons.h @endlink
 415  * Example 2: @link book/buttons/button/buttons.cc @endlink
 416  * Example 3: @link book/buttons/button/main.cc @endlink
 417  */
 418
 419 } // namespace Gtk
 420
 421
 422 namespace Glib
 423 {
 424   /** @relates Gtk::Button
 425    * @param object The C instance
 426    * @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
 427    * @result A C++ instance that wraps this C instance.
 428    */
 429   Gtk::Button* wrap(GtkButton* object, bool take_copy = false);
 430 }
 431 #endif /* _GTKMM_BUTTON_H */
 432