1. Introduction

WxExtLib is an open source C++ library with extensions for the wxWidgets cross-platform UI library. It contains control validators for immediate status output, an extended message box class, various helper functions, a few new controls, and more.

The most mature parts of the library (and longest existing) are the StatusValidators (validators for various data types, which allow immediate validation and display of an error message to some dedicated status output control), the MessageExtDialog (allowing for arbitrary named buttons and better support for long message texts and optional HTML mode), and WxMisc (various helper functions).

Some other parts are rather experimental, as wxAppRootFrame, and will work only for some wxWidgets ports as expected.

Other parts may be interesting for general development with C or C++, as the 'safecast' headers, and do not depend on the wxWidgets library. The wxFormatMessage() function is probably interesting by its own, and, unforeseen, now is possibly for me one of the most useful or often used functions I ever wrote.

WxExtLib has been used for a few small and mid-sized projects I was working on. Sometimes, WxExtLib has been specifically extended to fit the needs of these programs. The biggest project that uses WxExtLib currently has around 40 K-SLOC, and runs in a Win32 environment using the wxMSW port.

2. Features

Extended dialog class

• wxExtDialog class eases creating and adding controls
• adaptions to work with a MFC main window (under MSW, requires small modifications to wxWidgets library)
• simple support for dialog zoom
• simplification of control-change notification
• wxWindowAdder
  • simplify handling sizers: maintains a stack of sizers which can be manipulated with push and pop functions
  • simplify creation of labels
  • wxWindowAdderDefaultParameterSet
    • these parameters are used to customize the various functions of wxWindowAdder
• wxNonModalDialogManag
  • provide unified handling for non-modal dialogs
• wxCalendarDialog
  • dialog which contains wxCalendarCtrl and wxTraitedDateTimeValidator to allow input and validation of single wxDateTime value

Type-safe casts: safecast facility

• centralize cast operators in functions, avoid using C casts (or reinterpret_cast<>) directly in the rest of the code
• the purpose of using the case is made explicit by the cast-function name (e.g. cast_round_assign(), cast_approx_assign()), which may improve readability of code using casts

New message box class

• wxMessageExtDialog has support for arbitrary named buttons
• support for automatic line-wrap and use of scrollbars in case of long message texts
• optional HTML mode: it is possible to display HTML messages
• decoration: depending on message type (error, info etc.), display icon (or colour bar) to the right of displayed message

Type-safe printf() replacement

• wxMessageFormatter/wxFormat/wxFormatMessage provide type-safe string formatting similar to printf
• unlike with the C++ stream operator "<<", the format string must not be split up into pieces
• parameters are added with the "%" operator to wxMessageFormatter, alternatively, the overloaded function wxFormatMessage() can be used
• format string refers to parameters with "%N" or "%{N}" (with N being the N-th parameter added) - this makes it possible to reorder parameters in the output, which may be useful when translating the format string to other languages
• "%+" may be used to refer to the "next" parameter
• Example:

   wxString FilenameWxString = ...
   wxString FormattedWxString = wxFormatMessage ("file %2 has length of %1 bytes",
                                                 LengthAsInt, FilenameWxString);
  
   // new std::string flavor:
   std::string FilenameStdString = ... 
   std::string FormattedStdString = stFormatMessage ("file %2 has length of %1 bytes",
                                                     LengthAsInt, FilenameStdString);
  

• Implementation Note:
  • The wxFormatMessage() function uses an intermediate helper class wxFormat in conjunction with multiple overloads for different argument counts of wxFormat arguments. This technique (or trick) is supposed to work with any old C++ compiler -- no C++ templates are required for this!

Helper functions

• HTML encoding:
  • convertAsciiToHtml() to escape HTML control characters
• filename helper functions:
  • functions that encapsulate conversion from/to wxFileName
• number formatting:
  • formatNumberStringWithGrouping() support for configurable thousands grouping of digits
• various wxDateTime related functions:
  • formatDate(), parseDate() to correctly output and parse dates in the current locale
  • parseDateTimeWithFormat()
  • getMonthFromMonthIndex(), getMonthIndexFromMonth()
• message catalogue handling:
  • wxCatalogAddManag: loading and simple support for message catalogue file run-time version checks
