win.form Usage Guide - How to Create Windows and Add Controls

1. Form Designer

In aardio, there are several methods to create window interface applications:

Click the "New Form Designer" quick icon in the top-left corner of the development environment, or press Ctrl + Shift + N to create a blank form.
Open the Project Wizard, select "Window Application", choose any window project template, and click "Create Project".
After creating the project, right-click a project directory and select "New File/New Form Designer" to create a window.

By default, forms open in "Design View" in the Form Designer. You can select controls from the "Interface Controls" panel at the bottom-left and drag them onto the form.

Click the form or controls to set properties in the right-side properties panel.

Switch to "Code View" using Ctrl + U or by double-clicking controls to add event handlers (default oncommand event varies by control).

2. Code Structure Generated by Form Designer

Example code for a form with button and textbox:

import win.ui;
/*DSG{{*/
var winform = win.form({ text="Window Title";right=759;bottom=469 })
winform.add({
button1={cls="button";text="Button";left=550;top=414;right=701;bottom=458;z=1};
edit1={cls="edit";text="Edit";left=22;top=16;right=735;bottom=398;edge=1;multiline=1;z=2}
})
/*}}*/

winform.show();
win.loopMessage();

Key points:

Code between /*DSG{{*/ and /*}}*/ is auto-generated and should not be manually modified
Use separate files for multiple windows (see Multi-Window Applications)
win.form class must be imported via win.ui

3. Create Form Objects with `win.form` Class

Prototype:

var winform = win.form(formPropertiesTable)

Explanation:

The parameter formPropertiesTable is a table object.
The key-value pairs contained in formPropertiesTable define the properties of the window.

In practice, formPropertiesTable represents the collection of window properties set in the form designer.

The win.form function returns a winform object. In aardio, form windows are typically named winform by convention, with the exception that the first main window of a program is usually assigned to the global variable mainForm.

In aardio documentation, the term winform is generally used to refer to any window object created by win.form, regardless of its specific naming.

Example:

var winform = win.form({text="Window Title"; right=759; bottom=469 })

In aardio, when a function parameter is a table object constructor, and the first element appears as a key-value pair separated by an equal sign, the outer curly braces can be omitted.For example, the above code can be simplified as:

var winform = win.form( text="Window Title"; right=759; bottom=469 )

Note that this parameter writing style for win.form is not using named parameters, but rather a table parameter with omitted outer {} symbols. aardio does not support named parameters.

When the constructor parameters of win.form do not specify left and top coordinates,default values of -1 will be used, which centers the window on the screen. In this case, the window width and height will be right + 1 and bottom + 1 respectively.

If left and top values are less than or equal to -2, the window will use the origin coordinates obtained after being displayed in the bottom-right corner of the screen.
If left and top values are greater than or equal to 0,
coordinates will be counted normally from the top-left corner of the screen.

4. Add Controls with `winform.add`

4.1 Prototype

winform.add = function(controlsPropertiesTable) {
    /*
    `controlsPropertiesTable` is a key-value pair defining a collection of controls.  
    The key names represent the access names for controls, and their corresponding values are table objects describing each control's properties.  
    Format: {ControlAccessName = {ControlPropertyTable}, ...}  
    */
}

4.2 Description

The controlsPropertiesTable parameter is a table object. The key-value pairs within controlsPropertiesTable define one or more controls.

Key names specify the access names for controls through the winform object (e.g., winform.button1).
Values are table objects describing each control's properties (design-time attributes set in the form designer).

Each control's property table (e.g., button1={...}) includes attributes like cls (control class), text (display text), position parameters (left, top, right, bottom), and z (Z-order).

4.3 Example

import win.ui; 
var winform = win.form({ text="Window Title"; right=759; bottom=469 });

winform.add({
    button1={ // Access name: winform.button1
        cls="button"; // Use win.ui.ctrl.button class
        text="Add first button (button1) to winform.button1"; // Caption
        left=264; top=410; right=469; bottom=454; // Position
        z=1 // Z-order
    };
    button2={ // Access name: winform.button2
        cls="button"; 
        text="Add second button (button2) to winform.button2";
        left=499; top=410; right=688; bottom=454;
        z=2 
    };
    edit1={ // Access name: winform.edit1
        cls="edit"; // Use win.ui.ctrl.edit class
        text="Add first edit box (edit1) to winform.edit1"; 
        left=386; top=16; right=739; bottom=398;
        edge=true; multiline=true; z=3 // Border, multiline
    };
    edit2={ // Access name: winform.edit2
        cls="edit"; 
        text="Add second edit box (edit2) to winform.edit2";
        left=22; top=16; right=375; bottom=398;
        edge=true; multiline=true; z=4 
    }
});

The above code creates four controls:

