Fix usage of 'Since:' keyword in API documentation
[hildon] / src / hildon-note.c
index 4aebb67..48919a1 100644 (file)
@@ -8,7 +8,7 @@
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public License
  * as published by the Free Software Foundation; version 2.1 of
- * the License.
+ * the License, or (at your option) any later version.
  *
  * This library is distributed in the hope that it will be useful, but
  * WITHOUT ANY WARRANTY; without even the implied warranty of
 
 /**
  * SECTION:hildon-note
- * @short_description: A widget to ask confirmation from the user
+ * @short_description: A widget to ask confirmation from the user.
  *
  * Notes are used to for confirmation (OK/Cancel/etc.) from the user.
- * A simple note contains an information text and an OK button to be
- * pressed.  Additional features such as progress bars or animation can
- * also be included. 
+ * A simple note contains an information text. Additional features
+ * such as progress bars or animation can also be included.
  * 
  * <example>
  * <title>HildonNote example</title>
  * <programlisting>
  * <!-- -->
- * hildon_note_new_confirmation (window, "Confirmation message...");
+ * gboolean
+ * show_confirmation_note (GtkWindow *parent)
+ * {
+ *   gint retcode;
+ *   GtkWidget *note;
+ *   note = hildon_note_new_confirmation (parent, "Confirmation message...");
  * <!-- -->
- * i = gtk_dialog_run (GTK_DIALOG (note));
- * gtk_widget_destroy (GTK_WIDGET (note));
+ *   retcode = gtk_dialog_run (GTK_DIALOG (note));
+ *   gtk_widget_destroy (note);
  * <!-- -->
- * if (i == GTK_RESPONSE_OK)
- *      gtk_infoprint (window, "User pressed 'OK' button'");
- * else
- *      gtk_infoprint (window, "User pressed 'Cancel' button" );
+ *   if (retcode == GTK_RESPONSE_OK) {
+ *        g_debug ("User pressed 'OK' button'");
+ *        return TRUE;
+ *   } else {
+ *        g_debug ("User pressed 'Cancel' button");
+ *        return FALSE;
+ *   }
+ * }
  * </programlisting>
  * </example>
  */
 #include                                        <config.h>
 #endif
 
-#include                                        "hildon-note.h"
-#include                                        <gtk/gtklabel.h>
-#include                                        <gtk/gtkimage.h>
-#include                                        <gtk/gtkhbox.h>
-#include                                        <gtk/gtkalignment.h>
-#include                                        <gtk/gtkvbox.h>
-#include                                        <gtk/gtkbutton.h>
+#include                                        <stdio.h>
+#include                                        <string.h>
 #include                                        <libintl.h>
+#include                                        <X11/X.h>
+#include                                        <X11/Xatom.h>
+#include                                        <gdk/gdkx.h>
+
+#undef HILDON_DISABLE_DEPRECATED
+
+#include                                        "hildon-note.h"
 #include                                        "hildon-defines.h"
 #include                                        "hildon-sound.h"
 #include                                        "hildon-banner.h" 
 #include                                        "hildon-enum-types.h"
-#include                                        <stdio.h>
-#include                                        <string.h>
 #include                                        "hildon-note-private.h"
 
+
 #define                                         CONFIRMATION_SOUND_PATH \
                                                 "/usr/share/sounds/ui-confirmation_note.wav"
 
 #define                                         INFORMATION_SOUND_PATH \
                                                 "/usr/share/sounds/ui-information_note.wav"
 
-#define                                         HILDON_NOTE_CONFIRMATION_ICON \
-                                                "qgn_note_confirm"
-
-#define                                         HILDON_NOTE_INFORMATION_ICON \
-                                                "qgn_note_info"
-
 #define                                         _(String) dgettext("hildon-libs", String)
 
 static void 
@@ -126,6 +129,7 @@ enum
 
 static GtkDialogClass*                          parent_class;
 
