libgimp/gimpfileselection.[ch] document the two widgets.

2000-02-08  Michael Natterer  <mitch@gimp.org>

	* libgimp/gimpfileselection.[ch]
	* libgimp/gimppatheditor.[ch]: document the two widgets.

ChangeLog

@@ -1,3 +1,8 @@
+2000-02-08  Michael Natterer  <mitch@gimp.org>
+
+	* libgimp/gimpfileselection.[ch]
+	* libgimp/gimppatheditor.[ch]: document the two widgets.
+
 Tue Feb  8 18:19:29 CET 2000  Sven Neumann <sven@gimp.org>
 
 	* app/gimpdnd.c: When dragging a layer, show it in its full size 

devel-docs/ChangeLog

@@ -1,3 +1,11 @@
+2000-02-08  Michael Natterer  <mitch@gimp.org>
+
+	* libgimp/libgimp-decl.txt
+	* libgimp/tmpl/gimpexport.sgml
+	* libgimp/tmpl/gimpfileselection.sgml
+	* libgimp/tmpl/gimppatheditor.sgml: updated from the libgimp
+	sources. Added some more documentation to the sgml templates.
+
 Tue Feb  8 00:51:54 CET 2000  Sven Neumann <sven@gimp.org>
 
 	* libgimp/gimpexport.sgml: documented the enums

devel-docs/libgimp/tmpl/gimpfileselection.sgml

@@ -2,11 +2,28 @@
 GimpFileSelection
 
 <!-- ##### SECTION Short_Description ##### -->
-
+Widget for entering a filename.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+This widget is used to enter filenames or directories.
+</para>
+<para>
+There is a #GtkEntry for entering the filename manually and a "..."
+button which will pop up a #GtkFileSelection dialog.
+</para>
+<para>
+You can restrict the #GimpFileSelection to directories. In this case
+the filename listbox of the #GtkFileSelection dialog will be hidden.
+</para>
+<para>
+If you specify @check_valid as #TRUE in gimp_file_selection_new()
+the entered filename will be checked for validity and a pixmap will be
+shown which indicates if the file exists or not.
+</para>
+<para>
+Whenever the user changes the filename, the "filename_changed" signal
+will be emitted.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -22,7 +39,8 @@ GimpFileSelection
 
 <!-- ##### MACRO GIMP_FILE_SELECTION ##### -->
 <para>
-
+Checks if the passed pointer is a pointer to a #GimpFileSelection and
+performes the cast if valid.
 </para>
 
 @obj: The pointer to cast.
@@ -60,7 +78,7 @@ GimpFileSelection
 
 <!-- ##### SIGNAL GimpFileSelection::filename-changed ##### -->
 <para>
-
+This signal is emitted whenever the user changes the filename.
 </para>
 
 @gimpfileselection: the object which received the signal.

devel-docs/libgimp/tmpl/gimppatheditor.sgml

@@ -2,17 +2,33 @@
 GimpPathEditor
 
 <!-- ##### SECTION Short_Description ##### -->
-
+Widget for editing a file search path.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+This widget is used to edit file search paths.
+</para>
+<para>
+It shows a list of all directories which are in the search path. You
+can click a directory to select it. The widget provides a
+#GimpFileSelection to change the currently selected directory.
+</para>
+<para>
+There are buttons to add or delete directories as well as "up" and "down"
+buttons to change the order in which the directories will be searched.
+</para>
+<para>
+Whenever the user adds, deletes, changes or reorders a directory of
+the search path, the "path_changed" signal will be emitted.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
 #GimpFileSelection
 </para>
+<para>
+#G_SEARCHPATH_SEPARATOR
+</para>
 
 <!-- ##### STRUCT GimpPathEditor ##### -->
 <para>
@@ -22,7 +38,8 @@ GimpPathEditor
 
 <!-- ##### MACRO GIMP_PATH_EDITOR ##### -->
 <para>
-
+Checks if the passed pointer is a pointer to a #GimpPathEditor and
+performes the cast if valid.
 </para>
 
 @obj: The pointer to cast.
