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     // create a notification object with the given title and message (the
  34     // latter may be empty in which case only the title will be shown)
  35     wxNotificationMessageBase(const wxString& title,
  36                               const wxString& message = wxString(),
  37                               wxWindow *parent = NULL)
  38         : m_title(title),
  39           m_message(message),
  40           m_parent(parent)
  41     {
  42     }
  43
  44     // note that the setters must be called before Show()
  45
  46     // set the title: short string, markup not allowed
  47     void SetTitle(const wxString& title) { m_title = title; }
  48
  49     // set the text of the message: this is a longer string than the title and
  50     // some platforms allow simple HTML-like markup in it
  51     void SetMessage(const wxString& message) { m_message = message; }
  52
  53     // set the parent for this notification: we'll be associated with the top
  54     // level parent of this window or, if this method is not called, with the
  55     // main application window by default
  56     void SetParent(wxWindow *parent) { m_parent = parent; }
  57
  58
  59     // showing and hiding
  60     // ------------------
  61
  62     // possible values for Show() timeout
  63     enum
  64     {
  65         Timeout_Auto = -1,  // notification will be hidden automatically
  66         Timeout_Never = 0   // notification will never time out
  67     };
  68
  69     // show the notification to the user and hides it after timeout seconds
  70     // pass (special values Timeout_Auto and Timeout_Never can be used)
  71     //
  72     // returns false if an error occurred
  73     virtual bool Show(int timeout = Timeout_Auto) = 0;
  74
  75     // hide the notification, returns true if it was hidden or false if it
  76     // couldn't be done (e.g. on some systems automatically hidden
  77     // notifications can't be hidden manually)
  78     virtual bool Close() = 0;
  79
  80 protected:
  81     // accessors for the derived classes
  82     const wxString& GetTitle() const { return m_title; }
  83     const wxString& GetMessage() const { return m_message; }
  84     wxWindow *GetParent() const { return m_parent; }
  85
  86     // return the concatenation of title and message separated by a new line,
  87     // this is suitable for simple implementation which have no support for
  88     // separate title and message parts of the notification
  89     wxString GetFullMessage() const
  90     {
  91         wxString text(m_title);
  92         if ( !m_message.empty() )
  93         {
  94             text << "\n\n" << m_message;
  95         }
  96
  97         return text;
  98     }
  99
 100 private:
 101     wxString m_title,
 102              m_message;
 103
 104     wxWindow *m_parent;
 105
 106     DECLARE_NO_COPY_CLASS(wxNotificationMessageBase)
 107 };
 108
 109 #define wxUSE_GENERIC_NOTIFICATION_MESSAGE 1
 110
 111 #if defined(__WXGTK__) && wxUSE_LIBHILDON
 112     // we always use the native implementation in Hildon while the other ports
 113     // will fall back to the generic one even if they have a native version too
 114     #undef wxUSE_GENERIC_NOTIFICATION_MESSAGE
 115     #define wxUSE_GENERIC_NOTIFICATION_MESSAGE 0
 116
 117     #include "wx/gtk/hildon/notifmsg.h"
 118 /*
 119     TODO: provide support for
 120         - libnotify (Gnome)
 121         - Snarl (http://www.fullphat.net/, Win32)
 122         - Growl (http://growl.info/, OS X)
 123  */
 124 #else
 125     #include "wx/generic/notifmsg.h"
 126 #endif
 127
 128 #endif // wxUSE_NOTIFICATION_MESSAGE
 129
 130 #endif // _WX_NOTIFMSG_H_
 131