wxWidgets Developer Blog

Planning Ahead

2025-12-15T00:00:00+00:00

It’s common to recapitulate the past year as it ends, but let’s do something different and, instead of looking back at the record 6 releases we made in 2025 (it helps to introduce some bugs in them, so as to require making bug fix releases soon after, but they still count), let’s see what is coming in 2026.

First of all, we are going to release 3.3.2 relatively soon, maybe in January but hopefully not later than February. This release will bring a few new features that are already implemented in master (and are eagerly awaiting being tested, so if you’re interested in using them, please consider checking them out even before this release):

There is the new wxStyledTextCtrlMiniMap class, which implements a small map, showing a scaled-down overview of the document being edited in the main wxStyledTextCtrl and automatically synchronized with it. It is very simple to use, as it’s usually enough to just create it, see the updated stc sample for an example showing it, so there is not much to say about it, but it should be appreciated by the users. Thanks to GIANTS Software for the grant which allowed us to develop this feature!
Another new UI feature is the support for minimizing panes in wxAUI into taskbar-like docking bars. This is, again, very simple to use from the application point of view, as it’s enough to just call MinimizeButton function of wxAuiPaneInfo class when creating the pane to enable it and everything else is handled automatically by wxAUI. However there are some customization options available already and we will probably add more of them before final 3.3.2 release, so please let us know what else would you like to be able to change.
And the final relatively important recently implemented feature has nothing to do with the UI: it’s the possibility to choose between GLX and EGL-based implementations of wxGLCanvas in wxGTK. Previously this choice had to be done at compile-time, meaning that applications were forced to use EGL, even when using X11 GTK backend, where using GLX would be possible. Now it is possible to call PreferGLX function to do it in this case.
Of course, there were many other improvements and bug fixes since 3.3.1, in particular it is worth mentioning that all the third party libraries bundled with wxWidgets have been updated to their latest versions (thanks Maarten!), many bugs were fixed when using RTL writing direction (thanks Ali!), a few more classes were implemented in wxiOS (thanks Robert!) and wxStaticText has finally learnt how to wrap its contents automatically.

After 3.3.2 we will start thinking about making 3.4.0 release, which will be the first stable release with dark mode support for Windows. Right now it looks like we may not even need a 3.3.3 before it, as no other major changes are currently planned, but this may, of course, change depending on the feedback we get after 3.3.2 release.

One thing that we unfortunately almost surely still won’t have in 3.4.0 is GTK 4 support in wxGTK. This is something that will become more and more necessary with time passing, of course, but upgrading from GTK 3 to GTK 4 is a major endeavour and we’re still looking for volunteers and/or grants to make it happen. But surely if we wait for long enough, we’ll just be able to ask an LLM to write wxGTK4 for us, right?

Let me close this forecast for 2026 on this optimistic note. Happy holidays and let’s all hope for a better next year, and not just for wxWidgets!

Linux Power

2025-02-12T00:00:00+00:00

This post is (unfortunately) not about secret Linux power features, but just about handling wxPowerEvent with wxGTK under Linux. Until recently, such events were only generated in wxMSW, but now that the corresponding PR has been merged, wxEVT_POWER_SUSPENDED and wxEVT_POWER_RESUME can be generated when using wxGTK as well – however there is a small twist. Unlike under Microsoft Windows, they are not generated by default because trying to do anything in wxEVT_POWER_SUSPENDED handler could fail due to a race condition: the system might go to sleep before the handler finished its execution. To prevent this from happening, the usual pattern is to acquire a power lock, perform the required action when suspension notification is received and then release the lock to let the system suspend.

So, in an attempt to be a good Linux desktop citizen, wxGTK doesn’t generate these events until a wxPowerResourceBlocker object is created. However, because the intention here is not to prevent the system from sleeping, but just delay it for sufficiently long to allow the application event handler to run, it should be created with the (new) wxPOWER_DELAY block kind instead of the default wxPOWER_PREVENT one, e.g. like this:

wxPowerResourceBlocker delaySleep(wxPOWER_RESOURCE_SYSTEM,
                                  _("Close open files"),
                                  wxPOWER_DELAY)

The provided string is used to explain to the user why is sleep being delayed and appears e.g. in the output of systemd-inhibit tool.

Also, typically this variable would be a member variable of the application or main window class and not a local variable, so a program that wants to handle suspend/resume notifications should look like this:

#include <wx/wx.h>

class MyFrame : public wxFrame {
public:
    MyFrame() :
        wxFrame(nullptr, wxID_ANY, "My Power"),
        m_delaySleep(wxPOWER_RESOURCE_SYSTEM, _("Save changes"), wxPOWER_DELAY)
    {
        Bind(wxEVT_POWER_SUSPENDED, [this](wxPowerEvent&) {
            ... save unsaved modifications to some temporary file ...
        });

        Bind(wxEVT_POWER_RESUME, [this](wxPowerEvent&) {
            ... restore modifications from the file, if it exists ...
        });

        ...
    }

private:
    wxPowerResourceBlocker m_delaySleep;
};

class MyApp : public wxApp {
public:
    bool OnInit() override { auto* f = new MyFrame(); f->Show(); }
};

This will also work in wxMSW, but there it would work even without m_delaySleep while you need to create it when using wxGTK. And, of course, this requires some minimum system support under Linux, but it should work at least on all contemporary desktop systems using systemd.

Unfortunately power events are still not generated under macOS so, as always, further enhancements are still possible – and would be very welcome!

Hello Darkness

2024-10-29T00:00:00+00:00

wxWidgets 3.3.0 is not released yet, but there is no doubt about what will be the most important new feature in it when it does get released (hopefully some time soon): it will be support for dark mode in wxMSW, the Windows port of the library. This is “just” a cosmetic feature, but it’s also the most requested one since the entire history of wxWidgets existence, so it will be great to finally have it available, after all these years.

Of course, the delay hasn’t been just due to neglect of our users wishes. The main problem is that Microsoft still doesn’t officially support dark mode for the desktop Windows applications and so implementing it requires using undocumented API and also a huge amount of work on things not supported by those APIs, which are far from being complete.

I’m very grateful to KiCad organization for helping to solve the second part of the problem by funding my work on Windows dark mode implementation and, of course, also to all the other contributors who helped with reporting and fixing bugs. Thanks to them all, I believe that dark mode support is now in a good enough shape to be used in most applications, even though there are still some known problems, and, in fact, it’s already used in some of my own applications in production since quite some time.

However, due to the first problem, dark mode support is, and will remain, until Microsoft announces official support for it, disabled by default, and you will need to explicitly opt-in into using it. To give an example, this minimal wxWidgets application:

#include <wx/app.h>
#include <wx/artprov.h>
#include <wx/frame.h>
#include <wx/sizer.h>
#include <wx/stattext.h>

