Extensões do WindowManager

A Jetpack WindowManager. permite que os desenvolvedores de aplicativos ofereçam suporte a novos formatos de dispositivos e ambientes de várias janelas.

As extensões do WindowManager (extensões) são um módulo opcional da plataforma Android que ativa vários recursos da Jetpack WindowManager. O módulo foi implementado no AOSP em frameworks/base/libs/WindowManager/Jetpack e enviados em dispositivos compatíveis com os recursos da WindowManager.

Distribuição do módulo de extensões

As extensões são compiladas em uma biblioteca .jar e colocadas no system_ext em um dispositivo se as extensões estiverem ativadas no makefile do dispositivo.

Para ativar extensões em um dispositivo, adicione o seguinte ao dispositivo do produto makefile:

$(call inherit-product, $(SRC_TARGET_DIR)/product/window_extensions.mk)

Isso ativa os recursos androidx.window.extensions e androidx.window.sidecar pacotes no dispositivo e define a propriedade persist.wm.extensions.enabled. Incluir esses pacotes no makefile também coloca declarações em etc/permissions/, disponibilizando-os para processos de aplicativos. Normalmente, o módulos são carregados e executados como parte do processo do aplicativo de execução quando usado pela biblioteca WindowManager do Jetpack, o que facilita semelhante ao código do framework do lado do cliente, conforme mostrado figura:

Figura 1. Extensões do WindowManager carregadas no aplicativo semelhante ao código da plataforma.

O módulo androidx.window.extensions é o módulo de extensões atual em o desenvolvimento ativo. O módulo androidx.window.sidecar é legado incluídos para compatibilidade com as versões mais antigas da Jetpack WindowManager, mas o arquivo secundário não recebe mais a manutenção ativamente.

A figura a seguir mostra a lógica para determinar o uso de androidx.window.extensions ou androidx.window.sidecar.

Figura 2. Árvore de decisão para acessar androidx.window.extensions ou androidx.window.sidecar.

Módulos de extensão

As extensões oferecem recursos de janelamento para dispositivos dobráveis de tela grande e dispositivos compatíveis com a gestão de janelas em telas externas. As áreas de recursos incluem:

• Incorporação de atividades
• Informações de layout de janela
• Área da janela

As implementações de extensões de OEM podem fornecer componentes ou componentes nulos com implementações padrão ou de stub dos métodos na WindowExtensions interface se o hardware do dispositivo não oferecer suporte aos recursos correspondentes, a menos que o recurso seja especificamente solicitado Documento de definição de compatibilidade (CDD) 7.1.1.1.

APIs de extensões e Jetpack

O módulo de extensões da WindowManager fornece uma superfície de API própria, além das as APIs da plataforma pública. O módulo "Extensões" é desenvolvido publicamente em um androidx.window.extensions não voltada para desenvolvedores Jetpack, para que a Jetpack WindowManager (androidx.window) que podem ser vinculadas a ele durante a compilação. A superfície da API Extensions normalmente oferece APIs de nível inferior.

As APIs que as extensões oferecem precisam ser usadas pelo Jetpack. Somente a biblioteca WindowManager. As APIs Extensions não foram feitas para ser chamadas aos desenvolvedores de aplicativos. A biblioteca Extensions não deve ser adicionada como um dependência de um aplicativo no arquivo de build do Gradle para garantir a funcionalidade de armazenamento. Evite pré-compilar a biblioteca Extensions em um aplicativo. diretamente em vez disso, conte com o carregamento do ambiente de execução para evitar o carregamento de classes de extensões pré-compiladas e fornecidas pelo ambiente de execução.

