docs/doxygen/overviews/tips.h

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