Implement new sane, 5-function API for using GtkProgressBar. See

2000-07-25  Havoc Pennington  <hp@redhat.com>

* gtk/gtkprogressbar.h: Implement new sane, 5-function API for
using GtkProgressBar. See Changes-2.0.txt for details.

* gtk/gtkprogressbar.c: Add object arguments "fraction" and
"pulse_step" which are the equivalent of
gtk_progress_bar_set_pulse_step and gtk_progress_bar_set_fraction.
Implement new API.

* gtk/gtkprogress.h (struct _GtkProgress): Add a field
(use_text_format) to mark whether text set on the progress bar is
a format string. Deprecate entire GtkProgress interface.

* gtk/gtkprogress.c (gtk_progress_init): init use_text_format to TRUE
(gtk_progress_build_string): make this a no-op if use_text_format
is FALSE

* docs/Changes-2.0.txt: Describe progress bar changes.

12 files changed, 344 insertions, 11 deletions

diff --git a/ChangeLog b/ChangeLog
index 0b3adb73e7..5691db4055 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,23 @@
+2000-07-25  Havoc Pennington  <hp@redhat.com>
+
+	* gtk/gtkprogressbar.h: Implement new sane, 5-function API for
+	using GtkProgressBar. See Changes-2.0.txt for details.
+
+	* gtk/gtkprogressbar.c: Add object arguments "fraction" and
+	"pulse_step" which are the equivalent of
+	gtk_progress_bar_set_pulse_step and gtk_progress_bar_set_fraction.
+	Implement new API.
+	
+	* gtk/gtkprogress.h (struct _GtkProgress): Add a field
+	(use_text_format) to mark whether text set on the progress bar is
+	a format string. Deprecate entire GtkProgress interface.
+
+	* gtk/gtkprogress.c (gtk_progress_init): init use_text_format to TRUE
+	(gtk_progress_build_string): make this a no-op if use_text_format
+	is FALSE
+
+	* docs/Changes-2.0.txt: Describe progress bar changes.
+
 2000-07-25  Tor Lillqvist  <tml@iki.fi>
 
 	* Makefile.am: Include the build directory.
diff --git a/ChangeLog.pre-2-0 b/ChangeLog.pre-2-0
index 0b3adb73e7..5691db4055 100644
--- a/ChangeLog.pre-2-0
+++ b/ChangeLog.pre-2-0
@@ -1,3 +1,23 @@
+2000-07-25  Havoc Pennington  <hp@redhat.com>
+
+	* gtk/gtkprogressbar.h: Implement new sane, 5-function API for
+	using GtkProgressBar. See Changes-2.0.txt for details.
+
+	* gtk/gtkprogressbar.c: Add object arguments "fraction" and
+	"pulse_step" which are the equivalent of
+	gtk_progress_bar_set_pulse_step and gtk_progress_bar_set_fraction.
+	Implement new API.
+	
+	* gtk/gtkprogress.h (struct _GtkProgress): Add a field
+	(use_text_format) to mark whether text set on the progress bar is
+	a format string. Deprecate entire GtkProgress interface.
+
+	* gtk/gtkprogress.c (gtk_progress_init): init use_text_format to TRUE
+	(gtk_progress_build_string): make this a no-op if use_text_format
+	is FALSE
+
+	* docs/Changes-2.0.txt: Describe progress bar changes.
+
 2000-07-25  Tor Lillqvist  <tml@iki.fi>
 
 	* Makefile.am: Include the build directory.
diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10
index 0b3adb73e7..5691db4055 100644
--- a/ChangeLog.pre-2-10
+++ b/ChangeLog.pre-2-10
@@ -1,3 +1,23 @@
+2000-07-25  Havoc Pennington  <hp@redhat.com>
+
+	* gtk/gtkprogressbar.h: Implement new sane, 5-function API for
+	using GtkProgressBar. See Changes-2.0.txt for details.
+
+	* gtk/gtkprogressbar.c: Add object arguments "fraction" and
+	"pulse_step" which are the equivalent of
+	gtk_progress_bar_set_pulse_step and gtk_progress_bar_set_fraction.
+	Implement new API.
+	
+	* gtk/gtkprogress.h (struct _GtkProgress): Add a field
+	(use_text_format) to mark whether text set on the progress bar is
+	a format string. Deprecate entire GtkProgress interface.
+
+	* gtk/gtkprogress.c (gtk_progress_init): init use_text_format to TRUE
+	(gtk_progress_build_string): make this a no-op if use_text_format
+	is FALSE
+
+	* docs/Changes-2.0.txt: Describe progress bar changes.
+
 2000-07-25  Tor Lillqvist  <tml@iki.fi>
 
 	* Makefile.am: Include the build directory.
