We use US English which uses behavior. So we replace all occurrences of
behaviour.
Most notable is File Open behavior in preferences. Besides that several
mentions in function documentation and a few in comments.
In GTK, a common scheme is to let a function creating a specific widget
to return a `GtkWidget *`, rather than the specific subtype, since you
often need to call API of GtkWidget, avoiding some useless casts.
For bindings however (and especially bindings to compiled languages),
this is a bit annoying, as you have to explicitly change the type of the
return value (downcast), which is not trivial (or at least desirable) in
each language.
Luckily, we can use `(type ...)` annotation for this use case, leaving
the C API unchanged, while improving the experience for bindings.
… gimp_scale_entry_set_bounds().
I realized that this function may look like the set() opposite for
gimp_scale_entry_get_range(), which it is not at all. The get_range() is
for getting back the GtkRange widget packed in the GimpScaleEntry,
whereas the set_range() is to change the minimum and maximum allowed
values.
I had recently renamed the former, and could just rename it back into
gimp_scale_entry_get_scale() as it was, but since the class we rely on
is actually called GtkRange (GtkScale is a subclass), I think it could
be misleading. So in the end, let's rather rename the function setting
the widget minimum and maximum as gimp_scale_entry_set_bounds() instead.
Hopefully this is even more understandable. Naming is hard!
Renaming the temporary function gimp_scale_entry_new2() into
gimp_scale_entry_new() now that the original code is entirely gone. This
is now a fully-fledged widget with a nice and proper introspectable API.
Former gimp_color_scale_entry_new() is finally replaced by the
GimpColorScaleEntry implementation.
Both places which used it (GimpColorScales and compose plug-in) now use
the new widget.
Also making "upper" and "lower" properties of GimpScaleEntry into
construction properties, and create the main GtkAjustment at init, so
that we are sure that lower and upper bounds are properly set before we
set the value (when setting all properties at once, we cannot ensure
that these limit properties are set before the "value" one).
I updated GimpScaleEntry and GimpColorScaleEntry header to use
respectively the macros G_DECLARE_DERIVABLE_TYPE and
G_DECLARE_FINAL_TYPE.
Though having the `priv` structure directly in the object data is
extremely comfortable for developing (hence we don't want to use this
macro on core code as it makes coding a bit more bothersome), it is true
that it does not make for a very pretty public interface (showing a
`priv` member which nobody can actually use, and a private type which
has no associated functions). So it might be a good idea to use these
macros at least on libgimp side.
I am still not sure though if it is a good idea so we could say it's an
experiment. At least the docs says that using G_DECLARE_FINAL_TYPE does
not affect ABI stability as it can later be changed into a
G_DECLARE_DERIVABLE_TYPE because the class structure stays private. So
at least that's one good point.
P.S.: also reordering gimpwidgets.def.
Similarly to GimpScaleEntry, this is meant to replace usage of
gimp_color_scale_entry_new() by having a proper widget. This is a child
class of GimpScaleEntry which simply replaces the GtkScale by a
GimpColorScale by adding a GimpScaleEntry class method to create the
scale widget (only restriction: it must be a GtkRange subtype).
This also triggers me to rename gimp_scale_entry_get_scale() into
gimp_scale_entry_get_range() (as well as the 2 plug-ins already using
this function).
I got rid of gimp_scale_entry_set_sensitive(), as we can now use the
generic gtk_widget_set_sensitive(), and I ported the 2 plug-ins using
this function.
I also created gimp_scale_entry_set_value() to set the value (nicer than
setting object properties).
For very small ranges, just dividing by 10 and 100 is not very good. You
could end up with weird step values. It is often better to use 10^(-x)
values just below your range.
I.e for a 0.5 range, a step of 0.1 and page of 0.01 are probably fine
(better than 0.05 and 0.005).
Of course as usual these are default values only and setting custom
increments is possible through available API.
Also fixing a small bug in gimp_scale_entry_set_increments() added in
commit 0f05825a29.
Instead of setting always manually the step and page increments when
creating a GimpScaleEntry, let's just generate some common cases
automatically. Indeed the increments are rarely something you want to
care about. The algorithm used is:
- For a range under 1.0, use a hundredth and a tenth (typically a [0,
1.0] range will step-increment of 0.01 and page-increment of 0.1).
- For small ranges (under 40), step-increment by 1, page-increment by 2.
- For bigger ranges, step-increment by 1, page-increment by 10.
For use cases when you absolutely want specific increment values, I add
the gimp_scale_entry_set_increments() function. It is much better to
have a small and understandable constructor call followed by
configuration calls (only when needed) rather than a constructor with a
crazy amount of parameters. Hence gimp_scale_entry_new() went from 17
arguments (absolutely unreadable calls) to now 5.
* Add a gimp_scale_entry_get_value() because if we don't do a property
widget, getting the value of the widget easily is a main point.
* Move gimp_scale_entry_(set|get)_logarithmic() to the new class API.
* Internally edit the GtkSpinButton width depending on min/max values,
place digits, and possible value sign.
* Emit a "value-changed" signal (similarly to other widgets with a
value), for cases when just binding the "value" property is not
enough.
* Finally use the new API in palette-import-dialog.
Instead of the gimp_scale_entry_new() which creates several bound yet
independant widgets, and in the same time pack them into an existing
grid and return a GtkAdjustment (while heavily relying on GObject data
to link widgets), let's have a proper custom widget with its own clean
API.
This also simplifies the gimp_prop_scale_entry_new() property widget
variant.
First advantage is that we don't force the usage of a grid to use this
widget (there are a few pieces of code which create a GtkGrid with only
this inside just to be able to use this feature).
Second thing is that I am creating a much simpler API.
gimp_scale_entry_new() had 17 parameters! How crazy is that? So I
removed all the grid packing related parameters. Also I moved the spin
button/scale unconstraining parameters into their separate function,
because the constrained behavior is the most common use case, so it's
stupid to add 3 permanent dummy parameters for most calls. Instead the
few times where we'll want different ranges for the spin button and the
scale, we'll call the separate API gimp_scale_entry_set_range().
Thirdly the tooltip can be set directly with gimp_help_set_help_data()
since this is now its own widget. No need to have dedicated logics
anymore, better stay generic. Similarly no need of a custom function to
switch sensitivitivy (instead of generic gtk_widget_set_sensitive()).
Fourth thing is that we should not use macros for the public API, but
proper functions, because macros are not properly introspected for
binding.
For future improvements, maybe we could even make this widget implement
GtkOrientable interface, in order to be able to use it vertically.
Note: right now, I created a separate gimp_scale_entry_new2() and only
modified the property widget API to use this new code. Eventually I will
remove fully the old gimp_scale_entry_new() function (and the new code
will replace it).
Always use separate GtkAdjustments for the scale and the spinbutton,
and link them with a GBinding, either 1:1 or using logarithmic
transform functions.
This change also enables modifying both widgets' ranges independently
after construction, thus enabling the "constrain" feature also for
gimp_color_scale_entry_new().
because it confuses gtk-doc and breaks some links. Also change the
"Index of new symbols in GIMP 2.x" sections to be what seems to be the
modern standard (looked at the GLib and GTK+ docs), and update some
other stuff.
...are much too quick
In gimp_scale_entry_new(), set the spinbutton's climb_rate to the same
value as step_increment instead of hardcoding 1.0. This should make
many spinbuttons behave better.
2009-01-17 Michael Natterer <mitch@gimp.org>
* all files with a GPL header and all COPYING files:
Change licence to GPLv3 (and to LGPLv3 for libgimp).
Cleaned up some copyright headers and regenerated the parsers in
the ImageMap plugin.
svn path=/trunk/; revision=27913
Merged from weskaggs branch at Mitch's request. Will
need to update devel docs.
Place scale entry code into separate files, no
functional changes.
* libgimpwidgets/gimpscaleentry.c
* libgimpwidgets/gimpscaleentry.h: new files.
* libgimpwidgets/gimpwidgets.h
* libgimpwidgets/gimpwidgets.c
* libgimpwidgets/gimpwidgets.h
* libgimpwidgets/Makefile.am: changed accordingly.
svn path=/trunk/; revision=24887