+
 static void
 hildon_note_set_property                        (GObject *object,
                                                  guint prop_id,
@@ -157,13 +161,17 @@ hildon_note_set_property                        (GObject *object,
             break;
 
         case PROP_HILDON_NOTE_ICON:
-            gtk_image_set_from_icon_name (GTK_IMAGE (priv->icon), 
-                    g_value_get_string(value), HILDON_ICON_SIZE_BIG_NOTE);
+            if (priv->icon) {
+              g_free (priv->icon);
+            }
+            priv->icon = g_value_dup_string (value);
             break;
 
         case PROP_HILDON_NOTE_STOCK_ICON:
-            gtk_image_set_from_stock (GTK_IMAGE (priv->icon), 
-                    g_value_get_string (value), HILDON_ICON_SIZE_BIG_NOTE);
+            if (priv->stock_icon) {
+              g_free (priv->stock_icon);
+            }
+            priv->stock_icon = g_value_dup_string (value);
             break;
 
         case PROP_HILDON_NOTE_PROGRESSBAR:
@@ -213,11 +221,11 @@ hildon_note_get_property                        (GObject *object,
             break;
 
         case PROP_HILDON_NOTE_ICON:
-            g_object_get_property (G_OBJECT (priv->icon), "icon-name", value);
+            g_value_set_string (value, priv->icon);
             break;
 
         case PROP_HILDON_NOTE_STOCK_ICON:
-            g_object_get_property (G_OBJECT (priv->icon), "stock", value);
+            g_value_set_string (value, priv->stock_icon);
             break;
 
         case PROP_HILDON_NOTE_PROGRESSBAR:
@@ -303,6 +311,8 @@ hildon_note_class_init                          (HildonNoteClass *class)
      * HildonNote:icon:
      *
      * Icon for the note.
+     *
+     * Deprecated: Since 2.2
      */
     g_object_class_install_property (object_class,
             PROP_HILDON_NOTE_ICON,
@@ -316,6 +326,8 @@ hildon_note_class_init                          (HildonNoteClass *class)
      * HildonNote:stock-icon:
      *
      * Stock icon name for the note.
+     *
+     * Deprecated: Since 2.2
      */
     g_object_class_install_property (object_class,
             PROP_HILDON_NOTE_STOCK_ICON,
@@ -347,20 +359,20 @@ hildon_note_init                                (HildonNote *dialog)
 
     priv->label = gtk_label_new (NULL);
     gtk_label_set_line_wrap (GTK_LABEL (priv->label), TRUE);
-    
-    priv->icon  = gtk_image_new ();
+
+    priv->icon = NULL;
+    priv->stock_icon = NULL;
 
     /* Acquire real references to our internal children, since
        they are not nessecarily packed into container in each
        layout */
-    g_object_ref (priv->label);
-    g_object_ref (priv->icon);
-
-    gtk_object_sink (GTK_OBJECT (priv->label));
-    gtk_object_sink (GTK_OBJECT (priv->icon));
+    g_object_ref_sink (priv->label);
 
     gtk_dialog_set_has_separator (GTK_DIALOG (dialog), FALSE);
     gtk_window_set_modal (GTK_WINDOW (dialog), TRUE);
+
+    /* We use special hint to turn the note into information notification. */
+    gtk_window_set_type_hint (GTK_WINDOW (dialog), GDK_WINDOW_TYPE_HINT_NOTIFICATION);
 }
 
 
@@ -376,8 +388,14 @@ hildon_note_finalize                            (GObject *obj_self)
     if (priv->label)
         g_object_unref (priv->label);
 
-    if (priv->icon)
-        g_object_unref (priv->icon);
+    if (priv->icon) {
+        g_free (priv->icon);
+        priv->icon = NULL;
+    }
+    if (priv->stock_icon) {
+        g_free (priv->stock_icon);
+        priv->stock_icon = NULL;
+    }
 
     if (priv->progressbar)
         g_object_unref (priv->progressbar);
@@ -388,9 +406,13 @@ hildon_note_finalize                            (GObject *obj_self)
     G_OBJECT_CLASS (parent_class)->finalize (obj_self);
 }
 
+
 static void
 hildon_note_realize                             (GtkWidget *widget)
 {
+    GdkDisplay *display;
+    Atom atom;
+    const gchar *notification_type;
     HildonNotePrivate *priv = HILDON_NOTE_GET_PRIVATE (widget);
     g_assert (priv);
 
@@ -405,6 +427,21 @@ hildon_note_realize                             (GtkWidget *widget)
     if (priv->sound_signal_handler == 0)
         priv->sound_signal_handler = g_signal_connect_after(widget, 
                 "expose-event", G_CALLBACK (sound_handling), NULL);
+
+    /* Set the _HILDON_NOTIFICATION_TYPE property so Matchbox places the window correctly */
+    display = gdk_drawable_get_display (widget->window);
+    atom = gdk_x11_get_xatom_by_name_for_display (display, "_HILDON_NOTIFICATION_TYPE");
+
+    if (priv->note_n == HILDON_NOTE_TYPE_INFORMATION ||
+        priv->note_n == HILDON_NOTE_TYPE_INFORMATION_THEME) {
+        notification_type = "_HILDON_NOTIFICATION_TYPE_INFO";
+    } else {
+        notification_type = "_HILDON_NOTIFICATION_TYPE_CONFIRMATION";
+    }
+
+    XChangeProperty (GDK_WINDOW_XDISPLAY (widget->window), GDK_WINDOW_XID (widget->window),
+                     atom, XA_STRING, 8, PropModeReplace, (guchar *) notification_type,
+                     strlen (notification_type));
 }
 
 /* Helper function for removing a widget from it's container.
@@ -435,7 +472,6 @@ hildon_note_rebuild                             (HildonNote *note)
 
     /* Reuse exiting content widgets for new layout */
     unpack_widget (priv->label);
-    unpack_widget (priv->icon);
     unpack_widget (priv->progressbar);
 
     /* Destroy old layout and buttons */
@@ -457,34 +493,24 @@ hildon_note_rebuild                             (HildonNote *note)
     {
         case HILDON_NOTE_TYPE_CONFIRMATION:
             priv->okButton = gtk_dialog_add_button (dialog,
-                    _("ecdg_bd_confirmation_note_ok"), GTK_RESPONSE_OK);
-            priv->cancelButton = gtk_dialog_add_button (dialog,
-                    _("ecdg_bd_confirmation_note_cancel"), GTK_RESPONSE_CANCEL);
-
-            /* Fall through */
-        case HILDON_NOTE_TYPE_CONFIRMATION_BUTTON:
-            gtk_image_set_from_icon_name (GTK_IMAGE (priv->icon),
-                    HILDON_NOTE_CONFIRMATION_ICON, 
-                    HILDON_ICON_SIZE_BIG_NOTE);
-            break;
-
-        case HILDON_NOTE_TYPE_INFORMATION_THEME:
-        case HILDON_NOTE_TYPE_INFORMATION:
-            /* Add clickable OK button (cancel really,
-               but doesn't matter since this is info) */
+                    _("wdgt_bd_yes"), GTK_RESPONSE_OK);
             priv->cancelButton = gtk_dialog_add_button (dialog,
-                    _("ecdg_bd_information_note_ok"), GTK_RESPONSE_CANCEL);
-            gtk_image_set_from_icon_name (GTK_IMAGE (priv->icon),
-                    HILDON_NOTE_INFORMATION_ICON,
-                    HILDON_ICON_SIZE_BIG_NOTE);
+                    _("wdgt_bd_no"), GTK_RESPONSE_CANCEL);
+            gtk_widget_show (priv->cancelButton);
+            gtk_widget_set_no_show_all (priv->cancelButton, FALSE);
             break;
 
         case HILDON_NOTE_TYPE_PROGRESSBAR:
             priv->cancelButton = gtk_dialog_add_button (dialog,
-                    _("ecdg_bd_cancel_note_cancel"), GTK_RESPONSE_CANCEL);
+                    _("wdgt_bd_stop"), GTK_RESPONSE_CANCEL);
+            gtk_widget_show (priv->cancelButton);
+            gtk_widget_set_no_show_all (priv->cancelButton, FALSE);
             IsHorizontal = FALSE;
             break;
 
+        case HILDON_NOTE_TYPE_CONFIRMATION_BUTTON:
+        case HILDON_NOTE_TYPE_INFORMATION_THEME:
+        case HILDON_NOTE_TYPE_INFORMATION:
         default:
             break;
     }
