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 license
   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     /**
  28         Default constructor, use SetParent(), SetTitle() and SetMessage() to
  29         initialize the object before showing it.
  30     */
  31     wxNotificationMessage();
  32
  33     /**
  34         Create a notification object with the given attributes.
  35
  36         See SetTitle(), SetMessage(), SetParent() and SetFlags() for the
  37         description of the corresponding parameters.
  38     */
  39     wxNotificationMessage(const wxString& title, const wxString& message = wxEmptyString,
  40                           wxWindow* parent = NULL, int flags = wxICON_INFORMATION);
  41
  42     /**
  43         Hides the notification.
  44
  45         Returns @true if it was hidden or @false if it couldn't be done
  46         (e.g. on some systems automatically hidden notifications can't be
  47         hidden manually).
  48     */
  49     virtual bool Close();
  50
  51     /**
  52         This parameter can be currently used to specify the icon to show in the
  53         notification.
  54
  55         Valid values are @c wxICON_INFORMATION, @c wxICON_WARNING and
  56         @c wxICON_ERROR (notice that @c wxICON_QUESTION is not allowed here).
  57         Some implementations of this class may not support the icons.
  58     */
  59     void SetFlags(int flags);
  60
  61     /**
  62         Set the main text of the notification.
  63
  64         This should be a more detailed description than the title but still limited
  65         to reasonable length (not more than 256 characters).
  66     */
  67     void SetMessage(const wxString& message);
  68
  69     /**
  70         Set the parent for this notification: the notification will be associated with
  71         the top level parent of this window or, if this method is not called, with the
  72         main application window by default.
  73     */
  74     void SetParent(wxWindow* parent);
  75
  76     /**
  77         Set the title, it must be a concise string (not more than 64 characters), use
  78         SetMessage() to give the user more details.
  79     */
  80     void SetTitle(const wxString& title);
  81
  82     /**
  83         Show the notification to the user and hides it after @a timeout seconds
  84         are elapsed.
  85
  86         Special values @c Timeout_Auto and @c Timeout_Never can be used here,
  87         notice that you shouldn't rely on @a timeout being exactly respected
  88         because the current platform may only support default timeout value
  89         and also because the user may be able to close the notification.
  90
  91         @return @false if an error occurred.
  92     */
  93     virtual bool Show(int timeout = Timeout_Auto);
  94 };
  95