Event Handling

This page explains how to handle events -- that is, how to respond when a user interacts with GUI components in a VCSSL program.

Event-Driven Programming

Up to this point, VCSSL programs have been executed based on a predetermined, linear flow of instructions.

However, in GUI-based programs, actions like clicking a button or moving the mouse require specific responses. Since you can't predict when these actions will happen, you need to shift your mindset from "a fixed flow of instructions" to "reacting to things as they happen."

This is where event-driven programming comes in. VCSSL's GUI system follows a typical event-driven programming model.

What is an Event?

An event is something that "happens" and triggers a response. In other words, it's the "something happening" in the phrase: "do something when something happens."

For example, "a user clicks a button" or "the mouse is moved" are both considered events.

Event Handler Functions

When an event occurs, the system automatically calls a specific function in your program to respond to it. These functions are called event handler functions.

Concept Diagram of Event Handlers

When an event occurs -- such as a button being clicked -- the corresponding event handler function is called.

You define the contents of event handler functions yourself, so you can write whatever behavior is appropriate for your application.

No Manual Registration Required -- Just Declare the Function

In VCSSL, event handler functions are recognized automatically based on their function names and parameters, depending on the type of event. You don't need to manually register them anywhere.

Common Characteristics of Event Handlers

All event handler functions in VCSSL follow the same general pattern:

• Inside the function, you write the logic to execute when the event occurs.
• Event-related information is passed in as arguments. The number and type of arguments depend on the specific handler.
• Most handlers return "void", meaning they don't return a value.

Let's take a look at some actual events and how to define handler functions for them.

Handling Window Events

To handle events related to windows, you define the following event handler functions:

Arguments:

• id: The component ID of the window where the event occurred.
• width, height: The window's new size, if applicable.

Among these, the "onWindowClose" function is particularly important. Inside this function, if you call the exit() function, you can implement the common behavior of "exit the program when the window is closed."

Previously, VCSSL programs could only be terminated by manually closing the VCSSL console. But if you add this logic, the program can exit automatically when the window is closed -- making the console unnecessary. In that case, you can simply hide it with the hide() function.

Handling Button Events

To handle events related to buttons, define the following function:

Arguments:

• id: The component ID of the button that was clicked.
• text: The text label of the button.

Handling Select Field Events

To handle events related to select fields, define the following function:

Arguments:

• id: The component ID of the select field.
• text: The selected option text.

Handling Checkbox Events

To handle events related to checkboxes, define the following function:

Arguments:

• id: The component ID of the checkbox.
• state: The new ON/OFF state (true or false).

Handling Key Events

When the user presses a keyboard key while interacting with a GUI component, a key event occurs.

To handle key events, use the following event handler functions:

Arguments:

• id: The component ID where the event occurred.
• key: A string representing the printed label of the key (e.g., "A" or "@").
• keyCode: A predefined integer constant uniquely identifying the key.

VCSSL provides both "string" and "int" variants of these handlers:

• The "string" variant is useful for simple cases, like appending key inputs to a text variable. For example, pressing the �gA�h key yields "A", and pressing the "@" key yields "@".
• The "int" variant uses constants like KEY_AT, KEY_ENTER, etc., which offer more strict and typo-resistant comparisons. These are better for larger programs where reliability is important.

Common Key Code Constants

Handling Mouse Events

Mouse events occur when the user interacts with a GUI component using the mouse -- by moving the cursor, clicking, dragging, or scrolling.

Since mouse interaction includes many types of actions, a variety of event handler functions are provided:

Arguments:

• id: The component ID where the event occurred.
• x, y: The mouse cursor's coordinates, relative to the top-left corner of the component.
• button: Indicates which mouse button was used. Use constants like MOUSE_LEFT, MOUSE_RIGHT, or MOUSE_MIDDLE.
• count: The number of times the button was clicked in succession (e.g., 1 for single-click, 2 for double-click). Use MOUSE_SINGLE, MOUSE_DOUBLE for clarity.
• degree: The scroll amount of the mouse wheel, in fine-grained units.

Example Code

Let's try using various event handler functions in an actual code. Type the code below and run it to see how it works:

import GUI ;
import Graphics ;


