GNOME.org
 

eog r4574 - in trunk: . src

Author: csaavedra
Date: Mon May 19 05:21:23 2008
New Revision: 4574
URL: http://svn.gnome.org/viewvc/eog?rev=4574&view=rev

Log:
2008-05-19  Claudio Saavedra  <csaavedra gnome org>

	* src/eog-list-store.c:
	* src/eog-thumb-view.c:

	Add documentation for EogListStore and EogThumbView.



Modified:
   trunk/ChangeLog
   trunk/src/eog-list-store.c
   trunk/src/eog-thumb-view.c

Modified: trunk/src/eog-list-store.c
==============================================================================
--- trunk/src/eog-list-store.c	(original)
+++ trunk/src/eog-list-store.c	Mon May 19 05:21:23 2008
@@ -1,8 +1,8 @@
 /* Eye Of Gnome - Image Store
  *
- * Copyright (C) 2006-2007 The Free Software Foundation
+ * Copyright (C) 2006-2008 The Free Software Foundation
  *
- * Author: Claudio Saavedra <csaavedra alumnos utalca cl>
+ * Author: Claudio Saavedra <csaavedra gnome org>
  *
  * Based on code by: Jens Finke <jens triq net>
  *
@@ -185,6 +185,13 @@
 					      GTK_SORT_ASCENDING);
 }
 
+/**
+ * eog_list_store_new:
+ *
+ * Creates a new and empty #EogListStore.
+ *
+ * Returns: a newly created #EogListStore.
+ **/
 GtkListStore*
 eog_list_store_new (void)
 {
@@ -310,6 +317,13 @@
 	gtk_tree_path_free (path);
 }
 
+/**
+ * eog_list_store_remove:
+ * @store: An #EogListStore.
+ * @iter: A #GtkTreeIter.
+ *
+ * Removes the image pointed by @iter from @store.
+ **/
 static void
 eog_list_store_remove (EogListStore *store, GtkTreeIter *iter)
 {
@@ -325,6 +339,16 @@
 	gtk_list_store_remove (GTK_LIST_STORE (store), iter);
 }
 
+/**
+ * eog_list_store_append_image:
+ * @store: An #EogListStore.
+ * @image: An #EogImage.
+ *
+ * Adds an #EogImage to @store. The thumbnail of the image is not
+ * loaded and will only be loaded if the thumbnail is made visible
+ * or eog_list_store_set_thumbnail() is called.
+ *
+ **/
 void
 eog_list_store_append_image (EogListStore *store, EogImage *image)
 {
@@ -501,6 +525,20 @@
 	g_object_unref (file_enumerator);
 }
 
+/**
+ * eog_list_store_add_files:
+ * @store: An #EogListStore.
+ * @file_list: A %NULL-terminated list of #GFile's.
+ *
+ * Adds a list of #GFile's to @store. The given list
+ * must be %NULL-terminated.
+ *
+ * If any of the #GFile's in @file_list is a directory, all the images
+ * in that directory will be added to @store. If the list of files contains
+ * only one file and this is a regular file, then all the images in the same
+ * directory will be added as well to @store.
+ *
+ **/
 void
 eog_list_store_add_files (EogListStore *store, GList *file_list) 
 {
@@ -575,6 +613,13 @@
 	} 
 }
 
+/**
+ * eog_list_store_remove_image:
+ * @store: An #EogListStore.
+ * @image: An #EogImage.
+ *
+ * Removes @image from @store.
+ **/
 void
 eog_list_store_remove_image (EogListStore *store, EogImage *image)
 {
@@ -592,6 +637,15 @@
 	g_object_unref (file);
 }
 
+/**
+ * eog_list_store_new_from_glist:
+ * @list: a %NULL-terminated list of #EogImage's.
+ *
+ * Creates a new #EogListStore from a list of #EogImage's.
+ * The given list must be %NULL-terminated.
+ *
+ * Returns: a new #EogListStore.
+ **/
 GtkListStore *
 eog_list_store_new_from_glist (GList *list)
 {
@@ -607,6 +661,16 @@
 	return store;
 }
 
+/**
+ * eog_list_store_get_pos_by_image:
+ * @store: An #EogListStore.
+ * @image: An #EogImage.
+ *
+ * Gets the position where @image is stored in @store. If @image
+ * is not stored in @store, -1 is returned.
+ *
+ * Returns: the position of @image in @store or -1 if not found.
+ **/
 gint
 eog_list_store_get_pos_by_image (EogListStore *store, EogImage *image)
 {
@@ -627,6 +691,17 @@
 	return pos;
 }
 