winform.button1
winform.button2
winform.edit1
winform.edit2

Key Points:

Control names in controlsPropertiesTable (e.g., button1) become member names of the winform object.
The winform.add function adds these names to the winform object for later access (e.g., winform.button1).
Design-time properties (e.g., text, left) correspond to runtime properties documented in control reference guides.
In the form designer view, you can visually configure these properties and switch to code view to see generated details.

Here are several of the most important properties to consider when designing controls:

left: The left coordinate relative to the client area of the parent window, specified as a design-time coordinate. Therefore, the control's creation parameters use design-time coordinates, and the runtime coordinates are calculated based on the design-time coordinates. aardio windows support automatic scaling and coordinate adjustment. By default, the position and size of the window and controls are automatically adjusted based on the system DPI scaling settings.
top: The top coordinate relative to the client area of the parent window, specified as a design-time coordinate.
right: The right coordinate relative to the client area of the parent window, specified as a design-time coordinate.
bottom: The bottom coordinate relative to the client area of the parent window, specified as a design-time coordinate.
dl: Whether the left side is fixed relative to the left margin of the parent window. If it is a decimal, the current margin is calculated as a percentage of the parent window's width.
dt: Whether the top side is fixed relative to the top margin of the parent window. If it is a decimal, the current margin is calculated as a percentage of the parent window's height.
dr: Whether the right side is fixed relative to the right margin of the parent window. If it is a decimal, the current margin is calculated as a percentage of the parent window's width.
db: Whether the bottom side is fixed relative to the bottom margin of the parent window. If it is a decimal, the current margin is calculated as a percentage of the parent window's height.
cls: All controls must specify a cls, which corresponds to the class name in the win.ui.ctrl namespace. For example, cls="button" specifies that win.ui.ctrl.button is called to create a button control. cls is referred to as the design-time class name. After the control is created, a className property is generated to record the runtime class name, which is typically different. For instance, after win.ui.ctrl.tab is created, the runtime class name becomes "SysTabControl32", which is actually a system control class name provided by the operating system.

The aardio standard provides the following common control class names in win.ui.ctrl namespace:

custom A custom control that can be used to load other forms or as a container for other forms, and is the only control in the form designer that can have its cls property changed to another control class. Usage Guidelines
static static text control
button control
radiobutton radio button, checked property indicates whether or not it is checked.
checkbox A checkbox control with the checked property indicating whether the checkbox is selected or not.
combobox combobox control, the items property gets or sets an array of strings (list data). Example: Autocomplete effect
listbox listbox, the items property gets or sets an array of strings (list data).
listview The items property returns or sets an array of all the list items, each item in the array represents a row, each row must also be an array of columns of text, and the returned array has an optional field checked that contains all the checked rows.
checklist This is a listbox with checkboxes based on the listview control.
treeview Treeview control
splitter splitter bar control. Use the control's split function to split multiple controls. The argument can also be an array of controls, each of which must contain controls on the same side of the splitter bar.
tab A simple tab control with a simple style. Example . Advanced tabs (win.ui.tabs) can be used instead if you have more needs.
syslink The text file property of this control supports the HTML syntax of hyperlinks and can contain either plain text or multiple hyperlinks. Examples
atlax is used to create a COM control by specifying the class name in the text field of the parameter list. Examples
bk background control, no handles does not create an actual window, only used for background layout, uses GDI drawing.
bkplus advanced background control, no handles does not create an actual window, only for background layout, uses GDI+ drawing. Examples
calendar A calendar control, the time property is used to get or set the time object.
datetimepick The datetime control, the time property is used to get or set the time object.
ipaddress IP address control, the text property is in text format for IP addresses and the address property is in numeric format for IP addresses.
hotkey The hotkey control, the value property is used to get or set the settings, the value is an array representing the hotkey configuration.
edit Textbox control.
richedit rich textbox control, supports transparent background, text property reads and writes normal text, rtf property reads and writes RTF formatted text. Examples
picturebox image control, the image property sets the image path or image data, does not support png or animated gifs.
plus Advanced image control, support png or animated gif, can set rich appearance styles, different configurations to simulate different types of controls. Most commonly used in aardio. Guides
progress The progress bar control. Examples
spin Fine-tuning button with scrollable selection of values, buddy property setting, get-partner edit control. Examples
pick The color picker control. Example
vlistview dummy list control. Example
trackbar The trackbar control. Example

4.4 The return value of `winform.add`

Although winform.add has a return value, we don't usually use it.

The return value of winform.add has the same structure as the incoming parameter, if controlsPropertiesTable is passed then it returns the same table with control name-value pairs, except that the value corresponding to the name of the control is changed to the created control object.

