- Lesson 1 - Windows for entering and editing data
- Overview of the example used in this tutorial
- Opening the example project
- Creating a window to list products
- Creating the window
- Creating controls
- Window test
- Table control features
- Creating a "Product form" window
- Creating the window
- Creating data-bound controls
- Creating buttons
- Improving the UI of the "Product form" window
- Aligning controls
- Resizing the window
- Window appearance
- Managing anchors
- Opening the form from the list of products
- Resizing the window in the editor
- Create the Button control
- Displaying the product selected in the Table control
- Editing a product
- Modifying the product image
- Validating the changes made to the product
- Testing changes made to a product
- Creating a new product
- Adding a Button control
- Adding a new record in the data file
- Testing the addition of a product
- Viewing records
- To sum up
Tutorial - Managing data in a WINDEV application
Lesson 1 - Windows for entering and editing data We will cover the following topics: - Overview of the example project.
- Creating a menu window to list products.
- Creating a product form.
- Adding and modifying products.
 50 mn Overview of the example used in this tutorial In this tutorial, we will create an application that manipulates data files in HFSQL Classic format. This order management application will be used to: - View, enter and modify products,
- Print reports,
- Display statistics,
- Send emails,
- etc.
Later on, other tutorials will show you how to deploy and distribute the application to end customers. We are going to: - create different windows to list, add and modify products.
- create different reports.
These operations will allow you to discover several topics regarding the management of data files and they will also allow you to use some WINDEV features. Opening the example project In WINDEV, open the "WD Full Application" project: - Go to the WINDEV home page (Ctrl + <).
- On the home page, click "Tutorial", then in "Tutorial - Full application with data", click "Open exercise project".
 In this lesson, we will focus on how to create simple windows used to handle data files. Therefore, we will work with a ready-to-use project that contains no elements. We will see how to create a project in Creating a WINDEV project and its analysis.
Warning
This project will be used in the different lessons of this tutorial.
Creating a window to list products Before creating or modifying a product, let's create a window listing the different products available in our application. To create the window with the list of products, we will first create a blank window and then add all the necessary controls. Creating the window To create a new window: - Click
in the quick access buttons (or press Ctrl + N). - In the "New" window, click "Window", then "Window".
- In the wizard, click the "Based on a template" tab and choose "Use: WINTPL_Template".
- Validate.
- In the window that appears, specify the title of the window: "Menu".
Note: The window name (which will be used in the code) is created automatically, based on the window title. However, you can specify a name different from the window title. - Validate.
 In this tutorial, we use a window template to maintain consistency across the different windows of our application. WINTPL_Template contains a logo that will appear on all the windows:
For more details, see Window templates. Creating controls We will use a Table control to create the list of products. This control will display data from the "Product" data file.  What is a Table control?It's important to make a distinction between a "Table" and a "Table control". - Table is used in the context of SQL databases.
- A Table control displays data in the UI. In this case, the data can be entered directly or come from a data file (or table).
To create the Table control: - On the "Creation" tab, in the "Data" group, expand "Table and List Box" and select "Table (Vertical)". The control will follow the mouse cursor.
- Click within the window to open the Table control creation wizard.
- This Table control will display the records from the "Product" data file.
In the wizard, select "Display data from a data file or existing query".
Go to the next step of the wizard ("Next"). - The wizard lists the various data files and queries present in the current project.
Expand "Analysis" if necessary and select the "Product" data file.
Go to the next step. - The wizard shows the list of items in the "Product" data file.
By default, all items are checked in order to be displayed in the Table control. In our case, we will display all items EXCEPT the "ProductID" identifier that corresponds to the automatic identifier of the data file. Uncheck "ProductID".
Go to the next step. - Then, the wizard proposes to select the sort item. This item will be used to sort the data displayed in the Table control. The items displayed in the wizard are the ones defined as key items in the analysis. We will set the order of the items based on their caption.
Click the "Caption" row.
- Finish the wizard.
- The Table control is automatically created in the window. The control is automatically positioned and resized to fit all available space in the window.
 The data is already displayed in the control, even in the editor. This is known as "Live data": The contents of the data files located on the development computer are used in the windows or reports manipulated in the editor. This feature is very useful to define the size of the controls in a window for example. Window test We will test the window we have just created. - Click
