Desenhos

• A partir da versão v4 , indicadores e estratégias podem criar objetos de desenho no gráfico.
• 2 tipos de desenhos suportados no momento são:
  • label (rótulo)
  • line (linha)
  • Nota: Desenhos criados no gráfico através de scripts não podem ser modificados usando o mouse como em desenhos nativos do gráfico.
• Essas funções permitem criar estudos mais sofisticados através de componentes visuais, por exemplo, pontos de pivot, linhas de suporte e resistência, linhas zig zag, e rótulos contendo texto dinâmicos, etc.
• A diferença para funções de plotagem (plot, plotshape, plotchar) é a de que as funções de desenho podem ser criadas em barras históricas e barras futuras, ou seja aonde ainda elas não existem.

• Desenhos são criados com as funções
  • label.new
  • line.new

• Apenas os parâmetros de coordenadas são obrigatórios.

//@version=4
study("My Script", overlay=true)
label.new(bar_index, high)

• O rótulo é criado com os parâmetros x=bar_index (o index da barra atual) e y=high (máxima do preço da barra atual). Quando uma nova barra é criada, um novo rótulo é criado em cima da nova barra.
• Rótulos ficam no gráfico a não ser que sejam explicitamente removidos usando a função:
  • label.delete
  • Ou até que o processo de “garbage collection” os removam.

• Nesta adaptação o rótulo plota as coordenadas:

//@version=4
study("My Script", overlay=true)
label.new(bar_index, high, style=label.style_none,
    text="x=" + tostring(bar_index) + "\n y=" + tostring(high))
<code javascript>
 
  * Neste exemplo style=label.style_none significa que o rótulo não terá uma coloração de fundo.
 
  * Neste próximo exemplo uma linha é criada
 
<code javascript>
//@version=4
study("My Script", overlay=true)
line.new(x1=bar_index[1], y1=low[1], x2=bar_index, y2=high)

• Objetos de desenhos são sujeitos a 2 funções que afetam o comportamento do script quando executado em tempo real
  • commit
  • rollback

• O seguinte script mostra o efeito de rollback.

//@version=4
study("My Script", overlay=true)
label.new(bar_index, high)

• Enquanto label.new criar um novo rótulo a cada nova iteração do script (quando o preço muda em gráfico de tempo real) - o rótulo mais recente (criado na iteração anterior) é automaticamente apagado por causa do rollback antes da próxima iteração.
• Apenas o último rótulo criado antes da barra de tempo real fechar será commited e portanto persistirá no gráfico.

• Os desenhos são posicionados no gráfico seguindo 4 coordenadas
  • (x, y, xloc, yloc)
    • x = coordenada x - eixo horizontal
    • y = coordenada y - eixo vertical
  • xloc
    • xloc = xloc.bar_index - x é esperado como um index de uma barra
      • Pode usar bar_index
    • xloc = xloc.bar_time - x é esperado como um horário no formato UNIX
      • Pode usar time , timenow …
  • yloc
    • yloc = yloc.price - y é esperado como um valor de preço
    • yloc = yloc.abovebar ou yloc.belowbar - neste caso y é ignorado

//@version=4
study("My Script", overlay=true)
if barstate.islast
    label.new(timenow, close, xloc=xloc.bar_time)

• Este script posiciona um objeto rótulo no futuro.

• x-location funciona da mesma forma para rótulos e linhas.
• y-location é diferente para rótulos e linhas.
  • Para linhas yloc.price é sempre usado
    • portanto essa coordenada é sempre um preço absoluto.
  • Para rótulos há valores adicionais yloc.abovebar e yloc.belowbar
    • Quando esses são usados o valor y é ignorado.

• Um objeto de desenho pode ser modificado após sua criação. As funções label.new e line.new retornam uma referência ao objetos criados (do tipo series label e series line respectivamente).
• Esta referência pode então ser usada como primeiro argumento nas funções:
  • label.set_*
  • line.set_*

//@version=4
study("My Script", overlay=true)
l = label.new(bar_index, na)
if close >= open
    label.set_text(l, "green")
    label.set_color(l, color.green)
    label.set_yloc(l, yloc.belowbar)
    label.set_style(l, label.style_labelup)
else
    label.set_text(l, "red")
    label.set_color(l, color.red)
    label.set_yloc(l, yloc.abovebar)
    label.set_style(l, label.style_labeldown)

• Este script cria um rótulo na barra atual e então grava uma referência para este rótulo na variável l. Então, dependendo da barra (baseado na condição de close >= open) as propriedades do rótulo são modificadas : texto, cor, coordenada y e estilo do rótulo.
• Nota: na é passado como o argumento para a função label.new. Isto é porque neste exemplo o rótulo usa yloc.belowbar ou yloc.abovebar - que não requerem um valor y. Um valor absoluto y somente é requerido quando o rótulo usa yloc.price.

• Argumentos para função de rótulo:
  • label.set_color - altera a cor do rótulo.
  • label.set_size - altera o tamanho do rótulo.
  • label.set_style - altera o estilo do rótulo.
  • label.set_text - altera o texto do rótulo.
  • label.set_textcolor - altera a cor do texto do rótulo.
  • label.set_x - altera a coordenada x do rótulo.
  • label.set_y - altera a coordenada y do rótulo.
  • label.set_xy - altera as coordenadas de ambas coordenadas x e y do rótulo.
  • label.set_xloc - altera o parâmetro x-location do rótulo.
  • label.set_yloc - altera o parâmetro y-location do rótulo.
  • label.set_tooltp - altera a caixa de dica do rótulo.

