Some 3.0 release stats

So wxWidgets 3.0 is finally released. We should have done it much sooner than 7 years after 2.8.0 release, but better late than never. And at least this gives us a lot of statistics to analyse to see how much has changed since the last major release. So let's do just this.

Using git log shows that, in total, there have been 19224 commits (or 7.6 commits per day on average), changing 10352 files (3680 of which are new) with 2 085 638 insertions and 1 767 670 deletions, i.e. about 320 000 new lines. However these statistics are skewed by several big reorganizations that happened during 3.0 development: we moved wxPython out of the main wxWidgets repository, removed most of the old contrib directory and also converted the old documentation in LaTeX format to Doxygen. So maybe restricting ourselves to the code only, i.e. just include and src subdirectories is more fair. In this case, there are "only" 13857 commits changing 5132 files (and 600 files were added) with 926 608 insertions and 722 382 deletions i.e. more than 200 000 new lines of code. Which, by the way, brings the total number of lines of code in wxWidgets to more than 1.1 millions. To which should be added slightly more than 200 000 lines of documentation, more than 100 000 lines of the examples and, an area which has been especially greatly improved since 2.8, more than 50 000 lines of unit tests. Of course, the numbers of commits and lines of code don't mean everything and our numbers are not especially impressive anyhow, compared to other well-known open source projects such as Linux kernel or Apache, but, if nothing else, they show how active the project development was during all these years even in absence of any new stable releases.

Besides wxWidgets code base, a lot of other things have changed since 2007. One of them is that we're using Subversion instead of CVS now for version control. Naturally, a possible conclusion could be that things haven't changed enough as we still don't use Git for the official repository, even though I personally haven't used anything else since several years and we have an up-to-date Git mirror now. One of the problems of not using Git is that I don't have an accurate count of contributors to wxWidgets. While git shortlog does give the numbers of people who committed to svn, there are only about 25 of them, as almost all patches submitted to us ended up being committed by me and Subversion doesn't preserve the original authorship information. My personal estimation is that there must have been around 300 external contributors since 2.8 (we have about 220 of them mentioned in the change log but not everything is mentioned in it). Huge thanks to all the people who have kept helping improving wxWidgets and contributing back to community!

Looking forward, I have no idea when will 4.0 release happen nor what will it contain. But we'll definitely make 3.2 release sooner than in 7 years, even if it will probably mean less impressive numbers in its announcement post. In the meanwhile, enjoy using wxWidgets 3.0 — I know that we will enjoy having finally made it!

Second release candidate of 3.0.0 available

We have just made 3.0.0-rc2 files available. There are no truly exciting changes since 3.0.0-rc1 but this is the final release candidate before 3.0, so please test your applications with it and let us know if you find any real showstopper problems for the last chance of fixing them before 3.0.

You can get the release files, including binaries for not only MSVC but also MinGW-TDM this time, from SourceForge. More details are in the release announcement post and you can discuss this release on reddit.

wxWidgets and C++ 11

I've recently learnt† that the latest edition of Bjarne Stroustrup's "The C++ Programming Language", updated to cover C++11, mentions wxWidgets as one of the commonly used C++ libraries (you can search the book at Amazon for "wxWidgets" to find the relevant paragraph). Being mentioned in the bible of C++ is always nice, of course, but isn't it strange that a book about C++11 references a purely C++98 library? Of course, C++11 is almost fully backwards compatible with C++98 and wxWidgets can be compiled with a C++11 compiler (e.g. under Unix, just pass CXX="g++ -std=c++11" to configure) but this is not very interesting. More so is how the new C++11 features make writing code using wxWidgets simpler and this is the topic of this post.

To illustrate this, let's look at a very simple program written in C++ 98: It simply shows a window with a button and increases the button font when it is pressed. It's not especially useful but does show a few typical constructs appearing in real-life programs. This version can be compiled with just about any C++ compiler (VC6 need not apply) and works with any wxWidgets version since 2.9.0, which introduced Bind().

So let's now look at the version updated to use some C++ 11 features: This version requires a C++11 compiler, e.g. g++ 4.7 or later (tested with 4.8), MSVC11 (a.k.a. Microsoft Visual Studio 2012) or clang 3. It also doesn't quite compile with wxWidgets 2.9.5, so currently you need the latest Git/SVN sources. But it will compile out of the box with wxWidgets 3.0, of course.

The functionality is exactly the same, so what are the differences?

1. The most important change is undoubtedly the possibility to use lambdas as argument to Bind(). This is very useful for writing simple and short event handlers as it allows to keep the handler code together with the code creating (or loading from resources) the control. Notice that you need to capture this pointer by value in the lambda, hence the = in the line 12. Also notice that the lambda still must take (unused) wxCommandEvent&. This is something that we might get rid of in the future.
2. The possibility to use the new for loop is also quite appreciable, notice how much simpler iterating over the child windows has become.
3. Finally, there are small changes such as using nullptr instead of NULL, the added override in line 28 ensuring that you really override the base class method and using auto for the variables declaration. This is not really related to wxWidgets and I'm not completely convinced myself about the benefits of using auto everywhere (yet?) but if you are, perhaps after reading this article, you shouldn't encounter any problems doing it.

So, finally, even without any serious modifications to wxWidgets itself, the most user-visible changes of C++11 can be used in the programs using the library. Of course, there are many other C++11 features which would be very useful in the library implementation too and I'm very much looking forward to the variadic templates support becoming common enough to use them instead of the macro-based approach for the implementation of wxPrintf() and similar functions. But for now just using lambdas for the event handlers is already very nice.

---

† Thanks to Herb Thompson for noticing this.

Continuous Integration with Travis