+/**
+ * eog_list_store_get_image_by_pos:
+ * @store: An #EogListStore.
+ * @pos: the position of the required #EogImage.
+ *
+ * Gets the #EogImage in the position @pos of @store. If there is
+ * no image at position @pos, %NULL is returned.
+ *
+ * Returns: the #EogImage in position @pos or %NULL.
+ *
+ **/
 EogImage *
 eog_list_store_get_image_by_pos (EogListStore *store, const gint pos)
 {
@@ -644,6 +719,15 @@
 	return image;
 }
 
+/**
+ * eog_list_store_get_pos_by_iter:
+ * @store: An #EogListStore.
+ * @iter: A #GtkTreeIter pointing to an image in @store.
+ *
+ * Gets the position of the image pointed by @iter.
+ *
+ * Returns: The position of the image pointed by @iter.
+ **/
 gint
 eog_list_store_get_pos_by_iter (EogListStore *store, 
 				GtkTreeIter *iter)
@@ -660,6 +744,14 @@
 	return pos;
 }
 
+/**
+ * eog_list_store_length:
+ * @store: An #EogListStore.
+ *
+ * Returns the number of images in the store.
+ *
+ * Returns: The number of images in @store.
+ **/
 gint
 eog_list_store_length (EogListStore *store)
 {
@@ -668,6 +760,16 @@
 	return gtk_tree_model_iter_n_children (GTK_TREE_MODEL (store), NULL);
 }
 
+/**
+ * eog_list_store_get_initial_pos:
+ * @store: An #EogListStore.
+ *
+ * Gets the position of the #EogImage that should be loaded first.
+ * If not set, it returns -1.
+ *
+ * Returns: the position of the image to be loaded first or -1.
+ *
+ **/
 gint
 eog_list_store_get_initial_pos (EogListStore *store)
 {
@@ -731,6 +833,14 @@
 	g_object_unref (image);
 }
 
+/**
+ * eog_list_store_thumbnail_set:
+ * @store: An #EogListStore.
+ * @iter: A #GtkTreeIter pointing to an image in @store.
+ *
+ * Sets the thumbnail for the image pointed by @iter.
+ *
+ **/
 void
 eog_list_store_thumbnail_set (EogListStore *store, 
 			      GtkTreeIter *iter)
@@ -748,6 +858,15 @@
 	eog_list_store_add_thumbnail_job (store, iter);
 }
 
+/**
+ * eog_list_store_thumbnail_unset:
+ * @store: An #EogListStore.
+ * @iter: A #GtkTreeIter pointing to an image in @store.
+ *
+ * Unsets the thumbnail for the image pointed by @iter, changing
+ * it to a "busy" icon.
+ *
+ **/
 void
 eog_list_store_thumbnail_unset (EogListStore *store, 
 				GtkTreeIter *iter)
@@ -768,6 +887,14 @@
 			    -1);
 }
 
+/**
+ * eog_list_store_thumbnail_refresh:
+ * @store: An #EogListStore.
+ * @iter: A #GtkTreeIter pointing to an image in @store.
+ *
+ * Refreshes the thumbnail for the image pointed by @iter.
+ *
+ **/
 void
 eog_list_store_thumbnail_refresh (EogListStore *store,
 				  GtkTreeIter *iter)

Modified: trunk/src/eog-thumb-view.c
==============================================================================
--- trunk/src/eog-thumb-view.c	(original)
+++ trunk/src/eog-thumb-view.c	Mon May 19 05:21:23 2008
@@ -1,8 +1,8 @@
 /* Eye Of Gnome - Thumbnail View
  *
- * Copyright (C) 2006 The Free Software Foundation
+ * Copyright (C) 2006-2008 The Free Software Foundation
  *
- * Author: Claudio Saavedra <csaavedra alumnos utalca cl>
+ * Author: Claudio Saavedra <csaavedra gnome org>
  *
  * 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
@@ -545,6 +545,13 @@
 			  G_CALLBACK (thumbview_on_drag_data_get_cb), NULL);
 }
 
+/**
+ * eog_thumb_view_new:
+ *
+ * Creates a new #EogThumbView object.
+ *
+ * Returns: a newly created #EogThumbView.
+ **/
 GtkWidget *
 eog_thumb_view_new (void)
 {
@@ -555,6 +562,15 @@
 	return GTK_WIDGET (thumbview);
 }
 