A Jetpack WindowManager (androidx.window) precisa ser adicionada como um aplicativo. e fornece as APIs públicas voltadas para o desenvolvedor, incluindo as para recursos de extensões da WindowManager. A biblioteca WindowManager carrega extensões no processo do aplicativo e une as extensões de nível inferior APIs de extensões em abstrações de nível superior e mais focadas do Google Cloud. As APIs Jetpack da WindowManager seguem os padrões dos padrões de desenvolvimento de aplicativos Android e têm como objetivo fornecer de interoperabilidade com uma boa integração com bases de código que usam outras bibliotecas.

Versões e atualizações de extensões

O módulo de extensões pode ser atualizado junto com a plataforma Android anualmente ou atualizações trimestrais. Com as atualizações trimestrais, o nível da API Extensions é aumentou entre as atualizações da API da plataforma Android, permitindo uma iteração mais rápida e fornecendo aos OEMs a oportunidade de adicionar o acesso oficial da API a novos recursos. perto dos lançamentos de hardware.

A tabela a seguir lista as versões da API androidx.window.extensions para várias versões do Android.

Versão da plataforma Android	Nível da API Extensions do WindowManager	Versão da API androidx.window.extensions
Android 15	6	1.5.0 (em breve)
QPR3 do Android 14	5	1.4.0 (em breve)
Android 14 QPR1	4	1.3.0
Android 14	3	1.2.0
QPR3 do Android 13	2	1.1.0
Android 13	1	1.0.0
Android 12L	1	1.0.0

O nível da API Extensions (coluna central) aumenta sempre que há uma adicionar à superfície estável da API existente (coluna da direita).

Observação:OEMs não precisam oferecer suporte a atualizações de QPR, mas precisam coordenar da plataforma e o nível da API Extensions da seguinte maneira:

• Qualquer versão de software de plataforma básica enviada pelos OEMs precisa ter pelo menos a mesma versão das extensões, conforme definido na tabela.
• Você pode fornecer uma versão mais antiga da plataforma com uma versão mais recente do extensões, mas geralmente a implementação também exige modificações no WindowManager Core para oferecer suporte à funcionalidade.
• Implementações que incluem uma versão mais antiga da plataforma e uma versão mais recente das extensões precisam passar no conjunto de teste de compatibilidade (CTS) correspondente para as extensões mais recentes. A implementação não recebe verificação automática com os testes CTS para os métodos mais antigos uma versão da plataforma.

Compatibilidade com versões anteriores e posteriores

A Jetpack WindowManager lida com a complexidade de lidar com níveis frequentes da API. atualizações rápidas, rápida evolução das APIs e compatibilidade com versões anteriores. Quando o código da biblioteca é executado no processo do aplicativo, a biblioteca verifica os arquivos Extensions e fornece acesso a recursos de acordo com o nível

Para proteger um aplicativo contra falhas no ambiente de execução, a WindowManager também executa uma verificação de reflexão Java do ambiente de execução das APIs de extensão disponíveis, de acordo com o nível declarado da API Extensions. Se houver uma incompatibilidade, a WindowManager desativar o uso de extensões (parcial ou completamente) e denunciar os eventos como não disponíveis para o aplicativo.

As extensões da WindowManager são implementadas como um módulo system_ext que usa APIs particulares da plataforma para chamar o núcleo da WindowManager, DeviceStateManager, e outros serviços do sistema na implementação dos recursos das extensões.

Não é possível manter a compatibilidade com as versões de pré-lançamento das extensões antes do lançamento trimestral ou anual correspondente da plataforma Android com quando as versões são finalizadas. O histórico completo das APIs de extensões pode ser encontrados na ramificação de lançamento Arquivos de texto da API window:extensions:extensions.

As versões mais recentes das extensões precisam continuar funcionando com as versões mais antigas do A WindowManager compilou nos aplicativos para manter a compatibilidade com versões futuras. Para garanta isso, todas as novas versões da API Extensions apenas adicionarão novas APIs e não remove os mais antigos. Como resultado, os aplicativos com WindowManager mais antigo versões podem continuar usando as APIs de extensões mais antigas que os aplicativos foram compilados contra.

