From 70373b5a57223350e0fcc4968920f81463dc6125 Mon Sep 17 00:00:00 2001 From: Julian Smart Date: Sat, 31 Aug 2002 12:08:02 +0000 Subject: [PATCH] Applied patch [ 600500 ] Tip-of-day: comments, translatable By Robert O'Connor This is a patch to wxTip Provider classes used by the "Tip of the day" dialog. See wx-dev archives August 2002 for discussion of the functionality design. It does 5 things: -Support for comments inside the tips file. The pound character (#) is used, as recommended by Vadim. -Allows optional easy translation support to tips, by marking them as translatable for gettext, by enclosing them in a _(""). Program will translate these tips at runtime from the active catalog. -Blank lines or lines with just spaces are automatically skipped (I had to put this in, I keep wondering why I get blank tips sometimes and it is because the text file had a empty blank line at the end of the text file). -There is a pluggable virtual function to preprocess to modify the tip in a derived class, in case something specialized is desired, such as variable expansion, etc, as recommended by Julian and Vadim. -Now resets the tip counter if the previous tip is past the end of the file (ie you removed some tips, or changed tip files), as discussed on wx-dev. This patch updates: -The classes. -The class documentation and the Tip-of-the-day topic overview documentation. -The dialogs example, placing some new strings for the tips.txt file which demonstrate how to use the Tip-of-the-day features for in practice. git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@16887 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- docs/latex/wx/tipprov.tex | 13 ++- docs/latex/wx/ttips.tex | 25 ++++- docs/wine/install.txt | 212 ++++++++++++++++++++++---------------- include/wx/tipdlg.h | 7 +- samples/dialogs/tips.txt | 23 ++++- src/generic/tipdlg.cpp | 57 ++++++++-- 6 files changed, 231 insertions(+), 106 deletions(-) diff --git a/docs/latex/wx/tipprov.tex b/docs/latex/wx/tipprov.tex index c824373aab..acee3937d9 100644 --- a/docs/latex/wx/tipprov.tex +++ b/docs/latex/wx/tipprov.tex @@ -38,15 +38,24 @@ Constructor. Return the text of the current tip and pass to the next one. This function is pure virtual, it should be implemented in the derived classes. +\membersection{wxTipProvider::PreprocessTip}\label{wxtipproviderpreprocesstip} +\funct{virtual wxString}{PreProcessTip}{\param{const wxString\&} {tip}} + +Returns a modified tip. This function will be called immediately after read, +and before being check whether it is a comment, an empty string or a string +to translate. You can optionally override this in your custom user-derived class +to optionally to modify the tip as soon as it is read. You can return any +modification to the string. If you return wxEmptyString, then this tip is +skipped, and the next one is read. + \membersection{wxCurrentTipProvider::GetCurrentTip}\label{wxtipprovidergetcurrenttip} \constfunc{size\_t}{GetCurrentTip}{\void} -Returns the index of the current tip (i.e. the one which would be returned by +Returns the index of the current tip (i.e. the one which would be returned by GetTip). The program usually remembers the value returned by this function after calling \helpref{wxShowTip}{wxshowtip}. Note that it is not the same as the value which was passed to wxShowTip $+ 1$ because the user might have pressed the "Next" button in the tip dialog. - diff --git a/docs/latex/wx/ttips.tex b/docs/latex/wx/ttips.tex index e63e6e5303..5dac6dd911 100644 --- a/docs/latex/wx/ttips.tex +++ b/docs/latex/wx/ttips.tex @@ -32,7 +32,7 @@ hardcode the tips inside your program), you just have to derive another class from wxTipProvider and pass a pointer to the object of this class to wxShowTip - then you don't need wxCreateFileTipProvider at all. -Finally, you will probably want to save somewhere the index of the tip last +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 @@ -41,3 +41,26 @@ last shown tip (as returned by \helpref{wxTipProvider::GetCurrentTip}{wxtipprovidergetcurrenttip} 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 macro. For example, your tips.txt +file would look like this: +\begin{verbatim} +_("This is my first tip") +_("This is my second tip") +\end{verbatim} +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 aplication's translatable strings. +Note1: 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. +Note2: Remember to escape any doublequote characters within the tip string with +a backslash-doublequote. + +See the dialogs program in your samples folder for a working example inside a +program. diff --git a/docs/wine/install.txt b/docs/wine/install.txt index b696299648..29fc50154b 100644 --- a/docs/wine/install.txt +++ b/docs/wine/install.txt @@ -10,6 +10,9 @@ Most C++ compilers cannot compile the WINE sources yet (this includes all versions of g++ and egcs) so you have to make a minimal change and recompile all of WINE in order to get anywhere. +(Note: this information may be out of date now. See notes at +the bottom of this file.) + This change has do be applied to the /include/windef.h file, line 59 in the section "Calling convention definitions", where the sources reads: @@ -153,18 +156,18 @@ You can get the newest version of the WINE from the WINE homepage at: ----------------------------- Usage: - ./configure options + ./configure options If you want to use system's C and C++ compiler, set environment variables CC and CCC as - % setenv CC cc - % setenv CCC CC - % ./configure options + % setenv CC cc + % setenv CCC CC + % ./configure options to see all the options please use: - ./configure --help + ./configure --help The basic philosophy is that if you want to use different configurations, like a debug and a release version, @@ -192,52 +195,52 @@ in wxWindows snapshot 6, but not yet all (ODBC not). You must do this by running configure with either of: - --with-wine Use the WINE library - + --with-wine Use the WINE library + The following options handle the kind of library you want to build. - --enable-threads Compile without thread support. Threads - support is also required for the - socket code to work. - - --disable-shared Do not create shared libraries. - - --disable-optimise Do not optimise the code. Can - sometimes be useful for debugging - and is required on some architectures - such as Sun with gcc 2.8.X which - would otherwise produce segvs. - - --enable-profile Add profiling info to the object - files. Currently broken, I think. - - --enable-no_rtti Enable compilation without creation of - C++ RTTI information in object files. - This will speed-up compilation and reduce - binary size. - - --enable-no_exceptions Enable compilation without creation of - C++ exception information in object files. - This will speed-up compilation and reduce - binary size. Also fewer crashes during the - actual compilation... - - --enable-mem_tracing Add built-in memory tracing. - - --enable-dmalloc Use the dmalloc memory debugger. - Read more at www.letters.com/dmalloc/ - - --enable-debug_info Add debug info to object files and - executables for use with debuggers - such as gdb (or its many frontends). - - --enable-debug_flag Define __DEBUG__ and __WXDEBUG__ when - compiling. This enable wxWindows' very - useful internal debugging tricks (such - as automatically reporting illegal calls) - to work. Note that program and library - must be compiled with the same debug - options. + --enable-threads Compile with thread support. Threads + support is also required for the + socket code to work. + + --disable-shared Do not create shared libraries. + + --disable-optimise Do not optimise the code. Can + sometimes be useful for debugging + and is required on some architectures + such as Sun with gcc 2.8.X which + would otherwise produce segvs. + + --enable-profile Add profiling info to the object + files. Currently broken, I think. + + --enable-no_rtti Enable compilation without creation of + C++ RTTI information in object files. + This will speed-up compilation and reduce + binary size. + + --enable-no_exceptions Enable compilation without creation of + C++ exception information in object files. + This will speed-up compilation and reduce + binary size. Also fewer crashes during the + actual compilation... + + --enable-mem_tracing Add built-in memory tracing. + + --enable-dmalloc Use the dmalloc memory debugger. + Read more at www.letters.com/dmalloc/ + + --enable-debug_info Add debug info to object files and + executables for use with debuggers + such as gdb (or its many frontends). + + --enable-debug_flag Define __DEBUG__ and __WXDEBUG__ when + compiling. This enable wxWindows' very + useful internal debugging tricks (such + as automatically reporting illegal calls) + to work. Note that program and library + must be compiled with the same debug + options. * Feature Options ------------------- @@ -251,38 +254,38 @@ drastically reduced by removing features from wxWindows that are not used in your program. The most relevant such features are - --without-libpng Disables PNG image format code. - - --without-libjpeg Disables JPEG image format code. - -{ --without-odbc Disables ODBC code. Not yet. } - - --disable-resources Disables the use of *.wxr type - resources. - - --disable-threads Disables threads. Will also - disable sockets. - - --disable-sockets Disables sockets. - - --disable-dnd Disables Drag'n'Drop. - - --disable-clipboard Disables Clipboard. - - --disable-serial Disables object instance serialisation. - - --disable-streams Disables the wxStream classes. - - --disable-file Disables the wxFile class. - - --disable-textfile Disables the wxTextFile class. - - --disable-intl Disables the internationalisation. - - --disable-validators Disables validators. - - --disable-accel Disables accel. - + --without-libpng Disables PNG image format code. + + --without-libjpeg Disables JPEG image format code. + +{ --without-odbc Disables ODBC code. Not yet. } + + --disable-resources Disables the use of *.wxr type + resources. + + --disable-threads Disables threads. Will also + disable sockets. + + --disable-sockets Disables sockets. + + --disable-dnd Disables Drag'n'Drop. + + --disable-clipboard Disables Clipboard. + + --disable-serial Disables object instance serialisation. + + --disable-streams Disables the wxStream classes. + + --disable-file Disables the wxFile class. + + --disable-textfile Disables the wxTextFile class. + + --disable-intl Disables the internationalisation. + + --disable-validators Disables validators. + + --disable-accel Disables accel. + Apart from disabling certain features you can very often "strip" the program of its debugging information resulting in a significant reduction in size. @@ -296,7 +299,7 @@ or ~/wxWin or whatever) Now the makefiles are created (by configure) and you can compile the library by typing: - make + make make yourself some coffee, as it will take some time. On an old 386SX possibly two weeks. During compilation, you'll get a few @@ -310,16 +313,16 @@ Then you may install the library and its header files under have to log in as root (i.e. run "su" and enter the root password) and type - make install + make install You can remove any traces of wxWindows by typing make uninstall - + If you want to save disk space by removing unnecessary object-files: - make clean + make clean in the various directories will do the work for you. @@ -343,7 +346,7 @@ minimal.o: minimal.cpp mondrian.xpm $(CC) `wx-config --cflags` -c minimal.cpp -o minimal.o clean: - rm -f *.o minimal + rm -f *.o minimal This is certain to become the standard way unless we decide to stick to tmake. @@ -370,5 +373,38 @@ go ahead yourself :-) In the hope that it will be useful, Robert Roebling - - + + +Addition notes by Julian Smart, August 2002 +=========================================== + +I've fixed some compile errors, and got as far as +compiling wxWINE, but actually linking a sample will take +further work. + +To compile wxWINE, export these variables: + +export CPPFLAGS=-I/usr/local/include/wine +export LDFLAGS=-L/usr/local/lib/wine + +and configure with: + +configure --disable-static --enable-shared --enable-gui \ + --with-wine --without-libpng --enable-debug_flag --enable-log \ + --enable-debug_info --enable-ole --enable-clipboard --enable-dataobj \ + --enable-debug --enable-threads --disable-sockets \ + --with-libjpeg --enable-debug_cntxt + +Compiling a sample won't work yet because 'winebuild' needs +to be called, and the resuling C file compiled and linked. +Plus, Windows DLLs need to be imported. + +Note that the documentation on the WINE web site on using +winebuild is out of date (August 2002) -- the spec file no +longer supports import and type keywords. Instead look at +samples in the WINE 'programs' directory for inspiration +and compile options to use. It's probable that the +wxWINE library will need recompiling with different options. + +Any progress on this front will be very welcome. + diff --git a/include/wx/tipdlg.h b/include/wx/tipdlg.h index 594eb151b4..fe7a6be5c4 100644 --- a/include/wx/tipdlg.h +++ b/include/wx/tipdlg.h @@ -43,12 +43,17 @@ public: // get the current tip and update the internal state to return the next tip // when called for the next time - virtual wxString GetTip() = 0; + virtual wxString GetTip() = 0; // get the current tip "index" (or whatever allows the tip provider to know // from where to start the next time) size_t GetCurrentTip() const { return m_currentTip; } + // Allows any user-derived class to optionally override this function to + // modify the tip as soon as it is read. If return wxEmptyString, then + // the tip is skipped, and the next one is read. + virtual wxString PreprocessTip(const wxString& tip) { return tip; } + // virtual dtor for the base class virtual ~wxTipProvider() { } diff --git a/samples/dialogs/tips.txt b/samples/dialogs/tips.txt index 3a019d90e4..fe8a12efc1 100644 --- a/samples/dialogs/tips.txt +++ b/samples/dialogs/tips.txt @@ -1,5 +1,18 @@ -Startup tips are documented in "Startup tips overview" section of wxWindows documentation. -This is the first tip! -And this is another great tip... -And here is a very very very very very very very very very very very long one. -If you have something useful to add to this file, please do. +Startup tips are documented in the "Startup tips overview" section of wxWindows documentation. +These tips are being read from the tips.txt text file in this directory. Each line of the file contains a single tip. +If you close and open this tips dialog, you will notice that the tip numbers start at the point you were at when you closed the dialog last time. This allows easy cycling through the entire list of tips, instead of always showing the initial tips over and over. +Often you will want to save to the application's wxConfig, the last tip that the user saw, as well as whether they want to see tips on startup. +Comments in the tips file have a # as the first character. Comments are automatically skipped over. See the tips.txt file in this directory for the example. +# This line is a comment since it started with a #, and is skipped. +Blank lines in the tip file are also automatically skipped over. Lines with only spaces are also considered empty. +The next line in this tip file is empty, so it will be automatically skipped. + +The next line in this tip file is just empty spaces, so it is considered empty too, and is also automatically skipped. + +You can easily add translations to your startup tips via the usual gettext methods by wrapping a string in a gettext macro, which is _(""). See next tip for example. +_("This tip is marked as a translatable string by wrapping it inside the usual gettext macro, so it can be collected by gettext and added to a translation catalog. Your application can then use this catalog and serve out a translated version of the tip.") +Translatable strings must strictly begin with _(", not _( " or wxGetTranslation(" or something else. +If you are using gettext translatable strings, don't forget to escape to replace any " characters within the tip with a \" instead +_("This is a translatable tip with the quoted words \"Escape me\" properly escaped.") +If you have very specialized needs, you can derive your own wxTipProvider and use that instead. +If you want to modify the tip content at runtime for purposes other than translation (for example, variable expansion), one easy option is to use a custom tip provider derived from wxFileTipProvider. Your custom tip provider would contain a single virtual function to override: PreprocessTip(). diff --git a/src/generic/tipdlg.cpp b/src/generic/tipdlg.cpp index 8a10c41b60..7bd4d9ecc3 100644 --- a/src/generic/tipdlg.cpp +++ b/src/generic/tipdlg.cpp @@ -136,17 +136,56 @@ wxString wxFileTipProvider::GetTip() { size_t count = m_textfile.GetLineCount(); if ( !count ) - return _("Tips not available, sorry!"); - - // notice that it may be greater, actually, if we remembered it from the - // last time and the number of tips changed - if ( m_currentTip == count ) { - // wrap - m_currentTip = 0; + return _("Tips not available, sorry!"); } - - return m_textfile.GetLine(m_currentTip++); + + wxString tip; + + // Comments start with a # symbol. + // Loop reading lines until get the first one that isn't a comment. + // The max number of loop executions is the number of lines in the + // textfile so that can't go into an eternal loop in the [oddball] + // case of a comment-only tips file, or the developer has vetoed + // them all via PreprecessTip(). + for ( size_t i=0; i < count; i++ ) + { + // The current tip may be at the last line of the textfile, (or + // past it, if the number of lines in the textfile changed, such + // as changing to a different textfile, with less tips). So check + // to see at last line of text file, (or past it)... + if ( m_currentTip >= count ) + { + // .. and if so, wrap back to line 0. + m_currentTip = 0; + } + + // Read the tip, and increment the current tip counter. + tip = m_textfile.GetLine(m_currentTip++); + + // Allow a derived class's overrided virtual to modify the tip + // now if so desired. + tip = PreprocessTip(tip); + + // Break if tip isn't a comment, and isn't an empty string + // (or only stray space characters). + if ( !tip.StartsWith(wxT("#")) && (tip.Trim() != wxEmptyString) ) + { + break; + } + } + + // If tip starts with '_(', then it is a gettext string of format + // _("My \"global\" tip text") so first strip off the leading '_("'... + if ( tip.StartsWith(wxT("_(\"" ), &tip)) + { + //...and strip off the trailing '")'... + tip = tip.BeforeLast(wxT('\"')); + // ...and replace escaped quotes + tip.Replace(wxT("\\\""), wxT("\"")); + } + + return tip; } // ---------------------------------------------------------------------------- -- 2.45.2