<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- osx.qdoc -->
<title>Qt for macOS - Specific Issues | Qt 5.9</title>
<link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
<script type="text/javascript">
document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
// loading style sheet breaks anchors that were jumped to before
// so force jumping to anchor again
setTimeout(function() {
var anchor = location.hash;
// need to jump to different anchor first (e.g. none)
location.hash = "#";
setTimeout(function() {
location.hash = anchor;
}, 0);
}, 0);
</script>
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<table><tr>
<td ><a href="index.html">Qt 5.9</a></td><td >Qt for macOS - Specific Issues</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right">Qt 5.9.4 Reference Documentation</td>
</tr></table>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#aqua">Aqua</a></li>
<li class="level2"><a href="#qt-attributes-for-macos">Qt Attributes for macOS</a></li>
<li class="level2"><a href="#right-mouse-clicks">Right Mouse Clicks</a></li>
<li class="level2"><a href="#menu-bar">Menu Bar</a></li>
<li class="level2"><a href="#special-keys">Special Keys</a></li>
<li class="level2"><a href="#dock">Dock</a></li>
<li class="level2"><a href="#accessiblity">Accessiblity</a></li>
<li class="level1"><a href="#library-and-deployment-support">Library and Deployment Support</a></li>
<li class="level2"><a href="#qt-libraries-as-frameworks">Qt Libraries as Frameworks</a></li>
<li class="level2"><a href="#bundle-based-libraries">Bundle-Based Libraries</a></li>
<li class="level2"><a href="#combining-libraries">Combining Libraries</a></li>
<li class="level2"><a href="#initialization-order">Initialization Order</a></li>
<li class="level1"><a href="#compile-time-flags">Compile-Time Flags</a></li>
<li class="level1"><a href="#macos-native-api-access">macOS Native API Access</a></li>
<li class="level2"><a href="#accessing-the-bundle-path">Accessing the Bundle Path</a></li>
<li class="level2"><a href="#translating-the-application-menu-and-native-dialogs">Translating the Application Menu and Native Dialogs</a></li>
<li class="level2"><a href="#mixing-qt-with-native-code">Mixing Qt with Native Code</a></li>
<li class="level2"><a href="#using-native-cocoa-panels">Using Native Cocoa Panels</a></li>
<li class="level1"><a href="#limitations">Limitations</a></li>
<li class="level2"><a href="#fink">Fink</a></li>
<li class="level2"><a href="#mysql-and-macos">MySQL and macOS</a></li>
<li class="level2"><a href="#d-bus-and-macos">D-Bus and macOS</a></li>
<li class="level2"><a href="#menu-actions">Menu Actions</a></li>
<li class="level2"><a href="#native-widgets">Native Widgets</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Qt for macOS - Specific Issues</h1>
<span class="subtitle"></span>
<!-- $$$osx-issues.html-description -->
<div class="descr"> <a name="details"></a>
<p>This page outlines the main issues regarding macOS support in Qt. macOS terminologies and specific processes are found at <a href="https://developer.apple.com/">https://developer.apple.com/</a>.</p>
<a name="aqua"></a>
<h2 id="aqua">Aqua</h2>
<p>Aqua is an essential part of the macOS platform. As with Cocoa and Carbon, Qt provides widgets that look like those described in the Human Interface Descriptions. Qt's widgets use HIThemes to implement the look and feel. In other words, we use Apple's own APIs for doing the rendering. More documentation about Aqua is found at the <a href="http://developer.apple.com/library/mac/#documentation/UserExperience/Conceptual/AppleHIGuidelines/Intro/Intro.html#//apple_ref/doc/uid/20000957">macOS Human Interface Guidelines</a>.</p>
<p>The Qt Widget Gallery page contains sample images of applications using the macOS platform theme.</p>
<a name="qt-attributes-for-macos"></a>
<h3 >Qt Attributes for macOS</h3>
<p>The following lists a set of useful attributes that can be used to tweak applications on macOS:</p>
<ul>
<li>Qt::AA_MacPluginApplication</li>
<li>Qt::AA_DontUseNativeMenuBar</li>
<li>Qt::AA_MacDontSwapCtrlAndMeta</li>
<li>Qt::WA_MacNoClickThrough</li>
<li>Qt::WA_MacOpaqueSizeGrip</li>
<li>Qt::WA_MacShowFocusRect</li>
<li>Qt::WA_MacNormalSize</li>
<li>Qt::WA_MacSmallSize</li>
<li>Qt::WA_MacMiniSize</li>
<li>Qt::WA_MacVariableSize</li>
<li>Qt::WA_MacBrushedMetal</li>
<li>Qt::WA_MacAlwaysShowToolWindow</li>
<li>Qt::WA_MacFrameworkScaled</li>
<li>Qt::WA_MacNoShadow</li>
<li>Qt::Sheet</li>
<li>Qt::Drawer</li>
<li>Qt::MacWindowToolBarButtonHint,</li>
<li>QMainWindow::unifiedTitleAndToolBarOnMac</li>
</ul>
<p>macOS always double buffers the screen, therefore, the Qt::WA_PaintOnScreen attribute has no effect. Also it is impossible to paint outside of a paint event so Qt::WA_PaintOutsidePaintEvent has no effect either.</p>
<a name="right-mouse-clicks"></a>
<h3 >Right Mouse Clicks</h3>
<p>The QContextMenuEvent class provides right mouse click support for macOS applications. This will map to a context menu event, for example, a menu that will display a pop-up selection. This is the most common use of right mouse clicks, and maps to a control-click with the macOS one-button mouse support.</p>
<a name="menu-bar"></a>
<h3 >Menu Bar</h3>
<p>Qt detects menu bars and turns them into Mac native menu bars. Fitting this into existing Qt applications is normally automatic. However, if you have special needs, the Qt implementation currently selects a menu bar by starting at the active window (for example, QGuiApplication::focusWindow()) and applying the following tests:</p>
<ol class="1" type="1"><li>If the window has a QMenuBar, then it is used.</li>
<li>If the window is modal, then its menu bar is used. If no menu bar is specified, then a default menu bar is used (as documented below).</li>
<li>If the window has no parent, then the default menu bar is used (as documented below).</li>
</ol>
<p>These tests are followed all the way up the parent window chain until one of the above rules is satisifed. If all else fails, a default menu bar will be created. The default menu bar on Qt is an empty menu bar. However, you can create a different default menu bar by creating a parentless QMenuBar. The first one created will be designated the default menu bar and will be used whenever a default menu bar is needed.</p>
<p>Using native menu bars introduces certain limitations on Qt classes. The section with the <a href="osx-issues.html#limitations">list of limitations</a> below has more information.</p>
<p>Qt provides support for the Global Menu Bar with QMenuBar. macOS users expect to have a menu bar at the top of the screen and Qt honors this.</p>
<p>Additionally, users expect certain conventions to be respected, for example the application menu should contain <b>About</b>, <b>Preferences</b>, <b>Quit</b>, and so on. Qt handles these conventions, although it does not provide a means of interacting directly with the application menu.</p>
<p>Each QAction has a menuRole property which controls the special placement of application menu items; however by default the <code>menuRole</code> is TextHeuristicRole which mean the menu items will be auto-detected by their text.</p>
<p>Other standard menu items such as <b>Cut</b>, <b>Copy</b>, <b>Paste</b> and <b>Select All</b> are applicable both in your application and in some native dialogs such as QFileDialog. It's important that you create these menu items with the standard shortcuts so that the corresponding editing features will be enabled in the dialogs. At this time there are no <code>MenuRole</code> identifiers for them, but they will be auto-detected just like the application menu items when the <code>QAction</code> has the default TextHeuristicRole.</p>
<a name="special-keys"></a>
<h3 >Special Keys</h3>
<p>To provide the expected behavior for Qt applications on macOS, the Qt::Key_Meta, Qt::MetaModifier, and Qt::META enum values correspond to the Control keys on the standard Apple keyboard, and the Qt::Key_Control, Qt::ControlModifier, and Qt::CTRL enum values correspond to the Command keys.</p>
<a name="dock"></a>
<h3 >Dock</h3>
<p>Interaction with the dock is possible. The icon can be set by calling QWindow::setWindowIcon() from the main window in your application. The setWindowIcon() call can be made as often as necessary, providing an icon that can be easily updated.</p>
<a name="accessiblity"></a>
<h3 >Accessiblity</h3>
<p>Many users interact with macOS with assistive devices. With Qt the aim is to make this automatic in your application so that it conforms to accepted practice on its platform. Qt uses Apple's accessibility framework to provide access to users with disabilities.</p>
<a name="library-and-deployment-support"></a>
<h2 id="library-and-deployment-support">Library and Deployment Support</h2>
<p>Qt provides support for macOS structures such as Frameworks and bundles. It is important to be aware of these structure as they directly affect the deployment of applications.</p>
<p>Qt provides a deploy tool, <a href="osx-deployment.html#the-mac-deployment-tool">macdeployqt</a>, to simplify the deployment process. The <a href="osx-deployment.html">Qt for macOS - Deployment</a> article covers the deployment process in more detail.</p>
<a name="qt-libraries-as-frameworks"></a>
<h3 >Qt Libraries as Frameworks</h3>
<p>By default, Qt is built as a set of frameworks. Frameworks are the macOS preferred way of distributing libraries. The <a href="http://developer.apple.com/documentation/MacOSX/Conceptual/BPFrameworks/index.html">Apple's Framework Programming Guide</a> site has far more information about Frameworks.</p>
<p>It is important to remember that Frameworks always link with <i>release</i> versions of libraries. If the <i>debug</i> version of a Qt framework is desired, use the <code>DYLD_IMAGE_SUFFIX</code> environment variables to ensure that the debug version is loaded:</p>
<pre class="cpp">
<span class="keyword">export</span> DYLD_IMAGE_SUFFIX<span class="operator">=</span>_debug
</pre>
<p>Alternatively, you can temporarily swap your debug and release versions, which is documented in <a href="http://developer.apple.com/technotes/tn2004/tn2124.html#SECJUSTONELIB">Apple's "Debugging Magic" technical note</a>.</p>
<p>If you don't want to use frameworks, simply configure Qt with <code>-no-framework</code>.</p>
<pre class="cpp">
<span class="operator">.</span><span class="operator">/</span>configure <span class="operator">-</span>no<span class="operator">-</span>framework
</pre>
<a name="bundle-based-libraries"></a>
<h3 >Bundle-Based Libraries</h3>
<p>If you want to use some dynamic libraries in the macOS application bundle (the application directory), create a subdirectory named <i>Frameworks</i> in the application bundle directory and place your dynamic libraries there. The application will find a dynamic library if it has the install name <i>@executable_path/../Frameworks/libname.dylib</i>.</p>
<p>If you use <code>qmake</code> and Makefiles, use the <code>QMAKE_LFLAGS_SONAME</code> setting:</p>
<pre class="cpp">
QMAKE_LFLAGS_SONAME = -Wl,-install_name,@executable_path/../Frameworks/
</pre>
<p>Alternatively, you can modify the install name using the <code>install_name_tool(1)</code> on the command line.</p>
<p>The <code>DYLD_LIBRARY_PATH</code> environment variable will override these settings, and any other default paths, such as a lookup of dynamic libraries inside <i>/usr/lib</i> and similar default locations.</p>
<p>If you are using older versions of GDB you must run with the full path to the executable. Later versions allow you to pass the bundle name on the command line.</p>
<a name="combining-libraries"></a>
<h3 >Combining Libraries</h3>
<p>If you want to build a new dynamic library combining the Qt 4 dynamic libraries, you need to introduce the <code>ld -r</code> flag. Then relocation information is stored in the output file, so that this file could be the subject of another <code>ld</code> run. This is done by setting the <code>-r</code> flag in the <code>.pro</code> file, and the <code>LFLAGS</code> settings.</p>
<a name="initialization-order"></a>
<h3 >Initialization Order</h3>
<p><code>dyld(1)</code> calls global static initializers in the order they are linked into the application. If a library links against Qt and references the globals in Qt (from global initializers in your own library), link the application against Qt before linking it against the library. Otherwise the result will be undefined because Qt's global initializers have not been called yet.</p>
<a name="compile-time-flags"></a>
<h2 id="compile-time-flags">Compile-Time Flags</h2>
<p>The following flags are helpful when you want to define macOS specific code:</p>
<ul>
<li><code>Q_OS_DARWIN</code> is defined when Qt detects you are on a Darwin-based system such as macOS or iOS.</li>
<li><code>Q_OS_MACOS</code> is defined when you are on an macOS system.</li>
</ul>
<p><b>Note: </b><code>Q_WS_MAC</code> is no longer defined in Qt 5.</p><p>If you want to define code for specific versions of macOS, use the availability macros defined in <i>/usr/include/AvailabilityMacros.h</i>.</p>
<p>The QSysInfo documentation has information about runtime version checking.</p>
<a name="macos-native-api-access"></a>
<h2 id="macos-native-api-access">macOS Native API Access</h2>
<a name="accessing-the-bundle-path"></a>
<h3 >Accessing the Bundle Path</h3>
<p>macOS applications are structured as a directory (ending with <i>.app</i>). This directory contains sub-directories and files. It may be useful to place items, such as plugins and online documentation, inside this bundle. The following code returns the path of the application bundle:</p>
<pre class="cpp">
<span class="preprocessor">#ifdef Q_OS_MAC</span>
CFURLRef appUrlRef <span class="operator">=</span> CFBundleCopyBundleURL(CFBundleGetMainBundle());
CFStringRef macPath <span class="operator">=</span> CFURLCopyFileSystemPath(appUrlRef<span class="operator">,</span>
kCFURLPOSIXPathStyle);
<span class="keyword">const</span> <span class="type">char</span> <span class="operator">*</span>pathPtr <span class="operator">=</span> CFStringGetCStringPtr(macPath<span class="operator">,</span>
CFStringGetSystemEncoding());
qDebug(<span class="string">"Path = %s"</span><span class="operator">,</span> pathPtr);
CFRelease(appUrlRef);
CFRelease(macPath);
<span class="preprocessor">#endif</span>
</pre>
<p><b>Note: </b>When macOS is set to use Japanese, a bug causes this sequence to fail and return an empty string. Therefore, always test the returned string.</p><p>For more information about using the CFBundle API, visit <a href="http://developer.apple.com/documentation/CoreFoundation/Reference/CFBundleRef/index.html">Apple's Developer Website</a>.</p>
<p>QCoreApplication::applicationDirPath() can be used to determine the path of the binary within the bundle.</p>
<a name="translating-the-application-menu-and-native-dialogs"></a>
<h3 >Translating the Application Menu and Native Dialogs</h3>
<p>The items in the Application Menu will be merged correctly for localized applications, but they will not show up translated until the application bundle contains a localized resource folder. to the application bundle.</p>
<p>Essentially, there needs to be a file called <i>locversion.plist</i>. Here is an example of an application with Norwegian localization:</p>
<pre class="cpp">
<span class="operator"><</span><span class="operator">?</span>xml version<span class="operator">=</span><span class="string">"1.0"</span> encoding<span class="operator">=</span><span class="string">"UTF-8"</span><span class="operator">?</span><span class="operator">></span>
<span class="operator"><</span><span class="operator">!</span>DOCTYPE plist PUBLIC <span class="string">"-//Apple Computer//DTD PLIST 1.0//EN"</span>
<span class="string">"http://www.apple.com/DTDs/PropertyList-1.0.dtd"</span><span class="operator">></span>
<span class="operator"><</span>plist version<span class="operator">=</span><span class="string">"1.0"</span><span class="operator">></span>
<span class="operator"><</span>dict<span class="operator">></span>
<span class="operator"><</span>key<span class="operator">></span>LprojCompatibleVersion<span class="operator"><</span><span class="operator">/</span>key<span class="operator">></span>
<span class="operator"><</span>string<span class="operator">></span><span class="number">123</span><span class="operator"><</span><span class="operator">/</span>string<span class="operator">></span>
<span class="operator"><</span>key<span class="operator">></span>LprojLocale<span class="operator"><</span><span class="operator">/</span>key<span class="operator">></span>
<span class="operator"><</span>string<span class="operator">></span>no<span class="operator"><</span><span class="operator">/</span>string<span class="operator">></span>
<span class="operator"><</span>key<span class="operator">></span>LprojRevisionLevel<span class="operator"><</span><span class="operator">/</span>key<span class="operator">></span>
<span class="operator"><</span>string<span class="operator">></span><span class="number">1</span><span class="operator"><</span><span class="operator">/</span>string<span class="operator">></span>
<span class="operator"><</span>key<span class="operator">></span>LprojVersion<span class="operator"><</span><span class="operator">/</span>key<span class="operator">></span>
<span class="operator"><</span>string<span class="operator">></span><span class="number">123</span><span class="operator"><</span><span class="operator">/</span>string<span class="operator">></span>
<span class="operator"><</span><span class="operator">/</span>dict<span class="operator">></span>
<span class="operator"><</span><span class="operator">/</span>plist<span class="operator">></span>
</pre>
<p>Afterwards, when the application is run with the preferred language set to Norwegian, the menu items should display <b>Avslutt</b> instead of <b>Quit</b>.</p>
<p>The <a href="http://developer.apple.com/library/mac/#documentation/CoreFoundation/Conceptual/CFBundles/BundleTypes/BundleTypes.html#//apple_ref/doc/uid/10000123i-CH101-SW13">Bundle Programming Guide</a> contains information about bundles and the localized resource folder.</p>
<a name="mixing-qt-with-native-code"></a>
<h3 >Mixing Qt with Native Code</h3>
<p>Two classes are available for adding native Cocoa views and controls inside a Qt application, or for embedding Qt into a native Cocoa application: QMacCocoaViewContainer, and QMacNativeWidget.</p>
<a name="using-native-cocoa-panels"></a>
<h3 >Using Native Cocoa Panels</h3>
<p>Qt's event dispatcher is more flexible than what Cocoa offers, and lets the user spin the event dispatcher (and running QEventLoop::exec) without having to think about whether or not modal dialogs are showing on screen (which is a difference compared to Cocoa). Therefore, we need to do extra management in Qt to handle this correctly, which unfortunately makes mixing native panels hard. The best way at the moment to do this, is to follow the pattern below, where we post the call to the function with native code rather than calling it directly. Then we know that Qt has cleanly updated any pending event loop recursions before the native panel is shown:</p>
<pre class="cpp">
<span class="preprocessor">#include <QtGui></span>
<span class="keyword">class</span> NativeProxyObject : <span class="keyword">public</span> <span class="type">QObject</span>
{
Q_OBJECT
<span class="keyword">public</span> <span class="keyword">slots</span>:
<span class="type">void</span> execNativeDialogLater()
{
<span class="type">QMetaObject</span><span class="operator">::</span>invokeMethod(<span class="keyword">this</span><span class="operator">,</span> <span class="string">"execNativeDialogNow"</span><span class="operator">,</span> <span class="type">Qt</span><span class="operator">::</span>QueuedConnection);
}
<span class="type">void</span> execNativeDialogNow()
{
NSRunAlertPanel(@<span class="string">"A Native dialog"</span><span class="operator">,</span> @<span class="string">""</span><span class="operator">,</span> @<span class="string">"OK"</span><span class="operator">,</span> @<span class="string">""</span><span class="operator">,</span> @<span class="string">""</span>);
}
};
<span class="preprocessor">#include "main.moc"</span>
<span class="type">int</span> main(<span class="type">int</span> argc<span class="operator">,</span> <span class="type">char</span> <span class="operator">*</span><span class="operator">*</span>argv){
<span class="type">QApplication</span> app(argc<span class="operator">,</span> argv);
NativeProxyObject proxy;
<span class="type">QPushButton</span> button(<span class="string">"Show native dialog"</span>);
<span class="type">QObject</span><span class="operator">::</span>connect(<span class="operator">&</span>button<span class="operator">,</span> SIGNAL(clicked())<span class="operator">,</span> <span class="operator">&</span>proxy<span class="operator">,</span> SLOT(execNativeDialogLater()));
button<span class="operator">.</span>show();
<span class="keyword">return</span> app<span class="operator">.</span>exec();
}
</pre>
<a name="limitations"></a>
<h2 id="limitations">Limitations</h2>
<a name="fink"></a>
<h3 >Fink</h3>
<p>If you have installed the Qt for X11 package from <a href="osx-issues.html#fink">Fink</a>, it will set the <code>QMAKESPEC</code> environment variable to <code>darwin-g++</code>. This will cause problems when you build the Qt for macOS package. To fix this, simply unset your <code>QMAKESPEC</code> or set it to <code>macx-g++</code> before you run <code>configure</code>. To get a fresh Qt distribution, run <code>make confclean</code> in the command-line.</p>
<a name="mysql-and-macos"></a>
<h3 >MySQL and macOS</h3>
<p>There seems to be a issue when both <code>-prebind</code> and <code>-multi_module</code> are defined when linking static C libraries into dynamic libraries. If you get the following error message when linking Qt:</p>
<pre class="cpp">
ld: common symbols <span class="keyword">not</span> allowed with MH_DYLIB output format with the <span class="operator">-</span>multi_module option
<span class="operator">/</span>usr<span class="operator">/</span>local<span class="operator">/</span>mysql<span class="operator">/</span>lib<span class="operator">/</span>libmysqlclient<span class="operator">.</span>a(my_error<span class="operator">.</span>o) definition of common _errbuff (size <span class="number">512</span>)
<span class="operator">/</span>usr<span class="operator">/</span>bin<span class="operator">/</span>libtool: internal link edit command failed
</pre>
<p>re-link Qt using -single_module. This is only a problem when building the MySQL driver into Qt. It does not affect plugins or static builds.</p>
<a name="d-bus-and-macos"></a>
<h3 >D-Bus and macOS</h3>
<p>The QtDBus module defaults to dynamically loading the libdbus-1 library on macOS. That means applications linking against the QtDBus module will load even on macOS systems that do not have the libraries, but they will fail to connect to any D-Bus server and they will fail to open a server using QDBusServer.</p>
<p>To use D-Bus functionality, you need to install the libdbus-1 library, for example through Homebrew, Fink or MacPorts. You may want to include those libraries in your application's bundle if you're deploying to other systems. Additionally, note that there is no system bus on macOS and that the session bus will only be started after launchd is configured to manage it.</p>
<a name="menu-actions"></a>
<h3 >Menu Actions</h3>
<ul>
<li>Actions in a QMenu with accelerators that have more than one keystroke (QKeySequence) will not display correctly, when the QMenu is translated into a Mac native menu bar. The first key will be displayed. However, the shortcut will still be activated as on all other platforms.</li>
<li>QMenu objects used in the native menu bar are not able to handle Qt events via the normal event handlers. Install a delegate on the menu itself to be notified of these changes. Alternatively, consider using the QMenu::aboutToShow() and QMenu::aboutToHide() signals to keep track of menu visibility; these provide a solution that should work on all platforms supported by Qt.</li>
</ul>
<a name="native-widgets"></a>
<h3 >Native Widgets</h3>
<p>Qt has support for sheets, represented by the window flag, Qt::Sheet.</p>
<p>Usually, when referring to a native macOS application, <i>native</i> means an application that interfaces directly to the underlying window system, rather than one that uses some intermediary layer. Qt applications run as first class citizens, just like Cocoa and Carbon applications. We use Cocoa internally to communicate with the operating system.</p>
</div>
<!-- @@@osx-issues.html -->
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2017 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.<br> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br> Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