in the quick access buttons. - The window is automatically displayed with its data at runtime.
- You can navigate through the products with the scrollbar (or with the arrow keys).
Table control features Let's see how the Table control works at runtime, from the perspective of an end user.
Remarks: - First of all, the Table control has the same aspect at runtime and in the editor. This is called WYSIWYG ("What You See Is What You Get").
- Small icons appear at the top of the columns:
- the double arrow indicates that the column can be sorted ("Reference" or "Caption" column for example). For example, click the "Caption" column twice. The data is displayed in a different order. An arrow on the left of the column indicates that it is sorted and shows the sort direction.
- the magnifier indicates that a search can be performed in the column. For example, click the search icon of the "Reference" column. An input area allows you to type the search reference. Type "REF-010". The product corresponding to this reference is automatically displayed.
- A context menu is available for the Table control and its columns. This context menu appears:
- by right-clicking the column of the Table control.
- by clicking the arrow in the upper-right corner of the column headers.
This context menu is used to export the content of the Table control to Excel (or OpenOffice.org Calc), Word (or OpenOffice.org Writer), to print, etc.
In just a few minutes, we have seen some features that are automatically included in the Table control. You don't need to write code to make these features available to your users. These features are called "AAF" (Automatic Application Features).  Multiple controls include AAFs by default. If these features should not be available (for security or privacy reasons), they can be disabled in the editor or in the code. Now that the list of products is displayed, we may want to edit a given product. To do so, we are going to create a window used to display the product details. Close the test window using the "X" at the upper-right corner of the screen. The WINDEV editor is redisplayed. Creating a "Product form" window Creating the window We will create a window to display the characteristics of the product selected in the Table control. This type of window is called "Form" because it is a descriptive form of the desired element. Let's create a new window. | Your turn: As we have already created a window in this lesson, here are just a few indications: - You must use WINTPL_Template to create the window.
- Set "Product form" as window title ("WIN_Product_form" will be suggested as window name).
|
Creating data-bound controls In this example, the "Form" window will display the data from the different items in the "Product" data file. To create the different Edit controls, we will use the items of the Product data file directly: - In the "Project Explorer" pane, expand "Analysis" by clicking the
icon. The data files defined in the project analysis are displayed. - Click the icon to the left of the "Product" data file to view all its items.
- Select all the items displayed in the pane (except "ProductID"). You can select multiple elements by holding the Ctrl key down.
- Drag the items and drop them onto the previously created window.
- Different controls are automatically created in the window. These controls are bound to the corresponding item in the data file. To check this:
- Select the "Reference" control for example.
- Right-click to open the context menu and select "Description".
- Go to the "Link" tab of the description window:
This tab shows that the current Edit control is bound to the "Reference" item in the "Product" data file.
- Close the description window.
- Save the window.
Move the controls and resize the window to get the following UI:
Creating buttons We will add and modify products from the list in the "WIN_Product_form" window. To do so, we are going to add validation and cancellation buttons. To create the Button control to validate the data entered: - On the "Creation" tab, in the "Usual controls" group, expand "Button" (click the arrow under
). - The list of preset buttons is displayed.
- Select "Validate button". A ghost image of the Button control appears under the mouse pointer.
- Click to the right of the Edit controls to create the Button control.
Add the Button control to cancel the input following the same steps. - On the "Creation" tab, in the "Usual controls" group, expand "Button" (click the arrow under
). - In the list of preset buttons, select "Cancel button". A ghost image of the Button control appears under the mouse pointer.
- Then click below the "OK" Button control to create the control.
Improving the UI of the "Product form" window This window is quite simple, let's improve its UI. Some little details can become major obstacles for the user, so let's try to sort them out right now. Aligning controls First, we will align the controls and make them the same size: - Select the "Caption" control and then all the Edit controls in the window (hold the Ctrl key down and click on each control, for example). The first selected control will be used as reference to set the size of the other controls.
- In the ribbon, go to the "Alignment" tab. This tab contains all alignment options available for the controls.
- We will align the outside and inside borders of the controls. Click "Justify (Ins. and Out.)".
 If you don't know which alignment to choose, hover over the different options available in the "Alignment" tab. When you hover the mouse over an option, the controls selected in the window are automatically positioned and/or resized according to the hovered option. To apply the alignment, click the option. If you don't want to apply the alignment, simply exit the alignment options. The controls go back to their initial position.
