PHP-Class to handle WinBinder-ListViews

Author:    Horst Nogajski
Licence:   LGPL (http://www.opensource.org/licenses/lgpl-license.html)
Version:   1.0 BETA  (2007-01-03)

hnwb_ListView is a PHP-Class to handle WinBinder-ListViews

WinBinder is a open source extension for PHP. It allows PHP programmers to easily build native Windows applications.
Click here for more information.

I've tested with PHP 4 on W2k, only. Used WinBinder Version: 0.46.189

The Class supports:

automatic creation of HeaderColumns
it can handle indexed and associative DataArrays
if the DataRecords contain an Unique-Identifier-Field, the class validates new entries against it and skips all Records that fail
enhanced sorting for the columns:
- single Columns ascending / descending
- hirarchical sort of multiple Columns (max 3), ascending / descending
DataHandling for:
- Adding new Rows: with and without preserving existing rows
- Deleting Rows: all, selected, checked, unselected, unchecked
- Copy Data of Rows: all, selected, checked, unselected, unchecked
adding a statusbar to the ListView with useful information
adding a Button to open a Configurator-Window, to let the user save ColumnWidth for all columns, or define TextAlign per column, X-tended sortvalues per column, colors for the ListView and also if the Listview should display Lines or CheckBoxes
adding Display-by-Hover-Buttons for DataHandling-DELETE
Buttons: selected, checked, unselected, unchecked, all
... and more

General Thoughts

Besides the need of a more comfortable Sorting with ListViews, I want to ease up the configuration of ListViews during coding time. Very unlikely to me was to define the width for columns at coding time. So I decide to delegate all this stuff to the user at execution time of the apps.

Screenshots & Short Explanation

This is a sample-app with two ListViews, both handled by it's own class instance. Following the numbered indicators you see the StatusBar with different informations at #1.
#2 shows the little Button at the TopLeft-Position of the ListView, which only gets visible when the mouse hovers the window-area 10 pix above the ListView. This Button opens the Configurator-window to the user. (See next screenshot)
The ListViews can have individual colors for text and background. Also like at #3, they may have CheckBoxes and/or Lines, or not.
When using the class-extension "hnwb_ListView_Buttons" instead of the base-class, you have five default-buttons like at #4. The buttons only appear when the mouse hovers the 18 pix area beneath the ListView. Also all buttons which actions don't make sence on the current ListView-situation are shown, but disabled.

The Configurator-Window lets the user save the ColumnWidth, selecting Colors, display or hide lines and checkboxes, also optionally define TextAligns and sorting-lists for one, some or all Columns.

Limitations

When placing a ListView on a TabPage, the MouseMoves aren't catched. Therefor the configured Buttons are always visible.

Additionally you have to add one more line of code when creating the Class-Control:

    // create the Control,
    // don't forget to set the WBC_SORT-Flag!
    $lv1->ctrl = wb_create_control($winmain, ListView, '', 10, 25, 511, 145, IDC_LISTVIEW_1,
                  WBC_VISIBLE | WBC_ENABLED | WBC_SORT , 0, 2);

    // create a class-property with name 'TabPage', and assign the TabPage-ID to it:
    $lv1->TabPage = 2;

Example-Apps

I have packed a ZIP with the needed class-files 'hnwb_ListView.class.php', 'hn_basic.class.php', 'hn_ini.class.php' and 4 Example-Apps. Also this html-docfile is included.

In the first ExampleApp, a ListView is created with disabled Configurator-Window and therefor also the automatically creation of columnheaders isn't used. All is done manually: set the Column-Header-Names, define Column-width, optionally Textalign and some hirarchically sort-lists.

The second ExampleApp creates the same ListView, but delegates all settings-stuff via enabled Configurator-Window to the user. It also uses the Extended-Class-Version that adds some Default-Buttons to the ListView.

The third ExampleApp is a bit advanced, because it creates an own Class-Extension to the hnwb_ListView_Buttons-Class. It defines four own Buttons to transfer selected or checked Records from this ListView to another one via copy or move, (wow)! The second ListView collects all Records from the first one and also allows duplicate entries. It has the default-Buttons to delete Records.

You can pick the latest Zipfile directly here!

Happy coding!

Example Code

#--> STEP 1:
    // define ID-Constants for your ListViews
    if(!defined('IDC_LISTVIEW_1')) define('IDC_LISTVIEW_1', 1001);
    if(!defined('IDC_LISTVIEW_2')) define('IDC_LISTVIEW_2', 1002);

#--> STEP 2:
    // Create window with: WBC_NOTIFY, WBC_MOUSEMOVE | WBC_HEADERSEL !!!
    $winmain = wb_create_window(null, AppWindow, APPNAME, WBC_CENTER, WBC_CENTER,
                540, 449, WBC_NOTIFY, WBC_MOUSEMOVE | WBC_HEADERSEL );

#--> STEP 3:
    // create a global INI-Object
    $inifile = str_replace('.phpw','', __FILE__).'.ini';
    $ini = new hn_ini($inifile,TRUE,TRUE);

#--> STEP 4:
    // get Data for the Listview (e.g. from MySQL-Query)
    // for this example, we use an associative Data-Array with unique IDs.
    $data = example_data();

#--> STEP 5:
    // create an Object for the Listview
    $lv1 = new hnwb_ListView($ini,TRUE,TRUE);

    // create the Control,
    // don't forget to set the WBC_SORT-Flag!
    $lv1->ctrl = wb_create_control($winmain, ListView, '', 10, 25, 511, 145, IDC_LISTVIEW_1,
                  WBC_VISIBLE | WBC_ENABLED | WBC_SORT , 0, 0);

    // setup the ini-object, (ATTENTION: THIS MUST BE CALLED DIRECTLY AFTER THE CONTROL IS CREATED)
    $lv1->initialize_ini();

    // use AutoConfigure for the Headernames and setup the listview to handle
    // data with Unique-ID's (uid-fieldname = id), so no duplicate entries are allowed .
    $lv1->set_ASSOC_AUTO_Column_Header($data, 'id');

    // finally setup the enhanced Control, (ATTENTION: THIS MUST BE CALLED AFTER THE ColumnHeader ARE CREATED)
    $lv1->initialize();

    // pass Data
    $lv1->Data_PUT($data);

// following are the needed entries in the WinBinders wb_main_loop-CallBack-function

function process_main($window, $id, $ctrl=0, $lparam1=0, $lparam2=0)
{

#--> STEP 6:
    // make the $LV_cfg and the ListView-ObjectHandlers global!
    if(!isset($GLOBALS['LV_cfg'])) $GLOBALS['LV_cfg'] = null;
    global $lv1, $lv2;

    switch($id)
    {

#--> STEP 7:
        // First Hook into the MainProcess-EventHandler,
        // with fallthrough ! (without break-command)

        case IDDEFAULT:
            $lv1->Event_Handler($window, $id, $ctrl, $lparam1, $lparam2, $GLOBALS['LV_cfg']);
            $lv2->Event_Handler($window, $id, $ctrl, $lparam1, $lparam2, $GLOBALS['LV_cfg']);

#--> STEP 8:
        // For each ListView-ObjectHandler:
        // set a second Hook into the MainProcess-EventHandler,

        case $lv1->get_ID():
            $lv1->Event_Handler($window, $id, $ctrl, $lparam1, $lparam2, $GLOBALS['LV_cfg']);
            break;

        case $lv2->get_ID():
            $lv2->Event_Handler($window, $id, $ctrl, $lparam1, $lparam2, $GLOBALS['LV_cfg']);
            break;

#--> STEP 9:
        // For each ListView-ObjectHandler:
        // CleanUp at ProcessTermination

        case IDCLOSE:
            $GLOBALS['LV_cfg'] = null;
            unset($GLOBALS['LV_cfg']);

            $lv1->Destroy();
            $lv1=null;
            unset($lv1);

            $lv2->Destroy();
            $lv2=null;
            unset($lv2);

            wb_destroy_window($window);
            break;

    }

PHP-Class :: hnwb_ListView :: Documentation