Flet: Pagelet

Layout

Controle Pagelet

O controle Pagelet permite a inserção de uma área no aplicativo usando o layout do Material Design. Com ele podemos criar uma barra de cabeçalho, uma área de conteúdo, uma barra inferior e um menu que surge quando requerido.

Um exemplo simples de uso mostra essas áreas e seus respectivos nomes.

import flet as ft

def main(page: ft.Page):
    page.bgcolor=ft.colors.LIGHT_BLUE_ACCENT_700

    titulo=ft.Text("Barra superior da Pagelet", color="BLACK")
    conteudo=ft.Text("Conteúdo do corpo da Pagelet", color="BLACK")
    icone_inferior=ft.IconButton(icon=ft.icons.SEARCH, icon_color=ft.colors.BLUE)
    txt_inferior=ft.Text("Texto na barra inferior da Pagelet", color="BLACK")
    barra_inferior=ft.Row([icone_inferior, txt_inferior])

    menu_direita=[
        ft.NavigationDrawerDestination(icon=ft.icons.HOME, label="Em casa"),
        ft.NavigationDrawerDestination(icon=ft.icons.HOME_WORK, label="No trabalho")
    ]

    pagelet = ft.Pagelet(
        appbar=ft.AppBar(title=titulo, bgcolor=ft.colors.DEEP_ORANGE_200),
        content=conteudo,
        bgcolor=ft.colors.AMBER_50,
        bottom_app_bar=ft.BottomAppBar(
            bgcolor=ft.colors.CYAN_ACCENT_700,
            content=barra_inferior,
        ),
        end_drawer=ft.NavigationDrawer(controls=menu_direita, bgcolor=ft.colors.BLUE_ACCENT),
        width=400,
        height=300
    )

    page.add(pagelet)

ft.app(target=main)

O resultado da execução do código está mostrado na figura 1.

Figura 1: componentes de um controle Pagelet.

Respectivamente as propriedades de Pagelet correspondem: appbar, a barra superior, cabeçalho do aplicativo;
content, o conteúdo central; bottom_app_bar, a barra inferior; end_drawer uma barra ocultável, normalmente usada para inserir um menu de opções.

Propriedades de Pagelet

Propriedade Descrição
appbar controle exibido na parte superior do aplicativo. Geralmente contém texto mas pode conter outros controles
bgcolor cor de fundo da Pagelet.
bottom_appbar controle BottomAppBar a ser exibido na parte inferior da Pagelet. Se as propriedades bottom_appbar e navigation_bar estão preenchidas uma barra de navegação NavigationBar também será exibida.
bottom_sheet uma folha de fundo persistente para exibir conteúdo adicional. Qualquer controle pode ser usado como bottom_sheet.
content o controle filho da Pagelet, para a exibição de conteúdo. Ele é posicionado em cima, à esquerda, no espaço disponível entre as barras superior e inferior da Pagelet.
drawer um controle NavigationDrawer a ser exibido como painel deslizante a partir da borda superior da Pagelet.
end_drawer um controle NavigationDrawer a ser exibido como painel deslizante a partir da borda lateral da Pagelet.
floating_action_button um controle FloatingActionButton a ser exibido em cima do conteudo da Pagelet.
floating_action_button_location define a posição do controle FloatingActionButton. O valor é um enum com os valores:

CENTER_DOCKED END_TOP MINI_END_TOP
CENTER_FLOAT MINI_CENTER_DOCKED MINI_START_DOCKED
CENTER_TOP MINI_CENTER_FLOAT MINI_START_FLOAT
END_CONTAINED MINI_CENTER_TOP MINI_START_TOP
END_DOCKED MINI_END_DOCKED START_DOCKED
END_FLOAT (default) MINI_END_FLOAT START_FLOAT
navigation_bar é um controle NavigationBar a ser exibido no fundo da página. Se as propriedades bottom_appbar e navigation_bar estão preenchidas uma barra de navegação NavigationBar também será exibida.

Métodos de Pagelet

close_drawer() fecha a gaveta ativa.
close_end_drawer() fecha a gaveta ativa na posição à direita.
show_drawer(drawer: NavigationDialog) exibe a gaveta
show_end_drawer(drawer: NavigationDialog) exibe a gaveta na posição à direita

† NotaTraduzi drawer por gaveta.

Uso de Pagelet

import flet as ft

def main(page: ft.Page):
    page.bgcolor=ft.colors.BLUE_50

    citacao=[(
        'Há três métodos para ganhar sabedoria: primeiro, por reflexão, '
        'que é o mais nobre; segundo, por imitação, que é o mais fácil; '
        'e terceiro, por experiência, que é o mais amargo. Confúcio'
    ),
    (
        'Todos os seres vivos temem a violência. Todos temem a morte,'
        'todos amam a vida. Projete você mesmo em todas as criaturas.'
        'Quem você poderia ferir? Que mal você poderia fazer? Buda'
    )]

    def clicou_algo(e):
        mensagem.content.value=e.control.tooltip
        page.update()

    def selecionar_sabedoria(e):
        conteudo.content.value=citacao[e.control.selected_index]
        pagelet.end_drawer.open = False
        page.update()

    def abrir_drawer(e):
        pagelet.end_drawer.open = True
        pagelet.end_drawer.update()

    def fecha_barra_direita(e):
        mensagem.content.value="Menu da direita fechado"
        page.update()

    class Botao(ft.IconButton):
        def __init__(self, icon, tip):
            super().__init__()
            self.icon=icon
            self.icon_color=ft.colors.WHITE
            self.tooltip=tip
            self.on_click=clicou_algo

    conteudo = ft.Container(
        content=ft.Text(citacao[0], size=19, color="BLACK"),
        padding=ft.padding.all(20),
        bgcolor=ft.colors.BLUE_300,
        border=ft.border.all(3, ft.colors.BLUE_400),
        border_radius=ft.border_radius.all(10),
        expand=True,
    )
    barra_inferior = ft.BottomAppBar(
        bgcolor=ft.colors.BLUE,
        shape=ft.NotchShape.CIRCULAR,
        content=ft.Row(
            controls=[
                Botao(ft.icons.SUNNY, "Escolha seu destino"),
                Botao(ft.icons.AIRPLANEMODE_ACTIVE, "Compre sua passagem"),
                ft.Container(expand=True),
                Botao(ft.icons.HOTEL, "Reserve o seu hotel"),
                Botao(ft.icons.ROCKET, "Viaje para mais longe"),
            ]
        )
    )
    barra_direita=ft.NavigationDrawer(
        controls=[
            ft.NavigationDrawerDestination(icon=ft.icons.SELECT_ALL, label="Confúcio"),
            ft.NavigationDrawerDestination(icon=ft.icons.ADD_COMMENT, label="Buda"),
        ],
        bgcolor=ft.colors.LIGHT_BLUE_ACCENT_700,
        on_change=selecionar_sabedoria,
        on_dismiss=fecha_barra_direita,
    )

    pagelet = ft.Pagelet(
        appbar=ft.AppBar(
            title=ft.Text("Clique no menu para selecionar", color=ft.colors.BROWN),
            bgcolor=ft.colors.LIGHT_BLUE_ACCENT_100,
            toolbar_height=60,
        ),
        content=conteudo,
        bottom_app_bar=barra_inferior,
        end_drawer=barra_direita,
        floating_action_button=ft.FloatingActionButton("Menu", on_click=abrir_drawer),
        floating_action_button_location=ft.FloatingActionButtonLocation.CENTER_DOCKED,
        bgcolor=ft.colors.BLUE_600,
        width=400,
        height=300,
    )
    mensagem=ft.Container(
        ft.Text("Eventos aparecem aqui...", size=17, color=ft.colors.BLACK),
        padding=ft.padding.all(20),
        bgcolor=ft.colors.BROWN_200,
        border=ft.border.all(3, ft.colors.BROWN_300),
        border_radius=ft.border_radius.all(10),
        width=400,
        height=70,
    )
    page.add(
        ft.Container(
            content=ft.Column([pagelet,mensagem]),
            padding=ft.padding.all(20),
            bgcolor=ft.colors.BLUE_300,
            border=ft.border.all(3, ft.colors.BLUE_400),
            border_radius=ft.border_radius.all(10),
        ),
    )

ft.app(target=main)
Figura 2: Aplicativo após um clique sobre o ícone de sol e após seleção do menu|Buda. Segunda imagem com o menu aberto.

O resultado da execução do código está mostrado na figura 2.

Nesse código alguns componentes da Pagelet foram definidos separadamente e inseridas depois no controle. Isso foi feito para tornar o código mais fácil de ser entendido. A definição da classe Botao tem apenas o objetivo de diminuir as repetições de código na montagem da barra_inferior.

Os cliques nos ícones na barra inferior transfere o conteúdo dos tooltips para o container inferior no aplicativo. Cliques no menu deslizante, nos itens Confúcio e Buda alteram o conteúdo de texto do controle central através da função selecionar_sabedoria. A mensagem é selecionada usando e.control.selected_index, que é o índice do controle NavigationDrawerDestination clicado.

Flet: CupertinoListTile

Layout

Controle CupertinoListTile

CupertinoListTile é um controle similar ao ListTile mas seguindo a estilização do iOS. O controle possui a propriedade notched que, se marcada como False (default) renderiza o controle no modo padrão do iOS, ou, se marcada como True gera o controle na aparência de “Inset Grouped”, o mesmo usado em iOS Notes ou Reminders.

Ele exibe uma linha de altura fixa com controles internos, geralmente imagens, ícones, textos e menus. Ele admite ícones à direita ou à esquerda do título, podendo seus objetos interiores responder a certos eventos.

Um exemplo mínimo de código aparece listado abaixo, com a ilustração de seu resultado ao ser executado.

import flet as ft

def main(page: ft.Page):
    page.bgcolor="#ABE6DB"

    cuperLT_1=ft.CupertinoListTile(
        title=ft.Text("Patches de recuperação do Windows 12", color="BLACK"),
        subtitle=ft.Text("Equipe Mostarda", color="#333355"),
        additional_info=ft.Text("Completar tarefa até 21:45H", color="#333355"),
        leading=ft.Icon(name=ft.cupertino_icons.CHAT_BUBBLE),
        trailing=ft.Icon(name=ft.cupertino_icons.BELL_CIRCLE_FILL),
        bgcolor="#BDAB8D"
    )

    cuperLT_2= ft.CupertinoListTile(
        title=ft.Text("Patches de recuperação do iOS 17", color="BLACK"),
        subtitle=ft.Text("Equipe Catchup", color="#333355"),
        additional_info=ft.Text("Completar tarefa até 09:15H", color="#333355"),
        leading=ft.Icon(name=ft.cupertino_icons.CHAT_BUBBLE_2),
        trailing=ft.Icon(name=ft.cupertino_icons.BELL_CIRCLE, color="RED"),
        bgcolor="#AD9B7D"
    )

    page.add(cuperLT_1, cuperLT_2)

ft.app(target=main)
Figura 1: renderização do código de exemplo de CupertinoListTile

Propriedades de CupertinoListTile

Propriedade Descrição
additional_info controle a ser exibido à direita do título mas antes do controle ao final da linha. Com frequência é usado um texto, seguido por um ícone, embora isso não seja obrigatório.
bgcolor_activated cor de fundo do controle após ter sido clicado ou tocado.
leading A Control para exibir antes do title.
leading_size restringe largura e altura do controle. Default é 28.0.
leading_to_title espaço horizontal entre leading e title. Default é 16.0.
notched booleano. Se notched=True o controle será criado com a forma de um “Inset Grouped”, usado em aplicativos do iOS como Notes ou Reminders. Default é False.
padding espaçamento interno no controle CupertinoListTile, descrevendo distância entre os controles internos: title, subtitle, additional_info e trailing.* Veja a propriedade Container.padding para mais informações e possíveis valores.
subtitle conteúdo adicional exibido abaixo do título. Em geral é usado um controle de texto.
title usado para exibir o conteúdo principal no controle CupertinoListTile. Em geral é usado um controle de texto.
toggle_inputs booleano. Se toggle_inputs=True um clique na lista de altera o estado dos controles internos Radio, Checkbox ou Switch. Default é False.
trailing controle a ser exibido após o título. Normalmente é usado um controle de ícone.
url URL usada para localizar um recurso quando a lista recebe um clique. Se o evento on_click estiver registrado (se houver uma função a ele associada), o evento é disparado.
url_target como abrir URL no modo web. Pode ser:

  • _blank: o recurso é aberto em nova aba ou janela (default).
  • _self: o recurso é aberto na aba ou janela atual.

Evento de CupertinoListTile

on_click dispara quando o usuário clica ou toca na lista.

Apesar de não encontrar documentação a respeito, na minha experiência os nomes dos ícones podem ser idênticos aos nomes do flutter, mas escritas em maiúsculas. Exemplos são:

  • ft.cupertino_icons.FOLDER,
  • ft.cupertino_icons.FUNCTION,
  • ft.cupertino_icons.HAMMER

Um aplicativo que busca ícones cupertino pode ser encontrada em Cupertino Icons.

Exemplo de uso de CupertinoListTile

import flet as ft

