interface/wx/notifmsg.h

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