Apresentando a Desktop Windowing API para Flutter
Conheça o design por trás da nova Desktop Windowing API e escreva seu primeiro app Flutter com várias janelas.
O Flutter foi lançado originalmente em 2018 com suporte para as duas principais plataformas móveis: Android e iOS. Desde então, o Flutter expandiu seu alcance muito além do mobile, com suporte oficial para web, macOS, Linux e Windows, além de casos de uso personalizados, incluindo sistemas de infoentretenimento em carros, televisores inteligentes e sistemas embarcados. Dos seus começos humildes como um toolkit para apps mobile, o Flutter se tornou um toolkit de primeira linha para aplicações em um amplo espectro de dispositivos.
Mas ainda restam alguns resquícios do passado do Flutter como toolkit mobile. Uma peculiaridade do desenvolvimento mobile é que você não precisa desenhar em mais de uma janela: a janela simplesmente ocupa a tela inteira. Em vez de desenhar “janelas” especiais, como popups e tooltips, de forma independente, eles são renderizados como overlays sobre a janela principal. Para casos de uso mobile, essa é uma troca perfeitamente razoável. O formato é pequeno o suficiente para que ter várias janelas independentes traga pouco benefício ao desenvolvedor da aplicação em termos de usabilidade.
No entanto, essa premissa de janela única se tornou um problema assim que o Flutter foi lançado para desktop. Para que as aplicações se sintam em casa no desktop, elas precisam aproveitar o espaço de tela que um monitor grande oferece. Elas devem poder desenhar em quantas janelas quiserem e, ainda mais importante, desenhar além dos limites de uma única janela. Na época, o suporte a múltiplas janelas era a 6ª funcionalidade mais solicitada no Flutter, o que reforça a importância desse recurso.
Enquanto tudo isso acontecia, nós, da Canonical, estávamos ocupados integrando o Flutter em partes críticas da nossa stack, incluindo o Ubuntu Desktop Installer. Já tínhamos assumido a responsabilidade de principal mantenedor do Flutter Linux Embedder nessa época, e estávamos cada vez mais interessados em suporte nativo para uma API de windowing no Flutter. Então, em 2024, decidimos fazer parceria com o Google para tratar dessa nova API, com a Canonical liderando o design e a implementação, e o Google nos apoiando com revisões de design e de código.
Tipos de janela e hierarquia
Uma consideração de design importante para a API de windowing foi como torná-la multiplataforma. O Flutter está no seu melhor quando desenvolvedores conseguem "escrever uma vez, distribuir em qualquer lugar" com confiança, e queríamos desenhar uma API que tornasse isso o mais fácil possível. Foi assim que chegamos ao conceito de tipos de janela.
Nosso design gira em torno de cinco tipos de janela: regular, diálogo, tooltip, popup e satélite. Cada tipo de janela tem um comportamento e um propósito específicos e multiplataforma.
Janelas regulares são exatamente isso: uma janela comum em um desktop. Elas têm uma barra de ferramentas e podem ser redimensionadas, maximizadas, minimizadas e colocadas em tela cheia. Normalmente contêm o conteúdo principal de uma aplicação. Desenvolvedores de aplicações costumam ter pelo menos uma por aplicação, mas não é incomum ter mais de uma. Por exemplo, um navegador web pode abrir várias janelas regulares para que o usuário navegue de forma independente entre elas.

Janelas popup fornecem funcionalidades como menus suspensos e caixas de autocompletar de texto. Elas são janelas filhas de outras janelas e normalmente têm o tamanho do seu conteúdo. Importante: elas podem receber o foco de entrada (por exemplo, o usuário pode navegar em um menu suspenso com as setas do teclado). Nossa implementação também garante que janelas popup permaneçam visíveis na tela, transladando-as ou reduzindo-as, assegurando assim que informações importantes nunca se percam fora da tela.

Janelas tooltip são como janelas popup, exceto que não podem ter o foco de entrada. Elas normalmente são usadas para informações pequenas e passageiras. Por exemplo, formulários de entrada de dados de cartão de crédito costumam ter um campo de CVV com um pequeno ícone de “informação”. Quando o cursor passa por cima, esse ícone abre um tooltip explicando onde essa informação pode ser encontrada no seu cartão. Pequenas janelas informativas como essa funcionam melhor implementadas como tooltip.

Janelas de diálogo são janelas filhas que normalmente pedem ao usuário que execute uma ação. Os diálogos vêm em duas variantes: modal e não modal. Quando um diálogo é modal em relação a outra janela, essa janela não pode receber o foco até que o diálogo seja fechado. Um exemplo comum de janela de diálogo é um prompt modal pedindo ao usuário para confirmar ou cancelar a exclusão de um recurso da aplicação.

