gtkmm r995 - in trunk: . gtk/src

[murrayc svn gnome org]

Author: murrayc
Date: Wed May 14 17:37:10 2008
New Revision: 995
URL: http://svn.gnome.org/viewvc/gtkmm?rev=995&view=rev

Log:
2008-05-14  Murray Cumming  <murrayc murrayc com>

* gtk/src/gtk_docs_override.xml: Add custom documentation for the 
gtk_image_set_from_*() functions, because they refer to new_from_*
 functions instead of our constructors.
* gtk/src/image.hg: Add documentation for the constructors.

Modified:
   trunk/ChangeLog
   trunk/gtk/src/gtk_docs_override.xml
   trunk/gtk/src/image.hg

Modified: trunk/gtk/src/gtk_docs_override.xml
==============================================================================
--- trunk/gtk/src/gtk_docs_override.xml	(original)
+++ trunk/gtk/src/gtk_docs_override.xml	Wed May 14 17:37:10 2008
@@ -2031,6 +2031,113 @@
   <return></return>
 </function>
 
+
+<function name="gtk_image_set_from_pixmap">
+<description>
+See the Image::Image(const Glib::RefPtr&lt;Gdk::Pixmap&gt;&amp; pixmap, const Glib::RefPtr&lt;Gdk::Bitmap&gt;&amp; mask) constructor for details.
+</description>
+<parameters>
+<parameter name="image">
+<parameter_description> a #GtkImage
+</parameter_description>
+</parameter>
+<parameter name="pixmap">
+<parameter_description> a #Gdk::Pixmap
+</parameter_description>
+</parameter>
+<parameter name="mask">
+<parameter_description> a #Gdk::Bitmap
+</parameter_description>
+</parameter>
+</parameters>
+<return></return>
+</function>
+
+<function name="gtk_image_set_from_pixbuf">
+<description>
+See the Image::Image(const Glib::RefPtr&lt;Gdk::Pixbuf&gt;&amp; pixbuf) constructor for details.
+</description>
+<parameters>
+<parameter name="image">
+<parameter_description> a #GtkImage
+</parameter_description>
+</parameter>
+<parameter name="pixbuf">
+<parameter_description> a #Gdk::Pixbuf
+</parameter_description>
+</parameter>
+</parameters>
+<return></return>
+</function>
+
+<function name="gtk_image_set_from_image">
+<description>
+See the Image::Image(const Glib::RefPtr&lt;Gdk::Image&gt;&amp; image, const Glib::RefPtr&lt;Gdk::Bitmap&gt;&amp; mask) constructor for details.
+</description>
+<parameters>
+<parameter name="image">
+<parameter_description> a #GtkImage
+</parameter_description>
+</parameter>
+<parameter name="gdk_image">
+<parameter_description> a #Gdk::Image
+</parameter_description>
+</parameter>
+<parameter name="mask">
+<parameter_description> a #Gdk::Bitmap
+</parameter_description>
+</parameter>
+</parameters>
+<return></return>
+</function>
+
+<function name="gtk_image_set_from_file">
+<description>
+See the Image::Image(const std::string&amp; file) constructor for details.
+</description>
+<parameters>
+<parameter name="image">
+<parameter_description> a #GtkImage
+</parameter_description>
+</parameter>
+<parameter name="filename">
+<parameter_description> a filename.
+</parameter_description>
+</parameter>
+</parameters>
+<return></return>
+</function>
+
+<!-- Don't just refer to a constructor for this one, 
+     because there is no such constructor,
+     to avoid ambiguity with the filename constructor.
+-->
+<function name="gtk_image_set_from_icon_name">
+<description>
+Causes the Image to display an icon from the current icon theme.
+If the icon name isn&apos;t known, a &quot;broken image&quot; icon will be
+displayed instead.  If the current icon theme is changed, the icon
+will be updated appropriately.
+
+Since: 2.6
+</description>
+<parameters>
+<parameter name="image">
+<parameter_description> a #GtkImage
+</parameter_description>
+</parameter>
+<parameter name="icon_name">
+<parameter_description> an icon name
+</parameter_description>
+</parameter>
+<parameter name="size">
+<parameter_description> a stock icon size
+</parameter_description>
+</parameter>
+</parameters>
+<return></return>
+</function>
+
 <function name="gtk_icon_factory_add_default">
   <description>
     Adds an icon factory to the list of icon factories searched by

