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.