Picture-in-picture

O recurso picture-in-picture (PIP) para dispositivos portáteis Android permite que os usuários redimensionem um app com uma atividade em andamento para uma janela pequena. O PIP é especialmente útil para apps de vídeo porque o conteúdo continua sendo reproduzido enquanto o usuário pode realizar outras ações. Os usuários podem manipular a posição dessa janela pelo SystemUI e interagir com o aplicativo que está no modo picture-in-picture com até três ações fornecidas pelo app.

O PIP exige a ativação explícita de apps compatíveis e funciona por atividade. Um único aplicativo pode ter várias atividades, apenas uma delas está no PIP. As atividades pedem para entrar no picture-in-picture chamando enterPictureInPictureMode() e recebem callbacks de atividade na forma de onPictureInPictureModeChanged().

O método setPictureInPictureParams() permite que as atividades controlem a proporção enquanto estão no PIP e em ações personalizadas, o que permite que os usuários interajam com a atividade sem precisar expandi-la. No PIP, a atividade está em um estado pausado, mas renderizado, e não recebe diretamente a entrada de toque ou o foco da janela. Só é possível usar uma única tarefa no PIP por vez.

Mais informações estão disponíveis na documentação Picture-in-picture para desenvolvedores Android.

Requisitos do dispositivo

Para oferecer suporte ao PIP, ative o recurso do sistema PackageManager#FEATURE_PICTURE_IN_PICTURE em /android/frameworks/base/core/java/android/content/pm/PackageManager.java. Os dispositivos que oferecem suporte ao PIP precisam ter uma tela maior que 220 dp na largura mínima. Semelhante à tela dividida, o PIP permite que várias atividades sejam executadas na tela ao mesmo tempo. Portanto, os dispositivos precisam ter CPU e RAM suficientes para oferecer suporte a esse caso de uso.

Implementação

A maior parte do gerenciamento do ciclo de vida da atividade é feita no sistema entre ActivityManager e WindowManager. A implementação da interface de referência está no pacote SystemUI.

As modificações no sistema não podem afetar o comportamento intrínseco conforme definido pelos testes do conjunto de teste de compatibilidade (CTS). A lógica do sistema para o PIP gira principalmente em torno do gerenciamento de tarefas e atividades na pilha "fixada". Confira uma breve visão geral da classe:

  • ActivityRecord:rastreia o estado de imagem em tela dividida de cada atividade. Para impedir que os usuários entrem no PIP em determinadas circunstâncias, como na tela de bloqueio ou durante a RV, adicione casos a checkEnterPictureInPictureState().
  • ActivityManagerService:a interface principal da atividade para solicitar a entrada no PIP e a interface para chamadas de WindowManager e SystemUI para mudar o estado da atividade do PIP.
  • ActivityStackSupervisor:chamado pelo ActivityManagerService para mover tarefas para dentro ou para fora da pilha fixada, atualizando o WindowManager conforme necessário.
  • PinnedStackWindowController:a interface WindowManager do ActivityManager.
  • PinnedStackController:informa mudanças no sistema para SystemUI, como IME mostrado/oculto, mudança de proporção ou de ações.
  • BoundsAnimationController:anima as janelas de atividade do PIP de uma forma que não aciona uma mudança de configuração durante o redimensionamento.
  • PipSnapAlgorithm:uma classe compartilhada usada no sistema e no SystemUI que controla o comportamento de ajuste da janela PIP perto das bordas da tela.

A referência SystemUI oferece uma implementação completa do PIP que oferece suporte à apresentação de ações personalizadas aos usuários e à manipulação geral, como expansão e dispensa. Os fabricantes de dispositivos podem usar essas mudanças, desde que não afetem os comportamentos intrínsecos, conforme definido pelo CDD. Confira uma breve visão geral da classe:

  • PipManager:o componente SystemUI iniciado com SystemUI.
  • PipTouchHandler:o gerenciador de toque, que controla os gestos que manipulam o PIP. Ele só é usado enquanto o consumidor de entrada do PIP está ativo (consulte InputConsumerController). Novos gestos podem ser adicionados aqui.
  • PipMotionHelper:uma classe de conveniência que rastreia a posição do PIP e a região permitida na tela. Faz uma chamada para ActivityManagerService para atualizar ou animar a posição e o tamanho do PIP.
  • PipMenuActivityController:inicia uma atividade que mostra as ações fornecidas pela atividade que está no PIP. Essa atividade é uma atividade de sobreposição de tarefas e remove o consumidor de entrada sobreposto para permitir que ela seja interativa.
  • PipMenuActivity:a implementação da atividade do menu.
  • PipMediaController:o listener que atualiza SystemUI quando a sessão de mídia muda de uma forma que pode afetar as ações padrão no PIP.
  • PipNotificationController:o controlador que garante que uma notificação esteja ativa enquanto um usuário usa o recurso PIP.
  • PipDismissViewController:a sobreposição mostrada aos usuários quando eles começam a interagir com o PIP para indicar que ele pode ser dispensado.

Posição padrão

Há vários recursos do sistema que controlam a posição padrão do PIP:

  • config_defaultPictureInPictureGravity:o número inteiro gravity, que controla o canto para colocar o PIP, como BOTTOM|RIGHT.
  • config_defaultPictureInPictureScreenEdgeInsets:os deslocamentos das laterais da tela para posicionar o PIP.
  • config_pictureInPictureDefaultSizePercent e config_pictureInPictureDefaultAspectRatio:a combinação de porcentagem da largura da tela e a proporção controla o tamanho do PIP. O tamanho padrão do PIP computado não pode ser menor que @dimen/default_minimal_size_pip_resizable_task, conforme definido pelo CTS e pelo CDD.
  • config_pictureInPictureSnapMode:o comportamento de ajuste conforme definido em PipSnapAlgorithm.

As implementações de dispositivos não podem mudar as proporções mínimas e máximas definidas no CDD e CTS.

Permissões

A "operação do aplicativo" por pacote (OP_PICTURE_IN_PICTURE) em AppOpsManager (main/core/java/android/app/AppOpsManager.java) permite que os usuários controlem o PIP em um nível por aplicativo nas configurações do sistema. As implementações de dispositivos precisam respeitar essa verificação quando uma atividade solicita a entrada no modo picture-in-picture.

Teste

Para testar implementações de PIP, execute todos os testes relacionados a picture-in-picture encontrados nos testes do CTS do host em /cts/hostsidetests/services/activitymanager, particularmente em ActivityManagerPinnedStackTests.java.