def main(page: ft.Page):
    page.bgcolor="#ABE6DB"

    def click(e):
        if e.control.notched:
            clt2.data +=1
            txt = f"Esse controle foi clicado {clt2.data} vez{'es' if clt2.data>1 else ''}."
            clt2.subtitle=ft.Text(txt, color="#333355")
        else:
            clt1.data +=1
            txt = f"Esse controle foi clicado {clt1.data} vez{'es' if clt1.data>1 else ''}."
            clt1.subtitle=ft.Text(txt, color="#333355")

        titulo.value =f"Os controles foram clicados {clt1.data+clt2.data} vezes."
        page.update()

    clt1=ft.CupertinoListTile(
        title=ft.Text("Patches de recuperação do Windows 12", color="BLACK"),
        subtitle=ft.Text(
            "Esse controle ainda não foi clicado.",
            color="#333355"
        ),
        additional_info=ft.Text("Completar tarefa até 21:45H", color="#333355"),
        leading=ft.Icon(name=ft.cupertino_icons.CAR_DETAILED, color="BLACK"),
        trailing=ft.Icon(name=ft.cupertino_icons.WRENCH, color="RED", size=30),
        padding=ft.padding.only(15, 20, 30, 40),
        bgcolor="#BDAB8D",
        bgcolor_activated=ft.colors.AMBER_600,
        data=0,
        on_click=click,
    )
    clt2=ft.CupertinoListTile(
        title=ft.Text("Patches de recuperação do iOS 17", color="BLACK"),
        subtitle=ft.Text(
            "Esse controle ainda não foi clicado.",
            color="#333355"
        ),
        additional_info=ft.Text("Completar tarefa até 09:15H", color="#333355"),
        leading=ft.Icon(
            name=ft.cupertino_icons.CAR_DETAILED,
            color="BLUE",
            size=30,
        ),
        trailing=ft.Icon(
            name=ft.cupertino_icons.GAUGE,
            color="RED",
            size=30,
        ),
        padding=20,
        bgcolor="#CDBB9D",
        bgcolor_activated=ft.colors.AMBER_100,
        notched=True,
        data=0,
        on_click=click,
    )
    titulo=ft.Text(
        "Nenhum controle foi clicado até agora",
        color="#0b4b8f",
        size=30,
        weight=ft.FontWeight.BOLD,
    )
    ct=ft.Container(
        content=titulo,
        margin=5,
        padding=5,
        alignment=ft.alignment.center,
        bgcolor="#95d3c8",
        width=850,
        height=50,
        border_radius=10,
    )
    page.add(ct, clt1, clt2)

ft.app(target=main)
Figura 2: renderização do código de exemplo de CupertinoListTile depois de 2 cliques em cada tile. O primeiro controle está sob efeito do clique, exibindo a cor bgcolor_activated (amber).

Valem as observações: um container é inserido na cabeçalho, contendo um título que usa titulo=ft.Text(...). A variável titulo foi definida separadamente para estar disponível para alterações na função click().

As duas tiles foram definidas com a propriedade data em clt=ft.CupertinoListTile(..., data=0), usada para contar quantos cliques foram aplicados sobre o controle. Essa mesma propriedade é usada para construir a propriedade clt.subtitle, também atualizada a cada clique.

A função click() distingue entre os dois controles através da propriedade e.control.notched, que só é verdadeira no segundo controle. Desta forma não é necessário criar uma função para cada controle.

Flet: DataTable

Outro controle de Layout

Controle DataTable

DataTable é um controle usado para dispor dados em forma tabular. Ele é composto de um cabeçalho definido na propriedade columns que recebe uma lista de flet.DataColumn(), em geral contendo um controle de texto. Ele também pode conter ícones ou uma linha (Row) com ícones e texto. As colunas podem ser definidas como texto ou numéricas e exibir botão de seleção e ordenamento. As linhas de dados são constituídas de flet.DataRow(), por sua vez preenchidas com flet.DataCell()

Um exemplo curto de DataTable é mostrado abaixo.

import flet as ft

def main(page: ft.Page):

    def tit(texto):
        return ft.DataColumn(ft.Text(texto))

    def cel(texto):
        return ft.DataCell(ft.Text(texto))

    cabecalho=[tit("Título 1"), tit("Título 2"), tit("Título 3")]

    linha1=ft.DataRow(cells=[cel("A-1,1"),  cel("A-1,2"), cel("A-1,3")])
    linha2=ft.DataRow(cells=[cel("A-2,1"),  cel("A-2,2"), cel("A-2,3")])
    linha3=ft.DataRow(cells=[cel("A-3,1"),  cel("A-3,2"), cel("A-3,3")])

    linhas = [linha1, linha2, linha3]
    tabela=ft.DataTable(columns=cabecalho, rows=linhas)
    page.add(tabela)

ft.app(target=main)
Figura 1: Representação do código de DataTable e com seus controles internos.

Propriedades de DataTable

Algumas das propriedades e eventos listados aqui são mais associados a ações provocadas por toques em telas sensíveis ao toque (touch screen), embora muitas vezes possam ser executadas também com cliques de mouse. Exemplos são os eventos:

  • on_tap: recebimento de um toque,
  • on_long_press: recebimento de um toque longo,
  • on_tap_cancel: cancelamento do evento de toque, e
  • on_tap_down: arrastamento para baixo.
Propriedade Descrição
bgcolor cor de fundo da tabela
border definição da borda da tabela. O valor deve ser uma instância da classe flet.Border.
Veja a propriedade Container.border para mais informações.
border_radius raio dos cantos da borda.

Veja a propriedade Container.border para mais informações.

checkbox_horizontal_margin margin horizontal em torno das caixas de checagem (checkbox) se exibidas.
column_spacing margin horizontal entre o conteúdo de cada coluna.
columns lista de controle DataColumn descrevendo as colunas da tabela.
data_row_color cor de fundo das linhas de dados.

A cor de fundo pode ser ajustada para depender do estado do MaterialState, ou seja, com o estado da linha de selecionada, pressionada, percorrida pelo cursor, em foco, desabilitada ou não. [selected, pressed, hovered, focused, disabled or enabled].

A cor é renderizada como uma sobreposição à linha. Para garantir boa visibilidade é recomendado usar uma cor de fundo transparente.

Veja a propriedade Checkbox.fill_color para mais informações.

data_row_min_height altura mínima de cada linha (exceto a linha com o cabeçalho).
data_row_max_height altura máxima de cada linha (exceto a linha com o cabeçalho).
data_text_style estilo de texto para as linhas de dados. O valor deve ser uma instância da classe flet.TextStyle.
divider_thickness espessura do divisor (divider) entre as linhas da tabela. Esse valor deve ser ≥ 0, sendo o default 1.0
.
gradient gradiente de cor aplicado ao fundo da tabela.
Veja a propriedade Container.gradient para mais informações.
heading_row_color cor de fundo para a linha de cabeçalho.

A cor de fundo pode ser ajustada para depender do estado do MaterialState, ou seja, com o estado da linha de selecionada, pressionada, percorrida pelo cursor, em foco, desabilitada ou não. [selected, pressed, hovered, focused, disabled or enabled].

A cor é renderizada como uma sobreposição à linha. Para garantir boa visibilidade é recomendado usar uma cor de fundo transparente.

Veja a propriedade Checkbox.fill_color para mais informações.

heading_row_height altura da linha de cabeçalho.
heading_text_style estilo de texto para a linha de cabeçalho. O valor deve ser uma instância da classe flet.TextStyle.
horizontal_lines ajusta cor e largura das linhas horizontais separando as linhas de dados. O valor deve ser uma instância da classe flet.BorderSide.
horizontal_margin margem horizontal entre as bordas da tabela e o conteúdo da primeira e última célula de cada linha. Também é a margem entre
uma caixa de checagem (checkbox) (quando exibida) e o conteúdo da primeira coluna de dados.
rows uma lista de controles DataRow que definem as linhas da tabela.
show_bottom_border booleano, se a borda de fundo da tabela é exibida. Por default essa borda não é visível para que se aplique uma decoração sobre a borda geral da tabela.
show_checkbox_column booleano, se o controle deve conter caixas checkboxes para linhas selecionáveis.

Quando False nenhuma checkbox será apresentada. Quando True uma checkbox será apresentada no início de cada linha selecionável. Caso nenhuma linha seja marcada com DataRow.on_select_changed nenhuma checkbox será visível.

sort_ascending booleano, se a coluna indicada em sort_column_index (caso exista) será ordenada em ordem crescente. Caso contrário, se sort_ascending=False a ordem será descendente.
sort_column_index indica a chave primária de ordenação das linhas. Se especificada a colunas marcada será usada para a ordenação. O número deve indicar a coluna, em numeração iniciando em 0. Quando especificada a coluna mostrará um indicador de que o ordenamento é possível. Quando sort_column_index=None nenhum ordenamento será realizado.
vertical_lines cor e largura das linhas verticais entre colunas. O valor deve ser uma instância de classe flet.BorderSide.

Evento de DataTable

on_select_all dispara quando o usuário seleciona (ou desseleciona) todas as linhas usando o checkbox no cabeçalho.

Se on_select_all=None o evento de linhas DataRow.on_select_changed é disparado quando cada linha é selecionada. Para selecionar se uma linha é selecionável ou não use DataRow.on_select_changed. Esse evento só é relevante de existe alguma linha selecionável.

DataColumn

Objeto de configuração das colunas de uma DataTable. Todas as colunas a serem exibidas na tabela devem ter uma coluna de configuração.

Propriedades de DataColumn

label Conteúdo apresentado no cabeçalho. Em geral um controle de texto mas pode ser um ícone (tipicamente com size=18), ou uma coluna com ícone e texto.
numeric booleano, se essa coluna exibe valores numéricos. Colunas com valores numéricos são alinhadas à direita.
tooltip uma dica (tooltip) para a coluna. Pode conter uma descrição maior que o título ou mesmo título completo quando esse for abreviado na redução da largura da janela.

Evento de DataColumn

on_sort disparado quando o usuário requisita o ordenamento da tabela usando essa coluna. Se não for especificada uma função para esse evento a coluna será considerada não ordenável.

DataRow

Objeto de configuração das linhas e células de uma DataTable. Deve exitir uma linha de confighuração para cada linha da tabela. Os dados contidos na linhas são inseridos por meio de objetos flet.DataCells, reunidos em listas atribuidas à propriedade flet.DataRow(cells).

Propriedades de DataRow

cells recebe os dados a serem exibidos por meio de uma lista de controles DataCell. Devem existir células para todas as colunas (o número de células e colunas devem serem iguais).
color a cor da linha. Por default essa cor é transparente quando a linha não está selecionada, e recebem uma coloração acinzentada transparente quando selecioandas.

O cor exibida como resultado final depende do estado do MaterialState se a linha está selecionada, pressionada, percorrida pelo cursor, em foco, desabilitada ou não. [selected, pressed, hovered, focused, disabled or enabled].

A cor é renderizada como uma sobreposição à linha. Para garantir boa visibilidade é recomendado usar uma cor de fundo transparente.

Veja a propriedade Checkbox.fill_color para mais informações.

selected booleano, define se a linha está selecionda.

Se on_select_changed é não nula para alguma linha da tabela uma caixa checkbox é exibida no início de cada linha. Caso selected=True em uma linha sua checkbox aparecerá ticada e a linha destacada. Caso contrário a checkbox (se estiver presente) não será marcada.

Eventos de DataRow

on_long_press disparado quando a linha recebe um clique ou pressionamento longo.

Se uma célula DataCell na linha contém a definição de ação para os eventosDataCell.on_tap, DataCell.on_double_tap, DataCell.on_long_press, DataCell.on_tap_cancel ou DataCell.on_tap_down então essa definição sobrescreverá (terá prioridade sobre) o evento da linha se a ação for feita sobre a célula.

on_select_changed disparado quando o usuário seleciona ou desseleciona uma linha selecionável.

A linha é selecionável se essa propriedade não for nula. O estado da linha atual fica marcado na propriedade selected.

Se qualquer uma das linhas é selecionável o cabeçalho apresentará um checkbox que pode ser marcado para selecionar todas as linhas selecionáveis. Esse checkbox aparece marcado se todas as linhas estiverem selecionadas. Linhas subsequentes recebem um checkbox para sua seleção individual.

Se uma linha tem o evento on_select_changed=Null ela terá um checkbox desabilitado e será ignorada na determinação do estado de “todos os checkbox marcados”.

Se uma das células DataCell da linha tem o evento DataCell.on_tap definido, então essa definição sobrescreverá, naquela célula, os eventos definidos para a linha em geral.

DataCell

O objeto DataCell contém os dados para cada entrada em uma tabela DataTable. Uma lista de objetos
DataCell deve ser fornecida para cada linha, contendo o exato número de células que o de colunas.

Propriedades de DataCell

content o conteúdo com dados a serem apresentados em cada célula. Em geral contém um controle de texto um Dropdown.

Se não existem dados nessa propriedade o controle de texto será preenchido com um texto substituto (placeholder) e deve ser marcada a propriedade placeholder=True.

Esse controle só admite um filho. Para incluir layouts mais complexos é necessário inserir um widget tal como Row, Column ou Stack, que têm a propriedade controls que podem abrigar múltiplos filhos.

placeholder booleano, se o conteúdo é um texto substituto (placeholder).

Se placeholder=True o estilo default de texto para a célula é alterado para o estilo ajustado para placeholders.

show_edit_icon booleano, se o ícone de edição deve ser mostrado no final da célula. Essa propriedade não torna a célula editável. Esse comportamento deve ser definido no evento DataCell.on_tap.

Eventos de DataCell

on_double_tap disparado no duplo toque da célula.
on_long_press disparado no toque prolongado da célula.
on_tap disparado no toque da célula.
on_tap_cancel disparado se o usuário cancela um toque.
on_tap_down disparado se a célula é puxada para baixo.
Nota † válido para todos os eventos de DataCell Se não-nulo, o duplo toque da célula dispara esse evento. Se nulo o toque apenas seleciona a linha. Esse comportamento se extende a on_tap, on_long_press, on_tap_cancel e on_tap_down, caso DataRow.on_select_changed tenha sido definido.

Exemplo de uso de DataTable, DataRow e DataCell

Um exemplo um pouco mais elaborado de DataTable aparece no código abaixo.

import flet as ft

