<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>SpinButton</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="chapter-misc-widgets.html" title="Chapter 7. Miscellaneous Widgets">
<link rel="prev" href="sec-text-entry.html" title="Entry">
<link rel="next" href="sec-progressbar.html" title="ProgressBar">
</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">SpinButton</th></tr>
<tr>
<td width="20%" align="left">
<a accesskey="p" href="sec-text-entry.html"><img src="icons/prev.png" alt="Prev"></a> </td>
<th width="60%" align="center">Chapter 7. Miscellaneous Widgets</th>
<td width="20%" align="right"> <a accesskey="n" href="sec-progressbar.html"><img src="icons/next.png" alt="Next"></a>
</td>
</tr>
</table>
<hr>
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="sec-spinbutton"></a>SpinButton</h2></div></div></div>
<p>
A <code class="classname">SpinButton</code> allows the user to select a value from a
range of numeric values. It has an <code class="classname">Entry</code> widget with increment and decrement buttons
at the side. Clicking the buttons causes the value to 'spin' up and down across
the range of possible values. The <code class="classname">Entry</code> widget may also
be used to enter a value directly.
</p>
<p>
The value can have an adjustable number of decimal places, and the step size is
configurable. <code class="classname">SpinButton</code>s have an 'auto-repeat' feature
as well: holding down the increment or decrement button can optionally cause the value to
change more quickly the longer the button is held down.
</p>
<p>
<code class="classname">SpinButton</code>s use an <a class="link" href="chapter-adjustment.html" title="Chapter 14. Adjustments">Adjustment</a> object to hold information about
the range of values. These Adjustment attributes are used by the Spin Button
like so:
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>
<code class="literal">value</code>: value for the Spin Button
</p></li>
<li class="listitem"><p>
<code class="literal">lower</code>: lower range value
</p></li>
<li class="listitem"><p>
<code class="literal">upper</code>: upper range value
</p></li>
<li class="listitem"><p>
<code class="literal">step_increment</code>: value to increment/decrement when pressing
mouse button 1 on a button
</p></li>
<li class="listitem"><p>
<code class="literal">page_increment</code>: value to increment/decrement when pressing
mouse button 2 on a button
</p></li>
<li class="listitem"><p>
<code class="literal">page_size</code>: unused
</p></li>
</ul></div>
<p>
</p>
<p>
Additionally, mouse button 3 can be used to jump directly to the
<code class="literal">upper</code> or <code class="literal">lower</code> values.
</p>
<p>
The <code class="classname">SpinButton</code> can create a default
<code class="classname">Adjustment</code>, which you can access via the
<code class="methodname">get_adjustment()</code> method, or you can specify an existing
<code class="classname">Adjustment</code> in the constructor.
</p>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="spinbutton-methods"></a>Methods</h3></div></div></div>
<p>
The number of decimal places can be altered using the
<code class="methodname">set_digits()</code> method.
</p>
<p>
You can set the spinbutton's value using the <code class="methodname">set_value()</code>
method, and retrieve it with <code class="methodname">get_value()</code>.
</p>
<p>
The <code class="methodname">spin()</code> method 'spins' the
<code class="classname">SpinButton</code>, as if its increment or decrement button had been clicked.
You need to specify a <code class="classname">Gtk::SpinType</code> to specify the
direction or new position.
</p>
<p>
To prevent the user from typing non-numeric characters into the entry box, pass
<code class="literal">true</code> to the <code class="methodname">set_numeric()</code> method.
</p>
<p>
To make the <code class="classname">SpinButton</code> 'wrap' between its upper and
lower bounds, use the <code class="methodname">set_wrap()</code> method.
</p>
<p>
To force it to snap to the nearest <code class="literal">step_increment</code>,
use <code class="methodname">set_snap_to_ticks()</code>.
</p>
<p><a class="ulink" href="http://developer.gnome.org/gtkmm/3.24/classGtk_1_1SpinButton.html" target="_top">Reference</a></p>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="spinbutton-example"></a>Example</h3></div></div></div>
<p>
Here's an example of a <code class="classname">SpinButton</code> in action:
</p>
<div class="figure">
<a name="figure-spinbutton"></a><p class="title"><b>Figure 7.6. SpinButton</b></p>
<div class="figure-contents"><div class="screenshot"><div><img src="figures/spinbutton.png" alt="SpinButton"></div></div></div>
</div>
<br class="figure-break"><p><a class="ulink" href="http://git.gnome.org/browse/gtkmm-documentation/tree/examples/book/spinbutton?h=gtkmm-3-24" target="_top">Source Code</a></p>
<p>File: <code class="filename">examplewindow.h</code> (For use with gtkmm 3, not gtkmm 2)
</p>
<pre class="programlisting">
#ifndef GTKMM_EXAMPLEWINDOW_H
#define GTKMM_EXAMPLEWINDOW_H
#include <gtkmm.h>
class ExampleWindow : public Gtk::Window
{
public:
ExampleWindow();
virtual ~ExampleWindow();
protected:
//Signal handlers:
void on_checkbutton_snap();
void on_checkbutton_numeric();
void on_spinbutton_digits_changed();
void on_button_close();
enum enumValueFormats
{
VALUE_FORMAT_INT,
VALUE_FORMAT_FLOAT
};
void on_button_getvalue(enumValueFormats display);
//Child widgets:
Gtk::Frame m_Frame_NotAccelerated, m_Frame_Accelerated;
Gtk::Box m_HBox_NotAccelerated, m_HBox_Accelerated,
m_HBox_Buttons;
Gtk::Box m_VBox_Main, m_VBox, m_VBox_Day, m_VBox_Month, m_VBox_Year,
m_VBox_Accelerated, m_VBox_Value, m_VBox_Digits;
Gtk::Label m_Label_Day, m_Label_Month, m_Label_Year,
m_Label_Value, m_Label_Digits,
m_Label_ShowValue;
Glib::RefPtr<Gtk::Adjustment> m_adjustment_day, m_adjustment_month, m_adjustment_year,
m_adjustment_value, m_adjustment_digits;
Gtk::SpinButton m_SpinButton_Day, m_SpinButton_Month, m_SpinButton_Year,
m_SpinButton_Value, m_SpinButton_Digits;
Gtk::CheckButton m_CheckButton_Snap, m_CheckButton_Numeric;
Gtk::Button m_Button_Int, m_Button_Float, m_Button_Close;
};
#endif //GTKMM_EXAMPLEWINDOW_H
</pre>
<p>File: <code class="filename">main.cc</code> (For use with gtkmm 3, not gtkmm 2)
</p>
<pre class="programlisting">
#include "examplewindow.h"
#include <gtkmm/application.h>
int main(int argc, char *argv[])
{
auto app = Gtk::Application::create(argc, argv, "org.gtkmm.example");
ExampleWindow window;
//Shows the window and returns when it is closed.
return app->run(window);
}
</pre>
<p>File: <code class="filename">examplewindow.cc</code> (For use with gtkmm 3, not gtkmm 2)
</p>
<pre class="programlisting">
#include "examplewindow.h"
#include <iostream>
#include <cstdio>
ExampleWindow::ExampleWindow()
:
m_Frame_NotAccelerated("Not accelerated"),
m_Frame_Accelerated("Accelerated"),
m_VBox_Main(Gtk::ORIENTATION_VERTICAL, 5),
m_VBox(Gtk::ORIENTATION_VERTICAL),
m_VBox_Day(Gtk::ORIENTATION_VERTICAL),
m_VBox_Month(Gtk::ORIENTATION_VERTICAL),
m_VBox_Year(Gtk::ORIENTATION_VERTICAL),
m_VBox_Accelerated(Gtk::ORIENTATION_VERTICAL),
m_VBox_Value(Gtk::ORIENTATION_VERTICAL),
m_VBox_Digits(Gtk::ORIENTATION_VERTICAL),
m_Label_Day("Day: ", Gtk::ALIGN_START),
m_Label_Month("Month: ", Gtk::ALIGN_START),
m_Label_Year("Year: ", Gtk::ALIGN_START),
m_Label_Value("Value: ", Gtk::ALIGN_START),
m_Label_Digits("Digits: ", Gtk::ALIGN_START),
m_adjustment_day( Gtk::Adjustment::create(1.0, 1.0, 31.0, 1.0, 5.0, 0.0) ),
m_adjustment_month( Gtk::Adjustment::create(1.0, 1.0, 12.0, 1.0, 5.0, 0.0) ),
m_adjustment_year( Gtk::Adjustment::create(2012.0, 1.0, 2200.0, 1.0, 100.0, 0.0) ),
m_adjustment_value( Gtk::Adjustment::create(0.0, -10000.0, 10000.0, 0.5, 100.0, 0.0) ),
m_adjustment_digits( Gtk::Adjustment::create(2.0, 1.0, 5.0, 1.0, 1.0, 0.0) ),
m_SpinButton_Day(m_adjustment_day),
m_SpinButton_Month(m_adjustment_month),
m_SpinButton_Year(m_adjustment_year),
m_SpinButton_Value(m_adjustment_value, 1.0, 2),
m_SpinButton_Digits(m_adjustment_digits),
m_CheckButton_Snap("Snap to 0.5-ticks"),
m_CheckButton_Numeric("Numeric only input mode"),
m_Button_Int("Value as Int"),
m_Button_Float("Value as Float"),
m_Button_Close("Close")
{
set_title("SpinButton");
m_VBox_Main.set_border_width(10);
add(m_VBox_Main);
m_VBox_Main.pack_start(m_Frame_NotAccelerated);
m_VBox.set_border_width(5);
m_Frame_NotAccelerated.add(m_VBox);
/* Day, month, year spinners */
m_VBox.pack_start(m_HBox_NotAccelerated, Gtk::PACK_EXPAND_WIDGET, 5);
m_VBox_Day.pack_start(m_Label_Day);
m_SpinButton_Day.set_wrap();
m_VBox_Day.pack_start(m_SpinButton_Day);
m_HBox_NotAccelerated.pack_start(m_VBox_Day, Gtk::PACK_EXPAND_WIDGET, 5);
m_VBox_Month.pack_start(m_Label_Month);
m_SpinButton_Month.set_wrap();
m_VBox_Month.pack_start(m_SpinButton_Month);
m_HBox_NotAccelerated.pack_start(m_VBox_Month, Gtk::PACK_EXPAND_WIDGET, 5);
m_VBox_Year.pack_start(m_Label_Year);
m_SpinButton_Year.set_wrap();
m_SpinButton_Year.set_size_request(55, -1);
m_VBox_Year.pack_start(m_SpinButton_Year);
m_HBox_NotAccelerated.pack_start(m_VBox_Year, Gtk::PACK_EXPAND_WIDGET, 5);
//Accelerated:
m_VBox_Main.pack_start(m_Frame_Accelerated);
m_VBox_Accelerated.set_border_width(5);
m_Frame_Accelerated.add(m_VBox_Accelerated);
m_VBox_Accelerated.pack_start(m_HBox_Accelerated, Gtk::PACK_EXPAND_WIDGET, 5);
m_HBox_Accelerated.pack_start(m_VBox_Value, Gtk::PACK_EXPAND_WIDGET, 5);
m_VBox_Value.pack_start(m_Label_Value);
m_SpinButton_Value.set_wrap();
m_SpinButton_Value.set_size_request(100, -1);
m_VBox_Value.pack_start(m_SpinButton_Value);
m_HBox_Accelerated.pack_start(m_VBox_Digits, Gtk::PACK_EXPAND_WIDGET, 5);
m_VBox_Digits.pack_start(m_Label_Digits);
m_SpinButton_Digits.set_wrap();
m_adjustment_digits->signal_value_changed().connect( sigc::mem_fun(*this,
&ExampleWindow::on_spinbutton_digits_changed) );
m_VBox_Digits.pack_start(m_SpinButton_Digits);
//CheckButtons:
m_VBox_Accelerated.pack_start(m_CheckButton_Snap);
m_CheckButton_Snap.set_active();
m_CheckButton_Snap.signal_clicked().connect( sigc::mem_fun(*this,
&ExampleWindow::on_checkbutton_snap) );
m_VBox_Accelerated.pack_start(m_CheckButton_Numeric);
m_CheckButton_Numeric.set_active();
m_CheckButton_Numeric.signal_clicked().connect( sigc::mem_fun(*this,
&ExampleWindow::on_checkbutton_numeric) );
//Buttons:
m_VBox_Accelerated.pack_start (m_HBox_Buttons, Gtk::PACK_SHRINK, 5);
m_Button_Int.signal_clicked().connect( sigc::bind( sigc::mem_fun(*this,
&ExampleWindow::on_button_getvalue), VALUE_FORMAT_INT) );
m_HBox_Buttons.pack_start(m_Button_Int, Gtk::PACK_EXPAND_WIDGET, 5);
m_Button_Float.signal_clicked().connect( sigc::bind( sigc::mem_fun(*this,
&ExampleWindow::on_button_getvalue), VALUE_FORMAT_FLOAT) );
m_HBox_Buttons.pack_start(m_Button_Float, Gtk::PACK_EXPAND_WIDGET, 5);
m_VBox_Accelerated.pack_start(m_Label_ShowValue);
m_Label_ShowValue.set_text("0");
//Close button:
m_Button_Close.signal_clicked().connect( sigc::mem_fun(*this,
&ExampleWindow::on_button_close) );
m_VBox_Main.pack_start(m_Button_Close, Gtk::PACK_SHRINK);
show_all_children();
}
ExampleWindow::~ExampleWindow()
{
}
void ExampleWindow::on_button_close()
{
hide();
}
void ExampleWindow::on_checkbutton_snap()
{
m_SpinButton_Value.set_snap_to_ticks( m_CheckButton_Snap.get_active() );
}
void ExampleWindow::on_checkbutton_numeric()
{
m_SpinButton_Value.set_numeric( m_CheckButton_Numeric.get_active() );
}
void ExampleWindow::on_spinbutton_digits_changed()
{
m_SpinButton_Value.set_digits( m_SpinButton_Digits.get_value_as_int() );
}
void ExampleWindow::on_button_getvalue(enumValueFormats display)
{
gchar buf[32];
if (display == VALUE_FORMAT_INT)
sprintf (buf, "%d", m_SpinButton_Value.get_value_as_int());
else
sprintf (buf, "%0.*f", m_SpinButton_Value.get_digits(),
m_SpinButton_Value.get_value());
m_Label_ShowValue.set_text(buf);
}
</pre>
</div>
</div>
<div class="navfooter">
<hr>
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left">
<a accesskey="p" href="sec-text-entry.html"><img src="icons/prev.png" alt="Prev"></a> </td>
<td width="20%" align="center"><a accesskey="u" href="chapter-misc-widgets.html"><img src="icons/up.png" alt="Up"></a></td>
<td width="40%" align="right"> <a accesskey="n" href="sec-progressbar.html"><img src="icons/next.png" alt="Next"></a>
</td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Entry </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"> ProgressBar</td>
</tr>
</table>
</div>
</body>
</html>
