# picture — `u_pbt_picture` #

← Referência dos componentes · Índice do guia

> Apresentação de imagem: todos os formatos correntes, modos de enquadramento, alinhamento, acinzentamento automático e emblema de contador.

> ▶ Ver ao vivo — Aplicação de demonstração, mosaico Picture: a pré-visualização, o código que o produz e esta página, lado a lado.

## Em resumo #

Userobject | `u_pbt_picture`
Classe de items | — (componente sem items)
Serve para | Substituir um `picture` do PowerBuilder: formatos modernos (SVG, WebP, GIF animado), enquadramento controlado, imagem clicável, acinzentamento automático
Opções opt-in | `ib_track_mouse`

## Início rápido #

    // event open da janela
    uo_image.is_source  = "img\logo.png"
    uo_image.is_stretch = uo_image.STRETCH_UNIFORM   // adapta sem deformar
    uo_image.is_align   = uo_image.ALIGN_CENTER
    uo_image.is_tooltip = "Logotipo da empresa"

## De onde vem a imagem: `is_source` #

`is_source` aceita quatro formas, todas permutáveis:

Forma | Exemplo | Utilização
--- | --- | ---
Ficheiro local | `img\logo.png` | png, jpg, bmp, gif, ico, svg, webp
Endereço web | `https://…/logo.png` | Imagem carregada a partir de um servidor (`http` ou `https`)
Dados incorporados | `data:image/png;base64,…` | Imagem já em memória, sem ficheiro intermédio
Recurso de DLL | `img\packimages.dll:SAMPLE` | Imagem empacotada numa DLL de recursos

Pode colocar-se um prefixo `anim:` à frente de um GIF para assinalar explicitamente uma animação (os GIF animam-se de qualquer forma).

Quando o mesmo nome existe sob vários tipos de recurso numa DLL, deve indicar-se o tipo: `img\packimages.dll:PNG/SAMPLE`, `SVG/SAMPLE`, `ICON/APP`, `RCDATA/BLOB`. Ver As imagens e os ícones para os prefixos `mono:` e `tint:`, que recolorem um glifo consoante o tema.

## Como é enquadrada: `is_stretch` #

Constante | Efeito
--- | ---
`STRETCH_UNIFORM` | Predefinição. A imagem é redimensionada sem deformação, totalmente visível; podem surgir margens
`STRETCH_UNIFORMTOFILL` | Redimensionamento sem deformação, mas a moldura é totalmente preenchida; o que excede é recortado
`STRETCH_FILL` | A imagem é esticada para ocupar exatamente a moldura — pode ficar deformada
`STRETCH_NONE` | Tamanho original, sem redimensionamento

`is_align` decide a posição horizontal da imagem quando esta é mais pequena do que o controlo: `ALIGN_CENTER` (predefinição), `ALIGN_START`, `ALIGN_END`. O eixo vertical tem a sua própria propriedade, `is_valign`.

## Constantes #

Constante | Valor | Para
--- | --- | ---
`STRETCH_NONE` · `STRETCH_FILL` · `STRETCH_UNIFORM` · `STRETCH_UNIFORMTOFILL` | `"none"` `"fill"` `"uniform"` `"uniformtofill"` | `is_stretch`
`ALIGN_CENTER` · `ALIGN_START` · `ALIGN_END` | `"center"` `"start"` `"end"` | `is_align`
`VALIGN_TOP` · `VALIGN_CENTER` · `VALIGN_BOTTOM` | `"top"` `"center"` `"bottom"` | `is_valign`
`is_valign` | string | `VALIGN_CENTER` | Colocação vertical quando a imagem é mais pequena do que o controlo: `VALIGN_TOP`, `VALIGN_CENTER`, `VALIGN_BOTTOM`. Os dois eixos são independentes — `is_align` dá a coluna, este a linha — e é isso que torna um canto alcançável
`ROTATION_NONE` · `ROTATION_90` · `ROTATION_180` · `ROTATION_270` | `0` `90` `180` `270` | `ii_rotation`

`ALIGN_START` e `ALIGN_END` são lógicos: seguem o sentido de escrita (Idioma e RTL). Os valores físicos `left` e `right` continuam a ser aceites como sinónimos.

## Propriedades #

