[SCAR]Using Forms

Version: 1.0
Made By: Tharoux
Date: September 4th, 2008
Revision: September 4th, 2008
Goal: Creating a simple GUI with a textbox and a button displaying "Hello World !"


Even if most of us know SCAR for beeing able to play a game without fiddling with a GUI, it is possible to create one just like in every other language. There's a built-in function to design a form but it's only a small part of the process and you won't go anywhere with just that. Personally, I like to create my form by coding it, thus doing it the hard way, but I think it's important to understand the process before even trying the built-in function. So, let's start.

• ->Chapter One: Variable Declarations
  ->Chapter Two: Form Initialization
  ->Chapter Three: Displaying The Form
  ->Chapter Four: Adding Objects
  ->Chapter Five: Adding Code To The Button
  ->Chapter Six: Nice To Have...
  ->Script Example
  ->The End

Chapter One: Variable Declarations


Like all other variables in SCAR, all fields including the form itself must be declared at the beginning of the script using the syntax "Variable Name : Object Name". Here's a small list of the most common objects used in a GUI:

• -TForm : For the form itself
  -TLabel
  -TEdit
  -TButton
  -TCheckBox :
  -TRadioButton
  -TListBox
  -TComboBox

If we get back to our goal, we need to create a script with a textbox and a button, so we will use 3 objects and declare them as follow:

Code (Text):

1. Program UsingForm;
2.  
3. Var
4.   frmDesign : TForm;   //The form itself
5.   txtMessage : TEdit;   //The textbox
6.   cmdDisplayMessage : TButton;   //The button

Chapter Two: Form Initialization

Now that we have declared all the variables we need in our script, it's time to attack the form itself. For now, we will create an empty form and take a look at the different properties that we can use to customize it. Later, we will take care of putting extra stuffs in there.

Everything GUI related must be put into a procedure that we will call InitForm. The first line of the procedure is always the same and tell the variable witch contain the form to create itself.

Code (Text):

1. frmDesign := CreateForm;

Everything found after this line and beginning with the name of the form is properties that we will customize to make the GUI look like we want it to look. I won't be showing ALL the properties that we can use, because I find this useless. We will only code the needed one. The example below will also explain what each property do.

Code (Text):

1. Procedure InitForm;
2. Begin
3.   frmDesign := CreateForm;   //Create the form
4.   frmDesign.Left := 500;   //How many pixels from the left of the screen
5.   frmDesign.Top := 100;   //How many pixels from the top of the screen
6.   frmDesign.Width := 350;   //The width of the window
7.   frmDesign.Height := 250;   //The height of the window
8.   frmDesign.Caption := 'Hello World !';   //The title of the window
9.   frmDesign.Visible := False;   //Need to be "false" if we want to call the form within a thread
10. End;

Chapter Three: Displaying The Form

We have a plain form, but for now, we can't see it. It's a shame !

Now, it's time to do some magic and make it appear. The example I'm going to show you is probably not the only way to show the form but is the one used by all the coder and the one explained in the help section of scar. We will use threading and the best thing off all, we won't need to handle the exception and error return. Yippe !!!!

Again, all this coding is contained inside procedures. It's easier because we will need to call those using the thread call function. This will disable the SCAR window but will prevent your form from freezing while waiting for input or processing data.

First, the form initialization with the thread

Code (Text):

1. Procedure SafeInitForm;
2. Var
3.   v: TVariantArray;
4. Begin
5.   SetArrayLength(V, 0);
6.   ThreadSafeCall('InitForm', v);  //Important part: call the InitForm (The GUI)
7. End;

Now, our GUI exist, but it's still not showing anywhere. We have to tell the GUI to appear.

Code (Text):

1. Procedure ShowFormModal;
2. Begin
3.   frmDesign.ShowModal;   //Make the GUI visible
4. End;

But wait ! I don't see any threading function in there !

Code (Text):

1. Procedure SafeShowFormModal;
2. Var
3.   v: TVariantArray;
4. Begin
5.   SetArrayLength(V, 0);
6.   ThreadSafeCall('ShowFormModal', v);   //Important part: make the GUI visible using ShowFormModal
7. End;

Ok, everything is ready to use the form but it won't show just yet. We need to call the 2 threading function in our "Main function" or else all this nice code will just sit there waiting to work.

Code (Text):

1. Begin
2.   SafeInitForm;   //Initialize the form using the threading function
3.   SafeShowFormModal;   //Make the form visible using the threading function
4. End.

For those who weren't paying attention, here's what your script should look right now:

Code (Text):

