Xobas Software'> ]> ProLinga System Builder Tutorial: &version; - &release-date; Bas Driessen &xobas;

bas.driessen@xobas.com

Original author and current maintainer. 2002-©right-year; 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 contains the ProLinga Tutorial. Welcome to the ProLinga Tutorial. In this tutorial you are going to build a single application that allows a user to store hardware (devices) into a database using the ProLinga Development Environment. As example we take a System Administrator of a University who needs a system to be able to register the various hardware used on campus. This application is meant as an introduction to the ProLinga environment and for the sake of clarity, the end result application is very simple and basic. For more examples and/or training material of the more advanced features of ProLinga, go to the ProLinga Web Site. You need to have ProLinga installed and running on your system. Please see the installation instructions for your platform at http://www.prolinga.org/installation.html for details. In this tutorial you will learn how to read data from and write data to a database from your application. Check that you are using a database that is supported by the ProLinga-Data Project. In this tutorial a database called netadm will be used as well as a user name prolinga to connect to the database. Use the appropriate "CREATE DATABASE" and "CREATE USER" statements in your database environment to create the database and user. The user should have read and write access to the database. An example of how to prepare a PostgreSQL and MySQL database is given here. A correctly configured PostgreSQL database should be running on your system. For PostgreSQL specific installation and configuration issues, visit the Web Site of PostgreSQL for any help, as this falls outside the scope of this document. To create the database in PostgreSQL, logon to a terminal/command line environment as the database administrator user (by default is this user postgres) and type: $ createdb netadm This should produce as response: CREATE DATABASE To create the database user prolinga, logon to the interactive terminal of PostgreSQL and type: $ psql -h localhost -U postgres netadm The user can then be created as follows: netadm=# CREATE USER prolinga; Exit psql (\q) and test if you now can logon to the new database netadm with the new user name prolinga. $ psql -h localhost -U prolinga netadm If all went OK, you should see the psql prompt as follows: netadm=> A correctly configured MySQL database should be running on your system. For MySQL specific installation and configuration issues, visit the Web Site of MySQL for any help, as this falls outside the scope of this document. To create the database in MySQL, logon to mysql client as the database administrator user (by default is this user root) and type: $ mysql -h localhost -u root -p mysql The database can then be created as follows: mysql> CREATE DATABASE netadm; If this step went OK, you will see a result as follows: Query OK, 1 row affected (0.06 sec) The user can then be created as follows: mysql> GRANT ALL ON netadm.* TO 'prolinga'@'localhost'; In this example setup the user is given all privileges for the netadm database. In production environments, stricter security measures should probably apply. ProLinga uses gnome-db (libgda) technologies to connect to data providers as PostgreSQL and MySQL. To be able to connect to a database, a Data Source needs to be created that holds details as database name, user name, tcp port etc. The easiest way to create this is to run the gnome-db utility gnome-database-properties that comes as part of the libgnomedb package. Make sure you run this application as the user that will run the ProLinga environment, or for ProLinga Networked configurations, the user that started the prolingadatd daemon. Go to the command line and type: gnome-database-properties This brings up the gnomedb database properties tool. Click on the tab 'Providers' and check that your data provider is in this list. In this tuturial examples for both PostgreSQL as MySQL will be given. If there is no such entry, make sure that you have installed the libgda and gda-postgres packages as outlined in the ProLinga Installation Instructions. Click on the tab 'Data Sources' where you will see a list of configured data sources. If this is the first time you run this tool, this list is probably empty or contains just a 1 'Default' entry. Go to pulldown menu 'File' and click 'New'. This will start a druid that guides you through a series of screens to collect all the data needed. Click 'Forward'. On the screen 'General Information', enter the following details to create a data source to run the ProLinga demo applications netadm: Data source name : netadm Provider : PostgreSQL/MySQL Description : ProLinga Tutorial Application Username : (leave blank) Password : (leave blank) Click 'Forward'. Fill out the fields on screen Provider Parameters as outlined below. Where no data is given, leave the field blank. The values for PostgreSQL DATABASE: netadm SEARCHPATH: HOST: localhost HOSTADDR: 127.0.0.1 OPTIONS: PASSWORD: PORT: 5432 REQUIRESSL: TTY: USER: prolinga The values for MySQL Database Name: netadm Host Name: localhost Port: 3306 UNIX Socket: Use Secure Connection: Click 'Forward' and then 'Apply' to confirm all changes and to create the Data Source. To get to the ProLinga logon screen, type the following at the command line: $ prolinga4gl The ProLinga logon screen as shown below appears.

Screenshot of the ProLinga Welcome Screen.

You can logon to the ProLinga environment as 3 types of users: administrator user - This user can perform tasks like defining users and applications as well as changing system wide settings. developer user - This user can develop applications. end-user - This user can run applications as created by the developer In this tutorial, you are going to create an application netadm. Therefore you first have to logon as the administrator user and define this application. On the ProLinga Welcome Screen, type administrator in the field "User Name" and press the OK button. The Administrator screen will be displayed. Click on the tab Application and a list of available applications will be listed.

Screenshot of the List of Applications in the ProLinga Administrator.

Press the Add button and details of the new application can be added. Application Name: The name of the application. Only use alphabetic (A-Z,a-z) and numeric (0-9) characters and avoid spaces and special characters. Password: To protect your application from being accessed, a password can be set. Leave blank for no password. Application Type: Select if the application will be an administrator, developer or standard application. Use standard for end-user applications. If you do do not understand this setting, choose standard. Initial Logic Name: If an end-user starts your application, some point must be defined as starting point. This is called Initial Logic. This will be the first ProLinga code executed when starting your application. Description: There are two types of descriptions possible. A short one that will be used in lists and a long one that can be used to provide more details. Any text is allowed for either description fields. For our tutorial application netadm, use the following values:

Screenshot of how to add a new Application.

Press the OK button and your new application now appears in the list with the others.

Screenshot of the List of Applications in the ProLinga Administrator including netadm.

Have a further look in the Administrator. You will notice that there is a similar interface to add/modify/delete users. In this tutorial we will refer to the default developer user developer and end-user guest, so to continue this tutorial, there is no need to create any new users. However in multi-developer environments, it is recommended to assign every developer his/her own logon name. The same applies if there is more than one guest user on the system. Logout (Pulldown menu File and then option logout) from the Administrator. Now that the application name has been defined, it is time to start developing the application. Logon as user developer this time. On the welcome screen type developer in the field "User Name", leave all other fields blank and press the OK button. The ProLinga Developer application will appear on the screen.

Screenshot of the Start Screen of the ProLinga Developer.

Press the button "Open" on the toolbar and a popup screen appears where you can generate a list of available applications, by applying a filter. For this example we want to see a list of all the applications, so leave the "*" in place and press the "Index" button.

Screenshot of the Object Open Screen.

Select the application netadm and press OK. This will load the application netadm into the developer. The title of the main frame shows that we have loaded the correct application.

Screenshot of the Developer's Main Frame.

