| 1 | ///////////////////////////////////////////////////////////////////////////// |
| 2 | // Name: tipdlg.h |
| 3 | // Purpose: interface of wxTipProvider |
| 4 | // Author: wxWidgets team |
| 5 | // RCS-ID: $Id$ |
| 6 | // Licence: wxWindows licence |
| 7 | ///////////////////////////////////////////////////////////////////////////// |
| 8 | |
| 9 | /** |
| 10 | @class wxTipProvider |
| 11 | |
| 12 | This is the class used together with wxShowTip() function. |
| 13 | It must implement wxTipProvider::GetTip function and return the |
| 14 | current tip from it (different tip each time it is called). |
| 15 | |
| 16 | You will never use this class yourself, but you need it to show startup tips |
| 17 | with wxShowTip. Also, if you want to get the tips text from elsewhere than a |
| 18 | simple text file, you will want to derive a new class from wxTipProvider and |
| 19 | use it instead of the one returned by wxCreateFileTipProvider(). |
| 20 | |
| 21 | @library{wxadv} |
| 22 | @category{misc} |
| 23 | |
| 24 | @see @ref overview_tips, ::wxShowTip |
| 25 | */ |
| 26 | class wxTipProvider |
| 27 | { |
| 28 | public: |
| 29 | /** |
| 30 | Constructor. |
| 31 | |
| 32 | @param currentTip |
| 33 | The starting tip index. |
| 34 | */ |
| 35 | wxTipProvider(size_t currentTip); |
| 36 | |
| 37 | /** |
| 38 | Returns the index of the current tip (i.e. the one which would be returned by GetTip()). |
| 39 | |
| 40 | The program usually remembers the value returned by this function after calling |
| 41 | wxShowTip(). Note that it is not the same as the value which was passed to |
| 42 | wxShowTip + 1 because the user might have pressed the "Next" button in |
| 43 | the tip dialog. |
| 44 | */ |
| 45 | size_t GetCurrentTip() const; |
| 46 | |
| 47 | /** |
| 48 | Return the text of the current tip and pass to the next one. |
| 49 | This function is pure virtual, it should be implemented in the derived classes. |
| 50 | */ |
| 51 | virtual wxString GetTip() = 0; |
| 52 | |
| 53 | /** |
| 54 | Returns a modified tip. |
| 55 | |
| 56 | This function will be called immediately after read, and before being check |
| 57 | whether it is a comment, an empty string or a string to translate. |
| 58 | You can optionally override this in your custom user-derived class |
| 59 | to optionally to modify the tip as soon as it is read. You can return any |
| 60 | modification to the string. If you return wxEmptyString, then this tip is |
| 61 | skipped, and the next one is read. |
| 62 | */ |
| 63 | virtual wxString PreProcessTip(const wxString& tip); |
| 64 | }; |
| 65 | |
| 66 | |
| 67 | |
| 68 | // ============================================================================ |
| 69 | // Global functions/macros |
| 70 | // ============================================================================ |
| 71 | |
| 72 | /** @addtogroup group_funcmacro_dialog */ |
| 73 | //@{ |
| 74 | |
| 75 | /** |
| 76 | This function creates a wxTipProvider which may be used with wxShowTip(). |
| 77 | |
| 78 | @param filename |
| 79 | The name of the file containing the tips, one per line. |
| 80 | @param currentTip |
| 81 | The index of the first tip to show. Normally this index is remembered |
| 82 | between the 2 program runs. |
| 83 | |
| 84 | @see @ref overview_tips |
| 85 | |
| 86 | @header{wx/tipdlg.h} |
| 87 | */ |
| 88 | wxTipProvider* wxCreateFileTipProvider(const wxString& filename, |
| 89 | size_t currentTip); |
| 90 | |
| 91 | /** |
| 92 | This function shows a "startup tip" to the user. The return value is the |
| 93 | state of the "Show tips at startup" checkbox. |
| 94 | |
| 95 | @param parent |
| 96 | The parent window for the modal dialog. |
| 97 | @param tipProvider |
| 98 | An object which is used to get the text of the tips. It may be created |
| 99 | with the wxCreateFileTipProvider() function. |
| 100 | @param showAtStartup |
| 101 | Should be true if startup tips are shown, false otherwise. This is |
| 102 | used as the initial value for "Show tips at startup" checkbox which is |
| 103 | shown in the tips dialog. |
| 104 | |
| 105 | @see @ref overview_tips |
| 106 | |
| 107 | @header{wx/tipdlg.h} |
| 108 | */ |
| 109 | bool wxShowTip(wxWindow *parent, |
| 110 | wxTipProvider *tipProvider, |
| 111 | bool showAtStartup = true); |
| 112 | |
| 113 | //@} |
| 114 | |