Usually it is not necessary to use the return value of winform.add, you should access the control through winform. For example, use winform.button1, winform.edit1 in your code to access a control that has been added to a winform window, the benefit of this is that the form designer will provide better intelligent hints for this type of access.

5. Advanced Usage & Hidden Parameters

The win.form constructor and winform.add have some uncommon uses and hidden parameters to solve some less common needs. These parameters are demonstrated and annotated in detail in aardio's “Examples / Windowns Windows / Basics”, or you can check out the library reference manual, which will serve as an introductory guide.

As an introductory guide, we won’t go into too much detail here.

Referer:

Creating a Window with Hidden Parameters

Dynamic creation of controls

6. Create Window Example

// Import win.form window class from win.ui library
import win.ui;

/*DSG{{*/
	
// Create window
var winform = win.form(text="Do not omit the window title";right=763;bottom=425)

// Multiple controls should be added with a single call to winform.add
winform.add({// When a function has only one table parameter, the outer {} can be omitted
	
	// Specify control access name as winform.button1 (mandatory)
	button1={
		cls="button"; // Create button control using win.ui.ctrl.button class (mandatory)
		text="Click me"; // Button text
		left=556;top=367; // Top-left coordinates
		right=689;bottom=407; // Bottom-right coordinates
		z=1 // Z-order
	};
	
	// Specify control access name as winform.edit1 (mandatory)
	edit1={
		cls="edit"; // Create textbox using win.ui.ctrl.edit class (mandatory)
		text="Input text"; // Default text
		left=9;top=10; // Top-left coordinates
		right=752;bottom=351; // Bottom-right coordinates
		multiline=1; // Enable multiline
		z=2 // Z-order (optional)
	}
})
/*}}*/

// Set button click event handler
winform.button1.oncommand = function(id, event) {
    // Output numbers 1-10 to edit control
    for(i=1; 10; 1) {
        // Note that edit uses '\r\n' for line breaks, while richedit uses '\n'
        winform.edit1.appendText(i,'\r\n'); 
    }
};
	
// Display window
winform.show();

// Start UI message loop
win.loopMessage();

This example first imports the win.form class from the win.ui library, then creates a window with specified title, and then adds a button and textbox.

When button clicked, print number 1 to 10 with line breaks to the textbox. Finally, it displays the window and enters the message loop to handle user interactions.

When user click the button, winform.button1.oncommand event callback is triggered. For details see: [aardio Example: Handling Control Commands]

7. Frameless Window

border

Use the border parameter in win.form constructor to specify window border style:

var winform = win.form(text="Frameless Window (No Title Bar)";border="none")

Valid border values:

"none": Frameless window without title bar
"resizable": Default resizable border (explicit declaration optional)
"dialog frame": Non-resizable dialog-style frame (requires title bar)
"thin": Thin border for titlebar-less windows (non-resizable)

title

Use title parameter to control title bar visibility:

var winform = win.form(text="Thin Border + No Title Bar";border="thin";title=false)

The title field is only valid for windows with borders (Frameless windows must not have a title bar), and the default value of the title field for windows with borders is true, so you don't need to specify it explicitly.

If you don't use the text field to specify the title text in the constructor parameter of win.form, it will also cause the window not to display the title bar. Without a title bar, the user cannot find the close window button that was originally displayed in the title bar, and the user can only close the window via AL + F4, so it is generally not recommended to omit the text field from the window creation parameter. Even for windows without borders or title bars, it is generally recommended to give the window a suitable title.

The purpose of creating a borderless window is usually to customize the title bar and border yourself. aardio provides a simple example library win.ui.simpleWindow.

Usage demo:

import win.ui;

// Create frameless window
var winform = win.form(text="aardio form";border="none")

// Add title bar background
winform.add(
bkTitleBar={cls="bk";left=0;top=0;marginRight=0;bottom=30;bgcolor=8421504;dl=1;dr=1;dt=1;z=1}
) 

// Add shadow border and title bar
import win.ui.simpleWindow;
win.ui.simpleWindow(winform);

winform.show();
win.loopMessage();

See win.ui.simpleWindow library source code to learn how to customize borderless windows.

On a borderless window, the following function is called to simulate title bar button actions:

winform.hitMax()    // Maximize button
winform.hitMin()    // Minimize button
winform.hitClose()  // Close button
winform.hitCaption()// Title bar drag

References:

[Frameless Window Example]
[Web View Frameless Example]

1. Form Designer​

2. Code Structure Generated by Form Designer​

3. Create Form Objects with win.form Class​

4. Add Controls with winform.add​

4.1 Prototype​

4.2 Description​

4.3 Example​

4.4 The return value of winform.add​

5. Advanced Usage & Hidden Parameters​

6. Create Window Example​

7. Frameless Window​

border​

title​