WinRT: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
(Add "cleanup" tag)
(Decode HTML entity names)
 
(2 intermediate revisions by the same user not shown)
Line 14: Line 14:
= Porting Qt 5 to Windows Runtime (WinRT/Windows 8 Metro) =
= 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.
While WinRT is, in many ways, the same old Windows, many APIs have been [http://msdn.microsoft.com/en-us/library/windows/apps/br211377.aspx replaced or removed]. As such, most of Qt's Windows private implementations (PIMPLs) require [http://msdn.microsoft.com/en-us/library/windows/apps/hh464945.aspx refactoring]. 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.
'''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.
Line 33: Line 33:
== Technical details of the port ==
== 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.
* When including files from the [http://msdn.microsoft.com/en-us/windows/hardware/hh852363.aspx Windows SDK], 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.
* Beyond API changes, there are also a considerable number of POSIX C-runtime functions that are now completely unsupported under [http://msdn.microsoft.com/en-us/library/hh674596.aspx WinRT].
* 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).
* 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.
* 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.
* To achieve the best compatibility/consistency with C++ standards as well as support for code editors, only [http://msdn.microsoft.com/en-us/library/windows/apps/hh438466.aspx WRL templates] should be used when writing platform code for WinRT. No C+''/CX extensions should be used.
 
h2. High-level Approach to Porting


== High-level Approach to Porting ==
* For classes which "_qpa" PIMPLs are available, these should be used.
* For classes which "_qpa" PIMPLs are available, these should be used.
* In simple "_win" PIMPL cases, #ifdef regions can 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.
* In more complex situations (i.e. where a complete rewrite is needed), a "_winrt" PIMPL should be created.


h2. Porting Status
== 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.
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)
=== qtbase (QtCore, QtGui, QtNetwork, QtPrintingSupport) ===
 
There are about 30 C''+ files containing one or more Windows PIMPLs in qtbase.
There are about 30 C''+ files containing one or more Windows PIMPLs in qtbase.


Line 60: Line 57:


'''qwinmain'''
'''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
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 [https://qt.gitorious.org/qt/qtbase/trees/winrt/src/winmain here]


'''qsystemtrayicon_win.cpp'''
'''qsystemtrayicon_win.cpp'''
Line 73: Line 70:
'''qprintdialog_win.cpp'''
'''qprintdialog_win.cpp'''
'''qpagesetupdialog_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
From QtPrintSupport. Reimplement with [http://msdn.microsoft.com/en-us/library/windows/apps/windows.graphics.printing.aspx Windows.Graphics.Printing]


'''qnativesocketengine_win.cpp'''
'''qnativesocketengine_win.cpp'''
Line 83: Line 80:
Unsupported headers: Winsock2.h
Unsupported headers: Winsock2.h
Unsupported libs: Ws2_32
Unsupported libs: Ws2_32
Reimplement with "Windows.Networking.Sockets":http://msdn.microsoft.com/en-us/library/windows/apps/windows.networking.sockets.aspx
Reimplement with [http://msdn.microsoft.com/en-us/library/windows/apps/windows.networking.sockets.aspx Windows.Networking.Sockets]


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


'''qlocale_win.cpp'''
'''qlocale_win.cpp'''
Line 99: Line 96:


'''qwaitcondition_win.cpp'''
'''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.
Most synchronization features remain available in WinRT. WaitForSingleObject() should be replaced with [http://msdn.microsoft.com/en-us/library/windows/desktop/ms687036.aspx WaitForSingleObjectEx].
'''Done'''
'''Done'''


Line 106: Line 103:


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


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


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


Line 131: Line 128:
'''qsettings_win.cpp'''
'''qsettings_win.cpp'''
Unsupported libraries: Advapi32
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
As the registry is not supported in WinRT, reimplement with [http://msdn.microsoft.com/en-us/library/windows/apps/br241587.aspx Windows.Storage.ApplicationData]


'''qprocess_win.cpp'''
'''qprocess_win.cpp'''
Line 139: Line 136:
'''qfilesystemiterator_win.cpp'''
'''qfilesystemiterator_win.cpp'''
'''qfilesystemengine_win.cpp'''
'''qfilesystemengine_win.cpp'''
Reimplement with "Windows.Storage.StorageFile":http://msdn.microsoft.com/library/windows/apps/BR227171
Reimplement with [http://msdn.microsoft.com/library/windows/apps/BR227171 Windows.Storage.StorageFile]


=== QtQml ===
=== QtQml ===

Latest revision as of 17:56, 12 March 2015

This article may require cleanup to meet the Qt Wiki's quality standards. Reason: Auto-imported from ExpressionEngine.
Please improve this article if you can. Remove the {{cleanup}} tag and add this page to Updated pages list after it's clean.

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:

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. As such, most of Qt's Windows private implementations (PIMPLs) require refactoring. 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, 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.
  • 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 should be used when writing platform code for WinRT. No C+/CX extensions should be used.

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.

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.

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

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

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

qpixmap_win.cpp Unsupported headers: Wingdi.h Unsupported libs: Gdi32 Reimplement with Windows.Graphics.Imaging

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. Done

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

qmutex_win.cpp Change WaitForSingleObject() to WaitForSingleObjectEx, otherwise appears to be fine. Done

qlibrary_win.cpp Reimplement using LoadPackagedLibrary and friends. Done

qsystemsemaphore_win.cpp CreateSemaphoreEx 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

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

QtQml

QtQuick

qtjsbackend

QtWebKit