Guia Técnico: Como usar CLabel no MQL5 na prática

Se você já tentou exibir informações dinâmicas – preço de ativo, alerta de risco ou simples anotação – direto no gráfico do MetaTrader 5, provavelmente se deparou com a frustração de não encontrar uma ferramenta nativa que combine flexibilidade e leveza. O CLabel, objeto de texto da biblioteca gráfica, preenche esse vazio, mas sua API esbarra em nuances de posicionamento, atualização em tempo real e gerenciamento de memória que pegam até desenvolvedores experientes desprevenidos.

Quando usar CLabel?

• Alertas de breakout: um rótulo que aparece assim que o preço cruza a resistência.
• Indicadores customizados: mostre o valor exato de um cálculo que não cabe em um buffer.
• Feedback de script: informe ao trader que a estratégia está em “modo standby”.

Passo a passo prático

1. Crie o objeto no OnInit() – assim ele já está no gráfico antes da primeira barra.

label_handle = CLabel.Create(0, "MyLabel", 0, 0, 12, clrWhite);

2. Defina propriedades essenciais. O ponto de ancoragem (OBJPROP_CORNER) controla se o rótulo segue o canto da tela ou o canto da barra.

label_handle.Corner(0); // canto superior esquerdo label_handle.XDistance(10); // margem esquerda label_handle.YDistance(20); // margem superior label_handle.Text("Aguardando...");

3. Atualize dentro de OnTick() ou OnCalculate(). O truque é evitar chamadas desnecessárias; use if (new_value!=old_value) para reduzir overhead.

if(price!=last_price) { label_handle.Text("Preço: "+DoubleToString(price,Digits)); label_handle.XShift(ChartTimePriceToXY(0,TimeCurrent(),price).x); last_price=price; }

Limitações que pegam na primeira curva

• Visibilidade em múltiplos períodos: o rótulo não escala automaticamente; em gráficos de 1 min ele pode ficar sobreposto.
• Limite de objetos: o MetaTrader aceita cerca de 10 000 objetos; rótulos excessivos podem disparar erros de memória.
• Sincronização de cores: mudar o tema do gráfico não atualiza o clrWhite automaticamente.

Exemplo de falha e solução contra‑intuitiva

Um trader tentou exibir o “drawdown máximo” usando label_handle.Text() dentro de OnDeinit(). O rótulo nunca apareceu porque o objeto já havia sido destruído. A solução foi criar um label persistente no OnInit() e atualizá‑lo apenas enquanto o EA está ativo, deixando o OnDeinit() responsável apenas por ObjectDelete().

FAQ rápido

• Posicionamento relativo ao preço? Use ChartTimePriceToXY() para converter preço e tempo em coordenadas de tela.
• Atualizar a cada tick? Só se o cálculo for crítico; caso contrário, EventSetTimer() a cada 5 s economiza CPU.
• Rótulo desaparece ao mudar timeframe? Re‑aplique Corner() e XDistance/YDistance no OnChartEvent() que captura CHARTEVENT_CHART_CHANGE.

Dominar o CLabel transforma um gráfico estático em um painel de controle interativo. Experimente o snippet acima, ajuste as margens e teste a frequência de atualização; o ponto de ruptura costuma ser a sobrecarga de chamadas Text(). Confira mais detalhes e templates prontos para acelerar a implementação.

1. Configuração inicial do CLabel

Abra o MetaEditor e crie um novo script ou Expert Advisor. Inclua a biblioteca padrão:

#include  

Instancie o objeto imediatamente após a função OnInit():

CLabel myLabel;

Defina as propriedades básicas – texto, cor, fonte e posição – usando os métodos da classe:

• SetText(“Olá, MQL5!”);
• SetFont(“Arial”,12,STYLE_BOLD);
• SetColor(clrWhite,clrDarkBlue);
• SetPosition(10,20); // X, Y em pixels

2. Checklist operacional para o primeiro label

3. Rotina recomendada – atualização dinâmica

Para que o label reflita dados em tempo real (preço, spread, etc.), utilize OnTick():

