Win32Api
Este é um antigo tutorial meu que consegui resgatar de outra comunidade e estou tornando público aqui. Se você planeja tentar acessar funções do Windows diretamente através do RGSS ou aprender a manipular qualquer tipo de dll , você veio ao local certo ! O tópico que te explicará tudo sobre a classe WIN32API.
API's são blocos de dlls usadas principalmente pelo windows para gerenciar suas funções mais fundamentais. Elas nos permitem controlar tudo. As API's mais usadas são : WIN32API e WIN32OLE ;
O Ruby tem suporte a ambas as API's , enquanto o RGSS tem suporte somente a primeira delas.
Mas isto não é motivo para se angustiar, até por que as funções mais dramáticas para envolver jogos está dentro da 32API.
Este é um método avançado, ou seja, a menos que você já tenha uma boa noção de RGSS e saiba controlar Classes,Métodos, Arrays e outras coisas, talvez você não consiga entender este tutorial.
Chamar uma API é basicamente : chamar uma dll , definir a função a ser utilizada , definir os tipos de seus parâmetros e por fim definir o valor de seus parâmetros. O objeto resultante a isso poderá ser usado para enfim chamar a função.
Porém, existe um grande problema quanto aos argumentos. Eles são muito difíceis de definir, especialmente o parâmetro de retorno (veja em seguida). É preciso realizar testes no seu jogo para ver se tudo funcionará corretamente.
Para invocar o a classe Win32API e seus métodos use o seguinte código :
variável = Win32API.new("1","2","3","4")
variável.call("a","b","c",etc...)
Esta é a configuração básica para que tudo ocorra corretamente. Vamos nos aprofundar agora nos elementos do primeiro parênteses :
1 - Nome da Dll :
O nome da dll que está sendo utilizada, por exemplo, user32.dll ou kernel32.dll.
Dentro da pasta "C:/Windows/system32/" (relativa a seu computador) você encontra todas as dlls suportadas pelo comando.
2 - Função da Dll :
Uma das funções exercidas pela dll. Por exemplo : MessageBox é uma das funções da dll user32.dll.
3 - imputArray :
Esta talvez seja a característica mais dificil de entender, pois foi uma característica trazida da linguagem C.
A imput Array é um conjunto de letras (strings) que formam, em lógica, os tipos dos parâmetros que serão usados para iniciar a função da determinada dll. Existem 4 tipos de letras :
"n" e "l" : Representam, ambos, números não literais.
"i" : Representam integers (números inteiros, bignums ou fixnums)
"p" : Representam strings (textos entre aspas)
Por Exemplo : A função MessageBox necessita de 4 parâmetros, na seguinte ordem : Número,Texto,Texto,Número.
Logo, sua importArray será : 'lppl' (você entenderá porque 'nppn' e 'ippi' são inviáveis mais adiante)
Pode-se também separar as strings por uma Array, assim : ['l','p','p','l']
4 - export :
O valor de export é, em suma, uma única letra. O valor de export é o mais dificil de ser determinado, pois ele determina o tipo de parâmetro do valor do parâmetro em resposta a função. Parece complicado (e é) , mas é bem simples...Vamos supor que você crie uma MessageBox com os botões OK , Cancelar e Fechar (o "xis" no canto da caixa). Como o RGSS identificará qual é o botão que você pressionou ? Através do export. Se a função retornar um texto, você deve usar 'p' em export, para que o RGSS possa ler a resposta como sendo uma string e interprete-a. O mesmo vale para os outros tipos de parâmetro. Existe somente mais um tipo e parâmetro que o valor export suporta além do valor importArray, que é o parâmetro void, que tem o mesmo valor de nil (ou seja, nada), é representado pela letra 'v' e só aparece quando, por exemplo, o jogador não aperta nenhum botão.
Pronto, já podemos definir, por exemplo, nosso primeiro código para uma MessageBox :
variável = Win32API.new('user32','MessageBox','ippi','i')
variável.call(a,"b","c",d)
Repare que 'a' não possui aspas, por este ser um número integer, assim como 'd', e o mesmo vale para os opostos 'b' e 'c' que possuem aspas por serem strings. Isso foi definido na importArray, que apontou os parâmetros como sendo integer, string, string e integer. Veja também que o valor retornado quando o jogador clicar em um botão será um valor integer. Isto foi definido no export 'i'.
Até agora tudo bem tio Grunje...MAS COMO É QUE DIABOS VOU SABER QUAIS PARÂMETROS CADA FUNÇÃO USA ???
Calma calma, digo eu ! Não precisa ficar nervoso...tudo em seu tempo...
Sabemos que cada dll possui diversas funções, e que cada função necessita de diversos parâmetros...
Existem alguns modos de determinar as funções e os parâmetros das mesmas de uma dll usando sites de busca, pesquisando conteúdos sobre dll e etc...mas esta solução é muito vaga e inviável, pela enormidade de conteúdo que existe por aí, muitas vezes desatualizados ou falsos !
Um dos melhores métodos de determinar todos esses dados é utilizando um programa de simples interface : O API-Guide.
Este programa é um Guia de Referência (em inglês) que exibe todos os parâmetros, de todas as funções, de todas as dlls, de todas as APIS do seu atual Windows (PUXA!), computando-as em bancos de dados. Além disso, ele dá informações detalhadas sobre cada dll ou função (detalhadas mesmo!), além de exibir a Importação e os Retornos das Funções e Parâmetros, asism como permite que se faça uma busca rápida e eficaz sobre todas as funções existentes.
Este programa, gratuito, pode ser encontrado aqui (2.2 MB) : API-Guide 3.7
Após fazer download e instalar, abra o programa. Vamos descobrir agora como funciona a função MessageBox.
No retângulo branco superior esquerdo da tela digite o nome de sua função, que aparecerá na ordem alfabética : "MessageBox" (sem aspas). Você será direcionado para o nome de sua função. A tela será semelhante a esta :
1 - Aqui você visualiza a que dll pertence esta função, ou seja, no caso da MessageBox, pertence a dll User32.
2 - Aqui você visualiza os requerimentos mínimos para usar esta função em um computador (tanto no computador de quem está criando o jogo quanto de quem irá jogar). A MessageBox por exemplo, só pode ser usada em Windows 95 ou superior.
3 - Esta é uma janela que mostrará o uso e a descrição da função. No caso, a função MessageBox cria, exibe e opera janelas e você pode definir títulos, botões e ícones.
4 - Por fim, o último quadro destacado, mostra funções filhas da função MessageBox, exatamente como em uma herança Superclass do RGSS.A MessageBox , por exemplo, pode chamar a função MessageBoxEx e MessageBoxIndirect.
Após ter todas as informações essenciais sobre a função, clique na segunda aba do quadro direito : A aba "Parameters".
Esta aba é a mais importante. Vamos visualizá-la :
Vamos analisar agora o bloco de declaração :
Declare Function MessageBox Lib "user32" Alias "MessageBoxA" (ByVal hwnd As Long, ByVal lpText As String, ByVal lpCaption As String, ByVal wType As Long) As Long
Verde-A) Primeiro, a declaração define o nome da função, no caso, MessageBox.
Verde-B) Em seguida, ele define sua Lib (library) que é a user32.dll.
Verde-C) Por fim, ele define um nome de retorno,que será ativado quando a função acabar, ou seja, o alias "MessageBoxA".
Azul-A e B) Pelo Valor (ByVal) "hwnd" foi definido o priméiro parâmetro que é uma Long (por isso a imputArray é "L").
Azul-C e D) Pelo Valor (ByVal) "Ip Text" foi definido o segundo parâmetro que é uma String (daí o imput ser "S").
Azul-E , F, G e H) Foram definidos também o parâmetro "IpCaption" e "wType" que são uma Long e uma String.
Vermelho) Este é o tipo do valor do export , uma Long (por isso a export é uma string única tal que "L" a valoriza).
2 - Agora que você já descobriu quais são os parâmetros e os seus tipos através do bloco de declaração, só resta saber qual é a função de cada parâmetro. Para isso bastar analisar (e possuir um leve inglês) o segundo quadro, que descreve a função dos parâmetros. Por exemplo : a função do parâmetro "wType" (window type) é especificar um conjunto de sinalizadores de bit que determinam o conteúdo e o comportamento da caixa de diálogo (botões e ícones). Este parâmetro pode ser uma combinação de sinalizadores, resultando em uma combinação de botões e ícones. Eles estão em ordem numérica, ou seja, se você quiser uma janela, por exemplo, com ícone de ajuda e os botões "OK" e "Cancelar" , bastar unir os dois algarismos que à compõe (pelo menos em teoria...mas se não funcionar é só ir testando que não há falhas).
3 - Por fim, e não menos importante, temos a última caixa e que demonstra os retornos. Como assim ? Se você clicar em um botão da janela, o código do Win32API irá lhe mandar um retorno, ou seja, um número ou uma string (tal definido pela letra do export) , que definirá uma ação, que estão contidas neste último quadro. Por exemplo : o valor retornado será zero se não existir memória para criar a janela...ou o valor poderá retornar 2, indicando que o botão cancelar foi pressionado. Para descobrir qual o valor de cada ação, basta analisar o quadro. Você pode usar estes valores da maneira que quiser...(com condicionais, repetidores ou para fazer cálculos por exemplo).
Pronto ! O resultado final sairia mais ou menos isto :
variável = Win32API.new("user32","MessageBox","lppl","l")
case variável.call(0,"Ola, qual opcao deseja ?","Caixa de Opcoes",33)
when 1
print "Você escolheu \"Ok\"."
when 2
print "Você escolheu \"Cancelar\"."
end
(Bem, existe um mínimo problema em relação as letras 'ç' e as letras com acento...provavelmente por que não aparecem no teclado americano da microsoft...mas isso deve ser possível de resolver com um pouquinho de estudo)
Agora é com você ! Te dei a vara e ensinei a pescar...a paciência é sua para conseguir o peixe !
Existe uma ENORME biblioteca de funções dentro do API-Guide. Estude-as, pesquise...
Créditos : Otávio Grunje
Até a próxima !