Further there is an object palette available that contains links to all the various object editors to develop the application.

Screenshot of the Developer's Object Palette.

First we are going to create a screen that we want to display as soon as an end-user starts the application. At first time we will not put anything on the screen, so just a blank screen to begin with. ProLinga uses the "Glade" XML interface for displaying screens. Screens are stored in an XML format and at run time, they are parsed by libglade and the user interface created. Templates are provided to create screens. Press on the button Screen on the object palette and the Screen editor will appear. There are 3 types of screens possible: Single Instance Window: Typical data view/entry window. When trying to open more than once, the screen on that is on the desktop will get the focus. Examples are most editor screens in the ProLinga Developer. Multiple Instance Window: Typical data view/entry window. When trying to open more than once, a new instance of the screen will be opened. Example is the Logic Editor in the ProLinga Developer. Dialog: This is a screen that must be closed before any other screen can get focus. Example is an error screen that you must respond to in order to continue. For the main screen we will use the Single Instance Window. Press the button "New Window" on the toolbar to load the appropriate template in the editor. Click on the tab "Control" and select "False" for the field "Allow Multiple Instances". Now save the screen by pressing the "Save" button on the toolbar and give it the name "Main".

Screenshot of the initial screen in the editor.

We just created the first (empty) screen and we now proceed by going to create logic to call this screen. In the Administrator, we set the initial logic to be called Main. This will be the starting point of the application. Therefore we now have to create this logic "Main". Logic is a collection of ProLinga Statements that will be processed at run-time. Other programming environments call this functions or procedures for instance. We will keep our initial logic very simple to begin with. What we want to happen is what we call the screen with the name Main which we have created in the previous chapter. Press on the button Logic on the object palette and the Logic editor will appear. To call the screen Main, use the ProLinga command SCREEN: SCREEN Main It is essential that ProLinga commands, like SCREEN, are written using uppercase characters. Save this logic by either going to pulldown menu File and option Save or by pressing the save button on the toolbar. Save it with the name "Main". After the logic has been saved, it looks like this:

Screenshot of Initial Logic.

When saving the Logic, ProLinga also checks the syntax and references used. If there are any problems found, an error window will come up reporting the problems found. Correct the problems if that happens and try saving it again. We are now ready to run the application for the first time. To run the application, you have to return to the ProLinga welcome screen. You can either do this by going to the pulldown menu "File" which is located in the main frame of the Developer and then click "logout", or you can run a second ProLinga session, by typing prolinga4gl from (an other) command prompt. To run our application, we need to logon as an end-user. A standard end-user guest is defined by default. Use this name as user name on the logon screen and our application netadm as application name.

Screenshot of the login to run an application.

After pressing the OK button, our application starts and our (empty) initial screen will be displayed on the desktop.

Screenshot of first time running of the application.

Congratulations! Although, not very useful yet, our application is up and running. Press on the "X" in the right top corner to exit the application. Start the ProLinga Developer again and proceed to the next chapter. It is time to put some objecs on the screen. Since the Glade XML format is used to store and render screens, it makes sense to use the Glade User Interface Builder to design the screens. The ProLinga Developer calls Glade to make this painter available for the ProLinga environment. Open the screen "Main" in the screen editor and press the button "Painter

Screenshot of start screen painter.

The Interface Builder Glade now starts up. Besides the main application frame of Glade, two other windows (properties window and palette) are displayed as well. To bring up our screen "Main", go to the main frame of the painter and double click on the line "Main" as the following example shows.

Screenshot of how to make the screen visible in the screen painter.

Since our initial screen is empty, it make come up initially very small in the painter. Look for the small screen.

Screenshot of the small screen in the painter.

To resize the screen, simply click on the edge with the mouse and make it bigger.

Screenshot of the big screen in the painter.

To set the title of the window, edit the field "Title" in the properties editor. To get there, select the screen "Main" in the main frame (same line we double clicked on earlier) and details of the screen become availabe in the properties window. Change the text of "Title" to "Network Administration Application".

Screenshot of how to set the screen title.

Click on the tab "Common" and set the width of the screen to 500 and the height to 400. This will set the minimum size of the screen. Users will still be able to increase the size or maximize the screen.

Screenshot of how to set the screen size.

Leave all other fields default in the properties window of screen "Main". We will keep the screen simple and want to see four horizontal sections on the screen: Pulldown menu section Toolbar Main Area Message Bar Glade provides numerous ways to build up your screen. Everything can be dynamic, fixed or a mix. We are using a method that when a user resizes the screen, the objects on the screen will be resized too. To get the four sections on the screen, start by placing a "vertical box" on the screen. The way to place objects on the screen is to select them from the palette window and then click on the place where you want this to be on your screen. Bubble help will help you identify the various objects. Click on the "vertical box" button and then click on your window. When asked for the number of rows, change the default (3) to 4 and press the OK button.

Screenshot of location of vertical box object.

Your screen now should look like this:

Screenshot of screen with vertical box object.

Now we can get the objects in place. The first section should be our pulldown menu. Click on "Menu Bar" on the palette and click on the first section on the screen. This will put a default pulldown menu in place. We will put in the correct menu details later.

Screenshot of screen with pulldown menu.

In the second section, we want a toolbar that we want to be able to move freely. Therefore we first have to put the object "Handle Box" in place.

Screenshot of screen with handle box.

The "Handle Box" looks very big, so we have to prevent this from expanding. Click on the "Handle Box" on your screen (and NOT in the palette) and the properties of the "Handle Box" appear in the property window. Click on the tab "Packing" and change the setting "Expand" from "Yes" to "No".

Screenshot of how to prevent handle box to expand.

The "Handle Box" now looks as follows:

Screenshot of screen with correct sized handle box.

Now place the "Toolbar" in the empty space right next to the "Handle Box". When asked for the number of items, change the default (3) to 2.

Screenshot of screen with toolbar.

We put the object "Frame" in the 3rd section. It is important to give it a name, so we can use it in later exercises to present another screen in this frame. After placing the frame on the screen, go to the properties screen of this frame and set Name to "frame_main".

Screenshot of setting the name of a frame.

Finally, place a "Status Bar" in the last section. The screen now looks as follows:

Screenshot of screen with the 4 main sections.

Save the screen. Go to the main frame of Glade and press the "Save" button. You will see a message in the status bar "Project saved". Now exit the painter by clicking "Quit". You will return to the Screen Editor in the ProLinga Environment. You will notice that the XML in the Screen Editor has been updated automatically. Press "Save" to save the screen. If you do not press Save here, your changes will be lost!

Screenshot of updated screen in the Screen Editor.

Now run your application. Logon as an end-user (guest) and application netadm. If all went well, you will have the following screen.

Screenshot of a Run-Time view of the screen.

