Gerenciamento de Telas

Modelo de Dados

Funções de Gerência de Telas

cod_ret = Screens.Open(string screenNickName, string screenPathName[,list Models], int screenTop, int screenLeft)

Descrição:

Criar um novo objeto de tela. Se a tela fizer referência a modelos deve-se utilizar o parâmetro opcional “Models”.

Parâmetros de entrada:

screenNickName - string com o nome a ser atribuído à tela a ser aberta. Este nome deve ser utilizado como parâmetro nas demais funções de acesso à tela.

screenPathName - string com o caminho de acesso à definição da tela a ser aberta. A definição das telas do projeto estão localizadas no item “Viewer.Screens”, agrupadas funcionalmente em grupos de telas.

HIScada Pro anterior a versão 1.0.05: Este caminho é composto apenas pelo “nome” da tela a ser aberta. Para estas versões não é permitida a definição de nomes de telas iguais, mesmo que pertençam a grupos de telas distintos.

HIScada Pro a partir da versão 1.0.05 : Este caminho é definido pelo endereço completo até a tela ser aberta. Este caminho é composto pelo prefixo “Viewers.Screens.”, mais o nome do “grupo” a que pertence a tela, mais o “nome” da tela. Por exemplo: “Viewers.Screens.grupoTela.NomeTela”. Neste caso o prefixo “Viewers.Screens” é comum para compor o caminho de acesso a todas as telas do projeto, e como é especificado o caminho completo de acesso a tela, permite-se a definição de telas com nomes iguais desde que estejam em grupos de telas distintos.

Models - Parâmetro opcional, necessário quando a tela possui referências a modelos. Neste caso devemos especificar uma lista com as instâncias de modelos referenciados nesta tela. Cada item da lista corresponde a um par (refInstModel = “pathInstance”) conforme descrito abaixo:

refInstModel: referência para uma instância de modelo utilizada na definição da tela

pathInstance: string como o caminho de acesso para uma instância de modelo

screenTop - inteiro que define a posição do “Topo” da tela a ser aberta. Caso não seja passado nenhum valor, será considerada a posição definida no projeto.

screenLeft - inteiro que define a posição do lado “Esquerdo” da tela a ser aberta. Caso não seja passado nenhum valor, será considerada a posição definida no projeto.

Parametros de saída:

cod_ret - Código de retorno associado à execução da função, onde 0 (zero) indica execução com sucesso da função, caso contrário indica um código de falha na execução da função.

Exemplo de utilização:

-- Criação de uma tela chamada "MinhaTela" a partir da definição
-- de tela "grupo1.Tela2"
local ret = Screens.Open("MinhaTela", "Viewers.Screens.grupo1.Tela2")

-- Criação de uma tela chamada "MinhaTela" a partir da definição
-- de tela "grupo1.Tela2" com Topo = 100 e Esquerda = 200
local ret = Screens.Open("MinhaTela", "Viewers.Screens.grupo1.Tela2", 100, 200)

-- Criação de uma nova instância de tela chamada "MG345" a partir
-- do mesmo tipo de definição de tela "grupo1.Tela2"
local ret = Screens.Open("MG345", "Viewers.Screens.grupo1.Tela2")

-- Criação de uma nova instância de tela chamada "MG965" a partir
-- do mesmo tipo de definição de tela "grupo1.Tela2" com Topo = 0 e
-- Esquerda = 0
local ret = Screens.Open("MG965", "Viewers.Screens.grupo1.Tela2", 0, 0)

Exemplo de utilização com instância de modelo:

-- Criação de uma nova instância de tela chamada "VisaoGerente" a partir do tipo
-- de tela "grupoV.VisaoBM" utilizando informações da instância "grpBM.AR147"
local ret = Screens.Open("AR147","Viewers.Screens.grupoV.VisaoBM",{refInstBM = "grpBM.AR147"})

-- Utilizando informações da instância "grpBM.AR012"
local ret = Screens.Open("AR012","Viewers.Screens.grupoV.VisaoBM",{refInstBM = "grpBM.AR012"})

-- Definindo o Topo e o lado Esquerdo da tela
local ret = Screens.Open("AR012","Viewers.Screens.grupoV.VisaoBM",{refInstBM = "grpBM.AR012"}, 50, 50)


-- Criação de uma nova instância de tela chamada "VisaoOperador" a partir
-- do tipo de tela "grupoV.VisaoGeral" utilizando informações das instâncias
-- "grpBM.AR012" e "grpGLI.MG014":
local ret = Screens.Open("VisaoOperadorB","Viewers.Screens.grupoV.VisaoGeral",{refInstBM = "grpBM.AR012", refInstGLI = "grpGLI.MG014"})

