<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Chapter 5. Buttons</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="Programming with gtkmm 3">
<link rel="up" href="index.html" title="Programming with gtkmm 3">
<link rel="prev" href="changes-gtkmm3.html" title="Chapter 4. Changes in gtkmm 3">
<link rel="next" href="sec-toggle-buttons.html" title="ToggleButton">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr><th colspan="3" align="center">Chapter 5. Buttons</th></tr>
<tr>
<td width="20%" align="left">
<a accesskey="p" href="changes-gtkmm3.html"><img src="icons/prev.png" alt="Prev"></a> </td>
<th width="60%" align="center"> </th>
<td width="20%" align="right"> <a accesskey="n" href="sec-toggle-buttons.html"><img src="icons/next.png" alt="Next"></a>
</td>
</tr>
</table>
<hr>
</div>
<div class="chapter">
<div class="titlepage"><div><div><h1 class="title">
<a name="chapter-button-widget"></a>Chapter 5. Buttons</h1></div></div></div>
<div class="toc">
<p><b>Table of Contents</b></p>
<ul class="toc">
<li><span class="sect1"><a href="chapter-button-widget.html#sec-pushbuttons">Button</a></span></li>
<li><span class="sect1"><a href="sec-toggle-buttons.html">ToggleButton</a></span></li>
<li><span class="sect1"><a href="sec-checkboxes.html">CheckButton</a></span></li>
<li><span class="sect1"><a href="sec-radio-buttons.html">RadioButton</a></span></li>
</ul>
</div>
<p>
<span class="application">gtkmm</span> provides four basic types of buttons:
</p>
<div class="variablelist"><dl class="variablelist">
<dt><span class="term">Push-Buttons</span></dt>
<dd><p>
<a class="ulink" href="http://developer.gnome.org/gtkmm/3.24/classGtk_1_1Button.html" target="_top"><code class="classname">Gtk::Button</code></a>. Standard buttons, usually
marked with a label or picture. Pushing one triggers an action. See the <a class="link" href="chapter-button-widget.html#sec-pushbuttons" title="Button">Button</a> section.
</p></dd>
<dt><span class="term">Toggle buttons</span></dt>
<dd><p>
<a class="ulink" href="http://developer.gnome.org/gtkmm/3.24/classGtk_1_1ToggleButton.html" target="_top"><code class="classname">Gtk::ToggleButton</code></a>.
Unlike a normal Button, which springs back up, a ToggleButton stays down until you
press it again. It might be useful as an on/off switch. See the <a class="link" href="sec-toggle-buttons.html" title="ToggleButton">ToggleButton</a> section.
</p></dd>
<dt><span class="term">Checkboxes</span></dt>
<dd><p>
<a class="ulink" href="http://developer.gnome.org/gtkmm/3.24/classGtk_1_1CheckButton.html" target="_top"><code class="classname">Gtk::CheckButton</code></a>.
These act like ToggleButtons, but show their state in small squares,
with their label at the side. They should be used in most situations
which require an on/off setting.
See the <a class="link" href="sec-checkboxes.html" title="CheckButton">CheckButton</a> section.
</p></dd>
<dt><span class="term">Radio buttons</span></dt>
<dd><p>
<a class="ulink" href="http://developer.gnome.org/gtkmm/3.24/classGtk_1_1RadioButton.html" target="_top"><code class="classname">Gtk::RadioButton</code></a>.
Named after the station selectors on old car
radios, these buttons are used in groups for options which are
mutually exclusive. Pressing one causes all the
others in its group to turn off. They are similar to
CheckBoxes (a small widget with a label at the side), but usually
look different.
See the <a class="link" href="sec-radio-buttons.html" title="RadioButton">RadioButton</a> section.
</p></dd>
</dl></div>
<p>
Note that, due to GTK+'s theming system, the appearance of these
widgets will vary. In the case of checkboxes and radio buttons, they
may vary considerably.
</p>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="sec-pushbuttons"></a>Button</h2></div></div></div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="pushbutton-constructors"></a>Constructors</h3></div></div></div>
<p>
There are two ways to create a Button. You can specify a label
string in the <code class="classname">Gtk::Button</code> constructor,
or set it later with <code class="methodname">set_label()</code>.
</p>
<p>To define an accelerator key for keyboard navigation, place an underscore before one of the label's characters and specify <code class="literal">true</code> for the optional <code class="literal">mnemonic</code> parameter. For instance:
</p>
<pre class="programlisting">Gtk::Button* pButton = new Gtk::Button("_Something", true);</pre>
<p>
Stock items have been recommended for use in buttons. From <span class="application">gtkmm</span>-3.10 they are deprecated.
They should not be used in newly-written code. However, the documentation of
<a class="ulink" href="http://developer.gnome.org/gtkmm/3.24/namespaceGtk_1_1Stock.html" target="_top">namespace Gtk::Stock</a>
shows recommended labels and named icons to show in buttons.
</p>
<p>
<code class="classname">Gtk::Button</code> is also
a container so you could put any other widget, such as a
<code class="classname">Gtk::Image</code> into it.
</p>
<p><a class="ulink" href="http://developer.gnome.org/gtkmm/3.24/classGtk_1_1Button.html" target="_top">Reference</a></p>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="pushbutton-example"></a>Example</h3></div></div></div>
<p>
This example creates a button with a picture and a label.
</p>
<div class="figure">
<a name="figure-buttons"></a><p class="title"><b>Figure 5.1. buttons example</b></p>
<div class="figure-contents"><div class="screenshot"><div><img src="figures/buttons.png" alt="buttons example"></div></div></div>
</div>
<br class="figure-break"><p><a class="ulink" href="http://git.gnome.org/browse/gtkmm-documentation/tree/examples/book/buttons/button?h=gtkmm-3-24" target="_top">Source Code</a></p>
<p>File: <code class="filename">buttons.h</code> (For use with gtkmm 3, not gtkmm 2)
</p>
<pre class="programlisting">
#ifndef GTKMM_EXAMPLE_BUTTONS_H
#define GTKMM_EXAMPLE_BUTTONS_H
#include <gtkmm/window.h>
#include <gtkmm/button.h>
class Buttons : public Gtk::Window
{
public:
Buttons();
virtual ~Buttons();
protected:
//Signal handlers:
void on_button_clicked();
//Child widgets:
Gtk::Button m_button;
};
#endif //GTKMM_EXAMPLE_BUTTONS_H
</pre>
<p>File: <code class="filename">main.cc</code> (For use with gtkmm 3, not gtkmm 2)
</p>
<pre class="programlisting">
#include "buttons.h"
#include <gtkmm/application.h>
int main(int argc, char *argv[])
{
auto app = Gtk::Application::create(argc, argv, "org.gtkmm.example");
Buttons buttons;
//Shows the window and returns when it is closed.
return app->run(buttons);
}
</pre>
<p>File: <code class="filename">buttons.cc</code> (For use with gtkmm 3, not gtkmm 2)
</p>
<pre class="programlisting">
#include "buttons.h"
#include <iostream>
Buttons::Buttons()
{
m_button.add_pixlabel("info.xpm", "cool button");
set_title("Pixmap'd buttons!");
set_border_width(10);
m_button.signal_clicked().connect( sigc::mem_fun(*this,
&Buttons::on_button_clicked) );
add(m_button);
show_all_children();
}
Buttons::~Buttons()
{
}
void Buttons::on_button_clicked()
{
std::cout << "The Button was clicked." << std::endl;
}
</pre>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="pushbutton-signals"></a>Signals</h3></div></div></div>
<p>
The <code class="classname">Gtk::Button</code> widget has the following signals,
but all except the <code class="literal">clicked</code> signal are deprecated
and should not be used in newly-written code:
</p>
<p>
</p>
<div class="variablelist"><dl class="variablelist">
<dt><span class="term"><code class="literal">pressed</code></span></dt>
<dd><p>
Emitted when the button is pressed.
Use <code class="methodname">Gtk::Widget::signal_button_press_event()</code> instead.
</p></dd>
<dt><span class="term"><code class="literal">released</code></span></dt>
<dd><p>
Emitted when the button is released.
Use <code class="methodname">Gtk::Widget::signal_button_release_event()</code> instead.
</p></dd>
<dt><span class="term"><code class="literal">clicked</code></span></dt>
<dd><p>
Emitted when the button is pressed and released.
</p></dd>
<dt><span class="term"><code class="literal">enter</code></span></dt>
<dd><p>
Emitted when the mouse pointer enters the button's window.
Use <code class="methodname">Gtk::Widget::signal_enter_notify_event()</code> instead.
</p></dd>
<dt><span class="term"><code class="literal">leave</code></span></dt>
<dd><p>
Emitted when the mouse pointer leaves the button's window.
Use <code class="methodname">Gtk::Widget::signal_leave_notify_event()</code> instead.
</p></dd>
</dl></div>
<p>
</p>
</div>
</div>
</div>
<div class="navfooter">
<hr>
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left">
<a accesskey="p" href="changes-gtkmm3.html"><img src="icons/prev.png" alt="Prev"></a> </td>
<td width="20%" align="center"> </td>
<td width="40%" align="right"> <a accesskey="n" href="sec-toggle-buttons.html"><img src="icons/next.png" alt="Next"></a>
</td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Chapter 4. Changes in <span class="application">gtkmm</span> 3 </td>
<td width="20%" align="center"><a accesskey="h" href="index.html"><img src="icons/home.png" alt="Home"></a></td>
<td width="40%" align="right" valign="top"> ToggleButton</td>
</tr>
</table>
</div>
</body>
</html>
