## PhatSliderButton

PhatSliderButton — retrieve an integer or floating-point number from the user

## Synopsis

                PhatSliderButton;
    GtkWidget*  phat_slider_button_new          (GtkAdjustment *adjustment,
                                                 int digits);
    GtkWidget*  phat_slider_button_new_with_range
                                                (double value,
                                                 double lower,
                                                 double upper,
                                                 double step,
                                                 int digits);
    void        phat_slider_button_set_value    (PhatSliderButton *button,
                                                 double value);
    double      phat_slider_button_get_value    (PhatSliderButton *button);
    void        phat_slider_button_set_range    (PhatSliderButton *button,
                                                 double lower,
                                                 double upper);
    void        phat_slider_button_get_range    (PhatSliderButton *button,
                                                 double *lower,
                                                 double *upper);
    void        phat_slider_button_set_adjustment
                                                (PhatSliderButton *button,
                                                 GtkAdjustment *adjustment);
    GtkAdjustment* phat_slider_button_get_adjustment
                                                (PhatSliderButton *button);
    void        phat_slider_button_set_increment
                                                (PhatSliderButton *button,
                                                 double step,
                                                 double page);
    void        phat_slider_button_get_increment
                                                (PhatSliderButton *button,
                                                 double *step,
                                                 double *page);
    void        phat_slider_button_set_format   (PhatSliderButton *button,
                                                 int digits,
                                                 const char *prefix,
                                                 const char *postfix);
    void        phat_slider_button_get_format   (PhatSliderButton *button,
                                                 int *digits,
                                                 char **prefix,
                                                 char **postfix);
    void        phat_slider_button_set_threshold
                                                (PhatSliderButton *button,
                                                 guint threshold);
    int         phat_slider_button_get_threshold
                                                (PhatSliderButton *button);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkObject
                   +----GtkWidget
                         +----GtkContainer
                               +----GtkBox
                                     +----GtkHBox
                                           +----PhatSliderButton

## Implemented Interfaces

PhatSliderButton implements AtkImplementorIface.

## Signals

    "changed"   void        user_function      (PhatSliderButton *button,
                                                gpointer          user_data)      : Run first / Action
    "value-changed"
                void        user_function      (PhatSliderButton *button,
                                                gpointer          user_data)      : Run first / Action

## Description

A PhatSliderButton can be used in place of a GtkSpinButton. It's a better choice than a PhatFanSlider when you want the user to clearly see the value they are setting, or want to constrain their selection to a set of discrete values (fansliders are "continuous").

Sliderbuttons allow the user to change the value by grabbing the widget and dragging. They can also make small "one off" adjustments via the arrow buttons, or click the button to enter the value directly. They have a slightly higher learning curve than standard spinbuttons, but they offer much more efficiency to the user.

The way the current value of a sliderbutton is displayed is controlled with a printf style format specifier supplied at widget creation. Since sliderbuttons operate with doubles, the specifier should be in the form of "%`f`" or any of the other double compatible printf escapes. You should resist the urge to embed other information in the format specifier, since that extra text will also wind up in the entry when the user clicks the button. Instead, use `phat_slider_button_set_format()` to set prefix and/or postfix text.

## Details

### PhatSliderButton

    typedef struct _PhatSliderButton PhatSliderButton;

The PhatSliderButton struct contains private data only, and should be accessed using the functions below.

### phat_slider_button_new ()

    GtkWidget*  phat_slider_button_new          (GtkAdjustment *adjustment,
                                                 int digits);

Creates a new PhatSliderButton.

`adjustment` : | the GtkAdjustment that the new button will use
`digits` : | number of decimal digits to display
Returns : | a newly created PhatSliderButton

### phat_slider_button_new_with_range ()

    GtkWidget*  phat_slider_button_new_with_range
                                                (double value,
                                                 double lower,
                                                 double upper,
                                                 double step,
                                                 int digits);

Creates a new PhatSliderButton. The slider will create a new GtkAdjustment from `value`, `lower`, `upper`, and `step`. If these parameters represent a bogus configuration, the program will terminate.

`value` : | the initial value the new button should have
`lower` : | the lowest value the new button will allow
`upper` : | the highest value the new button will allow
`step` : | increment added or subtracted when sliding
`digits` : | number of decimal digits to display
Returns : | a newly created PhatSliderButton

### phat_slider_button_set_value ()

    void        phat_slider_button_set_value    (PhatSliderButton *button,
                                                 double value);

Sets the current value of the button. If the value is outside the range of values allowed by `button`, it will be clamped. The button emits the "value-changed" signal if the value changes.

`button` : | a PhatSliderButton
`value` : | a new value for the button