diff --git a/ChangeLog.pre-2-2 b/ChangeLog.pre-2-2
index 0b3adb73e7..5691db4055 100644
--- a/ChangeLog.pre-2-2
+++ b/ChangeLog.pre-2-2
@@ -1,3 +1,23 @@
+2000-07-25  Havoc Pennington  <hp@redhat.com>
+
+	* gtk/gtkprogressbar.h: Implement new sane, 5-function API for
+	using GtkProgressBar. See Changes-2.0.txt for details.
+
+	* gtk/gtkprogressbar.c: Add object arguments "fraction" and
+	"pulse_step" which are the equivalent of
+	gtk_progress_bar_set_pulse_step and gtk_progress_bar_set_fraction.
+	Implement new API.
+	
+	* gtk/gtkprogress.h (struct _GtkProgress): Add a field
+	(use_text_format) to mark whether text set on the progress bar is
+	a format string. Deprecate entire GtkProgress interface.
+
+	* gtk/gtkprogress.c (gtk_progress_init): init use_text_format to TRUE
+	(gtk_progress_build_string): make this a no-op if use_text_format
+	is FALSE
+
+	* docs/Changes-2.0.txt: Describe progress bar changes.
+
 2000-07-25  Tor Lillqvist  <tml@iki.fi>
 
 	* Makefile.am: Include the build directory.
diff --git a/ChangeLog.pre-2-4 b/ChangeLog.pre-2-4
index 0b3adb73e7..5691db4055 100644
--- a/ChangeLog.pre-2-4
+++ b/ChangeLog.pre-2-4
@@ -1,3 +1,23 @@
+2000-07-25  Havoc Pennington  <hp@redhat.com>
+
+	* gtk/gtkprogressbar.h: Implement new sane, 5-function API for
+	using GtkProgressBar. See Changes-2.0.txt for details.
+
+	* gtk/gtkprogressbar.c: Add object arguments "fraction" and
+	"pulse_step" which are the equivalent of
+	gtk_progress_bar_set_pulse_step and gtk_progress_bar_set_fraction.
+	Implement new API.
+	
+	* gtk/gtkprogress.h (struct _GtkProgress): Add a field
+	(use_text_format) to mark whether text set on the progress bar is
+	a format string. Deprecate entire GtkProgress interface.
+
+	* gtk/gtkprogress.c (gtk_progress_init): init use_text_format to TRUE
+	(gtk_progress_build_string): make this a no-op if use_text_format
+	is FALSE
+
+	* docs/Changes-2.0.txt: Describe progress bar changes.
+
 2000-07-25  Tor Lillqvist  <tml@iki.fi>
 
 	* Makefile.am: Include the build directory.
diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6
index 0b3adb73e7..5691db4055 100644
--- a/ChangeLog.pre-2-6
+++ b/ChangeLog.pre-2-6
@@ -1,3 +1,23 @@
+2000-07-25  Havoc Pennington  <hp@redhat.com>
+
+	* gtk/gtkprogressbar.h: Implement new sane, 5-function API for
+	using GtkProgressBar. See Changes-2.0.txt for details.
+
+	* gtk/gtkprogressbar.c: Add object arguments "fraction" and
+	"pulse_step" which are the equivalent of
+	gtk_progress_bar_set_pulse_step and gtk_progress_bar_set_fraction.
+	Implement new API.
+	
+	* gtk/gtkprogress.h (struct _GtkProgress): Add a field
+	(use_text_format) to mark whether text set on the progress bar is
+	a format string. Deprecate entire GtkProgress interface.
+
+	* gtk/gtkprogress.c (gtk_progress_init): init use_text_format to TRUE
+	(gtk_progress_build_string): make this a no-op if use_text_format
+	is FALSE
+
+	* docs/Changes-2.0.txt: Describe progress bar changes.
+
 2000-07-25  Tor Lillqvist  <tml@iki.fi>
 
 	* Makefile.am: Include the build directory.
diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8
index 0b3adb73e7..5691db4055 100644
--- a/ChangeLog.pre-2-8
+++ b/ChangeLog.pre-2-8
@@ -1,3 +1,23 @@
+2000-07-25  Havoc Pennington  <hp@redhat.com>
+
+	* gtk/gtkprogressbar.h: Implement new sane, 5-function API for
+	using GtkProgressBar. See Changes-2.0.txt for details.
+
+	* gtk/gtkprogressbar.c: Add object arguments "fraction" and
+	"pulse_step" which are the equivalent of
+	gtk_progress_bar_set_pulse_step and gtk_progress_bar_set_fraction.
+	Implement new API.
+	
+	* gtk/gtkprogress.h (struct _GtkProgress): Add a field
+	(use_text_format) to mark whether text set on the progress bar is
+	a format string. Deprecate entire GtkProgress interface.
+
+	* gtk/gtkprogress.c (gtk_progress_init): init use_text_format to TRUE
+	(gtk_progress_build_string): make this a no-op if use_text_format
+	is FALSE
+
+	* docs/Changes-2.0.txt: Describe progress bar changes.
+
 2000-07-25  Tor Lillqvist  <tml@iki.fi>
 
 	* Makefile.am: Include the build directory.
diff --git a/docs/Changes-2.0.txt b/docs/Changes-2.0.txt
index 5b4f2507d7..14cb9d0098 100644
--- a/docs/Changes-2.0.txt
+++ b/docs/Changes-2.0.txt
@@ -189,4 +189,44 @@ Incompatible Changes from GTK+-1.2 to GTK+-1.4:
   to the behavior of gdk_window_foreign_new(), and fixes a lot
   of problems with code where the pixmap wasn't supposed to be
   freed. If XFreePixmap() is needed, it can be done using the
-  destroy-notification facilities of g_object_set_data().
\ No newline at end of file
+  destroy-notification facilities of g_object_set_data().
+
+-  GtkProgress/GtkProgressBar had serious problems in GTK 1.2.
+ 
+  - Only 3 or 4 functions are really needed for 95% of progress  
+    interfaces; GtkProgress[Bar] had about 25 functions, and 
+    didn't even include these 3 or 4.
+  - In activity mode, the API involves setting the adjustment 
+    to any random value, just to have the side effect of 
+    calling the progress bar update function - the adjustment
+    is totally ignored in activity mode
+  - You set the activity step as a pixel value, which means to 
+    set the activity step you basically need to connect to 
+    size_allocate
+  - There are ctree_set_expander_style()-functions, to randomly 
+    change look-and-feel for no good reason
+  - The split between GtkProgress and GtkProgressBar makes no sense 
+    to me whatsoever.
+  
+ This was a big wart on GTK and made people waste lots of time,
+ both learning and using the interface.
+ 
+ So, we have added what we feel is the correct API, and marked all the
+ rest deprecated. However, the changes are 100% backward-compatible and
+ should break no existing code.
+
+ The following 5 functions are the new programming interface and you 
+ should consider changing your code to use them:
+ 
+  void       gtk_progress_bar_pulse                (GtkProgressBar *pbar);
+  void       gtk_progress_bar_set_text             (GtkProgressBar *pbar,
+                                                    const gchar    *text);
+  void       gtk_progress_bar_set_fraction         (GtkProgressBar *pbar,
+                                                    gfloat          fraction);
+
+  void       gtk_progress_bar_set_pulse_step       (GtkProgressBar *pbar,
+                                                    gfloat          fraction);
+  void       gtk_progress_bar_set_orientation      (GtkProgressBar *pbar,
+						    GtkProgressBarOrientation orientation);
+
+
diff --git a/gtk/gtkprogress.c b/gtk/gtkprogress.c
index 44ed4f4e89..4d31ce8943 100644
--- a/gtk/gtkprogress.c
+++ b/gtk/gtkprogress.c
@@ -198,6 +198,7 @@ gtk_progress_init (GtkProgress *progress)
   progress->y_align = 0.5;
   progress->show_text = FALSE;
   progress->activity_mode = FALSE;