@@ -49,7 +66,8 @@ GimpPathEditor
 
 <!-- ##### SIGNAL GimpPathEditor::path-changed ##### -->
 <para>
-
+This signal is emitted whenever the user adds, deletes, modifies or
+reorders an element of the search path.
 </para>
 
 @gimppatheditor: the object which received the signal.

libgimp/gimpfileselection.c

@@ -179,6 +179,19 @@ gimp_file_selection_get_type (void)
   return gfs_type;
 }
 
+/**
+ * gimp_file_selection_new:
+ * @title: The title of the #GtkFileSelection dialog.
+ * @filename: The initial filename.
+ * @dir_only: #TRUE if the file selection should accept directories only.
+ * @check_valid: #TRUE if the widget should check if the entered file
+ *               really exists.
+ *
+ * Creates a new #GimpFileSelection widget.
+ *
+ * Returns: A pointer to the new #GimpFileSelection widget.
+ *
+ */
 GtkWidget *
 gimp_file_selection_new (gchar    *title,
 			 gchar    *filename,
@@ -228,6 +241,15 @@ gimp_file_selection_realize (GtkWidget *widget)
   gtk_widget_show (gfs->file_exists);
 }
 
+/**
+ * gimp_file_selection_get_filename:
+ * @gfs: The file selection you want to know the filename from.
+ *
+ * Note that you have to g_free() the returned string.
+ *
+ * Returns: The file or directory the user has entered.
+ *
+ */
 gchar *
 gimp_file_selection_get_filename (GimpFileSelection *gfs)
 {
@@ -237,6 +259,16 @@ gimp_file_selection_get_filename (GimpFileSelection *gfs)
   return gtk_editable_get_chars (GTK_EDITABLE (gfs->entry), 0, -1);
 }
 
+/**
+ * gimp_file_selection_set_filename:
+ * @gfs: The file selection you want to set the filename for.
+ * @filename: The new filename.
+ *
+ * If you specified @check_valid as #TRUE in gimp_file_selection_new()
+ * the #GimpFileSelection will immediately check the validity of the file
+ * name.
+ *
+ */
 void
 gimp_file_selection_set_filename (GimpFileSelection *gfs,
 				  gchar             *filename)

libgimp/gimpfileselection.h

@@ -40,7 +40,7 @@ typedef struct _GimpFileSelectionClass  GimpFileSelectionClass;
 
 struct _GimpFileSelection
 {
-  GtkVBox    hbox;
+  GtkHBox    hbox;
 
   GtkWidget *file_exists;
   GtkWidget *entry;
@@ -65,21 +65,15 @@ struct _GimpFileSelectionClass
   void (* filename_changed) (GimpFileSelection *gfs);
 };
 
+/* For information look into the C source or the html documentation */
+
 GtkType     gimp_file_selection_get_type    (void);
 
-/*  creates a new GimpFileSelection widget
- *
- *  dir_only    == TRUE  will allow only directories
- *  check_valid == TRUE  will show a pixmap which indicates if
- *                       the filename is valid
- */
 GtkWidget*  gimp_file_selection_new         (gchar              *title,
 					     gchar              *filename,
 					     gboolean            dir_only,
 					     gboolean            check_valid);
 
-/*  it's up to the caller to g_free() the returned string
- */
 gchar*      gimp_file_selection_get_filename (GimpFileSelection *gfs);
 
 void        gimp_file_selection_set_filename (GimpFileSelection *gfs,

libgimp/gimppatheditor.c

@@ -162,7 +162,20 @@ gimp_path_editor_get_type (void)
   return gpe_type;
 }
 
-
+/**
+ * gimp_path_editor_new:
+ * @filesel_title: The title of the #GtkFileSelection dialog which can be
+ *                 popped up by the attached #GimpFileSelection.
+ * @path: The initial search path.
+ *
+ * Creates a new #GimpPathEditor widget.
+ *
+ * The elements of the initial search path must be separated with the
+ * #G_SEARCHPATH_SEPARATOR character.
+ *
+ * Returns: A pointer to the new #GimpPathEditor widget.
+ *
+ */
 GtkWidget *
 gimp_path_editor_new (gchar *filesel_title,
 		      gchar *path)
