ui/message_center/message_center.h

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef UI_MESSAGE_CENTER_MESSAGE_CENTER_H_
   6 #define UI_MESSAGE_CENTER_MESSAGE_CENTER_H_
   7
   8 #include <string>
   9
  10 #include "base/memory/scoped_ptr.h"
  11 #include "ui/message_center/message_center_export.h"
  12 #include "ui/message_center/message_center_types.h"
  13 #include "ui/message_center/notification_list.h"
  14
  15 class DownloadNotification;
  16
  17 namespace base {
  18 class DictionaryValue;
  19 }
  20
  21 // Interface to manage the NotificationList. The client (e.g. Chrome) calls
  22 // [Add|Remove|Update]Notification to create and update notifications in the
  23 // list. It also sends those changes to its observers when a notification
  24 // is shown, closed, or clicked on.
  25 //
  26 // MessageCenter is agnostic of profiles; it uses the string returned by
  27 // message_center::Notification::id() to uniquely identify a notification. It is
  28 // the caller's responsibility to formulate the id so that 2 different
  29 // notification should have different ids. For example, if the caller supports
  30 // multiple profiles, then caller should encode both profile characteristics and
  31 // notification front end's notification id into a new id and set it into the
  32 // notification instance before passing that in. Consequently the id passed to
  33 // observers will be this unique id, which can be used with MessageCenter
  34 // interface but probably not higher level interfaces.
  35
  36 namespace message_center {
  37
  38 namespace test {
  39 class MessagePopupCollectionTest;
  40 }
  41
  42 class MessageCenterObserver;
  43 class MessageCenterImplTest;
  44 class NotificationBlocker;
  45 class NotifierSettingsProvider;
  46
  47 class MESSAGE_CENTER_EXPORT MessageCenter {
  48  public:
  49   // Creates the global message center object.
  50   static void Initialize();
  51
  52   // Returns the global message center object. Returns NULL if Initialize is not
  53   // called.
  54   static MessageCenter* Get();
  55
  56   // Destroys the global message_center object.
  57   static void Shutdown();
  58
  59   // Management of the observer list.
  60   virtual void AddObserver(MessageCenterObserver* observer) = 0;
  61   virtual void RemoveObserver(MessageCenterObserver* observer) = 0;
  62
  63   // Queries of current notification list status.
  64   virtual size_t NotificationCount() const = 0;
  65   virtual size_t UnreadNotificationCount() const = 0;
  66   virtual bool HasPopupNotifications() const = 0;
  67   virtual bool IsQuietMode() const = 0;
  68   virtual bool HasClickedListener(const std::string& id) = 0;
  69
  70   // Find the notification with the corresponding id. Returns NULL if not found.
  71   // The returned instance is owned by the message center.
  72   virtual message_center::Notification* FindVisibleNotificationById(
  73       const std::string& id) = 0;
  74
  75   // Gets all notifications to be shown to the user in the message center.  Note
  76   // that queued changes due to the message center being open are not reflected
  77   // in this list.
  78   virtual const NotificationList::Notifications& GetVisibleNotifications() = 0;
  79
  80   // Gets all notifications being shown as popups.  This should not be affected
  81   // by the change queue since notifications are not held up while the state is
  82   // VISIBILITY_TRANSIENT or VISIBILITY_SETTINGS.
  83   virtual NotificationList::PopupNotifications GetPopupNotifications() = 0;
  84
  85   // Management of NotificationBlockers.
  86   virtual void AddNotificationBlocker(NotificationBlocker* blocker) = 0;
  87   virtual void RemoveNotificationBlocker(NotificationBlocker* blocker) = 0;
  88
  89   // Basic operations of notification: add/remove/update.
  90
  91   // Adds a new notification.
  92   virtual void AddNotification(scoped_ptr<Notification> notification) = 0;
  93
  94   // Updates an existing notification with id = old_id and set its id to new_id.
  95   virtual void UpdateNotification(
  96       const std::string& old_id,
  97       scoped_ptr<Notification> new_notification) = 0;
  98
  99   // Removes an existing notification.
 100   virtual void RemoveNotification(const std::string& id, bool by_user) = 0;
 101   virtual void RemoveAllNotifications(bool by_user) = 0;
 102   virtual void RemoveAllVisibleNotifications(bool by_user) = 0;
 103
 104   // Sets the icon image. Icon appears at the top-left of the notification.
 105   virtual void SetNotificationIcon(const std::string& notification_id,
 106                                    const gfx::Image& image) = 0;
 107
 108   // Sets the large image for the notifications of type == TYPE_IMAGE. Specified
 109   // image will appear below of the notification.
 110   virtual void SetNotificationImage(const std::string& notification_id,
 111                                     const gfx::Image& image) = 0;
 112
 113   // Sets the image for the icon of the specific action button.
 114   virtual void SetNotificationButtonIcon(const std::string& notification_id,
 115                                          int button_index,
 116                                          const gfx::Image& image) = 0;
 117
 118   // Operations happening especially from GUIs: click, disable, and settings.
 119   // Searches through the notifications and disables any that match the
 120   // extension id given.
 121   virtual void DisableNotificationsByNotifier(
 122       const NotifierId& notifier_id) = 0;
 123
 124   // This should be called by UI classes when a notification is clicked to
 125   // trigger the notification's delegate callback and also update the message
 126   // center observers.
 127   virtual void ClickOnNotification(const std::string& id) = 0;
 128
 129   // This should be called by UI classes when a notification button is clicked
 130   // to trigger the notification's delegate callback and also update the message
 131   // center observers.
 132   virtual void ClickOnNotificationButton(const std::string& id,
 133                                          int button_index) = 0;
 134
 135   // This should be called by UI classes after a visible notification popup
 136   // closes, indicating that the notification has been shown to the user.
 137   // |mark_notification_as_read|, if false, will unset the read bit on a
 138   // notification, increasing the unread count of the center.
 139   virtual void MarkSinglePopupAsShown(const std::string& id,
 140                                       bool mark_notification_as_read) = 0;
 141
 142   // This should be called by UI classes when a notification is first displayed
 143   // to the user, in order to decrement the unread_count for the tray, and to
 144   // notify observers that the notification is visible.
 145   virtual void DisplayedNotification(
 146       const std::string& id,
 147       const DisplaySource source) = 0;
 148
 149   // Setter/getter of notifier settings provider. This will be a weak reference.
 150   // This should be set at the initialization process. The getter may return
 151   // NULL for tests.
 152   virtual void SetNotifierSettingsProvider(
 153       NotifierSettingsProvider* provider) = 0;
 154   virtual NotifierSettingsProvider* GetNotifierSettingsProvider() = 0;
 155
 156   // This can be called to change the quiet mode state (without a timeout).
 157   virtual void SetQuietMode(bool in_quiet_mode) = 0;
 158
 159   // Temporarily enables quiet mode for |expires_in| time.
 160   virtual void EnterQuietModeWithExpire(const base::TimeDelta& expires_in) = 0;
 161
 162   // Informs the notification list whether the message center is visible.
 163   // This affects whether or not a message has been "read".
 164   virtual void SetVisibility(Visibility visible) = 0;
 165
 166   // Allows querying the visibility of the center.
 167   virtual bool IsMessageCenterVisible() const = 0;
 168
 169   // UI classes should call this when there is cause to leave popups visible for
 170   // longer than the default (for example, when the mouse hovers over a popup).
 171   virtual void PausePopupTimers() = 0;
 172
 173   // UI classes should call this when the popup timers should restart (for
 174   // example, after the mouse leaves the popup.)
 175   virtual void RestartPopupTimers() = 0;
 176
 177  protected:
 178   friend class ::DownloadNotification;
 179   friend class MessageCenterImplTest;
 180   friend class TrayViewControllerTest;
 181   friend class test::MessagePopupCollectionTest;
 182   virtual void DisableTimersForTest() = 0;
 183
 184   MessageCenter();
 185   virtual ~MessageCenter();
 186
 187  private:
 188   // Forces to flush the queued changes even when the message center opens. This
 189   // method is a workaround of UpdateNotification not updating notifications
 190   // while the message center.
 191   // Note carefully: this may break the layout of message center. Shouldn't use
 192   // this method if the update changes its notification size.
 193   virtual void ForceNotificationFlush(const std::string& id) {}
 194
 195   DISALLOW_COPY_AND_ASSIGN(MessageCenter);
 196 };
 197
 198 }  // namespace message_center
 199
 200 #endif  // UI_MESSAGE_CENTER_MESSAGE_CENTER_H_