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

[~andy/gtk] / gtk / gtkprogressbar.h

diff --git a/gtk/gtkprogressbar.h b/gtk/gtkprogressbar.h
index 7db79df174dfaaaeb84668322982e47d9d703c5c..0296be19541b4f70226639d0e97d271c052a0cbd 100644 (file)
--- 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 */