Modified: trunk/gtk/src/image.hg
==============================================================================
--- trunk/gtk/src/image.hg	(original)
+++ trunk/gtk/src/image.hg	Wed May 14 17:37:10 2008
@@ -60,10 +60,45 @@
 public:
 
   _CTOR_DEFAULT
+
+  //TODO: The C documentation says that the constructor parameters can be NULL. Choose sensible method overloads.
+
+  /** Creates an Image widget displaying @a pixmap with a @a mask.
+   * A Gdk::Pixmap is a server-side image buffer in the pixel format of the current display. 
+   *
+   * @param pixmap A Gdk::Pixmap
+   * @param mask A Gdk::Bitmap
+   */
   _WRAP_CTOR(Image(const Glib::RefPtr<Gdk::Pixmap>& pixmap, const Glib::RefPtr<Gdk::Bitmap>& mask), gtk_image_new_from_pixmap)
+
+  /** Creates an Image widget displaying an @a image with a mask.
+   * A Gdk::Image is a client-side image buffer in the pixel format of the current display.
+   */
   _WRAP_CTOR(Image(const Glib::RefPtr<Gdk::Image>& image, const Glib::RefPtr<Gdk::Bitmap>& mask), gtk_image_new_from_image)
+
+  /** Creates an Image widget displaying the file @a filename.
+   * If the file isn't found or can't be loaded, the resulting Gtk::Image will display a "broken image" icon. 
+   *
+   * If the file contains an animation, the image will contain an animation.
+   *
+   * If you need to detect failures to load the file, use Gdk::Pixbuf::create_from_file() to load the file yourself, 
+   * then create the GtkImage from the pixbuf. (Or for animations, use Gdk::PixbufAnimation::create_from_file()).
+   *
+   * The storage type (get_storage_type()) of the returned image is not defined. It will be whatever is appropriate for displaying the file.
+   */
   _WRAP_CTOR(Image(const std::string& file), gtk_image_new_from_file)
+
+  //TODO: Change this documentation when we have wrapped new_from_icon_set().
+  /** Creates a new Image widget displaying @a pixbuf.
+   * Note that this just creates an GtkImage from the pixbuf. The Gtk::Image created will not react to state changes. 
+   * Should you want that, you should use new_from_icon_set().
+   */
   _WRAP_CTOR(Image(const Glib::RefPtr<Gdk::Pixbuf>& pixbuf), gtk_image_new_from_pixbuf)
+  //TODO: Wrap gtk_image_new_from_icon_set()
+
+  //We don't wrap gtk_image_new_from_icon_name() to avoid a clash with the from-filename constructor.
+  //But we do wrap gtk_image_set_from_icon_name()
+  _IGNORE(gtk_image_new_from_icon_name)
 
   /** Creates am Image displaying a stock icon.
    * Sample stock icon identifiers are Gtk::Stock::OPEN, Gtk::Stock::EXIT. Sample stock sizes are Gtk::ICON_SIZE_MENU, Gtk::ICON_SIZE_SMALL_TOOLBAR.
@@ -84,6 +119,8 @@
   _WRAP_METHOD(void set(const Gtk::StockID& stock_id, IconSize size), gtk_image_set_from_stock)
   _WRAP_METHOD(void set(IconSet& icon_set, IconSize size), gtk_image_set_from_icon_set)
   _WRAP_METHOD(void set(const Glib::RefPtr<Gdk::PixbufAnimation>& animation), gtk_image_set_from_animation)
+
+
   _WRAP_METHOD(void set_from_icon_name(const Glib::ustring& icon_name, IconSize size), gtk_image_set_from_icon_name)
 
   _WRAP_METHOD(void clear(), gtk_image_clear)