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