WinRT

This page is here for historical reasons, but the port to WinRT is largely complete.

Qt for WinRT

Qt 5.3 Documentation

Qt for WinRT is part of the Qt 5.3 release and the following pages contain its documentation:

• http://doc.qt.io/qt-5/winrt-support.html - reference documentation
• http://wiki.qt.io/WinRTBuild - how to build Qt for WinRT

Porting Qt 5 to Windows Runtime (WinRT/Windows 8 Metro)

While WinRT is, in many ways, the same old Windows, many APIs have been "replaced or removed":http://msdn.microsoft.com/en-us/library/windows/apps/br211377.aspx. As such, most of Qt's Windows private implementations (PIMPLs) require "refactoring":http://msdn.microsoft.com/en-us/library/windows/apps/hh464945.aspx. In other words, Windows Store applications (Appx apps) have sandbox requirements that suggest a considerable overhaul of Qt's Windows internals.

Note: this page was created to track some of the finer details of the porting needs. See Qt 5 on Windows 8 and Metro UI for the rest of the story.

A new platform

The closest thing to WinRT in Qt's supported platform list is probably WinCE. Not insomuch as the platforms are similar, but rather how WinCE's private implementation is done: it uses the Windows' implementation with scattered #ifdef regions. As WinRT probably requires a bit more drastic set of changes than WinCE, there will likely be places for both #ifdef solutions as well as separate .cpp files.

• There needs to be a new os #define, Q_OS_WINRT
• It should be considered if architecture is needed as well: WINRT32, WINRT64, WINRTARM…

Initially it seemed like the Windows Phone 8 API would not differ much from WinRT API. Nevertheless it turned out that Windows Phone 8 supports API which is not available on WinRT (see winsock2 for example). So a Windows Phone 8 port does not automatically mean a WinRT port but the other way around might be possible.

Technical objectives of the port

• Create new QPA plugin(s) that can handle as much of the platform-specific details as possible.
• Base the remaining platform-specifics on the existing Windows implementation, creating new code or patches where needed.

Technical details of the port

• When including files from the "Windows SDK":http://msdn.microsoft.com/en-us/windows/hardware/hh852363.aspx, the WIN_API_FAMILY define can be used to hide parts that are not available to Windows Store applications. Obtaining a clean compile with WIN_API_FAMILY=WINAPI_FAMILY_APP is the end goal, but there are many backends which need to be rewritten in order to do this.
• Beyond API changes, there are also a considerable number of POSIX C-runtime functions that are now completely unsupported under "WinRT":http://msdn.microsoft.com/en-us/library/hh674596.aspx.
• Windows Store Applications (Appx) are compiled with the /ZW switch, which enables metadata and therefore doesn't support fun stuff like external C libraries. This shouldn't be an issue as long as Qt itself is compiled without the flag (and the apps are).
• As a consequence of the above requirements, Qt uses different compiler switches, headers, & libs for the Qt tools. Hence, we can only support the WinRT mkspec as an -xplatform. Furthermore, it should likely have variants winrt-x86, winrt-x64, winrt-armv7, etc.
• To achieve the best compatibility/consistency with C++ standards as well as support for code editors, only "WRL templates":http://msdn.microsoft.com/en-us/library/windows/apps/hh438466.aspx should be used when writing platform code for WinRT. No C+/CX extensions should be used.

h2. High-level Approach to Porting

• For classes which "_qpa" PIMPLs are available, these should be used.
• In simple "_win" PIMPL cases, #ifdef regions can be used.
• In more complex situations (i.e. where a complete rewrite is needed), a "_winrt" PIMPL should be created.

h2. Porting Status

This list is intended to track the porting progress by module and file. If you have worked with one of these, please update its status.

h3. qtbase (QtCore, QtGui, QtNetwork, QtPrintingSupport)

There are about 30 C+ files containing one or more Windows PIMPLs in qtbase.

moc cannot cope with #ifdef WINAPI_FAMILY==WINAPI_FAMILY_FOO moc's preprocessor has to be enhanced to be able to deal with these constructs

