GNOME.org
 

gtkmm r1015 - in trunk: . gtk/src tools/m4

Author: murrayc
Date: Fri Jul 25 15:31:32 2008
New Revision: 1015
URL: http://svn.gnome.org/viewvc/gtkmm?rev=1015&view=rev

Log:
2008-07-25  Murray Cumming  <murrayc murrayc com>

* tools/m4/convert_gtk.m4:
* gtk/src/widget.hg: Wrapped the DragResult enum and 
added the drag_failed signal.

* gtk/src/clipboard.hg:
* gtk/src/handlebox.ccg:
* gtk/src/handlebox.hg:
* gtk/src/image.hg:
* gtk/src/pagesetup.hg:
* gtk/src/printsettings.hg:
* gtk/src/toolshell.hg: Added documentation for some hand-written 
methods.

Modified:
   trunk/ChangeLog
   trunk/gtk/src/clipboard.hg
   trunk/gtk/src/handlebox.ccg
   trunk/gtk/src/handlebox.hg
   trunk/gtk/src/image.hg
   trunk/gtk/src/pagesetup.hg
   trunk/gtk/src/printsettings.hg
   trunk/gtk/src/toolshell.hg
   trunk/gtk/src/widget.hg
   trunk/tools/m4/convert_gtk.m4

Modified: trunk/gtk/src/clipboard.hg
==============================================================================
--- trunk/gtk/src/clipboard.hg	(original)
+++ trunk/gtk/src/clipboard.hg	Fri Jul 25 15:31:32 2008
@@ -179,7 +179,18 @@
   /// For instance: void on_uris_received(const Glib::StringArrayHandle& uris);
   typedef sigc::slot<void, const Glib::StringArrayHandle&> SlotUrisReceived;
 
-  //TODO: Documentation:
+ /** Requests the contents of the clipboard as URIs. When the URIs are
+  * later received @a slot will be called.
+  *
+  * The uris parameter to @a slot will contain the resulting array of
+  * URIs if the request succeeded, or an empty list if it failed. This could happen
+  * for various reasons, in particular if the clipboard was empty or if the
+  * contents of the clipboard could not be converted into URI form.
+  *
+  * @param slot A slot to call when the URIs are received, or the retrieval fails. (It will always be called one way or the other.)
+  *
+  * @newin2p14
+  */
   void request_uris(const SlotUrisReceived& slot);
   _IGNORE(gtk_clipboard_request_uris)
   