Resizing the window Once we have positioned all the controls in the window, we can define its final size. In our example, the window is still too big. We can use the sizing handles, as we have done previously. However, WINDEV also offers the possibility to directly enter the window dimensions. - Click on the window in the editor. The window is selected.
- In the message bar, enter the new window size. For example, enter 745 x 345.
- The window is automatically modified. To undo the changes and select another size, press Ctrl +Z.
Window appearance Let's see the appearance of our window. We will use a specific execution mode to display only the window's UI (without executing any code). - On the "Modification" tab, in the "Preview" group, click "Preview".
- Enlarge the window via the sizing handles at the bottom of the window. The position of the controls does not change, so there is a large empty area in the window.
Two methods can be used to solve this problem:- Prevent the window from being resized.
- Define the anchors, i.e., the behavior of the controls when the window is resized. That's what we are going to do.
- Close the preview by clicking the "Close" button or the "X" icon at the upper-right corner of the window.
Managing anchors We will now use anchors to define how the different controls react when the window is resized.  How to set anchors in a window?To set the anchors: - In the editor, reduce the window to its minimum size. All outside window borders should be close to a control (while preserving margins).
- Analyze each control and imagine how it should react as the window is enlarged.. Then, apply the corresponding anchors.
For this window, we are going to define the anchors together: - The "OK" and "Cancel" Button control must be anchored to the right.
- Select these two controls.
- Right-click to open the context menu and select "Anchor".
- In the anchor options window, select "Right".
- Confirm.
- Small red arrows appear in the editor, indicating that the controls are anchored to the right.
- The edit controls must be enlarged horizontally:
- Select the 4 edit controls.
- Right-click to open the context menu and select "Anchor".
- In the anchor options window, select "Width" (
). - Validate.
- We will test the behavior of this window in the preview:
- On the "Modification" tab, in the "Preview" group, click "Preview".
- Enlarge the window. The controls adapt horizontally.
- We will now define the vertical anchors of the controls.
- The "Description" control can contain a larger or smaller product description. It is the largest control in the window. It must fill all the available space. Set a horizontal and vertical anchor (
). - A red line appears automatically around the "Price BT" control. The window editor indicates the anchor settings are incorrect. If the "Description" control stretches down, the "Price BT" control must also move down.
- Open the anchoring window of the "Price BT" control. The editor automatically highlights the best anchoring option with a green checkmark. In this case, "Width and bottom". Select the suggested anchor and confirm.
- We will test the behavior of this window in the preview:
- On the "Modification" tab, in the "Preview" group, click "Preview".
- Enlarge the window. The controls adapt horizontally and vertically.
- Close the window preview to go back to the editor.
Opening the form from the list of products Now, let's see how to open the form of the product selected in the list. The desired behavior is quite simple: The user will select the product in the Table control, and will open the product details via a Button control. We are going to: - Resize the window and the Table control so that there is enough room for the Button control.
- Create the Button control.
- Display the product form.
Resizing the window in the editor We are going to modify the "WIN_Menu" window to create a Button control. Click "WIN_Menu" in the open document tabs: Currently, the Table control occupies the entire window. Let's enlarge the window to create more space to the right of the Table control: - Hold the Shift key down.
- Expand the window to the right with the sizing handles.
 The Shift key allows you to ignore the anchoring options of the controls when resizing the window.
We now have space on the right to create the Button control that will allow us to view the selected product in the Table control. Create the Button control In this tutorial, we already seen how to create "Cancel" and "OK" buttons using preset Button controls. We will follow the same steps to create the "Modify" Button control. To create the Button control to view the product: - On the "Creation" tab, in the "Usual controls" group, expand "Button" (click the arrow under
). - Enter "Modify" in the search box at the top of the list of preset Button controls. Click "Modify button". The shape of the control appears under the mouse pointer. Then, click on the right of the Table control to create the Button control.
The control is created. Now, let's write the code to open the form window: - Right-click the Button control you have just created. Select "Code" in the menu that appears.
- In the code window, write the following WLanguage code in the "Click" event:
 The code completion mechanism will help you write the code. When you enter a dot after the window name, a drop-down list will open with the functions that can be used in that window. Simply select the function you want with the keyboard or mouse. - Take a closer look at the WLanguage code. The <Window>.Open function opens the "WIN_Product_form" window.