def main(page: ft.Page):
    page.bgcolor="#BAD1EA"

    def formatar_tabela(t):
        t.bgcolor="#0E64C5"
        t.border=ft.border.all(3, "#304864")
        t.border_radius=5
        t.data_row_color="#6697CE"
        t.show_checkbox_column=True
        t.divider_thickness=2
        t.column_spacing=100
        t.sort_column_index=2
        t.sort_ascending=True
        t.heading_row_color="#1565C2"
        t.heading_row_height=60
        t.show_checkbox_column=True
        t.show_bottom_border=True

    def montar_tabela(matriz):
        cor=["#759DCB", "#DABD90"]
        colunas=[]
        for col in matriz[0]:
            colunas.append(ft.DataColumn(ft.Text(col)))

        linhas=[]
        i=0
        for linha in matriz[1:]:
            i+=1
            celulas=[]
            for celula in linha:
                celulas.append(
                    ft.DataCell(
                        ft.Text(celula, color="#000000"),
                        show_edit_icon=(i%2==0)
                    )
                )
            linhas.append(ft.DataRow(cells=celulas, color=cor[i%2]))
            tabela=ft.DataTable(columns=colunas, rows=linhas)
            formatar_tabela(tabela)
        return tabela

    matriz = [
        ["Nome",      "Sobrenome",  "Idade", "Profissão", "Nacionalidade"],
        ["Cristovão", "Colombo",    "43",    "Navegador", "Itália"],
        ["Joaquim",   "José",       "31",    "Militar",   "Brasil"],
        ["Maria",     "Joaquina",   "23",    "Realeza",   "Portugal"],
        ["Albert",    "Einstein",   "57",    "Físico",    "Alemanha"],
        ["Charles",   "Chaplin",    "73",    "Ator",      "França"]
    ]

    tabela = montar_tabela(matriz)

    page.add(ft.Text("Famosos na História", size=20,color="BLACK"), tabela)

ft.app(target=main)

O código mostra um exemplo de transformação de formato de dados obtidos inicialmente como uma matriz formada por uma lista de listas. A primeira linha é usada para capturar os títulos de cada coluna, as demais são os dados exibidos no corpo da tabela. A vantagem desse método está em que a tabela pode ter um número arbitrário de colunas e de linhas.

Figura 2: Representação do código executado do exemplo de DataTable.
† Nota: A transformação de dados entre formatos diferentes de exposição é uma das funções básicas em TI atualmente. Exemplos são dados obtidos em paginas da WEB (em formato HTML), em textos PDF, em planilhas, em arquivos csv, que devem ser separados e usados em código, geralmente expostos em formato diferente daquele original.

A função montar_tabela(matriz) (que recebe matriz, uma lista de listas) percorre as linhas e colunas montando o objeto DataTable. Antes de retornar o objeto tabela montado ele a submete à formatar_tabela(t). Lembramos que objetos são passados por referência no Python, por default. Isso significa que a variável t recebida como parâmetro da função é apenas apenas uma referência para o mesmo objeto indicado pela variável tabela e as transformações feitas nas propriedades dentro da função são efetivas no objeto retornado por montar_tabela(matriz).

Flet: GridView e ResponsiveRow

Outros controles de Layout: GridView e ResponsiveRow

Controle GridView

GridView, assim como ListView, é um controle apropriado para apresentar listas longas (milhares de ítens). Esses controles devem ser escolhidos ao invés de Column ou Row para se obter um rolamento suave de conteúdo. O Navegador de Ícones (Icons Brower) do Flet é construído com um GridView.

Um exemplo curto do uso do controle é mostrado abaixo. Nesse código um array (uma lista) de 8 containeres com cores de fundo escolhidas entre os valores da lista, cores. Essa lista é passada em flet.GridView.controls = array.

import flet as ft

cores = {0:"black",  1:"#1D74FF", 2:"#C51709", 3:"#FFE000",
         4:"#00CB4F",5:"#A866DC", 6:"#FF6600", 7:"#145375"}

def main(page: ft.Page):
    array = []
    for i in range(0, 8):
        array.append(
            ft.Container(
                bgcolor=cores[i],
                border=ft.border.all(1, "BLACK"),
                border_radius=ft.border_radius.all(15),
            )
        )

    grid_imagens = ft.GridView(
        controls = array,
        expand=1,
        runs_count=15,
        max_extent=100,
        child_aspect_ratio=1.0,
        spacing=2,
        run_spacing=2,
    )
    page.add(grid_imagens)

ft.app(target=main)

A execução desse código resulta na tela mostrada na figura 1.

Figura 1: oito containeres de cores diferentes adicionados a um GridView

Propriedades de GridView

Propriedade Descrição
auto_scroll booleano, auto_scroll=True se a barra de rolamento se move automaticamente para a posição onde o último filho foi inserido. Essa propriedade deve ser False para que o método scroll_to() funcione.
child_aspect_ratio proporção entre dimensões vertical e horizontal (cross-axis e main-axis) de cada filho.
controls lista de controles a serem renderizados dentro do GridView.
horizontal booleano, horizontal=True para que a grade empilhe itens horizontalmente.
max_extent largura ou altura máxima de cada ítem na grade.
on_scroll_interval intervalo em milisegundos para o disparo do evento on_scroll. Default é 10.
padding espaço interno de separação entre os filhos e a grade.

Veja a propriedade Container.padding para maiores informações.

reverse booleano, reverse=True faz com que o rolamento se dê invertido, de baixo para cima. Default é False.
run_spacing espaçamento entre cada filho em pixeis, ao longo do eixo vertical.
runs_count o número de controles filhos a serem apresentados na vertical.
spacing espaçamento entre cada filho em pixeis, ao longo do eixo horizontal.

Método de GridView

scroll_to(offset, delta, key, duration, curve) move a barra de rolamento para a posição definida, em termos absoluto, relativo ou salto para uma chave especificada.

Veja o método Column.scroll_to() para maiores informações.

Evento de GridView

on_scroll Dispara quando a posição de rolamento é alterada pelo usuário.Veja o evento Column.on_scroll para maiores informações.

Exemplo de uso de GridView

No exemplo abaixo usamos o controle flet.Image(src, fit, repeat, border_radius) que ainda não descrevemos nessas notas. Seu objetivo é o de inserir imagens, no caso atual lidas no repositório Image Gallery localizada em picsum.photos.

import flet as ft

def main(page: ft.Page):
    page.title = "GridView Example"
    page.theme_mode = ft.ThemeMode.DARK
    page.padding = 10
    
    txt = ft.Text("Controle GridView com Imagens", size = 28)
    titulo=ft.Container(txt, data=0)
    
    def incrementa(e):
        titulo.data+=12
        carregar_imagens()

    bt_mais=ft.ElevatedButton(
        "Carregar mais imagens",
        icon=ft.icons.BEACH_ACCESS,
        color="WHITE",
        bgcolor="#6E432B", width=300, height=40,
        on_click=incrementa
    )

    grid_imagens = ft.GridView(
        expand=1,
        runs_count=15,
        max_extent=150,
        child_aspect_ratio=1.0,
        spacing=5,
        run_spacing=5,
    )

    def carregar_imagens():
        grid_imagens.controls=[]
        for i in range(titulo.data, titulo.data+12):
            grid_imagens.controls.append(
                ft.Image(
                    src=f"https://picsum.photos/150/150?{i}",
                    fit=ft.ImageFit.NONE,
                    repeat=ft.ImageRepeat.NO_REPEAT,
                    border_radius=ft.border_radius.all(10),
                )
            )
        page.update()

    carregar_imagens()
    page.add(ft.Column([ft.Row([titulo,  bt_mais]), grid_imagens]))

ft.app(target=main)
Figura 2: Execução do código de exemplo de GridView

Nesse código o controle flet.GridView é criado com o array de controles vazio e depois populado pela função carregar_imagens() que insere 12 imagens na propriedade GridView.controls. A propriedade titulo.data armazena a posição das imagens baixadas e é incrementada de 12 a cada disparo do botão bt_mais.

Controle ResponsiveRow

ResponsiveRow traz para o Flet o mesmo conceito de layout de grade usado no framework Bootstrap. Com ele se pode alinhar os controles filhos em colunas virtuais que podem ser redimensionadas. Por padrão uma grade possui 12 colunas, número que pode ser modificado na propriedade ResponsiveRow.columns.

Cada coluna inserida em um ResponsiveRow possui a propriedade col especificando quantas colunas cada controle deve preencher, de modo análogo ao uso da propriedade expand. Por exemplo, para criar um layout que contém duas colunas abrangendo 6 colunas virtuais cada usamos:

import flet as ft

ft.ResponsiveRow([
    ft.Column(col=6, controls=[ft.Text("Coluna 1")]),
    ft.Column(col=6, controls=[ft.Text("Coluna 2")])
])

O controle é dito “responsivo” porque pode ajustar o tamanho de seus filhos à geometrias variáveis de telas, que pode ser a página, a janela, etc. No exemplo acima a propriedade col é um número constante, significando que o filho ocupará 6 colunas para qualquer tamanho de tela. Se a propriedade col de um filho não for especificada ele terá o número máximo de colunas.

A propriedade col pode ser configurada para ter um valor diferente para “pontos de interrupção” (breakpoints) específicos, de acordo com o tamanho da tela. Os pontos de interrupção, como intervalos de dimensão, recebem nomes:

Por exemplo, no código abaixo o conteúdo é colapsado em apenas uma coluna em uma tela pequena (como a de um telefone celular) e assume 2 colunas em telas grandes:

import flet as ft
ft.ResponsiveRow([
    ft.Column(col={"sm": 6}, controls=[ft.Text("Column 1")]),
    ft.Column(col={"sm": 6}, controls=[ft.Text("Column 2")])
])

Propriedades de ResponsiveRow

Propriedade Descrição
alignment alinhamento horizontal dos controles filhos. Por exemplo, MainAxisAlignment.START (que é o default) posiciona os filhos à esquerda da linha.

Os valores possíveis da propriedade estão no enum MainAxisAlignment com os valores:

  • START (default)
  • END
  • CENTER
  • SPACE_BETWEEN
  • SPACE_AROUND
  • SPACE_EVENLY
columns o número de colunas virtuais a usar no layout dos filhos. Default é columns=12.
controls uma lista de controles a serem exibidos dentro do ResponsiveRow.
run_spacing espaçamento entre as linhas quando o conteúdo está quebrado em múltiplas linhas. Default run_spacing=10.
spacing espaçamento entre os controles em uma linha. Default é spacing=10 (pixeis virtuais). Esse espaçamento só é aplicado quando o alinhamento (alignment) é start, end ou center.
vertical_alignment como os controles filhos são posicionados verticalmente.

Os valores possíveis da propriedade estão no enum CrossAxisAlignment com os valores:

  • START (default)
  • CENTER
  • END
  • STRETCH
  • BASELINE

Exemplo de uso de ResponsiveRow

No exemplo abaixo tanto as funções coluna() como linha() retornam containeres com um texto. Esses controles preenchem as posições de coluna do ResponsiveRow, a primeira delas especificando os pontos de quebra em
col={"sm": 6, "md": 4, "xl": 2}, a segunda em col={"md": 4}. Observe que Container não tem a propriedade col, exceto quando dentro de uma “linha responsiva”.

import flet as ft

def main(page: ft.Page):

    def coluna(texto, cor):
        # retorna um Container com um texto
        return ft.Container(
            ft.Text(texto),
            padding=15,
            bgcolor=cor,
            col={"sm": 6, "md": 4, "xl": 2}
        )

    def linha(texto, cor):
        # retorna um Container com um texto
        return ft.Container(
            ft.Text(texto, size=18),
            width=200, height=60, padding=15,
            border_radius=10,
            bgcolor=cor,
            col={"md": 4}
        )

    def page_resize(e):
        info.value = f"{page.width} px"
        info.update()

    page.on_resize = page_resize
    info = ft.Text(size=28)

    page.overlay.append(
        ft.Container(
            info,
            width=200, height=70, padding=10, border_radius=15,
            bottom=50, right=50, bgcolor="#acdeff",
        )
    )

    page.add(
        ft.ResponsiveRow(
            [
                coluna("Coluna 1", ft.colors.YELLOW),
                coluna("Coluna 2", ft.colors.GREEN),
                coluna("Coluna 3", ft.colors.BLUE),
                coluna("Coluna 4", ft.colors.RED),
            ],
        ),
        ft.ResponsiveRow(
            [
                linha("texto 1", ft.colors.BLUE_50),
                linha("texto 2", ft.colors.RED_50),
                linha("texto 3", ft.colors.GREEN_50),
            ],
            run_spacing={"xs": 10},
        ),
    )
    page_resize(None)

ft.app(target=main)

A propriedade de largura da página page.width é exibida dentro de um Container inserido na camada page.overlay para flutuar em cima dos controles da página. Esse controle está definido em espaçamento fixo bottom=50 e right=50, podendo se sobrepor aos controles da camada abaixo. A atualização é disparada no evento page.on_resize.

Observe que a atualização realizada no redimensionamento altera info.value e a renderização é exposta na página com info.update(). O mesmo efeito seria obtido com page.update() pois esse método cuida de atualizar apenas as partes modificadas da página.

O resultado da execução do código aparece nas figuras 3 e 4.

Figura 3: estado inicial do aplicativo com tela de largura superior a 1200 px.
Figura 4: estado do aplicativo com tela redimensionada para 567 px, depois 288px.

Flet: ListTile e ListView

Outros controles de Layout: ListTile e ListView

Controle ListTile

ListTile é um controle que exibe uma linha de altura fixa que pode conter outros controles, geralmente imagens, ícones, textos, botões e menus popups. Ele admite ícones à direita ou à esquerda do título, podendo seus objetos interiores responder a certos eventos.

Um exemplo mínimo de código aparece listado abaixo, com a ilustração de seu resultado ao ser executado. Um menu popup foi incluído porque esses controles são usados frequentemente juntos com ListTile.

import flet as ft

def main(page):

    lTile1=ft.ListTile(title=ft.Text("Você gosta de animais?", size=18))

    pop_menu=ft.PopupMenuButton(
        icon=ft.icons.MORE_VERT,
        items=[ft.PopupMenuItem(text="Jacaré"), ft.PopupMenuItem(text="Leão")]
    )
    lTile2=ft.ListTile(
        title=ft.Text("Qual é o seu animal favorito?"),
        subtitle=ft.Text("Selecione no menu popup"),
        trailing=pop_menu
    )
    page.add(ft.Card(ft.Column([lTile1, lTile2]), width=300))