Travis is a continuous integration system which works nicely with GitHub, so while we've been using Buildbot since a long time and will continue to do it, we thought it could be nice to also try Travis and so now we have a minimal configuration file for it and it builds wxGTK after each commit.

You can check the latest Travis build status by just looking at this blog post: and you can click the button for more details. For the other ports and also to check if the tests pass (as Travis currently only checks the compilation and doesn't run the tests yet), see our Buildbot status page.

Help with pre-2.9.5 testing

We plan to release 2.9.5 next Monday, so any testing right now would be even more welcome than usual -- as 2.9.5 is supposed to be the last release before 3.0, it would be great to avoid having to do any big changes after it is done and for this we need to avoid having the kind of bugs requiring such changes in the release in the first place.

So if you can grab the latest sources from SVN or Git and test them with your application, it would be really helpful. Especially if you discover any news bugs while doing it. And even more so if you don't ;-)

Thanks in advance!

---

P.S. Currently wxX11 and wxMotif are known to be broken (and will be fixed before 2.9.5) so testing these ports is not worth doing, but all the rest of the ports are supposed to work.

The fastest image format to load is...

... surprisingly, at least to me, TIFF. I have recently added a simple benchmark for wxImage methods, mostly to be able to test the optimizations to wxImage::Scale() done by @Hsilgos, but it also looked like a good opportunity to test the speed of loading the same image in different formats. And it turns out that loading the image from TIFF is consistently faster than loading it from JPEG, BMP or PNG even though the JPEG file is much smaller and I'd expect this to play a role. Actually, either the TIFF library under Linux is particularly optimized or the other ones are not optimized at all because using the system libraries for all formats (except BMP which is always loaded using our own code), loading TIFF image is more than twice faster than loading the JPEG one, 8 times faster and 10 times faster than loading the PNG one. Under Windows, where our builds of the libraries, compiled without any particular optimizations, are used, TIFF is relatively twice slower as it's only 10% faster than JPEG, 4 times faster than BMP and 5 times faster than PNG but the differences are still quite big.

The fact that using libpng turns out to be slower (albeit not by a large margin) than our own naive BMP loading code is rather surprising too but perhaps it's due to the code in wxPNGHandler which tries to determine the alpha format in a not very clever way. It would be interesting to profile this further and also test with other images (currently I have a huge sample of 1) and at least determine whether TIFF is consistently faster or just for some images (and, if so, for which ones) and whether this is specific to the code in wxWidgets or if the TIFF protocol or library is just really more efficient.

Simpler way to create fonts

Just a quick note about the new and simpler way to create fonts in wxWidgets 2.9: in addition to a multitude of wxFont constructors taking various font attributes, such as size, style, weight, face name and so on, there is now another constructor, taking a single wxFontInfo object that combines all of them together and allows to use the named parameter idiom for the font creation.

It may seem non-obvious how can adding another constructor help with the problem of having too many constructors, so here is a quick example to show how it does: suppose you want to create an underlined, 12 point version of "Courier" font. Here is how you'd do it currently:

wxFont f(12, wxFONTFAMILY_DEFAULT,
         wxFONTSTYLE_NORMAL, wxFONTWEIGHT_NORMAL, true, "Courier");

And here is how you'd do it with the new constructor:

wxFont f(wxFontInfo(12).Underlined().FaceName("Courier"));

Hopefully the advantages from the point of view of the library user are clear:

• You don't need to specify the default parameters such as wxFONTFAMILY_DEFAULT, that you don't care about.
• Each font attribute is clearly written out, while the meaning of true (which meant that the font should be underlined, by the way) was hardly obvious in the first form.
• You can specify the parameters in any order instead of having to check the documentation every time.
• Last and really least but still: you can create strike-through fonts (notice that they are only supported under MSW and GTK currently) using the new constructor using the natural Strikethrough() syntax, while this wasn't supported at all with the old constructor.

From our, i.e. developers, point of view, there is one extra important advantage, related to the last point: if support for a new wxFont attribute is added later, this way of creating fonts will be easy to extend to support it.

So my advice is to use wxFontInfo in all the new code using wxWidgets 2.9. The old constructors are not going anywhere and can still be used (except for the one taking int flags which was added for 2.9.4 and now removed to avoid ambiguities with the other existing constructors), but there is no reason to prefer them to the new one.

About the benefits of procrastination

And no, I'm not going to speak about why postponing 2.9.5 release for so long after its initially scheduled October 2012 release date is a good thing. Instead, I'd like to explain how can the recently added CallAfter() function make your life simpler.

CallAfter() is a method of wxEvtHandler, which means that it's available in the code of any classes deriving from it, including wxWindow but also wxApp and several others. And it basically allows to call another method of the class in which it is used asynchronously later. Notice that no threads are involved, the call to that other method still happens on the same main GUI thread but at a slightly later time. To be precise, the control first must return to the event loop and only then (i.e. "after") the specified method will be called.

Using it is quite simple: if you want to call some method Foo() taking 0, 1 or 2 arguments (this is the current maximum but it could be extended in the future if really needed), you can just write

void SomeWindow::OnSomeEvent(wxEvent& event) {
    // If the method doesn't take any arguments:
    CallAfter(&SomeWindow::Foo);

    // If the method takes an argument:
    CallAfter(&SomeWindow::Foo, arg1);

    // Or if it takes two:
    CallAfter(&SomeWindow::Foo, arg1, arg2);
}

Notice that Foo() must be a method of the same class. But other than that, this is pretty straightforward.

The above explains how to use CallAfter() but doesn't answer the really interesting question which is, of course, why would you ever want to do this instead of just calling Foo() directly? The answer is that some things often just can't be done immediately in a GUI program, either because doing them would interfere with its normal flow of control and generate extra events, potentially resulting in unexpectedly re-entering the same event handler and infinite recursion. Or because the current state of the program simply doesn't allow them. An example of the first case is showing a message box from a window activation event handler: doing this would immediately deactivate the window back again which is probably unexpected. An example of the second case is showing a message box from event handlers for all events generated by mouse click, e.g. button press event: as the mouse is captured by the button when the click happens, its mouse grab is released unexpectedly and the standard control itself can get confused by it, e.g. the button could appear to be stuck in pressed state.

The message box example is actually a poor one because wxWidgets already provides an easy way to prevent such problems from happening by using wxLogMessage() function which already postpones showing the message box until the next event loop iteration. What CallAfter() does is to provide you with a generic way to do the same thing very simply.

As a more realistic example, let's consider a common GUI layout with a tree control on the left and some window displaying the items in the tree on the right. Suppose you'd like to update the display when a tree item is double-clicked. There is a wxEVT_COMMAND_TREE_ITEM_ACTIVATED event corresponding to this action so typically you'd do something like this:

TreeViewFrame::TreeViewFrame() {
    wxTreeCtrl* tree = new wxTreeCtrl(this, ...);
    tree->Bind(wxEVT_COMMAND_TREE_ITEM_ACTIVATED, &TreeViewFrame::OnActivated, this);

    // This is the window showing the current item.
    m_view = new ViewWindow(this);

    DisplayItem(initial);
}

void TreeViewFrame::OnActivated(wxTreeEvent& event) {
    ... retrieve the item to show from the event (typically using client data) ...
    DisplayItem(item);
}

void TreeViewFrame::DisplayItem(ItemType item) {
    m_view->ShowItem(item);
    // Give the focus to the view to allow the user to easily use the keyboard.
    m_view->SetFocus();
}

And this works perfectly well except that the view doesn't get the focus after double clicking an item in the tree under Windows. The reason for this is that the native tree control there sends the activation event first and then processes the (second) mouse click which resulted in it itself, and as part of this processing it sets the focus to the control itself (as it's normal for the control to become focused when clicked). So while the view does get focus during the activation event handler execution, it loses it almost immediately afterwards.

