Executa assim que a cena é colocada no ar.

public sub OnOnline(Engine As xpEngine, Self As xpScene)

Executa antes de a cena ser preparada para ir ao ar ou ao preview. Bom lugar para preencher textos e dados.

public sub OnPrepare(Engine As xpEngine, Self As xpScene)

Executa antes de a cena ir ao ar e antes de um item existente no framebuffer sair do ar. Defina AbortSetOnline = True para cancelar a entrada no ar.

public sub OnBeforeOnline(Engine As xpEngine, Self As xpScene, FramebufferIndex As Integer, Layer As Integer, ByRef AbortSetOnline As Boolean)

Executa logo antes de o item ser removido de um framebuffer. Handled permite que o script assuma a saída do ar.

public sub OnBeforeOffline(Engine As xpEngine, Self As xpScene, ByRef Handled As Boolean)

Executa depois que o item é removido de um framebuffer.

public sub OnOffline(Engine As xpEngine, Self As xpScene)

Executa a cada frame renderizado, inclusive no preview. Type indica se é online, preview ou NLE. Mantenha o código muito rápido: roda uma vez por campo/frame.

public sub OnRender(Engine As xpEngine, Self As xpScene, FieldNumber As Integer, Type As RenderType)

Executa cada vez que a cena é renderizada no preview.

public sub OnPreviewRender(Engine As xpEngine, Self As xpScene, FieldNumber As Integer)

Executa quando a cena está sendo exportada para vídeo ou imagens a partir do sequencer.

public sub OnExport(Engine As xpEngine, Self As xpScene)

Executa quando esta cena está no ar e outra cena é colocada no ar em outra camada.

public sub OnSceneOnline(Engine As xpEngine, Self As xpScene, OnlineScene As xpScene)

Executa quando esta cena está no ar e outra cena é removida de outra camada.

public sub OnSceneOffline(Engine As xpEngine, Self As xpScene, OfflineScene As xpScene)

Executa quando o scene director principal da cena muda de estado (PlayState: parado, pausado, tocando...).

public sub OnSceneDirectorState(Engine As xpEngine, Self As xpScene, State As PlayState)

Comando CII para carregar um projeto. FileName pode ser alterado. Defina Handled = True se o próprio script fez o carregamento.

public sub OnLoadProject(Engine As xpEngine, ByRef FileName As String, ByRef Handled As Boolean)

Gravação de página CII: cria ou atualiza um take item (TakeItemID) a partir da cena SceneID com os campos Values(). Todos podem ser alterados.

public sub OnPageWrite(Engine As xpEngine, ByRef SceneID As Integer, ByRef TakeItemID As Integer, ByRef Values() As String, ByRef Handled As Boolean)

Leitura/recall de página CII: chama o take item TakeItemID no canal Channel.

public sub OnPageRead(Engine As xpEngine, ByRef TakeItemID As Integer, ByRef Channel As Integer, ByRef Handled As Boolean)

Comando CII para tirar do ar o take item TakeItemID.

public sub OnSetOffline(Engine As xpEngine, ByRef TakeItemID As Integer, ByRef Handled As Boolean)

Comando CII para limpar o canal Channel.

public sub OnClear(Engine As xpEngine, ByRef Channel As Integer, ByRef Handled As Boolean)

Roda quando o atalho, GPI ou gatilho P-Bus mapeado é acionado. Só Engine é passado: obtenha as cenas por ele.

public sub OnKeyPress(Engine As xpEngine)

Roda quando o texto do objeto é definido (por um take item, Datalinq, API...). Altere Text para mudar o que é exibido.

public sub OnSetText(Engine As xpEngine, Scene As xpScene, Self As xpTextObject, ByRef Text As String, ByRef Handled As Boolean)

Roda quando um texto é acrescentado ao objeto. Text é o trecho sendo adicionado.

public sub OnAddText(Engine As xpEngine, Scene As xpScene, Self As xpTextObject, ByRef Text As String, ByRef Handled As Boolean)

Roda quando uma única linha (LineIndex) de um texto multilinha é definida.

public sub OnSetLine(Engine As xpEngine, Scene As xpScene, Self As xpTextObject, LineIndex As Integer, ByRef Text As String, ByRef Handled As Boolean)

Roda quando o event marker é exibido (alcançado) durante a renderização da cena.

public sub OnShow(Engine As xpEngine, Scene As xpScene)

Roda quando o event marker é ocultado.

public sub OnHide(Engine As xpEngine, Scene As xpScene)

Roda quando a agulha do Scene Director alcança o script event.

public sub OnEvent(Engine As xpEngine, Scene As xpScene)

Condição de regra de Transition Logic: defina Result = True quando a regra deve valer para OtherScene.

public sub OnTransLogic(Engine As xpEngine, Scene As xpScene, OtherScene As xpScene, ByRef Result As Boolean)

' Roda toda vez que o texto é definido
Text = UCase(Trim(Text))

If IsNumeric(Text) Then
    Text = Format(CDbl(Text), "#,##0.00")
End If

Dim obj As xpBaseObject = Nothing
If Self.GetObjectByName("Clock", obj) Then
    Dim txt As xpTextObject = CType(obj, xpTextObject)
    txt.Text = Format(Now, "HH:mm")
End If

Dim obj As xpBaseObject = Nothing
If Self.GetObjectByName("Name", obj) Then
    If Trim(CType(obj, xpTextObject).Text) = "" Then
        AbortSetOnline = True
        Engine.DebugMessage("Nome vazio: " & Self.Name, MessageType.mt_Warning)
    End If
End If

' _Global (xpGlobal) é um dicionário compartilhado por todos os scripts
Dim n As Integer = 0
If _Global.KeyExists("takes") Then n = CInt(_Global.Value("takes"))
n += 1
_Global.Value("takes") = n
Engine.WriteToLog("Cena " & Self.Name & " foi ao ar " & CStr(n) & " vezes")

Dim path As String = "C:\dados\manchete.txt"
If System.IO.File.Exists(path) Then
    Text = System.IO.File.ReadAllText(path, System.Text.Encoding.UTF8)