+  progress->use_text_format = TRUE;
 }
 
 static void
@@ -357,6 +358,13 @@ gtk_progress_build_string (GtkProgress *progress,
   gchar fmt[10];
 
   src = progress->format;
+
+  /* This is the new supported version of this function */
+  if (!progress->use_text_format)
+    return g_strdup (src);
+
+  /* And here's all the deprecated goo. */
+  
   dest = buf;
  
   while (src && *src)
@@ -624,6 +632,11 @@ gtk_progress_set_format_string (GtkProgress *progress,
   g_return_if_fail (progress != NULL);
   g_return_if_fail (GTK_IS_PROGRESS (progress));
 
+  /* Turn on format, in case someone called
+   * gtk_progress_bar_set_text() and turned it off.
+   */
+  progress->use_text_format = TRUE;
+  
   if (format)
     {
       if (progress->format)
diff --git a/gtk/gtkprogress.h b/gtk/gtkprogress.h
index 5bf18f0ec1..11ab48d9b0 100644
--- a/gtk/gtkprogress.h
+++ b/gtk/gtkprogress.h
@@ -62,6 +62,7 @@ struct _GtkProgress
 
   guint          show_text : 1;
   guint          activity_mode : 1;
+  guint          use_text_format : 1;
 };
 
 struct _GtkProgressClass
@@ -73,6 +74,9 @@ struct _GtkProgressClass
   void (* act_mode_enter)   (GtkProgress *progress);
 };
 
+/* This entire interface is deprecated. Use GtkProgressBar
+ * directly.
+ */
 
 GtkType    gtk_progress_get_type            (void);
 void       gtk_progress_set_show_text       (GtkProgress   *progress,
diff --git a/gtk/gtkprogressbar.c b/gtk/gtkprogressbar.c
index e1db4c6b93..562fd3d3a2 100644
--- a/gtk/gtkprogressbar.c
+++ b/gtk/gtkprogressbar.c
@@ -52,7 +52,9 @@ enum {
   ARG_BAR_STYLE,
   ARG_ACTIVITY_STEP,
   ARG_ACTIVITY_BLOCKS,
-  ARG_DISCRETE_BLOCKS
+  ARG_DISCRETE_BLOCKS,
+  ARG_FRACTION,
+  ARG_PULSE_STEP
 };
 
 static void gtk_progress_bar_class_init    (GtkProgressBarClass *klass);
@@ -130,7 +132,15 @@ gtk_progress_bar_class_init (GtkProgressBarClass *class)
 			   GTK_TYPE_UINT,
 			   GTK_ARG_READWRITE,
 			   ARG_DISCRETE_BLOCKS);
-
+  gtk_object_add_arg_type ("GtkProgressBar::fraction",
+			   GTK_TYPE_FLOAT,
+			   GTK_ARG_READWRITE,
+			   ARG_FRACTION);
+  gtk_object_add_arg_type ("GtkProgressBar::pulse_step",
+			   GTK_TYPE_FLOAT,
+			   GTK_ARG_READWRITE,
+			   ARG_FRACTION);
+  
   object_class->set_arg = gtk_progress_bar_set_arg;
   object_class->get_arg = gtk_progress_bar_get_arg;
 
@@ -148,6 +158,7 @@ gtk_progress_bar_init (GtkProgressBar *pbar)
   pbar->blocks = 10;
   pbar->in_block = -1;
   pbar->orientation = GTK_PROGRESS_LEFT_TO_RIGHT;
+  pbar->pulse_fraction = 0.1;
   pbar->activity_pos = 0;
   pbar->activity_dir = 1;
   pbar->activity_step = 3;
@@ -183,6 +194,12 @@ gtk_progress_bar_set_arg (GtkObject           *object,
     case ARG_DISCRETE_BLOCKS:
       gtk_progress_bar_set_discrete_blocks (pbar, GTK_VALUE_UINT (*arg));
       break;
+    case ARG_FRACTION:
+      gtk_progress_bar_set_fraction (pbar, GTK_VALUE_FLOAT (*arg));
+      break;
+    case ARG_PULSE_STEP:
+      gtk_progress_bar_set_pulse_step (pbar, GTK_VALUE_FLOAT (*arg));
+      break;
     default:
       break;
     }
@@ -217,6 +234,12 @@ gtk_progress_bar_get_arg (GtkObject           *object,
     case ARG_DISCRETE_BLOCKS:
       GTK_VALUE_UINT (*arg) = pbar->blocks;
       break;
+    case ARG_FRACTION:
+      GTK_VALUE_FLOAT (*arg) = gtk_progress_get_current_percentage (GTK_PROGRESS (pbar));
+      break;
+    case ARG_PULSE_STEP:
+      GTK_VALUE_FLOAT (*arg) = pbar->pulse_fraction;
+      break;
     default:
       arg->type = GTK_TYPE_INVALID;
       break;
@@ -266,12 +289,16 @@ gtk_progress_bar_real_update (GtkProgress *progress)
       if (GTK_PROGRESS (pbar)->activity_mode)
 	{
 	  guint size;
-
+          
 	  /* advance the block */
 
 	  if (pbar->orientation == GTK_PROGRESS_LEFT_TO_RIGHT ||
 	      pbar->orientation == GTK_PROGRESS_RIGHT_TO_LEFT)
 	    {
+              /* Update our activity step. */
+              
+              pbar->activity_step = widget->allocation.width * pbar->pulse_fraction;
+              
 	      size = MAX (2, widget->allocation.width / pbar->activity_blocks);
 
 	      if (pbar->activity_dir == 0)
@@ -298,6 +325,10 @@ gtk_progress_bar_real_update (GtkProgress *progress)
 	    }
 	  else
 	    {
+              /* Update our activity step. */
+              
+              pbar->activity_step = widget->allocation.height * pbar->pulse_fraction;
+              
 	      size = MAX (2, widget->allocation.height / pbar->activity_blocks);
 
 	      if (pbar->activity_dir == 0)
@@ -747,16 +778,77 @@ gtk_progress_bar_paint (GtkProgress *progress)
 /*******************************************************************/
 
 void
+gtk_progress_bar_set_fraction (GtkProgressBar *pbar,
+                               gfloat          fraction)
+{
+  g_return_if_fail (pbar != NULL);
+  g_return_if_fail (GTK_IS_PROGRESS_BAR (pbar));
+
+  /* If we know the percentage, we don't want activity mode. */
+  gtk_progress_set_activity_mode (GTK_PROGRESS (pbar), FALSE);
+  
+  /* We use the deprecated GtkProgress interface internally.
+   * Once everything's been deprecated for a good long time,
+   * we can clean up all this code.
+   */
+  gtk_progress_set_percentage (GTK_PROGRESS (pbar), fraction);
+}
+
+void
+gtk_progress_bar_pulse (GtkProgressBar *pbar)
+{  
+  g_return_if_fail (pbar != NULL);
+  g_return_if_fail (GTK_IS_PROGRESS_BAR (pbar));
+
+  /* If we don't know the percentage, we must want activity mode. */
+  gtk_progress_set_activity_mode (GTK_PROGRESS (pbar), TRUE);
+
+  /* Sigh. */
+  gtk_progress_bar_real_update (GTK_PROGRESS (pbar));
+}
+
+void
+gtk_progress_bar_set_text (GtkProgressBar *pbar,
+                           const gchar *text)
+{
+  g_return_if_fail (pbar != NULL);
+  g_return_if_fail (GTK_IS_PROGRESS_BAR (pbar));
+  
+  /* We don't support formats in this interface */
+  GTK_PROGRESS (pbar)->use_text_format = FALSE;
+  
+  if (text && *text)
+    {
+      gtk_progress_set_show_text (GTK_PROGRESS (pbar), TRUE);
+      gtk_progress_set_format_string (GTK_PROGRESS (pbar), text);
+    }
+  else
+    {
+      gtk_progress_set_show_text (GTK_PROGRESS (pbar), FALSE);
+      gtk_progress_set_format_string (GTK_PROGRESS (pbar), "");
+    }
+}
+
+void
+gtk_progress_bar_set_pulse_step   (GtkProgressBar *pbar,
+                                   gfloat          fraction)
+{
+  g_return_if_fail (pbar != NULL);
+  g_return_if_fail (GTK_IS_PROGRESS_BAR (pbar));
+  
+  pbar->pulse_fraction = fraction;
+}
+
+void
 gtk_progress_bar_update (GtkProgressBar *pbar,
 			 gfloat          percentage)
 {
   g_return_if_fail (pbar != NULL);
   g_return_if_fail (GTK_IS_PROGRESS_BAR (pbar));
 
-  /***********************************************************************
-   *          Use of gtk_progress_bar_update() is deprecated !	         * 
-   * Use gtk_progress_set_value or gtk_progress_set_percentage instead.  *
-   ***********************************************************************/
+  /* Use of gtk_progress_bar_update() is deprecated ! 
+   * Use gtk_progress_bar_set_percentage ()
+   */   
 
   gtk_progress_set_percentage (GTK_PROGRESS (pbar), percentage);
 }
diff --git a/gtk/gtkprogressbar.h b/gtk/gtkprogressbar.h
index 7db79df174..0296be1954 100644
--- a/gtk/gtkprogressbar.h
+++ b/gtk/gtkprogressbar.h
@@ -75,6 +75,9 @@ struct _GtkProgressBar
   gint  activity_pos;
   guint activity_step;
   guint activity_blocks;
+
+  gfloat pulse_fraction;
+  
   guint activity_dir : 1;
 };
 
@@ -86,21 +89,62 @@ struct _GtkProgressBarClass
 
 GtkType    gtk_progress_bar_get_type             (void);
 GtkWidget* gtk_progress_bar_new                  (void);
+
+/*
+ * GtkProgress/GtkProgressBar had serious problems in GTK 1.2.
+ * 
+ *  - Only 3 or 4 functions are really needed for 95% of progress  
+ *    interfaces; GtkProgress[Bar] had about 25 functions, and 
+ *    didn't even include these 3 or 4.
+ *  - In activity mode, the API involves setting the adjustment 
+ *    to any random value, just to have the side effect of 
+ *    calling the progress bar update function - the adjustment
+ *    is totally ignored in activity mode
+ *  - You set the activity step as a pixel value, which means to 
+ *    set the activity step you basically need to connect to 
+ *    size_allocate
+ *  - There are ctree_set_expander_style()-functions, to randomly 
+ *    change look-and-feel for no good reason
+ *  - The split between GtkProgress and GtkProgressBar makes no sense 
+ *    to me whatsoever.
+ *  
+ * This was a big wart on GTK and made people waste lots of time,
+ * both learning and using the interface.
+ * 
+ * So, I have added what I feel is the correct API, and marked all the
+ * rest deprecated. However, the changes are 100% backward-compatible and
+ * should break no existing code.
+ *
+ * The following 5 functions are the new programming interface. 
+ */
+void       gtk_progress_bar_pulse                (GtkProgressBar *pbar);
+void       gtk_progress_bar_set_text             (GtkProgressBar *pbar,
+                                                  const gchar    *text);
+void       gtk_progress_bar_set_fraction         (GtkProgressBar *pbar,
+                                                  gfloat          fraction);
+
+void       gtk_progress_bar_set_pulse_step       (GtkProgressBar *pbar,
+                                                  gfloat          fraction);
+void       gtk_progress_bar_set_orientation      (GtkProgressBar *pbar,
+						  GtkProgressBarOrientation orientation);
+
+/* Everything below here is deprecated */
 GtkWidget* gtk_progress_bar_new_with_adjustment  (GtkAdjustment  *adjustment);
 void       gtk_progress_bar_set_bar_style        (GtkProgressBar *pbar,
 						  GtkProgressBarStyle style);
 void       gtk_progress_bar_set_discrete_blocks  (GtkProgressBar *pbar,
 						  guint           blocks);
+/* set_activity_step() is not only deprecated, it doesn't even work.
+ * (Of course, it wasn't usable anyway, you had to set it from a size_allocate
+ * handler or something)
+ */
 void       gtk_progress_bar_set_activity_step    (GtkProgressBar *pbar,
                                                   guint           step);
 void       gtk_progress_bar_set_activity_blocks  (GtkProgressBar *pbar,
 						  guint           blocks);
-void       gtk_progress_bar_set_orientation      (GtkProgressBar *pbar,
-						  GtkProgressBarOrientation orientation);
 void       gtk_progress_bar_update               (GtkProgressBar *pbar,
 						  gfloat          percentage);
 
-
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */