include/wx/tipdlg.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        tipdlg.h
   3 // Purpose:     declaration of wxTipDialog
   4 // Author:      Vadim Zeitlin
   5 // Modified by:
   6 // Created:     28.06.99
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) Vadim Zeitlin
   9 // Licence:     wxWindows licence
  10 ///////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_TIPDLG_H_
  13 #define _WX_TIPDLG_H_
  14
  15 #if defined(__GNUG__) && !defined(NO_GCC_PRAGMA)
  16     #pragma interface "tipdlg.h"
  17 #endif
  18
  19 // ----------------------------------------------------------------------------
  20 // headers which we must include here
  21 // ----------------------------------------------------------------------------
  22
  23 #include "wx/defs.h"
  24
  25 #if wxUSE_STARTUP_TIPS
  26
  27 #include "wx/textfile.h"
  28
  29 // ----------------------------------------------------------------------------
  30 // wxTipProvider - a class which is used by wxTipDialog to get the text of the
  31 // tips
  32 // ----------------------------------------------------------------------------
  33
  34 // the abstract base class: it provides the tips, i.e. implements the GetTip()
  35 // function which returns the new tip each time it's called. To support this,
  36 // wxTipProvider evidently needs some internal state which is the tip "index"
  37 // and which should be saved/restored by the program to not always show one and
  38 // the same tip (of course, you may use random starting position as well...)
  39 class WXDLLIMPEXP_ADV wxTipProvider
  40 {
  41 public:
  42     wxTipProvider(size_t currentTip) { m_currentTip = currentTip; }
  43
  44     // get the current tip and update the internal state to return the next tip
  45     // when called for the next time
  46     virtual wxString GetTip() = 0;
  47
  48     // get the current tip "index" (or whatever allows the tip provider to know
  49     // from where to start the next time)
  50     size_t GetCurrentTip() const { return m_currentTip; }
  51
  52     // Allows any user-derived class to optionally override this function to
  53     // modify the tip as soon as it is read. If return wxEmptyString, then
  54     // the tip is skipped, and the next one is read.
  55     virtual wxString PreprocessTip(const wxString& tip) { return tip; }
  56
  57     // virtual dtor for the base class
  58     virtual ~wxTipProvider() { }
  59
  60 protected:
  61     size_t m_currentTip;
  62 };
  63
  64 // a function which returns an implementation of wxTipProvider using the
  65 // specified text file as the source of tips (each line is a tip).
  66 //
  67 // NB: the caller is responsible for deleting the pointer!
  68 WXDLLIMPEXP_ADV wxTipProvider *wxCreateFileTipProvider(const wxString& filename,
  69                                                        size_t currentTip);
  70
  71 // ----------------------------------------------------------------------------
  72 // wxTipDialog
  73 // ----------------------------------------------------------------------------
  74
  75 // A dialog which shows a "tip" - a short and helpful messages describing to
  76 // the user some program characteristic. Many programs show the tips at
  77 // startup, so the dialog has "Show tips on startup" checkbox which allows to
  78 // the user to disable this (however, it's the program which should show, or
  79 // not, the dialog on startup depending on its value, not this class).
  80 //
  81 // The function returns true if this checkbox is checked, false otherwise.
  82 WXDLLIMPEXP_ADV bool wxShowTip(wxWindow *parent,
  83                                wxTipProvider *tipProvider,
  84                                bool showAtStartup = true);
  85
  86 #endif // wxUSE_STARTUP_TIPS
  87
  88 #endif // _WX_TIPDLG_H_