In a perfect world, wxWidgets would somehow isolate you from this peculiarity of Windows tree control implementation. But doing this is rather not trivial and, remember, this is just one of several examples. So in the imperfect world we live in, you need to deal with this problem at your application level. CallAfter() reduces the imperfectness of having to do it to acceptably low level as all you need to change in the snippet above to make it work is to replace the last line of the event handler with the call to it:

void TreeViewFrame::OnActivated(wxTreeEvent& event) {
    ... retrieve the item to show from the event (typically using client data) ...
    CallAfter(&TreeViewFrame::DisplayItem, item);
}

All we did was to delay the item display until the next event loop iteration after the one which dispatched the activated event itself and this is enough to get rid of the focus problem.

So if you have any capture, focus or other global state problems (and notice that they can stem from your own code as well, and not just behaviour of the native controls or wxWidgets itself), you can often use CallAfter() to easily solve them by just postponing whatever you need to do until slightly later. Remember that laziness is a cardinal virtue for a programmer -- and now wxWidgets helps you to cultivate it!

---

P.S. But we'll still try to release 2.9.5 soon...

Preparing for 2.9.5

As (unfortunately) not unusual, it looks like 2.9.5 won't be released before the end of October as I planned hoped. But the good news is that we're still relatively close to it, so even though the release is going to be late, at least it won't be late by much. This optimistic assessment is based on the fact that a lot of long-standing important tasks are finally getting closer to the completion:

First, we will finally (after 3 years) soon apply the XRC reorganization patch by Steven Lamerton that will allow us to have XRC handlers for the classes not in the "core" or "adv" libraries, e.g. wxRichTextCtrl, wxRibbonControl or various AUI classes. This was unfortunately impossible so far because of annoying inter-library dependencies issues, but will be fixed by this patch in a classic computer science manner -- that is, by introducing another level of indirection. The changes here are relatively straightforward but there are still quite a few of them, so it would be great to get more testing for them, even before 2.9.5 release, so if you're interested, please get the patch from the Trac or, soon, from the svn or its git mirror and let us know about your experience.

Second, an almost as long-lived branch containing several important changes to wxAUI by Malcolm MacLeod is also planned for a merge. The main user-visible effect of these changes is that it will now be possible to drag notebook pages not only between different wxAuiNotebooks but also form notebooks dynamically by simply piling up pages on top of each other. There are other notebook-related improvements, such as support for horizontal (i.e. on the left or right) tabs by Jens Lody. But here there are also a lot of changes and, to make matters more interesting, they're hardly straightforward so testing this patch would be very welcome as well.

The final relatively big feature planned for 2.9.5 is wxMaskedEdit by Manuel Martin and, again, unsurprisingly, feedback about it would be very welcome.

In addition to the not-yet-quite-merged patches above, several other long-postponed changes have been already done in the svn:

• Scintilla, used by wxStyledTextCtrl, was upgraded to almost the latest version. This brings a number of new features but also, possibly, some bugs which it would be great to find before the release.
• Much better support for symbolic links in wxFileName (see DontFollowLink() and the new flags argument of Exists()) and wxFileSystemWatcher (work done by David Hart).
• New wxSimplebook class.
• Support for embedding PNG into the program sources, XPM-like.
• wxPython CallAfter() equivalent for C++.

Please test your programs with the latest svn and, better yet, try using the new features in them and let us know about any regressions or things that could be improved in the new stuff.

Thanks in advance for helping us to make wxWidgets 3.0 better!

Spin news

