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.

1 files changed, 47 insertions, 3 deletions

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 */