Simba/Includes/eZForm.simba
A step by step guide to using eZForm
Step 1 - Making a new form
Making a new form is easy with eZForm. Firstly, we need to include eZForm and call the eZForm.create() method.
Script 1.0:
Simba Code:
program eZTutorial;
{$i eZForm.simba}
var
myForm:eZForm;
begin
myForm.create('Tutorial');
myForm.show();
repeat until false;
end.
We've initiated eZForm! The form we've created is titled Tutorial and has the default dimensions.
Step 2 - Adding components
Now that we've got our form, it's time to start adding some elements (controls) to it. To do this, we use the eZForm.add*() methods.
Script 2.0:
Simba Code:
program eZTutorial;
{$i eZForm.simba}
var
myForm:eZForm;
begin
myForm.create('Tutorial');
myForm.addButton('Text','b s8','button',[10,10],[230,95],nil);
myForm.show();
repeat until false;
end.
Running the code above, you'll see that we've created a large button. Typically when creating controls, the parameters for the add method are as follows:
- Caption - 'Text'
The caption is the text displayed to the user on the control. - Font - 'b s8'
The font, if the control supports it, is the style which we draw the text. A full list of font options are:
- Bold - b / bold
- Color - c# / color#
- Italic - i /italic
- Size - s# / size#
- Strikeout - s / strikeout
- Underline - u / underline
- Handle - button
The handle is the control's name or ID which can be useful for future reference. - Position - [10,10]
The position is the top-left point of the control which we're adding. - Dimensions - [230,95]
The dimensions, if the control supports it, is the width and height of the control. - Event Handler - nil
The event handler is the function to be called when the user interacts with the control.
Keep in mind that not all components support each option. For example, images do not support captions, labels do not support dimensions, etc.
Step 3 - Referencing components
More often then not, you'll need to reference your elements. Whether it's getting the contents of an edit field, whether or not a checkbox is checked, etc. There are a few ways we can do this.
First of all, we can store them into variables. Elements on a form use the eZElement type.
Script 2.0:
Simba Code:
program eZTutorial;
{$i eZForm.simba}
var
myForm:eZForm;
myCheckbox:eZElement;
begin
myForm.create('Tutorial');
myCheckbox:=myForm.addCheckbox('Text','i s8','',[10,10],nil);
myForm.show();
repeat
clearDebug();
writeLN(myCheckbox.checked());
until false;
end.
There we go! We can now reference the checkbox we created, and its methods, by using myCheckbox. We do this, in the above example, by writing if the checkbox is checked.
Now, what if we don't want to use a variable? How can we access the checkbox we've just made? eZForm.find() is a powerful method for finding controls on a form. It returns a eZElementArray - an array of control matching your query.
Script 2.1:
Simba Code:
program eZTutorial;
{$i eZForm.simba}
var
myForm:eZForm;
begin
myForm.create('Tutorial');
myForm.addCheckbox('Text','i s8','hCheckbox',[10,10],nil);
myForm.show();
repeat
clearDebug();
//~ Method 1
writeLN(myForm.find()[0].be('checked'));
//~ Or method 2...
writeLN(myForm.find('checkbox')[0].checked());
//~ Or method 3...
writeLN(myForm.find('#hCheckbox')[0].prop('checked'));
wait(50);
until false;
end.
This is a brief explanation of the methods above:
- Method 1 - eZForm.find()[0]
Excluding the parameter for find will return all controls. This works in this case because the first element happens to be the checkbox we were after. - Method 2 - eZForm.find('checkbox')[0]
Here we are referencing each checkbox. If we had multiple checkboxes, each would be returned. You can retrieve an array of any control type by using eZForm.find() this way. - Method 3 - eZForm.find('#hCheckbox')[0]
The most reliable, this method retrieves controls by their handle. In this case, we're looking for controls with the handle hCheckbox. While controls can not be named the same thing, this method still returns and array and thus still requires [0].
Step 4 - Event handlers
We've got a form where we can, at any time, get the contents and values of various controls. Though, how do we perform actions when the user interacts with controls?
Script 3.0:
Simba Code:
program eZTutorial;
{$i eZForm.simba}
var
myForm:eZForm;
procedure eCheckboxHandler();native;
var
_IsChecked:boolean;
begin
_IsChecked:=myForm.find('#hCheckbox')[0].checked();
myForm.find().isnt('#hCheckbox').disabled(_IsChecked);
end;
begin
myForm.create('Tutorial');
myForm.addCheckbox('Disable elements','i s8','hCheckbox',[10,10],eCheckboxHandler);
myForm.addButton('Text','b s8','',[10,35],[230,30],nil);
myForm.addCheckbox('Text','s8','',[10,75],nil);
myForm.addCheckbox('Text','s8','',[125,75],nil);
myForm.show();
repeat until false;
end.
In the above example, eCheckboxHandler is the event handler for our checkbox. Each time the user interacts with it, eCheckboxHandler is called.
Much like before, you can see we used method 3, from script 2.1, to reference the checkbox and stored its state inside _IsChecked. We then get all controls on the form using eZForm.find() to get an array of all controls on the form. We then exclude #hCheckbox using the eZElementArray.isnt() method and set the disabled property for each to _IsChecked.
It's really that easy. The rest you'll learn from playing with it - learning the various eZElement.prop() (property) options, component types, etc. For more examples and functionality, see the list full list here.