Propriedade | Tipo | Predefinição | Função
--- | --- | --- | ---
`is_source` | string | `""` | A imagem a apresentar (ver as quatro formas acima)
`is_stretch` | string | `"uniform"` | Modo de enquadramento: `STRETCH_NONE`, `STRETCH_FILL`, `STRETCH_UNIFORM`, `STRETCH_UNIFORMTOFILL`
`is_align` | string | `"center"` | Posicionamento horizontal quando a imagem é menor do que o controlo: `ALIGN_CENTER`, `ALIGN_START`, `ALIGN_END`. O eixo vertical é `is_valign`
`ib_enabled` | boolean | `true` | A `false`, a imagem é apresentada em tons de cinzento
`ii_badge` | integer | `0` | Emblema de contador no canto superior direito (`0` = nenhum)
`il_badge_color` | long | `0` | Fundo do emblema, em RGB do PowerBuilder (`0` = a cor que vem do tema). A cor do texto é escolhida automaticamente para que o contador continue legível
`ii_badge_size` | integer | `0` | Altura do emblema em píxeis (`0` = o tamanho que vem do tema). O tamanho da letra acompanha sozinho: o contador continua centrado seja qual for a dimensão
`ib_track_mouse` | boolean | `false` | Opt-in: ativa `ue_mouse_enter` / `ue_mouse_leave`
`is_placeholder` | string | `""` | Imagem de espera, apresentada enquanto `is_source` estiver vazia (uma moldura « adicionar uma fotografia », uma silhueta). Apresentada esbatida: um substituto não é o conteúdo e nunca é anunciado como imagem carregada. Aceita o prefixo `mono:`, que recolore um glifo monocromático com o tema
`is_error_source` | string | `""` | Imagem de recurso quando a origem falha o carregamento. Deixe-a vazia e o componente apresenta o seu próprio glifo de erro — nunca uma caixa vazia, que não diz nada ao utilizador enquanto `ue_error` só vai para o seu código. Aceita o prefixo `mono:`
`ii_rotation` | integer | `0` | Quartos de volta, para as digitalizações e fotografias que chegam deitadas: `ROTATION_NONE`, `ROTATION_90`, `ROTATION_180`, `ROTATION_270` (qualquer outro valor vale 0). Um quarto de volta troca também os eixos de ajuste, pelo que a imagem mantém as proporções em vez de ser esmagada
`ib_mirror` | boolean | `false` | Espelho horizontal, aplicado por cima da rotação
`ib_zoomable` | boolean | `false` | Opt-in: o utilizador pode aproximar-se (roda), deslocar-se (arrastar) e voltar ao enquadramento (duplo clique). Para uma planta, uma digitalização, uma fotografia — onde quatro modos de ajuste fixos não chegam
`id_zoom` | double | `1.0` | Fator de zoom: `1.0` = a imagem inteira cabe, até `8.0`. Ao relê-lo obtém o fator atual, roda incluída (`ue_zoom_changed` avisa a cada passo). Requer `ib_zoomable`
`ib_allow_drop` | boolean | `false` | Opt-in: aceita ficheiros largados a partir do Explorador do Windows. A moldura mostra que está armada, e os caminhos completos chegam por `ue_drop_files` — carregá-los em `is_source` cabe à sua aplicação
`ib_auto_height` | boolean | `false` | Opt-in: o userobject assume a altura que respeita as proporções da imagem à largura atual. Para uma imagem essa altura deduz-se: não é preciso calculá-la a partir das dimensões de `ue_loaded`
`is_theme_style` | string | `fluent` | Estilo visual do componente (constantes `THEME_STYLE_*`)
`is_theme_mode` | string | `light` | Variante clara ou escura (constantes `THEME_MODE_*`)
`il_theme_accent` | long | `-1` | Cor de destaque deste componente (`-1` = destaque do tema)
`is_tooltip` | string | `""` | Tooltip simples apresentado ao passar sobre o componente
`is_super_tooltip_title` | string | `""` | Título do tooltip enriquecido (prevalece sobre `is_tooltip`)
`is_super_tooltip_text` | string | `""` | Texto do tooltip enriquecido (aceita marcação enriquecida)
`is_super_tooltip_image` | string | `""` | Imagem do tooltip enriquecido

## Métodos #

Método | Função
--- | ---
`of_reset ( )` | Repõe todas as propriedades nos respetivos valores predefinidos e retira a imagem
`of_set_redraw (boolean)` | Agrupa uma sequência de modificações numa única representação
`of_save_as_png (string)` · `of_save_as_jpg (string)` | Exporta a representação como imagem

## Eventos #

