PHP WinBinder: Template

UniServer 5-Nano
PHP WinBinder.

Windows application template

If you don’t like Uniform Server’s control interface, the solution is to create you own windows application to replace it. WinBinder is a perfect match, because it allows you to write a Windows application in PHP which can tap into Uniform Server’s control core, also written in PHP.

There are two tutorials in this series that provide a step-by-step guide to producing a Windows application using WinBinder. In the main, it’s a copy and paste exercise with a bit of scripting thrown in.

Each Windows application starts with a basic script (template). This page covers the design of a basic windows application and how to run it. It concludes with a working template. The template is used for all examples in the rest of the tutorial.

Top

How to create a Windows application

If you have created a Windows application using another program you will appreciate how WinBinder hides the complexity from a user.

The following PHP code creates a Windows application.

Admittedly the application does absolutely nothing other than having the ability to close the window. See Windows Template for a working example of this code.

<?php
Include "../php/include/winbinder.php";          // Location Of Winbinder Library

$mainwin = wb_create_window(NULL, AppWindow, "XXX", 320, 240); // Create main window

wb_set_handler($mainwin, "process_main");        // Assign handler to main window. 
wb_main_loop();                                  // Enter application loop 

function process_main($window, $id)              // The handler function
{
  switch($id) { 

   case IDCLOSE:                                 // Constant IDCLOSE (8) predefined 
    wb_destroy_window($window);                  // Destroy the window
    break; 
  }
}
?>

This really is an elegant script because it masks all the complexity associated with creating a Windows application.

It produces a blank window (canvas) which is fully functional. All that is required is to add user functionality in terms of input and output.

An understanding of the underlying code is not essential to using this template. Just consider it a tool to be used and worry about any detail later.

To run the above script, navigate to folder UniServer\plugins\winbinder\examples and double click on the batch file test_1.bat. This runs the script test_1.phpw containing the above code.

Note:

Ignore the command window that opens it is there only for testing and development.

Note: Closing the command window also closes your Windows application. This will be addressed later in Run Window App Batch File.

Basic Script operation

Include "../php/include/winbinder.php";	Every Windows script you create must contain this line. It pulls in all the WinBinder functions. If your script is located in another folder, change the path accordingly.
$mainwin=wb_create_window(NULL,AppWindow,"XXX",320,240);	This function creates an application window with title XXX (change this to something meaningful). The window will have a width of 320 pixels and height of 240; again, these are changeable.
wb_set_handler($mainwin,"process_main");	Generally every window action (mouse movement, button click) requires processing. This is performed by a single function assigned to the main window. The function receives the ID of an event that requires processing. The function "process_main" is referred to as a handler. Hence Assign handler to main window. Note that if this function cannot handle the request it is passed onto a system default handler.
wb_main_loop();	This function effectively keeps the window alive. The call to wb_main_loop() must be the last executable statement of the PHP script. All statements after it will be ignored (this does not apply to any functions after it).
function process_main($window, $id)	The handler function processes all events occurring in our window $window. Each event produces an ID. Any event not handled is passed on to a default system handler.
switch($id)	The handler consists of a switch statement with each case corresponding to a specific ID. In this example a single case is shown: IDCLOSE. This constant is set to 8. Closing a window (clicking the "X" in the top right corner) sends ID 8 to the handler.
wb_destroy_window($window);	Every program must include this function. It terminates the window and performs a clean-up operation

Top

Command Window (cmd)

All Window applications in this tutorial are designed to replace the command window and provide a more effective user interface.

In addition I want to avoid any compiling, so to launch these Windows applications, a batch file is used.

It may seem a negative step, however any errors produced are written to standard I/O, i.e., to a batch file command window (cmd).

This method aids in debugging code.

Each test's batch file contains code similar to this:

Batch File for running PHP scripts



..\php\php.exe -c ..\php\php-wb.ini test_1.phpw

pause

..\php\php.exe - Move up one folder level and down into folder php
run PHP CLI interface program php.exe
-c ..\php\php-wb.ini - Force PHP to use configuration file php-wb.ini
test_1.phpw - PHP script to run (note extension phpw you can use php)

pause - Do not close command window until a key is pressed

Using batch files removes a need to create file associations in order to run scripts.

Relative paths are used in the batch files this allows scripts to be portable.

Window App Batch File

The above batch file is ideal for testing and debugging. Once you have working code, use the following batch file.

Change the above code to use php-win.exe, which runs your final application without displaying a command window:



start ..\php\php-win.exe -c ..\php\php-wb.ini test_1.phpw

Replace script and paths as appropriate.
To see a working example:
- Navigate to folder UniServer\plugins\winbinder\examples
- Double click on file test_1a.bat
Close Windows application (cross top right)

Note: You will see an annoying flicker produced by the command window opening and closing. This issue will be addressed later.

Top

Windows Template

All test examples used in this tutorial use file test_1.phpw as a template. It is generic hence can be used for starting any new design.

The file is divided into sections. These are required for all windows applications.

<?php
Include "../php/include/winbinder.php";       // Location Of Winbinder Library

//=== 1) Create main window ---------------------------------------------------
$mainwin = wb_create_window(NULL, AppWindow, "Test 1", 320, 240);

//=== 2) Create controls for the main window ----------------------------------

//=== 3) Assign handler function to the main window  --------------------------
wb_set_handler($mainwin, "process_main");       

//=== 5) Enter application loop -----------------------------------------------
wb_main_loop();                                  

//=== 4) Handler Function -----------------------------------------------------
function process_main($window, $id) 
{
  switch($id) { 

   case IDCLOSE:                          // Constant IDCLOSE (8) predefined 
    wb_destroy_window($window);           // Destroy the window
    break; 
  }
}
?>

Window produced by script

The above window is a blank application.
It has two active controls
Minimise button - A default handler perfoms the operation
A close button - Intercepted by our handler which destroys the window

Top

Summary

This introduced WinBinder and demonstrated how easy it is to create a basic Windows application.

Each Windows application starts with a basic script (template), additional components are required to make it do something useful.

Remainder of this tutorial looks at these additional components.

Basic input/output components are covered on the next page these provide a simple user interface.

Top