@@ -237,7 +250,6 @@ gimp_path_editor_realize (GtkWidget *widget)
   GdkPixmap      *pixmap;
   GdkBitmap      *mask;
   GtkWidget      *gtk_pixmap;
-  /* GList          *list = NULL; */
 
   gpe = GIMP_PATH_EDITOR (widget);
 
@@ -295,6 +307,18 @@ gimp_path_editor_realize (GtkWidget *widget)
   gdk_bitmap_unref (mask);
 }
 
+/**
+ * gimp_path_editor_get_path:
+ * @gpe: The path editor you want to get the search path from.
+ *
+ * The elements of the returned search path string are separated with the
+ * #G_SEARCHPATH_SEPARATOR character.
+ *
+ * Note that you have to g_free() the returned string.
+ *
+ * Returns: The search path the user has selected in the path editor.
+ *
+ */
 gchar *
 gimp_path_editor_get_path (GimpPathEditor *gpe)
 {
@@ -398,9 +422,10 @@ gimp_path_editor_new_callback (GtkWidget *widget,
   gtk_widget_set_sensitive (gpe->down_button, FALSE);
   gtk_widget_set_sensitive (gpe->file_selection, TRUE);
 
-  gtk_editable_set_position (GTK_EDITABLE (GIMP_FILE_SELECTION (gpe->file_selection)->entry), -1);
+  gtk_editable_set_position
-  /* gtk_editable_select_region (GTK_EDITABLE (gpe->entry), 0, -1); */
+    (GTK_EDITABLE (GIMP_FILE_SELECTION (gpe->file_selection)->entry), -1);
-  gtk_widget_grab_focus (GTK_WIDGET (GIMP_FILE_SELECTION (gpe->file_selection)->entry));
+  gtk_widget_grab_focus
+    (GTK_WIDGET (GIMP_FILE_SELECTION (gpe->file_selection)->entry));
 }
 
 static void

libgimp/gimppatheditor.h

@@ -63,15 +63,13 @@ struct _GimpPathEditorClass
   void (* path_changed) (GimpPathEditor *gpe);
 };
 
+/* For information look into the C source or the html documentation */
+
 GtkType     gimp_path_editor_get_type (void);
 
-/*  creates a new GimpPathEditor widget
- */
 GtkWidget * gimp_path_editor_new      (gchar          *filesel_title,
 				       gchar          *path);
 
-/*  it's up to the caller to g_free() the returned string
- */
 gchar     * gimp_path_editor_get_path (GimpPathEditor *gpe);
 
 #ifdef __cplusplus

libgimpwidgets/gimpfileentry.c

@@ -179,6 +179,19 @@ gimp_file_selection_get_type (void)
   return gfs_type;
 }
 
+/**
+ * gimp_file_selection_new:
+ * @title: The title of the #GtkFileSelection dialog.
+ * @filename: The initial filename.
+ * @dir_only: #TRUE if the file selection should accept directories only.
+ * @check_valid: #TRUE if the widget should check if the entered file
+ *               really exists.
+ *
+ * Creates a new #GimpFileSelection widget.
+ *
+ * Returns: A pointer to the new #GimpFileSelection widget.
+ *
+ */
 GtkWidget *
 gimp_file_selection_new (gchar    *title,
 			 gchar    *filename,
@@ -228,6 +241,15 @@ gimp_file_selection_realize (GtkWidget *widget)
   gtk_widget_show (gfs->file_exists);
 }
 
+/**
+ * gimp_file_selection_get_filename:
+ * @gfs: The file selection you want to know the filename from.
+ *
+ * Note that you have to g_free() the returned string.
+ *
+ * Returns: The file or directory the user has entered.
+ *
+ */
 gchar *
 gimp_file_selection_get_filename (GimpFileSelection *gfs)
 {
@@ -237,6 +259,16 @@ gimp_file_selection_get_filename (GimpFileSelection *gfs)
   return gtk_editable_get_chars (GTK_EDITABLE (gfs->entry), 0, -1);
 }
 