A verificação do CTS garante que, para qualquer versão declarada das APIs de extensões no dispositivo, todas as APIs dessa versão e das anteriores vão estar presentes e funcionando.

Desempenho

Por padrão, o módulo de extensões é armazenado em cache em carregadores de classe do sistema que não são bootclasspath a partir do Android 14 (nível 34 da API). Portanto, não há impacto no desempenho devido ao carregamento do módulo na memória na inicialização do app. O uso de recursos de módulos individuais pode ter uma pequena influência sobre as características de desempenho dos aplicativos quando outras chamadas de IPC são realizadas entre o cliente e o servidor.

Módulos

Incorporação de atividades

Incorporação de atividades componente fornece um conjunto de recursos que permitem que os aplicativos organizem apresentação da janela de atividades dentro dos limites do aplicativo pai. Isso inclui mostrar duas atividades simultaneamente lado a lado em um layout de vários painéis, facilitando a otimização de telas grandes para as versões legadas. aplicativos conteinerizados.

O componente de incorporação de atividades precisa estar disponível em todos os dispositivos com um tela integrada de tamanho igual ou maior que sw600 dp. A incorporação de atividades também precisa ser ativada em dispositivos com suporte a telas externas conexões de rede, já que o aplicativo pode ser exibido em um tamanho maior quando são conectadas durante a execução.

Configuração do dispositivo

Nenhuma configuração específica do dispositivo é necessária além da ativação das extensões , conforme descrito em Distribuição do módulo de extensões nesta seção. Faz sentido ativar as extensões em todos os dispositivos com suporte o modo de várias janelas. É provável que versões futuras do Android criem extensões necessários em configurações comuns de dispositivos portáteis e de tela grande.

Informações de layout de janelas

O componente de informações de layout de janela identifica a posição e o estado da são articulados em um dispositivo dobrável quando ela atravessa uma janela de aplicativo. As informações de layout de janela permitem que os aplicativos respondam e mostrem de forma otimizada layouts no modo de mesa em dispositivos dobráveis. Consulte Fazer com que o app reconheça um dispositivo dobrável para conferir detalhes de uso.

Dispositivos Android dobráveis que incluem uma articulação que conecta ou as áreas do painel de exibição contínua precisam incluir as informações sobre a articulação disponíveis para aplicativos pelo WindowLayoutComponent.

A posição e os limites da articulação precisam ser informados em relação ao aplicativo. identificada por um Context transmitido à API. Se a janela do aplicativo os limites não cruzam com os limites da articulação, DisplayFeature não podem ser informadas. Também é aceitável não informar os recursos de exibição quando a posição deles puder não ser relatada de maneira confiável, como quando um aplicativo pode ser movida livremente pelo usuário no modo de várias janelas ou com efeito letterbox de compatibilidade.

Para recursos de dispositivos dobráveis, as atualizações de estado precisam ser informadas quando a posição da articulação muda entre as estados estáveis. Por padrão, em um estado de exibição simples, a API precisa informar FoldingFeature.State.FLAT Se o hardware do dispositivo puder ser deixado no modo meia dobrado em um estado estável, o A API precisa informar FoldingFeature.State.HALF_OPENED. Não há estado fechado na API, já que, nesse caso, a janela do aplicativo não seria visível ou não estaria ultrapassando os limites da articulação.

Configuração do dispositivo

Para oferecer suporte à implementação do recurso de dobra, os OEMs precisam fazer o seguinte:

• Configure os estados do dispositivo no device_state_configuration.xml que serão usados por DeviceStateManagerService. Consulte DeviceStateProviderImpl.java para referência.

  Se as implementações padrão de DeviceStateProvider ou DeviceStatePolicy não forem adequados para o dispositivo, uma implementação personalizada poderá ser usada.

• Ative o módulo Extensions conforme descrito no Seção Distribuição do módulo de extensões.