ft.app(target=main)

A figura 1 mostra o resultado desse código, renderizado no desktop.

Figura 1:  (a) estado inicial do aplicativo; (b) estado após um clique no controle PopupMenuItem

Propriedades de ListTile

Propriedade Descrição
autofocus booleano, autofocus=True se o controle receberá o foco inicial (o cursor está sobre o controle). Se mais de um controle tiver esse ajuste o primeiro deles (na ordem da página) receberá o foco.
content_padding Espaçamento interno (padding) do controle. Separação entre os controles internos: leading, title, subtitle, e trailing. O default é padding.symmetric(horizontal=16). Veja Container.padding para maiores informações.
dense define se o controle tem exibição densa, com menor altura e caracteres compactos.
is_three_line booleano, se is_three_line=True o controle ListTile deve exibir 3 linhas de texto, e o subtitulo nao pode ser Null, uma vez que ele devera conter as linhas 2 e 3 de texto.Se is_three_line=False o ListTile deve conter uma linhas se subtitle=Null e duas linhas caso contrário.

Se um controle flet.Text for usado para title ou subtitle é possível estabelecer um limite máximo para o número de linhas com Text.max_lines.

leading controle a ser exibido antes (à esquerda) do título.
selected booleano; se selected=True para um tile então os ícones e textos terão a mesma cor. Por default a cor dos elementos em selected é a cor primária do tema.
subtitle Linhas (ou linhas de texto) a serem exibidas abaixo do título. Em geral um flet.Text.Se is_three_line=False o subtítulo não quebrará em linhas longas. Caso contrário deve ser configurado o número máximo de linhas (por exemplo com Text.max_lines).
title controle a ser exibido como conteúdo principal ou título, em geral um flet.Text. Linhas de título não são quebradas e um limite para essa linha única pode ser ajustado com Text.max_lines.
toggle_inputs booleano; define se um clique na ListTile deve abrir (ou fechar) uma caixa de Radio, Checkbox ou Switch. O default é toggle_inputs=False.
trailing controle a ser exibido após (à direita ) do título. Em geral é usado um controle de ícone.
url a URL a ser aberta quando o ListTile é clicado. O evento on_click, se definido, será acionado.
url_target a URL a ser aberta, no modo Web.

  • _blank: (default) – nova janela ou guia.
  • _self: na atual janela aberta.

Eventos de ListTile

Evento Descrição
on_click dispara com um clique (ou toque em touch screens) no controle ListTile.
on_long_press dispara com um clique longo (ou toque longo em touch screens) no controle ListTile

Exemplo de uso de ListTile

import flet as ft

def main(page):
    page.title = "Exemplo de uso do Widget ListTile"
    page.horizontal_alignment=ft.CrossAxisAlignment.CENTER

    def clk(e):
        lt1.data +=1
        lt1.title.value=f"Você clicou {lt1.data} {'vez' if lt1.data==1 else 'vezes'} no título"
        page.update()

    def clicado(e):
        ct_info.content.value=f"Foi clicado o item: {e.control.text}"
        page.update()

    class PI(ft.PopupMenuItem):
        def __init__(self, texto):
            super().__init__()
            self.text=texto
            self.on_click=clicado

    lt1=ft.ListTile(title=ft.Text("Linha única no título", size=18), data=0, on_click=clk)
    lt2=ft.ListTile(title=ft.Text("Uma linha densa nessa listTile"), dense=True)
    lt3=ft.ListTile(
        leading=ft.Icon(ft.icons.DELETE_FOREVER_ROUNDED),
        title=ft.Text("Essa linha abre selecionada"),
        selected=True
    )
    lt4=ft.ListTile(
        leading=ft.ElevatedButton(text="X", bgcolor="#cc8866", on_click=clicado),
        title=ft.Text("Linha com controle anterior"),
        subtitle=ft.Text("Clique para apagar caixa de info")
    )
    lt5=ft.ListTile(
        title=ft.Text("Linha com controle posterior"),
        trailing=ft.PopupMenuButton(
            icon=ft.icons.MORE_VERT,
            items=[PI("Popup 1.1"), PI("Popup  1.2")]
        )
    )
    lt6=ft.ListTile(
        leading=ft.Icon(ft.icons.BATTERY_1_BAR),
        title=ft.Text("Linha com controles anterior e posterior"),
        trailing=ft.PopupMenuButton(
            icon=ft.icons.MORE_VERT,
            items=[PI("Popup 2.1"), PI("Popup  2.2")]
        )
    )
    lt7=ft.ListTile(
        leading=ft.Icon(ft.icons.MENU_BOOK),
        title=ft.Text("Título e subtítulo com controles anterior e posterior"),
        subtitle=ft.Text("Aqui vai um subtítulo"),
        trailing=ft.PopupMenuButton(
            icon=ft.icons.MORE_VERT,
            items=[PI("Popup 3.1"), PI("Popup  3.2")]
        )
    )
    ct_info=ft.Container(
        content=ft.Text("Aqui você verá os itens clicados!"),
        width=500, height=40, bgcolor=ft.colors.AMBER_100,
        alignment=ft.alignment.center,
        border=ft.border.all(1, ft.colors.BLUE_100),
        border_radius = ft.border_radius.all(10)
    )
    titulo=ft.Tooltip(
        message="Exemplo de tooltip",
        content=ft.Text("Informações de cliques:"),
        padding=10
    )

    page.add(
        ft.Container(
            content=ft.Column(
                [lt1, lt2, lt3, lt4, lt5, lt6, lt7, titulo, ct_info],
                spacing=20
            ),
            width=500,
            bgcolor=ft.colors.BLUE_50,
            border=ft.border.all(1, ft.colors.BLUE_500),
            border_radius = ft.border_radius.all(15),
            padding=ft.padding.all(15),
            shadow=ft.BoxShadow(
                blur_radius=15,
                color=ft.colors.BLUE_GREY_500,
                offset=ft.Offset(0, 0),
                blur_style=ft.ShadowBlurStyle.OUTER
            )
        )
    )

ft.app(target=main)
Figura 2: (a) estado inicial do aplicativo; (b) estado após 3 cliques no título e um clique no popup 2.2.

A figura 2 exibe o código em execução.

Um clique no controle lt1 aciona a função clk(e) que incrementa o valor de lt1.data e o exibe em lt1.title.value.


Os controles lt5, lt6 e lt7 recebem em ListTile.trailing um menu popup PopupMenuButton. Cada um deles contém PopupMenuButton.items=[PI("Texto 1"), PI("Texto 2")], onde PI herda da classe PI(ft.PopupMenuItem). Isso cria menus popups que abrem ao serem clicados o ícone à direita, icon=ft.icons.MORE_VERT (três pontos verticais). Todos esses ítens respondem ao evento click abrindo a função clicado. Essa função recebe exibe o texto do controle que enviou o evento em ct_info.content.value. O texto é capturado em e.control.text.

Observe que ct_info.content.value é o texto dentro do container ct_info, um texto e não um objeto flet.Text. O nome do controle clicado está em e.control.text.

Como exemplo foi inserido um Tooltip (ferramenta de dicas) no controle titulo, responsável por exibir uma messagem quando o cursor percorre a área do controle.

Controle ListView

Ainda que seja possível adicionar listas longas nos controles Column e Row esses controles serão pouco eficazes e lentos nessa exibição, principalmente porque adicionam seu conteúdo de uma só vez, mesmo que não estejam visíveis. A solução para essa questão consiste em usar os controles ListView e GridView.

ListView é um controle especialmente útil para a exibição de conteúdo longo. Ele insere controle sucessivamente na direção estabelecida para o rolamento, permitindo percorrer sua extensão automaticamente (com o autoscroll). Controles podem ser adicionados na vertical (o default) ou na horizontal.

Apesar de que ListView insere gradualmente seu conteúdo e renderiza seus filhos com eficiência, o rolamento pode ser melhorado ajustando uma altura fixa para todos os ítens filhos no rolamento vertical, ou largura fixa no rolamento horizontal. Para fazer isso podemos determinar uma altura absoluta na propriedade item_extent ou, alternativamente marcando a propriedade first_item_prototype = True no primeiro filho, o que obriga todos os demais a ter a mesma extensão.

O seguinte exemplo mostra como se pode renderizar rapidamente 5000 linhas de texto com esse controle.

import flet as ft

def main(page: ft.Page):
    lv = ft.ListView(expand=True, spacing=10)
    for i in range(5000):
        lv.controls.append(ft.Text(f"Linha {i+1}"))
    page.add(lv)

ft.app(target=main)


Nesse caso o rolamento não é automático. Para que a tela role junto com inserção de controle modificamos a definição do controle usando:

lv = ft.ListView(expand=True, auto_scroll=True, spacing=10)

.
Note que foi usado expand=True no construtor de ListView. Para que essa propriedade funcione corretamente temos que ajustar a altura (height), ou largura (width) no rolamento horizontal. Podemos marcar ListView(height=300, spacing=10), por exemplo. No exemplo acima forçamos o controle a usar todo o espaço disponível com ListView.expand=True.

Propriedades de ListView

Propriedade Descrição
auto_scroll booleano, auto_scroll=True se a barra de rolamento (scrollbar) deve ser mover automaticamente até o final do último filho acrescentado. Para que o método scroll_to() funcione esse controle deve ser ajustado como auto_scroll=False.
controls A lista de controles a serem exibidos dentro do ListView.
divider_thickness Se esse valor for maior que zero um controle Divider é usado no espaçamento entre os ítens. O default é divider_thickness=0.
first_item_prototype booleano, first_item_prototype=True para que as dimensões do primeiro filho devem ser usadas como “protótipo” para os demais itens inseridos. Nesse caso todos os controles terão a mesma altura ou largura que o primeiro filho. O default é False.
horizontal booleano, horizontal=True para que os itens sejam dispostos horizontalmente.
item_extent uma altura (ou largura, no rolamento horizontal) fixa para que um item tenha renderização otimizada.
on_scroll_interval passo ou salto em milisegundos para o disparo do evento on_scroll. Default é on_scroll_interval=10.
padding espaçamento interno para posicionamento dos fihos. Veja a propriedade Container.padding.
reverse booleano, define a direção do rolamento. Default é reverse=False.
spacing altura do controle Divider entre itens do ListView. Espaçamento zero é usado se esse valor não é especificado.

Método de ListView

scroll_to(offset, delta, key, duration, curve) Move a posição da barra de rolagem (e, portanto, da posição visível dentro do controle) para uma marca absoluta, um salto relativo ou para uma chave especificada.

Veja Column.scroll_to() para detalhes.

Evento de ListView

on_scroll dispara quando a posição da barra de rolamento é alterada pelo usuário.

Veja Column.scroll_to() para detalhes.

Exemplo de uso de ListView

O exemplo mostra a montagem de conteúdo dentro de um ListView, com intervalo de tempo de .1 segundoprovocado por sleep(.1).

from time import sleep
import flet as ft

def main(page: ft.Page):
    page.title = "Use ListView com auto-rolagem"

    arr=[ft.Text("<h1>Título do conteúdo da Web</h1> ", size=20, bgcolor="#aabbff")]
    lv = ft.ListView(
        controls=[ft.Text("<h1>Título do conteúdo da Web</h1> ", size=20)],
        expand=True,
        spacing=1,
        padding=40,
        auto_scroll=True,
        divider_thickness=1
    )

    ct=ft.Container(
        content=lv,
        width=500, height=500, bgcolor=ft.colors.AMBER_50,
        alignment=ft.alignment.center,
        border=ft.border.all(1, ft.colors.BLUE_100),
        border_radius = ft.border_radius.all(10)
    )
    page.add(ct)

    def escreve_texto(texto):
        sleep(.1)
        lv.controls.append(ft.Text(texto))
        page.update()

    escreve_texto("<p>Podemos construir uma lista não-ordenada:</p>")
    escreve_texto("<ul>")

    for i in range(0, 3):
        escreve_texto(f"    <li>Exibindo conteúdo da linha {i}</li>")
    escreve_texto("</ul>")
    escreve_texto("<p>Podemos construir uma tabela</p>")
    escreve_texto("<table>")
    escreve_texto("<tr><th>Palavra</th><th>Número</th>")
    escreve_texto("<th>Palavra</th><th>Número</th>")
    escreve_texto("<th>Palavra</th><th>Número</th></tr>")

    for i in range(0, 9, 3):
        escreve_texto("<tr>")
        escreve_texto(f"    <td>palavra</td><td>{i}</td>")
        escreve_texto(f"    <td>palavra</td><td>{i+1}</td>")
        escreve_texto(f"    <td>palavra</td><td>{i+2}</td>")
        escreve_texto("</tr>")
    escreve_texto("</table>")

ft.app(target=main)
Figura 3: estado final do tivo após execução, com rolagem ajustada para o início.

O controle ListView é criado e inserido na página com apenas um controle (flet.Text). Controles filhos são adicionados depois por meio da função escreve_texto(texto). A figura 3 mostra o aplicativo resultante da execução desse código.

O texto gerado é parte de uma página HTML, algo usado apenas como uma demonstração da montagem gradual no controle, sem um significado especial pois esse controle não pode renderizar texto com marcação HTML. O texto gerado seria representado em um navegador como mostrado na figura 4, incluído aqui apenas por completeza.

Figura 4: texto html renderizado.

Flet: ExpansionTile

Outro controle de Layout

Controle ExpansionTile

Controle ExpansionTile é um controle que exibe uma linha contendo, por default, um ícone com setas, um título, subtítulo e admitindo como conteúdo um array de controles como filhos que serão exibidos como conteúdo. Um clique nas setas ou cabeçalho da linha provoca a a expansão ou colapso do controle. Quando colapsado o titulo e subtítulo continuam visíveis.

