PhatSliderButton

Name

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

Synopsis



struct      PhatSliderButton;
GtkWidget*  phat_slider_button_new          (GtkAdjustment *adjustment,
                                             const char *format);
GtkWidget*  phat_slider_button_new_with_range
                                            (double value,
                                             double lower,
                                             double upper,
                                             double step,
                                             const char *format);
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,
                                             const char *format,
                                             const char *prefix,
                                             const char *postfix);
void        phat_slider_button_get_format   (PhatSliderButton *button,
                                             char **format,
                                             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
   +----GtkObject
         +----GtkWidget
               +----GtkContainer
                     +----GtkBox
                           +----GtkHBox
                                 +----PhatSliderButton

Implemented Interfaces

PhatSliderButton implements AtkImplementorIface.

Signal Prototypes


"changed"   void        user_function      (PhatSliderButton *button,
                                            gpointer user_data);
"value-changed"
            void        user_function      (PhatSliderButton *button,
                                            gpointer user_data);

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

struct PhatSliderButton

struct PhatSliderButton;

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


phat_slider_button_new ()

GtkWidget*  phat_slider_button_new          (GtkAdjustment *adjustment,
                                             const char *format);

Creates a new PhatSliderButton. format is used to determine the way that the current value will be displayed, and should contain a "%f" or similar escape somewhere, or Bad Things are bound to happen.

adjustment :

the GtkAdjustment that the new button will use

format :

a printf style format specifier for the button's label

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,
                                             const char *format);

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

format :

a printf style format specifier for the button's label

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,
                                             const char *format,
                                             const char *prefix,
                                             const char *postfix);

Sets the format and extra text button uses to render it's label. If the first character in either prefix or postfix is '\0' the corresponding parameter will be unset. If format is not a valid string with a "%f" or compatible escape somewhere, woe betide you. Any field you aren't interested in adjusting may be set to NULL.

button :

a PhatSliderButton

format :

a printf style format specifier

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,
                                             char **format,
                                             char **prefix,
                                             char **postfix);

Retrieves the format specifier button uses to create its label. The value returned will point to the button's local copy, so don't write to it.

button :

a PhatSliderButton

format :

retrieves the format specifier

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

Signals

The "changed" signal

void        user_function                  (PhatSliderButton *button,
                                            gpointer user_data);

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);

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.