We see the pulldown menu, the frame, the status bar and since there are no buttons yet on the toolbar, we can't really see the toolbar yet. We have not linked any logic yet to any pulldown menu option, so nothing will work yet. Press the "X" in the right top corner to exit the application and logon again to the ProLinga Developer and open application netadm. Proceed to the following chapter. When creating the screen, we added pulldown menu structure in the first section. Now we are going to put the right names and actions in place. As soon as a user selects an option from one of the pulldown menus, some action needs to happen, like display another screen, or start a calculation etc. In ProLinga, this is controlled by "Action Handlers". Currently, there are three types of "Action Handlers": Control (C-): Built-in functions as described in the reference manual can be called. Examples are actions to cancel a screen or to return to the ProLinga logon screen. Logic (L-): ProLinga logic can be called. Examples are logic to read data from the database or to display a value on the screen. Screen (S-): A screen can be displayed. Examples are a search screen or data entry screen. In the tutorial application, we will create the pulldown menus File, Maintenance and Help. The pulldown menu entries and action handlers are outlined below. Most actions probably do not make much sense yet, but it will become clear once we create the logic and screens referenced here. Name Action Handler Description Home L-Home This will call logic called "Home" to clean up the main screen. ------- (leave blank) Separator line in the pulldown menu. Cosmetics only. Logout C-logout This will exit the application and return to the ProLinga logon screen. Exit C-exit This exit the application. Name Action Handler Description Device L-Device This will call logic called "Device" to provide a inquiry/update mechanism of available devices Name Action Handler Description About S-About This will display a screen with some application information. Open the screen "Main" in the painter in the ProLinga Developer. If you click on the pulldown menu, you will see a button called "Edit Menus...".

Screenshot of where to edit pulldown menu entries.

Press the button "Edit Menus...". All pulldown menus and entries will be displayed on a separate screen.

Screenshot of where to edit pulldown menu before edit.

When clicking on a line, details will be displayed in the right portion of the window. You can set details here like "name" and "action handler" as well as link icons to the menu entry or an accelerator. With the navigation buttons at the bottom of the screen you can change the order and hiearchy. When using an underscore sign "_" in the label name, the following character will be set as mnemonic. Edit the various menus, until your screen looks as follows:

Screenshot of where to edit pulldown menu after edit.

Save your screen in the painter, exit the painter, save your screen in the ProLinga Screen Editor and run your application. At the run-time your application now looks as follows:

Screenshot of pulldown menu 1.

Screenshot of pulldown menu 2.

Screenshot of pulldown menu 3.

If you click on any of the menu items linked to logic, you will get an error telling you that the logic does not exist. That is correct, since we have not written them yet.

Screenshot of an error message when logic does not exist.

The same applies to the screen. The Control "action handlers" logout (File/Logout) and exit (File/Quit) should work OK. In the next chapter we will create the toolbar. A toolbar normally contains a selection of often used action that are also defined as an action in the pulldown menu. Toolbars are created in the painter and are push buttons with an action handler attached. Open the screen "Main" in the painter in the ProLinga Developer. We reserved 2 places on the toolbar. We first have to place buttons in those empty slots. Select "Button" from the palette and click on the empty space on the toolbar. It now should put a button in place. Repeat that for the second button.

Screenshot of the toolbar after placing 2 buttons.

The first button we want to name "Home". The painter comes with a range of icons that can be used on buttons like this. They are called "Stock Buttons". If you click on button 1 on the toolbar you can select the "Stock Button" called "Home" in the Properties Window.

Screenshot of how to set a stock button.

The action handler that we want to link to this button is the same as the one we linked to the pulldown menu "Home" which is "L-Home". This will call ProLinga logic with the name "Home" when the user clicks on it. To set the action handler, stay in the properties window and click the tab Signals. In the field "Signal" we can define a signal that will trigger the call to our logic "Home". If you press the "..." button next to the field, you will get a list of possible actions. We want this to take place if the user clicks the button. Therefore we select the action "clicked". The handler is, like in the case of the pulldown menu, L-Home. After you have typed then in, you have to press the button "Add" to add this new entry to the list.

Screenshot of how to link a signal to the button.

The second button will be called "Quit" and the action handler is "C-exit". There is a "Stock Button" for this as well. If all went well, your screen now looks as follows in the painter:

Screenshot of a finished toolbar.

Save the screen in the painter, exit the painter and save the screen in the Screen Editor. Run your application and test the toolbar.

Screenshot of application at run time with finished toolbar.

In our pulldown menu entry Help/About we created an action handler S-About. This means that if a user selects this option, a screen with the name "About" will be displayed. To practise a bit more with screen painting, we will now create this screen. The "About" screen will be a of type "Dialog". This means that the screen must be closed before the user can continue with the application. Open the Screen Editor in the ProLinga Developer and press the button "New Dialog" on the toolbar. A standard template will populate the Editor. Save the screen and name it "About".

Screenshot of the creation of the About screen.

Bring up the screen in the painter. By default, a Dialog is displayed with an "OK" and "Cancel" Button. In this case, we only want a button called "Close". To change this click on the button box on the screen.

Screenshot of how to select the buttonbox on the screen.

Go to the properties screen and change the size from 2 to 1.

Screenshot of how to change the button size.

Change the "Cancel" button to a "Close" button. Click on the button, go to the properties screen and change the "Stock Button" to "Close". Add the signal "clicked" and action handler "C-cancel".

Screenshot of the Close button.

Set the screen title similar like we did on the Main screen. Call it "About". Set the screen width to 300 and the height to 200 In the big empty space on the screen, place a "Vertical Box", like we did at the previous screen. Set the number of rows to 2 and fill row 1 and 2 with a "Label". In the properties screen of the "Label", you can type any text in the field "Label" under the tab called "Widget". You can also use Pango markup like <big>label</big>. Other examples are <small>, <b> for instance. You have to change the setting "Use Markup" to "Yes".

Screenshot of how to mark up label text.

Under the tab "Packing", on the properties screen of a label, you can switch the setting "Expand" to "Yes" to get a nice layout.

Screenshot of how to expand a label.

Run your application, go to the pulldown menu "Help" and select "About.

Screenshot of the About screen.

In the next couple of chapters, you will learn how to create a data entry screen and how to get the data from and to your database. In a previous chapter "Create the data source" we created a data source (or channel if you like) to our database, which we called "netadm". In this external data source, we enter details as the name of our database that we want to use and the details to logon to that database. Now we have to link into this channel from within our application. Bring up the "netadm" application in the ProLinga Developer and select "Data Source" on the object palette.

Screenshot of the data source button on the object palette.

In the Data Source editor, press the button New and enter "netadm" in the field "External Name". This is the name of the external data source. Leave all other fields as they are. The field "User Name" here refers to the user name to be able to access the data source itself and not the user name needed to access the database. That last user name has already been defined in the external data source. Save the data source and name it "netadm".

Screenshot of the data source netadm in the ProLinga Developer.

Tables that you will create in further chapters and that use the data source "netadm", will now use your preferred database as data provider. Before we can access the data in our database through the data source, we first have to execute the ProLinga command "SQL CONNECT" to open a connection to the data source for this session. Since we will be accessing our data throughout the application, it is best to place this command at the very beginning of our application. Remember that the starting point of our application was logic called "Main". Bring up this logic in the logic editor and add the following line to it: SQL CONNECT netadm The name "netadm" is the name of the data source object that we created in the previous chapter. Your logic "Main" now should look as follows:

