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.