-- Definindo a posição do Topo e lado Esquerdo da tela
local ret = Screens.Open("VisaoOperadorB","Viewers.Screens.grupoV.VisaoGeral",{refInstBM = "grpBM.AR012", refInstGLI = "grpGLI.MG014"}, 100, 150)

cod_ret = Screens.Close(string screenNickName)

Descrição:

Fechar uma tela.

Parâmetros de entrada:

screenNicktName - string de identificação do nome da tela a ser fechada. Este parâmetro corresponde ao próprio parâmetro “screenNickName” passado na função “Screens.Open”

Parâmetros de saída:

cod_ret - Código de retorno associado à execução da função, onde 0 (zero) indica execução com sucesso da função, caso contrário indica um código de falha na execução da função.

Exemplo de utilização:

-- fechamento da Tela
erro = Screens.Close("MinhaTela")    -- fecha a tela "MinhaTela"
erro = Screens.Close("MG345")        -- fecha a tela "MG345"
erro = Screens.Close("AR147")        -- fecha a tela "AR147"

flag_exist = Screens.Exist(string screenNickName)

Descrição:

Verificar se uma tela existe. Uma tela existe no sistema a partir do momento que a mesma é aberta através de uma função “Screens.Open”.

Parâmetros de entrada:

screenNicktName - string de identificação do nome da tela a ser acessada. Este parâmetro corresponde ao próprio parâmetro “screenNickName” passado na função “Screens.Open”

Parâmetros de saída:

flag_exist - booleano que indica a existência da tela no sistema, onde :

true : tela existe no sistema

false : tela não existe no sistema

Exemplo de utilização:

-- testa se a tela "MG012" existe no sistema
if Screens.Exist("MG012") then
  print("Tela Existe")
else
  print("Tela Nao Existe")
end

scrObj = Screens.Get(string screenNickName)

Descrição:

Obter uma tela criada previamente e dado seu nome. A partir desta tela retornada é possível acessar os componentes pertencentes à tela.

Parâmetros de entrada:

screenNicktName - string de identificação do nome da tela a ser acessada. Este parâmetro corresponde ao próprio parâmetro “screenNickName” passado na função “Screens.Open”

Parâmetros de saída:

scrObj - objeto que representa a tela. Se a tela não existe retorna nil.

Exemplo de utilização:

-- Obtém um objeto de tela com nome "TelaMG012"
local scr = Screens.Get("TelaMG012")

-- Acesso aos atributos da tela "MG012"
-- próprio nome da tela: "Viewers.Screens.ScreenGroup_001.MG012"
print("Nome da instância de tela = " .. scr.Name).
-- Nome da definição do tipo da tela utilizado para instanciar a tela
-- "Viewers.Screens.ScreenGroup_001.MG012"
print("Nome do tipo de tela = "      .. scr.Type).
-- titulo da tela
print("Nome do tipo de tela = "      .. scr.Title).

-- Acesso aos componentes da instância de tela "TelaMG012"
local btclose = scr.myButtonClose.
-- altera o caption do botão "Close" da tela "MG012"
btclose.Caption = "Fecha Tela MG012".

Funções de Gerência de Instâncias de Telas

ScreenInstance (Instância de Tela)

O objeto de tela, neste exemplo atribuído a “scr”, pode ser obtido de duas formas.

A primeira forma é por criação direta em um script qualquer:

local ret = Screens.Open("VisaoPocosA","Viewers.Screens.grupo1.xTelaVisao", {refInstBM = "grpBM.AR147", refInstGLI = "grpGLI.MG012"})
local scr = Screens.Get("VisaoPocosA") -- obtém o objeto de tela associado a uma instância de tela especifcada como parâmetro.

A segunda forma é quando o script está associado à qualquer objeto de tela, inclusive à própria tela. Neste caso a variável global Sender pode ser utilizada para obter uma referência para a tela.

-- obtém o objeto de tela associado à instância de tela onde está localizado o "Sender"
scr = Sender.Screen

A instância de tela “VisaoPocosA” possui os atributos Name e Type.

Exemplo de utilização:

-- obtém a tela "MG012"
scr = Screens.Get("MG012")
print("Nome da tela = " .. scr.Name)
print("Tipo de tela = " .. scr.Type)
print("Titulo da tela = "  .. scr.Title)

A instância de modelo “refInstBM” foi associada à tela “VisaoPocosA” no ato de sua criação. È uma tabela que mapeia referências locais (no contexto do script) para nome de instâncias do modelo (no contexto do projeto) pode ser obtida da seguinte forma:

