|
|
|
|
|
- Lesson 2 - Searching and iterating over records
- Overview
- Using a Tab control in a window
- Creating the Tab control
- Changing the tab text and images
- Implementing the search
- Area for displaying the data found
- Exact-match search
- Generic search
- Looping through forms
- Window test
- To sum up
Tutorial - Managing data in a WINDEV application
Lesson 2 - Searching and iterating over records We will cover the following topics: - Record search management.
- Iterating over records.
 30 min In the previous lesson, we saw how to add and modify records. We will now complete our application by adding a search functionality (to modify a record, for example). We will modify the main window of the "WD Full Application" application to add tab panes. - The first tab pane will display the list of products and will allow you to add and modify them (we developed these features in the previous lesson).
- In the second tab pane you will be able to find a customer by name. The customer form will be displayed in the same tab pane.
Two search modes will be implemented: - an exact-match search,
- a generic search.
Warning
This lesson is based on the WD Full Application example used in Lesson 1. To follow this lesson, you must have completed the steps in Lesson 1.
Using a Tab control in a window In this example, we will include the search form in "WIN_Menu", instead of using a new window. So far, this window displays the list of products. We will use tabs to display different data in this window. Tabs are used to group data by theme. The user can directly access a theme by clicking the desired tab. To create tabs in this window, all we need is a Tab control. Creating the Tab control To display the data of the "WIN_Menu" window in a Tab control: - Open the "WIN_Menu" window if necessary:
- from the open document tabs.
- by double-clicking its name in the "Project explorer" pane.
- Select the controls and move them outside the window. This may seem "strange", but it will make it easier to work on the Tab control and then associate the controls with the desired tab pane.
- Create a Tab control in the window:
- On the "Creation" tab, in the "Containers" group, expand "Tab and associated" and select "Tab".
- Click in the window to create the Tab control.
- Position the Tab control at the top left of the window.
- A Tab control is created with two tabs by default. The Tab control occupies the entire available space in the window.
- Select the controls outside the window and move them to Tab 1.
- A green border appears when hovering the controls on the Tab control. This border indicates that the controls in the current tab pane will be automatically associated with it.
- Enlarge (if necessary) the window and the Tab control to display the Table control and the buttons in the Tab control.
 Handling controls in a Tab control- When you click another tab, all the controls associated with the current tab should disappear.
- To resize the Tab control without taking into account the anchors defined on the controls of the tab pane, hold down the Shift key while you resize the control.
Changing the tab text and images Change the name of the Tab control: - Double-click the Tab Control you've just created to open the description window.
- Change the control name. Name the control "TAB_View".
- Validate the control description window.
Two tabs are created by default. We will change their text directly: - Select the Tab control.
- Click "Tab 1". Once the tab switches to edit mode, enter "List of products". Press Enter to confirm.
- Click "Tab 2". The tab pane is displayed. Click "Tab 2" again. Type "Find customers". Press Enter to validate.
We will associate an image with each tab in the Tab control. To do so: - Open the Tab control description window (double-click the control, for example). The "General" tab of the description window allows you to configure the characteristics of each tab in the Tab control. The list of tabs is displayed on the left. You can change the characteristics of each selected tab on the right of the screen.
- In the description window, select "List of products".
- The tab characteristics are displayed.
- We will associate an image to the tab using WINDEV's image catalog.
 If an image can be displayed in a control or window, WINDEV proposes to use the image catalog. This image catalog can be opened via the "Catalog" option (available by clicking the  button). The catalog contains hundreds of images, cliparts and more. - Click