Modified: trunk/gtk/src/handlebox.ccg
==============================================================================
--- trunk/gtk/src/handlebox.ccg	(original)
+++ trunk/gtk/src/handlebox.ccg	Fri Jul 25 15:31:32 2008
@@ -26,11 +26,6 @@
 namespace Gtk
 {
 
-bool HandleBox::is_child_detached() const
-{
-  return gtk_handle_box_get_child_detached(const_cast<GtkHandleBox*>(gobj()));
-}
-
 bool HandleBox::is_float_window_mapped() const
 {
   return gobj()->float_window_mapped;

Modified: trunk/gtk/src/handlebox.hg
==============================================================================
--- trunk/gtk/src/handlebox.hg	(original)
+++ trunk/gtk/src/handlebox.hg	Fri Jul 25 15:31:32 2008
@@ -59,9 +59,7 @@
   _MEMBER_GET_GOBJECT(bin_window, bin_window, Gdk::Window, GdkWindow*)
   _MEMBER_GET_GOBJECT(float_window, float_window, Gdk::Window, GdkWindow*)
 
-  //TODO: Documentation:
-  bool is_child_detached() const;
-  _IGNORE(gtk_handle_box_get_child_detached)
+  _WRAP_METHOD(bool is_child_detached() const, gtk_handle_box_get_child_detached)
 
   bool is_float_window_mapped() const;
   bool is_in_drag() const;

Modified: trunk/gtk/src/image.hg
==============================================================================
--- trunk/gtk/src/image.hg	(original)
+++ trunk/gtk/src/image.hg	Fri Jul 25 15:31:32 2008
@@ -138,9 +138,24 @@
   _WRAP_METHOD(Glib::RefPtr<Gdk::PixbufAnimation> get_animation(), gtk_image_get_animation, refreturn)
   _WRAP_METHOD(Glib::RefPtr<const Gdk::PixbufAnimation> get_animation() const, gtk_image_get_animation, refreturn, constversion)
 
-  //TODO: Documentation:
+ /** Gets the Gio::Icon and size being displayed by the Gtk::Image.
+  * The storage type of the image must be IMAGE_EMPTY or
+  * IMAGE_GICON (see get_storage_type()).
+  *
+  * @param icon_size A place to store an icon size.
+  * 
+  * @newin2p14
+  */
   Glib::RefPtr<Gio::Icon> get_gicon(Gtk::IconSize& icon_size);
 
+ /** Gets the Gio::Icon and size being displayed by the Gtk::Image.
+  * The storage type of the image must be IMAGE_EMPTY or
+  * IMAGE_GICON (see get_storage_type()).
+  *
+  * @param icon_size A place to store an icon size.
+  * 
+  * @newin2p14
+  */
   Glib::RefPtr<const Gio::Icon> get_gicon(Gtk::IconSize& icon_size) const;
   _IGNORE(gtk_image_get_gicon)
 

Modified: trunk/gtk/src/pagesetup.hg
==============================================================================
--- trunk/gtk/src/pagesetup.hg	(original)
+++ trunk/gtk/src/pagesetup.hg	Fri Jul 25 15:31:32 2008
@@ -46,25 +46,38 @@
 protected:
   _CTOR_DEFAULT
 
-#if 0 //TODO: Reimplement, or add _construct_from_* functions in GTK+. See bug #475565 (fixed).
-GtkPageSetup	  *gtk_page_setup_new_from_file	    (const gchar         *file_name,
-						     GError              **error);
-GtkPageSetup	  *gtk_page_setup_new_from_key_file (GKeyFile            *key_file,
-						     const gchar         *group_name,
-						     GError             **error);
-#endif
-
 public:
   _WRAP_CREATE()
 
-  //TODO: Documentation:
+ /** Reads the page setup from the "Page Setup" group in the key file @a key_file.
+  * Returns a new PageSetup object with the restored
+  * page setup, or an empty RefPtr if an error occurred.
+  *
+  * @param key_file The KeyFile to retrieve the page setup from.
+  * @result The restored PageSetup
+  * 
+  * @throws KeyFileError
+  *
+  * @newin2p14
+  */
 #ifdef GLIBMM_EXCEPTIONS_ENABLED
   static Glib::RefPtr<PageSetup> create_from_key_file(const Glib::KeyFile& key_file);
 #else
   static Glib::RefPtr<PageSetup> create_from_key_file(const Glib::KeyFile& key_file, std::auto_ptr<Glib::Error>& error);
 #endif //GLIBMM_EXCEPTIONS_ENABLED
 
-  //TODO: Documentation:
+ /** Reads the page setup from the group @a group_name in the key file @a key_file.
+  * Returns a new PageSetup object with the restored
+  * page setup, or an empty RefPtr if an error occurred.
+  *
+  * @param key_file The KeyFile to retrieve the page setup from.
+  * @param group_name The name of the group in the key_file to read.
+  * @result The restored PageSetup
+  * 
+  * @throws KeyFileError
+  *
+  * @newin2p14
+  */
 #ifdef GLIBMM_EXCEPTIONS_ENABLED
   static Glib::RefPtr<PageSetup> create_from_key_file(const Glib::KeyFile& key_file, const Glib::ustring& group_name);
 #else
@@ -72,7 +85,15 @@
 #endif //GLIBMM_EXCEPTIONS_ENABLED
   _IGNORE(gtk_page_setup_new_from_key_file)
 
-  //TODO: Documentation:
+ /** Reads the page setup from the file @file_name. Returns a 
+  * new PageSetup object with the restored page setup, 
+  * or an empty RefPtr if an error occurred. See save_to_file().
+  *
+  * @param file_name The filename to read the page setup from.
+  * @result The restored PageSetup
+  * 
+  * @newin2p14
+  */
 #ifdef GLIBMM_EXCEPTIONS_ENABLED
   static Glib::RefPtr<PageSetup> create_from_file(const std::string& file_name);
 #else
@@ -88,7 +109,15 @@
   #m4 _CONVERSION(`const Glib::KeyFile&', `GKeyFile*', __FCR2P)
   _WRAP_METHOD(bool load_from_key_file(const Glib::KeyFile& key_file, const Glib::ustring& group_name), gtk_page_setup_load_key_file, errthrow)
 
-  //TODO: Documentation:
+ /** Reads the page setup from the "Page Setup" group in the key file @a key_file.
+  *
+  * @param key_file The KeyFile to retrieve the page setup from.
+  * @result true on success
+  * 
+  * @throws KeyFileError
+  *
+  * @newin2p14
+  */
 #ifdef GLIBMM_EXCEPTIONS_ENABLED
   bool load_from_key_file(const Glib::KeyFile& key_file);
 #else

Modified: trunk/gtk/src/printsettings.hg
==============================================================================
--- trunk/gtk/src/printsettings.hg	(original)
+++ trunk/gtk/src/printsettings.hg	Fri Jul 25 15:31:32 2008
@@ -49,14 +49,40 @@
 protected:
   _CTOR_DEFAULT
 
-  //TODO: Documentation:
+ //TODO: We need fuller information about the GError domains:
+ //http://bugzilla.gnome.org/show_bug.cgi?id=544706
+
+ /** Reads the print settings from the @a key_file.
+  * Returns a new PrintSettings object with the restored settings,
+  * or an empty RefPtr if an error occurred.
+  * See save_to_key_file().
+  *
+  * @param key_file The KeyFile to retrieve the settings from.
+  * @result the restored PrintSettings
+  *
+  * @throws KeyFileError
+  *
+  * @newin2p14
+  */
 #ifdef GLIBMM_EXCEPTIONS_ENABLED
   static Glib::RefPtr<PrintSettings> create_from_key_file(const Glib::KeyFile& key_file);
 #else
   static Glib::RefPtr<PrintSettings> create_from_key_file(const Glib::KeyFile& key_file, std::auto_ptr<Glib::Error>& error);
 #endif //GLIBMM_EXCEPTIONS_ENABLED
 
-  //TODO: Documentation:
+ /** Reads the print settings from the group @a group_name in @a key_file.
+  * Returns a new PrintSettings object with the restored settings,
+  * or an empty RefPtr if an error occurred.
+  * See save_to_key_file().
+  *
+  * @param key_file The KeyFile to retrieve the settings from.
+  * @param group_name The name of the group to use.
+  * @result the restored PrintSettings
+  *
+  * @throws KeyFileError
+  *
+  * @newin2p14
+  */
 #ifdef GLIBMM_EXCEPTIONS_ENABLED
   static Glib::RefPtr<PrintSettings> create_from_key_file(const Glib::KeyFile& key_file, const Glib::ustring& group_name);
 #else
@@ -64,7 +90,17 @@
 #endif //GLIBMM_EXCEPTIONS_ENABLED
   _IGNORE(gtk_print_settings_new_from_key_file)
 
-  //TODO: Documentation:
+ /** Reads the print settings from @a file_name. Returns a new PrintSettings
+  * object with the restored settings, or an empty RefPtr if an error occurred.
+  * See save_to_file().
+  *
+  * @param file_name The filename to read the settings from.
+  * @result the restored PrintSettings
+  *
+  * @throws KeyFileError
+  *
+  * @newin2p14
+  */
 #ifdef GLIBMM_EXCEPTIONS_ENABLED
   static Glib::RefPtr<PrintSettings> create_from_file(const std::string& file_name);
 #else
@@ -118,7 +154,16 @@
   #m4 _CONVERSION(`const Glib::KeyFile&', `GKeyFile*', __FCR2P)
   _WRAP_METHOD(bool load_from_key_file(const Glib::KeyFile& key_file, const Glib::ustring& group_name), gtk_print_settings_load_key_file, errthrow)
 
-  //TODO: Documentation:
+ /** Reads the print settings from the @a key_file.
+  * See save_to_key_file().
+  *
+  * @param key_file The KeyFile to retrieve the settings from.
+  * @result true on success.
+  *
+  * @throws KeyFileError
+  *
+  * @newin2p14
+  */
 #ifdef GLIBMM_EXCEPTIONS_ENABLED
   bool load_from_key_file(const Glib::KeyFile& key_file);
 #else

Modified: trunk/gtk/src/toolshell.hg
==============================================================================
--- trunk/gtk/src/toolshell.hg	(original)
+++ trunk/gtk/src/toolshell.hg	Fri Jul 25 15:31:32 2008
@@ -29,8 +29,10 @@
 namespace Gtk
 {
 
-/** TODO: Documentation
+/** A base class for containers containing ToolItem widgets.
+ * This interface allows container widgets to provide additional information when embedding ToolItem widgets. 
  *
+ * @newin2p14
  */
 class ToolShell : public Glib::Interface
 {

Modified: trunk/gtk/src/widget.hg
==============================================================================
--- trunk/gtk/src/widget.hg	(original)
+++ trunk/gtk/src/widget.hg	Fri Jul 25 15:31:32 2008
@@ -60,6 +60,7 @@
 _WRAP_ENUM(DestDefaults, GtkDestDefaults)
 _WRAP_ENUM(WidgetFlags, GtkWidgetFlags)
 _WRAP_ENUM(WidgetHelpType, GtkWidgetHelpType)
+_WRAP_ENUM(DragResult, GtkDragResult)
 
 class Action;
 class Style;
@@ -277,12 +278,29 @@
   _WRAP_METHOD(Glib::RefPtr<Clipboard> get_clipboard(const Glib::ustring& selection), gtk_widget_get_clipboard, refreturn)
   _WRAP_METHOD(Glib::RefPtr<const Clipboard> get_clipboard(const Glib::ustring& selection) const, gtk_widget_get_clipboard, refreturn, constversion)
 
-  _WRAP_METHOD(Glib::RefPtr<Gdk::Pixmap> get_snapshot(const Gdk::Rectangle& clip_rect) const, gtk_widget_get_snapshot)
+  _WRAP_METHOD(Glib::RefPtr<Gdk::Pixmap> get_snapshot(Gdk::Rectangle& clip_rect) const, gtk_widget_get_snapshot)
 
-  //TODO: Documentation:
+ /** Create a Gdk::Pixmap of the contents of the widget and its children.
+  *
+  * Works even if the widget is obscured. The depth and visual of the
+  * resulting pixmap is dependent on the widget being snapshot and likely
+  * differs from those of a target widget displaying the pixmap.
+  * The function Gdk::Pixbuf::get_from_drawable() can be used to convert
+  * the pixmap to a visual independant representation.
+  *
+  * The snapshot area used by this function is the widget's allocation plus
+  * any extra space occupied by additional windows belonging to this widget
+  * (such as the arrows of a spin button).
+  * Thus, the resulting snapshot pixmap is possibly larger than the allocation.
+  *
+  * The returned pixmap can be empty.
+  *
+  * @result A Gdk::Pixmap snapshot of the widget
+  * 
+  * @newin2p14
+  */
   Glib::RefPtr<Gdk::Pixmap> get_snapshot() const;
 
-
   //TODO: This probably needs a special conversion to do an extra ref (take_copy=true) for the returned instance:
   _WRAP_METHOD(Glib::RefPtr<Atk::Object> get_accessible(), gtk_widget_get_accessible, refreturn, ifdef GTKMM_ATKMM_ENABLED)
 
@@ -788,7 +806,7 @@
    */
   _WRAP_SIGNAL(void drag_data_delete(const Glib::RefPtr<Gdk::DragContext>& context), "drag_data_delete")
 
-  //TODO: Check the parameters: _WRAP_SIGNAL(bool drag_failed(const Glib::RefPtr<Gdk::DragContext>& context), "drag_failed")
+  _WRAP_SIGNAL(bool drag_failed(const Glib::RefPtr<Gdk::DragContext>& context, DragResult result), "drag_failed", no_default_handler)
   
   /**  The drag_leave signal is emitted on the drop site when the cursor leaves the widget.
    * A typical reason to connect to this signal is to undo things done in the drag_motion signal handler, 

Modified: trunk/tools/m4/convert_gtk.m4
==============================================================================
--- trunk/tools/m4/convert_gtk.m4	(original)
+++ trunk/tools/m4/convert_gtk.m4	Fri Jul 25 15:31:32 2008
@@ -125,6 +125,7 @@
 _CONV_ENUM(Gtk,PrintOperationAction)
 _CONV_ENUM(Gtk,PrintError)
 _CONV_ENUM(Gtk,PrintCapabilities)
+_CONV_ENUM(Gtk,DragResult)
 
 _CONVERSION(`GtkIconSize',`IconSize',`IconSize(static_cast<int>($3))')
 _CONVERSION(`GtkIconSize',`Gtk::IconSize',`Gtk::IconSize(static_cast<int>($3))')
@@ -624,3 +625,5 @@
 _CONVERSION(`const Glib::RefPtr<const Gio::Icon>&',`GIcon*',__CONVERT_CONST_REFPTR_TO_P_SUN(Gio::Icon))
 
 
+_CONVERSION(`GtkDragResult',`DragResult',`($2)$3')
+
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]