@@ -494,12 +520,6 @@ hildon_note_rebuild                             (HildonNote *note)
         priv->box = gtk_hbox_new (FALSE, HILDON_MARGIN_DEFAULT);
         gtk_container_add (GTK_CONTAINER (dialog->vbox), priv->box);
 
-        if (priv->icon) {
-            GtkWidget *alignment = gtk_alignment_new (0, 0, 0, 0);
-
-            gtk_box_pack_start (GTK_BOX (priv->box), alignment, FALSE, FALSE, 0);
-            gtk_container_add (GTK_CONTAINER (alignment), priv->icon);
-        }
         gtk_box_pack_start (GTK_BOX (priv->box), priv->label, TRUE, TRUE, 0);
 
     } else {
@@ -547,6 +567,7 @@ hildon_note_new_confirmation_add_buttons        (GtkWindow *parent,
     va_list args;
     char *message;
     int value;
+    GtkWidget *button;
 
     g_return_val_if_fail (description != NULL, NULL);
 
@@ -554,7 +575,6 @@ hildon_note_new_confirmation_add_buttons        (GtkWindow *parent,
         g_object_new (HILDON_TYPE_NOTE,
                 "note-type", HILDON_NOTE_TYPE_CONFIRMATION_BUTTON,
                 "description", description,
-                "icon", HILDON_NOTE_CONFIRMATION_ICON, 
                 NULL);
 
     if (parent != NULL)
@@ -571,7 +591,13 @@ hildon_note_new_confirmation_add_buttons        (GtkWindow *parent,
         }
         value = va_arg (args, int);
 
-        gtk_dialog_add_button (GTK_DIALOG (conf_note), message, value);
+        button = gtk_dialog_add_button (GTK_DIALOG (conf_note), message, value);
+        /* maemo-gtk is going to set the "no-show-all" property all
+           cancel/close-like buttons to TRUE, so that they are not shown. On
+           the other hand, this confirmation note with custom buttons should
+           not obey this rule, so we need to make sure they are shown. */
+        gtk_widget_show (button);
+        gtk_widget_set_no_show_all (button, FALSE);
     }
 
     va_end (args);
@@ -588,9 +614,9 @@ hildon_note_new_confirmation_add_buttons        (GtkWindow *parent,
  *   correctly. In GTK the X window ID can be checked using
  *   GDK_WINDOW_XID(GTK_WIDGET(parent)->window).
  * @description: the message to confirm
- * 
- * Create a new confirmation note. Confirmation note has text (description)
- * that you specify, two buttons and a default confirmation stock icon.
+ *
+ * Create a new confirmation note. Confirmation note has a text (description)
+ * that you specify and two buttons.
  *
  * Returns: a #GtkWidget pointer of the note
  */
@@ -598,8 +624,19 @@ GtkWidget*
 hildon_note_new_confirmation                    (GtkWindow *parent,
                                                  const gchar *description)
 {
-    return hildon_note_new_confirmation_with_icon_name
-        (parent, description, HILDON_NOTE_CONFIRMATION_ICON);
+    GtkWidget *dialog = NULL;
+
+    g_return_val_if_fail (description != NULL, NULL);
+
+    dialog = g_object_new (HILDON_TYPE_NOTE,
+            "note-type",
+            HILDON_NOTE_TYPE_CONFIRMATION,
+            "description", description, NULL);
+
+    if (parent != NULL)
+        gtk_window_set_transient_for (GTK_WINDOW (dialog), parent);
+
+    return dialog;
 }
 
 /**
@@ -612,8 +649,11 @@ hildon_note_new_confirmation                    (GtkWindow *parent,
  * @description: the message to confirm
  * @icon_name: icon to be displayed. If NULL, default icon is used.
  * 
- * Create a new confirmation note. Confirmation note has text(description) 
- * that you specify, two buttons and an icon.
+ * Create a new confirmation note. Confirmation note has a text (description) 
+ * that you specify and two buttons.
+ *
+ * Deprecated: Since 2.2, icons are not shown in confirmation notes. Icons set
+ * with this function will be ignored. Use hildon_note_new_confirmation() instead.
  *
  * Returns: a #GtkWidget pointer of the note
  */
@@ -622,20 +662,7 @@ hildon_note_new_confirmation_with_icon_name     (GtkWindow *parent,
                                                  const gchar *description,
                                                  const gchar *icon_name)
 {
-    GtkWidget *dialog = NULL;
-
-    g_return_val_if_fail (description != NULL, NULL);
-
-    dialog = g_object_new (HILDON_TYPE_NOTE,
-            "note-type",
-            HILDON_NOTE_TYPE_CONFIRMATION,
-            "description", description, "icon",
-            icon_name, NULL);
-
-    if (parent != NULL)
-        gtk_window_set_transient_for (GTK_WINDOW (dialog), parent);
-
-    return dialog;
+  return hildon_note_new_confirmation (parent, description);
 }
 
 /**
@@ -647,8 +674,8 @@ hildon_note_new_confirmation_with_icon_name     (GtkWindow *parent,
  *   GDK_WINDOW_XID(GTK_WIDGET(parent)->window).
  * @description: the message to confirm
  * 
- * Create a new information note. Information note has a text(description) 
- * that you specify, an OK button and an icon.
+ * Create a new information note. Information note has a text (description)
+ * that you specify and an OK button.
  * 
  * Returns: a #GtkWidget pointer of the note
  */
@@ -656,8 +683,19 @@ GtkWidget*
 hildon_note_new_information                     (GtkWindow *parent,
                                                  const gchar *description)
 {
-    return hildon_note_new_information_with_icon_name
-        (parent, description, HILDON_NOTE_INFORMATION_ICON);
+    GtkWidget *dialog = NULL;
+
+    g_return_val_if_fail (description != NULL, NULL);
+
+    dialog = g_object_new (HILDON_TYPE_NOTE,
+            "note-type",
+            HILDON_NOTE_TYPE_INFORMATION_THEME,
+            "description", description, NULL);
+
+    if (parent != NULL)
+        gtk_window_set_transient_for (GTK_WINDOW (dialog), parent);
+
+    return dialog;
 }
 
 /**
@@ -673,6 +711,9 @@ hildon_note_new_information                     (GtkWindow *parent,
  * Create a new information note. Information note has text(description) 
  * that you specify, an OK button and an icon.
  * 
+ * Deprecated: Since 2.2, icons are not shown in confirmation notes. Icons set
+ * with this function will be ignored. Use hildon_note_new_information() instead.
+ *
  * Returns: a #GtkWidget pointer of the note
  */
 GtkWidget*
@@ -680,21 +721,7 @@ hildon_note_new_information_with_icon_name      (GtkWindow * parent,
                                                  const gchar *description,
                                                  const gchar *icon_name)
 {
-    GtkWidget *dialog = NULL;
-
-    g_return_val_if_fail (description != NULL, NULL);
-    g_return_val_if_fail (icon_name != NULL, NULL);
-
-    dialog = g_object_new (HILDON_TYPE_NOTE,
-            "note-type",
-            HILDON_NOTE_TYPE_INFORMATION_THEME,
-            "description", description,
-            "icon", icon_name, NULL);
-
-    if (parent != NULL)
-        gtk_window_set_transient_for (GTK_WINDOW (dialog), parent);
-
-    return dialog;
+    return hildon_note_new_information (parent, description);
 }
 
 /* FIXME This documentation string LIES! */
@@ -763,7 +790,7 @@ hildon_note_set_button_text                     (HildonNote *note,
     if (priv->okButton) {
         gtk_button_set_label (GTK_BUTTON (priv->okButton), text);
         gtk_button_set_label (GTK_BUTTON (priv->cancelButton),
-                _("ecdg_bd_confirmation_note_cancel"));
+                _("wdgt_bd_no"));
     } else {
         gtk_button_set_label (GTK_BUTTON (priv->cancelButton), text);
     }