• Argumentos para função de linha:
• line.set_color - altera a cor da linha.
• line.set_extend - altera o atributo extensão da linha.
  • extend.none - um segmento de linha.
  • extend.left - estende a linha para esquerda.
  • extend.right - estende a linha para direita.
  • extend.both - estende a linha para esquerda e para direita.
    • line.set_style - altera o estilo da linha.
    • line.set_width - altera o comprimento da linha.
    • line_set_xloc - altera o parâmetro x-location da linha (ambos x1 e x2).
    • line.set_x1 - altera a coordenada x1 da linha.
    • line.set_y1 - altera a coordenada y1 da linha.
    • line.set_xy1 - altera ambas coordenadas x1 e y1 da linha.
    • line.set_x2 - altera a coordenada x2 da linha.
    • line.set_y2 - altera a coordenada y2 da linha.
    • line.set_xy2 - altera ambas coordenadas x2 e y2 da linha.

• Estilos que podem ser aplicados tanto nas funções label.new e label.set_style para o rótulo.

• Estilos que podem ser aplicados tanto nas funções line.new e line.set_style para o rótulo.

• As funções label.delete e line.delete apagam rótulos e linhas do gráfico.
• Neste exemplo vemos um rótulo desenhado na barra atual e rótulos de barras antigas sendo apagadas.

//@version=4
study("Last Bar Close 1", overlay=true)
 
c = close >= open ? color.lime : color.red
l = label.new(bar_index, na,
  text=tostring(close), color=c,
  style=label.style_labeldown, yloc=yloc.abovebar)
 
label.delete(l[1])

• Em cada atualização de uma nova barra - um novo objeto é criado e gravado na variável l do tipo series label, portanto o operador [ ] é usado para retornar o rótulo do objeto da barra anterior. Este rótulo anterior é então passado para a função label.delete para ser apagado.
• As funções label.delete e line.delete não fazem nada caso um valor na é usado com um id o que faz o seguinte código desnecessário.

if not na(l[1])
    label.delete(l[1])

• O script antigo pode ser reproduzido da seguinte forma:

//@version=4
study("Last Bar Close 2", overlay=true)
 
var label l = na
label.delete(l)
c = close >= open ? color.lime : color.red
l := label.new(bar_index, na,
  text=tostring(close), color=c,
  style=label.style_labeldown, yloc=yloc.abovebar)

• Quando o estudo recebe uma nova barra, a variável l ainda está referenciando o objeto de rótulo antigo criado na barra anterior. Este rótulo é apagado com a chamada de label.delete(l). Um novo rótulo é então criado e o seu id é gravado em l. Usando este formato não há necessidade de usar o operador [ ].

• Note que o uso da palavra-chave var cria a variável l e inicializa com o valor na apenas uma vez. label.delete(l) não teria um objeto para apagar se não fosse pelo fato de que l é incializada apenas uma vez.

• Há então uma outra forma de atingir o mesmo objetivo como nos dois scripts anteriores, desta vez modificando o rótulo ao invés de apagá-lo.

//@version=4
study("Last Bar Close 3", overlay=true)
 
var label l = label.new(bar_index, na,
  style=label.style_labeldown, yloc=yloc.abovebar)
 
c = close >= open ? color.lime : color.red
label.set_color(l, c)
label.set_text(l, tostring(close))
label.set_x(l, bar_index)

• Nota: o uso da palavra-chave var é essencial. É o que permite a função label.new ser chamada e executada apenas uma vez na primeira barra histórica.

• Desenhar objetos de desenho consomem recursos do servidor e é por isso que existe um limite de desenhos por estudo ou estratégia (study ou strategy).
• Quando muitos desenhos são criados, desenhos antigos são automaticamente apagados durante a execução em um processo chamado como “garbage collection” (coleta de lixo).
• Este código desenha um rótulo em cada barra, rolando a barra para a esquerda você notará que não haverão rótulos desenhados a partir de 50 barras.

//@version=4
study("My Script", overlay=true)
label.new(bar_index, high)

• Você pode alterar o limite entre 1 a 500 usando os parâmetros max_lines_count e max_labels_count para estudos ou estratégias.

//@version=4
study("My Script", overlay=true, max_labels_count=100)
label.new(bar_index, high)

• Funções de desenho podem apenas ser usadas no ativo do gráfico principal.

• max_bars_back
  • O uso de barstate.isrealtime em combinação com desenhos pode as vezes produzir resultados inesperados. Por exemplo este código tenta ignorar barras históricas e criar rótulos em barras de tempo real:

//@version=4
study("My Script", overlay=true)
 
if barstate.isrealtime
   label.new(bar_index[10], na, text="Label", yloc=yloc.abovebar)

• Porém irá falhar durante execução. O editor Pine não consegue determinar o tamanho do buffer para valores históricos da plotagem time, mesmo que time não esteja sendo explicitamente mencionado no código.
• Isto acontece porque a variável nativa bar_index usa a série time dentro da sua construção. Acessando o valor de bar_index 10 barras no passado requer que o tamanho do buffer histórico da série time seja do tamanho 10 ou maior.
• Em Pine há um mecanismo que automaticamente detecta o tamanho histórico do buffer na maioria das vezes.
• Autodetecção funciona deixando o script Pine acessar valores históricos qualquer número de barras no passado por uma duração limitada. Neste script, if barstate.isrealtime previne o acesso ocorra então o tamanho histórico do buffer não pode ser inferido e o código falha.
• A solução é usar a função max_bar_back para explicitamente configurar o tamanho histórico do buffer para a series time.

//@version=4
study("My Script", overlay=true)
 
max_bars_back(time, 10)
 
if barstate.isrealtime
    label.new(bar_index[10], na, text="Label", yloc=yloc.abovebar)

• Essas ocorrências são raras mas podem acontecer.