Janelas satélite são janelas auxiliares usadas para coisas como caixas de ferramentas e outros auxiliares. Elas são únicas porque mantêm sua posição em relação à janela pai conforme a janela pai se move e é redimensionada. Elas também podem ser filhas de várias janelas ao mesmo tempo, em vez de apenas uma, para que a barra de ferramentas possa ser compartilhada entre várias janelas principais. Satélites costumam ser encaixáveis também, o que significa que podem passar de uma janela satélite flutuante para ficar embutidas dentro do conteúdo principal da aplicação. Um exemplo de janela satélite é uma caixa de ferramentas com seleção de cor, seleção de ferramentas e outros recursos em softwares de edição de imagem, como o GIMP.

Esses tipos de janela existem em uma hierarquia de janelas. Por exemplo, uma aplicação pode ter uma janela regular principal na raiz, com popups e diálogos como filhos. Um diálogo pode então ter um tooltip aninhado dentro dele. A aplicação pode então abrir outra janela regular na raiz e aninhar outro popup dentro dessa janela. Dessa forma, uma hierarquia de janelas é construída. Na prática, essa hierarquia deve ser bem rasa, mas você não deve ter nenhum custo de performance por ter uma hierarquia profunda.
Esse design não foi escolhido arbitrariamente. A Canonical passou a maior parte das últimas duas décadas lançando um desktop que apresenta todo tipo de aplicações complexas. Por meio da nossa pesquisa, descobrimos que esses cinco tipos principais são fundamentais na maioria das aplicações, e por isso devem ter suporte de primeira classe nessa API. O melhor é que você, como desenvolvedor, pode ter confiança ao distribuir esses tipos de janela em todas as principais plataformas desktop, sabendo que o comportamento será sempre consistente.
No entanto, reconhecemos que surgem situações únicas. Por isso, sempre oferecemos uma "saída de emergência" pela qual você pode construir e modificar sua própria janela nativa para sua plataforma específica. Embora não seja a abordagem recomendada, isso pode ser uma ferramenta poderosa em circunstâncias que a exijam.
Explorando a API
A API de windowing está disponível atualmente no canal 'main' do Flutter. Note que as APIs estão escondidas atrás de uma feature flag experimental e, portanto, estão sujeitas a mudanças.
Para habilitar a API de windowing, execute o seguinte:
flutter channel main
flutter upgrade
flutter config --enable-windowing
Criando e modificando uma janela nativa
Para criar uma janela, começamos criando um WindowController. O controller interage com a plataforma subjacente para criar e atualizar a janela.
final controller = WindowController(
title: 'My Application',
size: const Size(800, 600),
);
O controller recebe a configuração inicial da janela, que inclui um tamanho e um título neste caso. Observe que esses argumentos podem não ser respeitados pela plataforma. Por exemplo, uma plataforma pode escolher um tamanho menor para a janela se a tela não for grande o suficiente para comportar o tamanho solicitado.
Cada tipo de janela tem seu próprio controller, que recebe argumentos diferentes. Por exemplo, para criar uma janela de diálogo em vez de uma janela regular, fica assim:
final dialogController = DialogWindowController(
title: 'My Dialog',
size: const Size(400, 300),
parent: parentController,
);
Diferente de uma janela regular, um DialogWindowController aceita um
controller de janela pai opcional em seu construtor.
Depois que um controller é criado, ele pode ser usado posteriormente para modificar a janela. Por exemplo, podemos modificar o título ou o tamanho da janela regular que criamos antes, ou até destruí-la:
controller.setTitle('Hello, world!');
controller.setSize(const Size.square(1000));
controller.destroy();
Renderizando em uma janela nativa
Agora que sabemos como criar e atualizar nossa janela nativa,
é hora de renderizar algo dentro dela. Para isso,
passamos nosso controller e o conteúdo a ser renderizado para um widget Window:
Widget build(BuildContext context) {
return Window(
controller: controller,
child: MyPage(),
);
}
Cada tipo de janela tem seu widget correspondente. Para uma janela regular,
usamos o widget Window, mas para uma janela de diálogo,
usaríamos o widget DialogWindow.
Vale notar que todas as janelas estão em uma única árvore de widgets. Isso significa que você pode compartilhar estado entre suas janelas sem nenhum trabalho adicional. Pacotes de gerenciamento de estado já existentes, como Riverpod ou Bloc, funcionam de imediato!
Escutando eventos em uma janela nativa
Agora que sabemos como criar nossa janela nativa e renderizar algo nela,
falta uma peça do quebra-cabeça: como recebemos notificações do sistema sobre nossa janela? Isso é feito de duas maneiras:
pelo delegate do controller de janela e pelo WindowScope.
O WindowControllerDelegate notifica sobre eventos importantes do ciclo de vida,
como a janela ser destruída ou o sistema pedir que destruamos
a janela. Implementamos um delegate sobrescrevendo o delegate do controller.
Por exemplo:
// Create the class first...
class MyWindowDelegate with WindowControllerDelegate {
@override
void onWindowDestroyed() {
super.onWindowDestroyed();
ServicesBinding.instance.exitApplication(AppExitType.required);
}
}
// and then pass it to the controller constructor.
final controller = WindowController(
title: 'My Application',
size: const Size(800, 600),
delegate: MyWindowDelegate(),
);
Esse delegate encerra a aplicação quando a janela é destruída, o que muitas vezes é a implementação apropriada para a janela principal de uma aplicação.
Podemos escutar informações menos críticas sobre uma janela com a ajuda do WindowScope, um
InheritedModel
criado por cada widget Window. Widgets aninhados em uma janela podem usar
WindowScope.of para acessar o escopo. Alternativamente,
eles podem usar um dos vários acessores específicos de campo no WindowScope
para escutar campos específicos da janela. Por exemplo,
se um widget tiver interesse no título da janela, ele pode fazer algo assim:
class MyWidget extends StatelessWidget {
@override
Widget build(BuildContext context) {
final title = WindowScope.titleOf(context);
// ... do something with the window title
}
}
Esse widget vai ser renderizado novamente sempre que o título da janela mudar.
Exemplo "Hello, Window"
Agora que entendemos a API e a justificativa por trás dela, o app de exemplo "Hello, Window" a seguir deve ser totalmente compreensível. Sinta-se à vontade para copiar e colar no seu projeto Flutter para testá-lo por conta própria:
// ignore_for_file: invalid_use_of_internal_member
// ignore_for_file: implementation_imports
import 'dart:ui';
import 'package:flutter/services.dart';
import 'package:flutter/src/widgets/_window.dart';
import 'package:flutter/widgets.dart';
/// Exits the application when the user closes the window.
class ExitOnCloseDelegate with WindowControllerDelegate {
@override
void onWindowCloseRequested(WindowController controller) {
ServicesBinding.instance.exitApplication(AppExitType.required);
}
}
void main() {
WidgetsFlutterBinding.ensureInitialized();
runWidget(const HelloWindow());
}
/// Displays a window and owns its [WindowController].
class HelloWindow extends StatefulWidget {
const HelloWindow({super.key});
@override
State<HelloWindow> createState() => _HelloWindowState();
}
class _HelloWindowState extends State<HelloWindow> {
final WindowController _controller = WindowController(
size: const Size(600, 400),
title: 'MyApp',
delegate: ExitOnCloseDelegate(),
);
@override
void dispose() {
_controller.dispose();
super.dispose();
}
@override
Widget build(BuildContext context) {
return Window(
controller: _controller,
child: const Directionality(
textDirection: TextDirection.ltr,
child: ColoredBox(
color: Color(0xFFFFFFFF),
child: Center(
child: Text(
'Hello, Window',
style: TextStyle(color: Color(0xFF000000), fontSize: 24),
),
),
),
),
);
}
}
O ótimo desse exemplo é que ele funciona imediatamente em todas as principais plataformas desktop, sem nenhum trabalho adicional da sua parte.
Um ponto importante a observar no exemplo acima é que não usamos mais a
runApp
função para renderizar nosso widget raiz, pois ela anexa o widget a uma view
criada implicitamente pela plataforma. Em vez disso, usamos
runWidget
e fornecemos a ela nossa própria view, que é a nossa Window.
Integração com design systems
Um ponto importante a notar é que, a longo prazo, a maioria dos usuários da API de windowing não vai interagir com ela explicitamente. Em vez disso, ela será integrada por baixo dos panos por um dos design systems existentes. Ao optar pelo design system, você simplesmente ganha todos os recursos de janela sem nenhuma configuração extra.
Especificamente, a equipe está trabalhando intensamente para integrar a nova API de windowing ao design system Material. Nossas integrações planejadas são com:
Esses métodos vão usar uma janela nativa verdadeira sempre que a plataforma fornecer uma. Quando a API de windowing não estiver disponível em uma plataforma (por exemplo, mobile), vamos recorrer à implementação existente. A API também oferecerá formas de desativar o windowing por completo nas circunstâncias em que isso for desejável.
Conclusão
A API de windowing foi um esforço de design e engenharia de vários anos entre a Canonical e o Google, e estamos muito animados para finalmente colocá-la em suas mãos. Se você tiver interesse em ver como é uma aplicação multi-janela mais complexa, confira https://flutter.dev/to/windowing-example.
Estamos ansiosos para ver o que vocês vão criar!