// =============================================
// GUI Component Setup - Start
// =============================================

//  Create a window at (x, y) = (300, 20) with width 360 and height 480
int windowID = newWindow( 300, 20, 360, 480, "Hello GUI" ) ;

// Create a button at (10, 10) with width 100 and height 50
int buttonID = newButton ( 10, 10, 100, 50, "PUSH" ) ;
mountComponent( buttonID, windowID ) ;

// Create a text field at (10, 70) with size 100 �~ 30
int textFieldD = newTextField( 10, 70, 100, 30, "INPUT" ) ;
mountComponent( textFieldD, windowID ) ;

// Create a text area at (120, 10) with size 200 �~ 200
int textAreaID = newTextArea( 120, 10, 200, 200, "INPUT" ) ;
mountComponent( textAreaID, windowID ) ;

// Create a select field at (10, 110) with size 100 �~ 20
string text[ 3 ] ;
text[ 0 ] = "TYPE-A";
text[ 1 ] = "TYPE-B";
text[ 2 ] = "TYPE-C";
int selectFieldID = newSelectField( 10, 110, 100, 20, text ) ;
mountComponent( selectFieldID, windowID ) ;

// Create a checkbox at (10, 140) with size 100 �~ 20
int checkBoxID = newCheckBox( 10, 140, 100, 20, "TURBO", true ) ;
mountComponent( checkBoxID, windowID ) ;

// Create a text label at (10, 170) with size 100 �~ 20
int textLabelID = newTextLabel( 10, 170, 100, 20, "Hello GUI ! " ) ;
mountComponent( textLabelID, windowID ) ;

// Load an image file named "Test.png"
int graphicsID = newGraphics( "Test.png" ) ;
// Create an image label at (10, 220) with size 310 �~ 200
int imageLabelID = newImageLabel( 10, 220, 310, 200, graphicsID ) ;
mountComponent( imageLabelID, windowID ) ;

// =============================================
// GUI Component Setup - End
// =============================================


// =============================================
// Event Handlers - Start
// =============================================

// Called when the window is closed
void onWindowClose( int id ){
	alert( "The program will now exit." ) ;
	exit( );
}

// Called when the button is clicked
void onButtonClick( int id, string text ){
	alert( "Button \"" + text + "\" was clicked." ) ;
}

// Called when a select field option is selected
void onSelectFieldClick( int id, string text ){
	alert( "\"" + text + "\" was selected." ) ;
}

// Called when the checkbox is toggled
void onCheckBoxClick( int id, bool state ){
	alert( "Checkbox state changed to: " + state ) ;
}

// Called when the mouse is dragged
void onMouseDrag( int id, int x, int y, int button ){
	// Check which component was dragged
	if( id == imageLabelID ){
		// Check which mouse button was used
		if( button == MOUSE_RIGHT ){
			println( "Right drag - X=" + x + " Y=" + y ) ;
		}else if( button == MOUSE_LEFT ){
			println( "Left drag - X=" + x + " Y=" + y ) ;
		}
	}
}

// Called when the mouse is clicked
void onMouseClick( int id, int x, int y, int button, int count ){
	// Check which component was clicked
	if( id == imageLabelID ){

		// Check which mouse button was used
		if( button == MOUSE_RIGHT ){
			println( "Right click - X=" + x + " Y=" + y ) ;
		}else if( button == MOUSE_LEFT ){
			println( "Left click - X=" + x + " Y=" + y ) ;
		}

		// Check whether it was a double-click
		if( count == MOUSE_DOUBLE ){
			alert( "Double-click detected." );
		}

	}
}

// Called on key press (string-based)
void onKeyDown( int id, string key ){
	println( "Key pressed: " + key ) ;
}

// Called on key press (keycode-based)
void onKeyDown( int id, int keyCode ){
	if( keyCode == KEY_SPACE ){
		alert( "Space key was pressed." ) ;
	}
}

// =============================================
// Event Handlers - End
// =============================================

When you run this program, a window will appear with various GUI components placed on it. Interacting with the components will trigger the corresponding event handlers.

Execution Result

Note: This image is a mockup. The actual appearance may vary depending on the operating system, the version of the VCSSL runtime system, and other factors.