chiark / gitweb /
doxygen
authorRichard Kettlewell <rjk@greenend.org.uk>
Mon, 1 Oct 2007 17:44:18 +0000 (18:44 +0100)
committerRichard Kettlewell <rjk@greenend.org.uk>
Mon, 1 Oct 2007 17:44:18 +0000 (18:44 +0100)
disobedience/client.c
disobedience/disobedience.h
disobedience/menu.c
disobedience/misc.c

index 506212b..8539221 100644 (file)
@@ -1,6 +1,6 @@
 /*
  * This file is part of DisOrder.
- * Copyright (C) 2006,  2007 Richard Kettlewell
+ * Copyright (C) 2006, 2007 Richard Kettlewell
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
index c3acca7..09e8daf 100644 (file)
@@ -17,6 +17,9 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  * USA
  */
+/** @file disobedience/disobedience.h
+ * @brief Header file for Disobedience, the DisOrder GTK+ client
+ */
 
 #ifndef DISOBEDIENCE_H
 #define DISOBEDIENCE_H
 struct queuelike;
 struct choosenode;
 
+/** @brief Callback data structure
+ *
+ * This program is extremely heavily callback-driven.  Rather than have
+ * numerous different callback structures we have a single one which can be
+ * interpreted adequately both by success and error handlers.
+ */
 struct callbackdata {
   void (*onerror)(struct callbackdata *cbd,
                   int code,
@@ -68,6 +77,11 @@ struct callbackdata {
   } u;
 };
 
+/** @brief Per-tab callbacks
+ *
+ * Some of the options in the main menu depend on which tab is displayed, so we
+ * have some callbacks to set them appropriately.
+ */
 struct tabtype {
   int (*properties_sensitive)(GtkWidget *tab);
   int (*selectall_sensitive)(GtkWidget *tab);
index 3347a51..ad79a92 100644 (file)
@@ -17,6 +17,9 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  * USA
  */
+/** @file disobedience/menu.c
+ * @brief Main menu
+ */
 
 #include "disobedience.h"
 
@@ -25,6 +28,10 @@ static GtkWidget *properties_widget;
 
 static void about_popup_got_version(void *v, const char *value);
 
+/** @brief Called when the quit option is activated
+ *
+ * Just exits.
+ */
 static void quit_program(gpointer attribute((unused)) callback_data,
                          guint attribute((unused)) callback_action,
                          GtkWidget attribute((unused)) *menu_item) {
@@ -33,6 +40,11 @@ static void quit_program(gpointer attribute((unused)) callback_data,
 }
 
 /* TODO can we have a single parameterized callback for all these */
+
+/** @brief Called when the select all option is activated
+ *
+ * Calls the per-tab select all function.
+ */
 static void select_all(gpointer attribute((unused)) callback_data,
                        guint attribute((unused)) callback_action,
                        GtkWidget attribute((unused)) *menu_item) {
@@ -43,6 +55,10 @@ static void select_all(gpointer attribute((unused)) callback_data,
   t->selectall_activate(tab);
 }
 
+/** @brief Called when the track properties option is activated
+ *
+ * Calls the per-tab properties function.
+ */
 static void properties_item(gpointer attribute((unused)) callback_data,
                             guint attribute((unused)) callback_action,
                             GtkWidget attribute((unused)) *menu_item) {
@@ -53,6 +69,12 @@ static void properties_item(gpointer attribute((unused)) callback_data,
   t->properties_activate(tab);
 }
 
+/** @brief Update menu state
+ *
+ * Determines option sensitivity according to the current tab and adjusts the
+ * widgets accordingly.  Knows about @ref DISORDER_CONNECTED so the callbacks
+ * need not.
+ */
 void menu_update(int page) {
   GtkWidget *tab = gtk_notebook_get_nth_page
     (GTK_NOTEBOOK(tabs),
@@ -66,7 +88,8 @@ void menu_update(int page) {
   gtk_widget_set_sensitive(selectall_widget,
                            t->selectall_sensitive(tab));
 }
-     
+   
+/** @brief Fetch version in order to display the about... popup */
 static void about_popup(gpointer attribute((unused)) callback_data,
                         guint attribute((unused)) callback_action,
                         GtkWidget attribute((unused)) *menu_item) {
@@ -78,6 +101,7 @@ static void about_popup(gpointer attribute((unused)) callback_data,
                            0);
 }
 
+/** @brief Callde when version arrives, displays about... popup */
 static void about_popup_got_version(void attribute((unused)) *v,
                                     const char *value) {
   GtkWidget *w;
@@ -102,6 +126,7 @@ static void about_popup_got_version(void attribute((unused)) *v,
   gtk_widget_destroy(w);
 }
 
+/** @brief Create the menu bar widget */
 GtkWidget *menubar(GtkWidget *w) {
   static const GtkItemFactoryEntry entries[] = {
     { (char *)"/File", 0,  0, 0, (char *)"<Branch>", 0 },
index d0caf3b..f87f4a0 100644 (file)
@@ -17,6 +17,9 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  * USA
  */
+/** @file disobedience/misc.c
+ * @brief Miscellaneous GTK+ interfacing stuff
+ */
 
 #include "disobedience.h"
 
@@ -26,6 +29,11 @@ WT(cached_image);
 
 /* Functions */
 
+/** @brief Put scrollbars around a widget
+ * @param child Widget to surround
+ * @param widgetname Name for (both) widgets
+ * @return Scroll widget
+ */
 GtkWidget *scroll_widget(GtkWidget *child,
                          const char *widgetname) {
   GtkWidget *scroller = gtk_scrolled_window_new(0, 0);
@@ -57,6 +65,15 @@ GtkWidget *scroll_widget(GtkWidget *child,
   return scroller;
 }
 
+/** @brief Find an image
+ * @param name Relative path to image
+ * @return pixbuf containing image
+ *
+ * Images are cached so it's perfectly sensible to call this lots of times even
+ * for the same image.
+ *
+ * Images are searched for in @c pkgdatadir/static.
+ */
 GdkPixbuf *find_image(const char *name) {
   static const struct cache_type image_cache_type = { INT_MAX };
 
@@ -76,6 +93,7 @@ GdkPixbuf *find_image(const char *name) {
   return pb;
 }
 
+/** @brief Pop up an error message */
 void popup_error(const char *msg) {
   GtkWidget *w;