Screenshot of the logic Main with SQL CONNECT.

Similar it is good practise to close a data source upon exiting from or logging out of the application. Therefore it is a good idea to write a logic block that is called every time the user exits or logs out from the application. Write a logic block named "Quit" as follows:

Screenshot of the logic Quit with SQL DISCONNECT.

Write the same logic and save it with the name "Logout".

Screenshot of the logic Logout with SQL DISCONNECT.

Make sure you do not overwrite the logic called "Main" and that you press the button New in the logic editor first before writing this new logic. Now we have to make sure that this logic gets called when the user exits/logs out from the application. The only way the user can exit the application is through the pulldown menu option "Quit" and "Logout" or through the toolbar button "Quit". Currently, we have linked that to C-exit and C-logout, but if we change that to L-Quit and L-Logout, our new logic block "Quit" or "Logout" will be called upon exit/logout. To change this, open the screen "Main" in the Screen Editor and start the painter. To update the link from the button "Quit", single click on the button, go to the properties screen and press the tab "Signals". Update the handler field to L-Quit.

Screenshot of how to update the toolbar button signal handler.

Update similar way the pulldown menu entry "Quit" and "Logout".

Screenshot of how to update the pulldown menu item signal handler.

Save the screen and test your application. Now that we have the connection from our application to the database in place, it is time that we build a table. The name of the table that we want is "Device" and the fields that we want in that table are as follows: Field Name Data Type Length deviceNumber Unsigned Decimal 5 description String 35 typeId String 3 dateInstall Date (format CCYY-MM-DD) 10 The primary key will be deviceNumber There are 4 easy steps involved in creating a table in ProLinga: Check if data dictionaries are available and if not create them. Group data dictionaries together in a Record. Group data dictionaries together in an Index. Create a Table definition and assign the Record(s) and Index(es) to it. From this point on we should not be using the terminology "Field Name" any more when refering to table definitions in ProLinga. Instead, ProLinga uses the concept of Data Dictionaries. A Data Dictionary is a very powerful reusable object. Think of 2 tables for instance that both have a field called "description". In traditional database environments, you have to create this field 2 times. Besides more work, also there is a chance that 1 field has a length of 15 and the other of 35 and that data can get lost when assigning one to another. In the case of ProLinga, we will use the same Data Dictionary for both tables, eliminating the possibility of incompatibility. To create the Data Dictionaries, open your application in the ProLinga Developer and select "Data Dictionary" from the Object Palette.

Screenshot of the data dictionary button on the object palette.

Press the button "New" on toolbar of the Data Dictionary editor to make sure you start with a new object. We first will create the Data Dictionary "deviceNumber". Set the "Maximum Length" to 5, "Data Type" to UnsignedDecimal, "External Storage Type" to Integer and "Justification" to Right. Leave all other fields default as they are. Save the Data Dictionary and name it "deviceNumber".

Screenshot of the data dictionary "deviceNumber".

Some details of key fields. The "Data Type" is the type of the data within ProLinga, while "External Storage Type" is the type of the data in the database. Most of the time they will be of a similar type, meaning that a String translates to the type Character and Unsigned Decimal to Integer, but there maybe situations that this is not the case. The same way, create the Data Dictionaries "description", "typeId" and "dateInstall".

Screenshot of the data dictionary "description".

Screenshot of the data dictionary "typeId".

Screenshot of the data dictionary "dateInstall".

Once we created all the Data Dictionaries that we need for our table "Device", we can group them together in a Record. Open the Record editor from the Object Palette.

Screenshot of the record button on the object palette.

Type in the name "deviceNumber" in the screen field "Data Dictionary Name" and press the "Add" button. You will see that the name now shows up in the list. Add the same the Data Dictionaries "description", "typeId" and "dateInstall". Instead of typing them in, you can also select them from the list when pressing the button "Find". The order from top to bottom will be the order of the fields in the database from left to right. It is important to get this right. When finished, save the Record with the name "Device".

Screenshot of the record "Device".

On a similar way, we can create an index. Open the Index editor from the Object Palette.

Screenshot of the index button on the object palette.

Click on the tab "Entries" and add the Data Dictionary Name "deviceNumber". Save the index with the name "deviceNumber."

Screenshot of the index "deviceNumber".

Finally, we create the Table itself. Open the Table editor from the Object Palette.

Screenshot of the table button on the object palette.

Add the Record to the Table definition by typing the name of the Record "Device" in the field "Record Name" under the "Record" tab and press the "Add" button.

Screenshot of adding Record to Table definition.

Press on the tab "Index" and add the Index called "deviceNumber".

Screenshot of adding Index to Table definition.

Click on the tab "Provider". The "External Name" will be used for the physical file name in the database. So enter "Device" here. As "Data Interface Type" choose GDA and the Data Source is the one we created earlier with the name "netadm".

Screenshot of adding Provider details to Table definition.

Now save the table and give it the name "Device". Now click on the tab "Data Manager" and click the button "Build Database Table". If you receive no error messages, all went OK and your table is now created in the database. To double check this, open an interactive terminal for your database and check if the new table is present.

Screenshot of Table definition in the database.

As you can see, all the fields are available as well as the index. At this stage, we can not test this yet in our application, as we do not have any data entry screen. Please proceed to the next chapter to build one. Since we have made a screen before, not all steps are described in great detail. If you have problems understanding it, you may want to go back and re-visit earlier chapters. To build a Data Entry Screen, open the application in the ProLinga Developer and go to the Screen Dialog Editor. Click the toolbar button "New Window" and then save this screen with the name "Device". Now bring it up in the painter. Set the window title to "Device", set the width to 550 and the height to 350. Remember the screen "Main" where we placed a "Frame" object in the third section. In later exercises, we will learn how we can integrate the screen "Device" with the screen "Main". To make this possible, we first have to place an object "Scrolled Window" on our screen "Device".

Screenshot of scrolled window object.

Go to the properties screen of the scrolled window object and give it the name "device_include".

Screenshot of name scrolled window.

Within the scrolled window, place a "Vertical Box" with 2 rows. In the first row place a painter object "Table" with 4 rows and 3 columns. In the second row place a "Horizontal Box" with 2 columns.

Screenshot of base screen Device.

Once we are placing objects within objects, it is easy to get lost. Therefore you can open a widget tree window. In the painter go to pulldown menu "View" and then click option "Show Widget Tree". Here you can simply select any object that you have placed on the screen.

Screenshot of painter widget window.

We have 4 data dictionaries in our table definition "Device". We can now place an object "Label" on the screen for all 4 of them.

Screenshot of labels on device screen.

Do not worry about the layout. Once all objects are on the screen, we will get all objects to display right. In the next column we put the object "Spin Button" for the Device Number field, since that is a numeric one, "Text Entry" for the Description field, "Combox Box" (not be confused with Combo Box Entry) for the Type Id field and "Text Entry" again for the Installation Date field.