1. Program UsingForm;
2.  
3. Var
4.   frmDesign : TForm;   //The form itself
5.   txtMessage : TEdit;   //The textbox
6.   cmdDisplayMessage : TButton;   //The button
7.  
8. Procedure InitForm;
9. Begin
10.   frmDesign := CreateForm;   //Create the form
11.   frmDesign.Left := 500;   //How many pixels from the left of the screen
12.   frmDesign.Top := 100;   //How many pixels from the top of the screen
13.   frmDesign.Width := 350;   //The width of the window
14.   frmDesign.Height := 250;   //The height of the window
15.   frmDesign.Caption := 'Hello World !';   //The title of the window
16.   frmDesign.Visible := False;   //Need to be "false" if we want to call the form within a thread
17. End;
18.  
19. Procedure SafeInitForm;
20. Var
21.   v: TVariantArray;
22. Begin
23.   SetArrayLength(V, 0);
24.   ThreadSafeCall('InitForm', v);  //Important part: call the InitForm (your GUI)
25. End;
26.  
27. Procedure ShowFormModal;
28. Begin
29.   frmDesign.ShowModal;   //Make the GUI visible
30. End;
31.  
32. Procedure SafeShowFormModal;
33. Var
34.   v: TVariantArray;
35. Begin
36.   SetArrayLength(V, 0);
37.   ThreadSafeCall('ShowFormModal', v);   //Important part: make the GUI visible using ShowFormModal
38. End;
39.  
40. Begin
41.   SafeInitForm;   //Initialize the form using the threading function
42.   SafeShowFormModal;   //Make the form visible using the threading function
43. End.

Chapter Four: Adding Objects

Time to test the script !
Click "Run Script" and you now have a nice GUI showing. Quite plain, isn't it ? Let's add some stuff in there !

First thing to know is that everytime we start working with a new object that will go on the form, we must tell the script to create it like this:

Code (Text):

1. "Variable Name := Object Name".Create(variable name of the form)

Again, all code after this one starting with the object name is properties witch we will modify to our taste and must be inside the InitForm like the form.

We will start with the textbox:

Code (Text):

1.   txtMessage := TEdit.Create(frmDesign);   //Create the textbox
2.   txtMessage.Parent := frmDesign;   //Add the textbox to the form
3.   txtMessage.Left := 100;   //How many pixels from the left of the form
4.   txtMessage.Top := 50;   //How many pixels from the top of the form
5.   txtMessage.Width := 150;   //Lenght of the textbox
6.   txtMessage.Height := 25;   //Height of the textbox

And the button:

Code (Text):

1.   cmdDisplayMessage := TButton.Create(frmDesign);   //Create the button
2.   cmdDisplayMessage.Parent := frmDesign;   //Add the button to the form
3.   cmdDisplayMessage.Left := 125;   //How many pixels from the left of the form
4.   cmdDisplayMessage.Top := 150;   //How many pixels from the top of the form
5.   cmdDisplayMessage.Width := 100;   //Width of the button
6.   cmdDisplayMessage.Height := 25;   //Height of the button
7.   cmdDisplayMessage.Caption := 'GO !';   //What's on the label of the button

After all those steps, our script should look like this:

Code (Text):

1. Program UsingForm;
2.  
3. Var
4.   frmDesign : TForm;   //The form itself
5.   txtMessage : TEdit;   //The textbox
6.   cmdDisplayMessage : TButton;   //The button
7.  
8. Procedure InitForm;
9. Begin
10.   frmDesign := CreateForm;   //Create the form
11.   frmDesign.Left := 500;   //How many pixels from the left of the screen
12.   frmDesign.Top := 100;   //How many pixels from the top of the screen
13.   frmDesign.Width := 350;   //The width of the window
14.   frmDesign.Height := 250;   //The height of the window
15.   frmDesign.Caption := 'Hello World !';   //The title of the window
16.   frmDesign.Visible := False;   //Need to be "false" if we want to call the form within a thread
17.   txtMessage := TEdit.Create(frmDesign);   //Create the textbox
18.   txtMessage.Parent := frmDesign;   //Add the textbox to the form
19.   txtMessage.Left := 100;   //How many pixels from the left of the form
20.   txtMessage.Top := 50;   //How many pixels from the top of the form
21.   txtMessage.Width := 150;   //Lenght of the textbox
22.   txtMessage.Height := 25;   //Height of the textbox
23.   cmdDisplayMessage := TButton.Create(frmDesign);   //Create the button
24.   cmdDisplayMessage.Parent := frmDesign;   //Add the button to the form
25.   cmdDisplayMessage.Left := 125;   //How many pixels from the left of the form
26.   cmdDisplayMessage.Top := 150;   //How many pixels from the top of the form
27.   cmdDisplayMessage.Width := 100;   //Width of the button
28.   cmdDisplayMessage.Height := 25;   //Height of the button
29.   cmdDisplayMessage.Caption := 'GO !';   //What's on the label of the button
30. End;
31.  
32. Procedure SafeInitForm;
33. Var
34.   v: TVariantArray;
35. Begin
36.   SetArrayLength(V, 0);
37.   ThreadSafeCall('InitForm', v);  //Important part: call the InitForm (your GUI)
38. End;
39.  
40. Procedure ShowFormModal;
41. Begin
42.   frmDesign.ShowModal;   //Make the GUI visible
43. End;
44.  
45. Procedure SafeShowFormModal;
46. Var
47.   v: TVariantArray;
48. Begin
49.   SetArrayLength(V, 0);
50.   ThreadSafeCall('ShowFormModal', v);   //Important part: make the GUI visible using ShowFormModal
51. End;
52.  
53. Begin
54.   SafeInitForm;   //Initialize the form using the threading function
55.   SafeShowFormModal;   //Make the form visible using the threading function
56. End.