I've recently needed to add a small new feature to wxSpinCtrl: possibility to display and enter the numbers in hexadecimal format. This is done now with the addition of SetBase() method, so now you can either call SetBase(16) explicitly in the code or use "base" XRC property by adding <base>16</base> to your XRC files (this needs to be done manually as dialog editors don't have support for it yet). Just in case you're curious, here is how the new control looks in the updated widgets sample under OS X:

But as a side effect of working on this, I've also fixed a few other bugs in wxSpinCtrl, hence this progress report:

• First, I've simply removed wxOSX version of this control. Strangely enough, we had a generic implementation of it for wxOSX which was different from another generic implementation used for all other platforms. They were not identical but pretty similar and at least now we only have one version to maintain.
• Next I fixed the funny bug with contents of the control being shown as password field if wxALIGN_CENTRE was used. Even though it's more correct to use wxTE_CENtRE, it's more user-friendly to support both versions, especially as the documentation was rather confusing on this subject until recently.
• I also added the generation of wxEVT_COMMAND_TEXT_ENTER to the generic wxSpinCtrl which didn't send them at all before. This fixed another bug as generic wxSpinCtrl was also used for wxSpinCtrlDouble under wxMSW, and so this event wasn't sent when using real-valued spin controls under Windows, even though it was sent with integer-valued ones.
• But integer-valued Windows wxSpinCtrl was not without problems neither: the value carried by its events wrapped over when it was greater than SHRT_MAX, i.e. 32767. So I fixed this as well.

There are still some bugs left in wxSpinCtrl, e.g. settings colours doesn't work correctly in the generic version but it's in a much better shape now than only a few days ago.

Did you know that Intel VTune used wxWidgets?

Well, I didn't know this but reading the release notes for a new update I've just downloaded I noticed the following at the end of the document:

wxWindows Library
This tool includes wxWindows software which can be downloaded from
http://www.wxwidgets.org/downloads.
wxWindows Library Licence, Version 3.1
======================================
Copyright (C) 1998-2005 Julian Smart, Robert Roebling et al
...

And, indeed, Ctrl-Alt-middle-clicking on VTune window gives:

Sometimes I forget that only a very small proportion of all wxWidgets users reads mailing lists (let alone posts to them), the forums and so on and that there are plenty of companies that use wxWidgets that we have no idea about at all. So it's not really surprising to find that Intel uses wx but it's still nice to have them in our users list!

How to use 2.9.4 wxMSW binaries

We have decided to experiment with providing binaries for wxWidgets releases. So, for the first time ever, 2.9.4 release includes binaries for a few different versions of Microsoft Visual C++ compiler.
However we might not have done a very good job of explaining how to actually use them, the README at the link above is relatively brief and omits some steps, so let me try to explain in more details how to build your wxWidgets applications using the files provided and without building wxWidgets yourself.
First, you need to get the correct files. You will always need the headers one but the rest depends on your compiler version and architecture: as different versions of MSVC compiler are not binary compatible, you should select the files with the correct vc80, vc90 or vc100 suffix depending on whether you use Visual Studio 2005, 2008 or 2010 respectively. You also need to decide whether you use the x64 files for 64-bit development or the ones without this suffix for the still more common 32-bit builds. After determining the combination of suffixes you need, you should download the "Dev" and the "ReleaseDLL" files in addition to the "Headers" one above, e.g. for 32-bit MSVS 2010 development you need wxMSW-2.9.4_vc100_Dev.7z and wxMSW-2.9.4_vc100_ReleaseDLL.7z.

Once you have the files you need, unzip all of them into the same directory, for example c:\wx\2.9.4. You should have only include and lib subdirectories under it, nothing else. To avoid hard-coding this path into your projects, define wxwin environment variable containing it: although it's a little known fact, all versions of MSVC support environment variable expansion in the C++ projects (but not, unfortunately, in the solution files).
Next step is to set up your project to use these files. You need to do the following:

• In the compiler options, i.e. "C/C++" properties:
  • Add $(wxwin)/include/msvc;$(wxwin)/include to the "Additional Include Directories". Notice that the order is important here, putting the MSVC-specific directory first ensures that you use wx/setup.h automatically linking in wxWidgets libraries.
  • Add WXUSINGDLL and wxMSVC_VERSION_AUTO to the list of defined symbols in "Preprocessor Definitions". The first should be self-explanatory (we only provide DLLs, not static libraries) while the second one is necessary to use the libraries from e.g. lib\vc100_dll directory and not the default lib\vc_dll.
  • Also check that _UNICODE and UNICODE symbols are defined in the same "Preprocessor Definitions" section. This should already be the case for the newly created projects but it might be necessary to add them if you're upgrading an existing one.
    [added at 2013-02-08 in response to comments]
  • Check that you use "Multi-threaded [Debug] DLL" in the "Run-time library" option under "Code Generation" to ensure that your build uses the same CRT version as our binaries.
• In the linker options you only need to add $(wxwin)\lib\vc100_dll (with the compiler-version-dependent suffix, of course) to "Additional Library Directories" under "Linker\General" in the options. Thanks to the use of MSVC-specific setup.h you don't need to list wxWidgets libraries manually, i.e. you do not need to put anything in the list of "Additional Dependencies".

Now you should be able to build your project successfully, both in "Debug" and "Release" configurations. With MSVC 10 it can also be done from the command line using msbuild.exe. Of course, to run the generated executable you will need to either add the directory containing wxWidgets DLLs to your PATH or copy the DLL files to a directory already on it. Finally, if you want to distribute the binaries created using these options, you will need to install Microsoft Visual C++ run-time DLLs. Again, MSVC 10 has an advantage here as you can simply copy msvcp100.dll and msvcr100.dll as any other DLL, while you need to install specially for the previous compiler versions that use WinSxS ("side-by-side") for them.
Let us know if you run into any problems using these binaries or, on the contrary, if you didn't but were glad to have them. If enough people find them useful, we'll try to provide them again for 2.9.5 and, most importantly, for 3.0.

