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