docs/doxygen/overviews/tips.h

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