---

Updated on 2012-08-23T12:55:10: Corrected linker options instructions.

Nicer Notifications

This is something really not that important in the grand scheme of things but notifications produced by wxNotificationMessage used to look relatively ugly under Unix as they appeared just as a normal window:

And this wasn't especially nicely looking and, even worse, inconsistent with all the other notifications shown by the system.

As I'm currently on vacation and don't feel bound to work on "important" things, I've finally decided to take time to change this. Switching to libnotify to show the notifications as everybody else does was very simple and the end result is much nicer:

or, to show an example of multiple active notifications:

Unfortunately fixing the rest of the problems due to lack of integration with Linux desktop turned out to be less trivial, for example I totally failed in my attempts to get notifications about the system going to sleep and waking up that I'd really like to implement for wxGTK. The only other thing I managed to do during this vacation was a couple of minor wxWebView enhancements but more about this in a future post.

MSVS 2012 RC Installation Experience

As an update to my previous post about building wxWidgets with VC11 beta, I'd like to say a few words about my experience with installing the RC version of the same compiler -- now known as MSVS 2012.

First of all, the installer doesn't tell you anything about having to uninstall the beta yourself before running it but you really must do it. Otherwise the installation will succeed but the IDE won't open afterwards with an "invalid licence" error (see this known issue, apparently beta has a higher version number than the RC).

Second, and much more annoyingly, the installer also doesn't warn you that it's going to break your existing VC 10 installation. This is also an apparently known problem and can be fixed by installing SP1 for VC 10 but if you're unaware of it it may not be completely obvious that the mysterious LNK1123: failure during conversion to COFF: file invalid or corrupt errors you now get when building any MSVS 2010 C++ projects in debug build are due to VS 2012 installation.

Hopefully knowing this in advance will make testing MSVS 2012 less aggravating to the other wxWidgets users than it was for me. Unfortunately you will still need to reboot your machine a couple of times to install it but then clearly not having to reboot for a compiler installation would have been too much to expect.

Ah, and as for building wxWidgets with VC 11 RC -- nothing to say here, it still works, just as it did with beta and I didn't notice any real changes affecting wxWidgets. The new IDE look is pretty ugly but all the features are there and the profiler is rather nice. Pity it's only included in Premium edition and later.

Building wxWidgets with Microsoft Visual C++ 11

This is practically a non-post as building wxWidgets with the recently released Visual Studio 11 Beta turned out to be completely uneventful. After installing the Visual Studio itself -- which was also perfectly straightforward albeit still a typically Microsoft experience as, obviously, installing a compiler should require you to reboot your machine -- I could build the current wxWidgets with the new compiler from command line using nmake /f makefile.vc without any problems. I did fix a harmless warning about an unrecognized Visual C++ version but no other changes were needed.

So far I don't have any experience with the new compiler yet, i.e. there are no obvious differences compared with VC10. It seems to produce slightly larger binaries (~70MiB instead of ~68 for VC10 for wxmsw29u_core.lib) but this is perhaps a consequence of its beta nature. I do look forward to testing the improved support for C++11 in the new version and, if I have some time, I'd like to play with the new WinRT stuff and, in particular, WRL library to see if it's realistic to write Metro applications in C++ without using Microsoft-specific compiler extensions and, if so, whether we can support Metro in wxWidgets.

Panta rhei

I've just done something that I hadn't done during the entire time I was working on wxWidgets: removed an entire port. And not even just one of them but two at once: wxPalmOS and wxMGL. The latter wasn't used since many years and I don't think the former has been ever really used at all. Moreover, the platforms targeted by these ports don't themselves exist any more. So removing them was a pretty straightforward decision as there were no benefits at all in keeping these ports while maintaining them took small but non zero amount of work.

The decision is less clear cut for them but there are other ports which might be dropped soon too. wxGTK1 will probably disappear when GTK+ 3 support is merged into trunk. The old Cocoa port should be removed too, if only to avoid confusion with the new wxOSX/Cocoa. wxMotif is definitely not very relevant any more so it will probably go as well. I'm not sure if anybody is interested in wxPM (OS/2 port) but it could be a candidate for removal in the near future as well.

The one port which we, or at least I, had high hopes for was the DirectFB-based wxUniversal, a.k.a. wxDFB. Unfortunately it hasn't attracted any interest from the community so it has never developed into a fully-fledged port. This is really a pity as I'd like to see wxWidgets used more on low-powered embedded devices where DirectFB is pretty popular and I still hope that we can find somebody interested in working on it. And while there is hope, we're not going to remove it, even if it's really not very useful in its current state.

With all these ports gone or going, what is remaining? The three major ports are, as always, wxMSW, wxGTK(2) and wxOSX. wxDFB, wxX11 and wxWinCE are not used much but still exist in a more or less reasonable shape. We also hope to have wxGTK3 soon and, more excitingly, the new wxiOS port. Other than that, wxQt port was started but seems to have stalled and, in any case, it was never clear if it made much sense. wxAndroid would be the port I personally would most love to see but it requires a big effort and in spite of having been discussed several times nothing much has happened.

I think writing new ports -- or maintaining and improving the existing ones -- is much simpler now than it used to be because of the clear definitions of the classes API (for the most part anyhow), more clear documentation and the unit tests allowing to automatically check the code correctness. And working on your own port is very rewarding and (at least in my, perhaps atypical, opinion) a lot of fun so if you're looking for a fun open source project for 2012, you could do worse than choose working on wxSomethingOrOther!

Adding a New Control to wxOSX: A Walkthrough.