• new controls:
  • wxTransparentStaticText: like wxStaticText, but with transparent background
  • wxColourBarWindow: coloured rectangle with border and optional rounded corners
  • wxScaledImageWindow (requires GraphicsHelper library which is not yet published)
  • wxMultiLineText: use best suited control (wxTextCtrl or wxHtmlWindow) for output of possibly longer texts (selected control depends on the used platform)
• resources:
  • load (e.g. PNG) images from memory or Windows resource file

Validators with immediate status output

• wxTextCtrlStatusValidator gives immediate feedback of validity of entered text via wxStatusMessageTarget (which output a status message into a wxTextCtrl)
• has support for "Undefined" (unspecified) values
• other general flags supported:
  • maintaining internal copy of value inside validator (useful e.g. to implement simple 'undo')
  • left and/or right trimming of input
• specializations:
  • wxTextCtrlStatusValidator: base class for validators (such as wxNumberValidator)
  • wxNumberValidator: allows specification of a range of valid values (int, long or double)
  • wxStringValidator: a maximum length for the entered string can be specified
  • wxDateTimeValidator: validate from/to wxDateTime using specified date/time format string, defaulting to a simple ISO style date/time
  • wxFilenameValidator: support validation of file or directory names, with optional checks for existence/non-existence in file system and from/to relative/absolute path resolution

Text/slider control pair validators .

• allow mutual update if one of both associated controls (wxTextCtrl or wxSlider) is changed by users input
• if entered text is valid: associated slider is updated immediately; otherwise the user will get immediate feedback via wxStatusMessageTarget (class is is derived from wxNumberValidator/wxTextCtrlStatusValidator)
• both required controls and both required validators can be created with minimum effort by calling wxExtDialog::addTextCtrlSliderPairWithLabel()

Image(DIB) filter managing class

• wxFilteredDIB provides an interface to filter a DIB image using ImageMagick filter functions (the input and result image format is DIB)
• automatic transformation of palette-based or 16-Bit color DIBs to true color IM image if filtering is desired
• for palette-based images, color adjustment is realized by modifying the palette in-place, which is much faster than modifying all pixels - the old palette is stored automatically for a later undo or a new modification
• image rotation must be 0, 90, 180 or 270 degree - if only the rotation angle (or mirroring) has changed since last filtering, rotation/mirroring will be made relative to the last result (improves performance)"

wxConfigEntryManager/wxConfigEntry classes

• wxConfigEntry and wxConfigEntryManager allow typesafe reading/writing of values from/to wxConfig
• keys (access paths) and default values are centralized in the wxConfigEntry objects and therefore duplication can be avoided
• allows writing all values at once (e.g. upon program termination, or to give the user an overview of all sections/keys and their (default) values)
• allows to reset to default values at once
• specializations of wxConfigEntry class:
  • wxIntegerConfigEntry (range of valid values can be specified)
  • wxStringConfigEntry
  • wxBooleanConfigEntry
  • wxDoubleConfigEntry
  • wxDateTimeConfigEntry

3. Sample Application and Screenshots

WxExtLib comes with a sample application to demonstrate some of the features of the library.

For the new version, a few ^screenshots are available.

For the old version 0.7.1, some more ^screenshots are available.

4. Interface and Source Documentation

Source documentation is currently contained as normal comments in headers and source files only.

Function or method parameters are usually documented only if the meaning is not obvious from the name of the parameter.

Comments in implementation files are often marked with an upper-case text, such as 'NOTE', 'WARN', 'BUG', 'PERFORMANCE' etc. giving a classification for the comment.

For various reasons I could not convince myself to convert comments to doxygen or JavaDoc like syntax. The goal is to use (or find) a documentation system with a lighter, Wiki-style comment syntax, better readable output, and acceptable member and function grouping functionality. A possible candidate for this, and at present maybe the only one as it seems, is ^Natural Docs.

5. Compilation and Tested Configurations

To use WxExtLib in an existing wxWidgets application, it is probably sufficient to add the files to the existing project- or makefiles.

To compile the sample application, one of the provided makefiles may be used. Most makefiles were generated by 'bdsgen', a makefile generator written by me using C++ as input and implementation language, which is planned to be published under an Open Source license in the future.

Tested configurations:

