mirror of
https://github.com/wxWidgets/Phoenix.git
synced 2025-07-21 12:41:10 +02:00
936d722cd8
⁉️ Not sure if the generated *.rst stuff is intended to have
whitespace or not, so seperating this from the other commits, so easy to
revert if necessary.
75 lines
3.0 KiB
ReStructuredText
75 lines
3.0 KiB
ReStructuredText
.. include:: headings.inc
|
|
|
|
|
|
.. _tipprovider overview:
|
|
|
|
==========================================
|
|
|phoenix_title| **TipProvider Overview**
|
|
==========================================
|
|
|
|
Many "modern" Windows programs have a feature (some would say
|
|
annoyance) of presenting the user tips at program startup.
|
|
|
|
While this is probably useless to the advanced users of the program,
|
|
the experience shows that the tips may be quite helpful for the
|
|
novices and so more and more programs now do this. For a wxPython
|
|
programmer, implementing this feature is extremely easy. To show a
|
|
tip, it is enough to just call :func:`wx.ShowTip` function like this::
|
|
|
|
if showTipsAtStartup:
|
|
|
|
tipProvider = wx.CreateFileTipProvider("tips.txt", 0)
|
|
wx.ShowTip(windowParent, tipProvider)
|
|
del tipProvider
|
|
|
|
|
|
Of course, you need to get the text of the tips from somewhere - in
|
|
the example above, the text is supposed to be in the file `tips.txt`
|
|
from where it is read by the tip provider. The tip provider is just an
|
|
object of a class deriving from :class:`~wx.adv.TipProvider`. It has
|
|
to implement one pure virtual function of the base class, `GetTip`. In
|
|
the case of the tip provider created by
|
|
:func:`wx.CreateFileTipProvider`, the tips are just the lines of the
|
|
text file.
|
|
|
|
If you want to implement your own tip provider (for example, if you
|
|
wish to hardcode the tips inside your program), you just have to
|
|
derive another class from :class:`~wx.adv.TipProvider` and pass a
|
|
pointer to the object of this class to func:`wx.ShowTip` - then you
|
|
don't need :func:`wx.CreateFileTipProvider` at all.
|
|
|
|
You will probably want to save somewhere the index of the tip last
|
|
shown - so that the program doesn't always show the same tip on
|
|
startup. As you also need to remember whether to show tips or not (you
|
|
shouldn't do it if the user unchecked "Show tips on startup" checkbox
|
|
in the dialog), you will probably want to store both the index of the
|
|
last shown tip (as returned by
|
|
:meth:`~wx.adv.TipProvider.GetCurrentTip` and the flag telling whether
|
|
to show the tips at startup at all.
|
|
|
|
In a `tips.txt` file, lines that begin with a ``#`` character are
|
|
considered comments and are automatically skipped. Blank lines and
|
|
lines only having spaces are also skipped.
|
|
|
|
You can easily add runtime-translation capacity by placing each line
|
|
of the `tips.txt` file inside the usual translation function. For
|
|
example, your `tips.txt` file would look like this::
|
|
|
|
_("This is my first tip")
|
|
_("This is my second tip")
|
|
|
|
|
|
Now add your `tips.txt` file into the list of files that gettext
|
|
searches for translatable strings. The tips will thus get included
|
|
into your generated .po file catalog and be translated at runtime
|
|
along with the rest of your application's translatable strings.
|
|
|
|
.. note::
|
|
|
|
Each line in the `tips.txt` file needs to strictly begin with
|
|
exactly the 3 characters of underscore-parenthesis-doublequote, and
|
|
end with doublequote-parenthesis, as shown above. Also, remember to
|
|
escape any doublequote characters within the tip string with a
|
|
backslash-doublequote.
|
|
|