Fix usage of 'Since:' keyword in API documentation
[hildon] / src / hildon-note.c
index 023a6c4..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>
+ * <!-- -->
+ * gboolean
+ * show_confirmation_note (GtkWindow *parent)
+ * {
+ *   gint retcode;
+ *   GtkWidget *note;
+ *   note = hildon_note_new_confirmation (parent, "Confirmation message...");
+ * <!-- -->
+ *   retcode = gtk_dialog_run (GTK_DIALOG (note));
+ *   gtk_widget_destroy (note);
+ * <!-- -->
+ *   if (retcode == GTK_RESPONSE_OK) {
+ *        g_debug ("User pressed 'OK' button'");
+ *        return TRUE;
+ *   } else {
+ *        g_debug ("User pressed 'Cancel' button");
+ *        return FALSE;
+ *   }
+ * }
+ * </programlisting>
+ * </example>
  */
 
 #ifdef                                          HAVE_CONFIG_H
 #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 
@@ -110,6 +129,7 @@ enum
 
 static GtkDialogClass*                          parent_class;
 
+
 static void
 hildon_note_set_property                        (GObject *object,
                                                  guint prop_id,
@@ -141,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:
@@ -197,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:
@@ -214,6 +238,13 @@ hildon_note_get_property                        (GObject *object,
     }
 }
 
+/**
+ * hildon_note_get_type:
+ *
+ * Returns GType for HildonNote.
+ *
+ * Returns: HildonNote type
+ */
 GType G_GNUC_CONST
 hildon_note_get_type                            (void)
 {
@@ -256,17 +287,17 @@ hildon_note_class_init                          (HildonNoteClass *class)
 
     g_object_class_install_property (object_class,
             PROP_HILDON_NOTE_TYPE,
-            g_param_spec_enum ("note_type",
+            g_param_spec_enum ("note-type",
                 "note type",
                 "The type of the note dialog",
-                hildon_note_type_get_type(),
-                HILDON_NOTE_CONFIRMATION_TYPE,
+                hildon_note_type_get_type (),
+                HILDON_NOTE_TYPE_CONFIRMATION,
                 G_PARAM_READWRITE | G_PARAM_CONSTRUCT));
 
     /**
      * HildonNote:description:
      *
-     * Description for note.
+     * Description for the note.
      */
     g_object_class_install_property (object_class,
             PROP_HILDON_NOTE_DESCRIPTION,
@@ -279,7 +310,9 @@ hildon_note_class_init                          (HildonNoteClass *class)
     /**
      * HildonNote:icon:
      *
-     * Icon for note.
+     * Icon for the note.
+     *
+     * Deprecated: Since 2.2
      */
     g_object_class_install_property (object_class,
             PROP_HILDON_NOTE_ICON,
@@ -292,7 +325,9 @@ hildon_note_class_init                          (HildonNoteClass *class)
     /**
      * HildonNote:stock-icon:
      *
-     * Stock icon for note.
+     * Stock icon name for the note.
+     *
+     * Deprecated: Since 2.2
      */
     g_object_class_install_property (object_class,
             PROP_HILDON_NOTE_STOCK_ICON,
@@ -305,7 +340,7 @@ hildon_note_class_init                          (HildonNoteClass *class)
     /**
      * HildonNote:progressbar:
      *
-     * Progressbar for note.
+     * Progressbar for the note (if any).
      */
     g_object_class_install_property (object_class,
             PROP_HILDON_NOTE_PROGRESSBAR,
@@ -324,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);
 }
 
 
@@ -353,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);
@@ -365,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);
 
@@ -382,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.
@@ -412,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 */
@@ -432,36 +491,26 @@ hildon_note_rebuild                             (HildonNote *note)
     /* Add needed buttons and images for each note type */
     switch (priv->note_n)
     {
-        case HILDON_NOTE_CONFIRMATION_TYPE:
+        case HILDON_NOTE_TYPE_CONFIRMATION:
             priv->okButton = gtk_dialog_add_button (dialog,
-                    _("ecdg_bd_confirmation_note_ok"), GTK_RESPONSE_OK);
+                    _("wdgt_bd_yes"), GTK_RESPONSE_OK);
             priv->cancelButton = gtk_dialog_add_button (dialog,
-                    _("ecdg_bd_confirmation_note_cancel"), GTK_RESPONSE_CANCEL);
-
-            /* Fall through */
-        case HILDON_NOTE_CONFIRMATION_BUTTON_TYPE:
-            gtk_image_set_from_icon_name (GTK_IMAGE (priv->icon),
-                    HILDON_NOTE_CONFIRMATION_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_INFORMATION_THEME_TYPE:
-        case HILDON_NOTE_INFORMATION_TYPE:
-            /* Add clickable OK button (cancel really,
-               but doesn't matter since this is info) */
+        case HILDON_NOTE_TYPE_PROGRESSBAR:
             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);
-            break;
-
-        case HILDON_NOTE_PROGRESSBAR_TYPE:
-            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;
     }
@@ -471,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 {
@@ -524,14 +567,14 @@ 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);
 
     GtkWidget *conf_note =
         g_object_new (HILDON_TYPE_NOTE,
-                "note_type", HILDON_NOTE_CONFIRMATION_BUTTON_TYPE,
+                "note-type", HILDON_NOTE_TYPE_CONFIRMATION_BUTTON,
                 "description", description,
-                "icon", HILDON_NOTE_CONFIRMATION_ICON, 
                 NULL);
 
     if (parent != NULL)
@@ -548,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);
@@ -565,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
  */
