![]() |
![]() |
![]() |
PHAT Reference Manual | ![]() |
---|---|---|---|---|
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);
GObject +----GInitiallyUnowned +----GtkObject +----GtkWidget +----GtkContainer +----GtkBox +----GtkHBox +----PhatSliderButton
"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
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.
typedef struct _PhatSliderButton PhatSliderButton;
The PhatSliderButton struct contains private data only, and should be accessed using the functions below.
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 |
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 |
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 |
double phat_slider_button_get_value (PhatSliderButton *button);
Retrieves the current value of the button.
button : |
a PhatSliderButton |
Returns : | current value of the button |
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 |
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 |
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 |
GtkAdjustment* phat_slider_button_get_adjustment (PhatSliderButton *button);
Retrives the current adjustment in use by button
.
button : |
a PhatSliderButton |
Returns : | button 's current GtkAdjustment
|
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 |
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 |
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 |
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 |
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 |
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
|
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. |
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. |