Pular para o conteúdo
CrossFly é 100% open sourceSiga no GitHub
CrossFlyCrossFly
Começar

ImageView

ImageView renderiza uma Image dentro dos limites do componente, com o modo de escala controlado pelo enum ImageSize e alinhamento horizontal/vertical via Position. É a forma declarativa de mostrar uma imagem fixa (foto, capa, logo) num layout.

Internamente ele mantém uma cópia escalada em cache (ResizeMode.STRETCH, ResizeQuality.FAST) para não redimensionar a cada frame; a cache é invalidada ao trocar a imagem, o modo de escala ou o tamanho.

🟢 · Pacote: dev.crossfly.ui · Estende: Component · Estilo: ComponentStyle (usa ingap para margem interna)

Quando usar

  • Exibir uma imagem fixa num layout: foto, capa, logo, avatar.
  • Ajustar como a imagem preenche o espaço (aspect ratio, cover, stretch).

Quando NÃO usar

  • Animação por frame, escala contínua variável ou desenho composto → faça um Component próprio com onPaint chamando paint.image(...) diretamente (ver images-and-graphics/).
  • Imagem de fundo de outro componente → use o BackgroundImage do próprio Component (Cap. 18).

Aparência

A imagem é centrada por padrão dentro da área interna (após ingap) e escalada conforme o ImageSize:

ImageSize Comportamento
ORIGINAL tamanho natural, sem escala
RATIO escala uniforme para caber dentro dos limites (letter-box) — padrão
FIT escala uniforme para cobrir os limites (pode cortar)
STRETCH estica para preencher exatamente (ignora aspect ratio)
FIT_WIDTH / FIT_HEIGHT ajusta à largura / à altura, mantendo proporção
FIT_HALF_WIDTH / FIT_HALF_HEIGHT ajusta a metade da largura / altura

``

Exemplo completo (copiar, colar e rodar)

package com.exemplo;

import dev.crossfly.ui.*;
import dev.crossfly.ui.layout.*;
import dev.crossfly.ui.image.*;   // Image, ImageException

/** Tela principal executável. Aponte o launcher (classname) e rode: gradlew :lwjgl3:run */
public class MainWindow extends Window
{
   @Override
   public void onShow() throws Exception
   {
      super.onShow();
      setLayout(new VerticalLayout());

      // Carregar uma Image pode lançar ImageException/IOException — trate para não quebrar a tela.
      ImageView iv = new ImageView();          // vazio (placeholder: nada é desenhado)
      try {
         Image capa = new Image("cf/samples/api/ui/books/book1.png");
         iv.image(capa).imageSize(ImageSize.RATIO);
      } catch (ImageException e) {
         System.out.println("Imagem não encontrada, usando placeholder vazio: " + e.getMessage());
      }

      add(LAY_FILL, iv);
   }
}

Os trechos abaixo mostram só o miolo (o que vai dentro de onShow()). Para rodar, coloque-os no esqueleto MainWindow acima.

Uso básico

Image capa = new Image("cf/samples/api/ui/books/book1.png");
ImageView iv = new ImageView(capa, ImageSize.RATIO);
container.add(LAY_FILL, iv);

Construtores

Construtor Descrição
ImageView() vazio (image = null, ImageSize.RATIO)
ImageView(Image image) imagem com modo RATIO
ImageView(Image image, ImageSize imageSize) imagem + modo de escala

Propriedades e personalização

Propriedade / método Tipo Padrão O que faz
image(Image) ImageView (fluente) null troca a imagem (invalida cache/layout)
imageSize(ImageSize) ImageView (fluente) RATIO define o modo de escala
alignX(Position) ImageView (fluente) CENTER alinhamento horizontal (START/CENTER/END)
alignY(Position) ImageView (fluente) CENTER alinhamento vertical
getImage() Image — imagem atual (ou null)
getImageSize() ImageSize — modo atual
getAutoWidth() / getAutoHeight() int — tamanho da imagem + ingap (0 se sem imagem)

Callbacks e eventos

Nenhum. ImageView é não interativo.

Estados

Sem estados de interação. Se image == null, nada é desenhado.

Cover (recorte) com alinhamento ao topo

Image foto = new Image(caminhoFoto);
ImageView avatar = new ImageView(foto, ImageSize.FIT)
   .alignY(Position.START);      // mantém o topo visível ao cortar
container.add(0.4f, avatar);

Trocar a imagem em runtime (fluente)

ImageView iv = new ImageView();          // vazio
container.add(LAY_FILL, iv);
// depois, ao carregar:
iv.image(new Image(novoCaminho))
  .imageSize(ImageSize.STRETCH);

Boas práticas

  • Dê ao ImageView um espaço de layout definido (LAY_FILL ou fração) — o modo de escala só faz sentido com limites conhecidos.
  • Libere a Image com dispose() quando ela não for mais usada (recurso nativo — ver Cap. 18).
  • No Web, prefira ResizeQuality.FAST; a escala interna do ImageView já usa esse caminho.

Erros comuns

  • Confundir FIT com RATIO: RATIO faz letter-box (cabe inteira); FIT cobre e pode cortar. STRETCH distorce.
  • Esperar tamanho automático de um ImageView sem imagem: getAutoWidth/Height() retornam 0 quando image == null.

Veja também

Esta página foi útil?