Screenshot of entries on device screen.

It is important to give all the editable objects a name, so we can refer to it from ProLinga logic. Use the names "entryDeviceNumber", "entryDescription", "entryTypeId" and "entryDateInstall". These values can be set in the properties screen of the objects as the example below of the Description Field shows.

Screenshot of how to set the name of an entry field.

In later chapters we want to create a lookup screen for the Device Number field. That means we have to trigger an action. For now we will just place a Button on the screen called "Find".

Screenshot of find button on device screen.

In the bottom 2 sections we are going to put a "Horizontal Button Box" in both of them.

Screenshot of horizontal buttonbox object.

When asked for the number of buttons in the box, type 1 for the left one and 3 for the right one. Then go to the properties screen of the left button box and set the value "Layout" in the "Widget" tab to "Start" and set the value to "End" in the right button box.

Screenshot of layout setting for horizontal buttonbox objects.

Now set the left button to be a "Delete" button, and the other 3 to be "Cancel", "Apply" and "OK". Your screen "Device" now should look similar to this.

Screenshot of horizontal buttonboxes on device screen.

All objects that we want to have are on the screen, so now we can format the screen to look a bit better. The buttons should always be at the bottom of the page. So we have to prevent them from expanding. The 2 horizontal button boxes are child objects of the horizontal box object, so we need to go to the properies screen of the horizontal box object. This is where you want to use the Widget Tree screen.

Screenshot of horizontal box in widget window.

Select the horizontal box object in the Widget Window and go to the properties screen. There under the tab "Packing" you will find a setting called "Expand". Set this to "No". You will see the direct effect in the "Device" screen in the painter. The rows and columns are a bit close to eachother in the screen and we should add some spacing. The labels and entry fields are child objects of the table object. Select this object in the Widget Window, go to the properties screen and select tab "Widget" (Default). Set both Row as Col Spacing to 5. Set the field Border Width of the vertical box (vbox1) to 10. Your screen now should look similar like this in the painter.

Screenshot of all objects on device screen.

The unused spaces around the "Find" buttons, will look OK at run-time. Before we can test this screen at run-time, we must remember how we are calling this screen. From the pulldown menu and toolbar, we created an action handler L-Device, meaning call logic "Device". We have not written that logic yet, so it is time to do it now. For the time being, all we want this logic to do is to call screen "Device". Therefore, open the Logic Editor in the Developer and write the following logic: SCREEN Device Save this logic and name it "Device".

Screenshot of device logic.

Start your application and see if the "Device" screen comes up. We have not written any logic yet to read/write data from/to your database, so that part will not work yet. You will notice that if you run your application your Device screen comes up as a separate window as soon as you select the pulldown menu option "Device".

Screenshot run-time Single Device Screen.

In a previous exercise we created a frame called "frame_main" on the screen called "Main". What we want now is to project this new Device Screen into this frame, so it becomes one single screen. To cater for that we have to go into the ProLinga Developer and open logic "Device" in the Logic Editor. Now we change the logic from: SCREEN Device to: SCREEN Device CONTAINER frame_main SOURCE device_include This tells the run-time engine to get from the screen "Device", only the object "device_include" and child objects. This "device_include" is the scrolled window object that we placed on the screen "Device". This "device_include" then should be projected in the frame (or often called containter) "frame_main" on the current screen. Save this logic and if you now run your application, you should have a similar screen as below, once you click on the "Device" pulldown menu option.

Screenshot run-time Device Screen in Containter.

As you will see the screens are nicely merged into a single screen. If it is not working, please review previous exercises where we placed the frame "frame_main" on the screen "Main" and where we created the scrolled window object "device_include" on the screen "Device". As all following exercises continues to work with this merged view, do not continue until you have it working. One of the screen fields used is called "Type Id". We defined it as a string with maximum of 3 characters. We only want to have 3 values available where the user can choose from: COM - Computers MON - Monitors PRT - Printers At run-time, we want to present these values to the user. That is why we chose the screen object "ComboBox" in the previous exercises. This ComboBox object can be used to present values that are in the ProLinga Pick List Object. We will now create a Pick List.

Screenshot of the pick list button on the object palette.

Press the button "New" on the tool bar of the Pick List Editor to create a new Pick List. Now type the value "COM" in the "Value" field and press the "Add" button. You will see that the value now appears in the list. Do the same for "MON" and "PTR". Save the Pick List with the name "DeviceType".

Screenshot of the pick list "DeviceType".

There is no point in testing your application at this stage, since this Pick List has no effect until we reference, so proceed direct to the next exercise. In the previous chapter we painted a data entry screen. We now have to put the functionality in place. First a bit of explanation how we can get data in to and out of the screen. In ProLinga we created a table called "Device". For every table you create in ProLinga, there will be a table buffer available. A table buffer can hold a value for every data dictionary of every record of a table. An object, like this table buffer, is called a Data Reference . Other examples of Data References are Variables and Constants for instance. Data Reference can be referenced from ProLinga logic and screens with a prefix. The prefix of a single table buffer entry is F-, referring to a single Field of the table buffer. (It will be clear later on why F is used and not T for instance). The syntax of a table buffer field reference is: F-data_dictionary_name.table_name.record_name So to reference the field deviceNumber in the table Device, we use the reference: F-deviceNumber.Device.Device The last section, the record section, can be omitted and in that case the default record of the table will be used. Since we only have one record called Device which then automatically is our default record, we can shorten this to F-deviceNumber.Device In ProLinga logic we can assign a value to or from the a table buffer entry using the logic command LET. So LET F-deviceNumber.Device = 123 as an 'assign to' example and LET V-deviceNumber = F-deviceNumber.Device as an 'assign from' example. See the reference manual for more details on this. We can also link data references to screen fields. There are situations that you want to move data from the screen field to the data reference, from the data reference to the screen field or both. To cater for this we have to indicate which of the two data moves we want to do. GET - This indicates that we want to move data FROM the data reference TO the screen field. PUT - This indicates that we want to move data TO the data reference FROM the screen field. To further not confuse a data reference prefix with an action prefix, "D:" is appended in front. If we return to the example of F-deviceNumber.Device, the data reference calls are as follows: D:GET:F-deviceNumber.Device D:PUT:F-deviceNumber.Device Like any action handler, we have to link a signal to a data reference call, so the system knows when to make the data move. In our situation we want data to move FROM the data reference to the field, when the focus enters a field and we want to move data (that we just typed for instance) TO the data reference when the focus leaves the field. There are many signals available in GTK+, but most of the time the signals focus_in_event and focus_out_event does the job. Knowing this, we can now return to our application. Open it in the ProLinga developer and bring up the screen "Device" in the painter. Click on the entry field (spin button) for deviceNumber and go to the properties screen. Under the tab "Signals" add the signals "focus_in_event" and "focus_out_event" for the GET and PUT of F-deviceNumber.Device.

Screenshot of setting signal for data reference device number.

