PHP WinBinder: Template: Difference between revisions

From The Uniform Server Wiki
Jump to navigation Jump to search
(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...)
 
m (Reverted edits by Upazixorys (Talk); changed back to last version by BobS)
 
(2 intermediate revisions by 2 users not shown)
Line 2: Line 2:
'''''Windows application template'''''
'''''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.
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 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.
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. From this starting point concludes with a working temple. This is used for all examples in the tutorial.
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 | Top]]'''''
'''''[[#top | Top]]'''''
== How to create a Windows application ==
== 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.  
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.
The following PHP code creates a Windows application.
Line 41: Line 41:
 
 
|
|
This really is an elegant script it masks everything of complexity associated with creating a Windows application.
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.
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.  
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.
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'':'''
'''''Note'':'''
Line 54: Line 54:
Ignore the command window that opens it is there only for testing and development.
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 | '''Run Window App Batch File''']].  
'''''Note'':''' Closing the command window also closes your Windows application. This will be addressed later in [[#Run Window App Batch File | '''Run Window App Batch File''']].  


'''''[[#top | Top]]'''''
=== Basic Script operation ===
=== Basic Script operation ===
{|
{|
Line 65: Line 64:
</pre>
</pre>
|
|
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.
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.
|-
|-
|
|
Line 72: Line 71:
</pre>
</pre>
|
|
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.  
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.  
|-
|-
|
|
Line 79: Line 78:
</pre>
</pre>
|
|
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.   
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.   
|-
|-
|
|
Line 86: Line 85:
</pre>
</pre>
|
|
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).   
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).   
|-
|-
|
|
Line 93: Line 92:
</pre>
</pre>
|
|
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.
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.
|-
|-
|
|
Line 100: Line 99:
</pre>
</pre>
|
|
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.   
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.   
|-
|-
|
|
Line 107: Line 106:
</pre>
</pre>
|
|
Every program must include this function it destroys the window and performs a clean-up operation  
Every program must include this function. It terminates the window and performs a clean-up operation  
|}
|}




'''''[[#top | Top]]'''''
'''''[[#top | Top]]'''''
== Command Window (cmd) ==
== Command Window (cmd) ==
All Window applications in this tutorial are designed to replace the command window and provide a more effective user interface.
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.
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 hence to a batch file command window (cmd).  
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.
This method aids in debugging code.
Line 142: Line 140:
* '''test_1.phpw''' - PHP script to run (note extension '''phpw''' you can use '''php''')  
* '''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
* 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.
Using batch files removes a need to create file associations in order to run scripts.
Line 148: Line 146:
Relative paths are used in the batch files this allows scripts to be portable.
Relative paths are used in the batch files this allows scripts to be portable.


'''''[[#top | Top]]'''''
=== Window App Batch File ===
=== Window App Batch File ===
The above batch file is ideal for testing and debugging.
The above batch file is ideal for testing and debugging.
Once you have working code, use the following batch file.


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:
 
Change the above code to use php-win.exe runs your final application without displaying a command window:
{|
{|
|-
|-
Line 172: Line 168:
* Close Windows application (cross top right)   
* 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     
'''''Note'':''' You will see an annoying flicker produced by the command window opening and closing. This issue will be addressed later.


'''''[[#top | Top]]'''''
'''''[[#top | Top]]'''''
== Windows Template ==
== 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.
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.   
The file is divided into sections. These are required for all windows applications.   
{|
{|
|-valign="top"
|-valign="top"
Line 223: Line 218:


'''''[[#top | Top]]'''''
'''''[[#top | Top]]'''''
== Summary ==
== Summary ==
The above introduced WinBinder and demonstrated how easy it is to create a basic Windows application.
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.  
Each Windows application starts with a basic script (template), additional components are required to make it do something useful.  

Latest revision as of 08:24, 24 November 2010

 

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