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