Documentação de automação

Referência do esquema de URL

Abra uma janela de calendário, um painel ancorado ou uma sobreposição em tela cheia a partir de outro app do Mac.

Estes guias abrangem o popCalendar 1.3 e versões posteriores. Algumas ações exigem uma versão mais recente do sistema, conforme indicado abaixo.

Abra um calendário a partir de outro app

Esta interface exige macOS 12 ou posterior. Ative primeiro o controle por apps externos e CLI. Use popcalendar para a edição padrão e popcalendar-setapp para Setapp. Crie URLs com URLComponents e URLQueryItem, codificando URLs de retorno aninhadas como um único valor.

popcalendar://integration/open?v=1&session=com.example.calendar&presentation=window&mode=two-years&date=2027-01-01
popcalendar://integration/toggle?v=1&session=com.example.picker&presentation=popup&mode=month&anchor=400,850,40,24&width=520&height=720&arrow=top
Voltar ao índice

Comandos e sessões

Toda URL exige v=1 e um nome de sessão de 1 a 128 letras ASCII, dígitos, pontos, sublinhados ou hifens. Até oito sessões podem ficar abertas, incluindo um painel ou sobreposição em tela cheia. Abrir outra vista temporária substitui a anterior. Janelas normais permanecem abertas.

Comando ou opçãoO que faz
/openAbre uma sessão ou atualiza e traz uma sessão existente para a frente.
/toggleFecha a sessão se ela existir ou a abre caso contrário.
/updateAtualiza conteúdo ou geometria sem abrir uma sessão ausente nem assumir o foco.
/moveMuda apenas a geometria sem abrir uma sessão ausente nem assumir o foco.
/closeFecha a sessão. Fechar uma sessão ausente não tem efeito.
Voltar ao índice

Conteúdo e geometria

Comando ou opçãoO que faz
presentationwindow por padrão, popup ou fullscreen. Feche uma sessão ativa antes de mudar sua apresentação.
modemonth, two-months, year, two-years, month-year ou month-two-years. O padrão é year.
dateYYYY-MM-DD gregoriano no fuso horário do app. Por padrão, a primeira data do intervalo ou hoje.
start, endExtremos inclusivos em YYYY-MM-DD. Informe ambos, com start anterior ou igual a end.
selectionUse clear para remover a seleção. Não pode ser combinado com start e end.
calendar-setUUID de um conjunto salvo ou current para copiar o filtro ativo. Obtenha IDs via CLI ou Atalhos. IDs desconhecidos são rejeitados.
displayApenas para tela cheia. current usa o monitor do ponteiro, main usa o principal, ou informe um UUID. Monitores desconectados são substituídos por um disponível.
width, heightDimensões do conteúdo em pontos lógicos, cada uma de 240 a 8192. Informe ambas. Os pop-ups mantêm o tamanho solicitado desde o primeiro quadro visível. Janelas comuns redimensionáveis podem aumentar até atingir o mínimo legível. Os limites da tela têm prioridade. A CLI também aceita --size WIDTHxHEIGHT.
anchorRetângulo da âncora como x,y,width,height em coordenadas globais. Não pode ser combinado com x e y.
x, yPosição explícita em vez de uma âncora. Informe ambas. Um painel com posição explícita não tem seta.
coordinatesappkit usa o canto inferior esquerdo do monitor principal. top-left mede para baixo a partir do canto superior esquerdo. Monitores secundários podem ter coordenadas negativas. Os valores são pontos, não pixels.
arrowauto, top, bottom, left, right ou none. Nomeia a borda do painel que contém a seta. A posição pode inverter para manter o painel visível.
callbackUm esquema de URL personalizado registrado para retornar datas explicitamente confirmadas.

CLI usa os mesmos nomes com prefixo --, exceto selection=clear, que vira --clear-selection. Sobreposições em tela cheia rejeitam toda geometria exceto display. Parâmetros desconhecidos ou duplicados, datas malformadas e URLs acima de 16 KiB são rejeitados por completo.

Voltar ao índice

Foco e duração das janelas

As sessões têm datas, layout, seleção e filtro próprios. Não substituem janelas normais nem são restauradas após sair. update e move não ativam o app. Painéis fecham com cliques externos, perda de foco, Escape ou troca de Espaço. Painéis secundários fecham primeiro. Sobreposições em tela cheia também fecham ao trocar de app.

Em apps nativos, use NSWorkspace.open com uma URL explícita do aplicativo e OpenConfiguration.activates definido como false para popup, fullscreen, update, move e close. Envie move quando sua janela se mover e close quando fechar. A entrega de uma URL não confirma a aceitação pelo protocolo. Use CLI ou Atalhos quando precisar de uma resposta confirmada.

Voltar ao índice

Receba as datas selecionadas

O usuário precisa confirmar antes de executar o retorno. Cancelar, perder o foco ou sair não retorna nada. São enviados apenas datas, fuso horário e identificador de sessão. Não são incluídos eventos nem conteúdo do calendário. Retornos HTTP, HTTPS, file, data, JavaScript e popCalendar são rejeitados.

popcalendar://integration/open?v=1&session=choose-trip&mode=month&callback=my-app%3A%2F%2Fcalendar-selection%3Ftoken%3Dexample

Os parâmetros existentes da URL de retorno são preservados. Não use os nomes reservados abaixo. Valide a sessão esperada e seu próprio token opaco ao receber um resultado. Nunca inclua credenciais em uma URL.

Comando ou opçãoO que faz
pc-sessionO nome original da sessão.
pc-start, pc-endO primeiro e o último dia civil selecionados, ambos incluídos.
pc-rangesUm array JSON de pares [start, end] preservando até 128 intervalos separados.
pc-time-zoneO identificador de fuso horário das datas retornadas.
Voltar ao índice