@@ -575,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;
 }
 
 /**
@@ -589,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
  */
@@ -599,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_CONFIRMATION_TYPE,
-            "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);
 }
 
 /**
@@ -624,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
  */
@@ -633,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;
 }
 
 /**
@@ -650,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*
@@ -657,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_INFORMATION_THEME_TYPE,
-            "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! */
@@ -705,8 +755,8 @@ hildon_note_new_cancel_with_progress_bar        (GtkWindow *parent,
     g_return_val_if_fail (description != NULL, NULL);
 
     dialog = g_object_new (HILDON_TYPE_NOTE,
-            "note_type",
-            HILDON_NOTE_PROGRESSBAR_TYPE,
+            "note-type",
+            HILDON_NOTE_TYPE_PROGRESSBAR,
             "description", description,
             "progressbar",
             progressbar, NULL);
@@ -740,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);
     }
@@ -749,8 +799,8 @@ hildon_note_set_button_text                     (HildonNote *note,
 /**
  * hildon_note_set_button_texts:
  * @note: a #HildonNote
- * @textOk: the new text of the default OK button
- * @textCancel: the new text of the default cancel button 
+ * @text_ok: the new text of the default OK button
+ * @text_cancel: the new text of the default cancel button 
  *
  * Sets the button texts to be used by this hildon_note widget.
  */
@@ -789,13 +839,13 @@ sound_handling                                  (GtkWidget *widget,
 
     switch (priv->note_n)
     {
-        case HILDON_NOTE_INFORMATION_TYPE:
-        case HILDON_NOTE_INFORMATION_THEME_TYPE:
+        case HILDON_NOTE_TYPE_INFORMATION:
+        case HILDON_NOTE_TYPE_INFORMATION_THEME:
             hildon_play_system_sound (INFORMATION_SOUND_PATH);
             break;
 
-        case HILDON_NOTE_CONFIRMATION_TYPE:
-        case HILDON_NOTE_CONFIRMATION_BUTTON_TYPE:
+        case HILDON_NOTE_TYPE_CONFIRMATION:
+        case HILDON_NOTE_TYPE_CONFIRMATION_BUTTON:
             hildon_play_system_sound (CONFIRMATION_SOUND_PATH);
             break;