Evento | Acionado quando
--- | ---
`ue_clicked ( )` | Clique esquerdo na imagem
`ue_loaded (long al_width, long al_height)` | A imagem foi carregada; os parâmetros contêm as suas dimensões de origem em pixels
`ue_error (string as_message)` | A imagem não pôde ser carregada (ficheiro inexistente, endereço inacessível, formato recusado)
`ue_rclicked ( )` | Clique direito na imagem
`ue_double_clicked ( )` | Duplo clique na imagem. Os cliques simples que o precedem também são emitidos, pela mesma ordem. Quando `ib_zoomable` está ativo, o duplo clique também repõe o enquadramento: o evento é emitido nos dois casos, e o significado é seu
`ue_zoom_changed (double ad_zoom)` | O fator de zoom mudou, quer pela roda quer por `id_zoom`. `1.0` significa que a imagem inteira volta a caber
`ue_auto_height (long al_height)` | O componente fixou-se numa nova altura; o userobject já foi redimensionado quando o evento é emitido. Requer `ib_auto_height`
`ue_drop_files (string as_files[])` | Ficheiros largados a partir do Explorador: caminhos completos, uma entrada por ficheiro. Requer `ib_allow_drop`
`ue_drag_enter ( )` | Um arrastamento de ficheiros entrou no componente (`ib_allow_drop`)
`ue_drag_leave ( )` | O arrastamento de ficheiros saiu do componente
`ue_mouse_enter ( )` | O rato entra — requer `ib_track_mouse = true`
`ue_mouse_leave ( )` | O rato sai — requer `ib_track_mouse = true`
`ue_ready ( )` | O componente terminou o carregamento; tudo o que foi enviado antes foi reproduzido
`ue_runtime_missing ( )` | O runtime WebView2 está ausente: o componente permanece vazio
`ue_bg_color (long al_color)` | O componente calculou a cor de fundo do respetivo tema; o userobject já a adotou (`backcolor`)

## Exemplos #

### Apresentar a fotografia de uma ficha #

    // event ue_row_changed do datawindow : apresentar a fotografia do cliente atual
    uo_photo.is_source  = "photos\" + ls_code_client + ".jpg"
    uo_photo.is_stretch = uo_photo.STRETCH_UNIFORMTOFILL   // preenche a moldura, o excedente e recortado
    uo_photo.is_align   = uo_photo.ALIGN_CENTER

    // event ue_error de uo_photo : (string as_message)
    uo_photo.is_source = "img\photo_absente.svg"     // imagem de substituicao

Tratar `ue_error` é a forma correta de gerir uma fotografia em falta: é escusado testar a existência do ficheiro antes de o atribuir.

### Uma imagem clicável, à maneira de um botão #

    uo_avatar.is_source    = "photos\utilisateur.png"
    uo_avatar.is_tooltip   = "A minha conta"

    // event ue_clicked de uo_avatar
    of_ouvrir_mon_compte()

### Contador e acinzentamento #

    // Um emblema de notificacoes num icone de correio
    uo_messagerie.is_source = "img\packimages.dll:SVG/MAIL"
    uo_messagerie.ii_badge  = ll_non_lus       // 0 faz desaparecer o emblema

    // Emblema vermelho acima de um limiar, cor do tema caso contrario (0)
    if ll_non_lus > 20 then
        uo_messagerie.il_badge_color = RGB(200, 30, 30)
    else
        uo_messagerie.il_badge_color = 0
    end if

    // Funcionalidade indisponivel : a imagem passa a tons de cinzento, sem outra imagem a fornecer
    uo_messagerie.ib_enabled = ib_droit_messagerie

O acinzentamento é calculado automaticamente: não é necessário fornecer uma segunda imagem «desativada».

### Conhecer as dimensões reais da imagem #

    uo_apercu.is_source = ls_fichier_choisi

    // event ue_loaded de uo_apercu : (long al_width, long al_height)
    uo_statut.of_item("main").is_text = String(al_width) + " x " + String(al_height) + " px"

    // Uma imagem mais pequena do que a moldura : nao a ampliar inutilmente
    if al_width < uo_apercu.width and al_height < uo_apercu.height then
        uo_apercu.is_stretch = uo_apercu.STRETCH_NONE
    end if

### Um banner de largura total #

    uo_banniere.is_source  = "img\banniere.jpg"
    uo_banniere.is_stretch = uo_banniere.STRETCH_UNIFORMTOFILL   // preenche toda a faixa, sem deformar
    uo_banniere.is_valign   = uo_banniere.VALIGN_TOP               // mantem o topo da imagem visivel

## Boas práticas #

- `STRETCH_UNIFORM` é o modo seguro: nunca deforma. `STRETCH_FILL` deve reservar-se para fundos decorativos, em que a deformação não tem consequências.
- Para uma fotografia numa moldura fixa (mosaico de retratos, miniatura), `STRETCH_UNIFORMTOFILL` dá uma apresentação regular, sem margens inestéticas.
- Os ícones devem ser agrupados numa DLL de recursos, em vez de se entregarem centenas de ficheiros; a forma `pack.dll:TIPO/NOME` elimina qualquer ambiguidade.
- Para um glifo monocromático que deve acompanhar o tema claro e escuro, deve utilizar-se o prefixo `mono:` (As imagens e os ícones).
- `ue_error` deve ser programado em todas as imagens cuja origem depende dos dados: é a única rede de segurança em caso de ficheiro em falta.
- Chamar `of_reset()` antes de reutilizar o componente para uma imagem de natureza diferente: sem isso, o modo de enquadramento, o emblema ou o estado acinzentado anteriores permanecem em vigor.

← Referência dos componentes · Índice do guia