X-Git-Url: http://pileus.org/git/?a=blobdiff_plain;f=gtk%2Fgtkprintsettings.c;h=b1e8476f03ee9be4da34ffa7d1235a070206dff8;hb=aa08f4d8f5ed60e3fe9e4bd970493582411c25c4;hp=5cbcab2da71f0214cf59c8aea5962920904da78d;hpb=5f1b5d24067468fc86b28dccc504c71abdaf68b8;p=~andy%2Fgtk

diff --git a/gtk/gtkprintsettings.c b/gtk/gtkprintsettings.c
index 5cbcab2da..b1e8476f0 100644
--- a/gtk/gtkprintsettings.c
+++ b/gtk/gtkprintsettings.c
@@ -13,18 +13,42 @@
  * Lesser General Public License for more details.
  *
  * You should have received a copy of the GNU Lesser General Public
- * License along with this library; if not, write to the
- * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
- * Boston, MA 02111-1307, USA.
+ * License along with this library. If not, see <http://www.gnu.org/licenses/>.
  */
 
 #include "config.h"
+
 #include <string.h>
 #include <stdlib.h>
+
 #include <glib/gprintf.h>
-#include <gtk/gtk.h>
+
 #include "gtkprintsettings.h"
 #include "gtkprintutils.h"
+#include "gtktypebuiltins.h"
+#include "gtkwidget.h"
+
+
+/**
+ * SECTION:gtkprintsettings
+ * @Short_description: Stores print settings
+ * @Title: GtkPrintSettings
+ *
+ * A GtkPrintSettings object represents the settings of a print dialog in
+ * a system-independent way. The main use for this object is that once
+ * you've printed you can get a settings object that represents the settings
+ * the user chose, and the next time you print you can pass that object in so
+ * that the user doesn't have to re-set all his settings.
+ *
+ * Its also possible to enumerate the settings so that you can easily save
+ * the settings for the next time your app runs, or even store them in a
+ * document. The predefined keys try to use shared values as much as possible
+ * so that moving such a document between systems still works.
+ *
+ * <!-- TODO example of getting, storing and setting settings -->
+ *
+ * Printing support was added in GTK+ 2.10.
+ */
 
 
 typedef struct _GtkPrintSettingsClass GtkPrintSettingsClass;
@@ -36,7 +60,7 @@ typedef struct _GtkPrintSettingsClass GtkPrintSettingsClass;
 struct _GtkPrintSettings
 {
   GObject parent_instance;
-  
+
   GHashTable *hash;
 };
 