class MyApp : public wxApp {
public:
    bool OnInit() override {
        // ❶ SetAppearance(Appearance::System);
        auto f = new wxFrame(nullptr, wxID_ANY, "wxWidgets Example");
        auto s = new wxGridSizer(1);
        s->Add(new wxStaticText(f, wxID_ANY, "Hello, world!"), wxSizerFlags().Center());
        f->SetSizer(s);
        f->SetIcon(wxArtProvider::GetIcon(wxART_WX_LOGO));
        f->Show();

        return true;
    }
};
wxIMPLEMENT_APP(MyApp);

still has the same boring, old, tired appearance, even when the system uses dark mode by default, shown on the left below. However by uncommenting the line marked with ❶ in the beginning of OnInit() the appearance changes to the modern, new, wired look on the right:

Of course, this assumes that the system uses the dark look by default. If it doesn’t, the appearance would naturally stay the same, even with the SetAppearance() call. As the documentation explains, this function can also be used with Appearance::Dark argument to force the use of dark mode or, to emphasize that dark mode is not wanted, with Appearance::Light.

Also note that while calling SetAppearance() is required for dark mode support under Windows, the situation under other platforms is a bit different: because they do provide perfectly official and safe to use API for the desktop applications, the system mode is used there by default and calling SetAppearance(Appearance::System) doesn’t do anything there – however it does no harm neither and using this function to force either dark or light appearance works under the other platforms as expected too.

Finally, there is a semi-secret way of enabling dark mode support for Windows applications even if they don’t call SetAppearance(): setting the environment variable wx_msw_dark_mode to the value of 1 has the same effect as opting in into using the system appearance, while setting it to 2 forces the use of dark appearance. However, if the application does set its own appearance, this overrides the environment variable value, so this trick is really only supposed to be used for the older applications which haven’t been updated to call SetAppearance() yet.

I’d like to end this post by repeating that everything described above is available in current Git master and while dark mode support will be included in wxWidgets 3.3.0 release, you are also more than welcome to try it already and report (and maybe help fix?) any problems you find!

Survival of the Oldest

2024-10-08T00:00:00+00:00

I’ve accidentally learnt about the Git of Theseus tool today and, of course, couldn’t resist running it on wxWidgets repository. After spinning the fans for quite some time, it finished analysing it and I could create a graph showing the survival rate of the lines of code in our code:

The exponential fit here is extremely bad, which is not really surprising considering that wxWidgets consists of several parts, evolving (or stagnating) at their own rate, but it’s still interesting to see that the half-life of more than 6 years is at the very end of the range of values presented in the table at the end of the tool’s author blog post, with only Git itself (at 6.60 years) having a value significantly higher than this.

Another potentially interesting graph is that of code added by year:

which clearly shows when old ports were removed from the repository (all those cliffs) but also the most productive years in terms of code added — and that the recent years are not among them, unfortunately.

Hopefully this will change when somebody contributes GTK 4 support!

Addressing wxWebRequest Requests

2024-08-22T00:00:00+00:00

wxWebRequest is a very useful class if you need to perform some HTTPS requests from a GUI application: it’s, perhaps, not the fastest nor the most full-featured, but it doesn’t have any dependencies and provides a very simple way to do it without blocking the normal event handling of the GUI program, i.e. without making it “unresponsive”, thanks to its asynchronous nature.

However, ever since it was added, there were requests to add an even simpler way to use it in blocking, or synchronous, way, when this is affordable, for example in simple console applications or in background threads of a GUI application. And this is finally possible with wxWebRequestSync, which can be used as simply as

wxWebRequestSync request = wxWebSessionSync::GetDefault().CreateRequest("https://www.wxwidgets.org");
auto const result = request.Execute();
if ( !result ) {
    wxLogError("Request failed: %s", result.error);
} else {
    if ( request.GetStatusCode() == 200 ) {
        // Do something with the response data in request.GetResponse()
        ...
    }
}

If you’re familiar with wxWebRequest itself, you can see that the new class is similar to it as it’s still created by wxWebSessionSync very similar to wxWebSession used with asynchronous requests, but instead of starting the request and waiting to get its results at some later time via an event you can just execute it in a blocking way and get the results in the same function.

By the way, note that, because the results are provided in the same wxWebResponse object, it is possible to write console and GUI versions of the same program that execute the requests differently, but share the code handling responses.

Finally, while adding support for synchronous operation, a few other things, some of which had been also requested before, and others just looked like a good idea, were added too:

It is now possible to set a common base URL to use for all requests created by the same session using either wxWebSession::SetBaseURL() or wxWebSessionSync::SetBaseURL() depending on the kind of the requests used. This is handy when sending requests to some web API.
It is now also possible to disable the proxy or specify a proxy different from the system default with wxWebSession::SetProxy() (which also exists in wxWebSessionSync, of course). Special thanks to Apple for making it apparently impossible to do this under iOS – so this function does nothing there.
Because the world wide web is dark and full of dangers and misconfigured servers, it is also possible to disable the host name verification in the TLS certificate by calling wxWebRequest::MakeInsecure(). Hopefully you will never need to do it, but the function is there if you do.

And there was some other minor cleanup and bug fixes: notably, credentials can now be specified directly in the URL under all platforms now, including when using WinHTTP under MSW.

Of course, as with any change, all these new features could have introduced their own bugs, so if you use wxWebRequest in your applications (or maybe have just been waiting to start to do it!), please let us know if they broke anything, preferably before the 3.3.0 release which is bound to happen at some moment in the future.

Great Grid Upgrades

2024-06-22T00:00:00+00:00

There have been a couple of changes to wxGrid in wx master that are important enough to deserve their own blog post.

