Reference Manual

Main Page | Namespace List | Class Hierarchy | Alphabetical List | Compound List | File List | Namespace Members | Compound Members | File Members

# Inti::Gtk::SpinButton Class Reference

A GtkSpinButton C++ wrapper class. More...

`#include <inti/gtk/spinbutton.h>`

Inheritance diagram for Inti::Gtk::SpinButton:

List of all members.

## Public Member Functions

Constructors

- SpinButton ()
    Construct a new spin button.
- SpinButton (Adjustment *adjustment, double climb_rate, unsigned int digits)
    Construct a new spin button with the specified Adjustment, climb_rate and digits.
- SpinButton (double min, double max, double step=1.0)
    Construct a new spin button without specifying an Adjustment.
- virtual ~SpinButton ()
    Destructor.

Accessors

- GtkSpinButton * gtk_spin_button () const
    Get a pointer to the GtkSpinButton structure.
- GtkSpinButtonClass * gtk_spin_button_class () const
    Get a pointer to the GtkSpinButtonClass structure.
- operator GtkSpinButton * () const
    Conversion operator; safely converts a SpinButton to a GtkSpinButton pointer.
- Adjustment * get_adjustment () const
    Get the adjustment associated with the SpinButton.
- unsigned int get_digits () const
    Fetches the precision of the spin button (see set_digits()).
- void get_increments (double *step, double *page) const
    Gets the current step and page the increments used by the spin button (see set_increments()).
- void get_range (double *min, double *max) const
    Gets the range allowed for the spin button (see set_range()).
- double get_value () const
    Get the value in the spin button.
- int get_value_as_int () const
    Get the value of the spin button represented as an integer.
- SpinButtonUpdatePolicy get_update_policy () const
    Gets the update behavior of the spin button (see set_update_policy()).
- bool get_numeric () const
    Returns whether non-numeric text can be typed into the spin button (see set_numeric()).
- bool get_wrap () const
    Returns whether the spin button's value wraps around to the opposite limit when the upper or lower limit of the range is exceeded (see set_wrap()).
- bool get_snap_to_ticks () const
    Returns whether the values are corrected to the nearest step (see set_snap_to_ticks()).

Methods

- void configure (Adjustment *adjustment, double climb_rate, unsigned int digits)
    Changes the properties of an existing spin button.
- void set_adjustment (Adjustment *adjustment)
    Replaces the Adjustment associated with the spin button.
- void set_digits (unsigned int digits)
    Set the precision to be displayed by the spin button.
- void set_increments (double step, double page)
    Sets the step and page increments for the spin button.
- void set_range (double min, double max)
    Sets the minimum and maximum allowable values for the spin button.
- void set_value (double value)
    Set the value of the spin button.
- void set_update_policy (SpinButtonUpdatePolicy policy)
    Sets the update behavior of the spin button.
- void set_numeric (bool numeric)
    Sets the flag that determines if non-numeric text can be typed into the spin button.
- void spin (SpinType direction, double increment)
    Increment or decrement a spin button's value in a specified direction by a specified amount.
- void set_wrap (bool wrap)
    Sets the flag that determines if a spin button value wraps around to the opposite limit when the upper or lower limit of the range is exceeded.
- void set_snap_to_ticks (bool snap_to_ticks)
    Sets the policy as to whether values are corrected to the nearest step increment when a spin button is activated after providing an invalid value.
- void update ()
    Manually force an update of the spin button.

Property Proxies

- const AdjustmentPropertyProxy prop_adjustment ()
    The adjustment that holds the value of the spin button (Adjustment* : Read / Write).
- const ClimbRatePropertyProxy prop_climb_rate ()
    The acceleration rate when you hold down a button (double : Read / Write).
- const DigitsPropertyProxy prop_digits ()
    The number of decimal places to display (unsigned int : Read / Write).
- const SnapToTicksPropertyProxy prop_snap_to_ticks ()
    Whether erroneous values are automatically changed to a spin button's nearest step increment (bool : Read / Write).
- const NumericPropertyProxy prop_numeric ()
    Whether non-numeric characters should be ignored (bool : Read / Write).
- const WrapPropertyProxy prop_wrap ()
    Whether a spin button should wrap upon reaching its limits (bool : Read / Write).
- const UpdatePolicyPropertyProxy prop_update_policy ()
    Whether the spin button should update always, or only when the value is legal (SpinButtonUpdatePolicy : Read / Write).
- const ValuePropertyProxy prop_value ()
    Reads the current value, or sets a new value (double : Read / Write).

Signal Proxies

- const InputSignalProxy sig_input ()
    Connect to the input_signal; emitted when a new value is displayed in the spin button.
- const OutputSignalProxy sig_output ()
    Connect to the output_signal; emitted to display the new value in the spin button.
- const ValueChangedSignalProxy sig_value_changed ()
    Connect to the value_changed_signal; emitted when the value has changed.

