interface/notifmsg.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        notifmsg.h
   3 // Purpose:     documentation for wxNotificationMessage class
   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
  31         Create a notification object with the given attributes.
  32
  33         See SetTitle(),
  34         SetMessage(),
  35         SetParent() and
  36         SetFlags() for the description of the
  37         corresponding parameters.
  38     */
  39     wxNotificationMessage();
  40     wxNotificationMessage(const wxString& title);
  41     //@}
  42
  43     /**
  44         Hides the notification.
  45
  46         Returns @true if it was hidden or @false if it couldn't be done (e.g. on
  47         some
  48         systems automatically hidden notifications can't be hidden manually)
  49     */
  50     bool Close();
  51
  52     /**
  53         This parameter can be currently used to specify the icon to show in the
  54         notification. Valid values are @c wxICON_INFORMATION,
  55         @c wxICON_WARNING and @c wxICON_ERROR (notice that
  56         @c wxICON_QUESTION is not allowed here).
  57
  58         Some implementations of this class may not support the icons.
  59     */
  60     void SetFlags(int flags);
  61
  62     /**
  63         Set the main text of the notification. This should be a more detailed
  64         description than the title but still limited to reasonable length (not more
  65         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
  79         details.
  80     */
  81     void SetTitle(const wxString& title);
  82
  83     /**
  84         Show the notification to the user and hides it after timeout seconds
  85         pass. Special values @c Timeout_Auto and @c Timeout_Never can be
  86         used here, notice that you shouldn't rely on @e timeout being exactly
  87         respected because the current platform may only support default timeout value
  88         and also because the user may be able to close the notification.
  89
  90         Returns @false if an error occurred.
  91     */
  92     bool Show(int timeout = Timeout_Auto);
  93 };