• Old version 0.7.1: The sample program was tested under a Debian Linux (wxGTK, wxMOTIF and wxX11 ports) and under Win9x/WinNT4/WinXP (wxMSW port). Specifically, the following compiler/port combinations were tested:
  • GCC 2.95.2 with wxGTK (using GTK 1.2.7), wxMOTIF and wxX11/wxUniversal
  • Visual C++ 6 with wxMSW
  • DigitalMars C++ 8.40 with wxMSW
  • Borland C++ 5.5.1 with wxMSW
  The following ^wxWidgets versions were used:
  • wxWidgets 2.4.1 (stable release)
  • wxWidgets 2.5.2 (development snapshot)
• Version 0.84.0016: The sample program was tested under a Gentoo Linux 2006.0 (wxGTK). Specifically, the following compiler/port combinations were tested:
  • GCC 4.1.1 with wxWidgets 2.8.0 (using wxGTK), GTK 2.10.6

To compile with the makefiles, create a sub-directory like 'build/my-build-config', change into this directory and then run (n)make -f ../../make/MAKEFILE .... Makefile-variables like WxWidgetsPrefix, WxWidgetsBuildPrefix, SourceDir etc. must be set.

Example for building the sample application for wxGTK, version 2.8.0:

 $ mkdir -p build/my-build-config
 $ cd build/my-build-config

 $ make -f ../../make/makefile-gcc-wx252-debug-generic.mak \
     SourceDir=../../src \
     WxWidgetsPrefix=/build/wxWidgets-2.8.0/ \
     WxWidgetsBuildIncludeDir=/build/wxWidgets-2.8.0/build/gtk2/lib/wx/include/gtk2-ansi-debug-2.8/ \
     _checks _clean _all 

The '_checks' pseudo-target is used to run some tests on the provided paths first, and prints warnings if certain expected directories and files cannot not be found.

An example and additional notes are contained as comments at the beginning of the makefiles.

Note: For compilation under Linux, the makefiles currently assume the 'wx-config' program to be located at '${WxWidgetsBuildPrefix}' (as is the case after compiling wxWidgets from the sources).

To debug an executable compiled with debug-information with GCC, point a debugger like 'ddd' or 'insight' to the executable; to debug an executable compiled with debug-information with VC++, simply open the executable with the Visual C++ IDE.

6. List of Changes

A list of changes made since first public release (version 0.7.1) may be found in the ^Changelog.

Most important changes since version 0.7.1 are:

• general:
  • several macros renamed to use 'M_WxExtLib_' prefix
  • some adaptions to better work with wxWidgets versions >2.5.2 and small changes for integration with WinXP
• WxExtLibConfig reorganization:
  • new WxExtLibConfig.h: proxy header to include settings header, then include header for automatic setup
  • new WxExtLibConfig_Setup.doc.txt: used config macros setup description
  • new WxExtLibConfig_Setup.h: default setup settings
  • new WxExtLibConfig_Auto.h: automatic setup
  • new WxExtLibConfig_Version.h: define version numbers
  • new WxExtLibConfig_VersionInfo.h,.cpp: structure for run-time querying of version and config information