- Save changes by clicking
in the quick access buttons. - Close the code window (click the "X" icon in the upper-right corner of the code editor).
Displaying the product selected in the Table control We are now going to modify the "WIN_Product_form" window to display the product that has been selected in the Table control. Click "WIN_Product_form" in the open document tabs to open the window in the editor. To display the product data: - Open the WLanguage events associated with the window:
- Right-click outside the window.
- Select "Code" in the context menu that appears.
- The code editor appears. The WLanguage events associated with the window are displayed.
- Enter the following WLanguage code in the "End of initialization of WIN_Product_form" event:
<Data file>.ToWindow displays the data from the data file in the controls, for the current record. In our case, the current record will be the record selected in the Table control of "WIN_Menu" window. - Close the code window.
- Save the window (Ctrl + S).
Now, we can simply check the end result. - Click "WIN_Menu" in the open document tabs to open the window in the editor.
- Test the window (click
in the quick access buttons).- In the list of products, click one of the products.
- Click the "Modify" button.
- The product detail window appears. This is the expected result.
- Close the different test windows using the "X" at the upper-right corner of the windows.
We will now modify the "WIN_Product_form" window to modify a product. We are going to: - allow the user to modify the product image.
- add Button controls to save or cancel changes made in the product form.
Modifying the product image The user will be able to modify the product image in the Product form. To do so, we are going to create a "Modify" Button control below the product image. This control will open a file picker to select the desired image.
Open the "WIN_Product_form" in the editor by selecting its corresponding tab. To create the Button control to modify the image: - Create a "Modify" Button control using the preset controls.
- Place the control below the product image.
- If necessary, resize the Button control (using the handles) so that it has the same width as the Image control.
 When resizing the control, an automatic magnetism effect simplifies the alignment of the Button control with the Image control.
- Right-click on the Button control. Select "Code" in the menu that appears.
- In the code window, write the following WLanguage code in the "Click" event:
- The code editor proposes a code wizard.
- Click "fImageSelect wizard".
- The code wizard opens.
 WINDEV includes multiple code wizards that will generate the corresponding lines of code via simple questions. Don't hesitate to use them, you will avoid syntax errors.
- Keep all the default options in the wizard and validate. The corresponding WLanguage code is automatically entered.
sFile is string
sFile = fImageSelect("", "", "Select an image...")
fImageSelect is used to open the image selection window and associate it with the "File" variable. - Add the following WLanguage code:
IF sFile <> "" THEN
IMG_Visual = sFile
END
This WLanguage code is used to assign the selected file to the Image control in the window. - Close the code editor (click the "X" icon in the upper-right corner of the code editor).
We will test this feature once all the changes in the product form are made. Validating the changes made to the product Two Buttons controls have been created in the "WIN_Product_form" window: - an "OK" Button control to validate changes,
- a "Cancel" Button control to return to the product list.
We will now write the WLanguage code of these two controls. First, open the "WIN_Product_form" window. We will now write the WLanguage code associated with the "OK" Button control. - Right-click the Button control and select "Code" in the context menu.
- Write the following code in the "Click" WLanguage event:
Product.FromWindow()
Product.Modify()
Close()
Let's take a look at this WLanguage code:- <Data file>.FromWindow updates the items of the current record with the data from the bound controls. This function is equivalent to the following lines of code:
Product.Reference = EDT_Reference
Product.Caption = EDT_Caption
Product.Description = EDT_Description
...
This method results in cleaner and more efficient code, especially in windows with a large number of controls. One line of code can assign all the required values. - <Data file>.Modify updates the current record in the data file.
- Save changes by clicking
in the quick access buttons. - Close the code window (click the "X" icon in the upper-right corner of the code editor).
The modifications performed in the "WIN_Product_form" window must be taken into account in the Table control used to list the products. To do this, we will simply modify the WLanguage code associated with the "Modify" Button control in "WIN_Menu". - Click "WIN_Menu" in the open document tabs to open the window in the editor.
- Select the "Modify" Button control and open the code editor (F2).
- Modify the "Click" event as follows:
WIN_Product_form.Open()
TABLE_Product.Display(taCurrentSelection)
Let's analyze this code:- <Table>.Display is used to update the Table control with the data modified in the product form.
- The taCurrentSelection constant is used to specify that the Table control must be updated from the position of the selection bar.
- Save changes by clicking
in the quick access buttons. - Close the code window (click the "X" icon in the upper-right corner of the code editor).
Testing changes made to a product We have made all the changes to make it possible to modify a product. Now, we can run a test. To test the changes of a product: - Test the project (click
in the quick access buttons). - WINDEV asks you to select the first project window. In our case, this window corresponds to "WIN_Menu". Select this window and validate.
 The first window of the project is the first window that will be opened when the application is launched. For more details, see First project window. - The project starts in test mode and the first window is displayed.