Chapter Five: Adding Code To The Button

Now, we want the button to display "Hello World !" in the textbox when we press it. To do so, we need to tell the button what happen when it's beeing click using the "@".

Code (Text):

1. "variable name".onClick := @"procedure to call"

This code need to be in the InitForm again after all the parameters we coded for the button. SCAR will know that this button need to perform an action this way. In our script, the button will call the procedure ButtonClick.

Code (Text):

1.   cmdDisplayMessage.OnClick:= @ButtonClick;   //Call a procedure on click

This procedure need to be created. The trick here is that the procedure need to know who sent the command. To do this, we will add a little extra code into the procedure and this will able the script to modify the form even if the form was declared in a thread. But SCAR beeing... well, SCAR, we need to put this procedure BEFORE the InitForm or the button won't be able to call it. (FYI, it's like this for all procedure. You can't call a procedure if the code is after the "caller" in the script")

Code (Text):

1. Procedure ButtonClick(sender: TObject);
2. Begin
3.   txtMessage.text := 'Hello World !';   //Change the text in the textbox
4. End;

The code should look like this at this point:

Code (Text):

1. Program UsingForm;
2.  
3. Var
4.   frmDesign : TForm;   //The form itself
5.   txtMessage : TEdit;   //The textbox
6.   cmdDisplayMessage : TButton;   //The button
7.  
8. Procedure ButtonClick(sender: TObject);
9. Begin
10.   txtMessage.text := 'Hello World !';   //Change the text in the textbox
11. End;
12.  
13. Procedure InitForm;
14. Begin
15.   frmDesign := CreateForm;   //Create the form
16.   frmDesign.Left := 500;   //How many pixels from the left of the screen
17.   frmDesign.Top := 100;   //How many pixels from the top of the screen
18.   frmDesign.Width := 350;   //The width of the window
19.   frmDesign.Height := 250;   //The height of the window
20.   frmDesign.Caption := 'Hello World !';   //The title of the window
21.   frmDesign.Visible := False;   //Need to be "false" if we want to call the form within a thread
22.   txtMessage := TEdit.Create(frmDesign);   //Create the textbox
23.   txtMessage.Parent := frmDesign;   //Add the textbox to the form
24.   txtMessage.Left := 100;   //How many pixels from the left of the form
25.   txtMessage.Top := 50;   //How many pixels from the top of the form
26.   txtMessage.Width := 150;   //Lenght of the textbox
27.   txtMessage.Height := 25;   //Height of the textbox
28.   cmdDisplayMessage := TButton.Create(frmDesign);   //Create the button
29.   cmdDisplayMessage.Parent := frmDesign;   //Add the button to the form
30.   cmdDisplayMessage.Left := 125;   //How many pixels from the left of the form
31.   cmdDisplayMessage.Top := 150;   //How many pixels from the top of the form
32.   cmdDisplayMessage.Width := 100;   //Width of the button
33.   cmdDisplayMessage.Height := 25;   //Height of the button
34.   cmdDisplayMessage.Caption := 'GO !';   //What's on the label of the button
35.   cmdDisplayMessage.OnClick := @ButtonClick;   //Call a procedure on click
36. End;
37.  
38. Procedure SafeInitForm;
39. Var
40.   v: TVariantArray;
41. Begin
42.   SetArrayLength(V, 0);
43.   ThreadSafeCall('InitForm', v);  //Important part: call the InitForm (your GUI)
44. End;
45.  
46. Procedure ShowFormModal;
47. Begin
48.   frmDesign.ShowModal;   //Make the GUI visible
49. End;
50.  
51. Procedure SafeShowFormModal;
52. Var
53.   v: TVariantArray;
54. Begin
55.   SetArrayLength(V, 0);
56.   ThreadSafeCall('ShowFormModal', v);   //Important part: make the GUI visible using ShowFormModal
57. End;
58.  
59. Begin
60.   SafeInitForm;   //Initialize the form using the threading function
61.   SafeShowFormModal;   //Make the form visible using the threading function
62. End.