scr.Instances   -- lista de instâncias de modelos referenciados nesta tela
                -- {refInstBM = "grpBM.AR147", refInstGLI = "grpGLI.MG012"}
instModel = scr:GetInstance("refInstBM")  -- obtém acesso a uma instância de modelo
instModel = scr.Instances["refInstBM"]    -- criar esta tabela "Instances"

-- referência para uma instância de modelo utilizada na definição da tela
print(instModel.Ref)     -- resultado: "refInstBM"

-- nome da instância de modelo associado à referência "refInstBM"
print(instModel.Name)    -- resultado: "grpBM.AR147"

-- Nome do modelo associado à instância "grpBM.AR147"
print(instModel.Model)   -- resultado: "xModelBM"

-- identificador do item de Instância na árvore de objetos (utilizado para depuração)
print(instModel.ItemID)

-- identificador do item de Modelo na árvore de objetos (utilizado para depuração)
print(instModel.ModelID)

Funções de Acesso aos Componentes de Telas

Quando existirem componentes de tela cujo modo de edição esteja configurado para ser via “Script”, existem as seguintes funções para permitir a gerência sobre os valores editados pelo usuário:

cod_ret = scr:SaveAllEdit()

Descrição:

Salva a edição de todos os objetos de tela que possuam alteração pendente. Aplicável aos componentes de tela cujo modo de edição esteja configurado para ser via “Script”.

Parâmetros de saída:

cod_ret - Código de retorno associado à execução da função.

Exemplo de utilização:

local scr = Sender.Screen         -- obtém a tela onde estão os componentes de tela a serem atualizados
local ret = scr:SaveAllEdit()     -- Salva os valores de todos os componentes de tela que possuam alteração pendente

cod_ret = scr:CancelAllEdit()

Descrição:

Cancela a edição de todos os objetos de tela que possuam alteração de valor pendente. Aplicável aos componentes de tela cujo modo de edição esteja configurado para ser via “Script”.

Parâmetros de saída:

cod_ret - Código de retorno associado à execução da função.

Exemplo de utilização:

-- obtém a tela onde estão os componentes de tela a serem atualizados
local scr = Sender.Screen

-- Cancela a edição de todos os objetos de tela que possuam alteração pendente
local ret = scr:CancelAllEdit()

Exemplos de Utilização

Exemplo de interação com componentes

local scr = Screens.Get("Screen_001")
print(tostring(scr))
print(scr.Button_001.Left)
scr.Button_001.Visible = false

Exemplo de interação com janelas, componentes e propriedades

  -- Criação de uma nova Tela "MG012" do tipo "xTela2"
  local ret = Screens.Open("MG012","Viewers.Screens.grupo1.xTela2")

  -- É possível passar um terceiro parâmetro opcional,
  -- com lista de instâncias (chave é nome da variável e valor é o nome do modelo
  local ret = Screens.Open("MG012","Viewers.Screens.grupo1.xTela2",{BM1 = "grpBM.AR147", GLI = "grpGLI.MG012"})
  print("Resultado do Screen.Open " .. ret)

  -- listagem de todas instâncias de modelo associada à tela
  for instance_scr_name, inst_obj in pairs(scr.Instances) do
  print(instance_scr_name).
  end

  -- Acesso à tela pai que ativou o script
  local scr = Sender.Screen

  -- Acesso à Tela "MG012", o nome da variável local pode ser qualquer
  local scr = Screens.Get("MG012")

  -- Acesso a componente de tela
  local btn2 = scr.xButton2
  btn2.Caption = "Novo rótulo"

  -- código análogo
  scr.xButton2.Caption = "Novo rótulo"

  -- Acesso a uma instância de modelo utilizado na tela
  local bm1 = scr:GetInstance("BM1")  -- retorna uma instância específica utilizada na tela
  print (bm1.Name)  -- imprime o nome da instância da tela corrente
  print (bm1.Model) -- imprime o nome do modelo que está associado a esta tela
  print (bm1.Path)  -- imprime o caminho do item até antes do item Tags

  -- teste da existência da Tela
  if Screens.Exist("MG012") then
    print("Existe")
    else
    print("Nao Existe")
  end

-- fechamento de Tela
Screens.Close("MG012")
Screens.Close(CurrentScreen)

-- listagem de todas as telas abertas no viewer
for screen_instance_name,type_name in pairs(Screens.List()) do
  print(screen_instance_name .. "->" .. type_name)
end

Atributos Acessíveis nos Componentes de Tela

Através de scripts é possivel acessar diversos atributos de componentes de telas. Estes atributos podem ser consultados em Acesso a atributos e funções de Componentes de Tela.