Advanced Tool scripting
The scripting language in lumina is not limited to controll the rendering, it is also
possible to write small tols wit a simple GUI. The GUI Toolkit based on the
QSA Dialog Factory
so it s possible to use Trolltechs documentation as overview. This
factory in lumina has some improvements: Many Widgets can send signals, which can be
connected with script functions, to handle GUI events like changing a Combobox or
processing a input of a lineedit.
For the first experiments the console can be used, but it is more recommend to store
the scrip in the plug in directory. To add the script to the context menus a small
header is requiered:
/*
<NAME>Lumina IRC Client</NAME>
<FILTER>ScriptToolBar</FILTER>
<DESCRIPTION>Simple IRC client. Connect to #lumina @ irc.freenode.net</DESCRIPTION>
<TOGGLE/>
<XPM>
static char *irc[]={
"22 22 3 1",
". c None",
"# c #000000",
"a c #00ff00",
"......................",
"......................",
"......................",
"......................",
".############...#####.",
".#aa##aaaaaa##.##aaa##",
".#aa##aaaaaaa###aaaaa#",
".#aa##aa####aa#aaa##a#",
".#aa##aa#..#aa#aa#####",
".#aa##aa####aa#aa#....",
".#aa##aaaaaaaa#aa#....",
".#aa##aaaaaaa##aa#....",
".#aa##aa##aa###aa#....",
".#aa##aa##aa###aa#....",
".#aa##aa###aa##aa##...",
".#aa##aa#.#aa##aaa####",
".#aa##aa#.##aa##aaaaa#",
".#aa##aa#..#aa###aaa##",
".########..####.#####.",
"......................",
"......................",
"......................"};
</XPM> */
The first line starts a commend that is closed at the end of the header with */ The
script interpreter will ignore the header content. The first Tag is the NAME tag, it
will be used as text in the contextmenu or Tooltip for a toolbar. The <FILTER> is a
regular expresion that have to match the object type if it should be added.
The <DESCRIPTION> is a longer text that will be displayed in the mainwindows status bar.
The <TOGGLE/> tag have to be included if the script can be switched on/off.
The <XPM> tag includes the content of a *.xpm file. It is the Icon that will be used.
The recommendent sizes are 22x22 for the ToolBar and 16x16 for context menues.
The plugin directory will be scanned only at the startup of lumina, but the script self
can be edited without restarting lumina.
A simple script
For editing the script code it is recommend to write the code in a script items editor.
There it s possible to use the advantages of the autocompleter, syntax highlighting and
the short reference.
A simple script is the Wizard script that creates some objects an load some content from
files:
World.addNode("Wizard");
World.Wizard.addScript();
World.Wizard.addVertexShader();
World.Wizard.addFragmentShader();
World.Wizard.addTexture("Colormap");
World.Wizard.addTexture("Normalmap");
World.Wizard.addTexture("Depthmap");
World.Wizard.Colormap.load("media/test5.png");
World.Wizard.Fragmentshader.load("media/simpletex.frag");
World.Wizard.Script.load("media/relief.js");
World.Wizard.Vertexshader.load("media/simpletex.vert");
This simple script replaces many clicks that would be requiered to create the
envrionment.
GUI
The first question is if the GUI should be a Dialog or a DockWidget. Dialogs are used to
to ask for options. Examples are the generator scripts for the testobjects or gears.
(They don t use the <TOGGLE> tag) The IRC client however based on the DockWidget. GUI
Widgets are owned by the script engine and have to be generated with the new Keyword:
dock = new Dock();
dock.title = "Example Dock Widget";
dialog = new Dialog();
dialog.title = "Example Dialog";
dialog.exec();
If this lines are entered into the script console the differend behaving wis visible:
The Dock intgrates it self to the GUI, but the Dialog will open a new window, block the
application and wait for pressing OK or Cancel.
The next step is to add widgets:
combo = new ComboBox();
dock.add(combo); // or use dialog
combo.label = " Select:";
combo.itemList = Array("One","Two","Three");
label = new Label();
dock.add(label); // or use dialog
This adds a combo box and a label to the dock or dialog. now it's possible to add a
signal handler to the combo box:
'
function changeHandler(){
switch(combo.currentItem){
case "One": label.text = "First Item"; break;
case "Two": label.text = "Second Item"; break;
case "Three": label.text = "Third Item"; break;
}
}
combo.changed.connect(changeHandler);
This is not possible in QSA, because the signal is a new feature in the modified dialog
factory. The code snipped is usefull to diplay a short help, set the content of other
widgets (i.E. the default values in a convolution matrix or select different shaders in
a more advances Wizard)
Curently are folowing Signals supportet:
CheckBox: clicked
RadioButton: clicked
Button: clicked -> a onClick function
LineEdit: returnPressed -> can be used to check the content in a dialog or handle the
content in a dock
ComboBox: changed -> demonstrated in the example
Slider: changed
other signals will be implemented in future.
An example to create 3 sliders to change a lightcolor stored in in a Buffer:
d = new Dock();
r = new Slider();
g = new Slider();
b = new Slider();
r.label = "Red:";
g.label = "Green:";
b.label = "Blue:";
d.add(r);
d.add(g);
d.add(b);
function lcolor (){
//Path and function
World.Node.Buffer.set(0,r.value * 0.02, g.value * 0.02, b.value* 0.02);
}
r.changed.connect(lcolor);
g.changed.connect(lcolor);
b.changed.connect(lcolor);
Scripts like this can be entered directly into the Console or executed from a script
object.
Network
Currently are two objects suported: A UDP server and a TCP client. These can be used to
connect Lumina to other programs or send data directly to a script in Lumina. Both
objects are designed for clear text protokolls. Two smal scripts to demonstrate the
functionality:
port = 5678;
udp = new UdpServer(port)
function handlePacked(packet){
print(packet); // print the line to std::out, may be invisible on windows
computer
}
udp.packed.connect(handlePacked);
This example needs an echo server running on the same computer:
tcp = new TcpClient("localhost:7"); //connet to a echo server
function ready(){
print (tcp.readLine());
}
tcp.ready.connect(ready);
tcp.sendLine("Send some text to the server\r\n");
Sometimes it may be usefully to change to an other handler (i.E. afer a sucesfull
login). In that case the disconnect function will help:
tcp.ready.disconnect(ready);
tcp.ready.connect(other function);
Working with the object tree
Some functions:
World.findChild("Node");
search for the first child named "Node" in World.
World.getType()
returns the lumina objectype. (The typeof operator returns the classname, that won't be
compatible to a future engine)
Calling script functions in other scripts
It isn't a good idea. to use the dialog factory in a render script, because a later
game engine couldn't handle the code, and to GUI would be killed every time the render
script is restarted.it is much better to add a function in the render script and call it
with:
World.Node.Script.Call("functionname",Array("String argument", 4, 5.0));
If only one number argument is used, a secondary dummy argument should be added, to
avoid an Array with "number argument" empty objects. If no argument is needed, an empty
Array have to be used.
Calling all script functions in a subtree
The same function is available for World and Nodes (since version 0.3.1)
World.Call("functionname",Array("String argument", 4, 5.0));
This is usefully for building renderers.
FAQ
How it's possible to remove Widget from a dialog/dock?
If they are added to another dialog/dock they will be removed from the first.