+/**
+ * gimp_file_selection_set_filename:
+ * @gfs: The file selection you want to set the filename for.
+ * @filename: The new filename.
+ *
+ * If you specified @check_valid as #TRUE in gimp_file_selection_new()
+ * the #GimpFileSelection will immediately check the validity of the file
+ * name.
+ *
+ */
 void
 gimp_file_selection_set_filename (GimpFileSelection *gfs,
 				  gchar             *filename)

libgimpwidgets/gimpfileentry.h

@@ -40,7 +40,7 @@ typedef struct _GimpFileSelectionClass  GimpFileSelectionClass;
 
 struct _GimpFileSelection
 {
-  GtkVBox    hbox;
+  GtkHBox    hbox;
 
   GtkWidget *file_exists;
   GtkWidget *entry;
@@ -65,21 +65,15 @@ struct _GimpFileSelectionClass
   void (* filename_changed) (GimpFileSelection *gfs);
 };
 
+/* For information look into the C source or the html documentation */
+
 GtkType     gimp_file_selection_get_type    (void);
 
-/*  creates a new GimpFileSelection widget
- *
- *  dir_only    == TRUE  will allow only directories
- *  check_valid == TRUE  will show a pixmap which indicates if
- *                       the filename is valid
- */
 GtkWidget*  gimp_file_selection_new         (gchar              *title,
 					     gchar              *filename,
 					     gboolean            dir_only,
 					     gboolean            check_valid);
 
-/*  it's up to the caller to g_free() the returned string
- */
 gchar*      gimp_file_selection_get_filename (GimpFileSelection *gfs);
 
 void        gimp_file_selection_set_filename (GimpFileSelection *gfs,

libgimpwidgets/gimpfileselection.c

@@ -179,6 +179,19 @@ gimp_file_selection_get_type (void)
   return gfs_type;
 }
 
+/**
+ * gimp_file_selection_new:
+ * @title: The title of the #GtkFileSelection dialog.
+ * @filename: The initial filename.
+ * @dir_only: #TRUE if the file selection should accept directories only.
+ * @check_valid: #TRUE if the widget should check if the entered file
+ *               really exists.
+ *
+ * Creates a new #GimpFileSelection widget.
+ *
+ * Returns: A pointer to the new #GimpFileSelection widget.
+ *
+ */
 GtkWidget *
 gimp_file_selection_new (gchar    *title,
 			 gchar    *filename,
@@ -228,6 +241,15 @@ gimp_file_selection_realize (GtkWidget *widget)
   gtk_widget_show (gfs->file_exists);
 }
 
+/**
+ * gimp_file_selection_get_filename:
+ * @gfs: The file selection you want to know the filename from.
+ *
+ * Note that you have to g_free() the returned string.
+ *
+ * Returns: The file or directory the user has entered.
+ *
+ */
 gchar *
 gimp_file_selection_get_filename (GimpFileSelection *gfs)
 {
@@ -237,6 +259,16 @@ gimp_file_selection_get_filename (GimpFileSelection *gfs)
   return gtk_editable_get_chars (GTK_EDITABLE (gfs->entry), 0, -1);
 }
 
+/**
+ * gimp_file_selection_set_filename:
+ * @gfs: The file selection you want to set the filename for.
+ * @filename: The new filename.
+ *
+ * If you specified @check_valid as #TRUE in gimp_file_selection_new()
+ * the #GimpFileSelection will immediately check the validity of the file
+ * name.
+ *
+ */
 void
 gimp_file_selection_set_filename (GimpFileSelection *gfs,
 				  gchar             *filename)

libgimpwidgets/gimpfileselection.h

@@ -40,7 +40,7 @@ typedef struct _GimpFileSelectionClass  GimpFileSelectionClass;
 
 struct _GimpFileSelection
 {
-  GtkVBox    hbox;
+  GtkHBox    hbox;
 
   GtkWidget *file_exists;
   GtkWidget *entry;
@@ -65,21 +65,15 @@ struct _GimpFileSelectionClass
   void (* filename_changed) (GimpFileSelection *gfs);
 };
 