## Protected Member Functions

Constructors

- SpinButton (GtkSpinButton *spin_button, bool reference=false)
    Construct a new SpinButton from an existing GtkSpinButton.

Signal Handlers

- virtual int on_input (double *new_value)
    Called when a new value is displayed in the spinbutton.
- virtual int on_output ()
    Called to display the new value in the spin button.
- virtual void on_value_changed ()
    Called when the value has changed.

## Detailed Description

A GtkSpinButton C++ wrapper class.

A SpinButton is an ideal way to allow the user to set the value of some attribute. Rather than having to directly type a number into a Entry, SpinButton allows the user to click on one of two arrows to increment or decrement the displayed value. A value can still be typed in, with the bonus that it can be checked to ensure it is in a given range. The main properties of a SpinButton are through an Adjustment. See the Adjustment section for more details about an adjustment's properties.

Example 1: Using a SpinButton to get an integer.

        #include <inti/main.h>
        #include <inti/gtk/window.h>
        #include <inti/gtk/adjustment.h>
        #include <inti/gtk/spinbutton.h>

        using namespace Inti;

        class Window : public Gtk::Window
        {
            Gtk::SpinButton *spinner;
        public:
            Window();
            int grab_value() const;
        };

        Window::Window()
        {
            set_border_width(5);
            Gtk::Adjustment *spinner_adj = new Gtk::Adjustment(50.0, 0.0, 100.0, 1.0, 5.0, 5.0);

            // Creates the spinner, with no decimal places.
            spinner = new Gtk::SpinButton(spinner_adj, 1.0, 0);
            add(*spinner);
            show_all();
        }

        int
        Window::grab_value() const
        {
            return spinner->get_value_as_int();
        }

        int main (int argc, char *argv[])
        {
            using namespace Main;

            init(&argc, &argv);

            Window window;
            window.sig_destroy().connect(slot(&Inti::Main::quit));

            run();
            return 0;
        }

Example 2: Using a SpinButton to get a floating point value.

        #include <inti/main.h>
        #include <inti/gtk/window.h>
        #include <inti/gtk/adjustment.h>
        #include <inti/gtk/spinbutton.h>

        using namespace Inti;

        class Window : public Gtk::Window
        {
            Gtk::SpinButton *spinner;
        public:
            Window();
            double grab_value() const;
        };

        Window::Window()
        {
            set_border_width(5);
            Gtk::Adjustment *spinner_adj = new Gtk::Adjustment(2.500, 0.0, 5.0, 0.001, 0.1, 0.1);

            // Creates the spinner, with no decimal places.
            spinner = new Gtk::SpinButton(spinner_adj, 0.001, 3);
            add(*spinner);
            show_all();
        }

        double
        Window::grab_value() const
        {
            return spinner->get_value();
        }

        int main (int argc, char *argv[])
        {
            using namespace Main;

            init(&argc, &argv);

            Window window;
            window.sig_destroy().connect(slot(&Inti::Main::quit));

            run();
            return 0;
        }

## Constructor & Destructor Documentation

Inti::Gtk::SpinButton::SpinButton | ( | GtkSpinButton * | spin_button,
|  | bool | reference = false
| ) | `[explicit, protected]`

Construct a new SpinButton from an existing GtkSpinButton.

Parameters:

  spin_button | A pointer to a GtkSpinButton.
  reference | Set false if the initial reference count is floating, set true if it's not.

The spin_button can be a newly created GtkSpinButton or an existing GtkSpinButton (see G::Object::Object).

Inti::Gtk::SpinButton::SpinButton | ( | Adjustment * | adjustment,
|  | double | climb_rate,
|  | unsigned int | digits
| ) |

Construct a new spin button with the specified Adjustment, climb_rate and digits.

Parameters:

  adjustment | The Adjustment object that this spin button should use.
  climb_rate | Specifies how much the spin button changes when an arrow is clicked on.
  digits | The number of decimal places to display.

Inti::Gtk::SpinButton::SpinButton | ( | double | min,
|  | double | max,
|  | double | step = 1.0
| ) |

Construct a new spin button without specifying an Adjustment.

Parameters:

  min | The minimum allowable value.
  max | The maximum allowable value.
  step | The increment added or subtracted by spinning the widget.

This is a convenience constructor that allows creation of a numeric SpinButton without manually creating an adjustment. The value is initially set to the minimum value and a page increment of 10 * step is the default. The precision of the spinbutton is equivalent to the precision of step.

## Member Function Documentation

void Inti::Gtk::SpinButton::configure | ( | Adjustment * | adjustment,
|  | double | climb_rate,
|  | unsigned int | digits
| ) |

Changes the properties of an existing spin button.

Parameters:

  adjustment | The new Adjustment object this spin button should use.
  climb_rate | How much the spin button changes when an arrow is clicked on.
  digits | The number of decimal places to display in the spin button.