Um exemplo mínimo de código aparece listado abaixo, com a ilustração de seu resultado ao ser executado.

import flet as ft

class ETile(ft.ExpansionTile):
    def __init__(self, titulo, subtitulo, arrCtl):
        super().__init__()
        self.title=ft.Text(titulo, size=22, weight=ft.FontWeight.BOLD)
        self.subtitle=ft.Text(subtitulo)
        self.controls=arrCtl

def main(page: ft.Page):

    exp_tile1 = ETile("Título do primeiro ExpansionTile", "Primeiro subtítulo", [ft.Text("Conteúdo interno 1")])
    exp_tile2 = ETile("Título do segundo ExpansionTile", "Segundo subtítulo", [ft.Text("Conteúdo interno 2")])
    arr=[ft.Text("Conteúdo interno 3"), ft.Text("Conteúdo interno 4"), ft.Text("Conteúdo interno 5")]
    exp_tile3 = ETile("Título do terceiro ExpansionTile", "Terceiro subtítulo", arr)
    page.add(exp_tile1, exp_tile2, exp_tile3)

ft.app(target=main)
Figura 1: Estado inicial; Primeiro e segundo tiles expandidos; apenas terceiro tile expandido.

Propriedades de ExpansionTile

ExpansionTile tem as seguintes propriedades:

Propriedade Descrição
affinity usado para forçar a exibição da ícone de expansão e contração (setas por deafault) sejam colocados à esquerda (no início) ou direita (no final) do controle. O valor de affinity pode ser dado por um enum TileAffinity que tem os seguintes valores:

  • LEADING, no início do controle,
  • TRAILING, no final do controle,
  • PLATFORM (default), seguindo as convenções da plataforma.
bgcolor cor de fundo do controle, exibida por trás da sublista, quando exibida.
controls uma lista de controles que serão exibidos quando o ExpansionTile está expandido. Um controle ListTile é normalmente usado como filho, embora outros controles possam ser inseridos.
controls_padding define os espaçamentos (padding) em torno dos controles. Mais informações em Container.padding.
clip_behavior define o comportamento de recorte (clipping) doo contéudo. O valor da propriedade é um enum ClipBehavior com os seguintes valores:

  • NONE (default),
  • ANTI_ALIAS.
  • ANTI_ALIAS_WITH_SAVE_LAYER.
  • HARD_EDGE.
collapsed_bgcolor cor de fundo do controle ExpansionTile quando a sublista está colapsada.
collapsed_icon_color cor do ícone de expansão do controle quando a sublista está colapsada.
collapsed_shape o formato da borda do controle quando a sublista está colapsada. O valor é uma instância do tipo OutlinedBorder do qual se pode herdar:

  • StadiumBorder
  • RoundedRectangleBorder
  • radius: raio da borda, uma instância de BorderRadius ou um número.
  • CircleBorder
  • BeveledRectangleBorder
  • radius: raio da borda, uma instância de BorderRadius ou um número.
  • ContinuousRectangleBorder
  • radius: raio da borda, uma instância de BorderRadius ou um número.
collapsed_text_color cor do título do controle quando a sublista está colapsada.
expanded_alignment define a alinhamento dos filhos, que são distribuídos em uma coluna, quando o controle está expandido.
Veja o propriedade Mais informações em Container.alignment para maiores informações.
expanded_cross_axis_alignment Define o alinhamento de cada controle filho quando o controle está expandido.
O valor da propriedade é um enum CrossAxisAlignment com os valores:

  • START
  • CENTER (default)
  • END
  • STRETCH
  • BASELINE
icon_color cor do ícone de expansão quando a sublista está expandida.
initially_expanded booleno, define se o controle é inicializado expandido ou colapsado. Default = False.
leading um controle a ser exibido antes (à esquerda) do título.
maintain_state booleano, define se o estado do controle é mantido após ser expandido ou colapsado. Default = False.
shape formato da borda do controle quando a sublista está expandida. O valor é uma instância do tipo OutlinedBorder da qual herdam:

  • StadiumBorder
  • RoundedRectangleBorder
  • radius: raio da borda, uma instância de BorderRadius ou um número.
  • CircleBorder
  • BeveledRectangleBorder
  • radius: raio da borda, uma instância de BorderRadius ou um número.
  • ContinuousRectangleBorder
  • radius: raio da borda, uma instância de BorderRadius ou um número.
subtitle conteúdo a ser exibido abaixo do título. Pode ser um widget de texto (flet.Text).
text_color cor de texto do título quando a sublista está expandida.
tile_padding Espaçamento interno (padding) do controle. O valor default é padding.symmetric(horizontal=16.0).
Veja Container.padding.
title controle a ser exibido como título principal. Pode ser um widget de texto (flet.Text).
trailing controle a ser exibido depois (à direita) do título. Pode ser um controle de ícone

Eventos de ExpansionTile

ExpansionTile tem os seguintes eventos:

Evento Descrição
on_change dispara quando o usuário clica (ou toca) no controle.
on_long_press dispara quando o usuário clica (ou toca) demoradamente sobre o controle.

Exemplo de uso de ExpansionTile

O código abaixo faz uma demonstração do controle ExpansionTile. Abaixo segue uma imagem, figura 2, mostrando o resultado da execução desse código.

import flet as ft
import random

cor=["#DA2222", "#2CDA22", "#2275DA", "#5622DA", "#C99032", "#A7D7DE"]
bgcor=["#E7DADA", "#DCE8DB", "#CFE3FA", "#D2CEDB", "#F9E9CE", "#D2E9EC"]

def main(page: ft.Page):
    page.spacing = 0
    page.theme_mode = ft.ThemeMode.LIGHT # DARK
    page.padding = ft.padding.all(5)
    page.bgcolor="#7CC2D1"

    def mostrar_snack(texto):
       return ft.SnackBar(
           ft.Row(
               [ft.ElevatedButton("Mudar Cores", bgcolor="WHITE", on_click=mudar_cor),
               ft.Text(texto,size=18)]
            ), duration=5000 )

    def apagar(e):
        if e.control.data==1:
            page.controls.remove(etile1)
        elif e.control.data==2:
            page.controls.remove(etile2)
        else:
            page.controls.remove(etile3)
        page.show_snack_bar(mostrar_snack(f"Apagado o controle {e.control.data}"))
        page.update()

    def mudar_cor(e):
        i = random.randrange(0,6)
        etile1.bgcolor=bgcor[i]
        etile1.collapsed_bgcolor=bgcor[(i+1)%6]
        etile2.bgcolor=bgcor[(i+2)%6]
        etile2.collapsed_bgcolor=bgcor[(i+3)%6]
        etile3.bgcolor=bgcor[(i+4)%6]
        etile3.collapsed_bgcolor=bgcor[(i+5)%6]
        page.update()

    def alterou_etile(e):
        qual = f"Barra com título '{e.control._ExpansionTile__title.value}' foi " #a.__dict__
        qual += f"{'expandida' if e.data=='true' else 'colapsada'}"
        page.show_snack_bar(mostrar_snack(qual))

    class ETile(ft.ExpansionTile):
        def __init__(self, titulo, subtitulo, arrCtl,cor1,id):
            super().__init__()
            self.id = id
            self.title=ft.Text(titulo, size=22, weight=ft.FontWeight.BOLD)
            self.subtitle=ft.Text(subtitulo)
            self.controls=arrCtl
            self.controls.append(ft.TextButton("Apagar", on_click=apagar, data=id))
            self.text_color=cor[cor1]
            self.collapsed_text_color=cor[5]
            self.on_change=alterou_etile
            self.bgcolor=bgcor[(cor1+1)%6]
            self.collapsed_bgcolor=bgcor[(cor1+2)%6]
            self.controls_padding = ft.padding.all(-5)

    titulo="Primeiro ExpansionTile"
    subtitulo="Demonstrando ícone no final do controle"
    arrCtl=[ft.ListTile(title=ft.Text("Texto interno do ExpansionTile 1"))]
    etile1=ETile(titulo, subtitulo, arrCtl, 0, 1)

    etile1.affinity=ft.TileAffinity.TRAILING
    etile1.maintain_state=True
    etile1.initially_expanded=True

    titulo="Segundo ExpansionTile"
    subtitulo="Demonstrando ícone personalizado"
    arrCtl=[ft.ListTile(title=ft.Text("Texto interno do ExpansionTile 2"))]
    etile2=ETile(titulo, subtitulo, arrCtl, 2, 2)
    etile2.trailing=ft.Icon(ft.icons.ADD_A_PHOTO_ROUNDED)

    titulo="Terceiro ExpansionTile"
    subtitulo="Ícone no início do controle e várias linhas internas"
    arrCtl=[ft.ListTile(title=ft.Text("3.1: Texto interno 1 do ExpansionTile 3")),
            ft.ListTile(title=ft.Text("3.2: Texto interno 2 do ExpansionTile 3")),
            ft.ListTile(title=ft.Text("3.3: Texto interno 3 do ExpansionTile 3"))]
    etile3=ETile(titulo, subtitulo, arrCtl, 4, 3)

    etile3.affinity=ft.TileAffinity.LEADING

    page.add(etile1, etile2, etile3)

    page.show_snack_bar(mostrar_snack("Clique nas barras ou ícones"))

ft.app(target=main)
Figura 2: estado inicial do aplicativo. Segundo e terceiro tiles expandidos. Segundo tile apagado.

A classe ETile é usada para construir os controles ExpansionTile no aplicativo. Ela adiciona um botão a cada um deles que pode apagar esse controle. Para identificar qual controle deve ser apagado cada botão recebe um id anexado por meio de flet.TextButton.data. O apagamento consiste na remoção do controle da lista page.controls.

O apagamento ou mudança de estado entre colapsado ou expandido de cada controle são relatados em um flet.SnackBar, uma barra mostrada temporariamente no pé da página. Eesa barra também contém um botão que aciona o evento que troca as cores de fundo dos elementos colapsados ou não.

Flet: Dismissible

Outro controle de Layout

Controle Dismissible

Dismissible é um controle que pode ser arrastado em uma direção especificada. Quando arrastado ele gera eventos que podem ser capturados para efetuar ações sobre o aplicativo. O conteúdo desenhado dentro do controle permanece visível e acompanha o arrasto do controle que o contém. O controle é dispensado (eliminado) do aplicativo quando atinge um deslocamento mínimo determinado em código.

Nota: chamaremos de dispensa a ação de dismiss do controle. Antes da dispensa o controle encolhe em tamanho, gerando os eventos descritos abaixo.

Um exemplo bem reduzido de uso do dismiss é mostrado abaixo.

import flet as ft
import copy

def main(page):

    dm1=ft.Dismissible(content=ft.Text("Primeira Linha", size=20, bgcolor=ft.colors.AMBER_100))
    (dm2 := copy.deepcopy(dm1)).content.value="Segunda Linha"
    (dm3 := copy.deepcopy(dm1)).content.value="Terceira Linha"

    page.add(ft.Column([dm1, dm2, dm3]))
ft.app(main)

Esse código gera o seguinte aplicativo, mostrado na figura 1 em três estados:

Figura 1: Três linhas de controle Dismissible: estado original, arrasto para a direita, linha 1 eliminada.

Nesse exemplo criamos um controle dm1=ft.Dismissible() e o copiamos, usando deepcopy para dois outros controles. O método copy.deepcopy é necessário para que controles internos sejam copiados e a cópia seja feita por valor. Isso significa que dm2 e dm3 são novos objetos e não apenas uma nova referência para dm1. Com isso podemos mudar dm2.content.value="Segunda Linha" (o valor do conteúdo interno).

Nota: O operador walrus (:=) de atribuição tem o efeito de fazer uma atribuição e já retornar o objeto para operações posteriores. Portanto:

    (dm2 := copy.deepcopy(dm1)).content.value="Segunda Linha"
    # é o mesmo que
    dm2 = copy.deepcopy(dm1)
    dm2.content.value="Segunda Linha"

Em um caso mais elaborado podemos inserir linhas formatadas (por exemplo inserindo o texto dentro de containers), capturar outros eventos e definir outras propriedades. A figura 2 mostra um caso um pouco mais elaborado e o exemplo de uso de Dismissible no final desse texto mostra um código mais completo.

Figura 2: linhas formatadas com container: arrasto da linha 1 para ambos os lados e exclusão da linha 1.

Propriedades de Dismissible

Dismissible tem as seguintes propriedades:

Propriedade Descrição
background um controle que fica por trás do controle principal que exibe conteúdo.
Se secondary_background também for especificado esse controle secundário aparece como fundo quando o conteúdo é arrastado para os lados ou verticalmente.
content um controle filho que fica exibido dentro do Dismissible e se move com ele.
cross_axis_end_offset especifica um valor para deslocamento vertical quando o controle é movido horizontalmente, fazendo o controle se mover na diagonal, para baixo se o valor for positivo, para cima se negativo.
direction direção usada para dispensar o controle. Os valores possível estão no enum DismissDirection:

  • DismissDirection.UP
  • DismissDirection.DOWN
  • DismissDirection.LEFT
  • DismissDirection.RIGHT
  • DismissDirection.START_TO_END
  • DismissDirection.END_TO_START
dismiss_thresholds o valor mínimo de deslocamento considerado para dispensar o controle. A partir desse valor o controle é removido do aplicativo. Por exemplo, se o valor é de 0.4 (o default) a barra tem que ser movida de 40% ou mais de sua extensão para ser dispensada. Seu valor é especificado como um dicionário tendo como chaves um objeto DismissDirection e o valor um valor numérico entre 0.0 e 1.0. O bloco de código mostra isso:

    ft.Dismissible(
    # ...
    dismiss_thresholds={
        ft.DismissDirection.VERTICAL: 0.1,
        ft.DismissDirection.START_TO_END: 0.7
    }
)

Esse dicionário define que os valores mínimos (thresholds) são 10% na vertical e 70% na horizontal, se o movimento for do início para o final (para a direita).