• Especifique o local dos recursos de exibição no com.android.internal.R.string.config_display_features recurso de string (geralmente em frameworks/base/core/res/res/values/config.xml na sobreposição do dispositivo).

  O formato esperado da string é:

  <type>-[<left>,<top>,<right>,<bottom>]

  O type pode ser fold ou hinge. Valores para left, top, right e bottom são coordenadas de pixel inteiro no espaço de coordenadas da tela a orientação natural da tela. A string de configuração pode conter várias recursos de exibição separados por ponto e vírgula.

  Exemplo:

  <!-- Jetpack WindowManager display features -->
  <string name="config_display_features" translatable="false">fold-[1000,0,1000,2000]</string>
  

• Definir o mapeamento entre os identificadores internos de estado do dispositivo usados em DeviceStateManager e as constantes de estado público enviadas aos desenvolvedores em com.android.internal.R.array.config_device_state_postures.

  O formato esperado para cada entrada é:

  <device_specific_state_identifier>:<Jetpack WindowManager state identifier>

  Os identificadores de estado compatíveis são:

  • COMMON_STATE_NO_FOLDING_FEATURES = 1: o estado não tem recursos de dobra para no relatório. Por exemplo, pode ser o estado fechado de uma típica tela com a tela principal na parte interna.
  • COMMON_STATE_HALF_OPENED = 2: o recurso dobrável está parcialmente aberto.
  • COMMON_STATE_FLAT = 3: o recurso de dobra é plano. Por exemplo, pode ser o estado aberto de um dispositivo dobrável típico com a tela principal no lado interno.
  • COMMON_STATE_USE_BASE_STATE = 1000: em O Android 14, um valor que pode ser usado para emulado em que o estado da articulação é derivado usando o estado base, conforme definido em CommonFoldingFeature.java

  Consulte DeviceStateManager.DeviceStateCallback#onBaseStateChanged(int) para mais informações.

  Exemplo:

  <!-- Map of System DeviceState supplied by DeviceStateManager to WindowManager posture.-->
  <string-array name="config_device_state_postures" translatable="false">
      <item>0:1</item>    <!-- CLOSED       : COMMON_STATE_NO_FOLDING_FEATURES -->
      <item>1:2</item>    <!-- HALF_OPENED  : COMMON_STATE_HALF_OPENED -->
      <item>2:3</item>    <!-- OPENED       : COMMON_STATE_FLAT -->
      <item>3:1</item>    <!-- REAR_DISPLAY : COMMON_STATE_NO_FOLDING_FEATURES -->
      <item>4:1000</item> <!-- CONCURRENT   : COMMON_STATE_USE_BASE_STATE -->
  </string-array>
  

Área da janela

O componente área de janela fornece um conjunto de recursos que dão aos aplicativos acesso a mais telas e áreas de exibição em alguns dispositivos dobráveis e dispositivos com várias telas.

O modo de tela traseira permite que um aplicativo mostre a interface de visualização da câmera no mostrar a tela de um dispositivo dobrável para permitir o uso da câmera principal do dispositivo para selfies e vídeos. Os dispositivos com suporte para Android (conforme definido pelo CDD do Android em termos de atributos como tamanho, densidade e recursos de navegação disponíveis) e a tela da capa alinhada com o dispositivo traseiro câmeras devem oferecer acesso ao modo de tela traseira.

No Android 14, o modo de tela dupla permite que os aplicativos executados na tela interna de um dispositivo dobrável mostrem mais conteúdo na tela da capa voltada para outros usuários. por exemplo, o visor da capa pode mostrar a visualização da câmera para a pessoa que está sendo fotografada ou gravada.

Configuração do dispositivo

Para oferecer suporte à implementação do recurso de dobra, os OEMs precisam fazer o seguinte:

• Configure os estados do dispositivo no device_state_configuration.xml que serão usados por DeviceStateManagerService. Consulte DeviceStateProviderImpl.java para mais informações.

  Se a implementação padrão DeviceStateProvider ou DeviceStatePolicy não for adequado para o dispositivo, uma implementação personalizada poderá ser usada.