### phat_slider_button_get_value ()

    double      phat_slider_button_get_value    (PhatSliderButton *button);

Retrieves the current value of the button.

`button` : | a PhatSliderButton
Returns : | current value of the button

### phat_slider_button_set_range ()

    void        phat_slider_button_set_range    (PhatSliderButton *button,
                                                 double lower,
                                                 double upper);

Sets the range of allowable values for the button, and clamps the button's current value to be between `lower` and `upper`.

`button` : | a PhatSliderButton
`lower` : | lowest allowable value
`upper` : | highest allowable value

### phat_slider_button_get_range ()

    void        phat_slider_button_get_range    (PhatSliderButton *button,
                                                 double *lower,
                                                 double *upper);

Places the range of allowable values for `button` into `lower` and `upper`. Either variable may be set to `NULL` if you are not interested in its value.

`button` : | a PhatSliderButton
`lower` : | retrieves lowest allowable value
`upper` : | retrieves highest allowable value

### phat_slider_button_set_adjustment ()

    void        phat_slider_button_set_adjustment
                                                (PhatSliderButton *button,
                                                 GtkAdjustment *adjustment);

Sets the adjustment used by `button`. If `adjustment` is `NULL`, a new adjustment with a value of zero and a range of [-1.0, 1.0] will be created.

`button` : | a PhatSliderButton
`adjustment` : | a GtkAdjustment

### phat_slider_button_get_adjustment ()

    GtkAdjustment* phat_slider_button_get_adjustment
                                                (PhatSliderButton *button);

Retrives the current adjustment in use by `button`.

`button` : | a PhatSliderButton
Returns : | `button`'s current GtkAdjustment

### phat_slider_button_set_increment ()

    void        phat_slider_button_set_increment
                                                (PhatSliderButton *button,
                                                 double step,
                                                 double page);

Sets the increments the button should use.

`button` : | a PhatSliderButton
`step` : | step increment value
`page` : | page increment value

### phat_slider_button_get_increment ()

    void        phat_slider_button_get_increment
                                                (PhatSliderButton *button,
                                                 double *step,
                                                 double *page);

Places the button's increment values into `step` and `page`. Either variable may be set to `NULL` if you are not interested in its value.

`button` : | a PhatSliderButton
`step` : | retrieves step increment value
`page` : | retrieves page increment value

### phat_slider_button_set_format ()

    void        phat_slider_button_set_format   (PhatSliderButton *button,
                                                 int digits,
                                                 const char *prefix,
                                                 const char *postfix);

Sets the way `button` renders it's label. If the first character in either `prefix` or `postfix` is '\0' the corresponding parameter will be unset. If you don't want to adjust `digits`, set it to a negative value. If you don't want to adjust `prefix` and/or `postfix`, set them to `NULL`.

`button` : | a PhatSliderButton
`digits` : | number of decimal digits to display
`prefix` : | text to prepend to number
`postfix` : | text to append to number

### phat_slider_button_get_format ()

    void        phat_slider_button_get_format   (PhatSliderButton *button,
                                                 int *digits,
                                                 char **prefix,
                                                 char **postfix);

Retrieves the information `button` uses to create its label. The value returned will point to the button's local copy, so don't write to it. Set the pointers for any value you aren't interested in to `NULL`.

`button` : | a PhatSliderButton
`digits` : | retrieves the number of decimal digits to display
`prefix` : | retrieves text prepended to number
`postfix` : | retrieves text appended to number

### phat_slider_button_set_threshold ()

    void        phat_slider_button_set_threshold
                                                (PhatSliderButton *button,
                                                 guint threshold);

Sets the threshold for `button`. The threshold is how far the user has to move the mouse to effect a change when sliding.

`button` : | a PhatSliderButton
`threshold` : | an unsigned int >= 1

### phat_slider_button_get_threshold ()

    int         phat_slider_button_get_threshold
                                                (PhatSliderButton *button);

Retrieves the threshold for `button`

`button` : | a PhatSliderButton
Returns : | the threshold for `button`, or -1 if `button` is invalid

## Signal Details

### The "changed" signal

    void        user_function                  (PhatSliderButton *button,
                                                gpointer          user_data)      : Run first / Action

The "changed" signal is emitted when any parameter of the slider's adjustment changes, except for the `value` parameter.

`button` : | the object on which the signal was emitted
`user_data` : | user data set when the signal handler was connected.

### The "value-changed" signal

    void        user_function                  (PhatSliderButton *button,
                                                gpointer          user_data)      : Run first / Action

The "value-changed" signal is emitted when the value of the button's adjustment changes.

`button` : | the object on which the signal was emitted
`user_data` : | user data set when the signal handler was connected.