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