on the right of "Image". Select "Catalog" in the context menu that appears. The image catalog window appears. - Type "Product" in the search area. Click the search icon to start the search.
- Select
and validate ("OK"). - The image settings window is displayed. In this window, you can define the characteristics of the image to be generated, including size, lightness, etc.. Keep the default options and confirm.
- The image is generated in the project directory and the corresponding file is automatically associated with the current element.
- In the Tab control description window, click "Find customers" in the list of static tabs.
- Click
on the right of "Image". Select "Catalog" in the context menu that appears. The image catalog window appears. - Type "Person" in the search area. Click the search icon to start the search.
- Select, among the proposed images, the icon representing two persons (
) and validate. - Keep the default options in the image settings and confirm.
- Validate the Tab control description window.
We have just created a new control. Now, we must define its anchors in the window. When the window is enlarged, the Tab control must also be enlarged in order to occupy the entire available space. Therefore, the control must stretch to the right and to the bottom. - Select the Tab control.
- Right-click to open the context menu and select "Anchor".
- In the anchor settings window, select
and confirm. - Save the window by clicking
in the quick access buttons.
The "WIN_Menu" window was entirely created. We can now focus on the content of the Tab control pane for finding customers. This Tab control pane will be divided into several areas: - An area for displaying the data found.
- An area for entering the search elements.
- An area containing the navigation buttons.
Area for displaying the data found First, we will create different controls to display the customer data. To create Edit controls, we will simply drag and drop elements from the "Analysis" pane, just like we did for the product form window. To create the controls that will display the customer data: - Open the WIN_Menu window in the editor and click the "Find customers" tab. The empty tab pane appears.
- 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 "Customer" data file to see its items. - Select the items of the Customer data file. You can select multiple elements by holding the Ctrl key down.
- Drag and drop these items onto the "Find customers" tab pane.
- The controls are automatically created in the Tab control pane. These controls are bound to the corresponding item in the data file.
- Save the window (Ctrl + S).
We will align the controls and make them the same size: - Select the "City" control and then the other Edit controls in the window (hold the Ctrl key down while clicking the different controls). The first selected control will be used as reference to set the size of the other controls.
- On the "Alignment" tab, in the "Inside and outside" group, click "Justify (Ins. and Out.)".
Test the window (click  in the quick access buttons). Click the "Find customers" tab. The window is displayed with empty controls. Close the test window to go back to the editor. Exact-match search First, let's perform an exact-match search.  Key information: Exact-match searches look for records that exactly match the search keywords. To perform an exact-match search, we are going to select the customer name in a Combo Box control. The "Exact-match search" Button control will be used to display the form of the corresponding person. In this case, only one person matches the selected name. The Combo Box control will be located above the created controls. If the controls are too close to the top of the Tab control pane, you will need to move them down. To do so: - Select all the controls in the Tab control pane:
- Press Ctrl + A to select all the controls in the window and in the current tab pane.
- Hold the Ctrl key down and click the Tab control. Only the controls within the current pane are selected.
- Release the Ctrl key.
- Move one of the selected controls down.
- All controls are moved down.
To create the Combo Box control used to select the desired person: - Create a Combo Box control. Go to the "Creation" tab, "Usual controls" group, and click "Combo Box".
- Click "Find customers", and position the control between the tab and the "Customer ID" control.
- The Combo Box control creation wizard appears. We will create a Combo Box control based on the "Customer" data file.
- Select "Display data from a data file or existing query".
Proceed to the next step of the wizard.
- Select the "Customer" data file. Go to the next step.
- We will display the customer's first and last name.
- Deselect the "CustomerID" item.
- Select the "FullName" item.
- Go to the next step.
- The "FullName" item will also be used to sort the list of customers displayed in the Combo Box control. Select the "FullName" item.
- Go to the next step.
- The value returned by the Combo Box control will be the "CustomerID". This is the value that will be searched in the Customer data file. Select the "CustomerID" item.
Go to the next step.
- The Combo Box control will not be bound to any item. Keep "No" and go to the next step.
- Validate the next step ("Next").
- Give a name ("COMBO_Customer" for example) and a caption ("Sought customer" for example) to the control.
- Finish the wizard. Position the Combo Box control in the window (e.g. in upper-left corner).
- Select and resize the Combo Box control so that the entire customer name is displayed.
To create the Button control to find customers: - On the "Creation" tab, in the "Usual controls" group, click
. - Position the Button control next to the Combo Box that was just created.
- Name the control "BTN_ExactMatchSearch" and define "Exact-match search" as caption.
- If necessary, adjust the size of the control so that the caption is displayed properly in the control.
- Select the "BTN_ExactMatchSearch" control and press F2 to see its code.
- Write the following WLanguage code in the "Click" event of the control:
Customer.ReadSeekFirst(CustomerID, COMBO_Customer)
IF Customer.Found() THEN
Customer.ToWindow()
END
- Let's take a look at this WLanguage code:
- <Data file>.ReadSeekFirst is used to perform an exact-match search. In this example, the search is performed on the Customer data file and on the CustomerID item. The search value is the last parameter of the function. Here, the search value corresponds to the value selected in the Combo Box. This value is obtained by using the name of the Combo Box control (COMBO_Customer).
- <Data file>.Found is used to check the search result. If <Data file>.Found returns True, a value was found; if <Data file>.Found returns False, no value was found. Any record found is read and it becomes the current record in the data file.
- In this code, if the record was found, it is displayed by <Data file>.ToWindow.
 <Data file>.ToWindow gets the data from the data file items and displays it in the corresponding controls. <Window>.ToFile, on the other hand, gets the data from the controls and updates the data file.