The adjustment, climb rate, and number of decimal places are all changed accordingly, after this function call.

unsigned int Inti::Gtk::SpinButton::get_digits | ( |  | ) | const

Fetches the precision of the spin button (see set_digits()).

Returns:
  The current precision.

void Inti::Gtk::SpinButton::get_increments | ( | double * | step,
|  | double * | page
| ) | const

Gets the current step and page the increments used by the spin button (see set_increments()).

Parameters:

  step | The location to store step increment, or null.
  page | The location to store page increment, or null.

bool Inti::Gtk::SpinButton::get_numeric | ( |  | ) | const

Returns whether non-numeric text can be typed into the spin button (see set_numeric()).

Returns:
  true if only numeric text can be entered.

void Inti::Gtk::SpinButton::get_range | ( | double * | min,
|  | double * | max
| ) | const

Gets the range allowed for the spin button (see set_range()).

Parameters:

  min | The location to store minimum allowed value, or null.
  max | The location to store maximum allowed value, or null.

bool Inti::Gtk::SpinButton::get_snap_to_ticks | ( |  | ) | const

Returns whether the values are corrected to the nearest step (see set_snap_to_ticks()).

Returns:
  true if values are snapped to the nearest step.

SpinButtonUpdatePolicy Inti::Gtk::SpinButton::get_update_policy | ( |  | ) | const

Gets the update behavior of the spin button (see set_update_policy()).

Returns:
  The current update policy.

int Inti::Gtk::SpinButton::get_value_as_int | ( |  | ) | const

Get the value of the spin button represented as an integer.

Returns:
  The value of the spin button.

bool Inti::Gtk::SpinButton::get_wrap | ( |  | ) | const

Returns whether the spin button's value wraps around to the opposite limit when the upper or lower limit of the range is exceeded (see set_wrap()).

Returns:
  true if the spin button wraps around.

virtual int Inti::Gtk::SpinButton::on_input | ( | double * | new_value | ) | `[protected, virtual]`

Called when a new value is displayed in the spinbutton.

Parameters:

  new_value | The new value of the spin button.

Returns:
  -1 if an error occurs, otherwise 0.

virtual int Inti::Gtk::SpinButton::on_output | ( |  | ) | `[protected, virtual]`

Called to display the new value in the spin button.

Returns:
  Always zero.

void Inti::Gtk::SpinButton::set_adjustment | ( | Adjustment * | adjustment | ) |

Replaces the Adjustment associated with the spin button.

Parameters:

  adjustment | An Adjustment to replace the existing adjustment.

void Inti::Gtk::SpinButton::set_digits | ( | unsigned int | digits | ) |

Set the precision to be displayed by the spin button.

Parameters:

  digits | The number of digits to be displayed for the spin button's value.

Up to 20 digit precision is allowed.

void Inti::Gtk::SpinButton::set_increments | ( | double | step,
|  | double | page
| ) |

Sets the step and page increments for the spin button.

Parameters:

  step | The increment applied for a button 1 press.
  page | The increment applied for a button 2 press.

This affects how quickly the value changes when the spin button's arrows are activated.

void Inti::Gtk::SpinButton::set_numeric | ( | bool | numeric | ) |

Sets the flag that determines if non-numeric text can be typed into the spin button.

Parameters:

  numeric | true if only numeric entry is allowed.

void Inti::Gtk::SpinButton::set_range | ( | double | min,
|  | double | max
| ) |

Sets the minimum and maximum allowable values for the spin button.

Parameters:

  min | The minimum allowable value.
  max | The maximum allowable value.

void Inti::Gtk::SpinButton::set_snap_to_ticks | ( | bool | snap_to_ticks | ) |

Sets the policy as to whether values are corrected to the nearest step increment when a spin button is activated after providing an invalid value.

Parameters:

  snap_to_ticks | A flag indicating if invalid values should be corrected.

void Inti::Gtk::SpinButton::set_update_policy | ( | SpinButtonUpdatePolicy | policy | ) |

Sets the update behavior of the spin button.

Parameters:

  policy | A SpinButtonUpdatePolicy value.

This determines whether the spin button is always updated or only when a valid value is set.

void Inti::Gtk::SpinButton::set_value | ( | double | value | ) |

Set the value of the spin button.

Parameters:

  value | The new value.

void Inti::Gtk::SpinButton::set_wrap | ( | bool | wrap | ) |

Sets the flag that determines if a spin button value wraps around to the opposite limit when the upper or lower limit of the range is exceeded.

Parameters:

  wrap | true if wrapping behavior is performed.

void Inti::Gtk::SpinButton::spin | ( | SpinType | direction,
|  | double | increment
| ) |

Increment or decrement a spin button's value in a specified direction by a specified amount.

Parameters:

  direction | A SpinType indicating the direction to spin.
  increment | The step increment to apply in the specified direction.

The documentation for this class was generated from the following file:

- spinbutton.h

Main Page - Footer