void OnTick() { string price = DoubleToString(SymbolInfoDouble(_Symbol,SYMBOL_BID),_Digits); myLabel.SetText("Bid: "+price); myLabel.Move(ChartGetInteger(0,CHART_XDISTANCE),ChartGetInteger(0,CHART_YDISTANCE)); } 

Observe que Move() aceita coordenadas relativas ao canto superior esquerdo do gráfico, permitindo reposicionamento automático quando o usuário altera o zoom.

4. Erros comuns e como evitá‑los

• Objeto não criado – Sempre chame myLabel.Create(0,0,0,0) antes de usar outros métodos.
• Posição fora da tela – Use ChartGetInteger() para obter limites atuais e ajuste.
• Conflito de nomes – Cada label deve ter um identificador único; use myLabel.Name("Label_"+IntegerToString(TimeCurrent())).

5. Fluxo de trabalho simplificado (mini dashboard)

Passo a passo rápido:
1️⃣ Incluir biblioteca
2️⃣ Instanciar CLabel
3️⃣ Definir propriedades
4️⃣ Criar no OnInit
5️⃣ Atualizar no OnTick

6. Aceleração de resultados – integração com indicadores

Combine o label com um indicador customizado para exibir sinais de compra/venda:

int signal = iCustom(_Symbol,_Period,"MySignal",0,0); if(signal==1) myLabel.SetText("⚡ BUY"); else if(signal==-1) myLabel.SetText("⚡ SELL"); 

Esta lógica mantém o trader informado sem abrir janelas adicionais.

7. Perguntas frequentes (FAQ)

• Posso colocar vários labels? Sim. Crie instâncias distintas (CLabel label1, label2) e repita o processo.
• Como remover um label? Use myLabel.Delete(); dentro de OnDeinit() ou quando não for mais necessário.
• É possível fixar o label ao canto da janela? Defina SetAnchor(ANCHOR_TOP_LEFT) antes de chamar Create().

Para aprofundar a documentação oficial da classe CLabel, acesse MetaTrader 5 Documentation.

Perfil ideal e limites de uso do CLabel em MQL5

Se o seu dia a dia envolve scripts que precisam exibir informações ao vivo no gráfico – preço de break‑even, contagem de ticks ou mensagens de alerta – o CLabel pode ser seu melhor aliado. Caso contrário, ele será só mais um objeto pesado que ocupa memória sem agregar valor.

Quem realmente tira proveito

• Desenvolvedores de indicadores avançados: quem cria dashboards customizados dentro do MetaTrader 5.
• Robôs de gestão de risco: a necessidade de mostrar margem disponível ou nível de stop‑loss em tempo real.
• Traders de alta frequência que monitoram múltiplas condições simultâneas e precisam de feedback visual imediato.

Quem deve evitar

• Iniciantes que mal sabem manipular objetos gráficos básicos.
• Estratégias que rodam exclusivamente em modo “headless” (sem visualização de gráfico).
• Sistemas que já usam bibliotecas de UI externas (por ex., Qt) e não precisam de sobreposição no chart.

Limitações práticas

O CLabel depende do thread gráfico. Em períodos de alta volatilidade, a atualização pode atrasar 30‑50 ms, suficiente para perder um ponto crítico. Também há um limite de cerca de 150 objetos simultâneos por chart; ultrapassar esse número gera exceções silenciosas.

FAQ contextual

Checklist rápido antes de decidir

• Precisa de texto visível no gráfico?
• O número total de objetos < 150?
• Seu algoritmo tolera latência de < 50 ms?
• Você tem domínio de CChartObject?

Parecer editorial

Em termos de custo‑benefício, o CLabel se destaca apenas quando a comunicação visual é parte central da lógica de decisão. Para estratégias puramente quantitativas, ele é supérfluo e pode até atrapalhar.

Se o seu projeto exige um painel de controle tático dentro do próprio chart, ele atende à expectativa: responsivo, personalizável e integrado ao Ecossistema MQL5. Caso contrário, dê preferência a logs em arquivo ou alarme sonoro.

Próximos passos: teste com um único label, monitore o EventSetTimer() para medir atraso, e só então aumente a contagem. Baixe o template oficial