- Close the code editor.
- Save the window (Ctrl + S).
Let's test our exact-match search: - Test the window (click
in the quick access buttons). - Click the "Find customers" tab if necessary.
- Select a value in the Combo Box control and click "Exact-match search".
- The result appears immediately.
- Close the test window to go back to the editor.
Generic search We are now going to perform a generic search.  Key information: A generic search looks for all elements beginning with the search value. To perform this search, we will create an Edit control to enter the name you are looking for, and a Button control to launch the search. To create the search control: - If necessary, select the "Find customers" tab of "WIN_Menu" in the editor.
- Create an Edit control. Go to the "Creation" tab, "Usual controls" group, and click
. - In the window, click below the Combo Box control ("Sought customer"). The edit control is created.
- Name the control "EDT_Sought_Name" and define "Sought name" as caption.
To create the Button control to launch the generic search: - Create a Button control. Go to the "Creation" tab, "Usual controls" group, and click
. - Position the control next to the Edit control that was just created.
- Name this control "BTN_GenericSearch" and define "Generic search" as caption.
- If necessary, adjust the size of the control so that the caption is displayed properly in the control.
- Select the "BTN_GenericSearch" control and press F2 to see its code.
- Write the following WLanguage code in the "Click" event of the button:
Customer.ReadSeek(FullName, EDT_Sought_Name)
IF Customer.Found() THEN
Customer.ToWindow()
ELSE
Error("No customer matches")
END
<Data file>.ReadSeek is used to perform a generic search. In this example, the search is performed on the "Customer" data file and on the "FullName" item. The search value corresponds to the value typed in the "EDT_Sought_Name" control. This value is obtained by using the control name. - Close the code window.
- Save the window (Ctrl + S).
Now, we can simply test our generic search: - Test the window (click
in the quick access buttons). - Click the "Find customers" tab if necessary.
- Enter a value in the edit control (for example "BEEF") and click "Generic search".
- The result appears immediately. However, if several records correspond to the search, only the first one is displayed.
- Stop the test and go back to the editor.
Looping through forms We will add four Button controls to iterate over the different records of the "Customer" data file. These controls are in a "Navigation" layout. These controls will allow you to: - iterate over the different records in the data file,
- iterate over the records that match a generic search.
Each button has an icon that displays: - the first record,
- the previous record,
- the next record,
- the last record.
To create the Button control used to display the first file record: - Go to the "Find customers" tab in the editor.
- On the "Creation" tab, in the "Usual controls" group, click
. - The shape of the control appears under the mouse pointer. Then click the Tab control pane, below "Generic search". The Button control is automatically created.
Skin templates are used to standardize the windows in a project. They define the style of all controls in the windows. A specific style is defined for each navigation button. To apply this style: - Select the Button control if necessary.
- Right-click to open the context menu and select "Choose a style".
- All the button styles are displayed in the window that appears. Under "Other styles", select "BTN_First".
- Validate.
Rename the Button control: - Open the control description window:
- Select the Button control.
- Right-click to open the context menu and select "Description".
- Name this control "BTN_First".
- Validate the description window.
| Your turn: Likewise, create 3 Button controls.- Name these controls as follows: "BTN_Previous", "BTN_Next" and "BTN_Last".
- Associate these controls with the following styles: "BTN_Previous", "BTN_Next" and "BTN_Last".
|
We will now write the WLanguage code associated with the different buttons. Let's start with the button for displaying the first record. - Right-click the control. Select "Code" in the menu that appears.
- In the code window, write the following WLanguage code in the "Click" event:
Customer.ReadFirst()
IF Customer.Out() THEN
Info("No form to view.")
ELSE
Customer.ToWindow()
END
<Data file>.ReadFirst is used to read the first file record according to the key used for the last search (FullName in our case).
For the button that displays the previous record, you can write the following WLanguage code in the "Click" event of "BTN_Previous":
IF Client.RecNum() <= 0 THEN
Customer.ReadLast()
ELSE
Customer.ReadPrevious()
END
IF Customer.Out() THEN
Info("Start of file reached.")
ELSE
Customer.ToWindow()
END
Likewise, write the following WLanguage code in the "Click" event of "BTN_Next":
IF Client.RecNum() <= 0 THEN
Customer.ReadFirst()
ELSE
Customer.ReadNext()
END
IF Customer.Out() THEN
Info("End of file reached.")
ELSE
Customer.ToWindow()
END
Lastly, write the following WLanguage code in the "Click" event of "BTN_Last":
Customer.ReadLast()
IF Customer.Out() THEN
Info("No form to view.")
ELSE
Customer.ToWindow()
END
In these different codes: - <Data file>.ReadLast reads the last record in the data file based on the key used for the last search.
- <Data file>.ReadNext reads the record whose key value is immediately greater than the one of the current record.
- <Data file>.ReadPrevious reads the record whose key value is immediately less than the one of the current record.
In any case:  The code in the "Next" and "Previous" Button controls contains additional lines of code to: - Check whether a search has already been started in the Customer data file (check the result of <Data file>RecNum to find out if a read operation has already been started).
- Read the first or last record if necessary. The next or previous record cannot be read if no reading has been started in the data file.
Save the window by clicking  in the quick access buttons. Window test Let's test the window one last time: - Test the window (click
in the quick access buttons). - Click the "Find customers" tab if necessary.
- Find a customer (enter "BEEF" and start a generic search, for example).
- Browse the data file by clicking each of the navigation buttons.
- Stop the test to go back to the editor.
 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 discovered how to perform exact-match and generic searches and how to loop through a data file. In the next lesson, we will perform a multi-criteria search in the database records.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|