X-Git-Url: https://git.distorted.org.uk/~mdw/disorder/blobdiff_plain/7b73a310fc76e120e9ea569ceb665da7363831d8..4eb1f430bde3b517e045cc7ed68194ff9dbdda4a:/disobedience/control.c

diff --git a/disobedience/control.c b/disobedience/control.c
index ba5b202..f4541f7 100644
--- a/disobedience/control.c
+++ b/disobedience/control.c
@@ -17,6 +17,9 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  * USA
  */
+/** @file disobedience/control.c
+ * @brief Volume control and buttons
+ */
 
 #include "disobedience.h"
 
@@ -25,7 +28,6 @@
 WT(adjustment);
 WT(hscale);
 WT(hbox);
-WT(tooltips);
 WT(button);
 WT(image);
 WT(label);
@@ -51,23 +53,40 @@ static void volume_adjusted(GtkAdjustment *a, gpointer user_data);
 static gchar *format_volume(GtkScale *scale, gdouble value);
 static gchar *format_balance(GtkScale *scale, gdouble value);
 
-static void control_monitor(void *u);
-
 /* Control bar ------------------------------------------------------------- */
 
+/** @brief Guard against feedback loop in volume control */
 static int suppress_set_volume;
-/* Guard against feedback loop in volume control */
 
-static struct icon {
+/** @brief Definition of an icon
+ *
+ * The design here is rather mad: rather than changing the image displayed by
+ * icons according to their state, we flip the visibility of pairs of icons.
+ */
+struct icon {
+  /** @brief Filename for image */
   const char *icon;
+
+  /** @brief Text for tooltip */
   const char *tip;
+
+  /** @brief Called when button is clicked (activated) */
   void (*clicked)(GtkButton *button, gpointer userdata);
+
+  /** @brief Called to update button when state may have changed */
   void (*update)(const struct icon *i);
+
+  /** @brief @ref eclient.h function to call */
   int (*action)(disorder_eclient *c,
                 disorder_eclient_no_response *completed,
                 void *v);
+
+  /** @brief Pointer to button */
   GtkWidget *button;
-} icons[] = {
+};
+
+/** @brief Table of all icons */
+static struct icon icons[] = {
   { "pause.png", "Pause playing track", clicked_icon, update_pause,
     disorder_eclient_pause, 0 },
   { "play.png", "Resume playing track", clicked_icon, update_play,
@@ -83,21 +102,31 @@ static struct icon {
   { "notescross.png", "Disable play", clicked_icon, update_disable,
     disorder_eclient_disable, 0 },
 };
+
+/** @brief Count of icons */
 #define NICONS (int)(sizeof icons / sizeof *icons)
 
-GtkAdjustment *volume_adj, *balance_adj;
+static GtkAdjustment *volume_adj;
+static GtkAdjustment *balance_adj;
+
+/** @brief Called whenever last_state changes in any way */
+static void control_monitor(void attribute((unused)) *u) {
+  int n;
 
-/* Create the control bar */
+  D(("control_monitor"));
+  for(n = 0; n < NICONS; ++n)
+    icons[n].update(&icons[n]);
+}
+
+/** @brief Create the control bar */
 GtkWidget *control_widget(void) {
   GtkWidget *hbox = gtk_hbox_new(FALSE, 1), *vbox;
   GtkWidget *content;
   GdkPixbuf *pb;
   GtkWidget *v, *b;
-  GtkTooltips *tips = gtk_tooltips_new();
   int n;
 
   NW(hbox);
-  NW(tooltips);
   D(("control_widget"));
   for(n = 0; n < NICONS; ++n) {
     NW(button);
@@ -158,12 +187,11 @@ GtkWidget *control_widget(void) {
   return hbox;
 }
 
-/** @brief Update the control bar after some kind of state change */
-void control_update(void) {
+/** @brief Update the volume control when it changes */
+void volume_update(void) {
   double l, r;
 
-  D(("control_update"));
-  /*control_monitor(0, disorder_eclient_state(client));*/
+  D(("volume_update"));
   l = volume_l / 100.0;
   r = volume_r / 100.0;
   ++suppress_set_volume;
@@ -172,13 +200,6 @@ void control_update(void) {
   --suppress_set_volume;
 }
 
-static void control_monitor(void attribute((unused)) *u) {
-  int n;
-
-  for(n = 0; n < NICONS; ++n)
-    icons[n].update(&icons[n]);
-}
-
 /** @brief Update the state of one of the control icons
  * @param icon Target icon
  * @param visible True if this version of the button should be visible
@@ -251,6 +272,7 @@ static void clicked_icon(GtkButton attribute((unused)) *button,
   icon->action(client, 0, 0);
 }
 
+/** @brief Called when the volume has been adjusted */
 static void volume_adjusted(GtkAdjustment attribute((unused)) *a,
                             gpointer attribute((unused)) user_data) {
   double v = gtk_adjustment_get_value(volume_adj) / goesupto;
@@ -272,7 +294,7 @@ static void volume_adjusted(GtkAdjustment attribute((unused)) *a,
                           0);
 }
 
-/* Called to format the volume value */
+/** @brief Formats the volume value */
 static gchar *format_volume(GtkScale attribute((unused)) *scale,
                             gdouble value) {
   char s[32];
@@ -281,7 +303,7 @@ static gchar *format_volume(GtkScale attribute((unused)) *scale,
   return g_strdup(s);
 }
 
-/* Called to format the balance value. */
+/** @brief Formats the balance value */
 static gchar *format_balance(GtkScale attribute((unused)) *scale,
                              gdouble value) {
   char s[32];
@@ -319,10 +341,12 @@ static gchar *format_balance(GtkScale attribute((unused)) *scale,
  * Thanks to Clive and Andrew.
  */
 
+/** @brief Return the greater of @p x and @p y */
 static double max(double x, double y) {
   return x > y ? x : y;
 }
 
+/** @brief Compute the left channel volume */
 static double left(double v, double b) {
   if(b > 0)                             /* volume = right */
     return v * (1 - b);
@@ -330,6 +354,7 @@ static double left(double v, double b) {
     return v;
 }
 
+/** @brief Compute the right channel volume */
 static double right(double v, double b) {
   if(b > 0)                             /* volume = right */
     return v;
@@ -337,10 +362,12 @@ static double right(double v, double b) {
     return v * (1 + b);
 }
 
+/** @brief Compute the overall volume */
 static double volume(double l, double r) {
   return max(l, r);
 }
 
+/** @brief Compute the balance */
 static double balance(double l, double r) {
   if(l > r)
     return r / l - 1;