The category of range widgets includes the ubiquitous scrollbar widget and the less common scale widget. Though these two types of widgets are generally used for different purposes, they are quite similar in function and implementation. All range widgets share a set of common graphic elements, each of which has its own X window and receives events. They all contain a "trough" and a "slider" (what is sometimes called a "thumbwheel" in other GUI environments). Dragging the slider with the pointer moves it back and forth within the trough, while clicking in the trough advances the slider towards the location of the click, either completely, or by a designated amount, depending on which mouse button is used.
As mentioned in Adjustments above, all range widgets are associated with an adjustment object, from which they calculate the length of the slider and its position within the trough. When the user manipulates the slider, the range widget will change the value of the adjustment.
These are your standard, run-of-the-mill scrollbars. These should be used only for scrolling some other widget, such as a list, a text box, or a viewport (and it's generally easier to use the scrolled window widget in most cases). For other purposes, you should use scale widgets, as they are friendlier and more featureful.
There are separate types for horizontal and vertical scrollbars. There really isn't much to say about these. You create them with the following functions:
function gtk_hscrollbar_new (adjustment : PGtkAdjustment) : PGtkWidget; function gtk_vscrollbar_new (adjustment : PGtkAdjustment) : PGtkWidget;
and that's about it (if you don't believe me, look in the header files!).
The adjustment argument can either be a pointer to an existing
Adjustment, or nil, in which case one will
be created for you. Specifying nil might
actually be useful in this case, if you wish to pass the newly-created
adjustment to the constructor function of some other widget which will
configure it for you, such as a text widget.
Scale widgets are used to allow the user to visually select and manipulate a value within a specific range. You might want to use a scale widget, for example, to adjust the magnification level on a zoomed preview of a picture, or to control the brightness of a color, or to specify the number of minutes of inactivity before a screensaver takes over the screen.
As with scrollbars, there are separate widget types for horizontal and vertical scale widgets. (Most programmers seem to favour horizontal scale widgets.) Since they work essentially the same way, there's no need to treat them separately here. The following functions create vertical and horizontal scale widgets, respectively:
function gtk_vscale_new (adjustment : PGtkAdjustment) : PGtkWidget;
function gtk_vscale_new_with_range (min : gdouble;
max : gdouble;
step : gdouble) : PGtkWidget;
function gtk_hscale_new (adjustment : PGtkAdjustment) : PGtkWidget;
function gtk_hscale_new_with_range (min : gdouble;
max : gdouble;
step : gdouble) : PGtkWidget;
The adjustment argument can either be an adjustment which
has already been created with gtk_adjustment_new(), or
nil, in which case, an anonymous Adjustment
is created with all of its values set to 0.0 (which isn't very useful
in this case). In order to avoid confusing yourself, you probably want
to create your adjustment with a page_size of 0.0 so that
its upper value actually corresponds to the highest value
the user can select. The _new_with_range() variants take care of creating
a suitable adjustment. (If you're already thoroughly confused,
read the section on Adjustments again for
an explanation of what exactly adjustments do and how to create
and manipulate them.)
Scale widgets can display their current value as a number beside the trough. The default behaviour is to show the value, but you can change this with this procedure:
procedure gtk_scale_set_draw_value (scale : PGtkScale;
draw_value : boolean);
As you might have guessed, draw_value is either
true or false,
with predictable consequences for either one.
The value displayed by a scale widget is rounded to one decimal point by default, as is the value field in its GtkAdjustment. You can change this with:
procedure gtk_scale_set_digits (scale : PGtkScale;
digits : gint);
where digits is the number of decimal places you want. You can set digits to anything you like, but no more than 13 decimal places will actually be drawn on screen.
Finally, the value can be drawn in different positions relative to the trough:
procedure gtk_scale_set_value_pos (scale : PGtkScale;
pos : TGtkPositionType);
The argument pos is of type TGtkPositionType,
which can take one of the following values:
GTK_POS_LEFT GTK_POS_RIGHT GTK_POS_TOP GTK_POS_BOTTOM
If you position the value on the "side" of the trough (e.g., on the top or bottom of a horizontal scale widget), then it will follow the slider up and down the trough.
The Range widget class is fairly complicated internally, but, like all the "base class" widgets, most of its complexity is only interesting if you want to hack it. Also, almost all of the functions and signals it defines are only really used in writing derived widgets. There are, however, a few useful functions that are defined to work on all range widgets.
The "update policy" of a range widget defines at what points during user
interaction it will change the value field of its Adjustment and emit
the "value_changed" signal on this Adjustment. The update policies,
defined as TGtkUpdateType, are:
GTK_UPDATE_POLICY_CONTINUOUSThis is the default. The "value_changed" signal is emitted continuously, i.e., whenever the slider is moved by even the tiniest amount.
GTK_UPDATE_POLICY_DISCONTINUOUSThe "value_changed" signal is only emitted once the slider has stopped moving and the user has released the mouse button.
GTK_UPDATE_POLICY_DELAYEDThe "value_changed" signal is emitted when the user releases the mouse button, or if the slider stops moving for a short period of time.
The update policy of a range widget can be set by casting it using
the GTK_RANGE(widget) macro and passing it to this procedure:
procedure gtk_range_set_update_policy (range : PGtkRange;
policy : GtkUpdateType);
Getting and setting the adjustment for a range widget "on the fly" is done, predictably, with:
function gtk_range_get_adjustment (range : PGtkRange) : PGtkAdjustment;
procedure gtk_range_set_adjustment (range : PGtkRange;
adjustment : PGtkAdjustment);
gtk_range_get_adjustment() returns a pointer
to the adjustment to which range is connected.
gtk_range_set_adjustment() does absolutely
nothing if you pass it the adjustment that range is already
using, regardless of whether you changed any of its fields or not. If you
pass it a new Adjustment, it will unreference the old one if it exists
(possibly destroying it), connect the appropriate signals to the new one,
and call the private function gtk_range_adjustment_changed(),
which will (or at least, is supposed to...) recalculate the size and/or
position of the slider and redraw if necessary. As mentioned in the section on
adjustments, if you wish to reuse the same Adjustment, when you modify
its values directly, you should emit the "changed" signal on it, like this:
g_signal_emit_by_name(adjustment, 'changed');
All of the GTK range widgets react to mouse clicks in more or less
the same way. Clicking button-1 in the trough will cause its adjustment's
page_increment to be added or subtracted from its
value, and the slider to be moved accordingly. Clicking
mouse button-2 in the trough will jump the slider to the point at which
the button was clicked. Clicking any button on a scrollbar's arrows will
cause its adjustment's value to change step_increment each
time.
Scrollbars are not focusable, thus have no key bindings. The key bindings for the other range widgets (which are, of course, only active when the widget has focus) do not differentiate between horizontal and vertical range widgets.
All range widgets can be operated with the left, right, up and down arrow
keys, as well as with the Page Up and Page Down
keys. The arrows move the slider up and down by step_increment,
while Page Up and Page Down move it by
page_increment.
The user can also move the slider all the way to one end or the other
of the trough using the keyboard. This is done with the Home
and End keys.
This example is a somewhat modified version of the "range controls" test
from testgtk.c. It basically puts up a window with three range
widgets all connected to the same adjustment, and a couple of controls
for adjusting some of the parameters mentioned above and in the section
on adjustments, so you can see how they affect the way these widgets work
for the user.
program RangeWidgets;
{$mode objfpc}
uses
glib2, gdk2, gtk2, sysutils;
var
hscale, vscale : PGtkWidget;
procedure cb_pos_menu_select (item : PGtkWidget;
pos : TGtkPositionType) ;cdecl;
begin
{ Set the value position on both scale widgets }
gtk_scale_set_value_pos(GTK_SCALE(hscale), pos);
gtk_scale_set_value_pos(GTK_SCALE(vscale), pos);
end;
procedure cb_update_menu_select (item : PGtkWidget;
policy : TGtkUpdateType); cdecl;
begin
{ Set the update policy for both scale widgets }
gtk_range_set_update_policy(GTK_RANGE(hscale), policy);
gtk_range_set_update_policy(GTK_RANGE(vscale), policy);
end;
procedure cb_digits_scale (adj :PGtkAdjustment);cdecl;
begin
{ Set the number of decimal places to which adj->value is rounded }
gtk_scale_set_digits(GTK_SCALE(hscale), round(adj^.value));
gtk_scale_set_digits(GTK_SCALE(vscale), round(adj^.value));
end;
procedure cb_page_size (get : PGtkAdjustment; dest : PGtkAdjustment); cdecl;
begin
{ Set the page size and page increment size of the sample
adjustment to the value specified by the 'Page Size' scale }
dest^.page_size := get^.value;
dest^.page_increment := get^.value;
{ This sets the adjustment and makes it emit the "changed" signal to
reconfigure all the widgets that are attached to this signal. }
gtk_adjustment_set_value(dest, CLAMP(round(dest^.value),
round(dest^.lower),
round(dest^.upper - dest^.page_size)));
{ Now emit the 'changed' signal to reconfigure all the widgets that
are attached to this adjustment }
g_signal_emit_by_name(G_OBJECT(dest), 'changed');
end;
procedure cb_draw_value (button : PGtkToggleButton) ;cdecl;
begin
{ Turn the value display on the scale widgets off or on depending
on the state of the checkbutton }
gtk_scale_set_draw_value(GTK_SCALE (hscale), active(button^) <> 0);
gtk_scale_set_draw_value(GTK_SCALE (vscale), active(button^) <> 0);
end;
{ Convenience functions }
function make_menu_item (name : pgchar;
callback : TGCallback;
data : integer) : PGtkWidget;
var
item : PGtkWidget;
begin
item := gtk_menu_item_new_with_label(name);
g_signal_connect(item, 'activate', callback, gpointer(data));
gtk_widget_show(item);
make_menu_item := item;
end;
function GINT_TO_POINTER (t : gint) : gpointer;
var
temp : gint;
begin
temp := t;
GINT_TO_POINTER := @temp;
end;
procedure scale_set_default_values (scale : PGtkScale);
begin
gtk_range_set_update_policy(GTK_RANGE(scale), GTK_UPDATE_CONTINUOUS);
gtk_scale_set_digits(scale, 1);
gtk_scale_set_value_pos(scale, GTK_POS_TOP);
gtk_scale_set_draw_value(scale, true);
end;
{ Makes the sample window }
procedure create_range_controls ();
var
window, box1, box2, box3, button, scrollbar, separator : PGtkWidget;
opt, menu, item, a_label, scale : PGtkWidget;
adj1, adj2 : PGtkObject;
begin
{ Standard window-creating stuff }
window := gtk_window_new(GTK_WINDOW_TOPLEVEL);
g_signal_connect(window, 'destroy', G_CALLBACK(@gtk_main_quit), nil);
gtk_window_set_title(GTK_WINDOW(window), 'range controls');
box1 := gtk_vbox_new(false, 0);
gtk_container_add(GTK_CONTAINER(window), box1);
gtk_widget_show(box1);
box2 := gtk_hbox_new(false, 10);
gtk_container_set_border_width(GTK_CONTAINER(box2), 10);
gtk_box_pack_start(GTK_BOX(box1), box2, true, true, 0);
gtk_widget_show(box2);
{ value, lower, upper, step_increment, page_increment, page_size.
Note that the page_size value only makes a difference for scrollbar
widgets, and the highest value you'll get is actually
(upper - page_size). }
adj1 := gtk_adjustment_new(0.0, 0.0, 101.0, 0.1, 1.0, 1.0);
vscale := gtk_vscale_new(GTK_ADJUSTMENT(adj1));
scale_set_default_values(GTK_SCALE(vscale));
gtk_box_pack_start(GTK_BOX(box2), vscale, true, true, 0);
gtk_widget_show(vscale);
box3 := gtk_vbox_new(false, 10);
gtk_box_pack_start(GTK_BOX(box2), box3, true, true, 0);
gtk_widget_show(box3);
{ Reuse the same adjustment }
hscale := gtk_hscale_new(GTK_ADJUSTMENT(adj1));
gtk_widget_set_size_request(GTK_WIDGET(hscale), 200, 30);
scale_set_default_values(GTK_SCALE(hscale));
gtk_box_pack_start(GTK_BOX(box3), hscale, true, true, 0);
gtk_widget_show(hscale);
{ Reuse the same adjustment again }
scrollbar := gtk_hscrollbar_new(GTK_ADJUSTMENT(adj1));
{ Notice how this causes the scales to always be updated
continuously when the scrollbar is moved }
gtk_range_set_update_policy(GTK_RANGE(scrollbar), GTK_UPDATE_CONTINUOUS);
gtk_box_pack_start(GTK_BOX(box3), scrollbar, true, true, 0);
gtk_widget_show(scrollbar);
box2 := gtk_hbox_new(false, 10);
gtk_container_set_border_width(GTK_CONTAINER(box2), 10);
gtk_box_pack_start(GTK_BOX(box1), box2, true, true, 0);
gtk_widget_show(box2);
{ A checkbutton to control whether the value is displayed or not }
button := gtk_check_button_new_with_label('Display value on scale widgets');
gtk_toggle_button_set_active(GTK_TOGGLE_BUTTON(button), true);
g_signal_connect(button, 'toggled',
G_CALLBACK(@cb_draw_value), nil);
gtk_box_pack_start(GTK_BOX(box2), button, true, true, 0);
gtk_widget_show(button);
box2 := gtk_hbox_new(false, 10);
gtk_container_set_border_width(GTK_CONTAINER(box2), 10);
{ An option menu to change the position of the value }
a_label := gtk_label_new('Scale Value Position:');
gtk_box_pack_start(GTK_BOX(box2), a_label, false, false, 0);
gtk_widget_show(a_label);
opt := gtk_option_menu_new();
menu := gtk_menu_new();
item := make_menu_item('Top', G_CALLBACK(@cb_pos_menu_select),
GTK_POS_TOP);
gtk_menu_shell_append(GTK_MENU_SHELL(menu), item);
item := make_menu_item('Bottom', G_CALLBACK(@cb_pos_menu_select),
GTK_POS_BOTTOM);
gtk_menu_shell_append(GTK_MENU_SHELL(menu), item);
item := make_menu_item('Left', G_CALLBACK(@cb_pos_menu_select),
GTK_POS_LEFT);
gtk_menu_shell_append(GTK_MENU_SHELL(menu), item);
item := make_menu_item('Right', G_CALLBACK(@cb_pos_menu_select),
GTK_POS_RIGHT);
gtk_menu_shell_append(GTK_MENU_SHELL(menu), item);
gtk_option_menu_set_menu(GTK_OPTION_MENU(opt), menu);
gtk_box_pack_start(GTK_BOX(box2), opt, true, true, 0);
gtk_widget_show(opt);
gtk_box_pack_start(GTK_BOX(box1), box2, true, true, 0);
gtk_widget_show(box2);
box2 := gtk_hbox_new(false, 10);
gtk_container_set_border_width(GTK_CONTAINER(box2), 10);
{ Yet another option menu, this time for the update policy of
the scale widgets }
a_label := gtk_label_new('Scale Update Policy:');
gtk_box_pack_start(GTK_BOX(box2), a_label, false, false, 0);
gtk_widget_show(a_label);
opt := gtk_option_menu_new();
menu := gtk_menu_new();
item := make_menu_item('Continuous', G_CALLBACK(@cb_update_menu_select),
GTK_UPDATE_CONTINUOUS);
gtk_menu_shell_append(GTK_MENU_SHELL(menu), item);
item := make_menu_item('Discontinuous', G_CALLBACK(@cb_update_menu_select),
GTK_UPDATE_DISCONTINUOUS);
gtk_menu_shell_append(GTK_MENU_SHELL(menu), item);
item := make_menu_item('Delayed', G_CALLBACK(@cb_update_menu_select),
GTK_UPDATE_DELAYED);
gtk_menu_shell_append(GTK_MENU_SHELL(menu), item);
gtk_option_menu_set_menu(GTK_OPTION_MENU(opt), menu);
gtk_box_pack_start(GTK_BOX(box2), opt, true, true, 0);
gtk_widget_show(opt);
gtk_box_pack_start(GTK_BOX(box1), box2, true, true, 0);
gtk_widget_show(box2);
box2 := gtk_hbox_new(false, 10);
gtk_container_set_border_width(GTK_CONTAINER(box2), 10);
{ A GtkHScale widget for adjusting the number of digits
on the sample scales. }
a_label := gtk_label_new('Scale Digits:');
gtk_box_pack_start(GTK_BOX(box2), a_label, false, false, 0);
gtk_widget_show(a_label);
adj2 := gtk_adjustment_new(1.0, 0.0, 5.0, 1.0, 1.0, 0.0);
g_signal_connect(adj2, 'value_changed',
G_CALLBACK(@cb_digits_scale), nil);
scale := gtk_hscale_new(GTK_ADJUSTMENT(adj2));
gtk_scale_set_digits(GTK_SCALE(scale), 0);
gtk_box_pack_start(GTK_BOX(box2), scale, true, true, 0);
gtk_widget_show(scale);
gtk_box_pack_start(GTK_BOX(box1), box2, true, true, 0);
gtk_widget_show(box2);
box2 := gtk_hbox_new(false, 10);
gtk_container_set_border_width(GTK_CONTAINER(box2), 10);
{ And, one last HScale widget for adjusting the page size
of the scrollbar. }
a_label := gtk_label_new('Scrollbar Page Size:');
gtk_box_pack_start(GTK_BOX(box2), a_label, false, false, 0);
gtk_widget_show(a_label);
adj2 := gtk_adjustment_new(1.0, 1.0, 101.0, 1.0, 1.0, 0.0);
g_signal_connect(adj2, 'value-changed',
G_CALLBACK(@cb_page_size), adj1);
scale := gtk_hscale_new(GTK_ADJUSTMENT(adj2));
gtk_scale_set_digits(GTK_SCALE(scale), 0);
gtk_box_pack_start(GTK_BOX(box2), scale, true, true, 0);
gtk_widget_show(scale);
gtk_box_pack_start(GTK_BOX(box1), box2, true, true, 0);
gtk_widget_show(box2);
separator := gtk_hseparator_new();
gtk_box_pack_start(GTK_BOX(box1), separator, false, true, 0);
gtk_widget_show(separator);
box2 := gtk_vbox_new(false, 10);
gtk_container_set_border_width(GTK_CONTAINER(box2), 10);
gtk_box_pack_start(GTK_BOX(box1), box2, false, true, 0);
gtk_widget_show(box2);
button := gtk_button_new_with_label('Quit');
g_signal_connect_swapped(button, 'clicked',
G_CALLBACK(@gtk_main_quit), nil);
gtk_box_pack_start(GTK_BOX(box2), button, true, true, 0);
GTK_WIDGET_SET_FLAGS(button, GTK_CAN_DEFAULT);
gtk_widget_grab_default(button);
gtk_widget_show(button);
gtk_widget_show(window);
end;
begin
gtk_init(@argc, @argv);
create_range_controls();
gtk_main();
end.
You will notice that the program does not call
gtk_signal_connect() for the "delete-event", but only for
the "destroy" signal. This will still perform the desired function, because
an unhandled "delete-event" will result in a "destroy" signal being given
to the window.