Add some hints about GnomeColorPicker --> GtkColorButton migration.

2004-11-04  Matthias Clasen  <mclasen@redhat.com>

	* gtk/gtk-docs.sgml:
	* gtk/migrating-GtkColorButton.sgml: Add some hints about
	GnomeColorPicker --> GtkColorButton migration.

3 files changed, 56 insertions, 0 deletions

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 140431bbe..0f6021ac6 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,5 +1,11 @@
 2004-11-04  Matthias Clasen  <mclasen@redhat.com>
 
+	* gtk/gtk-docs.sgml: 
+	* gtk/migrating-GtkColorButton.sgml: Add some hints about
+	GnomeColorPicker --> GtkColorButton migration.
+
+	* gtk/migrating-GtkAboutDialog.sgml: Fix links.
+
 	* gtk/Makefile.am (content_files): Add new migration chapters.
 
 	* gtk/tmpl/gtkaboutdialog.sgml: Markup fix.
diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml
index a6dc04610..26740e088 100644
--- a/docs/reference/gtk/gtk-docs.sgml
+++ b/docs/reference/gtk/gtk-docs.sgml
@@ -193,6 +193,7 @@
 <!ENTITY gtk-migrating-GtkComboBox SYSTEM "migrating-GtkComboBox.sgml">
 <!ENTITY gtk-migrating-GtkIconView SYSTEM "migrating-GtkIconView.sgml">
 <!ENTITY gtk-migrating-GtkAboutDialog SYSTEM "migrating-GtkAboutDialog.sgml">
+<!ENTITY gtk-migrating-GtkColorButton SYSTEM "migrating-GtkColorButton.sgml">
 <!ENTITY version SYSTEM "version.xml">
 <!ENTITY gtk-query-immodules SYSTEM "gtk-query-immodules-2.0.xml">
 <!ENTITY gtk-update-icon-cache SYSTEM "gtk-update-icon-cache.xml">
@@ -564,6 +565,9 @@ that is, GUI components such as <link linkend="GtkButton">GtkButton</link> or
       <para>
 	This part describes what you need to change in programs use
 	older versions of GTK+ so that they can use the new features.
+        It also mentions how to convert applications using widgets
+        found in the libgnomeui library to use their counterparts
+        in GTK+.
       </para>
     </partintro>
 
@@ -575,6 +579,7 @@ that is, GUI components such as <link linkend="GtkButton">GtkButton</link> or
     &gtk-migrating-GtkComboBox;
     &gtk-migrating-GtkIconView;
     &gtk-migrating-GtkAboutDialog;
+    &gtk-migrating-GtkColorButton;
   </part>
 
   <part>
diff --git a/docs/reference/gtk/migrating-GtkColorButton.sgml b/docs/reference/gtk/migrating-GtkColorButton.sgml
new file mode 100644
index 000000000..183b50d00
--- /dev/null
+++ b/docs/reference/gtk/migrating-GtkColorButton.sgml
@@ -0,0 +1,45 @@
+<chapter id="gtk-migrating-GtkColorButton">
+
+  <title>Migrating from GnomeColorPicker to GtkColorButton</title>
+
+  <para>
+    Since version 2.6, GTK+ provides the <link linkend="GtkColorButton">GtkColorButton</link>
+    widget as a replacement for the GnomeColorPicker widget in the libgnomeui library.
+  </para>
+
+  <para>
+   Porting an application from GnomeColorPicker to <link linkend="GtkColorButton">GtkColorButton</link>
+   is very simple. <link linkend="GtkColorButton">GtkColorButton</link> doesn't support dithering
+   (since it is rarely needed on modern hardware), and it doesn't have setters and getters to set the 
+   color from floating point or integer components. So instead of
+   <informalexample><programlisting>
+   guint red, green, blue, alpha;
+   /* ... */
+   gnome_color_picker_set_i8 (color_picker, red, green, blue, alpha);
+   </programlisting></informalexample>   
+   you have to write
+   <informalexample><programlisting>
+   GdkColor color;
+
+   color.red = red << 8;
+   color.green = green << 8;
+   color.blue = blue << 8;
+   gtk_color_button_set_color (color_picker, &color);
+   gtk_color_button_set_alpha (color_picker, alpha << 8);
+   </programlisting></informalexample>   
+  and similarly for the setters taking other number formats. For gnome_color_picker_set_i16() no conversion
+  is needed, for gome_color_picker_set_d(), you need to convert the color components like this:
+   <informalexample><programlisting>  
+   color.red = (guint16) (red * 65535.0 + 0.5);
+   color.green = (guint16) (green * 65535.0 + 0.5);
+   color.blue = (guint16) (blue * 65535.0 + 0.5);
+   </programlisting></informalexample>   
+  </para>
+</chapter>
+
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("gtk-docs.sgml" "book" "part" "chapter")
+End:
+-->