The same way set the following data references as well: F-description.Device F-dateInstall.Device The field "Type Id" needs some further explanation being a "ComboBox". As soon as this object is created we want the values of the Pick List "DeviceType" that we made earlier to be available in this object. For "ComboBox" and "ComboBoxEntry" objects, we have the Data Reference prefix P: available. So link P:DeviceType to signal "focus_in_event" which is emitted at screen creation time. The Data Reference GET is the same as other fields and the Data Reference PUT is not linked to the focus_out_event, but to the "changed" signal, so every time a user selects a value, the underlying data reference is updated.

Screenshot of setting signals for data reference type id.

As a general rule, do not forget to save your screen in between making major changes, to prevent having it to do all over again, in case of any type of user/system error. Now that we have the actual fields in place, we can finish the remainder of the action handlers. As soon as the user enters a device number and the focus leaves that field, we want to see all the details of that device number if it exists, or a message that a new device number can be added if the number does not exist. This means we have to link a logic to a signal from the deviceNumber field. The signal is again "focus_event_after" and the logic we want to call (and which we will create later) is "L-DeviceRead".

Screenshot of data reference and action.

As you can see we can use the same signal multiple times and mix it with the use of actions and data references. Now we link actions to the remaining objects on the screen: Object Signal Action Handler Find button. clicked L-SearchDeviceNumber Delete button (left below). clicked L-DeviceDelete Cancel button. clicked L-Home Apply button. clicked L-DeviceApply OK button. clicked L-DeviceOK As you maybe noticed, we want to call logic L-Home rather than the expected L-Cancel for the Cancel button. Remember that the Device screen is now integrated into the main screen. When cancelling the screen we really want to just clear the frame/container that holds the Device (sub) screen. To avoid confusion, we call this "Home". Now save the screen and run your application. Make sure all buttons on the Device screen now generate an error like "Logic [xyz] does not exist" when you press them. Notice also that this error is triggered when you place the cursor on the Device Number field and then leaving it by placing it somewhere else. We are now finished painting the Device screen and now we have to go into ProLinga logic to get it all to work. In the previous chapter we made many calls to ProLinga logics. Now we will write all those logics as well as adding some lines to existing ones. In a previous exercise we already created the logic called "Device" to display the screen "Device" in the "frame_main" frame. We will now add some lines to it. An explanation of the added lines are given as well. Change the logic "Device" to this: CLEAR TABLE Device LET F-dateInstall.Device = DATE() SCREEN Device CONTAINER frame_main SOURCE device_include DISPLAY ALL MESSAGE "Device can be updated." FOCUS entryDeviceNumber On the screen "Device" we linked data references like F-deviceNumber.Device. To assure that the table buffer is empty when the screen is display and does not contain some random/old values, we first clear the table buffer "Device" with the CLEAR command. We set the date field F-dateInstall.Device standard to today's date. The third line remains unchanged and projects the screen Device in the frame. The DISPLAY refreshes the contents of a screen field, by moving the contents of the data reference that is linked to it with the signal "focus_in_event" to it. By saying DISPLAY ALL we do that for all the screens. Since the data reference are table buffer entries like F-deviceNumber.Device, which we just cleared with the CLEAR command, all entries will be set to blank (or 0). So we get a nice clean data entry screen. The MESSAGE command places all its (data references) arguments on the status/message line at the botton of the current active screen. The FOCUS command sets the cursor to the Device Number entry field. After you applied the changes to logic "Device", save it and run the application. See if the message becomes visible on the status/message line and if all fields are initialized. Our Screen "Device" is now displaying in the frame called "frame_main". Once the user is finished with the data entry screen and wants to close it, this now means that we have to clear the frame "frame_main". We use the ProLinga command CLEAR for this. Write the logic "Home" as follows: COMMENT --- Clear frame --- CLEAR CONTAINER frame_main COMMENT --- Clear status line --- MESSAGE "" The CLEAR command removes all child objects from the frame/container "frame_main". Further we see the logic command COMMENT. This command is just for documentation purposes. Everything behind that command will be ignored by the ProLinga run-time engine. You may leave out the comment statements if you wish. The command MESSAGE prints text on the message/status line. Since we are giving it an empty string as argument, any messages on the message/status line will be deleted. Save the logic and run your application now. Click on pulldown menu "Device" and then press either the button "Home" or "Cancel". Also the pulldown menu entry "Home" should be tested. You should see that the frame is emptied when logic "Home" is processed." If the user has to type in a Device Number, but does not know the number, a search screen can be presented where a Device Number can be looked up using search criteria. We will implement this feature at a later stage, so for the time being, we just want to trigger the message "Feature has not been implemented yet". For that we can use the ERROR command. ERROR "Feature has not been implemented yet." SEVERITY Info This will trigger the information as follows:

Screenshot of an information message.

Please see the reference manual for all the various available ERROR severity options. Run your application and test if the information message comes up. This will be the logic where will test if a value exist in the database. If it exist then show all the details on the screen, so they can be modified and if it does not exist, provide a blank data entry screen for a new Device. The mechanism here is the we execute an SQL statement that returns with a DataModel (sometimes also referred to as 'Cursor' or 'ResultSet' in other environments). This DataModel is populated automatically, so we do not have to design them first setting column names etc. The only thing that is required that the DataModel as an object is available in ProLinga. To create a DataModel, logon to the ProLinga Developer and select "DataModel" from the Object Palette.

Screenshot of the data model button on the object palette.

Create a new DataModel and save it as "Device". Leave the setting "AutoClear" as it is.

Screenshot of the data model "Device".

