Xobas Software'> ]> ProLinga-UI Project Release: &PRODUCT;-&version; - February 12, 2007 (Second draft) Bas Driessen &xobas;
bas.driessen@xobas.com
 Original author and current maintainer. 2002-2008 The ProLinga Team Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License". This document describes the ProLinga-UI Project and how to build the software components. ProLinga-UI Project The ProLinga-UI project focusses on the development of a User Interfaces for the ProLinga-Run (4GL Interpreter) project. The event-driven User Interface sends off XML requests to ProLinga-Run where the 4GL logic is executed. As soon as a 4GL statement is being executed that is related to an UI update, an XML response is sent back to the UI containing information regarding this update (ie open new screen, clear screen field, etc). This response can also include a request for a return request if there is more logic to be interpreted. Storing and managing of data is controlled by UI Commands (UC) using the concept of request and response. An UC request is an XML document containing a command as "Execute Logic XYZ" or "Move value to a screen field". This request is presented to the run engine for processing. After processing, the result will be placed in an UC response document and returned to the caller. The project will at first focus on the graphical user interface GTK+ for the GNOME/Linux desktop. The project can be build around other (G)UIs as well, as long as they support the concept of storing screen and widget information in a text format (pref. XML) and if they have the ability to create/render screens and screen information from this text format at run-time. ProLinga-UI contains a binary (prolingaui) that can be started from the desktop. The sophisticated prolinga-soap SOAP layer on top controls the flow and processing of incoming and outgoing requests/responses over the TCP/IP network. Using this concept, programs appear to run locally on a machine, but in fact they can access a wide range of machines (= Web Services), centrally located in an intranet environment or anywhere in the world via the internet, to share the load and execute the application. ProLinga-UI is the perfect base for platform and user interface independent multi-developer and run-time environments. Main purpose for the creation of this project, is to provide an easy way to unlink the 4GL interpreter from user interface calls to provide a base for a user interface independent platform. At the moment ProLinga-UI has only been built and tested on the RedHat Fedora Core 2 platform (i386 and x86_64), but since all code is written in C++, it can be ported to all modern UNIX systems, Linux variants as well as Windows and Mac O/S platforms. When choosing a Windows or Mac O/S native format, code changes are required to port to the GUI toolset used. UI Commands UI Commands are used to communicate with the 4GL-interpreter. A request XML document containing a command is presented to the interpreter. This document is processed and a response XML document is returned. The response can be a follow up request. UI Commands have the following format: .... .... ]]> The following UI Commands are available: Connect Disconnect ExecuteAction GetDataReference PutDataReference GetListStore GetPickList Continue Screen Ping The following sections describe the various UI commands. The response examples given all are non-request responses. Connect With the connect command, a session is created. A valid session is required to be able to send UI Commands. The 4GL interpreter will hold all information like variables etc within this session. Example Connect Request: ]]> Example Connect Response: ]]> Disconnect With the disconnect command, a session is destroyed. Example Disconnect Request: ]]> Example Disconnect Response: ]]> ExecuteAction With the ExecuteAction command, an action can be executed in the run environment. The available actions are described in the 4GL Reference Manual. Example ExecuteAction Request: Logic UpdateStock ]]> Example ExecuteAction Response: ]]> GetDataReference With the GetDataReference command, the contents of a data reference can be retrieved from the run-time environment and assigned to a screen field when a focus-in-event is triggered for instance. Example GetDataReference Request: ]]> Example GetDataReference Response: Open ]]> PutDataReference With the PutDataReference command, the contents of a data reference can be updated in the run-time environment after a screen field receives a new value when a focus-out-event is triggered for instance. Example PutDataReference Request: Closed ]]> Example PutDataReference Response: ]]> GetListStore With the GetListStore command, the (initial) contents of a multi column list box can be retrieved from the run-time environment and assigned to the mclb screen widget. Example GetListStore Request: ]]> Example GetListStore Response: 2 3 1 Size Text False 2 Description Text False 1 1 Small 2 1 Small Size 1 2 Medium 2 2 Medium Size 1 3 Large 2 3 Large Size ]]> GetPickList With the GetPickList command, the list contents of an combo box (dropdown list) can be retrieved from the run-time environment and assigned to combo box screen widget Example GetPickList Request: ]]> Example GetPickList Response: Small Medium Large ]]> Continue The continue command is issued when a response is a return request command, so processing can continue in the run environment. Example Continue Request: ]]> Example Continue Response: ]]> Screen The screen command displays a screen. Example Screen Request: True Parts GTK_WINDOW_TOPLEVEL GTK_WIN_POS_NONE False True False True False False GDK_WINDOW_TYPE_HINT_NORMAL GDK_GRAVITY_NORTH_WEST True True GTK_POLICY_ALWAYS GTK_POLICY_ALWAYS GTK_SHADOW_NONE GTK_CORNER_TOP_LEFT . . . . . . . . . . . . . . . . False ]]> Example Screen Response: ]]> Ping The ping command can be used to test if an UI-host and service is on-line and responding to requests. Example Ping Request: ]]> Example Ping Response: ]]> Additionial error information from the underlying SOAP layer will be presented as well in the response document in case of an error. UI Response Commands Every UI Command will get a response back. This response can be a simple "OK" to confirm that the request has been processed successfully, but it can also be a return request. A return request is issued when a 4GL logic command is being processed by the interpreter that requires a screen update. The request of this update is being sent as the response request and a return request will be requested to be able to continue 4GL processing. UI Response Commands have the following format: .... .... ]]> The following UI Response Commands are available: CmdClear CmdDisplay CmdError CmdList CmdMessage CmdScreen GetScreenRef PutScreenRef RepositoryList CmdClear With the CmdClear command one or more screen widgets are ordered to clear their contents. Example CmdClear Response Request: SCREENFIELD entryQuantity ]]> Example CmdClear Response -> Follow up request: ]]> The description of the logic command CLEAR in the Reference Manual, describes the available arguments. CmdDisplay With the CmdDisplay command one or more screen widgets are ordered to update their contents. Example CmdDisplay Response Request: entryQuantity ]]> Example CmdDisplay Response -> Follow up request: ]]> Instead of a single widget name, the word "ALL" can be used to display all screen widgets. See the logic command DISPLAY in the reference manual for more information. CmdError With the CmdError command an error message is displayed on the screen. Example CmdError Response Request: "Total stock : " L-TotalStock SEVERITY Info ]]> Example CmdError Response -> Follow up request: ]]> See the 4GL command "ERROR" in the Reference Manual for more information. CmdList With the CmdList command the list store linked to a multi column list box can be updated. Example CmdList Response Request: APPEND sizes VALUE "XXXL" "JumboSize" ]]> Example CmdList Response -> Follow up request: ]]> See the 4GL logic command LIST for more (syntax) information. CmdMessage With the CmdMessage command a message can be printed on the status line. Example CmdMessage Response Request: "New order opened." ]]> Example CmdMessage Response -> Follow up request: ]]> See the 4GL logic command MESSAGE for more (syntax) information. CmdScreen With the CmdScreen a screen will be displayed on the desktop or an action on an existing screen will be undertaken. Example CmdScreen Response Request: Order ]]> Example CmdScreen Response -> Follow up request: ]]> See the 4GL logic command SCREEN for more (syntax) information. When creating a new screen, actions linked to initiating a screen will be executed first, before returning to the "continue" point. The "continue" status will get stacked. GetScreenReference With the GetScreenReference command, the contents of a screen widget can be moved to the run-time environment and assigned to a data reference when a "S-screenfield" name is used in 4GL logic for instance. Example GetScreenReference Request: ]]> Example GetScreenReference Response -> Follow up request: Open ]]> PutDataReference With the PutScreenReference command, the contents of a screen field reference can be updated when a "S-screenfield" assignment is used in 4GL. Example PutScreenReference Request: Closed ]]> Example PutScreenReference Response: ]]> RepositoryList With the RepositoryList command a list of repository objects can be loaded into a list store. Example RepositoryList Response Request: small medium large ]]> Example RepositoryList Response -> Follow up request: ]]> This will typically only be used in development applications and not in end-user applications. Error Handling As soon as something goes wrong when processing a request, an error is generated and put into the response document. The status of the response will be set to "Error" or "Warning" depending on the severity of the error. In case of an error, processing will abort immediately, while in case of a warning processing continues. An error has the following format: Error/Warning Short description An external error text if available ]]> Example response when trying to connect a non-existent service: Error Service not available ]]> The "External" element will contain any error text passed on from the O/S or 3rd party products. The following initial errors are defined (this list is under construction): Errors Error Id Severity Description 80000 Ok No Error 80001 Error Error parsing XML document 80002 Error Empty XML Document 80003 Error Invalid root element 80004 Error Invalid UI XML file 80005 Error Service not available ... ... ...