End If

Try
    Dim doc As New XmlDocument()
    doc.Load("C:\dados\placar.xml")
    Dim node As XmlNode = doc.SelectSingleNode("/placar/casa")
    If node IsNot Nothing Then Text = node.InnerText
Catch ex As Exception
    Engine.DebugMessage("Erro no XML: " & ex.Message, MessageType.mt_Error)
End Try

Dim dir As xpSceneDirector = Nothing
If Self.GetSceneDirectorByName("Loop", dir) Then
    dir.Play()
End If

Dim sc As xpScene = Nothing
If Engine.GetSceneByName("Bug", sc) Then
    sc.SetOnline(0, 10)
Else
    Engine.DebugMessage("Cena 'Bug' não encontrada", MessageType.mt_Error)
End If

Result = (OtherScene.Name = "Lower Third")

' OnRender roda a cada frame: faça o mínimo possível
If Type <> RenderType.rt_Online Then Exit Sub
Dim s As String = Format(Now, "HH:mm:ss")
If CStr(_Global.Value("lastClock")) <> s Then
    _Global.Value("lastClock") = s
    Dim obj As xpBaseObject = Nothing
    If Self.GetObjectByName("Clock", obj) Then CType(obj, xpTextObject).Text = s
End If

' Option Strict está Off, então late binding em Object funciona
Dim fso As Object = CreateObject("Scripting.FileSystemObject")
If fso.FolderExists("C:\dados") Then
    Text = CStr(fso.GetFolder("C:\dados").Files.Count) & " arquivos"
End If

' Junta espaços repetidos e remove tudo entre [colchetes]
Text = System.Text.RegularExpressions.Regex.Replace(Text, "\[[^\]]*\]", "")
Text = System.Text.RegularExpressions.Regex.Replace(Text, "\s{2,}", " ").Trim()

Engine.WriteToLog("CII write: cena " & CStr(SceneID) & " item " & CStr(TakeItemID) & " campos " & CStr(UBound(Values) + 1))
For i As Integer = 0 To UBound(Values)
    Values(i) = Trim(Values(i))
Next
' Deixe Handled = False para o XPression ainda criar o take item

' Scripting > Global Methods: viram membros da classe xp.xpc
Public Shared Function IsLong(ByVal s As String) As Boolean
    Return Len(s) > 20
End Function

Public Shared Function LongNames(ByVal names As System.Collections.Generic.List(Of String)) As System.Collections.Generic.List(Of String)
    ' VB 8 não tem lambdas: passe uma função nomeada com AddressOf
    Return names.FindAll(AddressOf IsLong)
End Function

Retorna o código (Integer) do primeiro caractere de uma String ou de um Char, usando a página de código ANSI atual. Lança ArgumentException para string vazia; use AscW para obter o code point Unicode.

Asc("A")  ' 65

Retorna o code point Unicode (Integer) do primeiro caractere de uma String ou de um Char, independentemente da página de código do sistema. Lança ArgumentException para string vazia.

AscW("é")  ' 233

Retorna o Char correspondente a um código de caractere; códigos de 0 a 255 são interpretados pela página de código ANSI atual. Prefira ChrW para valores Unicode ou as constantes vbCr, vbLf e vbCrLf para quebras de linha.

Chr(65)  ' "A"c

Retorna o Char correspondente a um code point Unicode (-32768 a 65535), sem depender da página de código do sistema. Útil para símbolos como setas, marcadores ou letras acentuadas em campos de texto.

ChrW(8226)  ' "•"c (bullet)

Retorna um array de String (base 0) com os elementos de Source que contêm a substring Match (ou que não a contêm quando Include é False). Compare escolhe comparação binária (diferencia maiúsculas) ou textual (não diferencia).

Filter(New String() {"CAM1", "CAM2", "VT1"}, "CAM")  ' {"CAM1", "CAM2"}

Formata um número ou data como string usando um formato nomeado ("Currency", "Percent", "Short Date", "Long Time"...) ou uma string de formato .NET/VB personalizada como "0.00" ou "dd/MM/yyyy HH:mm". O resultado segue as configurações regionais atuais (separadores decimais e de data), então o mesmo código pode gerar textos diferentes em máquinas com culturas diferentes.

Format(Now, "HH:mm:ss")  ' e.g. "14:05:09"

Formata um valor numérico como moeda usando o símbolo monetário e as configurações regionais do sistema; NumDigitsAfterDecimal define as casas decimais (-1 = padrão regional) e os argumentos TriState controlam o zero à esquerda, parênteses para negativos e agrupamento de dígitos.

FormatCurrency(1234.5)  ' "R$ 1.234,50" (pt-BR) / "$1,234.50" (en-US)

Formata um Date usando um dos valores de DateFormat: GeneralDate (padrão), LongDate, ShortDate, LongTime ou ShortTime, conforme as configurações regionais. Use Format para padrões personalizados.

FormatDateTime(Now, DateFormat.ShortTime)  ' e.g. "14:05"

Formata um valor numérico com o número de casas decimais indicado (-1 = padrão regional) e agrupamento de dígitos opcional, usando os separadores decimal e de milhar regionais. O valor é arredondado, não truncado.

FormatNumber(1234.567, 2)  ' "1,234.57" (en-US) / "1.234,57" (pt-BR)

Multiplica o valor por 100 e o formata com o sinal % no final, usando o número de casas decimais indicado (-1 = padrão regional). Passe a fração (0.25), não a porcentagem (25).

FormatPercent(0.256, 1)  ' "25.6%"

Retorna o Char na posição Index (base 1) da string. Lança ArgumentException se Index for menor que 1 ou maior que o comprimento.

GetChar("XPression", 2)  ' "P"c

Retorna a posição (base 1) da primeira ocorrência de String2 dentro de String1, ou 0 se não encontrar; o argumento opcional Start (também base 1) define onde a busca começa. Atenção: é base 1, ao contrário de String.IndexOf, que é base 0 e retorna -1.

InStr("XPression", "ss")  ' 5