• WxExtDialog:
  • new wxWindowAdder class
  • wxExtDialog to wxExtDlgBase refactoring:
    • now, functions of wxExtDialog are in extra class which is not derived by any wxWindow, wxObject class
  • new wxOverlayAdder class:
    • overlay support (put controls onto other control (e.g. onto background image, notebook page etc.)
    • wxWindowAdder: pushOverlay(), popOverlay() functions
  • new wxNonModalDialogManag class:
    • provide unified handling for non-modal dialogs
• StatusValidators:
  • conversion of StatusValidators.h,.cpp to use generic includes instead of macros
  • use of trait classes to simplify writing wxTextCtrlStatusValidator derived classes
  • wxTextCtrlStatusValidator now also works with wxChoice, wxListBox, wxComboBox controls
  • new wxFilenameValidator, based on wxTextCtrlStatusValidator
• WxMessageFormat:
  • moved from WxMisc.h,.cpp to extra files WxMessageFormat.h,.cpp
  • support now for most built-in types
  • variants to work with std::string instead of only wxString (stMessageFormatter/stFormat/stFormatMessage)
• RecorsetNavigationManag:
  • RecorsetNavigationManag (not yet published)
• build:
  • fixed makefiles for debug-mode compilation with gcc/g++

7. Open Issues

Version 0.7.1:

• The layout mechanism in wxWidgets version 2.5.2 (development snapshot) is currently broken under some ports.
• Some ports (e.g. wxMSW) of wxWidgets version 2.5.2 (development snapshot) ignore the font set for the dialog. This results in incorrect sizing when a dialog is scaled (zoom factor other than 1.0), because the controls will always use the default font size.
• The height of the text/HTML control of a wxMessageExtDialog (in text-mode) is one line only with the wxMSW and wxX11/wxUniversal ports of wxWidgets version 2.5.2 (development snapshot).
• The sizing logic for the wxGTK port currently assumes GTK~1, and must be extended for GTK~2 control sizes.

Version 0.84:

• Some of above issues related to wxWidgets version 2.5.2 are resolved by using a newer wxWidgets version.
• support for building in Unicode mode is not supported
• (TODO)

8. Requirements

• Requirements for compiling the source code:
  • C++ compiler
  • wxWidgets source distribution
  • (see above for tested configurations)

• Requirements for building the documentation:
  • txt2tags
  • HTML 'tidy'
  • Txt2tagsUtil (not yet published)
  • since Txt2tagsUtil has not yet been prepared for publication, only generated .html files are included for now

9. License

WxExtLib is available under a Zlib-like open source license. The license text is available ^here.

Additionally, some files are placed in the public domain. These are:

• accessor_macros.h
• safecast.h
• safecast_signedness.h
• pp_basics.h

Note that when linking against wxWidgets libraries, wxWidgets Library License must be considered as well, of course.

10. Configuration

WxExtLib is globally configured by defining or setting certain macros.

The file ^WxExtLibConfig_Setup.doc.html contains a description of used macros.

11. Sources and Download

Latest version

• individual files
  • common basics
    • accessor_macros.h   [pretty printed]
    • safecast.h   [pretty printed]
    • safecast_signedness.h   [pretty printed]
    • pp_basics.h   [pretty printed]
  • source configuration
    • WxExtLibConfig.h   [pretty printed]
    • WxExtLibConfig_Auto.h   [pretty printed]
    • WxExtLibConfig_Setup.h   [pretty printed]
    • WxExtLibConfig_Version.h   [pretty printed]
    • WxExtLibConfig_VersionInfo.cpp (not yet published)
    • WxExtLibConfig_VersionInfo.h (not yet published)
  • source configuration documentation
    • WxExtLibConfig_Setup.doc.txt
    • WxExtLibConfig_Setup.doc.html
  • core
    • ConfigEntry.h   [pretty printed]
    • ConfigEntry.cpp   [pretty printed]
    • MessageExtDialog.h   [pretty printed]
    • MessageExtDialog.cpp   [pretty printed]
    • StatusValidators.h   [pretty printed]
    • StatusValidators.cpp   [pretty printed]
    • TextCtrlSliderPairValidators.h   [pretty printed]
    • TextCtrlSliderPairValidators.cpp   [pretty printed]
    • WxMessageFormat.h   [pretty printed]
    • WxMessageFormat.cpp   [pretty printed]
    • WxMisc.h   [pretty printed]
    • WxMisc.cpp   [pretty printed]
    • WxExtDialog.h   [pretty printed]
    • WxExtDialog.cpp   [pretty printed]
    • WxExtLibAliases.h   [pretty printed]
    • WxExtLib-include-all.cpp   [pretty printed]
  • optional
    • ImageMagickExtensions.h   [pretty printed]
    • ImageMagickExtensions.c   [pretty printed]
    • RecordsetNavigationManag.cpp (not yet published)
    • RecordsetNavigationManag.h (not yet published)
  • message files
    • WxExtLib-de_DE.po
  • sample application
    • DescriptionTexts.cpp   [pretty printed]
    • WxExtLibTest.cpp   [pretty printed]
    • WxExtLibTest.rc   [pretty printed]
    • WxExtLibTest.xpm   [pretty printed]
    • WxExtLibTest-de_DE.po

• tar package (includes makefiles for sample application)
  • WxExtLib-0.84.0018.tar.gz   (187 KB - 2007 Apr 12 - MD5: c051f1622794cd3811e6c22e5a2497b3)

Previous releases

• tar package (includes makefiles for sample application)
  • WxExtLib-0.7.1.tar.gz   (91 KB - 2004 Jul 21 - MD5: 5b4f8212eed88b6ee9b87a3f956d6d9c)