• Para dispositivos dobráveis compatíveis com o modo aberto ou plano, especifique o identificadores de estado em com.android.internal.R.array.config_openDeviceStates.

• Para dispositivos dobráveis compatíveis com estados dobrados, liste o identificadores de estado em com.android.internal.R.array.config_foldedDeviceStates.

• Para dispositivos dobráveis dobráveis com suporte para o estado meio dobrado (a dobradiça está metade aberta) como um laptop), liste os estados correspondentes em com.android.internal.R.array.config_halfFoldedDeviceStates:

• Para dispositivos compatíveis com o modo de tela traseira:

  • Liste os estados correspondentes em com.android.internal.R.array.config_rearDisplayDeviceStates para DeviceStateManager.
  • Especifique o endereço de exibição física da tela traseira em com.android.internal.R.string.config_rearDisplayPhysicalAddress.
  • Especifique o identificador de estado em com.android.internal.R.integer.config_deviceStateRearDisplay para ser usado pelas extensões.
  • Adicione o identificador de estado em com.android.internal.R.array.config_deviceStatesAvailableForAppRequests para disponibilizá-lo aos aplicativos.

• No Android 14, para dispositivos com suporte ao modo de tela duplo (simultâneo):

  • Defina com.android.internal.R.bool.config_supportsConcurrentInternalDisplays como true.
  • Especifique o endereço de exibição física da tela traseira em com.android.internal.R.config_deviceStateConcurrentRearDisplay.
  • Especifique o identificador de estado em com.android.internal.R.integer.config_deviceStateConcurrentRearDisplay para ser usado pelas extensões se o identificador for disponibilizado para aplicativos.
  • Adicione o identificador de estado em com.android.internal.R.array.config_deviceStatesAvailableForAppRequests para disponibilizá-lo aos aplicativos.

Verificação

Os OEMs precisam verificar as implementações para garantir o comportamento esperado em comum diferentes. Os testes de CTS usando a Jetpack WindowManager estão disponíveis para OEMs para testar implementações.

Testes CTS

Para executar os testes de CTS, consulte Executar testes de CTS. O CTS Os testes relacionados à Jetpack WindowManager estão em cts/tests/framework/base/windowmanager/jetpack/. O nome do módulo de teste é CtsWindowManagerJetpackTestCases.

Testes da WindowManager

Para fazer o download dos testes da Jetpack WindowManager, siga as instruções abaixo. Instruções do Android Jetpack. Os testes estão localizados na biblioteca de janelas no módulo window:window: window/window/src/androidTest/.

Para executar os testes de dispositivo para o módulo window:window na linha de comando, faça o seguinte: o seguinte:

1. Conecte um dispositivo que tenha as opções do desenvolvedor e a depuração USB ativadas.
2. Permita que o computador depure o dispositivo.
3. Abra um shell no diretório raiz do repositório androidx.
4. Mude o diretório para framework/support.
5. Execute este comando: ./gradlew window:window:connectedAndroidTest.
6. analisar os resultados.

Para executar os testes no Android Studio, faça o seguinte:

1. Abra o Android Studio.
2. Conecte um dispositivo que tenha as opções do desenvolvedor e a depuração USB ativadas.
3. Permita que o computador depure o dispositivo.
4. Navegue até um teste na biblioteca de janelas do módulo de janela.
5. Abra uma classe de teste e execute usando as setas verdes do lado direito da editor.

Como alternativa, você pode criar uma configuração no Android Studio para executar um teste uma classe de teste ou todos os testes de um módulo.

Os resultados podem ser analisados manualmente observando a saída do shell. Algumas testes serão ignorados se o dispositivo não atender a certas suposições. Resultados são salva em um local padrão, e os analistas podem escrever um script para automatizar a análise dos resultados.