+/* For information look into the C source or the html documentation */
+
 GtkType     gimp_file_selection_get_type    (void);
 
-/*  creates a new GimpFileSelection widget
- *
- *  dir_only    == TRUE  will allow only directories
- *  check_valid == TRUE  will show a pixmap which indicates if
- *                       the filename is valid
- */
 GtkWidget*  gimp_file_selection_new         (gchar              *title,
 					     gchar              *filename,
 					     gboolean            dir_only,
 					     gboolean            check_valid);
 
-/*  it's up to the caller to g_free() the returned string
- */
 gchar*      gimp_file_selection_get_filename (GimpFileSelection *gfs);
 
 void        gimp_file_selection_set_filename (GimpFileSelection *gfs,

libgimpwidgets/gimppatheditor.c

@@ -162,7 +162,20 @@ gimp_path_editor_get_type (void)
   return gpe_type;
 }
 
-
+/**
+ * gimp_path_editor_new:
+ * @filesel_title: The title of the #GtkFileSelection dialog which can be
+ *                 popped up by the attached #GimpFileSelection.
+ * @path: The initial search path.
+ *
+ * Creates a new #GimpPathEditor widget.
+ *
+ * The elements of the initial search path must be separated with the
+ * #G_SEARCHPATH_SEPARATOR character.
+ *
+ * Returns: A pointer to the new #GimpPathEditor widget.
+ *
+ */
 GtkWidget *
 gimp_path_editor_new (gchar *filesel_title,
 		      gchar *path)
@@ -237,7 +250,6 @@ gimp_path_editor_realize (GtkWidget *widget)
   GdkPixmap      *pixmap;
   GdkBitmap      *mask;
   GtkWidget      *gtk_pixmap;
-  /* GList          *list = NULL; */
 
   gpe = GIMP_PATH_EDITOR (widget);
 
@@ -295,6 +307,18 @@ gimp_path_editor_realize (GtkWidget *widget)
   gdk_bitmap_unref (mask);
 }
 
+/**
+ * gimp_path_editor_get_path:
+ * @gpe: The path editor you want to get the search path from.
+ *
+ * The elements of the returned search path string are separated with the
+ * #G_SEARCHPATH_SEPARATOR character.
+ *
+ * Note that you have to g_free() the returned string.
+ *
+ * Returns: The search path the user has selected in the path editor.
+ *
+ */
 gchar *
 gimp_path_editor_get_path (GimpPathEditor *gpe)
 {
@@ -398,9 +422,10 @@ gimp_path_editor_new_callback (GtkWidget *widget,
   gtk_widget_set_sensitive (gpe->down_button, FALSE);
   gtk_widget_set_sensitive (gpe->file_selection, TRUE);
 
-  gtk_editable_set_position (GTK_EDITABLE (GIMP_FILE_SELECTION (gpe->file_selection)->entry), -1);
+  gtk_editable_set_position
-  /* gtk_editable_select_region (GTK_EDITABLE (gpe->entry), 0, -1); */
+    (GTK_EDITABLE (GIMP_FILE_SELECTION (gpe->file_selection)->entry), -1);
-  gtk_widget_grab_focus (GTK_WIDGET (GIMP_FILE_SELECTION (gpe->file_selection)->entry));
+  gtk_widget_grab_focus
+    (GTK_WIDGET (GIMP_FILE_SELECTION (gpe->file_selection)->entry));
 }
 
 static void

libgimpwidgets/gimppatheditor.h

@@ -63,15 +63,13 @@ struct _GimpPathEditorClass
   void (* path_changed) (GimpPathEditor *gpe);
 };
 
+/* For information look into the C source or the html documentation */
+
 GtkType     gimp_path_editor_get_type (void);
 
-/*  creates a new GimpPathEditor widget
- */
 GtkWidget * gimp_path_editor_new      (gchar          *filesel_title,
 				       gchar          *path);
 
-/*  it's up to the caller to g_free() the returned string
- */
 gchar     * gimp_path_editor_get_path (GimpPathEditor *gpe);
 
 #ifdef __cplusplus