Home | All Classes | Main Classes | Annotated | Grouped Classes | Functions |

# Qt/Mac Issues

This file outlines known issues and possible workarounds for limitations on Mac OS X with Qt. Contact Trolltech support if you find additional issues which are not covered here.

See also the document Qt/Mac is Mac OS X Native.

- GUI Applications
- QCursor
- Anti-aliased text
- Library Support

- Bundle-based Libraries
- Combining Libraries
- Initialization Order

- Compiler Settings

- Compile-time Flags

- Building and Configuring Qt/Mac

- Problems building a static configuration

- Mac OS X Native API Access

- Accessing the Bundle Path

- User Interface

- Right-Mouse Clicks
- Menubar

- Limitations

- MenuItems
- Native Widgets

## GUI Applications

GUI Applications must be run out of a bundle (something like widgets.app/) or using the open(1) command. Mac OS X needs this to dispatch events correctly, as well as gaining access to the menubar. If using GDB you must run with the full path to the executable.

## QCursor

Mac OS X only supports 16x16 custom cursors. For now the only workaround to this problem is to use a small customs cursors (16x16) with QCursor.

## Anti-aliased text

Qt/Mac (starting with 3.0.5) has introduced some support for smooth text as suggested by Apple's Aqua Style Guildelines. This support is limited to Mac OS X >10.1.4. If an older version is detected Qt will fallback to the old text rendering library.

## Library Support

### Bundle-based Libraries

If you want to incorporate dynamic libraries as part of your Mac OS X application bundle (the application directory), then you place these into a directory called Frameworks, a subdirectory of the application bundle.

The application finds these dynamic libraries if the libraries have an install name of "@executable_path/../Frameworks/libname.dylib.

If you use `qmake` and Makefiles, use the `QMAKE_LFFLAGS_SONAME` setting:

        QMAKE_LFLAGS_SONAME  = -Wl,-install_name,@executable_path/../Frameworks/

In case of Project Builder, you set the Library targets to have their install path (in the Build Settings of the target) set to "@executable_path/.../Frameworks". You also need to add a custom build setting called "SKIP_INSTALL" and set this to YES. In the Application target you need to add a Copy Files build phase that will copy the library product into the applications wrapper's Framework sub-folder.

Note that the `DYLD_LIBRARY_PATH` environment variable will override these settings, and any other default paths such as a lookup of dynamic libraries inside `/usr/lib` and similar default locations.

We still strongly recommend that you build static applications where the library code is incorporated into the Mac OS X binary. However, in case you ship applications that require plugin support, then you must use dynamic libraries as part of your application.

### Combining Libraries

If you want to build a new dynamic library combining the Qt 3.1 dynamic libraries, you need to introduce the `ld -r` flag so that relocation information is stored in the the output file, so that this file could be the subject of another `ld` run. This is done by setting the `-r` flag in the `.pro` file, and the `LFLAGS` settings.

### Initialization Order

dyld(1) will call global static initializers in the order in which they are linked into your application. If a library links against Qt and references globals in Qt (from global initializers in your own library) you should be sure to link against Qt before your library, otherwise the result will be undefined (as Qt's global initializers have not been called yet).

## Compiler Settings

### Compile-time Flags

If you want to wrap any specific Mac OS X code in a define, use the `Q_OS_MAC` flag, as in:

        #if defined(Q_OS_MAC)
        // the code used
        #endif

Note that when you build under Mac OS X 10.2, then the `MACOSX_102` flag is automatically included in the make builds.

## Building and Configuring Qt/Mac

### Problems building a static configuration

If a static build fails with the following error messages during the designer make phase:

        QWidget::sizeHint() const referenced from libqui expected to be defined in @executable_path/../Frameworks/libqt-mt.3.dylib
        non-virtual thunk [nv:-40] to QWidget::metric(int) const referenced from libqui
         expected to be defined in @executable_path/../Frameworks/libqt-mt.3.dylib

then ensure that your library path does not have `libqui` libraries or symbolic links. If you remove these, then the build will continue.

## Mac OS X Native API Access

### Accessing the Bundle Path

The Mac OS X application is actually a directory (ending with `.app`). This directory has various sub-directories and sources. In case you want to place for example the plugin directory, inside this bundle, then you need to find out where the bundle resides on the disk. The following code will do this:

                CFURLRef pluginRef = CFBundleCopyBundleURL(CFBundleGetMainBundle());
                CFStringRef macPath = CFURLCopyFileSystemPath(pluginRef,
                                                       kCFURLPOSIXPathStyle);
                const char *pathPtr = CFStringGetCStringPtr(macPath,
                                                       CFStringGetSystemEncoding());
                qDebug("Path = %s", pathPtr);

Do not forget to enclosure this in an #if defined(Q_OS_MAC) macro statement.

## User Interface

### Right-Mouse Clicks

If you want to provide right-mouse click support for Mac OS X, use the QContextMenuEvent class. This will map to a context menu event, in other words a menu that will display a popup selection. This is the most common use of right-mouse clicks, and maps to a control-click with the Mac OS X one-button mouse support.

### Menubar

Qt/Mac will automatically detect your menubars for you and turn them into Mac native menubars. Fitting this into your existing Qt application will normally be automatic, however, if you have special needs the Qt/Mac implementation currently selects a menubar by starting at the active window (ie QApplication::activeWindow()), and applying:

1. If the window has a QMenuBar then it is used.
2. If the window is a modal then its menubar is used. If no menubar is specified then a default menubar is used (as documented below)
3. If the window has no parent then the default menubar is used (as documented below).

The above 3 steps are applied all the way up the parent window chain until one of the above are satisifed. If all else fails a default menubar will be created, the default menubar on Qt/Mac is an empty menubar, however you can create a different default menubar by creating a parentless QMenuBar; the first one created will be designated the default menubar, and will be used whenever a default menubar is needed.

## Limitations

### MenuItems

- QCustomMenuItems are not supported in Mac native menubars, although they are supported in popup menus that are not in the Mac native menubar.
- Items with accelerators that have more than one keystroke (QKeySequence) will not be honored, and the first key will be used.

### Native Widgets

Qt/Mac now has support for sheets, drawers. Represented as WMacSheet and WMacDrawer in the window flags respectiviely. Brushed metal windows are also possible using WMacMetal.

We currently do not support the chooser (Panther-style tabs). There may be support for these in a future version of Qt.