+/**
+ * eog_thumb_view_set_model:
+ * @thumbview: A #EogThumbView.
+ * @store: A #EogListStore.
+ *
+ * Sets the #EogListStore to be used with @thumbview. If an initial image
+ * was set during @store creation, its thumbnail will be selected and visible.
+ *
+ **/
 void
 eog_thumb_view_set_model (EogThumbView *thumbview, EogListStore *store)
 {
@@ -576,6 +592,14 @@
 	}
 }
 
+/**
+ * eog_thumb_view_set_item_height:
+ * @thumbview: A #EogThumbView.
+ * @height: The desired height.
+ *
+ * Sets the height of each thumbnail in @thumbview.
+ *
+ **/
 void
 eog_thumb_view_set_item_height (EogThumbView *thumbview, gint height)
 {
@@ -595,6 +619,14 @@
 	(*(guint *) data) ++;
 }
 
+/**
+ * eog_thumb_view_get_n_selected:
+ * @thumbview: An #EogThumbView.
+ *
+ * Gets the number of images that are currently selected in @thumbview.
+ *
+ * Returns: the number of selected images in @thumbview.
+ **/
 guint
 eog_thumb_view_get_n_selected (EogThumbView *thumbview)
 {
@@ -605,6 +637,16 @@
 	return count;
 }
 
+/**
+ * eog_thumb_view_get_image_from_path:
+ * @thumbview: A #EogThumbView.
+ * @path: A #GtkTreePath pointing to a #EogImage in the model for @thumbview.
+ *
+ * Gets the #EogImage stored in @thumbview's #EogListStore at the position indicated
+ * by @path.
+ *
+ * Returns: A #EogImage.
+ **/
 static EogImage *
 eog_thumb_view_get_image_from_path (EogThumbView *thumbview, GtkTreePath *path)
 {
@@ -622,6 +664,16 @@
 	return image;
 }
 
+/**
+ * eog_thumb_view_get_first_selected_image:
+ * @thumbview: A #EogThumbView.
+ *
+ * Returns the first selected image. Note that the returned #EogImage
+ * is not ensured to be really the first selected image in @thumbview, but
+ * generally, it will be.
+ *
+ * Returns: A #EogImage.
+ **/
 EogImage *
 eog_thumb_view_get_first_selected_image (EogThumbView *thumbview)
 {
@@ -646,6 +698,15 @@
 	return image;
 }
 
+/**
+ * eog_thumb_view_get_selected_images:
+ * @thumbview: A #EogThumbView.
+ *
+ * Gets a list with the currently selected images. Note that a new reference is
+ * hold for each image and the list must be freed with g_list_free().
+ *
+ * Returns: A newly allocated list of #EogImage's.
+ **/
 GList *
 eog_thumb_view_get_selected_images (EogThumbView *thumbview)
 {
@@ -668,6 +729,17 @@
 	return list;
 }
 
+/**
+ * eog_thumb_view_set_current_image:
+ * @thumbview: A #EogThumbView.
+ * @image: The image to be selected.
+ * @deselect_other: Whether to deselect currently selected images.
+ *
+ * Changes the status of a image, marking it as currently selected.
+ * If @deselect_other is %TRUE, all other selected images will be
+ * deselected.
+ *
+ **/
 void
 eog_thumb_view_set_current_image (EogThumbView *thumbview, EogImage *image,
 				  gboolean deselect_other)
@@ -695,6 +767,20 @@
 	gtk_tree_path_free (path);
 }
 
+/**
+ * eog_thumb_view_select_single:
+ * @thumbview: A #EogThumbView.
+ * @change: A #EogThumbViewSelectionChange, describing the
+ * desired selection change.
+ *
+ * Changes the current selection according to a single movement
+ * described by #EogThumbViewSelectionChange. If there are no
+ * thumbnails currently selected, one is selected according to the
+ * natural selection according to the #EogThumbViewSelectionChange
+ * used, p.g., when %EOG_THUMB_VIEW_SELECT_RIGHT is the selected change,
+ * the first thumbnail will be selected.
+ *
+ **/
 void
 eog_thumb_view_select_single (EogThumbView *thumbview, 
 			      EogThumbViewSelectionChange change)
@@ -768,6 +854,15 @@
 }
 
 
+/**
+ * eog_thumb_view_set_thumbnail_popup:
+ * @thumbview: A #GtkThumbView.
+ * @menu: A #GtkMenu.
+ *
+ * Set the contextual menu to be used with the thumbnails in the
+ * widget. This can be done only once.
+ *
+ **/
 void
 eog_thumb_view_set_thumbnail_popup (EogThumbView *thumbview,
 				    GtkMenu      *menu)
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]