Qt para macOS: problemas específicos
Esta página describe los principales problemas relacionados con la compatibilidad de Qt con macOS. La terminología y los procesos específicos de macOS se pueden consultar en https://developer.apple.com/.
Aqua
El estilo Aqua es una parte esencial de la plataforma macOS. Al igual que con Cocoa, Qt proporciona widgets que se asemejan a los descritos en las Directrices de interfaz de usuario de macOS. Ten en cuenta que, aunque los widgets de Qt utilizan AppKit en segundo plano para su aspecto y comportamiento, no representan cada widget individual de Qt como un control nativo envuelto.
La página «Galería de Qt Widgets » contiene imágenes de ejemplo de aplicaciones que utilizan el tema de la plataforma macOS.
Atributos de Qt para macOS
A continuación se enumeran una serie de atributos útiles que pueden emplearse para personalizar aplicaciones en macOS:
- Qt::AA_PluginApplication
- Qt::AA_DontUseNativeMenuBar
- Qt::AA_MacDontSwapCtrlAndMeta
- Qt::WA_MacOpaqueSizeGrip
- Qt::WA_MacShowFocusRect
- Qt::WA_MacNormalSize
- Qt::WA_MacSmallSize
- Qt::WA_MacMiniSize
- Qt::WA_MacAlwaysShowToolWindow
- Qt::Sheet
- Qt::Drawer
- Qt::MacWindowToolBarButtonHint,
- QMainWindow::unifiedTitleAndToolBarOnMac
macOS siempre utiliza doble búfer en la pantalla, por lo que el atributo « Qt::WA_PaintOnScreen » no tiene ningún efecto. Además, es imposible dibujar fuera de un evento de dibujo, por lo que Qt::WA_PaintOutsidePaintEvent tampoco tiene ningún efecto.
Clics con el botón derecho del ratón
La clase ` QContextMenuEvent ` ofrece compatibilidad con el clic con el botón derecho del ratón para aplicaciones de macOS. Esto se asignará a un evento de menú contextual; por ejemplo, un menú que mostrará una selección emergente. Este es el uso más habitual de los clics con el botón derecho del ratón y se asigna a un clic con la tecla Control pulsada en el ratón de un solo botón de macOS.
Internacionalización
Las aplicaciones en macOS declaran los idiomas que admiten como parte del ` Info.plist ` de la aplicación. A continuación, el sistema comparará los idiomas compatibles con la aplicación con las preferencias de idioma del usuario para determinar la configuración regional en la que se ejecutará la aplicación. Esto, a su vez, determina el orden de los idiomas que se refleja a través de ` QLocale::uiLanguages()`, así como la forma en que los marcos del sistema, como AppKit, recogen sus recursos localizados, tales como los títulos de los menús y las cadenas de texto.
Dado que las aplicaciones Qt no vienen traducidas de serie, el archivo Info.plist generado por defecto para los proyectos CMake y qmake establece CFBundleAllowMixedLocalizationsYES, para permitir que los marcos del sistema seleccionen la localización que mejor se ajuste a las preferencias de idioma del usuario, incluso si dicha localización no está disponible para la propia aplicación. Una vez que añadas traducciones a tu aplicación mediante qt_add_translations, la CFBundleAllowMixedLocalizations clave se eliminará automáticamente y se sustituirá por CFBundleLocalizations, en la que se enumeran todos los idiomas compatibles. En el caso de ` qmake `, este proceso debe realizarse manualmente.
Barra de menús
Qt detecta las barras de menú y las convierte en barras de menú nativas de Mac. La integración de esto en las aplicaciones Qt existentes suele ser automática. Sin embargo, si tienes necesidades especiales, la implementación de Qt selecciona actualmente una barra de menú comenzando por la ventana activa (por ejemplo, QGuiApplication::focusWindow()) y aplicando las siguientes pruebas:
- Si la ventana tiene un QMenuBar, se utiliza este.
- Si la ventana es modal, se utiliza su barra de menús. Si no se especifica ninguna barra de menús, se utiliza una barra de menús predeterminada (tal y como se describe a continuación).
- Si la ventana no tiene ventana principal, se utiliza la barra de menús predeterminada (tal y como se describe a continuación).
Estas comprobaciones se realizan a lo largo de toda la cadena de ventanas padre hasta que se cumpla una de las reglas anteriores. Si todo lo demás falla, se creará una barra de menús predeterminada. La barra de menús predeterminada en Qt es una barra de menús vacía. Sin embargo, puedes crear una barra de menús predeterminada diferente creando una ` QMenuBar` sin padre. La primera que se cree se designará como la barra de menús predeterminada y se utilizará siempre que se necesite una barra de menús predeterminada.
El uso de barras de menú nativas introduce ciertas limitaciones en las clases de Qt. La sección con la lista de limitaciones que figura a continuación ofrece más información.
Qt ofrece compatibilidad con la barra de menús global mediante QMenuBar. Los usuarios de macOS esperan tener una barra de menús en la parte superior de la pantalla y Qt respeta esta expectativa.
Además, los usuarios esperan que se respeten ciertas convenciones; por ejemplo, el menú de la aplicación debe contener «Acerca de», «Preferencias», «Salir», etc. Qt se ajusta a estas convenciones, aunque no ofrece ningún medio para interactuar directamente con el menú de la aplicación.
Cada « QAction » tiene una propiedad « menuRole » que controla la ubicación específica de los elementos del menú de la aplicación; sin embargo, por defecto, el « menuRole » es « TextHeuristicRole », lo que significa que los elementos del menú se detectarán automáticamente según su « text ».
Otros elementos de menú estándar, como «Cortar», «Copiar», «Pegar» y «Seleccionar todo», son aplicables tanto en tu aplicación como en algunos cuadros de diálogo nativos, como QFileDialog. Es importante que crees estos elementos de menú con los atajos estándar para que las funciones de edición correspondientes estén habilitadas en los cuadros de diálogo. Por el momento no existen identificadores MenuRole para ellos, pero se detectarán automáticamente al igual que los elementos del menú de la aplicación cuando el QAction tenga el valor predeterminado TextHeuristicRole.
Teclas especiales
Para proporcionar el comportamiento esperado en las aplicaciones Qt en macOS, los valores de enumeración « Qt::Key_Meta », « Qt::MetaModifier » y « Qt::META » se corresponden con las teclas Control del teclado estándar de Apple, y los valores de enumeración « Qt::Key_Control », « Qt::ControlModifier » y « Qt::CTRL » se corresponden con las teclas Comando.
Dock
Es posible interactuar con el Dock. El icono se puede establecer llamando a ` QWindow::setIcon()` desde la ventana principal de la aplicación. La llamada a `setIcon()` se puede realizar tantas veces como sea necesario, lo que permite actualizar el icono fácilmente.
Accesibilidad
Muchos usuarios interactúan con macOS mediante dispositivos de asistencia. Con Qt, el objetivo es que esto se realice de forma automática en tu aplicación, de modo que se ajuste a las prácticas aceptadas en su plataforma. Qt utiliza el marco de accesibilidad de Apple para facilitar el acceso a los usuarios con discapacidad.
Soporte para bibliotecas e implementación
Qt ofrece compatibilidad con estructuras de macOS como los Frameworks y los paquetes. Es importante tener en cuenta estas estructuras, ya que afectan directamente a la implementación de las aplicaciones.
Qt ofrece una herramienta de implementación, macdeployqt, para simplificar el proceso de implementación. El artículo «Qt para macOS: Implementación» describe el proceso de implementación con más detalle.
Bibliotecas de Qt como Frameworks
Por defecto, Qt se compila como un conjunto de marcos. Los marcos son la forma preferida de distribuir bibliotecas en macOS. La página web de Apple «Framework Programming Guide» (Guía de programación de marcos) ofrece mucha más información sobre los marcos.
Es importante recordar que los marcos de trabajo siempre se vinculan con las versiones finales de las bibliotecas. Si se desea utilizar la versión de depuración de un marco de trabajo de Qt, utilice las variables de entorno ` DYLD_IMAGE_SUFFIX ` para asegurarse de que se carga la versión de depuración:
export DYLD_IMAGE_SUFFIX=_debugComo alternativa, puedes intercambiar temporalmente las versiones de depuración y de lanzamiento, tal y como se documenta en la nota técnica «Debugging Magic» de Apple.
Si no quieres utilizar marcos, basta con configurar Qt con -no-framework.
./configure -no-frameworkBibliotecas basadas en paquetes
Si quieres utilizar algunas bibliotecas dinámicas en el paquete de la aplicación de macOS (el directorio de la aplicación), crea un subdirectorio llamado «Frameworks» en el directorio del paquete de la aplicación y coloca allí tus bibliotecas dinámicas. La aplicación encontrará una biblioteca dinámica si tiene el nombre de instalación @executable_path/../Frameworks/libname.dylib.
Si utiliz qmake s y Makefiles, utiliza la configuración « QMAKE_LFLAGS_SONAME »:
QMAKE_LFLAGS_SONAME = -Wl,-install_name,@executable_path/../Frameworks/Como alternativa, puede modificar el nombre de instalación utilizando la opción « install_name_tool(1) » en la línea de comandos.
La variable de entorno ` DYLD_LIBRARY_PATH ` anulará esta configuración, así como cualquier otra ruta predeterminada, como la búsqueda de bibliotecas dinámicas en ` /usr/lib ` y otras ubicaciones predeterminadas similares.
Combinación de bibliotecas
Si desea compilar una nueva biblioteca dinámica que combine las bibliotecas dinámicas de Qt, debe introducir la opción « ld -r ». De este modo, la información de relocalización se almacena en el archivo de salida, de modo que este archivo pueda ser objeto de otra ejecución de « ld ». Para ello, hay que establecer la opción « -r » en el archivo « .pro » y la configuración « LFLAGS ».
Orden de inicialización
dyld(1) llama a los inicializadores estáticos globales en el orden en que se enlazan con la aplicación. Si una biblioteca se enlaza con Qt y hace referencia a las variables globales de Qt (desde inicializadores globales de tu propia biblioteca), enlaza la aplicación con Qt antes de enlazarla con la biblioteca. De lo contrario, el resultado será indefinido, ya que los inicializadores globales de Qt aún no se habrán llamado.
Opciones de compilación
Las siguientes opciones resultan útiles cuando se desea definir código específico para macOS:
Q_OS_DARWINSe define cuando Qt detecta que te encuentras en un sistema basado en Darwin, como macOS o iOS.Q_OS_MACOSSe define cuando se está en un sistema macOS.
Nota: « Q_WS_MAC » ya no está definido en Qt 5 y versiones posteriores.
Si deseas definir código para versiones específicas de macOS, utiliza las macros de disponibilidad definidas en /usr/include/AvailabilityMacros.h.
La documentación de QSysInfo y QOperatingSystemVersion contiene información sobre la comprobación de la versión en tiempo de ejecución.
Acceso a la API nativa de macOS
Acceso a la ruta del paquete
Las aplicaciones de macOS están estructuradas como un directorio (que termina en .app). Este directorio contiene subdirectorios y archivos. Puede resultar útil colocar elementos, como complementos y documentación en línea, dentro de este paquete. El siguiente código devuelve la ruta del paquete de la aplicación:
#ifdef Q_OS_MAC
QString bundlePath = QString::fromNSString(NSBundle.mainBundle.bundlePath);
qDebug() << "Bundle path =" << bundlePath;
#endifPara obtener más información sobre el uso de la API NSBundle, visita el sitio web para desarrolladores de Apple.
QCoreApplication::applicationDirPathSe puede utilizar () para determinar la ruta del archivo binario dentro del paquete.
Uso de paneles nativos de Cocoa
El distribuidor de eventos de Qt es más flexible que el que ofrece Cocoa y permite al usuario activar el distribuidor de eventos (y ejecutar QEventLoop::exec) sin tener que preocuparse de si hay o no cuadros de diálogo modales en pantalla (lo cual supone una diferencia con respecto a Cocoa). Por lo tanto, necesitamos realizar una gestión adicional en Qt para manejar esto correctamente, lo que, por desgracia, dificulta la combinación de paneles nativos. La mejor forma de hacerlo, por el momento, es seguir el patrón que se muestra a continuación, en el que enviamos la llamada a la función mediante código nativo en lugar de llamarla directamente. De este modo, sabemos que Qt ha actualizado correctamente cualquier recursión pendiente del bucle de eventos antes de que se muestre el panel nativo:
#include <QtGui>
class NativeProxyObject : public QObject
{
Q_OBJECT
public slots:
void execNativeDialogLater()
{
QMetaObject::invokeMethod(this, "execNativeDialogNow", Qt::QueuedConnection);
}
void execNativeDialogNow()
{
NSRunAlertPanel(@"A Native dialog", @"", @"OK", @"", @"");
}
};
#include "main.moc"
int main(int argc, char **argv){
QApplication app(argc, argv);
NativeProxyObject proxy;
QPushButton button("Show native dialog");
QObject::connect(&button, SIGNAL(clicked()), &proxy, SLOT(execNativeDialogLater()));
button.show();
return app.exec();
}Limitaciones
MySQL y macOS
Parece que hay un problema cuando se definen tanto -prebind como -multi_module al vincular bibliotecas C estáticas a bibliotecas dinámicas. Si aparece el siguiente mensaje de error al vincular Qt:
ld: common symbols not allowed with MH_DYLIB output format with the -multi_module option
/usr/local/mysql/lib/libmysqlclient.a(my_error.o) definition of common _errbuff (size 512)
/usr/bin/libtool: internal link edit command failedvuelve a vincular Qt utilizando la opción -single_module. Este problema solo se produce al integrar el controlador de MySQL en Qt. No afecta a los complementos ni a las compilaciones estáticas.
D-Bus y macOS
El módulo « QtDBus » carga de forma predeterminada la biblioteca «libdbus-1» de forma dinámica en macOS. Esto significa que las aplicaciones que se vinculan al módulo « QtDBus » se cargarán incluso en sistemas macOS que no dispongan de las bibliotecas, pero no podrán conectarse a ningún servidor D-Bus ni abrir un servidor mediante « QDBusServer ».
Para utilizar la funcionalidad de D-Bus, es necesario instalar la biblioteca libdbus-1, por ejemplo, a través de Homebrew, Fink o MacPorts. Es posible que desees incluir esas bibliotecas en el paquete de tu aplicación si vas a implementarla en otros sistemas. Además, ten en cuenta que en macOS no existe un bus del sistema y que el bus de sesión solo se iniciará una vez que launchd esté configurado para gestionarlo.
Acciones del menú
- Las acciones de un « QMenu » con atajos de teclado que tengan más de una pulsación (QKeySequence) no se mostrarán correctamente cuando QMenu se traduzca a una barra de menús nativa de Mac. Se mostrará la primera tecla. Sin embargo, el atajo seguirá activándose igual que en el resto de plataformas.
- QMenu Los objetos utilizados en la barra de menús nativa no pueden gestionar eventos de Qt a través de los controladores de eventos habituales. Instala un delegado en el propio menú para recibir notificaciones de estos cambios. Como alternativa, plantéate utilizar las señales ` QMenu::aboutToShow()` y ` QMenu::aboutToHide()` para realizar un seguimiento de la visibilidad del menú; estas señales ofrecen una solución que debería funcionar en todas las plataformas compatibles con Qt.
- Por defecto, Qt crea un elemento de menú nativo «Salir» que reacciona al atajo
CMD+Q. Al crear un QAction para la función « QAction::QuitRole », se sustituirá dicho elemento de menú. Por lo tanto, la acción de sustitución debe conectarse bien a la ranura QCoreApplication::quit, bien a una ranura personalizada que detenga la aplicación.
Widgets nativos
Qt admite hojas, representadas por el indicador de ventana Qt::Sheet.
Por lo general, cuando se habla de una aplicación nativa de macOS, «nativa» significa una aplicación que interactúa directamente con el sistema de ventanas subyacente, en lugar de una que utilice alguna capa intermediaria. Las aplicaciones Qt se ejecutan como elementos de primera clase, al igual que las aplicaciones Cocoa. Utilizamos Cocoa internamente para comunicarnos con el sistema operativo.
Advertencias sobre la visibilidad de los símbolos
En el contexto de la vinculación de bibliotecas de C++, las funciones y los objetos se denominan «símbolos». Los símbolos pueden tener visibilidad « default » o « hidden ».
Por motivos de rendimiento, Qt y muchas otras bibliotecas compilan sus fuentes utilizando, por defecto, la visibilidad « hidden », y solo marcan los símbolos con visibilidad « default » cuando están destinados a ser utilizados en proyectos de los usuarios.
Lamentablemente, el enlazador de Apple puede generar advertencias cuando una biblioteca se compila con visibilidad « hidden » y una aplicación o biblioteca de un proyecto de usuario se compila con visibilidad « default ».
Si los desarrolladores del proyecto desean silenciar la advertencia, deben compilar el código de su proyecto también con visibilidad « hidden ».
En CMake, esto se puede hacer añadiendo el siguiente código a tu ` CMakeLists.txt`:
set(CMAKE_CXX_VISIBILITY_PRESET hidden)En qmake, esto se puede hacer añadiendo el siguiente código a tu archivo ` .pro `:
CONFIG+=hide_symbolsEn caso de que un proyecto compile bibliotecas, cualquier símbolo de la biblioteca que esté destinado a ser utilizado en otra biblioteca o aplicación deberá marcarse explícitamente con visibilidad « default ». Por ejemplo, esto puede hacerse anotando dichas funciones o clases con « Q_DECL_EXPORT ».
Falta el paquete dSYM en el xcarchive creado por un proyecto de CMake en Xcode
Debido a un error en Xcode y a ciertas limitaciones de CMake, un proyecto de Xcode generado por CMake no incluirá el paquete « dSYM » de una aplicación en un « xcarchive » durante la tarea de archivado de Xcode.
Qt ofrece una solución alternativa opcional para que el paquete « dSYM » se incluya en el archivo « xcarchive », pero esto conlleva algunas desventajas. Es decir, las siguientes funciones de CMake no funcionarán correctamente:
- cualquier expresión generadora de «
$<TARGET_FILE:app>» podría expandirse a una ruta no válida que no conduzca al binario de la aplicación - la variable
CMAKE_RUNTIME_OUTPUT_DIRECTORYy su propiedad de destino asociadaRUNTIME_OUTPUT_DIRECTORYse ignorarán aunque estén configuradas - otros problemas desconocidos
Para mitigar los problemas anteriores, puedes:
- activar la solución alternativa únicamente cuando se pretenda crear el archivo «
xcarchive» y no durante el desarrollo del proyecto - asegurarse de añadir únicamente ejecutables y bibliotecas en el directorio raíz del proyecto, y no en las llamadas a «
add_subdirectory».
Para activar la solución alternativa, configura el proyecto con la siguiente opción:
cmake . -DQT_USE_RISKY_DSYM_ARCHIVING_WORKAROUND=ONo establece la variable en el proyecto antes de cualquier llamada a qt_add_executable o qt_add_library:
set(QT_USE_RISKY_DSYM_ARCHIVING_WORKAROUND ON)
...
qt_add_executable(app)© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. 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.