[gimp/soc-2011-gimpunitentry] Add gtk-doc documentation for GimpUnitEntry and GimpUnitAdjustment
- From: Enrico SchrÃder <eschroeder src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gimp/soc-2011-gimpunitentry] Add gtk-doc documentation for GimpUnitEntry and GimpUnitAdjustment
- Date: Sat, 20 Aug 2011 12:27:17 +0000 (UTC)
commit bc25bf1c9b8a82de163aa410139e56902c7d8f78
Author: Enrico SchroÌder <enni schroeder gmail com>
Date: Sat Aug 20 14:25:37 2011 +0200
Add gtk-doc documentation for GimpUnitEntry and GimpUnitAdjustment
libgimpwidgets/gimpunitadjustment.c | 295 +++++++++++++++++++++++++----------
libgimpwidgets/gimpunitentry.c | 122 ++++++++++++++-
2 files changed, 331 insertions(+), 86 deletions(-)
---
diff --git a/libgimpwidgets/gimpunitadjustment.c b/libgimpwidgets/gimpunitadjustment.c
index 8b95d4b..ba7fa21 100644
--- a/libgimpwidgets/gimpunitadjustment.c
+++ b/libgimpwidgets/gimpunitadjustment.c
@@ -31,6 +31,23 @@
#include "gimpwidgets.h"
#include "gimpunitadjustment.h"
+/**
+ * SECTION: gimpunitadjustment
+ * @title: GimpUnitAdjustment
+ * @short_description: A #GtkAdjustment subclass for holding a value
+ * and the corresponding unit.
+ * @see_also: #GimpUnitEntry, #GimpUnit
+ *
+ * #GimpUnitAdjustment is a subclass of #GtkAdjustment. The GimpUnitAdjustment
+ * oject represents a value and its unit and resolution. It works basically
+ * the same way as GtkAdjustment does, but has a few additional unit-related
+ * getters and setters and the ability to be connected to other GimpUnitAdjustments,
+ * so that the change of one of the adjustment's unit automatically
+ * changes the unit of all other connected adjustments.
+ *
+ * It is used by #GimpUnitEntry.
+ **/
+
/* debug macro */
//#define UNITADJUSTMENT_DEBUG
#ifdef UNITADJUSTMENT_DEBUG
@@ -62,8 +79,14 @@ typedef struct
G_DEFINE_TYPE (GimpUnitAdjustment, gimp_unit_adjustment, GTK_TYPE_ADJUSTMENT);
-static void gimp_unit_adjustment_convert_to_unit (GimpUnitAdjustment *adj, GimpUnit unit);
-static void gimp_unit_adjustment_other_unit_changed_handler (GimpUnitAdjustment *adj, gpointer userData);
+static void gimp_unit_adjustment_convert_to_unit (GimpUnitAdjustment *adjustment,
+ GimpUnit unit);
+static void gimp_unit_adjustment_other_unit_changed_handler (GimpUnitAdjustment *adjustment,
+ gpointer userData);
+static gdouble gimp_unit_adjustment_value_to_unit (gdouble value,
+ GimpUnit current_unit,
+ GimpUnit new_unit,
+ gdouble resolution);
static guint unit_adjustment_signals[LAST_SIGNAL] = {0};
@@ -116,39 +139,58 @@ gimp_unit_adjustment_class_init (GimpUnitAdjustmentClass *klass)
0);
}
-GimpUnitAdjustment *
-gimp_unit_adjustment_new (void)
-{
- return GIMP_UNIT_ADJUSTMENT (g_object_new (GIMP_TYPE_UNIT_ADJUSTMENT, NULL));
-}
-
static void
-gimp_unit_adjustment_other_unit_changed_handler (GimpUnitAdjustment *adj,
+gimp_unit_adjustment_other_unit_changed_handler (GimpUnitAdjustment *adjustment,
gpointer user_data)
{
GimpUnitAdjustment *other_adj = GIMP_UNIT_ADJUSTMENT (user_data);
GimpUnit unit = gimp_unit_adjustment_get_unit (other_adj);
- gimp_unit_adjustment_convert_to_unit (adj, unit);
+ gimp_unit_adjustment_convert_to_unit (adjustment, unit);
}
-/* connects adjustment to another adjustment */
+/**
+ * gimp_unit_adjustment_new:
+ *
+ * Creates a new GimpUnitAdjustment object.
+ *
+ * Returns: A Pointer to the new #GimpUnitAdjustment object
+ **/
+GimpUnitAdjustment *
+gimp_unit_adjustment_new (void)
+{
+ return GIMP_UNIT_ADJUSTMENT (g_object_new (GIMP_TYPE_UNIT_ADJUSTMENT, NULL));
+}
+
+/**
+ * gimp_unit_adjustment_follow_unit_of:
+ * @adjustment: The adjustment you want to adopt the followed adjustments
+ * unit.
+ * @follow_adjustment: The adjustment you want to follow.
+ *
+ * Lets a #GimpUnitAdjustment follow unit changes of another GimpUnitAdjustment.
+ *
+ * Whenever the followed adjustment changes its unit, the first adjustment is
+ * automatically changed to the same unit. Note that the connection is "one-way",
+ * if you also want the second adjustment to follow the first one, you have
+ * to call this function again for the other direction.
+ **/
void
-gimp_unit_adjustment_follow_unit_of (GimpUnitAdjustment *adj,
- GimpUnitAdjustment *other)
+gimp_unit_adjustment_follow_unit_of (GimpUnitAdjustment *adjustment,
+ GimpUnitAdjustment *followed_adjustment)
{
- g_signal_connect_swapped (other,
+ g_signal_connect_swapped (followed_adjustment,
"unit-changed",
G_CALLBACK (gimp_unit_adjustment_other_unit_changed_handler),
- (gpointer*) adj);
+ (gpointer*) adjustment);
}
/* converts value from one unit to another */
static void
-gimp_unit_adjustment_convert_to_unit (GimpUnitAdjustment *adj,
+gimp_unit_adjustment_convert_to_unit (GimpUnitAdjustment *adjustment,
GimpUnit unit)
{
- GimpUnitAdjustmentPrivate *private = GIMP_UNIT_ADJUSTMENT_GET_PRIVATE (adj);
+ GimpUnitAdjustmentPrivate *private = GIMP_UNIT_ADJUSTMENT_GET_PRIVATE (adjustment);
gdouble new_value = 0;
gdouble lower;
gdouble upper;
@@ -161,135 +203,204 @@ gimp_unit_adjustment_convert_to_unit (GimpUnitAdjustment *adj,
gimp_unit_get_abbreviation (unit));)
/* convert value to new unit */
- new_value = gimp_units_to_pixels (gtk_adjustment_get_value (&(adj->parent_instance)),
- private->unit,
- private->resolution);
- new_value = gimp_pixels_to_units (new_value,
- unit,
- private->resolution);
+ new_value = gimp_unit_adjustment_value_to_unit (gtk_adjustment_get_value (GTK_ADJUSTMENT (adjustment)),
+ private->unit,
+ unit,
+ private->resolution);
/* also convert bounds */
- upper = gimp_units_to_pixels (gtk_adjustment_get_upper (GTK_ADJUSTMENT (adj)),
- private->unit,
- private->resolution);
- lower = gimp_units_to_pixels (gtk_adjustment_get_lower (GTK_ADJUSTMENT (adj)),
- private->unit,
- private->resolution);
-
- upper = gimp_pixels_to_units (upper,
- unit,
- private->resolution);
- lower = gimp_pixels_to_units (lower,
- unit,
- private->resolution);
-
- gtk_adjustment_set_upper (GTK_ADJUSTMENT (adj), upper);
- gtk_adjustment_set_lower (GTK_ADJUSTMENT (adj), lower);
+ upper = gimp_unit_adjustment_value_to_unit (gtk_adjustment_get_upper (GTK_ADJUSTMENT (adjustment)),
+ private->unit,
+ unit,
+ private->resolution);
+ lower = gimp_unit_adjustment_value_to_unit (gtk_adjustment_get_lower (GTK_ADJUSTMENT (adjustment)),
+ private->unit,
+ unit,
+ private->resolution);
+
+ gtk_adjustment_set_upper (GTK_ADJUSTMENT (adjustment), upper);
+ gtk_adjustment_set_lower (GTK_ADJUSTMENT (adjustment), lower);
/* set the new unit */
private->unit = unit;
- gimp_unit_adjustment_set_value (adj, new_value);
+ gimp_unit_adjustment_set_value (adjustment, new_value);
}
-/* sets unit of adjustment, does conversion if neccessary */
+/**
+ * gimp_unit_adjustment_set_unit:
+ * @adjustment: The adjustment you want to change the unit of.
+ * @unit: The new unit.
+ *
+ * Changes the unit of a #GimpUnitAdjustment.
+ *
+ * The value and the upper and lower bounds of the adjustment are automatically
+ * converted to the new unit and the "unit-changed" signal is emmited.
+ **/
void
-gimp_unit_adjustment_set_unit (GimpUnitAdjustment *adj,
+gimp_unit_adjustment_set_unit (GimpUnitAdjustment *adjustment,
GimpUnit unit)
{
- gimp_unit_adjustment_convert_to_unit (adj, unit);
+ gimp_unit_adjustment_convert_to_unit (adjustment, unit);
/* emit "unit-changed" */
- g_signal_emit(adj, unit_adjustment_signals [UNIT_CHANGED], 0);
+ g_signal_emit(adjustment, unit_adjustment_signals [UNIT_CHANGED], 0);
}
+/**
+ * gimp_unit_adjustment_set_value:
+ * @adjustment: The adjustment you want to set the value of.
+ * @value: The new value.
+ *
+ * Sets the value of a #GimpUnitAdjustment in its current unit.
+ **/
void
-gimp_unit_adjustment_set_value (GimpUnitAdjustment *adj,
+gimp_unit_adjustment_set_value (GimpUnitAdjustment *adjustment,
gdouble value)
{
DEBUG (("set_value: %f", value);)
- gtk_adjustment_set_value (GTK_ADJUSTMENT (adj), value);
+ gtk_adjustment_set_value (GTK_ADJUSTMENT (adjustment), value);
}
+/**
+ * gimp_unit_adjustment_set_value_in_unit:
+ * @adjustment: The adjustment you want to set the value of.
+ * @value: The new value.
+ * @unit: The unit the new value is in.
+ *
+ * Sets the value of a #GimpUnitAdjustment in a specific unit.
+ *
+ * The value is converted from the given unit to the adjustments unit. The
+ * adjustments unit is not changed!
+ **/
void
-gimp_unit_adjustment_set_value_in_unit (GimpUnitAdjustment *adj,
+gimp_unit_adjustment_set_value_in_unit (GimpUnitAdjustment *adjustment,
gdouble value,
GimpUnit unit)
{
- GimpUnitAdjustmentPrivate *private = GIMP_UNIT_ADJUSTMENT_GET_PRIVATE (adj);
+ GimpUnitAdjustmentPrivate *private = GIMP_UNIT_ADJUSTMENT_GET_PRIVATE (adjustment);
/* convert from given unit to adjustments unit */
- value = gimp_units_to_pixels (value, unit, private->resolution);
- value = gimp_pixels_to_units (value, private->unit, private->resolution);
+ value = gimp_unit_adjustment_value_to_unit (value, unit, private->unit, private->resolution);
- gimp_unit_adjustment_set_value (adj, value);
+ gimp_unit_adjustment_set_value (adjustment, value);
}
+/**
+ * gimp_unit_adjustment_get_value:
+ * @adjustment: The adjustment you want to get the value from.
+ *
+ * Returns: The value of the #GimpUnitAdjustment in its current unit.
+ **/
gdouble
-gimp_unit_adjustment_get_value (GimpUnitAdjustment *adj)
+gimp_unit_adjustment_get_value (GimpUnitAdjustment *adjustment)
{
gdouble value;
- value = gtk_adjustment_get_value (GTK_ADJUSTMENT (adj));
+ value = gtk_adjustment_get_value (GTK_ADJUSTMENT (adjustment));
return value;
}
+/**
+ * gimp_unit_adjustment_get_value_in_unit:
+ * @adjustment: The adjustment you want to get the value from.
+ * @unit: The unit you want the value to be converted to.
+ *
+ * Returns: The value of the #GimpUnitAdjustment converted to the given unit.
+ **/
gdouble
-gimp_unit_adjustment_get_value_in_unit (GimpUnitAdjustment *adj,
+gimp_unit_adjustment_get_value_in_unit (GimpUnitAdjustment *adjustment,
GimpUnit unit)
{
- GimpUnitAdjustmentPrivate *private = GIMP_UNIT_ADJUSTMENT_GET_PRIVATE (adj);
- gdouble value = gimp_unit_adjustment_get_value (adj);
+ GimpUnitAdjustmentPrivate *private = GIMP_UNIT_ADJUSTMENT_GET_PRIVATE (adjustment);
+ gdouble value = gimp_unit_adjustment_get_value (adjustment);
- value = gimp_units_to_pixels (value, private->unit, private->resolution);
- value = gimp_pixels_to_units (value, unit, private->resolution);
+ value = gimp_unit_adjustment_value_to_unit (value,
+ private->unit,
+ unit,
+ private->resolution);
return value;
}
+/**
+ * gimp_unit_adjustment_set_resolution:
+ * @adjustment: The adjustment you want to set the value of.
+ * @resolution: The new resolution.
+ *
+ * Sets the resolution of a #GimpUnitAdjustment in dpi.
+ *
+ * Emits the "resolution-changed" signal.
+ **/
void
-gimp_unit_adjustment_set_resolution (GimpUnitAdjustment *adj,
+gimp_unit_adjustment_set_resolution (GimpUnitAdjustment *adjustment,
gdouble res)
{
- GimpUnitAdjustmentPrivate *private = GIMP_UNIT_ADJUSTMENT_GET_PRIVATE (adj);
+ GimpUnitAdjustmentPrivate *private = GIMP_UNIT_ADJUSTMENT_GET_PRIVATE (adjustment);
if (private->resolution != res)
{
private->resolution = res;
/* emit "resolution-changed" */
- g_signal_emit(adj, unit_adjustment_signals [RESOLUTION_CHANGED], 0);
+ g_signal_emit(adjustment, unit_adjustment_signals [RESOLUTION_CHANGED], 0);
}
}
+/**
+ * gimp_unit_adjustment_get_resolution:
+ * @adjustment: The adjustment you want to get the resolution from.
+ *
+ * Returns: The resolution of the #GimpUnitAdjustment in dpi.
+ **/
gdouble
-gimp_unit_adjustment_get_resolution (GimpUnitAdjustment *adj)
+gimp_unit_adjustment_get_resolution (GimpUnitAdjustment *adjustment)
{
- GimpUnitAdjustmentPrivate *private = GIMP_UNIT_ADJUSTMENT_GET_PRIVATE (adj);
+ GimpUnitAdjustmentPrivate *private = GIMP_UNIT_ADJUSTMENT_GET_PRIVATE (adjustment);
return private->resolution;
}
+/**
+ * gimp_unit_adjustment_get_unit:
+ * @adjustment: The adjustment you want to get the unit from.
+ *
+ * Returns: The unit of the #GimpUnitAdjustment.
+ **/
GimpUnit
-gimp_unit_adjustment_get_unit (GimpUnitAdjustment *adj)
+gimp_unit_adjustment_get_unit (GimpUnitAdjustment *adjustment)
{
- GimpUnitAdjustmentPrivate *private = GIMP_UNIT_ADJUSTMENT_GET_PRIVATE (adj);
+ GimpUnitAdjustmentPrivate *private = GIMP_UNIT_ADJUSTMENT_GET_PRIVATE (adjustment);
return private->unit;
}
+/**
+ * gimp_unit_adjustment_set_bounds:
+ * @adjustment: The adjustment you want to set the bounds of.
+ * @unit: The unit your given bounds are in.
+ * @lower: The lower bound.
+ * @upper: The upper bound.
+ *
+ * Sets the lower and upper bounds (minimum and maximum value) of a #GimpUnitAdjustment.
+ *
+ * The bounds are converted from the given unit to the adjustment's. If the adjustment's
+ * value is smaller/bigger than the lower/upper bound, it is automatically changed to be
+ * in bounds. Note that if you change the adjustments unit, the bounds are also
+ * converted to that unit.
+ **/
void
-gimp_unit_adjustment_set_bounds (GimpUnitAdjustment *adj,
+gimp_unit_adjustment_set_bounds (GimpUnitAdjustment *adjustment,
GimpUnit unit,
gdouble lower,
gdouble upper)
{
- GimpUnitAdjustmentPrivate *private = GIMP_UNIT_ADJUSTMENT_GET_PRIVATE (adj);
+ GimpUnitAdjustmentPrivate *private = GIMP_UNIT_ADJUSTMENT_GET_PRIVATE (adjustment);
gdouble temp;
/* switch lower and upper bounds if neccessary
- (older revisions used gimp_unit_adjustment_set_bounds (adj, unit, upper, lower)) */
+ (older revisions used gimp_unit_adjustment_set_bounds (adjustment, unit, upper, lower)) */
if (lower > upper)
{
temp = upper;
@@ -298,22 +409,40 @@ gimp_unit_adjustment_set_bounds (GimpUnitAdjustment *adj,
}
/* convert bounds from given unit to current unit */
- upper = gimp_units_to_pixels (upper,
- unit,
- private->resolution);
- lower = gimp_units_to_pixels (lower,
- unit,
- private->resolution);
-
- upper = gimp_pixels_to_units (upper,
- private->unit,
- private->resolution);
- lower = gimp_pixels_to_units (lower,
- private->unit,
- private->resolution);
+ upper = gimp_unit_adjustment_value_to_unit (upper,
+ unit,
+ private->unit,
+ private->resolution);
+ lower = gimp_unit_adjustment_value_to_unit (lower,
+ unit,
+ private->unit,
+ private->resolution);
/* set bounds */
- gtk_adjustment_set_upper (GTK_ADJUSTMENT (adj), upper);
- gtk_adjustment_set_lower (GTK_ADJUSTMENT (adj), lower);
+ gtk_adjustment_set_upper (GTK_ADJUSTMENT (adjustment), upper);
+ gtk_adjustment_set_lower (GTK_ADJUSTMENT (adjustment), lower);
+
+ /* update value if neccessary */
+ temp = gimp_unit_adjustment_get_value_in_unit (adjustment, unit);
+ if (temp < lower)
+ {
+ gimp_unit_adjustment_set_value (adjustment, lower);
+ }
+ else if (temp > upper)
+ {
+ gimp_unit_adjustment_set_value (adjustment, upper);
+ }
}
+static gdouble
+gimp_unit_adjustment_value_to_unit (gdouble value,
+ GimpUnit current_unit,
+ GimpUnit new_unit,
+ gdouble resolution)
+{
+ gdouble new_value;
+
+ new_value = gimp_units_to_pixels (value, current_unit, resolution);
+
+ return gimp_pixels_to_units (new_value, new_unit, resolution);
+}
diff --git a/libgimpwidgets/gimpunitentry.c b/libgimpwidgets/gimpunitentry.c
index f1cf40b..22d6ef6 100644
--- a/libgimpwidgets/gimpunitentry.c
+++ b/libgimpwidgets/gimpunitentry.c
@@ -38,6 +38,39 @@
#include "gimpunitentry.h"
#include "gimpunitadjustment.h"
+/**
+ * SECTION: gimpunitentry
+ * @title: GimpUnitEntry
+ * @short_description: A #GtkSpinButton subclass for entering a value
+ * and the corresponding unit.
+ * @see_also: #GimpUnitAdjustment, #GimpUnit, #GimpEevl
+ *
+ * #GimpUnitEntry is a subclass of #GtkSpinButton. It provides an entry field
+ * for entering a value and its unit. The input is parsed via the #GimpEevl
+ * parser, supporting basic mathematical operations including terms with different
+ * units (e.g. "20 cm + 10 px"). Parsing and updating the value is done "live" while
+ * the user enters the string and not just after the entry looses keyboard focus.
+ *
+ * The unit of the entered string is automatically
+ * determined (either the first entered unit or, if the user didn't input one,
+ * the last set unit). Currently only entering the unit abbreviation is supported
+ * ("in" is seen as valid input, "inch" however isn't). If the user inputs an invalid
+ * string, this is indicated by painting the entry red after a short delay.
+ *
+ * #GimpUnitEntry uses the #GimpUnit system and thus supports all units the currently
+ * installed Gimp version supports (including user defined units). The user can also set
+ * the unit via the right-click menu.
+ *
+ * #GimpUnitEntry also supports basic resolution input (see #gimp_unit_entry_set_mode).
+ *
+ * For holding the actual value/unit, #GimpUnitAdjustment is used. Note that you need to
+ * manually create the GimpUnitAdjustment object and set it via
+ * #gimp_unit_entry_set_adjustment. #GimpUnitEntry provides a few convenience getter/setter
+ * methods for accessing the actual value/unit of the adjustment, but for more options you
+ * need to access the #GimpUnitAdjustment directly.
+ *
+ **/
+
/* debug macro */
//#define UNITENTRY_DEBUG
#ifdef UNITENTRY_DEBUG
@@ -135,6 +168,15 @@ gimp_unit_entry_class_init (GimpUnitEntryClass *class)
g_type_class_add_private (class, sizeof (GimpUnitEntryPrivate));
}
+/**
+ * gimp_unit_entry_new:
+ *
+ * Creates a new #GimpUnitEntry object. Note that this does not create the corresponding
+ * #GimpUnitAdjustment which actually holds the value/unit. Like with #GtkSpinButton you
+ * need to manually create the adjustment and set it via #gimp_unit_entry_set_adjustment.
+ *
+ * Returns: A Pointer to the new #GimpUnitEntry object.
+ **/
GtkWidget*
gimp_unit_entry_new (void)
{
@@ -143,6 +185,12 @@ gimp_unit_entry_new (void)
return entry;
}
+/**
+ * gimp_unit_entry_get_adjustment:
+ * @entry: The #GimpUnitEntry you want to get the adjustment of.
+ *
+ * Returns: A Pointer to the #GimpUnitAdjustment object of the given entry.
+ **/
GimpUnitAdjustment*
gimp_unit_entry_get_adjustment (GimpUnitEntry *entry)
{
@@ -158,6 +206,13 @@ gimp_unit_entry_get_adjustment (GimpUnitEntry *entry)
return GIMP_UNIT_ADJUSTMENT (adjustment);
}
+/**
+ * gimp_unit_entry_set_adjustment:
+ * @entry: The #GimpUnitEntry you want to set the adjustment of.
+ * @adjustment: The #GimpUnitAdjustment you want to set.
+ *
+ * Sets the #GimpUnitAdjustment of an entry.
+ **/
void
gimp_unit_entry_set_adjustment (GimpUnitEntry *entry,
GimpUnitAdjustment *adjustment)
@@ -171,7 +226,15 @@ gimp_unit_entry_set_adjustment (GimpUnitEntry *entry,
(gpointer) adjustment);
}
-/* connect to another entry */
+/**
+ * gimp_unit_entry_connect:
+ * @entry: The #GimpUnitEntry you want to automatically change unit.
+ * @target: The #GimpUnitEntry you want to follow.
+ *
+ * Connects one entry to another entry so that it automatically changes its unit
+ * whenever the second entry does. Just a convenience function for invoking
+ * #gimp_unit_adjustment_follow_unit_of so see there for details.
+ **/
void
gimp_unit_entry_connect (GimpUnitEntry *entry,
GimpUnitEntry *target)
@@ -398,7 +461,12 @@ gimp_unit_entry_menu_item (GtkWidget *menu_item,
gimp_unit_adjustment_set_unit (adj, unit);
}
-/* convenience getters/setters */
+/**
+ * gimp_unit_entry_get_pixels:
+ * @entry: The #GimpUnitEntry you want to get the value of.
+ *
+ * Returns: The current value of the entry converted to pixels.
+ **/
gdouble
gimp_unit_entry_get_pixels (GimpUnitEntry *entry)
{
@@ -407,6 +475,17 @@ gimp_unit_entry_get_pixels (GimpUnitEntry *entry)
return gimp_unit_adjustment_get_value_in_unit (adj, GIMP_UNIT_PIXEL);
}
+/**
+ * gimp_unit_entry_set_bounds:
+ * @adjustment: The entry you want to set the bounds of.
+ * @unit: The unit your given bounds are in.
+ * @lower: The lower bound.
+ * @upper: The upper bound.
+ *
+ * Sets the lower and upper bounds (minimum and maximum values) of a #GimpUnitEntry.
+ *
+ * See #gimp_unit_adjustment_set_bounds for details.
+ **/
void
gimp_unit_entry_set_bounds (GimpUnitEntry *entry,
GimpUnit unit,
@@ -417,6 +496,13 @@ gimp_unit_entry_set_bounds (GimpUnitEntry *entry,
gimp_unit_adjustment_set_bounds (adj, unit, lower, upper);
}
+/**
+ * gimp_unit_entry_set_pixels:
+ * @entry: The #GimpUnitEntry you want to set the value of.
+ *
+ * Set the pixel value of an #GimpUnitEntry. The value is converted to the current
+ * unit of the entry.
+ **/
void
gimp_unit_entry_set_pixels (GimpUnitEntry *entry,
gdouble value)
@@ -425,6 +511,20 @@ gimp_unit_entry_set_pixels (GimpUnitEntry *entry,
gimp_unit_adjustment_set_value_in_unit (adj, value, GIMP_UNIT_PIXEL);
}
+/**
+ * gimp_unit_entry_set_mode:
+ * @entry: The #GimpUnitEntry you want to set the mode of.
+ * @mode: The mode of the entry.
+ *
+ * Sets the input mode of the entry. Possible modes are GIMP_UNIT_ENTRY_MODE_UNIT and
+ * GIMP_UNIT_ENTRY_MODE_RESOLUTION. Unit mode is default, but if you set the entry to
+ * resolution mode, the input is interpreted as a resolution.
+ *
+ * Note that resolution mode is very basic and disables the parser and mathematical
+ * expressions completely. The user can then just input a value and set the unit
+ * via the right-click menu. The unit is to be interpreted as pixels per unit.
+ * If the input e.g. is 72 px/in, then the value is 72.0 and the unit is inch.
+ **/
void
gimp_unit_entry_set_mode (GimpUnitEntry *entry,
GimpUnitEntryMode mode)
@@ -441,7 +541,14 @@ gimp_unit_entry_set_mode (GimpUnitEntry *entry,
}
}
-/* get string in format "value unit" */
+/**
+ * gimp_unit_entry_to_string:
+ * @entry: The #GimpUnitEntry you want to get the value string of.
+ *
+ * IMPORTANT: The returned string needs to be g_free()'d after usage!
+ *
+ * Returns: A string containing the current value and unit of the entry
+ **/
gchar*
gimp_unit_entry_to_string (GimpUnitEntry *entry)
{
@@ -450,6 +557,15 @@ gimp_unit_entry_to_string (GimpUnitEntry *entry)
gimp_unit_adjustment_get_unit (gimp_unit_entry_get_adjustment (entry)));
}
+/**
+ * gimp_unit_entry_to_string_in_unit:
+ * @entry: The #GimpUnitEntry you want to get the value string of.
+ * @unit: The #GimpUnit the value shall be converted to.
+ *
+ * IMPORTANT: The returned string needs to be g_free()'d after usage!
+ *
+ * Returns: A string containing the current value converted to the given unit and the unit.
+ **/
gchar*
gimp_unit_entry_to_string_in_unit (GimpUnitEntry *entry,
GimpUnit unit)
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
