<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>SpinButton</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="chapter-misc-widgets.html" title="Chapter 6. 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 6. 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" title="SpinButton">
<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 Entry widget with up and down arrow 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 one of the arrows can optionally cause the value to
change more quickly the longer the arrow is held down.
</p>
<p>
<code class="classname">SpinButton</code>s use an <a class="link" href="chapter-adjustment.html" title="Chapter 12. 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" 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" title="Methods">
<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 one of its arrows 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>
You can modify the update policy using the
<code class="methodname">set_update_policy()</code> method, specifying either
<code class="literal">Gtk::UPDATE_ALWAYS</code> or
<code class="literal">Gtk::UPDATE_IF_VALID</code>.
<code class="literal">Gtk::UPDATE_ALWAYS</code> causes the
<code class="classname">SpinButton</code> to ignore errors encountered while converting
the text in the entry box to a numeric value. This setting also therefore
allows the <code class="classname">SpinButton</code> to accept non-numeric values. You
can force an immediate update using the <code class="methodname">update()</code> method.
</p>
<p><a class="ulink" href="http://library.gnome.org/devel/gtkmm/unstable/classGtk_1_1SpinButton.html" target="_top">Reference</a></p>
</div>
<div class="sect2" title="Example">
<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 6.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/cgit/gtkmm-documentation/tree/examples/book/spinbutton" target="_top">Source Code</a></p>
<p>File: <code class="filename">examplewindow.h</code>
</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::HBox m_HBox_NotAccelerated, m_HBox_Accelerated,
m_HBox_Buttons;
Gtk::VBox 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;
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">examplewindow.cc</code>
</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(false, 5),
m_Label_Day("Day: "),
m_Label_Month("Month: "),
m_Label_Year("Year: "),
m_Label_Value("Value: "),
m_Label_Digits("Digits: "),
m_adjustment_day(1.0, 1.0, 31.0, 1.0, 5.0, 0.0),
m_adjustment_month(1.0, 1.0, 12.0, 1.0, 5.0, 0.0),
m_adjustment_year(1998.0, 0.0, 2100.0, 1.0, 100.0, 0.0),
m_adjustment_value(0.0, -10000.0, 10000.0, 0.5, 100.0, 0.0),
m_adjustment_digits(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_Label_Day.set_alignment(Gtk::ALIGN_LEFT);
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_Label_Month.set_alignment(Gtk::ALIGN_LEFT);
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_Label_Year.set_alignment(Gtk::ALIGN_LEFT);
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_Label_Value.set_alignment(Gtk::ALIGN_LEFT);
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_Label_Digits.set_alignment(Gtk::ALIGN_LEFT);
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>
<p>File: <code class="filename">main.cc</code>
</p>
<pre class="programlisting">
#include <gtkmm/main.h>
#include "examplewindow.h"
int main(int argc, char *argv[])
{
Gtk::Main kit(argc, argv);
ExampleWindow window;
//Shows the window and returns when it is closed.
Gtk::Main::run(window);
return 0;
}
</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>
