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