- Select a product from the product list (for example the first one) and click "Modify".
- The details of the selected product are displayed in the form window.
- Change the price (e.g., 200.00) and click "OK".
- When you go back to the list of products, you will notice that the price of the product has been updated.
- Open the product details again.
- Click the "Modify" button below the image. The image picker is displayed. Select an image and validate. The image is displayed in the form.
- Click the "Cancel" button. The image modification was ignored in the data file.
- Click the "X" to close the application.
The principle for creating a product is as follows: - In the product list window, we will add a "New" Button control that will open the "Product form" window.
- Then, we will modify the code of the "Product form" window to add a product to the Product data file.
Adding a Button control To add a "New" Button control to "WIN_Menu": - Create a "New" Button control using the preset controls.
- Position the "New" button above the "Modify" button (move the latter if necessary).
- Modify the WLanguage code of this control:
- Select the control and press F2.
- Write the following code in the "Click" WLanguage event:
Product.Reset()
WIN_Product_form.Open()
TABLE_Product.Display(taCurrentRecord)
Let's analyze this code:- <Data file>.Reset resets the item variables in the "Product" data file to the default values to handle the new record.
- <Window>.Open is used to open the product form to enter the new record.
- <Table>.Display is used to re-display the Table control. In this code, the taCurrentRecord constant re-displays the Table control from the position of the current record.
- Save changes by clicking
in the quick access buttons. - Close the code window (click the "X" icon in the upper-right corner of the code editor).
Adding a new record in the data file We will now modify the product form window to add a new record. - Open the "WIN_Product_form" window.
- We will make changes in the WLanguage code of the "OK" button:
- Select the "OK" Button control and press F2.
- In the "Click" event, replace the existing WLanguage code with the following:
Product.FromWindow()
IF Product..NewRecord THEN
Product.Add()
ELSE
Product.Modify()
END
Close()
Let's take a look at this WLanguage code:- The NewRecord property indicates whether the current record should be created.
- If <Data file>.Reset has been called previously, the property returns True (when "New" is clicked) and the record is created with <Data file>.Add.
- If the current record already exists, it is modified with <Data file>.Modify.
- <Data file>.Add adds the record to the data file. This function takes the values in memory and writes the contents of the items to the data file itself. The indexes are immediately and automatically updated. In this case, the "Product" data file is updated.
- Save changes by clicking
in the quick access buttons. - Close the code window (click the "X" icon in the upper-right corner of the code editor).
Testing the addition of a product To test the addition of a product: - Test the project (click
in the quick access buttons). - In the list of products, click the "New" button.
- Enter a new product with the following characteristics:
- Reference: REF-337
- Caption: WB Surf
- Description: Surf with WINDEV colors
- Price: 150
- Confirm. The new product appears in the list of products.
- Click the "New" button again.
- Enter a new product with the following characteristics:
- Reference: REF-337
- Caption: WB Surf
- Description: Surf with WEBDEV colors
- Price: 150
- Confirm. A specific window is displayed:
This window lets the user know that a duplicate has been found. The reference (which is a unique key) is the same for two products. This window allows you to change the reference value. For example, type "REF-338".
This window handles HFSQL errors automatically.
 You may encounter different errors when adding or modifying records. Some examples may include duplicate records, integrity errors, wrong passwords, etc. By default, WINDEV handles errors automatically. For each error encountered when handling database records, a specific window is displayed to the user. This window allows users to modify their data directly. For more details, see Automatic error handling. Viewing records The new added records can be immediately viewed in the Table control of the "WIN_Menu" window. However, in some cases (when running tests for example), you may want to see the content of the data file directly. WINDEV offers a simple tool to view the contents of the data files while the application is being developed (e.g. when the windows that will display data have not yet been created). This tool is WDMAP. We will use it to view the contents of the Product data file. To start WDMAP: - On the "Tools" tab, in the "Database" group, click "WDMap".
- Select the "Product" data file. The data file content is displayed.
- Sort the elements by reference (click the header of the "Reference" column), the two added records appear.
 Completed project Do you want to check the end result of the steps described here? A completed project is available. This project contains the different windows created in this lesson. To open the completed project, go to the home page and click "Tutorial", then in "Tutorial - Full application with data", click "Open completed project". In this lesson, we saw how to add and modify a record in a database via a user interface. In the next lesson, we will perform a simple search in the database records.
|
|
|