CopperSpice Overview  1.5.2
Mac UI

A native Mac application is a program which uses the underlying window system, instead of an X11 server or a web browser. CopperSpice uses the native Mac OS X APIs to display the user interface. The Human Interface Guidelines, released by Apple, define what the UI on Mac OS X should look like.

Documentation for HI can be found at Human Interface Guidelines

Compile-Time Flags

When compile time checking for Mac OS X specific code is required, use platform defines. Refer to Platform Defines.

Refer to QSysInfo in the CopperSpice API for information on runtime version checking.

The Global Menu Bar

Mac users expect to have a menu bar at the top of the screen. A CopperSpice application accomplishes this using a QMenuBar.

Users also expect certain Mac OS X conventions to be respected. For example, the application menu should be shown to the right of the Apple menu. Some of the items in the application menu are About, Preferences, Quit, etc. CopperSpice creates the application menu automatically, although there is no way to interact directly with the this menu.

Menu Bar

CopperSpice will automatically detect your menu bars and turn them into Mac native menu bars. Fitting this into your existing application will normally be automatic. CopperSpice selects a menu bar by starting at the active window and applying the following tests:

  • If the window has a QMenuBar, then it is used as the active menu.
  • If the window is modal, then its menu bar is used. If no menu bar is specified, then a default menu bar is used.
  • If the window has no parent, then the default menu bar is used.

These tests are followed all the way up the parent window chain until one of the above rules is satisfied. If all else fails, a default menu bar will be created. The default menu bar is an empty menu bar.

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.

Menu Actions

  • Actions in a QMenu with accelerators that have more than one keystroke (QKeySequence) will not display correctly. Only the first key will be displayed however, the shortcut will still be available.
  • QMenu objects used in the native menu bar are not able to handle events via the normal event handlers.

For Cocoa, you will have to 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.

  • In order to modify which menu items are moved to the Application Menu, refer to the enums for QAction::MenuRole()


Aqua is an important concept for Mac OS X and is the primary visual theme. CopperSpice widgets use HIThemes to implement the appropriate look.

To have your application conform to the Apple guidelines, you will need to implement this in your UI design. Mac OS X is a significantly different platform to Unix and Windows and some special considerations must be made based on your users.

Native Widgets

CopperSpice has support for sheets and drawers, represented in the window flags by Qt::Sheet and Qt::Drawer respectively. Brushed metal windows can also be created by using the Qt::WA_MacMetalStyle window attribute.

Documentation for this topic can be found from this link and searching for 'Providing a Drawer' HI UI Element Guidelines: Windows


Mac OS X always double buffers the screen so the Qt::WA_PaintOnScreen attribute has no effect. Also, it is not possible to paint outside of a paint event so Qt::WA_PaintOutsidePaintEvent has no effect.


The items in the Application Menu will be merged correctly for your localized application, however they will not show up translated until you add a localized resource folder to the application bundle. You will need to create a file called locversion.plist.

Here is an example for Norwegian. The value for LprojLocale is "no". For English this value would be "en", for French it would be "fr", etc.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN"
<plist version="1.0">

For additional information refer to Internationalization


Interaction with the dock is possible. A dock icon can be set by calling QWidget::setWindowIcon() on the main window in your application. The setWindowIcon() call can be made as often as necessary, providing an icon that can be easily updated.

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 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 Mac OS X one-button mouse support.

Special Keys

To provide the expected behavior for applications on Mac OS X, the Qt::Meta, Qt::MetaModifier, and Qt::META enum values correspond to the Control keys on the standard Macintosh keyboard. The Qt::Control, Qt::ControlModifier, and Qt::CTRL enum values correspond to the Command keys.


Although many users never use accessibility some users will only interact with your applications via assistive devices. With CS the aim is to make this automatic.