Procura StringMatch do fim de StringCheck para o início e retorna sua posição (base 1) contada a partir do começo, ou 0 se não encontrar. Start = -1 (padrão) começa pelo último caractere.

InStrRev("C:\Clips\intro.mov", "\")  ' 9

Concatena os elementos de um array unidimensional em uma única string, separados por Delimiter (um espaço por padrão). Passe "" como Delimiter para juntar sem separador.

Join(New String() {"A", "B", "C"}, ", ")  ' "A, B, C"

Retorna a String ou o Char convertido para minúsculas usando a cultura atual. Nothing é retornado como string vazia.

LCase("XPression")  ' "xpression"

Retorna os Length caracteres mais à esquerda de uma string; se Length for maior que o tamanho da string, retorna a string inteira (sem erro). Dentro de uma classe que tenha sua própria propriedade Left, chame como Microsoft.VisualBasic.Left.

Left("XPression", 2)  ' "XP"

Para String, retorna o número de caracteres (0 para Nothing); para outros tipos, retorna o número de bytes necessários para armazenar o valor (ex.: 4 para Integer, 8 para Double). Para texto, equivale à propriedade String.Length, mas sem erro quando o valor é Nothing.

Len("XPression")  ' 9

Retorna Source alinhado à esquerda em uma string de exatamente Length caracteres, completada com espaços à direita ou truncada se for maior. Útil para colunas de largura fixa.

LSet("AB", 5) & "|"  ' "AB   |"

Retorna a string sem os espaços iniciais. Remove apenas espaços (não tabulações nem quebras de linha); use String.TrimStart() para outros caracteres em branco.

LTrim("   Hello")  ' "Hello"

Retorna uma substring a partir da posição Start (base 1), com Length caracteres ou até o fim se Length for omitido; retorna "" se Start passar do fim. Lembre-se de que é base 1 (String.Substring é base 0).

Mid("XPression", 3, 5)  ' "ressi"

Retorna uma cópia de Expression com as ocorrências de Find trocadas por Replacement; Count limita a quantidade de trocas (-1 = todas) e Compare define se diferencia maiúsculas. Atenção: quando Start é maior que 1, a string retornada começa na posição Start (os caracteres anteriores são descartados).

Replace("1-2-3", "-", "/")  ' "1/2/3"

Retorna os Length caracteres mais à direita de uma string; se Length for maior que o tamanho da string, retorna a string inteira. Dentro de uma classe que tenha sua própria propriedade Right, chame como Microsoft.VisualBasic.Right.

Right("Clip_0042", 4)  ' "0042"

Retorna Source alinhado à direita em uma string de exatamente Length caracteres, completada com espaços à esquerda ou truncada se for maior. Útil para alinhar números em texto de largura fixa.

RSet("42", 5)  ' "   42"

Retorna a string sem os espaços finais. Remove apenas espaços; use String.TrimEnd() para tabulações ou quebras de linha.

RTrim("Hello   ")  ' "Hello"

Retorna uma string composta pelo número especificado de espaços. Útil para preencher ou alinhar texto.

"[" & Space(3) & "]"  ' "[   ]"

Divide Expression em um array de String (base 0) usando Delimiter (espaço por padrão; a string delimitadora inteira é usada, não caracteres isolados); Limit restringe o número de elementos (-1 = todos). Uma entrada vazia retorna um array com um único elemento "".

Split("Ana;Bia;Caio", ";")(1)  ' "Bia"

Compara duas strings e retorna -1 se String1 vier antes de String2, 0 se forem iguais ou 1 se vier depois. Use CompareMethod.Text para comparação sem diferenciar maiúsculas de minúsculas.

StrComp("abc", "ABC", CompareMethod.Text)  ' 0

Converte uma string conforme um valor de VbStrConv, como UpperCase, LowerCase, ProperCase (inicial maiúscula em cada palavra), Wide/Narrow ou Katakana/Hiragana. LocaleID define opcionalmente a cultura usada na conversão.

StrConv("joão da silva", VbStrConv.ProperCase)  ' "João Da Silva"

Retorna uma string formada pelo primeiro caractere de Character repetido Number vezes. Apenas o primeiro caractere é usado, mesmo que uma string maior seja passada.

StrDup(5, "-")  ' "-----"

Retorna a string com os caracteres em ordem inversa. Retorna "" para Nothing ou string vazia.

StrReverse("ABC")  ' "CBA"

Retorna a string sem os espaços do início e do fim. Remove apenas espaços; use String.Trim() para remover também tabulações e quebras de linha (por exemplo, em dados lidos de arquivos).

Trim("  Score  ")  ' "Score"

Retorna a String ou o Char convertido para maiúsculas usando a cultura atual. Nothing é retornado como string vazia.

UCase("breaking news")  ' "BREAKING NEWS"

Retorna a mensagem de erro de um número de erro de tempo de execução do VB; sem argumentos, retorna a mensagem do erro mais recente (Err.Number). Retorna "" quando o número é 0.

ErrorToString(11)  ' "Division by zero."

Remove a parte fracionária de um número, truncando em direção a zero, e retorna o mesmo tipo numérico. Difere de Int para negativos: Fix(-8.4) = -8, enquanto Int(-8.4) = -9.

Fix(-8.4)  ' -8

Retorna uma string com a representação hexadecimal de um valor inteiro (sem o prefixo "&H"). Números negativos aparecem em complemento de dois, por exemplo Hex(-1) = "FFFFFFFF".

Hex(255)  ' "FF"

Retorna a parte inteira de um número, arredondando para baixo em direção ao infinito negativo (piso), mantendo o mesmo tipo numérico (um Double continua Double). Envolva com CInt se precisar de um Integer.

Int(-8.4)  ' -9

Retorna uma string com a representação octal de um valor inteiro (sem o prefixo "&O"). Números negativos aparecem em complemento de dois.

Oct(8)  ' "10"

Converte um número em string usando a cultura invariante (ponto como separador decimal). Atenção: números positivos ganham um espaço inicial reservado para o sinal; use Trim(Str(x)), CStr ou ToString quando não quiser esse espaço.

Str(42)  ' " 42"

Interpreta os números no início de uma string e retorna um Double, ignorando espaços e parando no primeiro caractere que não consegue interpretar; não depende da cultura (apenas "." é separador decimal) e aceita os prefixos &H/&O. Retorna 0 se não houver nada numérico, sem lançar erro para texto inválido.

Val("12.5 km")  ' 12.5

Retorna um Date ao qual foi somado um número de intervalos (use Number negativo para subtrair). O intervalo é um valor de DateInterval ou uma string: "yyyy" ano, "q" trimestre, "m" mês, "ww" semana, "d" dia, "h" hora, "n" minuto (não "m"!), "s" segundo.

DateAdd(DateInterval.Minute, 90, Now)  ' now + 1h30

Retorna um Long com o número de limites de intervalo entre Date1 e Date2 (positivo quando Date2 é posterior). Interval usa o enum DateInterval ou as mesmas strings de DateAdd ("d", "h", "n", "s"...); note que conta limites cruzados, então DateDiff("yyyy") entre 31/12 e 01/01 dá 1.

DateDiff(DateInterval.Second, startTime, Now)  ' elapsed seconds

Retorna um Integer com o componente pedido de uma data (ano, trimestre, mês, semana do ano, dia da semana, hora...), escolhido por um valor de DateInterval ou string de intervalo. Os argumentos opcionais definem o primeiro dia da semana e a primeira semana do ano.

DatePart(DateInterval.Quarter, #8/15/2007#)  ' 3

Monta um Date (hora 00:00:00) a partir dos números de ano, mês e dia. Valores fora da faixa são ajustados, então o mês 13 vira janeiro do ano seguinte e o dia 0 é o último dia do mês anterior.

DateSerial(2024, 3, 0)  ' #2/29/2024#

Retorna a data atual como string, sempre no formato "MM-dd-yyyy" (mês primeiro), independentemente das configurações regionais. Atribuir um valor a ela altera a data do sistema; use Format(Today, ...) para exibição.

DateString  ' e.g. "12-31-2024"

Converte uma string em um Date contendo apenas a parte de data (a informação de hora é descartada). A string é interpretada pelas configurações regionais atuais, então "01/02/2024" pode significar 2 de janeiro ou 1º de fevereiro.

DateValue("2024-12-31")  ' #12/31/2024#

Retorna o dia do mês (1 a 31) de um Date como Integer.

Day(#12/25/2024#)  ' 25

Retorna a hora (0 a 23) de um Date como Integer.

Hour(#2:30:00 PM#)  ' 14

Retorna o minuto (0 a 59) de um Date como Integer.

Minute(#2:30:00 PM#)  ' 30

Retorna o mês (1 a 12) de um Date como Integer.

Month(#12/25/2024#)  ' 12

Retorna o nome de um mês (1 a 12) no idioma da cultura atual, opcionalmente abreviado. Em um sistema pt-BR os nomes saem em português ("janeiro").

MonthName(1, True)  ' "Jan" (en-US)

Retorna um Date com a data e a hora atuais do sistema (hora local). Fonte típica para relógios e carimbos de data/hora em grafismos.

Format(Now, "HH:mm")  ' e.g. "14:05"

Retorna o segundo (0 a 59) de um Date como Integer.

Second(#2:30:15 PM#)  ' 15

Retorna um Date com a hora atual do dia (parte de data 1º de janeiro do ano 1). Atribuir um valor a ela altera o relógio do sistema, o que não deve ser feito em um script.

Hour(TimeOfDay)  ' current hour

Retorna um Double com o número de segundos (com frações) decorridos desde a meia-noite. Útil para medições simples de tempo decorrido, mas volta a 0 à meia-noite.

Dim elapsed As Double = Timer - t0  ' seconds since t0 = Timer

Monta um Date contendo apenas uma hora do dia a partir dos números de hora, minuto e segundo (a parte de data é 1º de janeiro do ano 1). Valores fora da faixa são ajustados, por exemplo 90 minutos vira 1 h 30 min.

TimeSerial(14, 30, 0)  ' 2:30:00 PM

Retorna a hora atual como string, sempre no formato de 24 horas "HH:mm:ss", independentemente das configurações regionais. Atribuir um valor a ela altera o relógio do sistema.

TimeString  ' e.g. "14:05:09"

Converte uma string em um Date contendo apenas a parte de hora (a parte de data é 1º de janeiro do ano 1). Aceita formatos como "14:30" ou "2:30 PM".

TimeValue("14:30:15")  ' 2:30:15 PM

Retorna a data atual do sistema com a hora zerada (00:00:00). Também é uma propriedade gravável que altera a data do sistema, o que nunca deve ser feito a partir de um script.

Format(Today, "dd/MM/yyyy")

Retorna o dia da semana como Integer de 1 a 7, onde 1 é o dia indicado por DayOfWeek (domingo por padrão). Passe FirstDayOfWeek.Monday para que segunda-feira seja 1.

Weekday(#12/25/2024#)  ' 4 (Wednesday)

Retorna o nome de um dia da semana (1 a 7) no idioma da cultura atual, opcionalmente abreviado. A numeração depende de FirstDayOfWeekValue, que por padrão segue a configuração do sistema; passe FirstDayOfWeek.Sunday para resultados previsíveis.

WeekdayName(Weekday(Today), False, FirstDayOfWeek.Sunday)  ' e.g. "Monday"

Retorna o ano (1 a 9999) de um Date como Integer.

Year(Today)  ' e.g. 2024

Traz para o primeiro plano a janela de um aplicativo já em execução, identificada pelo título da janela ou pelo ID do processo (por exemplo, o valor retornado por Shell). Lança ArgumentException se nenhuma janela correspondente for encontrada.

AppActivate("Untitled - Notepad")

Toca o bipe padrão do sistema pelo dispositivo de som do computador. Em uma máquina de exibição isso pode ser audível em uma saída de áudio, então use apenas para depuração.

Beep()

Lê ou define uma propriedade, ou chama um método, de um objeto usando o nome como string em tempo de execução; UseCallType é CallType.Get, Let, Set ou Method, e Args contém os argumentos. Útil quando o nome do membro vem de dados, ao custo de desempenho e de verificação em tempo de compilação.

CallByName(obj, "Text", CallType.Let, "Hello")

Retorna o elemento da lista Choice na posição Index (base 1; frações são truncadas), ou Nothing se Index estiver fora da faixa. Todas as opções são avaliadas, e o resultado é um Object que pode precisar de CStr/CInt.

CStr(Choose(2, "Red", "Green", "Blue"))  ' "Green"

Retorna os argumentos de linha de comando do processo atual como uma única string (sem o nome do programa). No XPression, é a linha de comando usada para iniciar o próprio XPression.

Dim args As String = Command()

Cria e retorna uma nova instância de um objeto COM (ActiveX) pelo seu ProgID, opcionalmente em um servidor remoto; o resultado é de vinculação tardia (Object), então chamadas de membros exigem Option Strict Off. O componente COM precisa estar registrado na máquina do XPression.

Dim fso As Object = CreateObject("Scripting.FileSystemObject")

Exclui uma seção ou uma chave das configurações do aplicativo no registro do Windows (HKEY_CURRENT_USER\Software\VB and VBA Program Settings\AppName). Omitir Key exclui a seção inteira, e omitir Section exclui todas as configurações de AppName.

DeleteSetting("MyXPScripts", "Scores", "Home")

Retorna o valor de uma variável de ambiente do sistema operacional pelo nome, ou "" se ela não existir; com um índice numérico (base 1), retorna a string "NOME=valor" dessa entrada.

Environ("COMPUTERNAME")  ' e.g. "XPN-PLAYOUT1"

Retorna todas as chaves e valores de uma seção do registro salva com SaveSetting como um array bidimensional de String, em que (i, 0) é a chave e (i, 1) o valor. Retorna Nothing se a seção não existir.

Dim s(,) As String = GetAllSettings("MyXPScripts", "Scores")

Retorna uma referência a um objeto COM, carregado de um arquivo (PathName) ou a uma instância já em execução da classe indicada (Class). Assim como CreateObject, o resultado é de vinculação tardia.

Dim xl As Object = GetObject(, "Excel.Application")

Lê do registro um valor salvo com SaveSetting para o usuário atual do Windows, retornando Default ("" se omitido) quando a chave não existe. Prático para guardar pequenos valores entre sessões do XPression.

GetSetting("MyXPScripts", "Scores", "Home", "0")

Retorna TruePart se Expression for True, caso contrário FalsePart, como Object. Atenção: as duas partes são sempre avaliadas (sem curto-circuito), então IIf(x Is Nothing, "", x.Name) ainda falha quando x é Nothing; nesse caso use um bloco If...Else (o operador If() não existe no VB 8).

CStr(IIf(score >= 10, "WIN", "LOSE"))

Exibe uma caixa de diálogo modal pedindo que o usuário digite um texto e o retorna (ou "" se cancelar); Title, DefaultResponse e a posição são opcionais. Bloqueia a thread de renderização do XPression até ser fechada, então nunca use em scripts que rodam no ar.

Dim name As String = InputBox("Guest name:", "Lower third", "John Doe")

Exibe uma caixa de mensagem modal e retorna um MsgBoxResult indicando o botão clicado; Buttons combina flags de MsgBoxStyle (botões, ícone, botão padrão) e Title define o título. Bloqueia a thread de renderização do XPression até ser fechada, então use apenas em testes, nunca no ar.

If MsgBox("Clear all?", MsgBoxStyle.YesNo, "Confirm") = MsgBoxResult.Yes Then Reset()

Retorna uma string "inferior:superior" indicando qual faixa de tamanho Interval, entre Start e Stop, contém Number; os valores são completados com espaços à esquerda até a largura de Stop mais um. Usado principalmente para montar tabelas de frequência ou histogramas.

Partition(25, 0, 99, 10)  ' " 20: 29"

Grava um valor de string no registro do Windows em HKEY_CURRENT_USER\Software\VB and VBA Program Settings\AppName\Section\Key. O valor é por usuário do Windows, portanto não é compartilhado entre máquinas ou contas.

SaveSetting("MyXPScripts", "Scores", "Home", "3")

Inicia um programa externo e retorna o ID do processo; Style define o estilo da janela e Wait = True bloqueia até o programa terminar (ou até passar Timeout ms). No XPression, evite Wait = True e programas demorados, pois o script bloqueia a thread de renderização.

Shell("notepad.exe C:\temp\log.txt", AppWinStyle.NormalFocus)

Recebe pares (condição, valor) e retorna o valor do primeiro par cuja condição seja True, ou Nothing se nenhuma for. Todos os argumentos são avaliados, e o resultado é um Object.

CStr(Switch(x < 0, "neg", x = 0, "zero", True, "pos"))

Retorna o número da linha onde ocorreu o último erro, o que só funciona quando o código usa linhas numeradas; caso contrário, retorna 0.

Dim line As Integer = Erl()

Retorna o ErrObject com informações sobre o erro de tempo de execução mais recente (Number, Description, Source...). É preenchido pelo tratamento On Error e também quando uma exceção é capturada em um bloco Try...Catch.

If Err.Number <> 0 Then Engine.WriteToLog(Err.Description)

Retorna True se a variável referenciar um array. Retorna False para Nothing e para strings.

IsArray(New Integer() {1, 2})  ' True

Retorna True se a expressão for um Date ou uma string que possa ser convertida em Date pelas configurações regionais atuais. Use antes de CDate para evitar exceções de conversão.

IsDate("31/12/2024")  ' True on pt-BR, False on en-US

Retorna True se a expressão for DBNull.Value, o valor que representa um NULL de banco de dados (por exemplo, de um DataRow ou DataReader). Verifique antes de converter campos de banco de dados.

If IsDBNull(row("Score")) Then score = 0

Retorna True se a expressão for um objeto Exception. Mantida principalmente por compatibilidade com código VB6 que usava valores de erro.

IsError(New Exception("x"))  ' True

Retorna True se a expressão for Nothing (sem objeto atribuído). Equivale ao teste x Is Nothing.

If IsNothing(scene) Then Exit Sub

Retorna True se a expressão for um número ou uma string que possa ser convertida em número (pelas configurações regionais atuais, aceitando também os prefixos &H/&O). Use para validar texto antes de chamar CDbl ou CInt.

IsNumeric("12abc")  ' False

Retorna True se a expressão contiver um tipo por referência (String, arrays, instâncias de classes) e False para tipos por valor como Integer, Date ou estruturas.

IsReference("abc")  ' True

Retorna o menor índice disponível da dimensão indicada (Rank, base 1) de um array. No VB.NET os arrays sempre começam em 0, então normalmente o resultado é 0.

LBound(arr)  ' 0

Retorna o valor de cor RGB (Integer, &H00BBGGRR) de uma das 16 cores clássicas do QuickBASIC (0 a 15). O valor usa a ordem de bytes COM/OLE, não o ARGB de System.Drawing.Color; converta com ColorTranslator.FromOle se necessário.

QBColor(12)  ' &HFF (light red)

Retorna um valor de cor Integer montado a partir dos componentes vermelho, verde e azul (0 a 255), na ordem COM/OLE &H00BBGGRR (vermelho no byte menos significativo). Não é o mesmo que Color.FromArgb(...).ToArgb(); use ColorTranslator.FromOle para obter um System.Drawing.Color.

RGB(255, 0, 0)  ' 255

Converte um nome de tipo VB no nome do tipo .NET (CLR) correspondente, ou retorna Nothing se o nome não for um tipo elementar do VB.

SystemTypeName("Integer")  ' "System.Int32"

Retorna uma string com o nome VB do tipo de dado da variável, como "Integer", "String", "Double", "Integer()" para arrays ou "Nothing". Útil para depurar objetos de vinculação tardia.

TypeName(42)  ' "Integer"

Retorna o maior índice da dimensão indicada (Rank, base 1) de um array; para Dim a(5) retorna 5 (seis elementos). Retorna -1 para um array vazio e lança exceção para Nothing.

UBound(New String() {"A", "B", "C"})  ' 2

Retorna um valor de VariantType que identifica o tipo de dado da variável (ex.: VariantType.Integer, VariantType.String, VariantType.Date). Arrays combinam VariantType.Array com o tipo dos elementos.

VarType(3.5) = VariantType.Double  ' True

Converte um nome de tipo .NET (CLR) no nome de tipo VB correspondente, ou retorna Nothing se não houver equivalente em VB. Aceita nomes com ou sem o prefixo "System.".

VbTypeName("System.Int32")  ' "Integer"

Altera o diretório de trabalho atual. Isso afeta todo o processo do XPression (e os caminhos relativos em geral), então prefira trabalhar com caminhos absolutos.

ChDir("D:\Graphics")

Altera a unidade atual, usando a primeira letra da string ou do Char informado. Assim como ChDir, altera um estado global do processo.

ChDrive("D")

Retorna o caminho do diretório de trabalho atual, ou o diretório atual da letra de unidade informada.

CurDir()  ' e.g. "C:\Program Files\XPression"

Retorna o primeiro nome de arquivo ou pasta que corresponde a um padrão de caminho (curingas * e ?) e a Attributes; chamar Dir() de novo sem argumentos retorna a próxima correspondência, e "" quando não houver mais. Retorna apenas o nome (não o caminho completo), e o estado de busca compartilhado não é thread-safe.

Dim f As String = Dir("D:\Logos\*.png")

Retorna True quando o fim de um arquivo aberto para Input, Random ou Binary foi atingido. Use como condição de laço ao ler arquivos.

If EOF(fn) Then FileClose(fn)

Retorna o OpenMode (Input, Output, Append, Binary ou Random) com o qual um número de arquivo foi aberto por FileOpen.

FileAttr(fn) = OpenMode.Append  ' True

Fecha os arquivos abertos com FileOpen para os números de arquivo informados; sem argumentos, fecha todos. Arquivos não fechados ficam bloqueados pelo processo do XPression.

FileClose(fn)

Copia um arquivo de Source para Destination, sobrescrevendo o destino se existir. Falha se o arquivo de origem estiver aberto para gravação.

FileCopy("D:\data.xml", "D:\backup\data.xml")

Retorna a data e a hora em que o arquivo foi criado ou modificado pela última vez. Útil para detectar se um arquivo de dados mudou desde a última leitura.

FileDateTime("D:\scores.txt")

Lê dados de um arquivo aberto em modo Random ou Binary para a variável informada (passada ByRef), no RecordNumber (registro base 1 no modo Random, posição em bytes no modo Binary) ou na posição atual. Contraparte de FilePut.

Dim n As Integer : FileGet(fn, n, 1)

Lê um valor de um arquivo aberto em modo Random ou Binary para uma variável Object, no registro RecordNumber (base 1) ou na posição atual. Use no lugar de FileGet quando a variável for declarada As Object.

FileGetObject(fn, value, 1)

Retorna o tamanho de um arquivo em bytes como Long. Para um arquivo aberto com FileOpen, use LOF para obter o tamanho atualizado.

FileLen("D:\scores.txt")  ' e.g. 1024

Abre um arquivo para E/S no estilo VB, associando-o a um número de arquivo (obtenha um com FreeFile); Mode é OpenMode.Input, Output, Append, Binary ou Random, e Access, Share e RecordLength são opcionais. Sempre feche com FileClose, de preferência em um bloco Finally.

Dim fn As Integer = FreeFile() : FileOpen(fn, "D:\log.txt", OpenMode.Append)

Grava o valor de uma variável em um arquivo aberto em modo Random ou Binary, no RecordNumber (base 1) ou na posição atual. Os dados são gravados em formato binário, para serem lidos com FileGet.

FilePut(fn, 42, 1)

Grava um valor Object em um arquivo aberto em modo Random ou Binary, no RecordNumber ou na posição atual. Contraparte de FileGetObject.

FilePutObject(fn, CObj(42), 1)

Define a largura máxima de linha para saída em um arquivo aberto com FileOpen; Print/Write passam para nova linha quando ela é atingida. Largura 0 significa ilimitada.

FileWidth(fn, 80)

Retorna o próximo número de arquivo disponível para usar com FileOpen. Sempre use em vez de fixar números no código, pois outros scripts podem ter arquivos abertos.

Dim fn As Integer = FreeFile()

Retorna as flags de FileAttribute de um arquivo ou pasta (ReadOnly, Hidden, System, Directory, Archive...). Teste uma flag com And, por exemplo (GetAttr(p) And FileAttribute.Directory) <> 0.

(GetAttr("D:\Logos") And FileAttribute.Directory) <> 0  ' True

Lê um valor delimitado por vírgula de um arquivo aberto em modo Input para a variável informada (ByRef). Destinado a dados gravados com Write/WriteLine, que colocam strings entre aspas e delimitam os campos.

Dim s As String : Input(fn, s)

Lê CharCount caracteres de um arquivo aberto em modo Input ou Binary e os retorna como string, incluindo vírgulas, aspas e quebras de linha.

Dim all As String = InputString(fn, CInt(LOF(fn)))

Exclui um ou mais arquivos do disco; curingas (* e ?) são aceitos, então confira bem o padrão. Os arquivos excluídos não vão para a Lixeira.

Kill("D:\Temp\*.tmp")

Lê uma linha inteira de um arquivo aberto em modo Input e a retorna sem a quebra de linha final. Combine com EOF em um laço para ler arquivos de texto linha a linha.

Dim s As String = ""
Do Until EOF(fn)
    s = LineInput(fn)
Loop

Retorna a posição atual em um arquivo aberto: último registro lido/gravado no modo Random, último byte no modo Binary e a posição em bytes dividida por 128 em arquivos sequenciais.

Loc(fn)

Impede que outros processos acessem todo um arquivo aberto, um único registro ou um intervalo de registros (Random) / bytes (Binary). Cada Lock deve ter um Unlock correspondente com os mesmos argumentos.

Lock(fn, 1, 10)

Retorna o tamanho, em bytes, de um arquivo aberto com FileOpen. Reflete os dados já gravados na sessão atual, ao contrário de FileLen.

LOF(fn)  ' e.g. 2048

Cria um novo diretório. Lança IOException se o diretório já existir.

MkDir("D:\Export\Today")

Grava valores formatados para exibição em um arquivo aberto para Output ou Append, sem adicionar quebra de linha. Use TAB e SPC para posicionar a saída.

Print(fn, "Score: ", 10)

Grava valores formatados para exibição em um arquivo aberto para Output ou Append, seguidos de uma quebra de linha. A forma mais simples de gravar uma linha de log em texto.

PrintLine(fn, Format(Now, "HH:mm:ss") & " take OK")

Renomeia um arquivo ou diretório; se o novo caminho estiver em outra pasta da mesma unidade, o arquivo é movido. Lança exceção se NewPath já existir.

Rename("D:\data.txt", "D:\data_old.txt")

Fecha todos os arquivos abertos com FileOpen e descarrega seus buffers. Equivale a chamar FileClose sem argumentos.

Reset()

Remove um diretório existente, que precisa estar vazio. Exclua os arquivos antes com Kill.

RmDir("D:\Export\Old")

Sem Position, retorna a posição atual de leitura/gravação de um arquivo aberto; com Position, define essa posição. As posições são base 1: posição em bytes nos modos Binary/sequencial e número do registro no modo Random.

Seek(fn, 1)  ' rewind

Define as flags de FileAttribute de um arquivo, como ReadOnly ou Hidden; combine flags com Or. Use FileAttribute.Normal para limpá-las.

SetAttr("D:\data.xml", FileAttribute.ReadOnly)

Usado dentro de Print/PrintLine para inserir Count espaços na saída. Prático para alinhamento simples de texto.

PrintLine(fn, "A", SPC(5), "B")

Usado dentro de Print/PrintLine para mover a saída para uma coluna (base 1); sem argumento, move para a próxima zona de impressão (a cada 14 colunas).

PrintLine(fn, "Name", TAB(20), "Score")

Libera um bloqueio aplicado antes com Lock em um arquivo inteiro, um registro ou um intervalo de registros. Os argumentos devem coincidir com a chamada de Lock original.

Unlock(fn, 1, 10)

Grava valores em um arquivo sequencial como campos separados por vírgula, com strings entre aspas e datas como #yyyy-MM-dd#, sem quebra de linha. A saída foi feita para ser lida de volta com Input.

Write(fn, "Home", 3)

Assim como Write, grava valores separados por vírgula e entre aspas em um arquivo sequencial, mas termina com uma quebra de linha. Gera registros simples, parecidos com CSV, legíveis com Input.

WriteLine(fn, "Home", 3)  ' "Home",3

Retorna a depreciação de um ativo em um período pelo método de saldo decrescente duplo (ou outra taxa via Factor). Cost, Salvage, Life e Period devem usar unidades coerentes.

DDB(10000, 1000, 5, 1)  ' 4000

Retorna o valor futuro de um investimento com pagamentos periódicos constantes e taxa de juros Rate constante por período. Valores pagos são negativos e recebidos são positivos; Due define pagamentos no fim ou no início de cada período.

FV(0.01, 12, -100)  ' ≈ 1268.25

Retorna a parcela de juros do pagamento do período Per de um empréstimo ou anuidade com pagamentos e taxa constantes. Usa a mesma convenção de sinais de Pmt.

IPmt(0.01, 1, 12, 1000)  ' -10

Retorna a taxa interna de retorno de uma série de fluxos de caixa periódicos em um array de Double, que deve conter pelo menos um valor negativo (pagamento) e um positivo (recebimento). Guess é a estimativa inicial do cálculo iterativo.

Dim cf() As Double = {-1000, 300, 400, 500} : IRR(cf)  ' ≈ 0.089

Retorna a taxa interna de retorno modificada de uma série de fluxos de caixa, usando FinanceRate para o custo dos pagamentos e ReinvestRate para os recebimentos reinvestidos. O array precisa ter valores negativos e positivos.

MIRR(cf, 0.1, 0.12)

Retorna o número de períodos necessários para que um investimento ou empréstimo com pagamentos constantes Pmt e taxa Rate atinja o valor futuro indicado. Usa a convenção de sinais habitual (pagamentos negativos).

NPer(0.01, -100, 1000)  ' ≈ 10.59

Retorna o valor presente líquido de uma série de fluxos de caixa futuros (array de Double) descontados à taxa Rate. O primeiro valor é descontado um período inteiro, então some o investimento inicial separadamente.

Dim f() As Double = {300, 400, 500} : NPV(0.1, f)  ' ≈ 978.96

Retorna o pagamento constante por período de um empréstimo ou anuidade, dados a taxa por período, o número de períodos e o valor presente. O resultado é negativo para valores pagos; divida uma taxa anual por 12 para pagamentos mensais.

Pmt(0.01, 12, 1000)  ' ≈ -88.85

Retorna a parcela de amortização do principal no período Per de um empréstimo ou anuidade com pagamentos e taxa constantes. IPmt + PPmt é igual a Pmt em cada período.

PPmt(0.01, 1, 12, 1000)  ' ≈ -78.85

Retorna o valor presente de uma série de pagamentos futuros constantes a uma taxa constante por período. Usa a convenção de sinais habitual (pagamentos negativos).

PV(0.01, 12, -100)  ' ≈ 1125.51

Retorna a taxa de juros por período de uma anuidade, calculada de forma iterativa a partir do número de períodos, do pagamento e do valor presente. Lança exceção se o cálculo não convergir; tente outro Guess.

Rate(12, -88.85, 1000)  ' ≈ 0.01

Retorna a depreciação linear de um ativo em um período: (Cost - Salvage) / Life.

SLN(10000, 1000, 5)  ' 1800

Retorna a depreciação pelo método da soma dos dígitos dos anos para o período Period. A depreciação é maior nos primeiros períodos.

SYD(10000, 1000, 5, 1)  ' 3000

Inicializa o gerador de números aleatórios usado por Rnd, com semente baseada no relógio do sistema ou no Number informado. Chame uma única vez (ex.: no início do script), não antes de cada Rnd.

Randomize()

Retorna um Single aleatório maior ou igual a 0 e menor que 1. Chame Randomize uma vez antes, senão a mesma sequência se repete sempre que o mecanismo de script inicia; um argumento negativo retorna o mesmo número para a mesma semente e 0 repete o último número.

CInt(Int(Rnd() * 10)) + 1  ' 1 to 10

Retorna o nome da linguagem de script em uso, que é sempre "VB" no Visual Basic .NET.

ScriptEngine()  ' "VB"

Retorna o número de build do runtime do Visual Basic. Útil principalmente para diagnóstico.

ScriptEngineBuildVersion()

Retorna o número de versão principal do runtime do Visual Basic (8 no Visual Basic 2005).

ScriptEngineMajorVersion()  ' 8

Retorna o número de versão secundária do runtime do Visual Basic.

ScriptEngineMinorVersion()  ' e.g. 0

Adiciona um item à Collection, opcionalmente com uma chave Key de texto única (sem diferenciar maiúsculas) e uma posição dada por Before ou After (índice ou chave). Adicionar uma chave duplicada lança ArgumentException.

col.Add("Ana Souza", "guest1")

Remove todos os itens da Collection, deixando Count em 0.

col.Clear()

Retorna True se a Collection tiver um item com a chave informada. Use antes de Item(key) para evitar exceção com chaves inexistentes.

If col.Contains("guest1") Then col.Remove("guest1")

Retorna o número de itens da Collection. Os índices válidos vão de 1 a Count.

Dim last As Object = col(col.Count)

Retorna um enumerador para os itens da Collection; é o que permite o uso de For Each. Raramente é chamado diretamente.

For Each o As Object In col : Engine.WriteToLog(CStr(o)) : Next

Propriedade padrão que retorna um item pelo índice (base 1) ou pela chave de texto (col(1) ou col("chave")). Note que a Collection começa em 1, ao contrário de arrays e List(Of T), e um argumento Integer é sempre tratado como índice.

CStr(col("guest1"))  ' "Ana Souza"

Remove um item da Collection pela chave ou pelo índice (base 1). Lança exceção se a chave ou o índice não existir.

col.Remove("guest1")

Zera todas as propriedades do objeto Err (Number = 0, Description = ""...). É chamado automaticamente pelas instruções Resume, Exit Sub/Function e On Error.

Err.Clear()

Obtém ou define o texto descritivo do erro atual. É a mensagem que normalmente se registra em log ou se exibe.

Engine.WriteToLog(Err.Description)

Retorna o número da linha onde ocorreu o erro, apenas quando o código usa linhas numeradas; caso contrário, 0.

Err.Erl

Retorna o objeto Exception correspondente ao erro atual em Err. Útil para acessar os detalhes do .NET (tipo, stack trace, InnerException).

Dim ex As Exception = Err.GetException()

Obtém ou define o ID de contexto de um tópico no arquivo de ajuda associado ao erro. Raramente usado em scripts.

Err.HelpContext

Obtém ou define o caminho completo de um arquivo de ajuda associado ao erro. Raramente usado em scripts.

Err.HelpFile

Retorna o código de erro do sistema da última chamada a uma função de DLL não gerenciada feita por meio de uma instrução Declare. Só tem significado logo após essa chamada.

Err.LastDllError

Obtém ou define o código numérico do erro atual; 0 significa nenhum erro. Normalmente verificado após On Error Resume Next.

If Err.Number <> 0 Then Engine.WriteToLog(Err.Description)

Gera um erro de tempo de execução com o Number indicado e Source, Description e informações de ajuda opcionais. Para erros próprios, some um valor a vbObjectError para não conflitar com os números de erro do sistema.

Err.Raise(vbObjectError + 1, "MyScript", "Data file not found")

Obtém ou define o nome do objeto ou aplicativo que gerou o erro. Ajuda a identificar qual script ou componente falhou.

Err.Source