<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Chapter 4. Buttons</title>
<link rel="stylesheet" href="style.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.75.1">
<link rel="home" href="index.html" title="Programming with gtkmm">
<link rel="up" href="index.html" title="Programming with gtkmm">
<link rel="prev" href="sec-helloworld.html" title="Hello World in gtkmm">
<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 4. Buttons</th></tr>
<tr>
<td width="20%" align="left">
<a accesskey="p" href="sec-helloworld.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" title="Chapter 4. Buttons">
<div class="titlepage"><div><div><h2 class="title">
<a name="chapter-button-widget"></a>Chapter 4. Buttons</h2></div></div></div>
<div class="toc">
<p><b>Table of Contents</b></p>
<ul>
<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>
<dt><span class="term">Push-Buttons</span></dt>
<dd><p>
<a class="ulink" href="http://library.gnome.org/devel/gtkmm/unstable/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://library.gnome.org/devel/gtkmm/unstable/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://library.gnome.org/devel/gtkmm/unstable/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">CheckBox</a> section.
</p></dd>
<dt><span class="term">Radio buttons</span></dt>
<dd><p>
<a class="ulink" href="http://library.gnome.org/devel/gtkmm/unstable/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" title="Button">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="sec-pushbuttons"></a>Button</h2></div></div></div>
<div class="sect2" title="Constructors">
<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>
Wherever possible you should use Stock items, to ensure consistency with other applications, and to improve the appearance of your applications by using icons. For instance,
</p>
<pre class="programlisting">Gtk::Button* pButton = new Gtk::Button(Gtk::Stock::OK);</pre>
<p>
This will use standard text, in all languages, with standard keyboard accelerators, with a standard icon.
</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://library.gnome.org/devel/gtkmm/unstable/classGtk_1_1Button.html" target="_top">Reference</a></p>
</div>
<div class="sect2" title="Example">
<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 4.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/cgit/gtkmm-documentation/tree/examples/book/buttons/button" target="_top">Source Code</a></p>
<p>File: <code class="filename">buttons.h</code>
</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>
</p>
<pre class="programlisting">
#include <gtkmm/main.h>
#include "buttons.h"
int main(int argc, char *argv[])
{
Gtk::Main kit(argc, argv);
Buttons buttons;
//Shows the window and returns when it is closed.
Gtk::Main::run(buttons);
return 0;
}
</pre>
<p>File: <code class="filename">buttons.cc</code>
</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>
<p>
Note that the <code class="classname">XPMLabelBox</code> class can be used to place XPMs and
labels into any widget that can be a container.
</p>
</div>
<div class="sect2" title="Signals">
<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 most of the time you will just handle the <code class="literal">clicked</code> signal:
</p>
<p>
</p>
<div class="variablelist"><dl>
<dt><span class="term"><code class="literal">pressed</code></span></dt>
<dd><p>
Emitted when the button is pressed.
</p></dd>
<dt><span class="term"><code class="literal">released</code></span></dt>
<dd><p>
Emitted when the button is released.
</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 moves over the button's window.
</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.
</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="sec-helloworld.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">Hello World in <span class="application">gtkmm</span> </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>
