WinToast
v1.3.0
O Wintoast é uma biblioteca levemente escrita em C ++, que traz uma integração completa das notificações modernas de brindes do Windows 8 , Windows 10 e Windows 11 .
As notificações de brinde permite que seu aplicativo informe os usuários sobre informações relevantes e eventos oportunos que eles devem ver e agir dentro do seu aplicativo, como uma nova mensagem instantânea, uma nova solicitação de amizade, notícias de última hora ou um evento de calendário.
O Wintoast integra todos os modelos padrão disponíveis na enumeração ToastTemplateType.
| Modelo | Descrição | Exemplo |
|---|---|---|
ImageAndText01 | Uma imagem grande e uma única corda envolta em três linhas de texto. |  |
ImageAndText02 | Uma imagem grande, uma corda de texto em negrito na primeira linha, uma série de texto regular envolto na segunda e terceira linhas. |  |
ImageAndText03 | Uma imagem grande, uma corda de texto em negrito envolvido nas duas primeiras linhas, uma sequência de texto regular na terceira linha. |  |
ImageAndText04 | Uma imagem grande, uma corda de texto em negrito na primeira linha, uma sequência de texto regular na segunda linha, uma sequência de texto regular na terceira linha. |  |
Text01 | String única embrulhada em três linhas de texto. |  |
Text02 | Uma corda de texto em negrito na primeira linha, uma sequência de texto regular envolto na segunda e terceira linhas. |  |
Text03 | Uma corda de texto em negrito envolvido nas duas primeiras linhas, uma série de texto regular na terceira linha. |  |
Text04 | Uma sequência de texto em negrito na primeira linha, uma sequência de texto regular na segunda linha, uma sequência de texto regular na terceira linha. |  |
Exemplo de um modelo ImageAndText02 :
WinToastTemplate templ = WinToastTemplate(WinToastTemplate::ImageAndText02);
templ.setTextField( L" title " , WinToastTemplate::FirstLine);
templ.setTextField( L" subtitle " , WinToastTemplate::SecondLine);
templ.setImagePath( L" C:/example.png " ); NOTA: O usuário pode usar o som do sistema padrão ou especificar um som a ser reproduzido quando uma notificação de brinde for exibida. O mesmo comportamento da imagem de notificação de brinde, por padrão, o Windows tente usar o ícone do aplicativo.*
Wintoast lide com diferentes eventos:
Crie seu manipulador personalizado para interagir com as ações do usuário subclassificando a interface IWinToastHandler :
class WinToastHandlerExample : public IWinToastHandler {
public:
WinToastHandlerExample ();
// Public interfaces
void toastActivated () const override ;
void toastActivated ( int actionIndex) const override ;
void toastDismissed (WinToastDismissalReason state) const override ;
void toastFailed () const override ;
};A documentação completa do conteúdo de notificação aqui.
Para criar notificações importantes, alarmes, lembretes e notificações de chamadas recebidas, basta usar uma notificação de aplicativo normal com um valor de cenário atribuído a ele. O cenário ajusta alguns comportamentos para criar uma experiência de usuário consistente e unificada. Existem quatro valores de cenário possíveis:
Defina o tempo após o qual uma notificação de brinde não é mais considerada atual ou válida e não deve ser exibida. O Windows tenta aumentar as notificações de brindes imediatamente após o show de chamadas, para que essa propriedade raramente seja usada.
Para o aplicativo Windows 8.x, essa propriedade também faz com que a notificação da brinde seja removida do Centro de Ação assim que os dados e o tempo especificados forem atingidos.
Nota: O comportamento padrão do Windows é ocultar a notificação automaticamente após o tempo definido nas configurações de facilidade de acesso do Windows. Se você precisar preservar a notificação no Windows Action Center por um período mais longo, precisará ligar para o método WinToastTemplate::setExpiration .
As diretrizes no estilo da Microsoft recomendam representar as imagens do perfil com uma imagem circular para fornecer uma representação consistente de pessoas entre os aplicativos e o shell. Defina a propriedade Hintcrop para circular para renderizar a imagem com uma colheita circular.
WinToastTemplate templ = WinToastTemplate(WinToastTemplate::ImageAndText02);
templ.setTextField( L" Matt sent you a friend request " , WinToastTemplate::FirstLine);
templ.setTextField( L" Hey, wanna dress up as wizards and ride around on hoverboards? " , WinToastTemplate::SecondLine);
templ.setImagePath( L" C:/example.png " );
templ.setHintCrop(WinToastTemplate::Circle);
A imagem do herói é uma imagem grande que aparece no topo de uma notificação de brindes. A imagem do herói é opcional e pode ser usada para fornecer contexto adicional ao usuário.
Nota: A imagem do herói não é suportada no Windows 8.1 e Windows Phone 8.1.
WinToastTemplate templ = WinToastTemplate(WinToastTemplate::ImageAndText02);
templ.setTextField( L" Mary Anne " , WinToastTemplate::FirstLine);
templ.setTextField( L" Check out where we camped last night! " , WinToastTemplate::SecondLine);
templ.setHeroImagePath( L" C:/example.png " );
A imagem do herói é especificada chamando o método WinToastTemplate::setHeroImagePath . O caminho da imagem pode ser um caminho de arquivo local ou um URI.
O segundo parâmetro do método WinToastTemplate::setHeroImagePath é um valor booleano que especifica se a imagem deve ser inlinada na notificação de brindes.
WinToastTemplate templ = WinToastTemplate(WinToastTemplate::ImageAndText01);
templ.setTextField( L" Feature image of the day " , WinToastTemplate::FirstLine);
templ.setHeroImagePath( L" C:/example.png " , true );
Você pode adicionar suas próprias ações, esse fato permite que você interaja com o usuário de uma maneira diferente:
WinToastTemplate templ = WinToastTemplate(WinToastTemplate::ImageAndText01);
templ.setTextField( L" New product in stock " , WinToastTemplate::FirstLine);
std::vector<std::wstring> actions;
actions.push_back( L" See more details " );
actions.push_back( L" Remind me later " );
// ...
for ( auto const &action : actions) {
templ. addAction (action);
}
WinToast::instance ()->showToast(templ, handler) 
Novo na atualização de aniversário: se você precisar fazer referência à fonte do seu conteúdo, poderá usar o texto de atribuição. Este texto é sempre exibido abaixo de todos os elementos de texto, mas acima das imagens embutidas. O texto usa um tamanho um pouco menor que os elementos de texto padrão para ajudar a distinguir dos elementos regulares de texto.
WinToastTemplate templ = WinToastTemplate(WinToastTemplate::Text02);
templ.setTextField( L" Mary Anne " , WinToastTemplate::FirstLine);
templ.setTextField( L" Check out where we camped last night! " , WinToastTemplate::SecondLine);
templ.setHeroImagePath( L" C:/example.png " );
templ.setAttributionText( L" Via SMS " );
A quantidade de tempo a torrada deve ser exibida. Este atributo pode ter um dos seguintes valores: - Sistema : Configuração do sistema padrão. - curto : configuração de curto período de tempo padrão. - Long : Configuração de longo tempo do sistema padrão.
Você pode modificar os diferentes comportamentos do som: - Padrão : reproduz o arquivo de áudio apenas uma vez. - Silencioso : desligue o som. - Loop : toca o som dado em um loop durante a existência de brinde.
O Wintoast permite a modificação do arquivo de áudio padrão. Adicione o arquivo fornecido aos recursos dos seus projetos ( deve ser MS-Appx: // ou ms-appdata: // Path ) e defini-lo ligando para:
WinToastTemplate::setAudioPath
Por padrão, o Wintoast verifica se seus sistemas suportam os recursos, ignorando os não suportados.
Existem vários motivos pelos quais o Wintoast pode falhar, é por isso que a biblioteca notifica o chamador sobre o motivo da falha. Esses são o código para cada falha:
| Wintoterror | Código de erro | Mensagem de erro |
|---|---|---|
NoError | 0x00 | Sem erro. O processo foi executado corretamente |
NotInitialized | 0x01 | A biblioteca não foi inicializada |
SystemNotSupported | 0x02 | O sistema operacional não suporta wintoast |
ShellLinkNotCreated | 0x03 | A biblioteca não conseguiu criar um link de shell para o aplicativo |
InvalidAppUserModelID | 0x04 | O aumi não é válido |
InvalidParameters | 0x05 | Os parâmetros usados para configurar a biblioteca não são válidos normalmente porque um AUMI inválido ou o nome do aplicativo |
NotDisplayed | 0x06 | A torrada foi criada corretamente, mas Wintoast não foi capaz de exibir a torrada |
UnknownError | 0x07 | Erro desconhecido |
Um exemplo comum de uso é verificar ao inicializar a biblioteca ou mostrar uma notificação de brinde o possível código de falha:
WinToast::WinToastError error;
const auto succedded = WinToast::instance()-> initialize (&error);
if (!succedded) {
std::wcout << L" Error, could not initialize the lib. Error number: "
<< error << std::endl;
}
...
// Configure the template
...
const auto toast_id = WinToast::instance()-> showToast (templ, handler, &error);
if (toast_id < 0 ) {
std::wcout << L" Error: Could not launch your toast notification. Error: "
<< error << std::endl;
}Para um uso fácil, você pode usar a instância Singleton disponível.
Primeira etapa, importe o arquivo de cabeçalho wintoastlib.h para o seu projeto. Você deve verificar se a versão do Windows é suportada pela biblioteca.
using namespace WinToastLib ;
....
if (!WinToast::isCompatible()) {
std::wcout << L" Error, your system in not supported! " << std::endl;
}Configure o ID do modelo de usuário do aplicativo, isso pode ser feito usando o ajudante existente:
WinToast::instance ()->setAppName( L" WinToastExample " );
const auto aumi = WinToast::configureAUMI( L" mohabouje " , L" wintoast " , L" wintoastexample " , L" 20161006 " );
WinToast::instance ()->setAppUserModelId(aumi); Inicialize todas as dependências e verifique se o Wintoast foi inicializado com sucesso em seu sistema:
if (!WinToast::instance()-> initialize ()) {
std::wcout << L" Error, could not initialize the lib! " << std::endl;
} Implemente seu próprio manipulador de ação subclassificando a interface IWinToastHandler e personalize seu modelo:
WinToastHandlerExample* handler = new WinToastHandlerExample;
WinToastTemplate templ = WinToastTemplate(WinToastTemplate::ImageAndText02);
templ.setImagePath( L" C:/example.png " );
templ.setTextField( L" title " , WinToastTemplate::FirstLine);
templ.setTextField( L" subtitle " , WinToastTemplate::SecondLine);Finalmente mostre os resultados:
const auto toast_id = WinToast::instance()-> showToast (templ, handler, &error);
if (toast_id < 0 ) {
std::wcout << L" Error: Could not launch your toast notification! " << std::endl;
}Shao Voon Wong escreveu um excelente artigo sobre o uso de Wintoast. Você pode encontrá -lo aqui.
Se você estiver usando um gerenciador de pacotes, existe uma porta para vcpkg. Caso contrário, a maneira mais fácil é copiar os arquivos de origem como dependências externas.
O Windows permite a configuração do comportamento padrão de uma notificação de brinde. Isso pode ser feito na configuração da facilidade de acesso , modificando a guia outras opções .
A configuração do sistema ajuda você a definir quanto tempo você deseja que as notificações apareçam por (5 segundos a 5 minutos) como ativar notificações visuais para som.
