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