cvs: php-gtk-doc /manual/en/reference/gtk gtkiconfactory.xml

auroraeosrose		Wed Oct  4 18:06:47 2006 UTC

  Modified files:              
    /php-gtk-doc/manual/en/reference/gtk	gtkiconfactory.xml 
  Log:
  Daily Doc - finish descriptions for GtkIconFactory
  
http://cvs.php.net/viewvc.cgi/php-gtk-doc/manual/en/reference/gtk/gtkiconfactory.xml?r1=1.5&r2=1.6&diff_format=u
Index: php-gtk-doc/manual/en/reference/gtk/gtkiconfactory.xml
diff -u php-gtk-doc/manual/en/reference/gtk/gtkiconfactory.xml:1.5 php-gtk-doc/manual/en/reference/gtk/gtkiconfactory.xml:1.6
--- php-gtk-doc/manual/en/reference/gtk/gtkiconfactory.xml:1.5	Fri Aug 11 07:31:16 2006
+++ php-gtk-doc/manual/en/reference/gtk/gtkiconfactory.xml	Wed Oct  4 18:06:47 2006
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8" ?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
 <classentry id="gtk.gtkiconfactory">
  <classmeta>
   <classtitle>GtkIconFactory</classtitle>
@@ -40,10 +40,21 @@
     </funcprototype>
    </funcsynopsis>
    <shortdesc>
-
+    Creates a new <classname>GtkIconFactory</classname> to manage icon sets.
    </shortdesc>
    <desc>
-
+    <para>
+     Creates a new <classname>GtkIconFactory</classname>. An icon factory
+     manages a collection of icon sets; an icon set manages a set of variants of
+     a particular icon. Icons in an icon factory are named by a stock ID, which
+     is a simple string identifying the icon. Each
+     <classname>GtkStyle</classname> has a list of icon factories derived from
+     the current theme; those icon factories are consulted first when searching
+     for an icon. If the theme doesn't set a particular icon, GTK+ looks for the
+     icon in a list of default icon factories. Applications with icons should
+     add a default icon factory with their icons, which will allow themes to
+     override the icons for the application.
+    </para>
    </desc>
   </constructor>
 
@@ -55,14 +66,28 @@
    <funcsynopsis>
     <funcprototype>
      <funcdef>void <function>add</function></funcdef>
-     <paramdef>void</paramdef>
+     <paramdef><classname>GtkIconSet</classname> <parameter>icon_set</parameter></paramdef>
+     <paramdef>string <parameter>stock_id</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <shortdesc>
-
+    Adds a new <classname>GtkIconSet</classname> to the icon factory.
    </shortdesc>
    <desc>
-
+    <para>
+     This method adds a specified <literal>icon_set</literal> to the icon
+     factory under the name <literal>stock_id</literal>. The stock id you
+     specify should include the name of your application. Normally applications
+     create a <classname>GtkIconFactory</classname> and add it to the list of
+     default factories with <function
+     class="GtkIconFactory">add_default</function>. Then they pass the stock id
+     to widgets like <classname>GtkImage</classname> to display the icon.
+    </para>
+    <para>
+     Themes can provide an icon with the same name to override your
+     application's default icons. If an icon already existed in the icon factory
+     for stock_id, it is unreferenced and replaced with the new icon_set.
+    </para>
    </desc>
   </method>
 
@@ -74,10 +99,18 @@
     </funcprototype>
    </funcsynopsis>
    <shortdesc>
-
+    Adds the icon factory to list of default factories.
    </shortdesc>
    <desc>
     <para>
+     This method adds the icon factory to the list of icon factories searched by
+     <function class="GtkStyle">lookup_icon_set</function>. This means that, for
+     example, <function class="GtkImage">set_from_stock</function> will be able
+     to find icons in the icon factory. There will normally be an icon factory
+     added for each library or application that comes with icons. The default
+     icon factories can be overridden by themes.
+    </para>
+    <para>
      &seealso;
      <function class="GtkIconFactory">lookup_default</function>, 
      <function class="GtkIconFactory">remove_default</function>
@@ -94,10 +127,20 @@
     </funcprototype>
    </funcsynopsis>
    <shortdesc>
-
+    Searches for a <classname>GtkIconSet</classname> in current icon factory.
    </shortdesc>
    <desc>
-
+    <para>
+     This function returns a <classname>GtkIconSet</classname> that has the name
+     specified by <literal>stock_id</literal> by searching the current <classname>GtkIconFactory</classname> instance
+     . If the icon set cannot be found the function returns NULL.
+    </para>
+    <para>
+     You should use <function class="GtkStyle">lookup_icon_set</function> on the
+     <classname>GtkStyle</classname> for the widget for displaying the icon to
+     the user, instead of using this function directly, so that themes
+     are taken into account.
+    </para>
    </desc>
   </method>
 
@@ -109,10 +152,15 @@
     </funcprototype>
    </funcsynopsis>
    <shortdesc>
-
+    Searches for a <classname>GtkIconSet</classname> in default icon factories.
    </shortdesc>
    <desc>
     <para>
+     This function returns a <classname>GtkIconSet</classname> that has the name
+     specified by <literal>stock_id</literal> by searching the default factories
+     available. If the icon set cannot be found the function returns NULL.
+    </para>
+    <para>
      &seealso;
      <function class="GtkIconFactory">add_default</function>, 
      <function class="GtkIconFactory">remove_default</function>
@@ -129,10 +177,15 @@
     </funcprototype>
    </funcsynopsis>
    <shortdesc>
-
+    Removes an icon factory from the list of default factories.
    </shortdesc>
    <desc>
     <para>
+     This method removes an icon factory from the list of default icon
+     factories. Not normally used though you might use it for a library that can
+     be unloaded or shut down.
+    </para>
+    <para>
      &seealso;
      <function class="GtkIconFactory">add_default</function>, 
      <function class="GtkIconFactory">lookup_default</function>