interface/wx/notifmsg.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        notifmsg.h
   3 // Purpose:     interface of wxNotificationMessage
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxNotificationMessage
  11
  12     This class allows to show the user a message non intrusively.
  13
  14     Currently it is implemented natively only for the Maemo platform and uses
  15     (non-modal) dialogs for the display of the notifications under the other
  16     platforms but it will be extended to use the platform-specific notifications
  17     in the other ports in the future.
  18
  19     Notice that this class is not a window and so doesn't derive from wxWindow.
  20
  21     @library{wxadv}
  22     @category{misc}
  23 */
  24 class wxNotificationMessage : public wxEvtHandler
  25 {
  26 public:
  27     /// Possible values for Show() timeout.
  28     enum
  29     {
  30         Timeout_Auto = -1,  ///< Notification will be hidden automatically.
  31         Timeout_Never = 0   ///< Notification will never time out.
  32     };
  33
  34     /**
  35         Default constructor, use SetParent(), SetTitle() and SetMessage() to
  36         initialize the object before showing it.
  37     */
  38     wxNotificationMessage();
  39
  40     /**
  41         Create a notification object with the given attributes.
  42
  43         See SetTitle(), SetMessage(), SetParent() and SetFlags() for the
  44         description of the corresponding parameters.
  45     */
  46     wxNotificationMessage(const wxString& title, const wxString& message = wxEmptyString,
  47                           wxWindow* parent = NULL, int flags = wxICON_INFORMATION);
  48
  49     /**
  50         Hides the notification.
  51
  52         Returns @true if it was hidden or @false if it couldn't be done
  53         (e.g. on some systems automatically hidden notifications can't be
  54         hidden manually).
  55     */
  56     virtual bool Close();
  57
  58     /**
  59         This parameter can be currently used to specify the icon to show in the
  60         notification.
  61
  62         Valid values are @c wxICON_INFORMATION, @c wxICON_WARNING and
  63         @c wxICON_ERROR (notice that @c wxICON_QUESTION is not allowed here).
  64         Some implementations of this class may not support the icons.
  65     */
  66     void SetFlags(int flags);
  67
  68     /**
  69         Set the main text of the notification.
  70
  71         This should be a more detailed description than the title but still limited
  72         to reasonable length (not more than 256 characters).
  73     */
  74     void SetMessage(const wxString& message);
  75
  76     /**
  77         Set the parent for this notification: the notification will be associated with
  78         the top level parent of this window or, if this method is not called, with the
  79         main application window by default.
  80     */
  81     void SetParent(wxWindow* parent);
  82
  83     /**
  84         Set the title, it must be a concise string (not more than 64 characters), use
  85         SetMessage() to give the user more details.
  86     */
  87     void SetTitle(const wxString& title);
  88
  89     /**
  90         Show the notification to the user and hides it after @a timeout seconds
  91         are elapsed.
  92
  93         Special values @c Timeout_Auto and @c Timeout_Never can be used here,
  94         notice that you shouldn't rely on @a timeout being exactly respected
  95         because the current platform may only support default timeout value
  96         and also because the user may be able to close the notification.
  97
  98         @return @false if an error occurred.
  99     */
 100     virtual bool Show(int timeout = Timeout_Auto);
 101 };
 102