SingleApplication

Aplicativo único

Esta é uma substituição do QtSingleApplication para Qt5 e Qt6 .

Mantém a instância primária do seu aplicativo e elimina cada instância subsequente. Ele pode (se habilitado) gerar instâncias secundárias (não relacionadas à primária) e pode enviar dados para a instância primária a partir de instâncias secundárias.

Documentação

Você pode encontrar a referência completa de uso e exemplos aqui.

Uso

A classe SingleApplication herda de qualquer classe Q[Core|Gui]Application especificada por meio da macro QAPPLICATION_CLASS ( QCoreApplication é o padrão). O uso adicional é semelhante ao uso das classes Q[Core|Gui]Application .

Você pode usar a biblioteca como se usasse qualquer outra classe derivada de QCoreApplication :

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

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

    return app. exec ();
}

Para incluir os arquivos da biblioteca, recomendo que você os adicione como um submódulo git ao seu projeto. Veja como:

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

Qfazer:

Em seguida, inclua o arquivo singleapplication.pri no arquivo de projeto .pro .

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

CMake:

Em seguida, inclua o subdiretório no arquivo de projeto 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 diretamente este repositório como um submódulo Git, ou mesmo apenas uma cópia superficial do código-fonte em novos projetos, pode não ser ideal ao usar o CMake. Outra opção é utilizar o módulo FetchContent do CMake, disponível desde a versão 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
)

A biblioteca configura um QLocalServer e um bloco QSharedMemory . A primeira instância do seu aplicativo é sua instância primária. Ele verificaria se o bloco de memória compartilhada existe e, caso contrário, iniciaria um QLocalServer e escutaria conexões. Cada instância subsequente do seu aplicativo verificaria se o bloco de memória compartilhada existe e, se existir, ele se conectará ao QLocalServer para notificar a instância primária de que uma nova instância foi iniciada, após o que terminaria com o código de status 0 . Na instância primária, SingleApplication emitiria o sinal instanceStarted() ao detectar que uma nova instância foi iniciada.

A biblioteca usa stdlib para encerrar o programa com a função exit() .

Também não se esqueça de especificar qual classe QCoreApplication seu aplicativo está usando se não for QCoreApplication como nos exemplos acima.

Sinal de início de instância

A classe SingleApplication implementa um sinal instanceStarted() . Você pode vincular a esse sinal para aumentar a janela do seu aplicativo quando uma nova instância for iniciada, por exemplo.

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

Usar SingleApplication::instance() é uma maneira legal de obter a instância SingleApplication para vincular seus sinais em qualquer lugar do seu programa.

Nota: No Windows, a capacidade de colocar as janelas do aplicativo em primeiro plano é restrita. Consulte Implementações específicas do Windows para obter uma solução alternativa e um exemplo de implementação.

Instâncias Secundárias

Se você quiser iniciar instâncias secundárias adicionais (não relacionadas à sua instância primária), será necessário habilitá-las com o terceiro parâmetro do construtor SingleApplication . O padrão é false o que significa que não há instâncias secundárias. Aqui está um exemplo de como você iniciaria uma instância secundária, enviaria uma mensagem com os argumentos da linha de comando para a instância primária e depois encerraria.

 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: Uma instância secundária não causará a emissão do sinal instanceStarted() por padrão. Consulte SingleApplication::Mode para obter mais detalhes.*

Você pode verificar se sua instância é primária ou secundária com os seguintes métodos:

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

Observação: se sua Instância Primária for encerrada, uma instância recém-iniciada substituirá a Instância Primária, mesmo que o sinalizador Secundário tenha sido definido.*

Exemplos

Existem três exemplos fornecidos neste repositório:

• Exemplo básico que impede que uma instância secundária inicie examples/basic
• Um exemplo de um aplicativo gráfico que levanta sua janela pai examples/calculator
• Um aplicativo de console enviando a instância primária e seus parâmetros de linha de comando examples/sending_arguments

Versionamento

Cada versão principal introduz alterações muito significativas ou não é compatível com versões anteriores. Versões secundárias apenas adicionam recursos adicionais, correções de bugs ou melhorias de desempenho e são compatíveis com versões anteriores da versão anterior. Consulte CHANGELOG.md para obter mais detalhes.

Implementação

A biblioteca é implementada com um bloco QSharedMemory que é thread-safe e garante que não ocorrerá uma condição de corrida. Ele também usa um QLocalSocket para notificar o processo principal de que uma nova instância foi gerada e, assim, invocar o sinal instanceStarted() e para enviar mensagens à instância primária.

Além disso, a biblioteca pode se recuperar de uma eliminação forçada em sistemas *nix e redefinirá o bloco de memória, desde que não haja outras instâncias em execução.

Licença

Esta biblioteca e sua documentação de suporte, com exceção dos exemplos da calculadora Qt que são distribuídos sob a licença BSD, são lançadas sob os termos The MIT License (MIT) com uma condição extra, que:

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.