I've decided to write down my notes about implementing a new control for wxOSX port in the hope that it can help other OS X developers to participate in wxOSX development (but, to be honest, also because I might return to it myself when I have to do this the next time).

So, without further ado, here is the full and unabridged true story [*] of implementing wxDatePickerCtrl in wxOSX/Cocoa.

To start with, you need to set up your wxWidgets development environment. For this you need to get wxWidgets sources, ideally from svn or its git mirror. You then need to build them enabling debug support to make sure you can debug them later. The simplest way to do this is to use the command line, even if you prefer to use Xcode for editing and debugging later. It's strongly recommended to build wxWidgets in a separate directory from the one containing its sources, so, assuming you put the sources in $HOME/src/wx, you should do:

 $ mkdir -p ~/build/wx/osx_cocoa-debug
 $ cd $_
 $ ~/src/wx/configure --with-osx_cocoa --enable-debug

If you prefer to build in 32 bits, add --enable-macosx_arch=i386 switch to configure. Another useful option is -C to make configure cache the results of its checks, this will make it run much faster the subsequent times. In any case, after doing this you just need to do make -s -j8 with "-s" added to avoid huge quantities of output you probably don't care about and "-j8" being adequate for the modern quad-core CPUs. Of course, if you use a less -- or more -- powerful machine, adjust the "8" accordingly. Depending on your machine characteristics the build can take anywhere from a couple of minutes to half an hour or more but it should eventually finish. To test that everything well, and also because we will need it later for testing anyhow, try building and running the "widgets" sample:

 $ cd ~/build/wx/osx_cocoa-debug/samples/widgets
 $ make -s
 $ open ./widgets.app

Next step is to add stubs for OS X-specific version of the control: usually, the control you want to implement will be already available under OS X but its "generic", i.e. platform-independent and hence not really Mac-looking, version would be used. We want to replace it with the native one so let's do it by modifying a few files in wxWidgets sources:

1. Modify include/wx/datetimectrl.h to include wx/osx/datetimectrl.h if __WXOSX_COCOA__ is defined. Notice that we only implement this control for the Cocoa port version, if you were doing it for both Carbon and Cocoa, you would have tested for just __WXOSX__.


2. Our example is actually more complicated than a typical control because there are two classes: wxDateTimePickerCtrlBase, which is the common base class for wxDatePickerCtrl and wxTimePickerCtrl and wxDatePickerCtrl itself. So we also need to update include/wx/datectrl.h in a similar way.


3. Of course, now that we added inclusions of the new files, we actually need to create them so let's do it. Both headers should declare the corresponding classes, i.e. the same as in the common headers from where we include them but without the "Base" suffix. So let's define wxDateTimePickerCtrl, inheriting from wxDateTimePickerCtrlBase in include/wx/osx/datetimectrl.h. and, similarly, wxDatePickerCtrl inheriting from wxDatePickerCtrlBase in include/wx/osx/datectrl.h. You can copy the file structure (i.e. the standard header comment, the include guards, ...) from another OS X header or maybe from the common header that you already modified itself. Don't forget to put your name in the "Author" line!


4. Usually, the classes we declared are concrete, so they should have the correct constructors and implement base class pure virtual methods. The "Base" classes don't define the constructors so we need to look at an existing implementation, for example the native MSW one in include/wx/datectrl.h, to see which arguments should the constructor take. You can simply copy the constructors (including the default one) and Create() function declaration from there as they must be the same for all ports, it's just their implementation that will be different.

At this stage, it might be a good idea that our new headers compile correctly (of course, nothing is going to work nor even link yet) so you could try to compile some file including them. In my case let me check if "make advdll_datavcmn.o" still works -- it does, so we didn't make any stupid mistakes (yet) and can continue.

Let's add the stubs for the implementation of the new classes too now:

1. Create src/osx/datetimectrl_osx.cpp and src/osx/cocoa/datetimectrl.mm. The latter is an "Objective-C++" source file, hence the relatively unusual extension. Again, as we actually are implementing two new classes and not one, we also need to create src/osx/datectrl_osx.cpp. But as we suspect that we won't need any Cocoa-specific implementation for this class (as everything will be done in the base one), we don't need any other Objective-C++ files.


2. We need to update wxWidgets build system to take the new files into account. For this, we need to edit build/bakefiles/files.bkl, locate ADVANCED_OSX_COCOA_SRC definition in it and add the new files paths to it. Also do the same for ADVANCED_OSX_COCOA_HDR.


3. If you don't have it yet, you need to install bakefile for the next step. Just grab the DMG from download page and install it as usual.


4. Go to build/bakefiles subdirectory and run bakefile_gen -b wx.bkl to update all make and project files for wxWidgets.


5. Finally, re-run configure or just recreate the makefile using the command ~/src/wx/regen Makefile from the build directory.


6. And redo make again as a sanity check. I got undefined symbol error from the linker about wxDatePickerCtrl::GetClassInfo() when doing this, which made me realize that I forgot to put wxIMPLEMENT_DYNAMIC_CLASS() in src/osx/datectrl_osx.cpp. After adding it, everything linked correctly. Of course, nothing works yet but we're going to change this soon.

So, finally, here is the interesting part: actually implementing the control using Cocoa API. The details of doing this depend on the exact control used, of course, e.g. we are going to base it on NSDatePicker in this case but another subclass of NSControl would need to be used for another control. But some things need to be done for all of them in more or less the same way because all wxOSX classes are similar and use pImpl-idiom: the wxControl-derived class itself just forwards all of its methods to its "peer", which is a pointer to an internal object of a class deriving from wxWidgetImpl implemented differently for Carbon and Cocoa ports. In more details:

1. As we need some additional methods in our "impl", we're going to define a new class for it. Notice that sometimes this can be avoided as wxWidgetImpl already has quite a few standard methods which are enough for many common controls. In our case, however, they are not. So we add a new include/wx/osx/core/private/datetimectrl.h header and define wxDateTimeWidgetImpl class with the Set/GetDate() and Set/GetDateRange() methods corresponding to wxDatePickerCtrl methods we need to implement in it. Notice that this is a private header, not installed when wxWidgets is installed, so there is no need to add it to build/bakefiles/files.bkl unlike the public headers we had created before.


2. We also a static CreateDateTimePicker() method that we'll use for creating the native Cocoa control to this class as well.


3. The implementation will be the same as for the other Cocoa widgets, i.e. it will first create a subclassed NSDatePicker which is only necessary in order to call wxOSXCocoaClassAddWXMethods() (it would definitely be nice to have some way to avoid duplicating this code, even if it's quite trivial for all classes, but I don't know how to do it -- contributions from Cocoa/Objective-C experts would be welcome) and associate it with the peer object mentioned above.


4. We also need to implement wxDateTimeWidgetImpl implementing all its pure virtual methods we added above and implement them using the corresponding NSDatePicker methods in the straightforward way. We'll call our derived class wxDateTimeWidgetCocoaImpl for consistency with the similar classes.


5. Finally we also need to add code for generating events for our control. In this case it is very simple as there is only one event and it's the main/default action of the Cocoa control so it's enough to just override controlAction() method in wxDateTimeWidgetCocoaImpl.

By now we have a minimally working implementation of the control! It's definitely not perfect as we don't handle almost any styles of wxDatePickerCtrl, notably wxDP_ALLOWNONE, but as there doesn't seem to be any simple way to implement it with the native Cocoa control we're just going to leave it unimplemented for now. We do need to mention this to warn the users so let's update interface/wx/datectrl.h to add a note about this.
Otherwise no new documentation needs to be written as it already existed so we are almost done.

The last thing is to submit the changes for the inclusion to wxWidgets. This is normally done by submitting a patch to our Trac but as this patch is rather extensive, it's a good idea to request a review for it first. Remember to clean up your patch before submitting for the review, just as I did before submitting this patch.

While this post turned out to be quite long, it's mostly because I tried to describe all the steps, including the very first ones, in details. It also involved a rather atypical case with 2 different classes being involved when usually only one of them is. Adding new controls to wxOSX is really not that difficult and I hope this walk-through will encourage more people to do it. And if you do follow it and find any inexactitudes (this word sounds so much better than "stupid errors"), please let me know and I'll correct them here.

Happy hacking!

---

* For some values of "unabridged" and "true". I did simplify a few things, mainly because I implemented both wxDatePickerCtrl and wxTimePickerCtrl at the same time.

2.9.3 release in details

wxWidgets 2.9.3 has been officially released today. In spite of our efforts to speed up the release process, it still took us 5 months to do it after 2.9.2. However it's significantly better than a year that both 2.9.1 and 2.9.2 had taken. And we plan to make 2.9.4 sooner than in 5 months too as explained in the updated roadmap.

As a remainder, here is a summary of the most important new features that appeared in wxWidgets since 2.9.2:

• The star addition of this release is the wxWebView library by Steven Lamerton and Auria, developed during Google Summer of Code 2011. It is by far the biggest and most important new feature. Thanks to it it is finally possible to embed a fully functional native web rendering engine (with JavaScript and CSS support) in wxWidgets applications.


• wxTimePickerCtrl logically complements wxDatePickerCtrl. Currently it uses a native control under MSW and a generic implementation elsewhere but we have plans to also provide a native implementation for OS X in the next version (and for wxDatePickerCtrl as well).


• wxTreeListCtrl: this is much less revolutionary but is a convenient and, most importantly, simple to use multi-column hierarchical control.


• wxRichToolTip and wxBannerWindow are also not exactly earth shattering but provide a simple way to enhance your application UI by presenting more information in a nice and not distracting way to the user.


• Time functions now can return time with microsecond, rather than millisecond, precision and wxStopWatch is more precise thanks to this.


• The generation of wxEVT_CHAR_HOOK event was made consistent for all the major platforms and DoAllowNextEvent() was added to make it possible to handle this event in more flexible way.


• wxMessageDialog gained support for wxHELP button and, consequently, it is now possible to easily show message boxes with up to 4 (instead of 3 before) custom buttons. We are sure that wxWidgets users won't abuse this feature but, just in case, we officially announce that 4 is as high as the number of message box buttons will ever go.


• You can now try to enter a critical section, without blocking.


• wxTextCtrl has gained support for auto-completing the directories (unfortunately, as with the files, this is only implemented in wxMSW currently).


• And it is now also possible to find the pixel coordinates of a text position in wxTextCtrl which is helpful for e.g. showing a context menu or a popup window for the given character or word.


• Support for wxSplitterWindow persistency was added, meaning that you can now simply call wxPersistentRegisterAndRestore(splitter) to automatically save the splitter position and restore it the next time your program is executed. Additionally, the location and the format of saved persistent options can now be customized by providing a custom wxPersistenceManager and overriding its GetKey() method.


• Keyboard navigation in generic wxDataViewCtrl has been significantly enhanced to make it really practical to use it for editing and not just browsing data.

There were many more minor additions and plenty of bug fixes as well, of course, see the change log for even more details.

Finally some combined statistics about the changes since the last release:

% git shortlog -sn remotes/tags/WX_2_9_2..
   465  Vadim Zeitlin
   232  Steven Lamerton
    74  Stefan Csomor
    71  Vaclav Slavik
    47  Dimitri Schoolwerth
    47  Robin Dunn
    41  Paul Cornett
    26  Julian Smart
    21  Jouk Jansen
     6  Francesco Montorsi
     5  Chris Elliott
     1  Bryan Petty
     1  John Chain
     1  Mike Wetherell