Chapter Six: Nice To Have...

The script is pretty much done. But I added this section just for 1 line of code simply because this line is very usefull.

Code (Text):

1. "variable name".ModalResult:= mrOk;

This code will simply close the form and terminate the script once executed. We need to use it on the form variable directly.

Code (Text):

1.   frmDesign.ModalResult:= mrOk;   //Close the form and terminate the script

Script Example

This is the final release of the script ! Congratulation !

Code (Text):

1. Program UsingForm;
2.  
3. Var
4.   frmDesign : TForm;   //The form itself
5.   txtMessage : TEdit;   //The textbox
6.   cmdDisplayMessage : TButton;   //The button
7.  
8. Procedure ButtonClick(sender: TObject);
9. Begin
10.   txtMessage.text := 'Hello World !';   //Change the text in the textbox
11. End;
12.  
13. Procedure InitForm;
14. Begin
15.   frmDesign := CreateForm;   //Create the form
16.   frmDesign.Left := 500;   //How many pixels from the left of the screen
17.   frmDesign.Top := 100;   //How many pixels from the top of the screen
18.   frmDesign.Width := 350;   //The width of the window
19.   frmDesign.Height := 250;   //The height of the window
20.   frmDesign.Caption := 'Hello World !';   //The title of the window
21.   frmDesign.Visible := False;   //Need to be "false" if we want to call the form within a thread
22.   txtMessage := TEdit.Create(frmDesign);   //Create the textbox
23.   txtMessage.Parent := frmDesign;   //Add the textbox to the form
24.   txtMessage.Left := 100;   //How many pixels from the left of the form
25.   txtMessage.Top := 50;   //How many pixels from the top of the form
26.   txtMessage.Width := 150;   //Lenght of the textbox
27.   txtMessage.Height := 25;   //Height of the textbox
28.   cmdDisplayMessage := TButton.Create(frmDesign);   //Create the button
29.   cmdDisplayMessage.Parent := frmDesign;   //Add the button to the form
30.   cmdDisplayMessage.Left := 125;   //How many pixels from the left of the form
31.   cmdDisplayMessage.Top := 150;   //How many pixels from the top of the form
32.   cmdDisplayMessage.Width := 100;   //Width of the button
33.   cmdDisplayMessage.Height := 25;   //Height of the button
34.   cmdDisplayMessage.Caption := 'GO !';   //What's on the label of the button
35.   cmdDisplayMessage.OnClick := @ButtonClick;   //Call a procedure on click
36. End;
37.  
38. Procedure SafeInitForm;
39. Var
40.   v: TVariantArray;
41. Begin
42.   SetArrayLength(V, 0);
43.   ThreadSafeCall('InitForm', v);  //Important part: call the InitForm (your GUI)
44. End;
45.  
46. Procedure ShowFormModal;
47. Begin
48.   frmDesign.ShowModal;   //Make the GUI visible
49. End;
50.  
51. Procedure SafeShowFormModal;
52. Var
53.   v: TVariantArray;
54. Begin
55.   SetArrayLength(V, 0);
56.   ThreadSafeCall('ShowFormModal', v);   //Important part: make the GUI visible using ShowFormModal
57. End;
58.  
59. Begin
60.   SafeInitForm;   //Initialize the form using the threading function
61.   SafeShowFormModal;   //Make the form visible using the threading function
62. End.

The End

Hope this tutorial helped you with your coding. This still is a very small idea of what SCAR can do for us. I'm currently trying to code a small game with scar using the debug/canvas window but there's so much more things involve when getting into this kind of coding.

Anyway, I apologize for any typo, weird words, unreadable sentences: english is not my main language and I'm not perfect so if you see any problem with this tutorial, let me know so I can fix it.

I'm also open to questions for SCAR so go ahead, challenge me !