Internetpräsenz Peter Lenhard

Navigation:

wxLocalisator: generated dialog to choose a locale in wxWidgets

direct download

file locor_readme.htm

Contents:



What is wxLocalisator?

It is a cpp-class for use with wxWidgets.
It supports the internationalisation of your application.

Internationalisation with the free and portable GUI Toolkit wxWidgets is quite easy because of the locale-concept and the great free tool poedit from Vaclav Slavik.

But your application has to decide which locale to choose. If the system locale (default) is not the right one, this is done via an entry in the configuration of your program (not very user-friendly) or with a dialog to ask the user.

The class wxLocalisator is such a dialog and it provides you additional features:
  • It stores the choosen locale permanently in its own ini-file.
  • It can read the allowed locales/languages from its ini-file.
  • The user can edit the ini-file to provide additional locales
    without recompilation of your code.
  • The ini-file is quite easy to understand.
  • You can customize the style of the dialog.
  • You can show a html-document instead,
    so you have even more control about the layout.
  • Last but not least: You do not have to write this dialog by yourself.

Some pictures of the three styles:

Common Dialog
Generated html
Static html file
Common dialog, modified
Generated html, modified

How do I use wxLocalisator?

You have to add the file locor.cpp to your sources, as this class is not part of the wxWidgets distribution. Include the file locor.h in your main application file, like shown in the demo.

By calling AskUser() the dialog will show up and you get a locale-ID as return-value. The choosen locale will be stored in ./locale/locale.ini, which is the default ini-file of wxLocalisator.
Just set this ID in the global locale-object.
If wxLocalisator can read a valid locale from its ini-file, the dialog will not be shown, unless you call AskUser(true).
(The name of this method is not just ShowModal() because of its side effects.)

Customisation

The method AskUser() provides an additional parameter style to choose from three styles:
  • Common dialog, build from locale.ini (default)
  • Html dialog, generated from locale.ini
  • Show a static html document with special links instead (./locale/locale.htm as default)
The method ItemsShown() lets you choose from three possible layouts:
The corresponding flag for each language is shown or the name of the language or both (default).
The second parameter decides whether the short descriptive text is shown (default) or not.

If you choose the third style, the mode parameter of AskUser() and and a former call of SetStyle() have obviously no effect.
You can change the shown file by calling SetFileHtml().
If you choose the second style and you want the generated html-code to look more fancy, you have to edit the generating code in the method wxLocalisator::BuildHtml().

By default no language is known by the dialog.
Add a language by a call of AddLanguage().
You can also read all languages specified in the ini-file by calling ReadFile(), which simply makes some calls of AddLanguage().

Have a look at the demo i18ner.cpp, which shows the different possibilities.

What about the files locorh.cpp and locorh.h?

There is a light-weight-version of the class, named wxLocalisatorHtml. It resides in these files.
This class can only show up a static html-file, and it does not store anything in an ini-file.
The default file is ./locale/locale.htm, like above, but no ini-file is needed.
You are responsible for storing the locale by yourself.
The method AskUser() now has a wxString as return-value, giving the ascii-code of the locale (like "en_GB" or "de_DE").
Use the method FindId() to translate it to the needed locale-ID.
Have a look at the demo i18ner_h.cpp.

Download

Download the zip-archive with the code of the dialogs, the code of the demos and a VC++ project file.

Legal stuff

This code is a inofficial contribution to wxWidgets and underlies (only) the same small restrictions.
You may use and modificate it freely.

As the author of this code I do not guarantee anything, so do not blame me for any damage it may cause or something else.

Any suggestions are welcome.

Peter Lenhard, January 2003