[ Prev | Index | Next ]
Japanese English

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.

Sponsored Link


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
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:

Function Name Arguments Triggered When...
onWindowOpen int id The window is opened
onWindowClose int id The window is closed
onWindowMove int id,
int x,
int y
The window is moved
onWindowResize int id,
int width,
int height
The window is resized
onWindowShow int id The window is shown
onWindowHide int id The window is hidden

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:

Function Name Arguments Triggered When...
onButtonClick int id,
string text
The button is clicked

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:

Function Name Arguments Triggered When...
onSelectFieldClick int id,
string text
A selection is made in the select field

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:

Function Name Arguments Triggered When...
onCheckBoxClick int id,
bool state
The checkbox is clicked

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.

Note:

Be careful about which GUI component the key event is triggered on.

For example, if a window contains text fields or other components that accept keyboard input, key events will be prioritized on those components.

In such cases, if you try to detect a key event on a neighboring graphics label or similar component, the event may not be captured correctly.

Similarly, if the window contains buttons or components that respond to specific keys (like the Enter key), other components might not receive those key events.

Therefore, if you want to use key events on a component like a text label or graphics label -- which normally doesn't accept keyboard input -- it is recommended not to place text-input components or buttons on the same window.

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

Function Name Arguments Triggered When...
onKeyDown int id,
string key
A key is pressed
onKeyDown int id,
int keyCode
A key is pressed
onKeyUp iint id,
string key
A key is released
onKeyUp iint id,
int keyCode
A key is released

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 gAh 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

Key Label Constant Key Label Constant
A - Z KEY_A - KEY_Z 0 - 9 KEY_0 - KEY_9
F1 - F12 KEY_F1 - KEY_F12 @ KEY_AT
/ KEY_SLASH
ENTER KEY_ENTER + KEY_PLUS
SPACE KEY_SPACE - KEY_MINUS
TAB KEY_TAB , KEY_COMMA
SHIFT KEY_SHIFT . KEY_PERIOD
CONTROL KEY_CONTROL ALT KEY_ALT
; KEY_SEMICOLON [ KEY_LEFT_SQUARE_BRACKET
^ KEY_CIRCUMFLEX ] KEY_RIGHT_SQUARE_BRACKET
UP KEY_UP DOWN KEY_DOWN
LEFT KEY_LEFT RIGHT KEY_RIGHT

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:

Function Name Arguments Triggered When...
onMouseOver int id,
int x,
int y
The mouse enters the component area
onMouseOut int id,
int x,
int y
The mouse leaves the component area
onMouseMove iint id,
int x,
int y
The mouse moves within the component area
onMouseCkick int id,
int x,
int y,
int button,
int count
A mouse click occurs (quick press-and-release)
onMouseDown int id,
int x,
int y,
int button
A mouse button is pressed
onMouseUp int id,
int x,
int y,
int button
A mouse button is released
onMouseDrag int id,
int x,
int y,
int button
The mouse is dragged with a button held down
onMouseScroll int id,
int degree
The mouse wheel is scrolled

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
// =============================================
EventSample.vcssl
[an error occurred while processing this directive]/en-us/code/archive/0001/7500-doc-gui-event/download/GUIEvent.zip[an error occurred while processing this directive]

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
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.


Sponsored Link



Japanese English
Index
News From RINEARN
* VCSSL is developed by RINEARN.

VCSSL 3.4.52 Released: Enhanced Integration with External Programs and More
2025-05-25 - This update introduces enhancements to the external program integration features (e.g., for running C-language executables). Several other improvements and fixes are also included. Details inside.

Released: Latest Version of VCSSL with Fixes for Behavioral Changes on Java 24
2025-04-22 - VCSSL 3.4.50 released with a fix for a subtle behavioral change in absolute path resolution on network drives, introduced in Java 24. Details inside.

Released the Latest Versions of RINEARN Graph and VCSSL - Now Supporting Customizable Tick Positions and Labels!
2024-11-24 - Starting with this update, a new "MANUAL" tick mode is now supported, allowing users to freely specify the positions and labels of ticks on the graph. We'll explain the details and how to use it.

Released Exevalator 2.2: Now Compatible with TypeScript and Usable in Web Browsers
2024-10-22 - The open-source expression evaluation library, Exevalator, has been updated to version 2.2. It now supports TypeScript and can be used for evaluating expressions directly in web browsers. Explains the details.

Behind the Scenes of Creating an Assistant AI (Part 1: Fundamental Knowledge)
2024-10-07 - The first part of a series on how to create an Assistant AI. In this article, we introduce the essential knowledge you need to grasp before building an Assistant AI. What exactly is an LLM-based AI? What is RAG? And more.

Launching an Assistant AI to Support Software Usage!
2024-09-20 - We've launched an Assistant AI that answers questions about how to use RINEARN software and helps with certain tasks. Anyone with a ChatGPT account can use it for free. We'll explain how to use it.

Software Updates: Command Expansion in RINEARN Graph, and English Support in VCSSL
2024-02-05 - We updated our apps. This updates include "Enhancing the Command-Line Features of RINEARN Graph" and "Adding English Support to VCSSL." Dives into each of them!

Inside the Repetitive Execution Speedup Impremented in Vnano Ver.1.1
2024-01-17 - Delves into the update in Vnano 1.1 from a developer's viewpoint, providing detailed insights into the specific improvements made to the internal structure of the script engine.