]> git.saurik.com Git - wxWidgets.git/blame_incremental - docs/doxygen/overviews/tips.h
extracted the part of ProcessEvent() which is repeated multiple times during the...
[wxWidgets.git] / docs / doxygen / overviews / tips.h
... / ...
CommitLineData
1/////////////////////////////////////////////////////////////////////////////
2// Name: tips.h
3// Purpose: topic overview
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows license
7/////////////////////////////////////////////////////////////////////////////
8
9/**
10
11@page overview_tips wxTipProvider Overview
12
13Many "modern" Windows programs have a feature (some would say annoyance) of
14presenting the user tips at program startup. While this is probably useless to
15the advanced users of the program, the experience shows that the tips may be
16quite helpful for the novices and so more and more programs now do this. For a
17wxWidgets programmer, implementing this feature is extremely easy. To show a
18tip, it is enough to just call wxShowTip function like this:
19
20@code
21if ( ...show tips at startup?... )
22{
23 wxTipProvider *tipProvider = wxCreateFileTipProvider("tips.txt", 0);
24 wxShowTip(windowParent, tipProvider);
25 delete tipProvider;
26}
27@endcode
28
29Of course, you need to get the text of the tips from somewhere - in the example
30above, the text is supposed to be in the file tips.txt from where it is read by
31the <em>tip provider</em>. The tip provider is just an object of a class
32deriving from wxTipProvider. It has to implement one pure virtual function of
33the base class: GetTip. In the case of the tip provider created by
34wxCreateFileTipProvider, the tips are just the lines of the text file.
35
36If you want to implement your own tip provider (for example, if you wish to
37hardcode the tips inside your program), you just have to derive another class
38from wxTipProvider and pass a pointer to the object of this class to
39wxShowTip - then you don't need wxCreateFileTipProvider at all.
40
41You will probably want to save somewhere the index of the tip last shown - so
42that the program doesn't always show the same tip on startup. As you also need
43to remember whether to show tips or not (you shouldn't do it if the user
44unchecked "Show tips on startup" checkbox in the dialog), you will probably
45want to store both the index of the last shown tip (as returned by
46wxTipProvider::GetCurrentTip and the flag telling whether to show the tips at
47startup at all.
48
49In a tips.txt file, lines that begin with a # character are considered comments
50and are automatically skipped. Blank lines and lines only having spaces are
51also skipped.
52
53You can easily add runtime-translation capacity by placing each line of the
54tips.txt file inside the usual translation macro. For example, your tips.txt
55file would look like this:
56
57@code
58_("This is my first tip")
59_("This is my second tip")
60@endcode
61
62Now add your tips.txt file into the list of files that gettext searches for
63translatable strings. The tips will thus get included into your generated .po
64file catalog and be translated at runtime along with the rest of your
65application's translatable strings.
66
67@note Each line in the tips.txt file needs to strictly begin with exactly the 3
68characters of underscore-parenthesis-doublequote, and end with
69doublequote-parenthesis, as shown above. Also, remember to escape any
70doublequote characters within the tip string with a backslash-doublequote.
71
72See the dialogs program in your samples folder for a working example inside a
73program.
74
75*/
76