PHP WinBinder: Template

From The Uniform Server Wiki
Revision as of 07:19, 28 January 2010 by Ric (talk | contribs) (New page: {{Nav PHP WinBinder}} '''''Windows application template''''' If you don’t like Uniform Server’s control interface solution is to create you own windows application to replace it. WinB...)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

 

UniServer 5-Nano
PHP WinBinder.

Windows application template

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

There are two tutorials in this series these 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.

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

Top

How to create a Windows application

If you have created a Windows application using another program you will appreciate the complexity WinBinder hides 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 it masks everything of 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 in reality 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 see Run Window App Batch File.

Top

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 widow 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 an handler. Hence Assign handler to main window. Note 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 (does not apply to any functions after it).

function process_main($window, $id)  

The handler function process all events occurring in our window $window, each event produces an ID any event not handled is passed onto a default system handler.

switch($id)  

The handler consists of a switch statement each case corresponds to a specific ID. In this example a single case is shown IDCLOSE this constant is set to 8 closing a window (clicking cross top right) sends ID 8 to the handler.

wb_destroy_window($window);

Every program must include this function it destroys 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 hence 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 hence 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.

Top

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

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

The above 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