COMMANDPublished

@ ... BITMAP

@ <nRow>, <nCol> BITMAP [<oBmp>] [RESOURCE <cResName> | FILE <cFileName>] [SIZE <nWidth>, <nHeight>] [OF <oWnd>] [PIXEL]

Displays an image in an AdvPL interface from a repository resource or a disk file.

Visual interfaceImageBitmapTBitmapCommands

01 · OVERVIEW

Overview

The @ ... BITMAP command creates a visual component for displaying images in dialogs, panels and other containers. During compilation it is translated into the TBitmap class New() constructor. The image may come from a resource stored in the object repository or from a file resolved from the environment RootPath.

02 · SYNTAX

Syntax

@ <nRow>, <nCol> BITMAP [<oBmp>] [RESOURCE <cResName> | FILE <cFileName>] [SIZE <nWidth>, <nHeight>] [OF <oWnd>] [PIXEL]

Parameters

nRow, nCol

NuméricoRequired

Row and column where the component is placed. With PIXEL, coordinates start at the upper-left corner of the parent.

oBmp

ObjetoOptional

Variable that receives the TBitmap object, required when properties or methods will be used after creation.

RESOURCE cResName

CaractereOptional

Name of an image stored as a resource in the object repository. NAME and RESNAME are also accepted.

FILE cFileName

CaractereOptional

Disk filename resolved from the environment RootPath. FILENAME and DISK are also accepted.

SIZE nWidth, nHeight

NuméricoOptional

Width and height reserved for the component.

OF oWnd

ObjetoOptional

Dialog, panel, folder or other visual container that owns the bitmap. OF is the form recommended by the official documentation.

ON CLICK / ON RIGHT CLICK

ExpressãoOptional

Literal function executed on a left or right click. The documented syntax does not accept a CodeBlock here.

NOBORDER · SCROLL · ADJUST · CURSOR · PIXEL · WHEN · VALID

CláusulasOptional

Control border, scroll bars, image fitting, cursor, coordinates, enablement and component validation.

03 · PRACTICAL EXAMPLE

Image loaded from a file

#Include "TOTVS.ch"

User Function ExBitmap()
    Local oDlg
    Local oBmp
    Local cFile := "\system\image.png"

    Define Dialog oDlg Title "Image example" ;
        From 180, 180 To 550, 700 Pixel

    @ 10, 10 Bitmap oBmp File (cFile) ;
        Size 120, 80 Of oDlg Pixel NOBORDER

    Activate Dialog oDlg Centered
Return

Expected result

The file is read from RootPath, displayed without a border, and the object remains available in oBmp.

04 · PRACTICAL EXAMPLE

Repository image with click

#Include "TOTVS.ch"

User Function ExBitmapRecurso()
    Local oDlg
    Local oBmp

    Define Dialog oDlg Title "Atalho visual" ;
        From 0, 0 To 180, 360 Pixel

    @ 15, 20 Bitmap oBmp Resource "LOGO_EMPRESA" ;
        Size 120, 60 Of oDlg Pixel Adjust ;
        On Click AbrirCadastro()

    Activate Dialog oDlg Centered
Return

Static Function AbrirCadastro()
    MsgInfo("Imagem selecionada")
Return

Expected result

The resource is fitted to the defined area and calls a literal function when left-clicked.

BEST PRACTICES

Include TOTVS.ch to make the command available to the compiler.
Prefer OF to explicitly identify the owner container.
Keep oBmp when you need Load() or class properties after creation.
SCROLL enables bars when the image is larger than its area.
ADJUST stretches the image and may distort it when aspect ratios differ.
Consult TBitmap for supported formats and additional properties such as transparency.

COMMON PITFALLS

FILE is resolved from RootPath; verify location and availability in the execution environment.
Mixing PIXEL coordinates with another unit may position or size the component incorrectly.
ADJUST may deform the image; preserve its aspect ratio when visual fidelity matters.
Without OF, the component is created in the active window or dialog and may be bound unexpectedly.
For ON CLICK and ON RIGHT CLICK, provide a literal function as documented, not a code block.