include/wx/notifmsg.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/notifmsg.h
   3 // Purpose:     class allowing to show notification messages to the user
   4 // Author:      Vadim Zeitlin
   5 // Created:     2007-11-19
   6 // Copyright:   (c) 2007 Vadim Zeitlin <vadim@wxwindows.org>
   7 // Licence:     wxWindows licence
   8 ///////////////////////////////////////////////////////////////////////////////
   9
  10 #ifndef _WX_NOTIFMSG_H_
  11 #define _WX_NOTIFMSG_H_
  12
  13 #include "wx/event.h"
  14
  15 #if wxUSE_NOTIFICATION_MESSAGE
  16
  17 // ----------------------------------------------------------------------------
  18 // wxNotificationMessage: allows to show the user a message non intrusively
  19 // ----------------------------------------------------------------------------
  20
  21 // notice that this class is not a window and so doesn't derive from wxWindow
  22
  23 class WXDLLIMPEXP_ADV wxNotificationMessageBase : public wxEvtHandler
  24 {
  25 public:
  26     // ctors and initializers
  27     // ----------------------
  28
  29     // default ctor, use setters below to initialize it later
  30     wxNotificationMessageBase()
  31     {
  32         m_parent = NULL;
  33         m_flags = wxICON_INFORMATION;
  34     }
  35
  36     // create a notification object with the given title and message (the
  37     // latter may be empty in which case only the title will be shown)
  38     wxNotificationMessageBase(const wxString& title,
  39                               const wxString& message = wxEmptyString,
  40                               wxWindow *parent = NULL,
  41                               int flags = wxICON_INFORMATION)
  42         : m_title(title),
  43           m_message(message),
  44           m_parent(parent)
  45     {
  46         SetFlags(flags);
  47     }
  48
  49     // note that the setters must be called before Show()
  50
  51     // set the title: short string, markup not allowed
  52     void SetTitle(const wxString& title) { m_title = title; }
  53
  54     // set the text of the message: this is a longer string than the title and
  55     // some platforms allow simple HTML-like markup in it
  56     void SetMessage(const wxString& message) { m_message = message; }
  57
  58     // set the parent for this notification: we'll be associated with the top
  59     // level parent of this window or, if this method is not called, with the
  60     // main application window by default
  61     void SetParent(wxWindow *parent) { m_parent = parent; }
  62
  63     // this method can currently be used to choose a standard icon to use: the
  64     // parameter may be one of wxICON_INFORMATION, wxICON_WARNING or
  65     // wxICON_ERROR only (but not wxICON_QUESTION)
  66     void SetFlags(int flags)
  67     {
  68         wxASSERT_MSG( flags == wxICON_INFORMATION ||
  69                         flags == wxICON_WARNING || flags == wxICON_ERROR,
  70                             "Invalid icon flags specified" );
  71
  72         m_flags = flags;
  73     }
  74
  75
  76     // showing and hiding
  77     // ------------------
  78
  79     // possible values for Show() timeout
  80     enum
  81     {
  82         Timeout_Auto = -1,  // notification will be hidden automatically
  83         Timeout_Never = 0   // notification will never time out
  84     };
  85
  86     // show the notification to the user and hides it after timeout seconds
  87     // pass (special values Timeout_Auto and Timeout_Never can be used)
  88     //
  89     // returns false if an error occurred
  90     virtual bool Show(int timeout = Timeout_Auto) = 0;
  91
  92     // hide the notification, returns true if it was hidden or false if it
  93     // couldn't be done (e.g. on some systems automatically hidden
  94     // notifications can't be hidden manually)
  95     virtual bool Close() = 0;
  96
  97 protected:
  98     // accessors for the derived classes
  99     const wxString& GetTitle() const { return m_title; }
 100     const wxString& GetMessage() const { return m_message; }
 101     wxWindow *GetParent() const { return m_parent; }
 102     int GetFlags() const { return m_flags; }
 103
 104     // return the concatenation of title and message separated by a new line,
 105     // this is suitable for simple implementation which have no support for
 106     // separate title and message parts of the notification
 107     wxString GetFullMessage() const
 108     {
 109         wxString text(m_title);
 110         if ( !m_message.empty() )
 111         {
 112             text << "\n\n" << m_message;
 113         }
 114
 115         return text;
 116     }
 117
 118 private:
 119     wxString m_title,
 120              m_message;
 121
 122     wxWindow *m_parent;
 123
 124     int m_flags;
 125
 126     wxDECLARE_NO_COPY_CLASS(wxNotificationMessageBase);
 127 };
 128
 129 /*
 130     TODO: Implement under OS X using notification centre (10.8+) or
 131           Growl (http://growl.info/) for the previous versions.
 132  */
 133 #if defined(__WXGTK__) && wxUSE_LIBNOTIFY
 134     #include "wx/gtk/notifmsg.h"
 135 #elif defined(__WXGTK__) && (wxUSE_LIBHILDON || wxUSE_LIBHILDON2)
 136     #include "wx/gtk/hildon/notifmsg.h"
 137 #elif defined(__WXMSW__) && wxUSE_TASKBARICON && wxUSE_TASKBARICON_BALLOONS
 138     #include "wx/msw/notifmsg.h"
 139 #else
 140     #include "wx/generic/notifmsg.h"
 141
 142     class wxNotificationMessage : public wxGenericNotificationMessage
 143     {
 144     public:
 145         wxNotificationMessage() { }
 146         wxNotificationMessage(const wxString& title,
 147                               const wxString& message = wxEmptyString,
 148                               wxWindow *parent = NULL,
 149                               int flags = wxICON_INFORMATION)
 150             : wxGenericNotificationMessage(title, message, parent, flags)
 151         {
 152         }
 153     };
 154 #endif
 155
 156 #endif // wxUSE_NOTIFICATION_MESSAGE
 157
 158 #endif // _WX_NOTIFMSG_H_
 159