movement_duration a duração do movimento para que o controle seja dispensado ou retorne para sua posição original.
resize_duration a duração do movimento de contração antes que o evento de dispensa seja acionado.
secondary_background um controle desenhado por tras do conteúdo principal, que é exposto quando o conteúdo é arrastado para os lados. Só pode ser especificado se o background também for definido.

Eventos de Dismissible

Evento Descrição
on_confirm_dismiss um evento que ocorre antes que o controle seja dispensado, dando a oportunidade de se confirmar ou negar essa operação. O controle não pode ser arrastado novamente até que essa pendência seja resolvida.

Para resolver essa pendência deve ser chamado o método confirm_dismiss(dismiss) passando um booleano: True para confirmar, provocando a dispensa do controle, False para negar, o que faz com que ele volte para sua posição original. Uma possibilidade consiste em apresentar a pergunta em uma caixa como AlertDialog.

on_dismiss dispara quando o controle é dispensado. Antes da dispensa o controle é contraído, diminuindo de tamanho.
on_resize dispara quando o controle muda de tamanho, o que ocorre, por exemplo, na contração ao ser dispensado.
on_update dispara quando o controle é arrastado, independentemente de ser ou não dispensado.

Método de Dismissible

Método Descrição
confirm_dismiss(dismiss: bool) resolve a pendência quando a dispensa é requerida. Esse evento pode ser chamado quando se trata do evento on_confirm_dismiss.

Exemplo de uso de Dismissible

Um exemplo mais completo de código está listado abaixo. Para manter a simplicidade e não usar caixas de diálogo (ainda não consideradas nessas notas) o evento on_confirm_dismiss=informe_dispensa apenas aciona a função informe_dispensa que registra na caixa de informações as ações de remoção dos controles pela direita ou pela esquerda, sem pedir a confirmação.

import flet as ft

def main(page):

    def informe_dispensa(e: ft.DismissibleDismissEvent):
        if e.direction == ft.DismissDirection.END_TO_START:
            msg.value += "\nSaída pela direita!"
        else:
           msg.value += "\nSaída pela esquerda!"
        e.control.confirm_dismiss(True)
        page.update()

    def dispensar(e):
        coluna.controls.remove(e.control)
        page.update()

    def atualizar(e: ft.DismissibleUpdateEvent):
        if e.direction == ft.DismissDirection.END_TO_START:
            icone.name=ft.icons.ARROW_BACK
        else:
            icone.name=ft.icons.ARROW_FORWARD
        texto.value=f"Progresso: {e.progress}"
        page.update()

    cor = [ft.colors.AMBER_100,ft.colors.BLUE_GREY_100, ft.colors.BLUE_50]
    array=[
        ft.Dismissible(
            content=ft.Container(
                ft.Text(f"Esta é a linha {i+1}", size=15),
                height=35, width=380, 
                border = ft.border.all(2, ft.colors.BLACK54),
                bgcolor= cor[i%2],
                padding = ft.padding.all(6),
                margin = ft.margin.all(2)
            ),
            dismiss_direction=ft.DismissDirection.HORIZONTAL,
            background=ft.Container(bgcolor=ft.colors.CYAN_100),
            secondary_background=ft.Container(bgcolor=ft.colors.BROWN_50),
            dismiss_thresholds={
                ft.DismissDirection.END_TO_START: 0.2,
                ft.DismissDirection.START_TO_END: 0.2
            },
            on_dismiss=dispensar, 
            on_update=atualizar,
            on_confirm_dismiss=informe_dispensa
        ) for i in range(10)
    ]

    coluna=ft.Column(array, spacing=1)
    icone=ft.Icon(name=ft.icons.KEYBOARD, color=ft.colors.BLUE, size=30)
    texto=ft.Text("Posição dos controles", size=18)
    linha_info = ft.Row([icone, texto])
    msg = ft.Text(f"Eventos capturados (Dispensar):\n" , size=15)
    ver_acao = ft.Container(
        msg,
        height=100, width=380, 
        expand=True,
        border = ft.border.all(2, ft.colors.BLACK54),
        bgcolor= cor[2],
        padding = ft.padding.all(12),
        margin = ft.margin.all(3)
    )

    page.add(coluna, linha_info, ver_acao)

ft.app(main)
Figura 3: (a) o estado inicial do aplicativo; (b) arrasto da linha 1 para a direita; (c) arrasto da linha 2 para a esquerda; (d) removidas linhas 1 e 3.

A operação array=[(objeto(i)) for i in range(10)] cria uma lista com 10 objetos objeto(i) passando o valor de i internamente para o objeto em cada loop.

A função informa_dispensa(e) recebe o evento e que contém uma descrição da direção do evento de arrastar. Ela atualiza a variável msg que é exibida dentro do container ver_acao.

A função dispensar(e) usa a referência ao controle e.control para removê-lo, usando coluna.controls.remove(e.control).

A função atualizar(e) escolhe um ícone de direção e insere texto mostrando a porcentagem de arrasto a cada momento, atualizando a variável texto que está em linha_lnfo.

Flet: Exemplo 4

Controles de Layout

Card, Tabs, SafeArea, Divider, VerticalDivider, ExpansionPanelList são outros controles que facilitam a divisão, exibição ou ocultação de conteúdo dentro de uma página de aplicativo.

Seguem-se alguns exemplos de códigos usando esses controles.

Exemplo de uso de Card

Leia sobre a descrição do controle, suas propriedades e evento em Controles de Layout: Card.
O código abaixo exibe a construção de uma página com 3 cards.

import flet as ft

def main(page):
    page.title = "Exemplo usando \"card\""

    listitulo = ft.ListTile(leading=ft.Icon(ft.icons.ACCESS_ALARM,  size=50, color="#D3143E"),
                            title=ft.Text("Compromisso: 28 de junho de 2024"),
                            subtitle=ft.Text("Aniversário de seu filho. Não esqueça o presente!"),)
    
    def apagar(e):
        listitulo.title= ft.Text("")
        listitulo.subtitle=ft.Text("* apagado", color="#aaaaaa")
        cartao.color="WHITE"
        page.update()

    def proximo(e):
        listitulo.title=ft.Text("Compromisso: 01 de agosto de 2024")
        listitulo.subtitle=ft.Text("Viagem para São Paulo", color="#000000")
        cartao.color="#CBEBA8"
        page.update()

    bt1 = ft.TextButton("Apagar", on_click=apagar)
    bt2 = ft.TextButton("Próximo compromisso", on_click=proximo)

    linha = ft.Row([bt1, bt2], alignment=ft.MainAxisAlignment.END)
    coluna = ft.Column([listitulo, linha,])
    contem = ft.Container(coluna, width=500, padding=20,)
    cartao = ft.Card(contem, color="YELLOW", shadow_color="white", elevation=8.0)

    page.add(cartao)

ft.app(target=main)

Na figura 1 o resultado desse código, quando executado.

Figura 1: O Card amarelo mostra o estado incial do app. Card verde, se for clicado “Próximo compromisso”. Último Card, se o clique for no botão “Apagar”.

Tabs

Leia sobre a descrição do controle, suas propriedades e evento em Controle Tabs.

O controle Tabs, usualmente chamado de guias ou abas em português, é usado para separar conteúdo de categorias diferentes, facilitando a navegação do usuário. Ele simula a marcação de bookmarks em um livro físico, para indicar setores de conteúdos diversos, sendo um padrão de desenho com o qual os usuários estão acostumados, no desktop ou web.

Exemplo de uso de Tabs

O código abaixo exibe a construção de uma página o uso de Tabs.

import flet as ft

def main(page: ft.Page):
    page.bgcolor=ft.colors.BROWN_200
    
    ct_interno=ft.Container(content=ft.Text("Conteúdo do Tab 1 dentro de um Card",
                            size=20, weight=ft.FontWeight.BOLD), padding=45)
    
    card = ft.Card(content= ct_interno, elevation=20, expand=1)

    ct_tab1 = ft.Container(content=card, bgcolor="#BAE3ED", alignment=ft.alignment.center)

    tab1 = ft.Tab(text="Tab 1", content=ct_tab1)

    ct_tab2 = ft.Container(content=ft.Text("Conteúdo de texto do Tab 2", size=30),
                           bgcolor="#BBF3EF",
                           margin = ft.margin.all(10.0),
                           padding=ft.padding.all(1.0),
                           alignment=ft.alignment.top_right,
                           border=ft.border.all(2, "#55555"),
                           border_radius=20)

    tab2 = ft.Tab(text="Tab 2", icon=ft.icons.SEARCH, content=ct_tab2)

    ct_tab3 = ft.Container(content=ft.Text("Conteúdo de texto do Tab 3", size=30),
                           bgcolor="#FCF5CC", alignment=ft.alignment.bottom_left)

    tab3 = ft.Tab(text="Tab 3", icon=ft.icons.SETTINGS, content=ct_tab3)

    tabs = ft.Tabs(tabs=[tab1, tab2, tab3],
                   selected_index=0,
                   divider_color="#ABCAD0",
                   label_color="WHITE",
                   unselected_label_color="BLACK",
                   overlay_color = "YELLOW",
                   indicator_padding=10,
                   indicator_color="RED")

    page.add(ft.Container(tabs, bgcolor=ft.colors.BROWN_200, expand=1))

ft.app(target=main)

O resultado desse código está mostrado na figura 2.

Figura 2: Tabs 1, 2 e 3 exibidos, com cliques nas respectivas guias ou abas (tab).

O primeiro tab exibe um card com texto interno, centralizado. O segundo tab tem um container formatado com bordas arredondadas e texto no alto, à direita. O terceiro tab tem texto em baixo, à esquerda.

Observe que no código acima, e na maioria dos blocos de código nessas notas, os controles são montados por partes, separando controles que serão depois inseridos dentro de outros. Para montar o tab1, criamos ct_interno, um container com um texto e o inserimos dentro de card, que é inserido em ct_tab1 e finalmente em tab1. Isso é feito por motívo didático, para que o código fique mais fácil de ser entendido, e não tem efeito no resultado no momento da execução. Esse estilo é uma preferência do programador. Uma forma alternativa para a construção do mesmo controle pode ser vista abaixo.

    tab1 = ft.Tab(
        text="Tab 1",
        content=ft.Container(
            content=ft.Card(
                content=ft.Container(
                    content=ft.Text("Conteúdo do Tab 1 dentro de um Card",
                    size=20, weight=ft.FontWeight.BOLD), padding=45
                ),
                elevation=20, expand=1
            ),
            bgcolor="#BAE3ED",
            alignment=ft.alignment.center
        )
    )

De qualquer forma é importante estabelecer um critério de indentação e se manter coerente com ele.

SafeArea

SafeArea insere conteúdo com preenchimento (padding, as distâncias entre as margens internas do container com as bordas externas do controle) de modo a impedir que os elementos de interface do sistema operacional se sobreponham às do aplicativo. Leia sobre a descrição do controle, suas propriedades em Controles de Layout: SafeAreaCard.

Um exemplo é mostrado no código abaixo.

import flet as ft

class Contador:
    contagem = 0

def main(page: ft.Page):    
    def add_click(e):
        cliques.contagem += 1
        contador.value = f"Contador: {cliques.contagem}"
        contador.update()

    page.horizontal_alignment=ft.CrossAxisAlignment.CENTER
    page.vertical_alignment=ft.MainAxisAlignment.CENTER
    page.floating_action_button = ft.FloatingActionButton(icon=ft.icons.ADD, on_click=add_click)

    cliques = Contador()

    contador = ft.Text("Contador: 0", size=30, color="WHITE", weight=ft.FontWeight.BOLD)

    page.add(
        ft.SafeArea(
            expand=False,
            content=ft.Container(
                content=contador,
                padding=35, width=300, height=190,
                alignment=ft.alignment.center,
                bgcolor="BLUE",
                gradient=ft.LinearGradient(colors=[ft.colors.BLACK, ft.colors.BLUE_900]),
                border=ft.border.all(3, ft.colors.BLUE_100),
                border_radius=ft.border_radius.all(10)
            )
        )
    )

ft.app(main)

A execução desse código gera um aplicativo mostrado na figura 3.

Figura 3: Controle SafeArea tendo um container no seu interior.

Observe que, para manter um contador global foi criada a classe e propriedade State.counter. O objeto cliques = Contador() tem, portanto a propriedade cliques.contagem, que é incrementada a cada clique no botão floating_action_button.

Divider e VerticalDivider

São controles usados para desenhar uma linha divisória, horizontal e vertical, respectivamente. Leia sobre a descrição dos controles e suas propriedades em Controle Divider e VerticalDivider.

import flet as ft

def main(page: ft.Page):
    ct1 = ft.Container(bgcolor="#797EF6", expand=True)
    ct2 = ft.Container(bgcolor="#4ADEDE", expand=True)
    divisorVertical = ft.VerticalDivider(width=50, thickness=10, color="#960cc9")
    ct3 = ft.Container(bgcolor="#1AA7EC", expand=True)
    ct4 = ft.Container(bgcolor="#1E2F97", expand=True)
    divisorHorizontal= ft.Divider(height=50, thickness=40, color="#F6E750")

    page.add(
        ft.Row([ct1, divisorVertical, ct2], spacing=0, expand=True),
        ft.Column([ct3, divisorHorizontal, ct4], spacing=0, expand=True)
    )

ft.app(target=main)

O código executado é renderizado como a figura 4.

Figura 4: Divider e VerticalDivider.

A única diferença entre propriedades de Divider e VerticalDivider são as propriedades Divider.height e VerticalDivider.width.

ExpansionPanel e ExpansionPanelList

ExpansionPanelList é o controle usado para criar painéis expansíveis, que podem ser contraídos até um mínimo, expandidos para exibir conteúdo, ou removidos da página. ExpansionPanelsList recebe uma lista de controles ExpansionPanel. Leia sobre a descrição dos controles e suas propriedades em Controle ExpansionPanelList e ExpansionPanel.

import flet as ft

