COMMANDPublished

@ ... GROUP

@ <nTop>, <nLeft> GROUP <oGroup> TO <nBottom>, <nRight> [LABEL <cLabel>] [OF <oWnd>] [COLOR <nClrText>, <nClrBack>] [PIXEL]

Draws a TGroup frame with an optional title to visually organize controls.

Visual interfaceGroupTGroupVisual groupingLayoutCommands

01 · OVERVIEW

Overview

The @ ... GROUP command draws a grouping rectangle in the interface and may display a title. During compilation it is translated into the TGroup class New() constructor. Unlike TPanel or TFolder, TGroup does not create a container: controls placed inside the frame still belong to the dialog, panel or tab specified in their own commands.

02 · SYNTAX

Syntax

@ <nTop>, <nLeft> GROUP <oGroup> TO <nBottom>, <nRight> [LABEL <cLabel>] [OF <oWnd>] [COLOR <nClrText>, <nClrBack>] [PIXEL]

Parameters

nTop, nLeft

NuméricoRequired

Row and column of the frame starting coordinate.

oGroup

ObjetoRequired

Variable that receives the created TGroup object.

TO nBottom, nRight

NuméricoRequired

Final row and column, defining the lower and right limits of the frame.

LABEL / PROMPT cLabel

CaractereOptional

Title displayed on the grouping frame.

OF oWnd

ObjetoOptional

Dialog, panel, tab or other parent component where the frame is drawn.

COLOR / COLORS nClrText, nClrBack

NuméricoOptional

Text color and, optionally, component background color.

PIXEL

CláusulaOptional

Indicates that coordinates are expressed in pixels from the upper-left corner of the parent.

03 · PRACTICAL EXAMPLE

Visual grouping of credentials

#Include "TOTVS.ch"

User Function ExGroup()
    Local oDlg
    Local oGroup
    Local cUser := Space(30)
    Local cPassword := Space(20)

    Define Dialog oDlg Title "Access" ;
        From 100, 100 To 300, 560 Pixel

    @ 10, 10 Group oGroup To 90, 250 ;
        Label "Credentials" Of oDlg Pixel

    @ 30, 20 Say "User:" Of oDlg Pixel
    @ 28, 75 Get cUser Size 130, 12 Of oDlg Pixel
    @ 58, 20 Say "Password:" Of oDlg Pixel
    @ 56, 75 Get cPassword Size 130, 12 ;
        Of oDlg Pixel Password

    Activate Dialog oDlg Centered
Return

Expected result

GROUP draws the frame. SAY and GET belong directly to oDlg even though they appear inside it.

04 · PRACTICAL EXAMPLE

Group inside a tab

#Include "TOTVS.ch"

User Function ExGroupFolder()
    Local oDlg
    Local oFolder
    Local oGroup
    Local lEnviar := .T.

    Define Dialog oDlg Title "Configurações" ;
        From 0, 0 To 320, 560 Pixel

    @ 10, 15 Folder oFolder Prompts "Notificações" ;
        Size 240, 120 Of oDlg Pixel

    @ 10, 10 Group oGroup To 75, 210 ;
        Label "E-mail" Of oFolder:aDialogs[1] Pixel

    @ 30, 20 CheckBox lEnviar Prompt "Enviar confirmação" ;
        Size 120, 15 Of oFolder:aDialogs[1] Pixel

    Activate Dialog oDlg Centered
Return

Expected result

The frame and CHECKBOX belong to the same tab; oGroup remains only a visual element.

BEST PRACTICES

Include TOTVS.ch to make the command available to the compiler.
Use GROUP to communicate that fields belong to the same section.
Bind inner controls to the same dialog, panel or tab as the group — not to oGroup.
Use short, meaningful LABEL or PROMPT titles.
Leave enough margin between the border, title and inner controls.
Specify OF explicitly to avoid relying on the active window.

COMMON PITFALLS

TGroup is not a container: do not use OF oGroup for controls shown inside the frame.
TO coordinates must be greater than starting coordinates to form a valid area.
Mixing PIXEL with another unit between frame and controls may cause misalignment.
Fields over the title or too close to the border reduce readability.
Too many nested or decorative groups make the interface visually heavy.
Without OF, the frame is drawn in the active window or dialog.