for 1038 commits. Notice that my own check ins include committing many patches from other people (which git would have kept track of but svn is unfortunately incapable of this). In particular, I'd like to thank Catalin Raceanu, Kinaou Hervé, David Hart, troelsk, Armel Asselin, wsu, joostn, Navaneeth, Allonii, ivan_14_32, Marcin Wojdyr, John Roberts and others for their contributions to this release (sorry in advance if I forgot anybody in this list, please contact me if you should have been included into it). To keep an idea of the amount of code changed by these commits here is another statistics:

% git diff --shortstat remotes/tags/WX_2_9_2
 1202 files changed, 231492 insertions(+), 149751 deletions(-)

So around 80000 lines have been added which seems enormous but more than 60000 of them were actually changes to the (automatically generated) make and project files and message catalogs so "only" approximatively 18000 new lines of code have been added. Remarkably, almost 6000 of them were added to the documentation and another 1500 or so to the unit tests. On the other hand, we actually lost 20000 lines in an upgrade of libpng so the actual amount of the new lines in our own code is close to 15000 which is still pretty impressive.

On a less bright note we also have:

% ./trac-ticket-stats trac.wxwidgets.org 2011-07-04 today
Ticket statistics for http://trac.wxwidgets.org/timeline from 2011-07-04 to 2011-12-14:
--------------------
New              454
Closed           397
Reopened          59
--------------------
Delta            116

so while almost 400 bugs were fixed since 2.9.2, net effect is unfortunately that today we have 116 more bugs than 5 months ago.

Please help with testing 2.9.3 RC

Release candidate for the next 2.9.3 is available from SourceForge and soon will also be at FTP mirror.

Please test the distribution files and let us know about any problems you encounter with downloading, compiling or installing from them. If all goes well the final 2.9.3 should be done next week.

Thanks in advance for your help!

August Augmentations

August has been a busy month this year, with a couple of new classes being
added and several minor enhancements to the existing ones as well. Even though none of these changes is particularly major, they should hopefully be useful to wxWidgets users, just as they were useful for me when working on my projects.

---

The first of the new classes is wxBannerWindow. As you can see from the screenshot at that link, it is a particularly simple class as it is static in appearance and basically doesn't do anything except providing some information about the current window to the user and, mostly, just looking nice. Of course, it was always pretty simple to do something like this with wxWidgets and personally I had already done it a few times but having a standard class for this makes using it even easier, especially as it can also be defined in the XRC resources and so added to your existing dialogs very easily.

---

The second new class is actually not really a new class at all but a wrapper for an existing one: wxTreeListCtrl is a façade for wxDataViewCtrl which is not nearly as flexible as the full wxDataViewCtrl class but is much easier to use in a special yet common case when you just want to have a multi-column tree control, optionally with icons and, also optionally, check boxes, in the first column, like this:


What you can't see on the screenshot is that the source code of the new treelist sample is much simpler than that of the dataview sample. Of course, this simplicity comes at a price: you can't have "infinitely" many items in this control because it stores all of them internally. However if you have a control with relatively few (not more than a couple of thousands) items, then this is probably not a big problem and this control can be a simple alternative to wxDataViewCtrl. And, of course, wxTreeListCtrl features are a union of those of wxTreeCtrl and wxListCtrl and so it may also provide a simple solution if you're currently using one of those controls but need the extra features (multiple columns or hierarchical items) not available in it.

---

And then there were several enhancements to the existing classes:

• Navaneeth has contributed a useful wxTextCtrl::PositionToCoords() method allowing to find the pixel coordinates of the given character in wxTextCtrl. This allows to show auto-completion window at the right position, for example.



• wxMessageDialog and, hence, wxMessageBox(), have gained support for wxHELP button. Beyond the ability to provide help in your message boxes this is significant because you can now have up to 4, instead of 3, as before, buttons in your message boxes. And as using SetHelpLabel() you can set arbitrary text for this button, it means you can now propose more choices to the user if really necessary (an advance warning: 4 is as high as it will go).



• A new wxTextEntry::AutoCompleteDirectories() was added. Unfortunately, just as AutoCompleteFileNames(), it is currently MSW-only. But at least on this platform it makes using controls used for entering directory names in them more convenient for the user. Moreover, wxFilePickerCtrl and wxDirPickerCtrl now call the appropriate completion function automatically for their integrated text control and so you don't even need to worry about not forgetting to do it yourself if you use one of those handy controls.



• Another MSW-specific change is the addition of wxTopLevelWindow::MSWGetSystemMenu(). This function can be used to add items to the "system" window of Windows programs. Using it is inherently not portable but can still be useful even in cross-platform applications: for example, you could use it to add an "About" item to the system menu under MSW if your application doesn't have any normal menu bar. This is actually consistent with OS X where all applications have the standard "About" item in their "Apple" menu, whether they have a menu bar or not. Maybe in the future we will provide a higher level interface for this but for now this function can be helpful.



• Some cleanup was done as well: SetImageList() and AssignImageList() now work consistently for all controls, as discussed in this thread. And wxDataViewCtrl::GetSelection() now works consistently in all ports, after the changes proposed here were implemented. New, more clear, wxComboBox::IsTextEmpty() and IsListEmpty() were added to replace IsEmpty() whose behaviour was inconsistent in different port. Finally, Stefan fixed long-standing issue with Ctrl vs Cmd keys confusion in wxOSX after this discussion.

---

More new features are planned for September too, notably I'm personally planning to add a new wxTimePickerCtrl class and also wxBalloonTooltip. Any help with their development or participation in discussion of the API of the new classes is always welcome on wx-dev.