SingleApplication

Aplicación única

Este es un reemplazo de QtSingleApplication para Qt5 y Qt6 .

Mantiene la instancia principal de su aplicación y elimina todas las instancias posteriores. Puede (si está habilitado) generar instancias secundarias (no relacionadas con la primaria) y puede enviar datos a la instancia primaria desde instancias secundarias.

Documentación

Puede encontrar la referencia de uso completa y ejemplos aquí.

Uso

La clase SingleApplication hereda de cualquier clase Q[Core|Gui]Application que especifique mediante la macro QAPPLICATION_CLASS ( QCoreApplication es el valor predeterminado). El uso posterior es similar al uso de las clases Q[Core|Gui]Application .

Puede utilizar la biblioteca como si utilizara cualquier otra clase derivada de QCoreApplication :

# include < QApplication >
# include < SingleApplication.h >

int main ( int argc, char * argv[] )
{
    SingleApplication app ( argc, argv );

    return app. exec ();
}

Para incluir los archivos de la biblioteca, le recomendaría que los agregue como un submódulo git a su proyecto. Así es como:

git submodule add https://github.com/itay-grudev/SingleApplication.git singleapplication

Qhacer:

Luego incluya el archivo singleapplication.pri en su archivo de proyecto .pro .

 include ( singleapplication/singleapplication.pri )
DEFINES += QAPPLICATION_CLASS = QApplication

Chacer:

Luego incluya el subdirectorio en su archivo de proyecto CMakeLists.txt .

 set (QAPPLICATION_CLASS QApplication CACHE STRING "Inheritance class for SingleApplication" )
add_subdirectory (src/third-party/singleapplication)
target_link_libraries ( ${PROJECT_NAME} SingleApplication::SingleApplication)

Incluir directamente este repositorio como un submódulo de Git, o incluso simplemente una copia superficial del código fuente en nuevos proyectos, puede no ser ideal cuando se usa CMake. Otra opción es utilizar el módulo FetchContent de CMake, disponible desde la versión 3.11 .

 # Define the minumun CMake version, as an example 3.24
cmake_minimum_required ( VERSION 3.24)

# Include the module
include (FetchContent)

# If using Qt6, override DEFAULT_MAJOR_VERSION
set (QT_DEFAULT_MAJOR_VERSION 6 CACHE STRING "Qt version to use, defaults to 6" )

# Set QAPPLICATION_CLASS
set (QAPPLICATION_CLASS QApplication CACHE STRING "Inheritance class for SingleApplication" )


# Declare how is the source going to be obtained
FetchContent_Declare(
  SingleApplication
  GIT_REPOSITORY https://github.com/itay-grudev/SingleApplication
  GIT_TAG        master
  #GIT_TAG        e22a6bc235281152b0041ce39d4827b961b66ea6
)

# Fetch the repository and make it available to the build
FetchContent_MakeAvailable(SingleApplication)

# Then simply use find_package as usual
find_package (SingleApplication)

# Finally add it to the target_link_libraries() section
target_link_libraries (ClientePOS PRIVATE
    Qt ${QT_VERSION_MAJOR} ::Widgets
    Qt ${QT_VERSION_MAJOR} ::Network
    Qt ${QT_VERSION_MAJOR} ::Sql

    SingleApplication::SingleApplication
)

La biblioteca configura un QLocalServer y un bloque QSharedMemory . La primera instancia de su Aplicación es su Instancia Primaria. Verificará si el bloque de memoria compartida existe y, de lo contrario, iniciará un QLocalServer y escuchará las conexiones. Cada instancia posterior de su aplicación verificará si el bloque de memoria compartida existe y, si existe, se conectará al QLocalServer para notificar a la instancia principal que se ha iniciado una nueva instancia, después de lo cual terminará con el código de estado 0 . En la instancia primaria, SingleApplication emitiría la señal instanceStarted() al detectar que se había iniciado una nueva instancia.

La biblioteca usa stdlib para finalizar el programa con la función exit() .

Además, no olvide especificar qué clase QCoreApplication está usando su aplicación si no es QCoreApplication como en los ejemplos anteriores.

Señal de instancia iniciada

La clase SingleApplication implementa una señal instanceStarted() . Puede vincularse a esa señal para abrir la ventana de su aplicación cuando se inició una nueva instancia, por ejemplo.

 // window is a QWindow instance
QObject::connect (
    &app,
    &SingleApplication::instanceStarted,
    &window,
    &QWindow::raise
);

Usar SingleApplication::instance() es una buena manera de obtener la instancia SingleApplication para vincularla a sus señales en cualquier parte de su programa.

Nota: En Windows, la capacidad de poner las ventanas de la aplicación en primer plano está restringida. Consulte implementaciones específicas de Windows para obtener una solución alternativa y un ejemplo de implementación.

Instancias secundarias

Si desea poder iniciar instancias secundarias adicionales (no relacionadas con su instancia principal), debe habilitarlo con el tercer parámetro del constructor SingleApplication . El valor predeterminado es false , lo que significa que no hay instancias secundarias. A continuación se muestra un ejemplo de cómo iniciaría una instancia secundaria, enviaría un mensaje con los argumentos de la línea de comando a la instancia principal y luego la cerraría.

 int main ( int argc, char *argv[])
{
    SingleApplication app ( argc, argv, true );

    if ( app. isSecondary () ) {
        app. sendMessage (  app. arguments (). join ( ' ' )). toUtf8 () );
        app. exit ( 0 );
    }

    return app. exec ();
}

Nota: Una instancia secundaria no provocará la emisión de la señal instanceStarted() de forma predeterminada. Consulte SingleApplication::Mode para obtener más detalles.*

Puede verificar si su instancia es primaria o secundaria con los siguientes métodos:

app.isPrimary();
// or
app.isSecondary();

Nota: Si su instancia principal finaliza, una instancia recién lanzada reemplazará a la principal incluso si se ha configurado el indicador Secundario.*

Ejemplos

Hay tres ejemplos proporcionados en este repositorio:

• Ejemplo básico que evita que una instancia secundaria inicie examples/basic
• Un ejemplo de una aplicación gráfica que genera su examples/calculator de ventana principal
• Una aplicación de consola que envía a la instancia principal sus parámetros de línea de comando examples/sending_arguments

Versionado

Cada versión principal introduce cambios muy significativos o no es compatible con la versión anterior. Las versiones menores solo agregan funciones adicionales, correcciones de errores o mejoras de rendimiento y son compatibles con la versión anterior. Consulte CHANGELOG.md para obtener más detalles.

Implementación

La biblioteca se implementa con un bloque QSharedMemory que es seguro para subprocesos y garantiza que no se producirá una condición de carrera. También utiliza un QLocalSocket para notificar al proceso principal que se ha generado una nueva instancia y así invocar la señal instanceStarted() y enviar mensajes a la instancia principal.

Además, la biblioteca puede recuperarse de una eliminación forzosa en sistemas *nix y restablecerá el bloque de memoria dado que no hay otras instancias en ejecución.

Licencia

Esta biblioteca y su documentación de respaldo, con excepción de los ejemplos de calculadora Qt que se distribuyen bajo la licencia BSD, se publican bajo los términos de The MIT License (MIT) con una condición adicional:

Permission is not granted to use this software or any of the associated files
as sample data for the purposes of building machine learning models.