class Painel(ft.ExpansionPanel):
    def __init__(self, cabecalho, titulo, texto, cor, botao=None, indice=0):
        super().__init__()
        self.can_tap_header=True
        self.bgcolor=cor
        self.header=ft.Text("  " + cabecalho, size=22, weight=ft.FontWeight.BOLD)
        self.titulo=ft.Text(titulo, size=18)
        self.texto=ft.Text(texto, size=17)
        self.conteudo=ft.ListTile(
            title=self.titulo,
            subtitle=self.texto,
            trailing=botao
        )
        self.content=self.conteudo
        self.indice = indice

def main(page: ft.Page):
    cor = [ft.colors.GREEN_100, ft.colors.BLUE_100, ft.colors.RED_100,
           ft.colors.WHITE10, ft.colors.BLUE_500, ft.colors.WHITE70]
    
    def pegar_painel(index):
        for pn in panel.controls:
            if index == pn.indice: return pn
        return None    
            

    def mudou(e: ft.ControlEvent):
        if int(e.data)==4: return
        atividade.conteudo.subtitle.value += f"\nO painel {e.data} foi modificado"
        page.update()

    def apagar(e: ft.ControlEvent):
        pn = pegar_painel(e.control.data)
        if pn:
            panel.controls.remove(pn)
            atividade.conteudo.subtitle.value += f"\nFoi apagado o Painel {e.control.data}"
        page.update()

    panel = ft.ExpansionPanelList(
        elevation=8,
        spacing=6,
        expand_icon_color=ft.colors.AMBER_100,
        divider_color=ft.colors.CYAN_ACCENT_100,
        on_change=mudou
    )
    panel.controls.append(
        Painel("Atividades Online", "Lista das ações realizadas no aplicativo.", "",
               cor[4], None,0
        )
    )
  
    panel.controls.append(
        Painel(
            "Painel 1", "Conteúdo do painel 1", "Clique no ícone para apagar o painel 1.", cor[0],
            ft.ElevatedButton("Apagar", icon=ft.icons.DELETE, width=150, height=30, data=1,
            on_click=apagar), 1
        )
    )

    panel.controls.append(
        Painel(
            "Painel 2", "Conteúdo do painel 2", "Clique no ícone para apagar o painel 2.", cor[1],
            ft.ElevatedButton("Apagar", icon=ft.icons.DELETE, width=150, height=30, data=2,
            on_click=apagar), 2
        )
    )

    panel.controls.append(
        Painel(
            "Painel 3", "Conteúdo do painel 3", "Clique no ícone para apagar o painel 3.", cor[2],
            ft.ElevatedButton("Apagar", icon=ft.icons.DELETE, width=150, height=30, data=3,
            on_click=apagar), 3
        )
    )

    atividade = Painel("Resumo de Atividades", "", "Conteúdo de texto da informação de uso", cor[5])
    panel.controls.append(atividade)

    page.add(panel)

ft.app(target=main)

O resultado pode ser visto na figura 5.

Figura 5: à esquerda o painel com todos os painéis recolhidos. À direita o estado do app após algumas operações de expandir e apagar.

Como são gerados no código vários painéis flet.ExpansionPanel é interessante criar a classe Class Painel que herda de ExpansionPanel, personalizando na inicialização cada caso a ser inserido. O último dos painéis exibidos, atividade é usado para armazenar e exibir as ações feitas no aplicativo, no campo atividade.conteudo.subtitle.value. Essas ações são executadas nos eventos ExpansionPanelList.on_change e pelo clique nos botões ElevatedButton colocados em cada painel, exceto o último, e pela ação de apagar um painel. Os painéis são identificados pela propriedade painel.indice, usada para encontrar e deletar um deles.

Outros controles de Layout

Outros controles de montagem de Layout

Nessa seção veremos os controles Card, Tabs, SafeArea, Divider, VerticalDivider, ExpansionPanelList, todos eles widgets que facilitam a divisão, exibição ou ocultação de conteúdo dentro de uma página de aplicativo.

Card

Um card no flet é um painel de bordas arredondadas e com um sombreado colorido simulando uma elevação sobre o fundo onde está desenhado.

Propriedades de Card

Propriedade Descrição
color indica a cor de fundo do card.
content o controle a ser exibido pelo controle. card só pode ter um filho. Para inserir mais de um widget dentro de card insira nele controles que podem ter vários filhos, como Row, Column ou Stack.
elevation: controla o tamanho da sombra abaixo do card, simulando que esse esteja elevado sobre sua base. O valor default é 1.0.
margin distância entre as bordas e a borda de seu container.
shadow_color cor da sombra abaixo do card.
shape a forma do card. Esse valor é uma instância de uma das implementações:

  • StadiumBorder
  • RoundedRectangleBorder
    • radius: raio da borda, uma instância da classe BorderRadius ou um número.
  • CircleBorder
  • BeveledRectangleBorder
    • radius: raio da borda, uma instância da classe BorderRadius ou um número.
  • ContinuousRectangleBorder
    • radius: raio da borda, uma instância da classe BorderRadius ou um número.

O formato default é RoundedRectangleBorder com radius=4.0.

surface_tint_color cor usada como sobreposição de cor para indicar elevação.
Se ajustada para None, nenhuma sobreposição será aplicada. Caso contrário, esta cor será composta sobre a cor de fundo com opacidade relacionada à elevação e usada para desenhar fundo do card. O default é None.
Não consegui usar essa propriedade. Se algum leitor tem essa informação peço que me envie.

Exemplo de uso de Card

Um exemplo mais completo pode ser encontrado em Uso de Card.

import flet as ft

def main(page):
    icon=ft.Icon(ft.icons.ADB_ROUNDED, color=ft.colors.BLUE, size=50 )
    texto1 = ft.Text("Título do Card", size=30)
    texto2 = ft.Text("Conteúdo de texto do Card")
    linha = ft.Row([icon, ft.Column([texto1, texto2])])
    cartao = ft.Card(ft.Container(linha, width=300, padding=20))
    page.add(cartao)

ft.app(target=main)



Como vemos, card tem um único filho, um container que, que sua vez, tem uma linha com um ícone e uma coluna (com dois controles de textos).

Tabs

O controle Tabs, usualmente chamado de guias ou abas em protuguês, é usado para separar conteúdo de categorias diferentes, facilitando a navegação do usuário. Ele simula a marcação de bookmarks em um livro físico, para indicar setores de conteúdos diversos, sendo um padrão de desenho com o qual os usuários estão acostumados, no desktop ou web.

Propriedades de Tabs

Propriedade Descrição
animation_duration tempo de duração, em milisegundos, da animação de trocas entre tabs. O default é 50.
divider_color a cor do divisor entre os tabs ou guias.
indicator_border_radius o raio de arredondadmento de cantos do indicador.
indicator_border_side cor e largura da linha horizontal desenhada abaixo da guia selecionada. Essa linha indica que uma guia está em uso.
indicator_color cor da linha exibida abaixo da guia selecionada.
indicator_padding localiza a linha sublinhada abaixo da guia selecionada, relativa a sua borda. A propriedade indicator_tab_size pode ser usada para indicar a localização das bordas. A propriedade é Falsa para centralizar o conteúdo ou True para usar toda a extensão do tab.
indicator_tab_size booleano, True para que o indicador ocupe todo o tab.
label_color cor dos rótulos das guias selecionadas.
overlay_color define a resposta da cor inicial quando o controle está em foco, hover ou splash. Quando especificada essa propriedade usa MaterialState.FOCUSED, MaterialState.HOVERED ou MaterialState.PRESSED.
selected_index índice do tab selecionado. Pode ser ajustado programaticamente ou selecionado pelo usuário.
scrollable booleano, indica se a barra de tab pode ser rolada horizontalmente. Se scrollable=True cada tab tem a largura necessária para comportar seu rótulo e o controle inteiro é rolável. Se scrollable=False o espaço disponível é distribuído igualmente entre os tabs.
tab_alignment especifica o alinhamento horizontal dos tabs dentro do controle Tabs.
A propriedade TabAlignment é um enum com os valores:

  • NONE
  • START (é o default se scrollable=True)
  • START_OFFSET
  • FILL (é o default se scrollable=False)
  • CENTER
tabs uma lista com os controles tab a serem exibidos.
unselected_label_color a cor das guias (tabs) não selecionadas.

Evento de Tab

Evento Descrição
on_change Dispara quando o índice da guia selecionada (selected_index) é alterado.

Um exemplo de uso de tabs pode ser visto em Uso de Tabs.

Propriedades de Tab

Propriedade Descrição
content o controle a ser exibido quando o Tab é selecionado.
icon ícone a ser exibido à esquerda do texto de Tab.
tab_content um controle com o conteúdo personalizado a substituir o texto e o ícone.
text o nome ou rótulo do Tab.

SafeArea


Outro controle voltado para a diagramação das páginas de aplicativos, SafeArea insere conteúdo com preenchimento (padding, as distâncias entre as margens internas do container com as bordas externas do controle) de modo a impedir que os elementos de interface do sistema operacional se sobreponham às do aplicativo. Ele recua o conteúdo interno evitando sobreposição pela barra de status no alto da tela.

Em particular esse recurso permite o recuo do conteúdo para evitar obstrução pelo “entalhe” no iPhone, (notch) ou outras modificações na geometria das telas em aparelhos menores.

Propriedades de SafeArea

Propriedade Descrição
bottom booleano, se o aplicativo deve evitar intrusão do SO na parte inferior da tela. Default é True.
content recebe o controle filho a ser exibido dentro SafeArea.
left booleano, se o aplicativo deve evitar intrusão do SO na parte esquerda da tela. Default é True.
maintain_bottom_view_padding booleano, default é False. Se True o controle SafeArea deve manter em exibição o MediaQueryData.viewPadding no parte inferior da tela, em vez do MediaQueryData.padding (que é o default).

Por exemplo, caso um teclado na tela seja exibido acima da SafeArea, o preenchimento interno (padding) pode ser mantido abaixo da obstrução sem ser ocultado. Pode ser útil quando o layout contém controles flexíveis que podem ser movidos na interface do usuário. Definir SafeArea=True evita alteração na IU.

minimum preenchimento (padding) mínimo a ser aplicado. Quando o valor de minimum é especificado ele será adotado como padding exceto se esse valor não for suficiente para garantir o preenchimento da área segura.
right booleano, se o aplicativo deve evitar intrusão do SO na parte direita da tela. Default é True.
right booleano, se o aplicativo deve evitar intrusão do SO na parte superior da tela, que em geral contém uma barra de status. Default é True.
Nota: Denotamos nessa tabela, SO = sistema operacional, IU = interface de usuário (ou interface gráfica)

Um exemplo de uso do controle pode ser visto em Uso de SafeArea.

Divider


Um controle voltado para a diagramação das páginas de aplicativos, desenhando uma linha horizontal externa sobre o container pai, com uma linha interna de mesma extensão mas altura possível diferente. Ele admite preenchimento (padding) em ambas as bordas. Pode ter cor, comprimento e espessura definidas.

Propriedades de Divider

Propriedade Descrição
color cor da linha.
height altura da linha, no sentido horizontal. O centro da linha, desenhada no container, fica no centro de sua altura horizontal. O default é 16.0 se esse valor for null.
thickness espessura da linha desenhada dentro do Divider. Se thickness=0.0 a altura será de 1 pixel. Se esse valor for null esse será 0.0.

Exemplos de uso dos controles Vertical e VerticalDivider podem ser vistos em Uso de Divider.

VerticalDivider

Um controle voltado para a diagramação das páginas de aplicativos, desenhando uma linha vertical sobre o container pai, com exatamente análoga à Divider mas com propriedades cor, largura e espessura. A única propriedade diferente é width que define a largura no sentido horizontal da linha externa.

color cor da linha.
width largura linha externa. O centro da linha, desenhada no container, fica no centro de sua altura horizontal. O default é 16.0 se esse valor for null.
thickness espessura da linha dentro do VerticalDivider. Se thickness=0.0 a altura será de 1 pixel. Se esse valor for null esse será 0.0.

ExpansionPanel e ExpansionPanelList

O controle ExpansionPanelList permite a criação de painéis expansíveis, ou seja, podem ser contraídos até um mínimo, expandidos para exibir conteúdo, ou removidos da página. Como organizador de conteúdo na diagramação de uma interface gráfica ele é similar aos Tabs, mas separando o espaço da página em faixas horizontais. Além disso vários painéis podem ficar simultaneamente abertos.

O controle ExpansionPanelsList recebe uma lista de controles ExpansionPanel.

Propriedades de ExpansionPanelList

Propriedade Descrição
controls uma lista de controles ExpansionPanel a serem exibidos dentro do controle pai.
divider_color a cor do divisor quando ExpansionPanel.expanded=False.
elevation define a elevação dos controles filhos ExpansionPanel quando extendido. O valor default é 2.
expanded_header_padding define o espaçamento interno (padding) em torno da cabeçalho quando extendido. O valor default é padding.symmetric(vertical=16.0). Leia mais sobre padding em Propriedades de Containers.
expanded_icon_color cor do ícone. Default é colors.BLACK_54 em modo de tema claro e colors.WHITE_60 em modo escuro.
spacing tamanho do intervalo entre os ExpansionPanels quando extendidos.

Evento de ExpansionPanelList

on_change dispara quando um ExpansionPanel muda de estado entre expandido e colapsado. A propriedade de evento e.data contem o índice do painel ExpansionPanel que causou o evento.

Propriedades de ExpansionPanel

Os objetos ExpansionPanel são os filhos diretos de ExpansionPanelList, que serão representados na página como painéis extendíveis.

bgcolor a cor de fundo do painel.
content os controles que aparecerão dentro desse painel. Esse conteúdo aparece abaixo do cabeçalho (header) quando o painel está expandido. Se content=None o painel terá um espaço reservado para Texto como conteúdo.
can_tap_header booleano. Se can_tap_header=True um toque sobre o cabeçalho do painel provocará sua expansão ou colapso. Defaults é False.
expanded booleano. Define o estado do painel como expandido ou colapsado. Defaults é False (colapsado).
header o controle a ser apresentado dentro do cabeçalho (header). Se header=None o ExpansionPanel terá terá um espaço reservado para Texto no cabeçalho.