Further we need a setting so we can keep track if a Device record was present or not. We need to know when updating if we need to trigger an "insert" or "update" action. The easiest way to keep track of this is by using a (global) Variable object called isPresentDevice. Before we can create this Variable "isPresentDevice", we first need to create the underlying data dictionary "isPresentDevice". Create a this data dictionary of type "Boolean" and length of 5 (so it can hold the values True and False. Since we have created Data Dictionaries before, only the end result is shown below:

Screenshot of the data dictionary "isPresentDevice".

To create the Variable "isPresentDevice" open the Variable Editor in the ProLinga Developer.

Screenshot of the variable button on the object palette.

Enter the just created Data Dictionary "isPresentDevice" and set the default value to "False". Save the Variable with the name "isPresentDevice".

Screenshot of the variable "isPresentDevice".

Everything is now present to write the logic "DeviceRead". LET V-isPresentDevice = FALSE() COMMENT --- No validation on empty key IF F-deviceNumber.Device = 0 RETURN ENDIF CLEAR DATAMODEL Device DATAMODEL SELECT Device TABLE Device CONDITION "where \"deviceNumber\" = '" F-deviceNumber.Device "'" IF SQLSTATUS() <> 0 ERROR "Can not read Device." RETURN ENDIF IF SQLRETURN() = 0 LET V-isPresentDevice = FALSE() LET L-deviceNumber = F-deviceNumber.Device CLEAR RECORD Device LET F-deviceNumber.Device = L-deviceNumber DISPLAY ALL MESSAGE "New Device can be inserted." FOCUS entryDescription ELSE LET V-isPresentDevice = TRUE() FOREACH Device LET R-Device = O-Device BREAK ENDFOR DISPLAY ALL MESSAGE "Device can be updated." FOCUS entryDescription ENDIF At first this may look complicated to you, but if you look a bit closer, you will recognise that we already used most of the ProLinga logic commands in previous examples. Some commands here do need some additional explanation. We prevent the user from using the value 0. In that case an error message will be triggered. The DATAMODEL SELECT command executes a "Select * from" statement on a table in the database and will place the result in an updatable DataModel Device. Notice in this example the " around the column names and the " around the column names and ' around the values. This is the only place where the underlying database determines how to construct your SQL, mainly because most databases have their own SQL flavour. In this example we are using the PostgreSQL database. If you are using MySQL then you should surround the column names with ` and the data with ". Knowledge of the flavour of SQL you are using is required here. At the end of the command, you see "DATAMODEL Device". This means that if the query produces any results, load them into the DataModel "Device" that we created a little bit earlier. A little but further in the we test for SQLRETURN(). If this is set to 0 that means that a Device with the requested Device Number does NOT exist. In that case we clear the table buffer and the user can type the details of the new Device to be added. In case SQLRETURN() is set to a value, that represents the number of rows the query returned. With the FOREACH ProLinga command, all entries in a datamodel can be "walked through". Since we are only interested in the first entry (and only entry), we can use BREAK to break out of the loop after the first read. With the command LET R-Device = O-Device, the current DataModel entry can be assigned to the table buffer, so we can use it to reference the fields. Carefully study this logic. It may look difficult at first, but after analyzing it, it is not that diffult Since the screen "Device" is called from the logic "Device", it is wise to initialize the Variable "V-isPresentDevice" in this logic as well. Open your logic "Device" and change it to this: CLEAR TABLE Device LET V-isPresentDevice = FALSE() LET F-dateInstall.Device = DATE() SCREEN Device CONTAINER frame_main SOURCE device_include DISPLAY ALL MESSAGE "Device can be updated." FOCUS entryDeviceNumber Notice the new second line. You can run your application now, to see if you do not get any unexpected errors. Since the table in the database is still empty, you will not see any data yet. As soon as we press the "Apply" button we want to write the changes to the database. If we changed an existing record we want to perform an update and if created a new record we want to add it. The logic to do so is as follows: IF F-deviceNumber.Device = 0 ERROR "Please enter a Device Number." FOCUS entryDeviceNumber RETURN ENDIF IF V-isPresentDevice = TRUE() LET O-Device = R-Device DATAMODEL UPDATE Device ELSE LET O-Device = R-Device DATAMODEL APPEND Device ENDIF IF DATAMODELSTATUS() <> 0 ERROR "Error updating Device." RETURN ENDIF MESSAGE "Device has been updated." LET V-isPresentDevice = TRUE() After we check if a valid number was entered, we check if we either update an exising record or if we add a new one. To update the database using the logic command DATAMODEL, we first have to make sure that the current record in the DataModel contains the correct values. We know that the correct values are in the table buffer "Device", since we have linked data references like F-deviceNumber.Parts to the screen. To get these values to the DataModel "Device", you can either assign them one by one (M-deviceNumber.Device = F-deviceNumber.Device), or by assigning a complete table buffer record to the DataModel using the Group Data Reference prefixes O- (DataModel) and R- (table buffer Record). After an DATAMODEL UPDATE or APPEND, we have to check if the update went OK, by testing the a return status made available through the built-in function DATAMODELSTATUS Finally we inform the user by updating a message on the message bar and we have to set the Variable isPresentDevice to TRUE since even if we added a record, it is present now. Save the logic as "DeviceApply" and test your application. You should now be able to add new and modify existing records in the database. If we press the OK button, we want exactly the same actions to be performed when pressing the Apply button and after that we want to close the Device screen. Closing the Device screen in our situation means to clear the container, so calling the logic "Home". CALL DeviceApply CALL Home With the logic command CALL we can execute another logic block. Save this logic as "DeviceOK". When pressing the "Delete" button, we want to delete the record currently displayed on the screen. We have to perform some tests first. We have to check if a record is loaded and if so ask confirmation of the user if the record really can be removed. Finally the physical removal of the record if the user confirms. IF F-deviceNumber.Device = 0 ERROR "Please enter a Device Number." FOCUS entryDeviceNumber RETURN ENDIF IF V-isPresentDevice = FALSE() ERROR "No Device loaded." RETURN ENDIF ERROR "Are you sure you want to remove Device: " CLIP(F-deviceNumber.Device) "?" SEVERITY Question IF ERRORRETURN() <> 0 RETURN ENDIF LET O-Device = R-Device DATAMODEL REMOVE Device IF DATAMODELSTATUS() <> 0 ERROR "Error removing Device." RETURN ENDIF LET V-isPresentDevice = FALSE() CLEAR RECORD Device DISPLAY ALL MESSAGE "Device has been removed." We have seen all ProLinga statements before, so you should be able now to read this logic. Save the function as "DeviceDelete" and test your application. The first part of your application is now fully functional. In the next chapters we will make a search mechanism for a Device, in case the user does not know a Device Number. If the user does not know the Device Number, a search mechanism should be available. The user presses the "Find" button that we created earlier and a screen comes up, where the user can enter a filter and browse through the available Devices. One the selection is made, the screen disappears and the Device Number is pasted in the Device Number field on the screen Device. Before we create the Search screen, we first need a mechanism to get the value from the Search screen to the Device Number field on the Device screen. We can use a Variable (V-) for this like we seen before, but since in bigger applications, there will be more than one search screen, it is probably better to group them together in a Variable Group. We create a Variable Group that can hold a Device Number. If the application grows, we can add more search criteria later.

Screenshot of the pick list button on the object palette.

Press the button "New" on the tool bar of the Variable Group Editor to create a new Variable Group. Now enter the name of the Data Dictionary "deviceNumber" in the "Data Dictionary Name" field and leave the "Initial Value" field empty. Press the "Add" button and you will see that the value now appears in the list. Save the Variable Group with the name "Search".

Screenshot of the variable group "Search".

This change has no effect on your application yet, so there will not be any differences when running the application now. Open the Screen Dialog Editor in the ProLinga Developer. Press the "New Dialog" button and save the screen as "DeviceSearch". Now open this screen in the painter. Set the Title to "Search Device". Set the width of the screen to 400 and the height to 300.

Screenshot of base screen DeviceSearch.

Place a "Vertical Box" in the main area of the screen.

Screenshot of vertical box screen DeviceSearch.

Place a "Scrolled Window" object in the first section and within that a "List or Tree View" object.

Screenshot of list view screen DeviceSearch.

In the second section place a "Horizontal Box" with 3 columns.

Screenshot of horizontal box screen DeviceSearch.

In the first column place a "Label" object with the text "Filter:", in the second column place a "Text Entry" object and the last column place a "Button" object with using the stock icon "Index".

Screenshot of filter line screen DeviceSearch.

Now we make some cosmetic changes. The horizontal box should not expand, Border Width set to 5 and Spacing set to 5. Also we set the Border Width of the Scrolled Window to 5.

Screenshot of all objects screen DeviceSearch.

The painting of the Search Screen is now completed and we can populate it. We will use the "List Tree View" on the DeviceSearch screen as a Multi Column List Box. Therefore we need a ProLinga List Store object that contains the data we select. Since the list will be populated at run-time, we only need to create an empty List Store with the columns we want to see. We will only display the Device Number and the Description fields.

Screenshot of the list store button on the object palette.

Open the List Store Editor and press the "New" button on the toolbar to create a new List Store. In the tab "General", set the number of columns to 2 and leave the setting "Maximum Number of Rows" default to 1. Click on the tab "Store". Enter "Device Number" in the field "Label", select "Type" "Number" and set sort direction to "Ascending". Press the "Apply" button. Enter "2" in the field "Column Id" and details of the second column can be entered. Set "Label" to "Description", "Type" to "Text" and sorting to "None". Press "Apply" again. You will see both column names now in the list. Since the data will be loaded at run-time, we do not have to enter any data at row level. Save the List store with the name "Device".

Screenshot of the list store "Device".

In the next chapter we will link this List Store into our DeviceSearch screen, so it did not change the run-time behaviour of your application. We have created a DeviceSearch screen, but we have not linked any action handlers and data references to it. Open your screen "DeviceSearch" in the ProLinga Screen Editor and start the Painter. The Screen itself must be linked to "L-DeviceSearchRealize" for the "realize" signal. This signal is triggered as soon as the screen is created at run-time. To link signals to the screen itself either select the entry "DeviceSearch" in the Widget Window (first entry) or click on the "DeviceSearch" of the main frame of the Painter and then go to the "signal" tab of the Properties Window. The "Cancel" button must be linked to "C-cancel" for the "clicked" signal. The "OK" button must be linked to "L-DeviceSearchOK" for the "clicked" signal. The button should also be set as the 'default' button, meaning that logic linked to the button will be executed when the 'ENTER' button is pressed on the Text Entry field. Go to the 'Common' tab and set the toggle buttons 'Has Focus' and 'Can Focus' to 'Yes'. The "Index" button must be linked to "L-DeviceSearchList" for the "clicked" signal. The "Text Entry" field must be linked to Data Reference D:GET:G-deviceNumber.Search for the focus_in_event and D:PUT:G-deviceNumber.Search for the focus_out_event. With G- we can get a value from a Variable Group entry. It is also important that you give this object the name "entryFilter" so we can reference it from logic later on. Set the 'Activates Default' toggle button to 'Yes'. In the 'Common' tab set the toggle buttons 'Can Focus' and 'Has Focus' to 'Yes', so this field will get the input focus when displayed. It is important that we set the name of the "List Store", since we need to reference it later on from logic. Set the name to "DeviceSearchList".

Screenshot of the name of the List View.

Then we need to link a couple of signals to the "List View". Set a "cursor_changed" signal and link that to logic "PartSearchSelect". This logic is performed every time the user selects a line in the list view. Set a "button_press_event" signal and link that to "L-DeviceSearchOK". This logic will be triggered on a double mouse click. Set a "realize" signal and and link that to " I:"Device" ", the name of our List Store.

Screenshot of the signals of the List View.

This is all that needs to be done in the Painter for the "DeviceSearch" screen. Save the screen and continue with the next chapter where we will write all the matching logics. During the painting of the "Device Search" screen, we made many calls to ProLinga logics. We will now write all those logics. In the logics we need to be able to find out if the user presses OK or Cancel when closing the screen. For that we create a Variable (V-) called "accept". This will be of a boolean type that can accept a "True" and "False" value. If you are unsure how to create a Variable, look back a couple of chapters where we created the Variable "isPresentDevice". Do exactly the same, only this time name it "accept". When the user presses the "Find" button from the "Device" screen, we created an error message that this functionality has not been implemented. Open this function and replace the logic with the following one: LET V-accept = FALSE() LET G-deviceNumber.Search = "*" SCREEN DeviceSearch IF V-accept = TRUE() DISPLAY entryDeviceNumber ENDIF What we do here is to initialize the variable and variable group entry and then we call the screen "DeviceSearch". As soon as the user leaves this screen we check if the user pressed OK by testing the "V-accept" variable. In that case we want to display the selected value in the Device Number field. As soon as the "DeviceSearch" screen is displayed, we need to clear the List Store Device and display the contents of all fields. CLEAR LISTSTORE Device DISPLAY ALL This logic is performed as soon as the screen is displayed. If the user presses the "Index" button on the "DeviceSearch" screen, we want to get all Device entries from the database and place them in a List Store, so they can be presented in the List View. CLEAR LISTSTORE Device CLEAR DATAMODEL Device DATAMODEL SELECT DeviceSearch TABLE Device IF SQLSTATUS() <> 0 RETURN ENDIF FOREACH DeviceSearch LIST APPEND Device VALUE CLIP(M-deviceNumber.DeviceSearch) CLIP(M-description.DeviceSearch) ENDFOR DISPLAY DeviceSearchList We first clear the List Store from any data if any, execute a DATAMODEL statement to retrieve the data and append all values to the List Store. The built-in function CLIP, clips leading and trailing spaces from a data reference. If the user selects an entry in the multi column list box (List View), we want the selected value to be copied to G-deviceNumber.Search LIST GET Device VALUE G-deviceNumber.Search COLNO 1 DISPLAY entryFilter Here we get the value from the first column of the List Store "Device" and store it in the Variable Group entry "deviceNumber". The field is visually updated on the screen with the "DISPLAY" command. If the user presses OK, we want to confirm some checks if a correct selection has been made and if so, assign the value to the table buffer entry "F-deviceNumber.Device". We set the Variable "accept" to "True" so we know on the lower level that the user pressed "OK". IF G-deviceNumber.Search = "*" ERROR "Please enter a valid Device number." RETURN ENDIF IF CLIP(G-deviceNumber.Search) = "" ERROR "Please enter a valid Device Number." RETURN ENDIF LET F-deviceNumber.Device = G-deviceNumber.Search LET V-accept = TRUE() CONTROL cancel The ProLinga "CONTROL" commands destroys the screen "DeviceSearch" and processing resumes in the logic calling this screen (dialog). If you now run your application and press the "Find" button, you will see that you have a working search screen.

Screenshot of the Search Screen at Run-Time.

You will see that if you select a value and click "OK" (or just double click), the value will be brought back to the previous screen, where you can modify the record. Congratulations! You just completed your first ProLinga application. We hope that you enjoyed working with ProLinga and we would appreciate if you would let us know your comments. There are many more ProLinga commands and features in ProLinga that are not present in the tutorial. Please read the Reference Manual where all this is documented. &fdl;