To Widget or Not to Widget? Given the canvas-like, touch-oriented nature of the Metro environment, widgets (and modules which depend on them) should be considered low priority. That is not to say that they have no place in Qt WinRT apps, but it is to say that configuring with —no-widgets helps us focus on more important tasks.

qwinmain This is a static library that is linked in Windows applications which boostraps the entry point. This is actually a good fit for WinRT as well, which requires that the application run is launched in one thread but actually executes in another. Progress "here":https://qt.gitorious.org/qt/qtbase/trees/winrt/src/winmain

qsystemtrayicon_win.cpp Use qsystemtrayicon_qpa.cpp instead. QtWidgets, low-priority. Done

qwizard_win.cpp QtWidgets, low-priority. Done

qprintengine_win.cpp qprintdialog_win.cpp qpagesetupdialog_win.cpp From QtPrintSupport. Reimplement with "Windows.Graphics.Printing":http://msdn.microsoft.com/en-us/library/windows/apps/windows.graphics.printing.aspx

qnativesocketengine_win.cpp qlocalsocket_win.cpp qlocalserver_win.cpp qnetworkproxy_win.cpp qhostinfo_win.cpp qdnslookup_win.cpp Unsupported headers: Winsock2.h Unsupported libs: Ws2_32 Reimplement with "Windows.Networking.Sockets":http://msdn.microsoft.com/en-us/library/windows/apps/windows.networking.sockets.aspx

qpixmap_win.cpp Unsupported headers: Wingdi.h Unsupported libs: Gdi32 Reimplement with "Windows.Graphics.Imaging":http://msdn.microsoft.com/en-us/library/windows/apps/windows.graphics.imaging.aspx

qlocale_win.cpp Likely can remain with minor modifications. GetLocaleEx (as opposed to GetLocale) is supported under WinRT, so #ifdefs likely sufficient. Done

qelapsedtimer_win.cpp Appears that only GetModuleHandleW() needs replacement. Everything else should work. Done

qwaitcondition_win.cpp Most synchronization features remain available in WinRT. WaitForSingleObject() should be replaced with "WaitForSingleObjectEx":http://msdn.microsoft.com/en-us/library/windows/desktop/ms687036.aspx. Done

qthread_win.cpp Some threading APIs remain in WinRT, but others require reimplementation. Needs more investigation.

qmutex_win.cpp Change WaitForSingleObject() to "WaitForSingleObjectEx":http://msdn.microsoft.com/en-us/library/windows/desktop/ms687036.aspx, otherwise appears to be fine. Done

qlibrary_win.cpp Reimplement using "LoadPackagedLibrary":http://msdn.microsoft.com/en-us/library/windows/desktop/hh447159.aspx and friends. Done

qsystemsemaphore_win.cpp "CreateSemaphoreEx":http://msdn.microsoft.com/en-us/library/windows/desktop/ms682446.aspx can be used to replace CreateSemaphore(). Done

qsharedmemory_win.cpp Shared memory is not supported in WinRT and apps are sandboxed… possibly not supportable.

qeventdispatcher_win.cpp Reimplement using WRL

qcoreapplication_win.cpp Mostly filled with unneeded message types. Reimplement a minimal "winrt" version.

qstandardpaths_win.cpp Relies on the unsupported SHGetSpecialFolderPath() call. Possibly can be reimplemented with Windows.Storage.StorageFolder/Windows.Storage.Search

qsettings_win.cpp Unsupported libraries: Advapi32 As the registry is not supported in WinRT, reimplement with "Windows.Storage.ApplicationData":http://msdn.microsoft.com/en-us/library/windows/apps/br241587.aspx

qprocess_win.cpp Named pipes are not supported in WinRT, which is the backbone of the Windows QProcess PIMPL. Some functions, such as pid(), should remain working.

qfsfileengine_win.cpp qfilesystemiterator_win.cpp qfilesystemengine_win.cpp Reimplement with "Windows.Storage.StorageFile":http://msdn.microsoft.com/library/windows/apps/BR227171