-documenting main_window_file_download.c code

2 files changed, 75 insertions, 44 deletions

diff --git a/src/fs/gnunet-fs-gtk-download.c b/src/fs/gnunet-fs-gtk-download.c
index 8c4f8ee6..233f3fcc 100644
--- a/src/fs/gnunet-fs-gtk-download.c
+++ b/src/fs/gnunet-fs-gtk-download.c
@@ -49,6 +49,7 @@ GNUNET_GTK_save_as_dialog_free_download_context (struct DownloadContext *dc)
   GNUNET_free (dc);  
 }
 
+
 gboolean
 GNUNET_GTK_save_as_dialog_delete_event_cb (GtkWidget * widget, GdkEvent * event,
                                            gpointer user_data)
@@ -158,6 +159,7 @@ GNUNET_FS_GTK_open_download_as_dialog (struct DownloadContext *dc)
   gtk_window_present (GTK_WINDOW (ad));
 }
 
+
 void
 GNUNET_FS_GTK_default_open_download_as_callback (struct DownloadContext *dc)
 {
diff --git a/src/fs/gnunet-fs-gtk-main_window_file_download.c b/src/fs/gnunet-fs-gtk-main_window_file_download.c
index ec0191b4..9fce0c65 100644
--- a/src/fs/gnunet-fs-gtk-main_window_file_download.c
+++ b/src/fs/gnunet-fs-gtk-main_window_file_download.c
@@ -1,6 +1,6 @@
 /*
      This file is part of GNUnet
-     (C) 2005, 2006, 2010 Christian Grothoff (and other contributing authors)
+     (C) 2005, 2006, 2010, 2012 Christian Grothoff (and other contributing authors)
 
      GNUnet is free software; you can redistribute it and/or modify
      it under the terms of the GNU General Public License as published
@@ -21,6 +21,11 @@
 /**
  * @file src/fs/gnunet-fs-gtk-main_window_file_download.c
  * @author Christian Grothoff
+ * @brief code for the 'Open URI' dialog.
+ *
+ * TODO:
+ * - automatically populate dialog from clipboard?
+ * - use our own builder instead of the main builder?
  */
 #include "gnunet-fs-gtk-common.h"
 #include "gnunet-fs-gtk-download.h"
@@ -29,22 +34,23 @@
 
 /**
  * User selected "Open URI" in main window.
+ *
+ * @param dummy some widget
+ * @param user_data unused
  */
 void
 GNUNET_GTK_main_menu_file_download_uri_activate_cb (GtkWidget * dummy,
                                                     gpointer user_data)
 {
-  GtkBuilder *builder;
+  GtkBuilder *builder = GTK_BUILDER (user_data);
   GtkWidget *dialog;
   GtkTextBuffer *tb;
-  GtkTextIter ti_start, ti_end;
-
-  builder = GTK_BUILDER (user_data);
-
-  dialog =
-      GTK_WIDGET (gtk_builder_get_object
-                  (builder, "GNUNET_GTK_open_url_window"));
+  GtkTextIter ti_start;
+  GtkTextIter ti_end;
 
+  dialog = GTK_WIDGET (gtk_builder_get_object
+                       (builder, 
+                        "GNUNET_GTK_open_url_window"));
   tb = GTK_TEXT_BUFFER (gtk_builder_get_object
                         (builder,
                          "GNUNET_GTK_open_url_dialog_url_textview_buffer"));
@@ -52,12 +58,18 @@ GNUNET_GTK_main_menu_file_download_uri_activate_cb (GtkWidget * dummy,
   gtk_text_buffer_get_iter_at_offset (tb, &ti_end, -1);
   gtk_text_buffer_delete (tb, &ti_start, &ti_end);
 
-  /* TODO: queue the clipboard, maybe there's valid URI in there?
+  /* TODO: query the clipboard, maybe there's valid URI in there?
    * If so, get it. */
-
   gtk_widget_show (dialog);
 }
 
+
+/**
+ * User selected "execute" in the open-URI dialog.
+ * 
+ * @param button the execute button
+ * @param user_data the 'GtkBuilder' of the URI dialog
+ */
 void
 GNUNET_GTK_open_url_dialog_execute_button_clicked_cb (GtkButton * button,
                                                       gpointer user_data)
@@ -125,28 +137,38 @@ GNUNET_GTK_open_url_dialog_execute_button_clicked_cb (GtkButton * button,
   GNUNET_FS_uri_destroy (uri);
 }
 
+
+/**
+ * User selected "cancel" in the open-URI dialog.
+ * 
+ * @param button the cancel button
+ * @param user_data the 'GtkBuilder' of the URI dialog
+ */
 void
 GNUNET_GTK_open_url_dialog_cancel_button_clicked_cb (GtkButton * button,
                                                      gpointer user_data)
 {
-  GtkBuilder *builder;
-
-  builder = GTK_BUILDER (user_data);
+  GtkBuilder *builder = GTK_BUILDER (user_data);
 
   gtk_widget_hide (GTK_WIDGET
                    (gtk_builder_get_object
                     (builder, "GNUNET_GTK_open_url_window")));
-  return;
 }
 
+
+/**
+ * User closed the window of the open-URI dialog.
+ * 
+ * @param widget the window
+ * @param event the deletion event
+ * @param user_data the 'GtkBuilder' of the URI dialog
+ */
 gboolean
 GNUNET_GTK_open_url_window_delete_event_cb (GtkWidget * widget,
                                             GdkEvent * event,
                                             gpointer user_data)
 {
-  GtkBuilder *builder;
-
-  builder = GTK_BUILDER (user_data);
+  GtkBuilder *builder = GTK_BUILDER (user_data);
 
   gtk_widget_hide (GTK_WIDGET
                    (gtk_builder_get_object
@@ -154,54 +176,61 @@ GNUNET_GTK_open_url_window_delete_event_cb (GtkWidget * widget,
   return TRUE;
 }
 
-#ifndef GDK_KEY_Return
-#define GDK_KEY_Return GDK_Return
-#endif
 
+
+/**
+ * User pushed a key in the open-URI dialog, check if we currently
+ * have valid URI and if the key was 'RETURN', run the action.
+ * 
+ * @param widget the window
+ * @param event the deletion event
+ * @param user_data the 'GtkBuilder' of the URI dialog
+ */
 gboolean
 GNUNET_GTK_open_url_dialog_url_textview_key_press_event_cb (GtkWidget * widget,
                                                             GdkEventKey * event,
                                                             gpointer user_data)
 {
-  GtkBuilder *builder;
-
-  builder = GTK_BUILDER (user_data);
-
-  if (event->keyval == GDK_KEY_Return)
-  {
-    GtkWidget *execute = GTK_WIDGET (gtk_builder_get_object (builder,
-                                                             "GNUNET_GTK_open_url_dialog_execute_button"));
-
-    if (gtk_widget_get_sensitive (execute))
-      GNUNET_GTK_open_url_dialog_execute_button_clicked_cb (GTK_BUTTON
-                                                            (execute),
-                                                            user_data);
-    return TRUE;
-  }
-  return FALSE;
+  GtkBuilder *builder = GTK_BUILDER (user_data);
+  GtkWidget *execute;
+
+  if (event->keyval != GDK_KEY_Return)
+    return FALSE;
+  execute = GTK_WIDGET (gtk_builder_get_object (builder,
+                                                "GNUNET_GTK_open_url_dialog_execute_button"));  
+  if (gtk_widget_get_sensitive (execute))
+    GNUNET_GTK_open_url_dialog_execute_button_clicked_cb (GTK_BUTTON (execute),
+                                                          user_data);
+  return TRUE;
 }
 
+
+/**
+ * User edited the URI of the open-URI dialog, check if it is currently
+ * a valid URI and update the sensitivity of the 'execute' button accordingly.
+ * 
+ * @param textbuffer the updated buffer
+ * @param user_data the 'GtkBuilder' of the URI dialog
+ */
 void
 GNUNET_GTK_open_url_dialog_url_textview_buffer_changed_cb (GtkTextBuffer *
                                                            textbuffer,
                                                            gpointer user_data)
 {
+  GtkBuilder *builder = GTK_BUILDER (user_data);
   struct GNUNET_FS_Uri *uri;
   GtkTextBuffer *tb;
-  GtkTextIter ti_start, ti_end;
-  GtkBuilder *builder;
+  GtkTextIter ti_start;
+  GtkTextIter ti_end;
   char *perr;
   char *uris;
 
-  builder = GTK_BUILDER (user_data);
-
   perr = NULL;
   tb = GTK_TEXT_BUFFER (gtk_builder_get_object
                         (builder,
                          "GNUNET_GTK_open_url_dialog_url_textview_buffer"));
   gtk_text_buffer_get_iter_at_offset (tb, &ti_start, 0);
   gtk_text_buffer_get_iter_at_offset (tb, &ti_end, -1);
-
   uris = gtk_text_buffer_get_text (tb, &ti_start, &ti_end, FALSE);
   if (uris != NULL)
     uri = GNUNET_FS_uri_parse (uris, &perr);
@@ -215,8 +244,8 @@ GNUNET_GTK_open_url_dialog_url_textview_buffer_changed_cb (GtkTextBuffer *
                             (uri == NULL) ? FALSE : TRUE);
   if (uri != NULL)
     GNUNET_FS_uri_destroy (uri);
-  else
-    GNUNET_free_non_null (perr);
+  GNUNET_free_non_null (perr);
 }
 
+
 /* end of gnunet-fs-gtk-main_window_file_download.c */