First of all, Dietmar Schwertberger has implemented basic accessibility support for it (see #24368), which makes it usable when using a screen reader.

Dietmar has also enhanced wxGrid in other ways, by implementing drag-resizing its row and column label windows (#24362) and making several improvements to row/column reordering (see #24303, #24363, #24619).

And, second, Ali Kettab has modified selection drawing to use much nicer “overlay” effect instead of simply changing the background colour (see #24561), here is how it now looks under Linux:

and macOS, in dark mode:

Of course, as with any changes, there is always a possibility that the new features could have changed the existing behaviour, even if we are not aware of any incompatible changes right now, so if you use grids in your application, please check how they work with the latest wx master and let us know about any regressions!

More Resourceful Property Grid

2024-02-11T00:00:00+00:00

Just a quick note to say that it is now possible to define wxPropertyGrid controls in XRC, e.g. here is a minimal example:

<object class="wxPropertyGrid" name="grid_music">
    <property class="wxStringProperty">
        <label>Name</label>
        <value>Now And Then</value>
    </property>
    <property class="wxIntProperty">
        <label>Year</label>
        <value>2023</value>
    </property>
</object>

Support for wxPropertyGrid must be explicitly enabled by registering the XRC handler for it, so the code loading the XRC file including the fragment above would look like this:

// Include declaration of the XRC handler for wxPropertyGrid.
#include "wx/xrc/xh_propgrid.h"

bool MyApp::OnInit() {
    auto xrc = wxXmlResource::Get();

    // Initialize all standard handlers.
    xrc->InitAllHandlers();

    // And add this one which is not standard.
    xrc->AddHandler(new wxPropertyGridXmlHandler);

    if ( !xrc->Load("propgrid.xrc") )
    {
        wxLogError("XRC file couldn't be loaded.");
        return false;
    }

    ...
}

The updated sample contains a more complex example of wxPropertyGridManager defined in XRC and the documentation has been updated to describe the supported elements.

Operators Are Your Friends

2024-01-12T00:00:00+00:00

Or, at least, they should be. But for most of wxWidgets history the operators defined in the library itself, for its own types, were not very friendly. For example, if you worked on your program containing the following

#include <wx/wx.h>

class MyClassWithALotOfData {
    // TODO: Implement the "a lot of data" part.
};

int main() {
    MyClassWithALotOfData first, second;
    return first == second;
}

and tried to compile it with gcc, you would get the following errors (it’s ok if your eyes glaze over when you look at them):

oper.cpp: In function ‘int main()’:
oper.cpp:9:18: error: no match for ‘operator==’ (operand types are ‘MyClassWithALotOfData’ and ‘MyClassWithALotOfData’)
    9 |     return first == second;
      |            ~~~~~ ^~ ~~~~~~
      |            |        |
      |            |        MyClassWithALotOfData
      |            MyClassWithALotOfData
In file included from /usr/local/include/wx/dialog.h:16,
                 from /usr/local/include/wx/wx.h:64,
                 from oper.cpp:1:
/usr/local/include/wx/sharedptr.h:158:6: note: candidate: ‘template<class T, class U> bool operator==(const wxSharedPtr<T>&, const wxSharedPtr<U>&)’
  158 | bool operator == (wxSharedPtr<T> const &a, wxSharedPtr<U> const &b )
      |      ^~~~~~~~
/usr/local/include/wx/sharedptr.h:158:6: note:   template argument deduction/substitution failed:
oper.cpp:9:21: note:   ‘MyClassWithALotOfData’ is not derived from ‘const wxSharedPtr<T>’
    9 |     return first == second;
      |                     ^~~~~~
In file included from /usr/local/include/wx/wx.h:14:
/usr/local/include/wx/defs.h:924:17: note: candidate: ‘bool operator==(char, const wxUniChar&)’
  924 |     inline bool operator op(T1 x, T2 y) { return y oprev x; }
      |                 ^~~~~~~~
...
... many lines snipped
...
... and when I say many, I really mean it
...
In file included from /usr/local/include/wx/dc.h:24,
                 from /usr/local/include/wx/wx.h:51:
/usr/local/include/wx/brush.h:109:13: note: candidate: ‘bool operator==(wxBrushStyle, wxDeprecatedGUIConstants)’
  109 | inline bool operator==(wxBrushStyle s, wxDeprecatedGUIConstants t)
      |             ^~~~~~~~
/usr/local/include/wx/brush.h:109:37: note:   no known conversion for argument 1 from ‘MyClassWithALotOfData’ to ‘wxBrushStyle’
  109 | inline bool operator==(wxBrushStyle s, wxDeprecatedGUIConstants t)
      |                        ~~~~~~~~~~~~~^```

with most of them snipped because the complete output contains 526 lines, with just the first 6 of them being actually relevant and the rest being uselessly confusing and ensuring that you don’t even see the first lines with the actual description of the error as they would scroll out of your terminal or IDE window.

This was due to the fact that whenever the compiler encountered an operator (any operator, not necessarily just ==) that it couldn’t match, it had to try using all of the operators defined for wxWidgets types, such as wxSharedPtr<> or wxBrushStyle appearing above, but also many, many others, and diligently report that it couldn’t use any of them. The compiler didn’t really have any choice because this is what the language rules dictate: all the operators defined in the global scope have to be considered in this case.

However there is a better way, known as “hidden friends” idiom and popularized (but probably not invented, although I’d welcome any information about who did invent this) by Anthony Williams in his blog post. So if we define these operators as friends of e.g. wxSharedPtr directly in this class declaration, they would still work just fine when used with wxSharedPtr, as intended, but wouldn’t be considered for anything else. And this is exactly what the latest wxWidgets version does, for all these operators, so that now compiling the program above results in just

oper.cpp: In function ‘int main()’:                                            
oper.cpp:9:18: error: no match for ‘operator==’ (operand types are ‘MyClassWithALotOfData’ and ‘MyClassWithALotOfData’)
    9 |     return first == second;                                                                                    
      |            ~~~~~ ^~ ~~~~~~                                                                                     
      |            |        |                                                                                          
      |            |        MyClassWithALotOfData                                                                      
      |            MyClassWithALotOfData

and nothing else, making the error immediately clear and obvious.

Moreover, even if there are no errors, there are still benefits to the new approach: compiler has to consider fewer candidates and so compilation process is faster, too.

Of course, as always, there are some caveats. The main, and most important one, is that this change is not fully backwards-compatible: if you previously had some type implicitly convertible to e.g. wxString, you could compare it with wxString or anything string-like via this implicit conversion and operator==() defined by wxWidgets. This is not the case any longer and while this is not always a problem – and could, indeed, fix unwanted comparisons and other operators being available for your type – it may be, in some cases, and you will have to convert the objects to wxString explicitly or define your own operator now.

The second one is that Microsoft C++ compiler in its infinite wisdom still considers even the hidden friend operators when looking for overload candidates. This helpful behaviour can be disabled by using /permissive- compiler flag which is done implicitly if you use /std:c++20 with this compiler (which is recommended if possible, of course).

But globally this should be a big improvement and wxWidgets-defined operators shouldn’t get in your way when using operators with your own types ever again.

Using XDG-compliant Config Files

2024-01-07T00:00:00+00:00

XDG Base Directory Specification has been a standard for organizing application data files under Linux for a long time. Unfortunately, wxWidgets has been around for even longer, and when support for configuration files was added to it back in 1997, the usual convention was still to put these so-called “dot files” directly in the user home directory, which is why an application called myapp would use ~/.myapp as its configuration file by default and this default couldn’t be just changed because this would make the existing applications “lose” their configuration files, annoying their users.

However if this wasn’t a concern, applications can (and this isn’t exactly new as this function exists since many years – thanks to Martin Kögler for contributing it) call

wxStandardPaths::Get().SetFileLayout(wxStandardPaths::FileLayout_XDG);

to have their new files created in XDG-compliant ~/.config directory (or $XDG_CONFIG_HOME if this variable is defined, of course).

This was an easy, and recommended way to use the standard locations for the new programs. However it didn’t completely solve the problem because you had to know about it in order to do add this call to a new application and for the other ones there was still the vexing question of what to do with their existing installations.

So, here is the good news: two recent changes in wxWidgets do, finally, solve this problem fully. First of all, since wxWidgets 3.3.0 wxFileConfig defaults to creating new files under ~/.config by default, even without using FileLayout_XDG, if there is no existing dot file in the home directory. Unlike changing the file layout globally for all functions, this is broadly backwards-compatible because the existing installations are not affected: if there already was a dot file in the home directory, it will still be used. But if the application runs on a new system for the first time, it will behave correctly and avoid polluting the home directory with its files, creating them under ~/.config instead.

And, second, if you’d like to change the configuration file location to the recommended one even for the existing users of your application, this is now as simple as just calling the new wxFileConfig::MigrateLocalFile() function: it does what its name implies and migrates the existing local configuration file to the new location. It is not limited just to this, but the intended use case is, of course, for the applications not already using XDG to call it with wxCONFIG_USE_XDG flag, as following:

// Execute this early during the application startup, before the
// global wxConfig object is created.
const auto res = wxFileConfig::MigrateLocalFile("myapp", wxCONFIG_USE_XDG);

This will do nothing if there is no existing ~/.config/.myapp file and will move this file to the new location, i.e. ~/.config/myapp/myapp.conf, if it does exist. Or, rather, it will try to move it, but it might fail, so you will also want to check for errors, e.g. like this:

if ( !res.oldPath.empty() ) {
    if ( res.error.empty() )
        wxLogMessage("Config file moved from \"%s\" to \"%s\"", res.oldPath, res.newPath);
    else
        wxLogWarning("Migrating old config failed: %s.", res.error);
}

And if it did succeed, which should normally be the case, wxFileConfig will use the file in the new, XDG-compliant, location by default, you don’t have anything special to do.

To summarize, wxFileConfig default behaviour has now changed to be what most people would expect and creating new files in the correct location doesn’t require any effort at all, while moving the existing ones to it is as simple as adding a single function call. However if, for some reason, you’d like to keep the old behaviour, you now need to specify the new wxCONFIG_USE_HOME flag when creating wxFileConfig to force using home directory for the configuration files, no matter what.

Hopefully this will help wx applications to stop using configuration files in the home directory in 2024!

Initializer List and Ambiguous Overloads with 3.1.4

2023-11-30T00:00:00+00:00

If you have started getting compilation errors about “ambiguous overload” after updating to wxWidgets 3.1.4, you have unfortunately run into this bug which got inadvertently introduced in this version, while trying to make wxWidgets array classes more comfortable to use.

The problem happens whenever you have a function overloaded to take more than one class that can be implicitly constructed from std::initializer_list<>, e.g.

void DoSomethingWithString(const std::vector<wxString>& strings);
void DoSomethingWithString(const wxArrayString& strings);

and then calling it with an initializer list like

DoSomethingWithString({"Now", "and", "Then"});

The preferred fix for these problems is to explicitly specify the overload to use, for example:

DoSomethingWithString(std::vector<wxString>{"Now", "and", "Then"});

but if you have many instances of this problem and use wxWidgets 3.1.5 (or the latest 3.2 branch until this version is released), you may want to add -DwxNO_INITIALIZER_LIST to the compiler options to prevent the new overloads added in wxWidgets 3.1.4 from being defined.

Sorry about introducing this problem and hopefully this post can help you with solving it!

Are Macros Required To Use wxWidgets?

2023-05-01T00:00:00+00:00

As anybody familiar with the Betteridge’s law of headlines could immediately tell, the answer to the question in the title is, of course, “No” and the goal of this post is to debunk the myth that using wxWidgets C++ API involves dealing with macros.

Of course, as anybody familiar with the mythology could also tell, like many good myths, this one is based on the real events, and even if these events happened in the distant past, they left their trace in the historical record, including various forum posts, tutorials and even wxWidgets own samples, few of which have been updated to follow the best practices. So you are still unfortunately very likely to see programs like this, written in the “classic” (which is the polite term for “old and hoary”) style:

// Complete, compilable example using old style.
#include <wx/wx.h>

class MyFrame : public wxFrame {
public:
    MyFrame() : wxFrame(nullptr, wxID_ANY, L"Hello old wxWidgets!") {
        SetBackgroundColour(*wxWHITE);
        Show();
    }

private:
    void OnPaint(wxPaintEvent&) {
        wxPaintDC dc{this};
        dc.SetTextForeground(*wxBLUE);
        dc.Clear();
        dc.SetFont(dc.GetFont().Scaled(2));
        dc.DrawLabel(L"This uses macros :-(", GetClientSize(), wxALIGN_CENTER);
    }

    void OnSize(wxSizeEvent&) { Refresh(); }

    wxDECLARE_EVENT_TABLE(); // ❶ Event table declaration macro.
};

wxBEGIN_EVENT_TABLE(MyFrame, wxFrame) // ❷ Event table definition macro.
    EVT_PAINT(MyFrame::OnPaint) // ❸ Event handlers macros.
    EVT_SIZE(MyFrame::OnSize) // ❸ 
wxEND_EVENT_TABLE()

class MyApp : public wxApp {
public:
    MyApp() = default;

    bool OnInit() wxOVERRIDE { // ❹ Pre-C++11 portability macros.
        if (!wxApp::OnInit())
            return false;

        new MyFrame();

        return true;
    }

    wxDECLARE_NO_COPY_CLASS(MyApp); // ➎ Pre-C++11 equivalent macros.
};

wxIMPLEMENT_APP(MyApp); // ➏ Application definition macro.

But, of course, none of the macros used here are required and most of them are not recommended since a very long (10+ years). In particular, there is no reason to ever use macros ➍ or ➎ that only made sense for C++98 support and there are rarely any good reasons use the event table macros in any new code (and “new” here applies to anything written since 10+ years ago), as using Bind() is almost always preferable, so all event handler macros like ❸ can, and should, be replaced with the calls to Bind() and the macros ❶ and ❷ removed entirely, resulting in this version:

// Complete, compilable example using new style.
class MyFrame : public wxFrame {
public:
    MyFrame() : wxFrame(nullptr, wxID_ANY, L"Hello modern wxWidgets!") {
        Bind(wxEVT_PAINT, &MyFrame::OnPaint, this);
        Bind(wxEVT_SIZE, [this](wxSizeEvent&) { Refresh(); });

        SetBackgroundColour(0xffffff);
        Show();
    }

private:
    void OnPaint(wxPaintEvent&) {
        wxPaintDC dc{this};
        dc.SetTextForeground(wxColour(0x00, 0x00, 0xff));
        dc.Clear();
        dc.SetFont(dc.GetFont().Scaled(2));
        dc.DrawLabel(L"Look, no macros!", GetClientSize(), wxALIGN_CENTER);
    }
};

class MyApp : public wxApp {
public:
    MyApp() = default;

    MyApp(MyApp const&) = delete;
    MyApp& operator=(MyApp const&) = delete;

    bool OnInit() override {
        if (!wxApp::OnInit())
            return false;

        new MyFrame();

        return true;
    }
};

wxIMPLEMENT_APP(MyApp); // The only macro still remaining.

By the way, this shows that using Bind() we may avoid not only using the event table macros, but even avoid defining event handler functions entirely, as we did for OnSize() which was replaced with a lambda – although, of course, it may still be a good idea to keep the event handling in a separate function if it is less trivial, like OnPaint().

In fact, using Bind() allows to avoid defining a separate class at all, if its only purpose was to define event table handlers, and the whole program may instead be written in the following simpler way:

// Complete, compilable example using new style without a separate frame class.
#include <wx/wx.h>

class MyApp : public wxApp {
public:
    MyApp() = default;

    MyApp(MyApp const&) = delete;
    MyApp& operator=(MyApp const&) = delete;

    bool OnInit() override {
        if (!wxApp::OnInit())
            return false;

        auto const win = new wxFrame(nullptr, wxID_ANY, L"Hello wxWidgets!");

        win->Bind(wxEVT_PAINT, [win](wxPaintEvent&) {
            wxPaintDC dc{win};
            dc.SetTextForeground(wxColour(0x00, 0x00, 0xff));
            dc.Clear();
            dc.SetFont(dc.GetFont().Scaled(2));
            dc.DrawLabel(L"No class to look at!", win->GetClientSize(), wxALIGN_CENTER);
        });

        win->Bind(wxEVT_SIZE, [win](wxSizeEvent&) { win->Refresh(); });

        win->SetBackgroundColour(0xffffff);
        win->Show();

        return true;
    }
};

wxIMPLEMENT_APP(MyApp); // The only macro still remaining.

The remaining macro could be avoided too, as we could replace it roughly with the following (please note that it’s not quite the exact equivalent):

#ifdef __WXMSW__
extern "C" int WINAPI
WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, wxCmdLineArgType lpCmdLine, int nCmdShow) {
    wxApp::SetInstance(new MyApp{});
    return wxEntry(hInstance, hPrevInstance, lpCmdLine, nCmdShow);
}
#else
int main(int argc, char* argv[]) {
    wxApp::SetInstance(new MyApp{});
    return wxEntry(argc, argv);
}
#endif

but comparing the two versions side by side, it’s easy to see why many applications still use wxIMPLEMENT_APP().

However this is just one, single macro that is still acceptable to use. Not only the event table macros don’t have to be used, but not using them can often make the code shorter and simpler and more readable, by keeping the event handling logic in a single place.

So just say no to the macros and let’s finally kill the myth that wxWidgets requires using them.

Separate STL Build Is No More

2023-04-18T00:00:00+00:00

Since almost 20 years (see this commit) wxWidgets had a separate “STL build mode”, in which it used the standard library classes instead of the legacy code originally written even earlier because the standard library hadn’t been universally available under all platforms back then. This build mode provided better interoperability with the rest of the code, using the standard C++, at the cost of less than perfect backwards compatibility.

The bad news is that the separate STL build mode doesn’t exist in wxWidgets 3.3 any more. But the good news is that it doesn’t exist because using standard library is now the default and, in most places, the only supported option (amazingly, even in 2023, we still have to use our own code instead of std::unordered_map when using gcc 4.8). Globally, this is, of course, a very good change as it’s not necessary to set any options to make wxWidgets use standard classes any longer and, in particular, distribution-provided packages under Linux or other packaged wxWidgets binaries (provided by Homebrew, vcpkg etc) will now use them.

So, mostly, the news is: all containers used by wxWidgets are now standard containers under the hood and you should treat them as such, ignoring any non-standard member functions they may also have for compatibility reasons.

Unfortunately, as usual, there is some price to pay for this in terms of backwards compatibility. This is briefly documented in the incompatible changes section of the changelog, but this post will go into a bit more details about how you may need to update your code when upgrading to wxWidgets 3.3. There are two non-overlapping cases that we’ll cover separately below:

Upgrading from non-STL build

The first case is about upgrading the code which used the default build of the library, with wxUSE_STL==0. Such code should mostly continue to compile and work unchanged if it was already upgraded to use compatibility_iterator to iterate over the various linked lists. If it still uses wxNode-based iteration, i.e. contains any fragments like this

    // Existing code which only compiles in non-STL build mode of wx < 3.3.
    const wxWindowList& children = someWindow->GetChildren();
    for ( wxWindowList::Node* node = children.GetFirst(); node; node = node->GetNext() ) {
        wxWindow* const child = node->GetData();
        // ... do something with the child ...
    }

you need to update it to use compatibility_iterator, recommended since wxWidgets 2.5.0, and working in any build, and with any wx version. This can be done by just changing the type of node variable above, i.e. writing

    // This code compiles in both STL and non-STL build with any wx version.
    const wxWindowList& children = someWindow->GetChildren();
    for ( wxWindowList::compatibility_iterator node = children.GetFirst(); node; node = node->GetNext() ) {
        wxWindow* const child = node->GetData();
        // ... do something with the child ...
    }

Of course, this is the absolutely minimum change and you might prefer to update this code to use the real iterators instead or even get rid of the explicit iterators and use the range for loop:

    // This code also compiles with any wx 3.x version.
    for ( const wxWindow* child : GetChildren() ) {
        // ... do something with the child ...
    }

but this is not required.

The only other changes that may be required are to the code which used legacy containers that were never part of wxWidgets public API. As wxWidgets itself doesn’t use them any longer (note that this doesn’t apply to the legacy containers that were, and still are, part of the public API, such as wxWindowList shown above), you can simply update your code to use std::vector<>, std::list<> or std::unordered_map<> instead of the containers based on wx array/list/hashmap macros.

Upgrading from STL build

The other situation is when the existing code base already used the STL build, i.e. used --enable-stl configure option or set wxUSE_STL=1 in some other way. While using all wxWidgets containers in such code will continue to work without any changes, there is another backwards-incompatible change that may still affect it: traditionally, STL build enabled implicit conversions of wxString to std::string and std::wstring. This always was a rather poor idea and is now not done any more. If your code relied on such conversions, consider modifying it to use ToStdString() or, usually more convenient, utf8_string() for converting to std::string and ToStdWstring() for converting to std::wstring explicitly instead.

But if doing this is too difficult, you may set the wxUSE_STD_STRING_CONV_IN_WXSTRING build option to 1 to enable these implicit conversions again.

For completeness, please note that implicit conversions to const char* and const wchar_t*, which used to be disabled in the STL build in the previous wxWidgets versions, are now enabled by default, for compatibility with the non-STL build. You may want to disable them by predefining wxNO_IMPLICIT_WXSTRING_CONV_TO_PTR when compiling your code. Note that, unlike changing wxUSE_XXX, this does not require rebuilding the library itself and can be used with the standard binaries.

Conclusion

Most of the existing code should continue to work without any changes with wxWidgets 3.3, but some code may need to be updated. Please try building your code with the current Git master or 3.3.0 once it is released and if you run into any problems not mentioned here, please open an issue about them, so that we could fix them before the final 3.4 release, which is still some time off. Thanks in advance!

Custom Controls in File Dialogs in 3.2.0

2022-06-28T00:00:00+00:00

One long-standing problem in wxMSW was that, until now, we were still using old-style Windows file dialogs that looked out of place under modern Windows versions in some cases. To be more precise, wxFileDialog switched to using the old-looking dialog when its SetExtraControlCreator() function was called to add some custom controls to it, resulting in dialogs like this:

This will finally be fixed in wxWidgets 3.2.0 where the same dialogs now looks as expected:

provided the new SetCustomizeHook() function is used to customize the dialog instead.

The switch to the new API is, unfortunately, required, as the new-style Windows file dialogs simply don’t provide the degree of customization that was allowed by the old wxWidgets API (but please note that the old API still continues to work, i.e. backwards compatibility is 100% preserved, it’s just that using it still results in an old-style dialog being shown).

Using it is quite different from the old one, but should be relatively straightforward. The simplest possible example is shown in the dialogs samples and looks like this:

#include "wx/filedlg.h"
#include "wx/filedlgcustomize.h"

void SomeFunction() {
    class EncryptHook : public wxFileDialogCustomizeHook {
    public:
        void AddCustomControls(wxFileDialogCustomize& customizer) override {
            m_checkbox = customizer.AddCheckBox("Encrypt");
        }

        void TransferDataFromCustomControls() override {
            m_encrypt = m_checkbox->GetValue();
        }

        bool Encrypt() const { return m_encrypt; }

    private:
        wxFileDialogCheckBox* m_checkbox = nullptr;

        bool m_encrypt = fase;
    };

    EncryptHook customHook;
    dialog.SetCustomizeHook(customHook);

    if ( dialog.ShowModal() == wxID_OK ) {
        // Use customHook.Encrypt() here
    }
}

As you can see, using the new API involves defining a new class inheriting from wxFileDialogCustomizeHook and implementing its AddCustomControls() pure virtual function to actually add the custom controls to the dialog. The available controls are restricted to a few basic ones, see wxFileDialogCustomize documentation for the list of available AddXXX() methods, but should cover all the usual needs. Similarly, the controls created by these functions are not the usual wxWidgets controls, but provide the basic expected functionality, e.g. as can be seen above, wxFileDialogCheckBox has the same GetValue() method as wxCheckBox, and similarly for the other wxFileDialogXXX classes.

Once the controls are created, they can be updated while the dialog is shown by overriding UpdateCustomControls() virtual function (not shown here), and their values must be saved when TransferDataFromCustomControls() is called, which only happens if the dialog was accepted by the user.

Note that there is no control over the layout in the new API, it is determined by Windows itself, with more or less satisfactorily results depending on the size of the dialog. Generally speaking, using just a few controls will work well, while creating too many of them will probably result in less great results. Of course, if precise control over the controls positioning is absolutely needed, there is still always the possibility to use the old SetExtraControlCreator() function, which is one of the reasons it hasn’t been deprecated – but in most cases you should use SetCustomizeHook() instead and update the existing code to use it.

Last, but not least, the reason for taking so long to finally address this problem is due to the fact that implementing the new API required quite a non-trivial amount of work and it was finally only made possible by generous funding from KiCad project – so thanks a lot to KiCad for making it possible to include this enhancement in wxWidgets 3.2 (but I’ll still take sole credit for all the bugs in the implementation, of course)!

Sizer Asserts in wxWidgets 3.1

2021-06-01T00:00:00+00:00

When updating an existing application to wxWidgets 3.1, you may encounter new assertion failures in the code which seemed to work fine previously, with older wxWidgets versions. For example, a message box telling you that “only horizontal alignment flags can be used in vertical sizers” when adding an element to a wxBoxSizer or that “wxEXPAND flag will be overridden by alignment flags” when doing it with a wx(Flex)GridSizer might pop up where previously nothing was shown. What’s going on here and what should you do about it?

These asserts are indeed new in wxWidgets 3.1 and were added to help you to detect incorrect use of the sizer flags to avoid head-scratching moments when you wonder why exactly is wxEXPAND you had specified doesn’t seem to have any effect – now you’re immediately going to get the message above when developing that will hopefully save you time and frustration. However, unlike most other asserts, that usually indicate a serious problem in the program, these asserts can be safely ignored because they only warn you about the sizer flags not having the effect that you might expect them to have, but nothing catastrophic happens if you just continue running the program after them.

Moreover, these asserts, as all the other ones, are only useful to the program developers, not its users. Of course, in theory, the users are never supposed to see them at all because the production versions of the program should be built with NDEBUG defined, as explained in the debugging overview in the manual, but in practice many projects forget to do it and thus asserts remain active even in the production (also known as “release”) builds. This is a more general problem that you should definitely address in your project build system in any case, but in the meanwhile, if you’re using such a project and can’t modify its build system to rebuild it with NDEBUG, we have provided, since the commit 1d6c740f3b (Disable sizer flag checks if WXSUPPRESS_SIZER_FLAGS_CHECK is set, 2021-05-20), which will be included in wxWidgets 3.1.6 release, an escape hatch allowing to avoid these asserts if you’re not the program developer and these asserts are just annoying, rather than useful, to you.

TL;DR: You can define WXSUPPRESS_SIZER_FLAGS_CHECK environment variable to avoid these asserts if you just want to run the program, e.g. do

export WXSUPPRESS_SIZER_FLAGS_CHECK=1

before running it.

And if you’re the program developer, it is recommended to fix these asserts which is usually as simple as removing the offending flags that have no effect anyhow – but may sometime indicate the previously unknown defects in your layout, that should be fixed in some more extensive way. In some very extreme cases (e.g. hundreds of windows auto-generated by some GUI layout tool and triggering these asserts), you can also call the static wxSizerFlags::DisableConsistencyChecks() function to globally disable these asserts for your programs, but this is strongly not recommended

wxWidgets in 2020 and beyond

2021-01-03T00:00:00+00:00

To keep up with the tradition, here is our slightly belated Happy New Year post! We all hope that 2021 will be better than 2020 – which is, admittedly, not a very high bar to clear – and we, in particular, also hope to finally make wxWidgets 3.2.0 release this year, after successfully failing to do it in 2020 again.

This doesn’t mean that nothing got done, however: in 2020 there were 2010 commits in the main wxWidgets repository from 88 contributors, changing 3375 files, and, beyond these statistics, we even managed to make not one but two releases (3.1.4 and 3.0.5).

As the result of all this work, we are close to making 3.1.5 which should be the last release before 3.2.0 which will become the new stable version, after 3.0.0 released back in 2013. It will have too many enhancements and improvements to list in this blog post without turning it into a book, but just for the changes specifically in 3.1.5, I’m very glad that we will finally have a built-in way to use HTTPS from wxWidgets when Tobias’ pull request is merged.

Of course, we already know that we won’t have everything that we’d like to have in wx 3.2. In particular, this version unfortunately won’t support GTK 4 as its API is so incompatible with the previous GTK versions that huge parts of wxGTK would have to be rewritten and we currently don’t have any resources for this (but then wxWidgets was always based on the efforts of volunteers, so there is always hope that someone could contribute GTK 4 support). It will, however, have better support for modern Linux systems with Wayland and EGL improvements and also support for the latest macOS systems, including macOS 11 Big Sur and M1 (“Apple Silicon”) architecture.

Thanks for reading and happy New Year once again!

Vadim Zeitlin, on behalf of wxWidgets development team.

Implicit and explicit encoding of wxString data

2020-08-31T12:00:00+00:00

This blog post is about encoding and decoding non-ASCII characters in wxString’s.

TL;DR: Define the macro wxNO_IMPLICIT_WXSTRING_ENCODING if you want your compiler to refuse to convert wxStrings to and from C strings, unless you explicitly indicate the encoding.

The dim and distant past

A long time ago, when wxWidgets 2.8 ruled the world, developers had to choose between two different wxWidgets builds: “Unicode” and “ANSI”. Anyone living (or exporting their software) out of the United States probably chose the Unicode build, because it allowed them to work with non-ASCII strings, containing accented letters, umlauts and other funny symbols foreign languages like to use.

The biggest downside of the Unicode build was that every literal string had to be wrapped by the wxT() macro, in order to be transformed into a wxString. Standard const char * strings were not allowed as wxStrings in Unicode builds.

    wxString english = wxT("We the people...");
    wxString italian = wxT("L'Italia è una Repubblica...");

The wxT() macro had two different meanings, depending on the current build. In ANSI builds, it was a no-op. In Unicode builds, it was equivalent to a L, indicating that the literal string was “wide”, i.e. based on wchar_t rather than char.

The closer past

One of the great improvements of wxWidgets 3.0 over the previous versions, was that Unicode builds were the default, but more important, the wxT() macro was not necessary any more and was declared obsolete.

Finally, developers could use plain const char * for literal strings all over the place, with all their à’s, ü’s and ø’s, knowing that their compiler, wxWidgets and their operating system would know what to do.

Or maybe not.

Some users were in fact noticing that the same code was working well on a platform, while on another platform the contents of some strings were lost because their encoding or decoding failed silently.

The default behavior of the “automatic” encoding and decoding of wxString’s was found to be “unsafe” and a new macro was born to prevent problems: wxNO_UNSAFE_WXSTRING_CONV.

Encodings galore

This chapter is about string encoding. You can skip it if you already know what Unicode, ASCII, ISO-8859-1 and UTF-8 are. You can also refer to the document “Unicode support in wxWidgets” for more details on the Unicode Standard and how wxWidgets implement it.

The main problem with “standard” (i.e. non-wide) strings in today’s globalized world, is that one char is “only” 8 bits, and therefore it cannot represent any symbol from any language being spoken today. The ASCII encoding, for example, does not contain any accented letters.

The first solution to this problem was to “amend” ASCII, assigning language-specific symbols to the characters above number 127. This was a good solution, as long as you did not need to display, say, Russian and German messages in the same program. 8 bits could have been enough for one language, but not for all of them at the same time. And for other languages, such as Chinese, they were not even enough.

The second solution was to enable multi-byte encodings. If 8 bit were not enough, then 16 could suffice, or maybe even 24 or 32.

Quoting Andrew S. Tanenbaum, the nice thing about standards is that you have so many to choose from. There is no “silver bullet” encoding, and you and wxWidgets must be ready to support all (or at least many) of them.

In order to make encodings inter-operable, you need a “super-encoding” that could represent all possible characters, symbols, letters etc. That’s the Unicode Standard.

Strings should then be considered “Unicode strings”. Rather than “characters”, they are made of “code points”. A code point can represent a character, a part of it or even something else, like information on spacing or line breaking. There is no possibility to confuse an “À” with a “╖” in the Unicode world, because every character of every language can be represented by one or more code points.

Encodings, then, can be seen as ways to convert characters between the perfect world of Unicode, and whatever “limited” encoding you are currently using on your computer. The process of converting text to Unicode is called “decoding”, whereas representing Unicode codepoints into your current encoding is called “encoding”.

In wxWidgets, Unicode strings are represented as wide strings. The most expert readers would argue that wchar_t strings are also encoded, but we can ignore this detail as it should not affect us practically: wide strings are the closest we can get to the ideal Unicode world. The wxMBConv and derived classes are used to convert between wide and narrow strings. Following the terminology we just introduced, it is enough for us to understand that “encoding” means converting wide to narrow strings, and “decoding” means converting narrow to wide strings.

What’s my encoding and how do I choose it?

We will discuss decoding strings first, but the same logic will apply to encoding them.

There are three ways to create a wxString from a literal string:

Wide character strings. When you declare them (remember, this was the case of the now-obsolete wxT() macro), you are asking your compiler to decode them into Unicode. You just need to tell your encoding to GCC, Visual Studio or whatever build system you are using, and you can rely on them for exact decoding of all your strings.
Explicit encoding. Use the wxString constructor or any other factory method that explicitly indicates the encoding. For example: wxString::fromASCII() or wxString::fromUTF8(). In this case, your code is responsible for indicating the correct encoding.
Rely on the default wxString constructor, letting it “guess” the encoding for you. This is the “implicit” way, allowed since wxWidgets 3.0. This is based on the operating system’s choice of the best encoding for the current user, at run time. This encoding is called wxConvLibC.

This post is about disabling choice 3. above, in case you want to be 100% in control of your strings.

For example, if Linux is your primary choice for developing and testing your software, your CPP files will probably be encoded in UTF-8, because that is the standard nowadays.

If you compiled the same CPP files on Windows, the same strings may be decoded incorrectly, because Windows is not currently adopting UTF-8 as standard for all languages, and wxConvLibC could rather choose Windows-1252 if you are in Europe.

As stated at the beginning of this paragraph, the same applies to encoding wxStrings. You can:

request a wchar_t representation with method wxString::wc_str(),
call method wxString::mb_str() explicitly indicating the encoding (for example wxConvUTF8),
call method wxString::mb_str() without any parameters, i.e. requesting wxConvLibC.

Why do we need another macro?

wxWidgets 3.0 never took away from you the possibility to indicate encodings explicitly, or to use wide character strings for all your literals. But there may be many places where the conversions are done… implicitly, under the hood, with no notice.

The purpose of the wxNO_IMPLICIT_WXSTRING_ENCODING macro is to disable all such conversions, so that they would just not compile. It is designed to help developers spot all the places where they are not indicating the encoding explicitly.

You are free to use it, or not. By default it is not defined, so if you want to activate it, you have to change your build configuration, as suggested in the blog post for the wxNO_UNSAFE_WXSTRING_CONV macro linked above.

As a side note, the new macro implies the old one: if you disable any implicit en/decoding, you are also disabling the unsafe ones.

Conclusion

The wxNO_IMPLICIT_WXSTRING_ENCODING macro tries to be an additional help to developers, who want to be extra-sure that their software will work well on any computer worldwide.

In the intentions of the wxWidgets’ developers, this macro must not introduce any breakage to currently working code, when not activated.

If your software is being affected in any ways by this new macro, and you are not defining it, then please contact them because they may need to fix something.

Grid selection

2020-04-15T00:00:00+00:00

If you’ve ever used wxGrid, you probably must have had some questions about the handling of the selection in its API. The class provides several methods, such as GetSelectedCells(), GetSelected{Rows,Cols} and GetSelectionBlock{TopLeft,BottomRight}() and it’s not always clear when each of them should be used and what do they return and, especially, what they don’t return.

The bad news is that now there is one more method, GetSelectedBlocks(). But the good news is that the new method replaces all of the previous ones, can be called in any grid selection mode and always returns all the selected cells, whether they’re selected individually or as parts of rows, columns or blocks. And, as an extra bonus, this method is also more convenient to use from C++11 code as it returns an object that can be iterated over range-based for loops:

    for ( const auto block: grid->GetSelectedBlocks() ) {
        // Handle the block, e.g. check if it touches the given area.
        if ( block.Intersects(myBlock) ) {
            ...
            break;
        }
    }

The type of block in the loop above is wxGridBlockCoords, which is a very simple class containing 4 integers describing the block top-left and bottom-right corners. It provides a couple of useful operations such as Intersects() shown above or Contains(), but mostly you would just use its simple accessors to get the cells covered by this block, e.g.

        if ( block.GetLeftCol() == 0 &&
                block.GetRightCol() == grid->GetNumberCols() - 1 ) {
            // This block contains rows from block.GetTopRow() to
            // block.GetBottomRow() inclusive -- possibly just one of them.
        }

Note that you can still use wxGrid::IsInSelection() to just check if the given cell is selected, but for any other use of the selection, and in particularly if you need to operate on the entire rows or columns, you use wxGrid::GetSelectedBlocks() from now on – i.e. starting with wxWidgets 3.1.4.

Finally, as part of the work on improving grid selection handling, its user-visible behaviour has also been completely overhauled and enhanced in too many ways to list here but, to summarize, the various combinations involving Shift, Ctrl and cursor arrow or space keys now work as expected in all grid selection modes and so does clicking on row or column headers and even using both of them together, whereas previously this could result in quite interesting, to put it mildly, and rather unpredictable, selection changes.

wxWidgets and vcpkg

2019-01-14T00:00:00+00:00

Something that may have flown under your radar since its creation in 2016 is Microsoft’s vcpkg, “A C++ package manager for Windows, Linux and MacOS”. It’s been steadily improving since release, and while I’ve only used its Windows incarnation, I can attest that it brings the overhead of working with third-party C++ libraries down to almost nil.

Set up with wxWidgets in 5 minutes

_{^{Network and compiler speed depending.}}

Prerequisites: Visual Studio on Windows, gcc on Linux or Clang on MacOS, Visual Studio Code on Linux/MacOS.
Install vcpkg (full instructions at https://docs.microsoft.com/en-us/cpp/vcpkg).
- git clone https://github.com/Microsoft/vcpkg
- bootstrap-vcpkg.bat (for Windows) or ./bootstrap-vcpkg.sh (for Linux/MacOS)
Install wxWidgets (using your platform’s default triplet, e.g. x86-windows or x64-linux.cmake).
- vcpkg install wxwidgets
- This will take a little while. Pause the timer and go grab a beverage
Make wxWidgets available to Visual Studio or Visual Studio Code.
- vcpkg integrate install
Use wxWidgets in your project of choice. Just #include wx headers as normal. Delete any existing references to wxWidgets in your include or library directories. You may need to add the preprocessor definition WXUSINGDLL if the project did not previously reference wxWidgets.
- If you are using Windows and Visual Studio, try this console hello world app. All you need to do is clone and build it.

Why bother?

vcpkg automatically builds the latest version of each installed library from source on your local machine, guaranteeing compatibility. For hands-free local dependency management you can use the implicit integration demonstrated above, and to cut down on third party build time and hassles across a team you can export as-built bundles of one or more libraries (e.g. wxWidgets, sqlite and boost) to be consumed by MSBuild/Visual Studio, CMake or custom tooling.

By using a combination of vcpkg and exported packages, it’s now easy to set up a project such that developers working with the wxWidgets framework can keep their team up to date almost effortlessly, and developers working on non-framework areas never need to consider it at all.

Using wxWidgets with MSVS

2018-11-18T00:00:00+00:00

If you are using a less than 10 year old version of Microsoft Visual Studio (i.e. 2010 or later), configuring your project to work with wxWidgets will become even simpler in the upcoming 3.1.2 release. Instead of configuring the library include and library paths and preprocessor definitions, all you have to do to use wxWidgets from a project now is to add wxWidgets property sheet to it using the “View|Property Manager” menu item in the IDE or by just editing your project file directly and adding a line such as

<Import Project="3rdparty\wx\wxwidgets.props">

to it after any existing similar “Import” lines. This particular example assumes that you use wxWidgets as a submodule in your main Git repository under 3rdparty/wx path, but any path can be specified, including a full path to a directory outside of the repository or $(wxwin) environment variable.

You still need to either build wxWidgets yourself (which is as simple as opening and building build/msw/wx_vcN.sln file matching your compiler version) or download the binaries, but there is nothing else to do now and, in particular, no fiddling with the various project options is required.

A Tactical Retreat

2018-09-02T00:00:00+00:00

If a “retreat” is the antonym of “advance”, then we’ve just made one by removing all the contents of the wxAdvanced library, affectionately known as “adv”. This library used to contain a hodge-podge of classes having nothing much to do with each other except not naturally belonging to any other library and being considered too “advanced”, in some vague sense of the word, to be in wxCore. Just the trouble of explaining what it was shows why it was a bad idea to have it in the first place and we have decided to not perpetuate this mistake any more by moving all of its contents to wxCore itself.

This change is perfectly backwards compatible for now, and will remain so in wxWidgets 3.2, as we still provide an empty “adv” library for compatibility, so that the existing projects linking with it continue to work. You just don’t need to do it any longer, i.e. you can simply remove all references to this library now. E.g. if you’re currently using wx-config --libs std,adv,html when linking your program under Unix, just use wx-config --libs std,html instead.

The empty compatibility husk of wxAdvanced will only be removed in some distant future, so there is no real urgency with upgrading your make- and project files, but at the very least remember that you don’t need to link with it any more when creating new projects.