Beginners Tutorial

Getting Started

The basic procedure for using the KiXforms Library is as follows. First a form is created, then various graphical objects (controls) are placed onto it. The types of controls that can be placed on a form include buttons, checkboxes, comboboxes, listboxes, sliders and many more. After the form has been defined, it is displayed on the screen and control given to a library procedure called DoEvents(). This routine takes care of the interaction between the user and the form and returns as soon as some change occurs in the status of the form due to a user action. In this case control is returned to the script (indicating that the object changed) and the script can take action accordingly, after which control is once again returned to the DoEvents() routine.

The KiXforms Library is simple to use. Defining a form takes only a few lines of code and interaction is fully handled by the library routines. A number of demo programs are provided to show how to piece together various parts of the library and demonstrate how easy it is to build and use a form. Studying these demos is a good way of learning the system.

How do I create a form?

Always start with the following template code. This is the absolute barebones (minimum) KiXforms script. It may not seem like it does very much, but under the covers, these statements pack a lot of punch. Plus, by running this script first, it verifies that the library is properly installed and registered:

Break On

$System = CreateObject("Kixtart.System")

$Form = $System.Form()

$Form.Show

While $Form.Visible
  $ = Execute($System.Application.DoEvents)
Loop

Exit 1

[SCREENSHOT]

First, this script imports the System (root) namespace and then creates a new instance of a Form object and assigns it to a KiXtart variable called $Form. We will use $Form as a handle to our form throughout the rest of the script. A form (by default) is not visible to the user, so the next step is to show the form - we do this with the Show method. Now we need some way to start the form and query for events from the user. This is accomplished with a While loop and inside that, a method call to a function called DoEvents(). In a nutshell, what this construct is saying is “While our form is visible, execute the next event generated by the user”. Because our form has no visual controls, the only thing a user can do is close the form. When a form is closed, it becomes invisible or hidden - at which point the While condition will evaluate FALSE and the loop will stop and the script will terminate normally.

How do I change the title bar?

After the form is created, assign a string to the forms Caption property, like this:

$Form.Caption = "This is my first KiXforms script"

How do I change the size and location of a form?

You can change the size and location of your form using it's Left, Top, Width and Height properties, for example, here's a script that creates a form that is 300 pixels wide by 600 pixels high. It then centers the form on the screen using the Center method.

Break On

$System = CreateObject("Kixtart.System")

$Form = $System.Form()

$Form.Caption = "This is my first KiXforms script"
$Form.Width = 300
$Form.Height = 600
$Form.Center

$Form.Show

While $Form.Visible
  $ = Execute($System.Application.DoEvents)
Loop

Exit 1

[SCREENSHOT]

How do I change the color of a form?

Use the BackColor property and a form function called RGB. The RGB function allows you to specify your color in terms of its Red, Green and Blue color components. Here’s an example: suppose you want to set the background color to yellow. Yellow is made up of equal parts Red and Green, here the code:

Break On

$System = CreateObject("Kixtart.System")

$Form = $System.Form()

$Form.Caption = "This is my first KiXforms script"
$Form.Width = 300
$Form.Height = 600
$Form.Center
$Form.BackColor = $Form.RGB(255,255,0)

$Form.Show

While $Form.Visible
  $ = Execute($System.Application.DoEvents)
Loop

Exit 1

[SCREENSHOT]

How do I add a button to a form?

The form object has a create function for every control that you can place on a form. For example, if you wanted to add a command button to a form, use the CommandButton (or Button) function, like this:

Break On

$System = CreateObject("Kixtart.System")

$Form = $System.Form()

$Button = $Form.CommandButton

$Form.Show

While $Form.Visible
  $ = Execute($System.Application.DoEvents)
Loop

Exit 1

[SCREENSHOT]

How do I set the location of a button?

A command button has the same Left, Top, Width, Height and Caption properties that a Form has. In object oriented parlance, they call that “Poly-Morphism” – when objects share the same properties and behaviors. There are actually two ways of specifying the caption and location. In the object create function itself, or afterwards using each property separately. Here is an example that creates a command button and an option button using each method:

Break On

$System = CreateObject("Kixtart.System")

$Form = $System.Form()

$Button1 = $Form.CommandButton("Click Me!",10,10,100,25)

$Button2 = $Form.OptionButton
$Button2.Caption = "No - Select Me!"
$Button2.Left = 10
$Button2.Top = 50
$Button2.Width = 100
$Button2.Height = 25

$Form.Show

While $Form.Visible
  $ = Execute($System.Application.DoEvents)
Loop

Exit 1

[SCREENSHOT]

How do I make the button do something?

This is where the fun starts. To make the button do something when the user clicks it, you have to program the button OnClick event. You do this by placing kixtart code into the event property of the object itself. For example, lets say you want to change the background color of the form every time the user clicks a “Change Color” button. Here’s the code for that:

Break On

$System = CreateObject("Kixtart.System")

$Form = $System.Form()

$Button1 = $Form.CommandButton("Change Color!")
$Button1.Center

$Button1.OnClick = "Button1_Click()"

$Form.Show

While $Form.Visible
  $ = Execute($System.Application.DoEvents)
Loop

Exit 1

Function Button1_Click()
  $Form.BackColor = $Form.RGB(RND(255),RND(255),RND(255))
EndFunction

[SCREENSHOT]

What's going on here?

We put a function call into the OnClick event of our button. Every time the button is clicked, KiXtart executes a function call to Button1_Click(). Inside that function, we simply set the forms background color to some random color generated with the RGB and RND methods.

What now?

Study the documentation provided on this web site and deconstruct example scripts provided in the Script Archive and from various other sites. If you run into difficulties and have exhausted all the available options, then post a question to the KiXforms Bulletin Board. Have fun!