Download ProLinga-UI There are two types of product versions available for download: Production Version Development Version Production Version The production version is an official product release. This is a stable completed version which should be used in production environments. At this stage the product is only available as a source archive. Binary packages for a wide range of platforms will be available for download as the project progresses. Please visit the download page for the latest details. Development Version The development version is a snapshot of the latest source files. Since it can contain bugs as part of "work in progress", this version should not be used in production environments. Only developers who want to help with further development of the ProLinga Projects should download this version. Please read the details at the Subversion section of how to obtain the latest development version. Build ProLinga-UI Prerequisites ProLinga-UI &version; has currently only been built and tested on Fedora Core 2 (i386 and x86_64). The product should compile and run successfully on other Linux distributions as well as UNIX, but this can not be confirmed at this stage. GNU gcc/g++ 3.3 compilers/tools are required for a successful build. This is the standard gcc/g++ set that ship with Fedora Core 2. Required 3rd party package(s) for a successful build: libxml2. This product provides XML libraries. ProLinga-Soap This product provides a SOAP/XML engine. Libglade This product loads XML files to create the user interface dynamically. GTK+ (GLib, GTK+, Pango, ATK) This project is used provides a complete set of widgets. General Download and Installation Instructions 3rd Party Products. Assuming the directory /opt/builds will be used for 3rd party products, then in general the following steps need to be taken to download and extract a 3rd party product source archive. Download source tar/gz archive to /opt/builds/[product] Example: place libxml2-x.x.x.tar.gz in /opt/builds/libxml2 Use 'gunzip' to unzip the archive Use 'tar xvf [product.tar] to extract the archive. Example: tar xvf libxml2-x.x.x.tar. A new sub directory will be created with the new version of the product. Example: /opt/builds/libxml2/libxml2-x.x.x This way several versions of the same products can be installed next to each other. For product specific installation instructions see following sections. Libxml2: Product root dir: /opt/builds/libxml2 Current version: 2.6.31 Download: ftp://ftp.gnome.org/pub/GNOME/sources/libxml2/2.6/libxml2-2.6.31.tar.gz Build Instructions: cd /opt/builds/libxml2/libxml2-2.6.31 ./configure --prefix=/opt/builds/libxml2/libxml2-2.6.31 make make install ProLinga-Soap: Product root dir: /opt/builds/prolinga Current version: 0.0.1 Download: http://download.prolinga.org Build Instructions: cd /opt/builds/prolinga/prolinga-soap-0.0.1 ./configure --prefix=/opt/builds/prolinga/prolinga-soap-0.0.1 make make install See the ProLinga-Soap Project documentation for more installation information. Libglade: Product root dir: /opt/builds/libglade Current version: 2.6.0 Download: ftp://ftp.gnome.org/pub/GNOME/sources/libglade/2.6/libglade-2.6.0.tar.gz Build Instructions: cd /opt/builds/libglade/libglade-2.6.0 ./configure --prefix=/opt/builds/libglade/libglade-2.6.0 make make install GTK+: Use the GTK+ version that ships with O/S. Version 2.6.0 or higher required. Build Instructions Extracting archive The product archive can be extracted to any desired directory using unzip (.zip file extension) or gunzip (.gz file extension)/ bunzip2 (.bz2 file extension) and tar. After extracting, the following directories will be created: Directory Structure. Directory Description &PRODUCT;-&version; Product version root directory. &PRODUCT;-&version;/config Config build information. &PRODUCT;-&version;/doc Documentation. &PRODUCT;-&version;/src All source and internal header files. &PRODUCT;-&version;/tests Self tests.
Compiling and Linking To build the product go to the product root directory and run the configure script. For default installation in /usr/local type: ./configure To install into another directory type: ./configure --prefix=/any/dirname/ For all other configure options, type: ./configure --help After running the configure script, the product can be build with: make To run the optional self-test type: make check After compilation, the binaries, libraries and header files can be installed with: make install You may need root access for this last option. By default, HTML documentation pages are available in the doc/html directory. These pages are generated from DocBook XML file format files in /doc. To re-generate the HTML pages from these files type: make html The command line XSLT processor xsltproc must be available from $PATH to be able to generate the HTML documentation. Dependencies Many of the ProLinga Projects are dependent on 3rd party libraries. These (non system) dependencies of ProLinga-UI are outlined below. If these 3rd party products are not installed in either /usr/bin, /usr/lib, /usr/include or /usr/local/bin, /usr/local/lib, /usr/local/include, the additional configure option needs to be provided when building. Dependencies Dependency Version Configure Option libxml2 >=2.6.31 --with-libxml-prefix=/path/to/libxml2 ProLinga-Soap >=0.0.1 --with-prolingasoap-prefix=/path/to/prolingasoap Libglade >=2.6.0 --with-libglade-prefix=/path/to/libglade GTK+ >=2.6.0 --with-gtk-prefix=/path/to/gtk
Choosing the right type of build The default configuration options provide libraries which can be used both to develop/debug as to run the product. However better builds are possible for a dedicated development or production environment. In production environments, builds are needed which contain minimal (debug) overhead, so they are fast and small. To build such binaries/libraries, the --enable-final options can be used. Example: ./configure --enable-final The enable-final flag is configured to be used with GCC environments only. If access to more compilers become available over time, the enable-flag will be ported to those compilers as well. In development environments, builds are needed producing warnings, enabling maximum debugging info etc. Several options are available here. --enable-warnings : Set all compiler warning flags --enable-debug : Enable all debug messages --enable-gprof : Enables profiling with gprof (GCC only) Further development of ProLinga-UI All ProLinga Projects are under constant active development. This includes issues related to fixing bugs, increasing performance etc, as well as expanding the various projects with new features. This chapter provides information of all these types of tasks as well as details of how to join the development team. To-do List This section contains a list of work that needs to be done on the product. This should be worked out further using a priority system and categories (bug, enhancement, etc), but this will do for now. Implement XML Schemas for validation. Libxml2 is finishing up XML schemas. If it is still too far away, start with DTD. ProLinga-UI is written in C++. Libxml2 however is C only. There is a C++ wrapper for this XML parser library. Details at http://libxmlplusplus.sourceforge.net/. Some strings/paths are hardcoded in the product. This all should be reviewed and be removed or made all configurable using a config file. Utilities. Code review and cleanup. Logging Self-tests need to be developed for quality control. Porting to other platforms. (Windows/Solaris?), so we can make a distribution available on a specific port if we need to. Add command line options to the binaries. At least a -? should be available. Subversion A Subversion tree containing the latest project sources is available at http://svn.prolinga.org. For access please contact the ProLinga Development team. Bugzilla Bugzilla software development and bug tracking system to manage the ProLinga projects is available at http://bugzilla.prolinga.org. For access please contact the ProLinga Development team. Help to Develop Are you ready to join the ProLinga development team? There are several ways you can help: Use the product. Tell us what you think, ideas, bugs etc. Fixing bugs. Look at the on-line development page , choose a bug, fix it and send us the code changes. Enhancements. Have a look at the enhancement section of the to-do list and let us know which new feature you want to help to develop. Porting. To be successful it is essential that the ProLinga Projects are available on a wide range of platforms. We need help in porting and testing as well as providing binary releases for many different platforms. Let us know if and how you can help out. Real world examples. Are you using ProLinga products or do you know people who are happily using it. Tell us the story and provide some screenshots. ProLinga-UI User Guide This section contains the user guide for the ProLinga-UI. All the binaries are documented here. &prolinga-ui-userguide; &fdl;