@@ -106,10 +130,10 @@ copy_hash_entry  (gpointer  key,
 /**
  * gtk_print_settings_copy:
  * @other: a #GtkPrintSettings
- * 
+ *
  * Copies a #GtkPrintSettings object.
- * 
- * Return value: a newly allocated copy of @other
+ *
+ * Return value: (transfer full): a newly allocated copy of @other
  *
  * Since: 2.10
  */
@@ -143,7 +167,7 @@ gtk_print_settings_copy (GtkPrintSettings *other)
  * 
  * Since: 2.10
  */
-G_CONST_RETURN gchar *        
+const gchar *
 gtk_print_settings_get (GtkPrintSettings *settings,
 			const gchar      *key)
 {
@@ -472,7 +496,7 @@ gtk_print_settings_set_int (GtkPrintSettings *settings,
 /**
  * gtk_print_settings_foreach:
  * @settings: a #GtkPrintSettings
- * @func: (scope call) the function to call
+ * @func: (scope call): the function to call
  * @user_data: user data for @func
  *
  * Calls @func for each key-value pair of @settings.
@@ -498,7 +522,7 @@ gtk_print_settings_foreach (GtkPrintSettings    *settings,
  *
  * Since: 2.10
  */
-G_CONST_RETURN gchar *       
+const gchar *
 gtk_print_settings_get_printer (GtkPrintSettings *settings)
 {
   return gtk_print_settings_get (settings, GTK_PRINT_SETTINGS_PRINTER);
@@ -792,8 +816,9 @@ gtk_print_settings_set_use_color (GtkPrintSettings *settings,
 gboolean
 gtk_print_settings_get_collate (GtkPrintSettings *settings)
 {
-  return gtk_print_settings_get_bool (settings, 
-				      GTK_PRINT_SETTINGS_COLLATE);
+  return gtk_print_settings_get_bool_with_default (settings,
+                                                   GTK_PRINT_SETTINGS_COLLATE,
+                                                   TRUE);
 }
 
 /**
@@ -1401,16 +1426,17 @@ gtk_print_settings_set_print_pages (GtkPrintSettings *settings,
   
   gtk_print_settings_set (settings, GTK_PRINT_SETTINGS_PRINT_PAGES, str);
 }
-     
+
 /**
  * gtk_print_settings_get_page_ranges:
  * @settings: a #GtkPrintSettings
- * @num_ranges: return location for the length of the returned array
- * 
+ * @num_ranges: (out): return location for the length of the returned array
+ *
  * Gets the value of %GTK_PRINT_SETTINGS_PAGE_RANGES.
- * 
- * Return value: an array of #GtkPageRange<!-- -->s. Use g_free()
- *   to free the array when it is no longer needed. 
+ *
+ * Return value: (array length=num_ranges) (transfer full): an array
+ *     of #GtkPageRange<!-- -->s.  Use g_free() to free the array when
+ *     it is no longer needed.
  *
  * Since: 2.10
  */
@@ -1467,7 +1493,7 @@ gtk_print_settings_get_page_ranges (GtkPrintSettings *settings,
 /**
  * gtk_print_settings_set_page_ranges:
  * @settings: a #GtkPrintSettings
- * @page_ranges: an array of #GtkPageRange<!-- -->s
+ * @page_ranges: (array length=num_ranges): an array of #GtkPageRange<!-- -->s
  * @num_ranges: the length of @page_ranges
  * 
  * Sets the value of %GTK_PRINT_SETTINGS_PAGE_RANGES.
@@ -1513,7 +1539,7 @@ gtk_print_settings_set_page_ranges  (GtkPrintSettings *settings,
  *
  * Since: 2.10
  */
-G_CONST_RETURN gchar *
+const gchar *
 gtk_print_settings_get_default_source (GtkPrintSettings *settings)
 {
   return gtk_print_settings_get (settings, GTK_PRINT_SETTINGS_DEFAULT_SOURCE);
@@ -1548,7 +1574,7 @@ gtk_print_settings_set_default_source (GtkPrintSettings *settings,
  *
  * Since: 2.10
  */
-G_CONST_RETURN gchar *
+const gchar *
 gtk_print_settings_get_media_type (GtkPrintSettings *settings)
 {
   return gtk_print_settings_get (settings, GTK_PRINT_SETTINGS_MEDIA_TYPE);
@@ -1583,7 +1609,7 @@ gtk_print_settings_set_media_type (GtkPrintSettings *settings,
  *
  * Since: 2.10
  */
-G_CONST_RETURN gchar *
+const gchar *
 gtk_print_settings_get_dither (GtkPrintSettings *settings)
 {
   return gtk_print_settings_get (settings, GTK_PRINT_SETTINGS_DITHER);
@@ -1647,7 +1673,7 @@ gtk_print_settings_set_finishings (GtkPrintSettings *settings,
  *
  * Since: 2.10
  */
-G_CONST_RETURN gchar *
+const gchar *
 gtk_print_settings_get_output_bin (GtkPrintSettings *settings)
 {
   return gtk_print_settings_get (settings, GTK_PRINT_SETTINGS_OUTPUT_BIN);
@@ -1672,7 +1698,7 @@ gtk_print_settings_set_output_bin (GtkPrintSettings *settings,
 /**
  * gtk_print_settings_load_file:
  * @settings: a #GtkPrintSettings
- * @file_name: the filename to read the settings from
+ * @file_name: (type filename): the filename to read the settings from
  * @error: (allow-none): return location for errors, or %NULL
  *
  * Reads the print settings from @file_name. If the file could not be loaded
@@ -1707,7 +1733,7 @@ gtk_print_settings_load_file (GtkPrintSettings *settings,
 
 /**
  * gtk_print_settings_new_from_file:
- * @file_name: the filename to read the settings from
+ * @file_name: (type filename): the filename to read the settings from
  * @error: (allow-none): return location for errors, or %NULL
  * 
  * Reads the print settings from @file_name. Returns a new #GtkPrintSettings
@@ -1781,7 +1807,7 @@ gtk_print_settings_load_key_file (GtkPrintSettings *settings,
       gchar *value;
 
       value = g_key_file_get_string (key_file,
-				     KEYFILE_GROUP_NAME,
+				     group_name,
 				     keys[i],
 				     NULL);
       if (!value)
@@ -1832,7 +1858,7 @@ gtk_print_settings_new_from_key_file (GKeyFile     *key_file,
 /**
  * gtk_print_settings_to_file:
  * @settings: a #GtkPrintSettings
- * @file_name: the file to save to
+ * @file_name: (type filename): the file to save to
  * @error: (allow-none): return location for errors, or %NULL
  * 
  * This function saves the print settings from @settings to @file_name. If the