Um exemplo de uso dos controles ExpansionPanelList e ExpansionPanel pode ser visto em Uso de ExpansionPanel.

Bibliografia

Todas as URLs foram visitadas em janeiro de 2024.

Python: Strings e Codificação


Outras informações sobre Strings

Aviso: Se você está lendo essas notas pela primeira vez essas informações podem ser consideradas um pouco complexas. É recomendável que você pule essa seção e volte a ela mais tarde.

Strings são variáveis usadas para armazenar texto. Nessas notas elas já foram estudadas na seção Python: Strings. Algumas informações adicionais podem ser úteis.

Prefixos Modificadores de Strings

Além das strings usuais é possível usar modificadores por meio de prefixos para representar coisas diferentes no Python. As strings resultantes são objetos de string, como qualquer outra string, admitindo seus métodos e propriedades. O prefixo f é o mais comum, permitindo a avaliação de expressões dentro de uma string. Além dele podemos mencionar outros prefixos que podem ser usados sozinhos ou em conjunto:

  • b: bytes literais
  • f: string formatada
  • r: strings brutos
  • u: string usando Unicode legado (PEP 414)

As f-strings são de uso muito comum no Python, que permitindo avaliar expressões dentro de literais de string. As strings brutas não são tão populares quanto as f-strings mas têm seus próprios usos, importantes em certas ocasiões. Resumidamente elas ignoram sequências de escape e retornam texto puro. Strings de bytes são necessárias para armazenar objetos que não contém apenas caracteres mas também códigos de controles e outros valores binários. Unicode legado serve para expressar string em sistemas antigos que ainda não tinham o UTF-8 incorporado.

Strings e bytes

O Python tem o datatype bytes, uma classe diferente das strings.

» string1 = 'Python Pool' 
» print(type(string1))  
↳ <class 'str'>

» string2 = b'Python Pool' 
» print(type(string2)) 
↳ <class 'bytes'>

Método bytes(): O método bytes() converte strings em bytes, retornando um objeto imutável. Seu construtor pode receber o conteúdo da string e sua codificação.

» texto = "Podemos converter strings em bytes"
# converta string em bytes
» texto_to_byte = bytes(texto, 'utf-8')
» print(texto_to_byte)
# Output:
↳ b'Podemos converter strings em bytes'

Lembrando: Nos blocos de código nesse site usamos a notação » para linhas de código, para resuktados (outputs) e # para comentários do Python.

O método bytes(texto, 'utf-8') converte a string em um objeto bytes usando a codificação utf-8.
Também é possível passar apenas o tamanho da variável, ou uma lista (um iterável):

» tamanho = 7
» bvar = bytes(tamanho)
» print(bvar)
# Output
↳ b'\x00\x00\x00\x00\x00'

» lista = [1, 2, 3, 4, 5]
» bvar = bytes(lista)
» print(bvar)

# Output
↳ b'\x01\x02\x03\x04\x05'

As saídas contém os números de entrada transformados para o formato hexadecimal: 0 &arr;\x00, …, 5 &arr;\x05, etc.

Método decode(): O método inverso, para receber entradas em formato codificado e retornar o argumento decodificado em uma string comum é decode().

» st1 = b'Decodificar \xE2\x9C\x85'
» st2 = b'Decodificar \xE2\x9B\x85'
» print(st1.decode("utf-8"))
↳ Decodificar ✅
» print(st2.decode("utf-8"))
↳ Decodificar ⛅

Nesse caso decode() converteu bytes em strings. Nesse exemplo o código utf-8 \xE2\x9C\x85 representa o sinal ✅ enquanto \xE2\x9B\x85 é o código para o sinal ⛅.

Método chr(): O método chr() converte um inteiro no caracter unicode correspondente.

» print("Usando chr(int):")
» print(f"Maiúsculas: chr(65) = {chr(65)}, ..., chr(90) = {chr(90)}")
» print(f"Minúsculas: chr(97) = {chr(97)}, ..., chr(122) = {chr(122)}")
    
↳ Usando chr(int):
↳ Maiúsculas: chr(65) = A, ..., chr(90) = Z
↳ Minúsculas: chr(97) = a, ..., chr(122) = z

Strings formatadas

Iniciando com o Python 3.12 passou a ser permitido usar strings formatadas, ou f-strings. Elas são uma forma de inserir avaliações de código dentro de texto, concatenando literais de strings com o resultado.

» idade_1 = 15
» idade_2 = 19
» print(f"A idade somada de nossos alunos é {idade_1 + idade_2}, com média {(idade_1 + idade_2)/2}.")
↳ 'A idade somada de nossos alunos é 34, com média 17.0.'

» aluno = {"nome": "Jean Paul", "sobrenome": "Dirac" ,"area": "Física"}
» print(f"Nosso aluno {aluno["nome"]} {aluno["sobrenome"]} se destacou em {aluno["area"]}!")
↳ 'Nosso aluno Jean Paul Dirac se destacou em Física!'

# uma forma mais compacta de conseguir o mesmo resultado consiste em usar 
» aluno = {"nome": "Jean Paul", "sobrenome": "Dirac" ,"area": "Física"}
» print("Nosso aluno {nome} {sobrenome} se destacou em {area}!".format(**aluno))
↳ 'Nosso aluno Jean Paul Dirac se destacou em Física!'


No último exemplo usamos os nomes dos campos diretamente e passamos a string para o método string.format(**aluno). Como argumento o operador ** de desempacotamento (unpacking) retorna os valores do dicionário, ignorando campos extras, caso existam. Essa última forma é mais concisa e legível.

Strings brutas

Strings brutas (raw strings) tem um comportamento igual ao de uma string literal normal, com uma diferença importante: elas ignoram quaisquer sequências de caracteres de escape contidas na string. Por exemplo:

» print("1 - Componentes do átomo:\n\t Prótons \n\t Nêutrons \n\t Elétrons")
↳ 1 - Componentes do átomo:
       Prótons 
       Nêutrons 
       Elétrons

» print(r"2 - Componentes do átomo:\n\t Prótons \n\t Nêutrons \n\t Elétrons")
↳ 2 - Componentes do átomo:\n\t Prótons \n\t Nêutrons \n\t Elétrons

No primeiro caso os carateres de controle \n e \t, respectivamente newline e tab, são interpretados como controles. No segundo caso os controles são representados literalmente, como strings.

Se nenhum caracter de controle for encontrado a string fica inalterada com o prefixo r.

» print(r"É muito legal programar com python!" == "É muito legal programar com python!")
↳ True

# mas...
» print(r"10\25\1991" == "10\25\1991")
↳ False

regex
Esse tipo de recurso é particularmente útil quando usamos expressões regulares. Nelas são passadas aos métodos parâmetros com strings incluídas barras invertidas, que têm significado especial para as regex, sem necessidade de escape. Você pode ler sobre as expressões regulares em Expressoes Regulares no Python e, no caso geral, Expressoes Regulares.

Raw strings também auxiliam na construção de caminhos de arquivos e diretórios que contêm barras invertidas que não devem ser “escapadas”. Finalmente elas são úteis para exibir strings com caracteres difíceis de digitar ou ler, caracteres de controle como nova linha ou tabulações.

Codificações de caracteres em Python

Para representar caracteres e sinais de controle no computador diversos sistemas de codificação foram criados. Uma codificação é um sistema de traduzir caracteres (letras, pontuações, símbolos, espaços em branco e controle) para números inteiros e posteriormente para bits.

O mais simples deles é o sistema ASCII, que usa apena 1 byte em toda a sua codificação. Isso pode ser confirmado com a operação:

» all(len(chr(i).encode("ascii")) == 1 for i in range(128))
↳ True

o que mostra que todos os caracteres em chr(i).encode("ascii") com i = 0 … 127 tem comprimento 1.
Tabela ASCII resumida:

Código representa
0 até 31 caracteres de controle, não imprimíveis,
32 até 64 pontuação, símbolos, núeros e espaço,
65 até 90 caracteres maiúsculos do alfabeto inglês,
91 até 96 sinais gráficos como [ \ ] ^ _ `,
97 até 122 caracteres minúsculos do alfabeto inglês,
123 até 126 sinais gráficos adicionais como { | } ~,
127 controle de apagamento (del) não imprimível.

No entanto, o sistema de codificação ASCII permite apenas o mapeamento de 127 sinais ou controles. Ele é pequeno demais para representar a variedade de caracteres acentuados, além daqueles usados em outras línguas como chinês e russo. Por isso se desenvolveu um sistema capaz de representar um conjunto muito maior de caracteres e sinais, de denominado Unicode. Muitos outros sistemas foram criados entes dele mas é predominante, hoje o uso do Unicode e um de seus esquemas de codificação, o UTF-8. Por motivo de compatibilidade os primeiros 127 códigos coicidem com os do ASCII



O Unicode não é um sistema de codificação mas engloba vários deles. Ele mapeia caracteres como “a”, “¢” ou “😎”, incluindo emojis. Ele contém praticamente todos os caracteres necessários para uma comunicção moderna internacional, incluindo a marca (código 8207) que indica que o texto será exibido da direita para a esquerda, usado em línguas árabes.

UTF-8: Para representar essa diversidade de caracteres, sinais e controles surgiu o UTF-8, que usa mais de 1 bite na codificação. Seu código tem comprimento variável para cada sinal, podendo chegar a até 4 bites. Por default o Python usa a codificação utf-8.

O código abaixo mostra um caracter, um emoji, com comprimento 4 nessa codificação.

» emoji = "🤨"
» print(len(emoji))
↳ 1
» print(emoji.encode("utf-8"))
↳ b'\xf0\x9f\xa4\xa8'
» print(len(ibrow.encode("utf-8")))
↳ 4

# construir uma lista com objeto de bytes retorna
# o valor decimal para cada byte
» print(list(b'\xf0\x9f\xa4\xa8'))
↳ [240, 159, 164, 168]

Nota, é importante lembrar: o comprimento de um único caracter em unicode no Python é 1, mesmo que ele ocupe vários bites. O comprimento desse caracter codificado em bytes será entre 1 e 4, no UTF-8.

Funções associadas do Python

O Python tem várias funções internas (built-in) associadas com systemas de numeração e codificação de caracteres:

Função retorna
ascii(objeto) string, representação ASCII do objeto com caracteres não-ASCII escapados,
bin(inteiro) string, representação binária do inteiro com prefixo “0b”,
bytes(iterável) converte para bytes, dados binários brutos,
chr(inteiro) string, caracter unicode,
hex(inteiro) string, representação hexadecimal com prefixo “0x”,
int(número) inteiro, converte para inteiro,
oct(número) inteiro, converte para número octal com prefixo “0o”,
ord(string) inteiro, converte caracter unicode para inteiro,
str(objeto) converte para string, texto.

Alguns exemplos:

» print(ascii("jalapeño"))
↳ "'jalape\\xf1o'"

» print(bin(400))
↳ '0b110010000'

» print(bytes(range(97, 123)))  # Iterável de inteiros
↳ b'abcdefghijklmnopqrstuvwxyz'

» print(chr(1114111))
↳ '\U0010ffff'

» print(hex(100))
↳ '0x64'

» print(int('11', base=2))
↳ 3

» print(ord("a"))
↳ 97

» print(str(5))
↳ '5'

» print(str(0xc0ffee))
↳ '12648430'

Módulo String

O Módulo de Strings vem pre-instalado no Python, contendo constantes e método úteis, e duas classes.

String, constantes:

» import string

# string module constants
» print(string.ascii_letters)
↳ abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ

» print(string.ascii_lowercase)
↳ abcdefghijklmnopqrstuvwxyz

» print(string.ascii_uppercase)
↳ ABCDEFGHIJKLMNOPQRSTUVWXYZ

» print(string.digits)
↳ 0123456789

» print(string.hexdigits)
↳ 0123456789abcdefABCDEF

» print(string.whitespace)  # ' \t\n\r\x0b\x0c'

» print(string.punctuation)
↳ !"#$%&'()*+,-./:;?@[\]^_`{|}~

Método capwords(): O módulo possui um único método, capwords(texto, sep=None). Ela quebra a string em texto, transforma em maiúscula a primeira letra de cada palavra e as junta na string de retorno. Se o argumento opcional sep="None" espaços em branco nas extremidaddes são removidos. Se outro sep é fornecido ela é usado para quebrar o texto original.

» import string
» texto = "  venha aprender o \n\n python  "
» print(string.capwords(texto))
↳ "Venha Aprender O Python"

Classe Formatter: O módulo string possui também duas classes. A classe Formatter tem o mesmo comportamento que string.format() mas é útil para ser herdada em uma classe nova do usuário que define formatação personalizada.

» from string import Formatter
» formatter = Formatter()
» print(formatter.format('Um bom site é {site}', site='Phylos.net.'))
↳ 'Um bom site é Phylos.net.'

# variáveis podem ser posicionais e nomeadas
» print(formatter.format('{} {site}', 'Visite nosso site: ', site='Phylos.net.'))
↳ 'Visite nosso site: Phylos.net.'

# O método de string "format()" tem o mesmo comportamento
» print('{} {site}'.format('Leia sobre vários tópicos em ', site='Phylos.net.'))
↳ 'Leia sobre vários tópicos em Phylos.net.'

Método Template: A outra classe de Formatter é Template, útil para a produção de aplicativos internacionalizados, onde um marcador informa a posição onde texto posterir será inserido.

» from string import Template
» temp = Template('Em $lingua a palavra "$palavra" é traduzida como  "$traducao".')
» texto = temp.substitute(lingua='português', palavra='intruder', traducao='intruso')
» print(texto)
↳ 'Em português a palavra "intruder" é traduzida como  "intruso".'

Bibliografia

Todas as URLs foram visitadas em janeiro de 2024.