ONLINE HELP
 WINDEVWEBDEV AND WINDEV MOBILE

New WINDEV Mobile 2024 feature!
Help / WINDEV Mobile Tutorial / Tutorial - Developing an Android and iOS application
  • Lesson 4 - Windows with search
  • Overview
  • Principle
  • Creating a query to find products
  • Creating the query
  • Query test
  • Adding a selection condition
  • Test of the query with parameters
  • Creating the interface
  • Creating the window
  • Opening the product form
  • Window test
  • Implementing the search functionality
  • Improving the window
  • Pull to refresh
  • Using a sliding menu
  • To sum up

Tutorial - Developing an Android and iOS application

Lesson 4 - Windows with search
We will cover the following topics:
  • Creating a query with parameters.
  • Creating a window via the wizard.
  • Implementing the search.
  • Using the Pull-to-refresh functionality.
  • Adding a sliding menu.
Durée de la leçon 30 min
Overview
In lesson 2, we created a window listing the products in a Looper control.
In this lesson, we will create a window following the same steps, but we will add an option to search by product name:
  • the window displays the list of products in a Looper control.
  • when the user enters the name of a product in the search field, only the products that match the search criteria are displayed in the Looper control.
In our example, this search will be performed on the "Product" data file.
Warning
This lesson is based on the WM Product Management example used in Lesson 1. To follow this lesson, you must have completed the steps from the previous lessons.
Principle
The window we are going to create will be as follows:
Find
To create this window, we are going to:
  • Create the query for selecting records in the Product data file.
  • Create and configure the search window.
What is a select query?
A select query is a query that will "choose" the records corresponding to the specified criteria.
This type of query is called "select query" because of the SQL SELECT command.
Creating a query to find products

Creating the query

The query editor will be used to create the query.
  1. Click Create an element in the quick access buttons. The new element window appears: click "Query­". The query creation wizard starts.
  2. Select the "Select" option.
    This query will be used to select records. Go to the next step.
  3. The query description window appears.
  4. Give a name and a caption to your query: set "QRY_Products" as query name and "Find products by name" as caption:
    Query name
To build the query, we are going to select the elements that will be displayed in the result. We will use this query to show the characteristics of a given product: the product caption, description and image.
  1. Under "Analysis", select the "Product" data file.
  2. Expand the "Product" data file by clicking on the arrow: The list of items is displayed.
    Selecting data file items
  3. Select the "ProductID" item and click the button. The item appears in the list of query elements.
  4. Repeat the same steps for the "Caption", "Description" and "Photo" items.
  5. The query description window is as follows:
    Query description window
  6. Validate the query description window ("OK" button).
  7. The graphic representation of the query and the window for saving the query are displayed.
  8. Validate the displayed information.

Query test

Like all the elements of a WINDEV Mobile project, you can immediately test the query:
  1. Click Test query.
  2. The result is displayed in a window:
    Query result
    The result lists all products.
    In our case, we will only display the products that match the search criteria (the product name). To do so, we must use a query with parameters.
  3. Close the window.

Adding a selection condition

In our example, the user will be able to select a value for the product name. We must modify the query to use a query parameter as search criterion.

To define a query parameter, open the query description window. To do so, you can:
  • double-click the background of the query diagram.
  • open the context menu of the query and select "Query description".
To set a parameter based on the name of the product, we will define a condition on one of the items of the Product data file:
  1. Select the Product.Caption item in the list of query elements.
  2. Open the context menu and select "Selection condition .. New condition".
    Selection condition
  3. In the window that appears, we will specify that the selection condition corresponds to a parameter:
    Condition description
    • Select "contains".
    • Select "the parameter".
    • Keep the default parameter name: "ParamCaption".
  4. Validate the condition description window. The number "1" appears on the right of "Product.Caption", indicating that a selection condition has been defined.
    Condition in the query description window
  5. Validate the query description window.
  6. The query graph is modified to take into account the selection condition that was defined.
    Query graph
  7. Save the query by clicking Save element in the quick access buttons.

Test of the query with parameters

To test the query with parameters:
  1. Click Test query.
  2. A window appears and allows you to enter the different query parameters.
  3. Select the ParamCaption parameter. In the lower section of the window, enter "Polo".
    Entering the query parameters
  4. Validate the window. The query result corresponding to the specified parameters is displayed.
  5. Close the window.
We will create the interface of our window based on this query.
Creating the interface
We will create the search window using the window creation wizard. We are going to create a "Looper" window to list the products as we did in lesson 2. However, in this lesson, the window will not use data directly from a data file, but from the query. This will allow us to perform a search using the parameter we defined in the query.
The window creation wizard includes different preset windows. These windows have modern UIs for your applications.
Most of these windows can be generated from your data.

Creating the window

To create the search window:
  1. Click Create an element in the quick access buttons. The new element window appears: click "Window" then "Window".
  2. In the wizard, choose "Looper" and validate.
  3. The window creation wizard opens.
  4. Choose the platform to be used: "Generic Android phone". Proceed to the next step of the wizard.
  5. The wizard prompts you to choose the data source associated with the window. In our case, it is a query:
    • Click "Queries".
    • Select the query that was just created: "QRY_Products".
      Selecting the query
  6. Go to the next step.
  7. Select the looper style: "Image + Title + Text below". Go to the next step.
  8. The wizard automatically shows the query items that correspond to the generated looper. Keep the default options and go to the next step.
  9. Keep "Caption" as the default sort item. Go to the next step.
  10. The wizard shows multiple options for generating the Looper window. In our example, keep the default options. Go to the next step.
  11. Define a title and a name for the window. In our case:
    • Set "Products" as title.
    • Set "WIN_Advanced_LIST_Products" as name.
  12. Finish the wizard. The window is automatically created, displayed in the editor and saved.

Opening the product form

We will modify the "WIN_Advanced_LIST_Products" window to open the Product form we created in lesson 2.
  1. Right-click the Looper control and select "Code".
    Caution: make sure you select the Looper control and not one of the controls it contains.
  2. In the code editor, type the following WLanguage code in the initialization event:
    QRY_Products.ParamCaption = Null
    This line of code initializes the value of the parameter in the "QRY_Products" query used by the Looper control. By default, the value of this parameter is set to "Null" (which ignores the parameter). Therefore, all products will be displayed in the window.
  3. In the code editor, type the following WLanguage code in the "Select a row" event:
    Product.ReadSeek(ProductID, QRY_Products.ProductID)
    WIN_Product_form.OpenMobileWindow()
    Let's analyze this code:
    • The Looper control is based on the QRY_Products query. By selecting a product in the Looper control, you are actually selecting a record in the query.
    • The aim is to open the previously created window when a row is clicked . This window is based on the Product data file.
    • The record selected by the query must be in the "Product" data file in order to load the buffer of the selected data in memory. The operation is performed by <Data file>.ReadSeek.
    • Then, the form window named "WIN_Product_form" is opened by <Window>.OpenMobileWindow.
  4. Save changes by clicking Save element in the quick access buttons.
  5. Close the code window (click the "X" icon in the upper-right corner of the code editor).

Window test

We will test the window in the simulator:
  1. Click Test window in the quick access buttons.
    Window currently run
  2. Click one of the products: the form window opens.
  3. End the test.
Implementing the search functionality
We are going to implement the search functionality. To do so, we will:
  • Enable search in the Action Bar.
  • Create a search button in the Action Bar.
To enable search in the Action Bar:
  1. Open the "WIN_Advanced_LIST_Products" window in the editor.
  2. Open the Action Bar description window (double-click the Action Bar).
  3. In the "Details" tab, check "Enable search in the Action Bar".
To create a search button in the Action Bar:
  1. In the "General" tab of the Action Bar description window:
  2. Click number 2. A new UI allows you to enter an option in the toolbar.
  3. Click the "+" button to add an option. A new option is created at the top right. Change the option characteristics:
    • In the "Caption" area, type "Find".
    • In the "Preset image" area, expand the list and select "Find".
    • Confirm changes and close the description window.
  4. The code of this option will show the search area. To write this code:
    • Select the Action Bar.
    • Click the search button.
    • A drop-down menu with the "Find" option is displayed.
    • Right-click the option.
    • Select "Code" in the context menu that appears.
    • Write the following WLanguage code in the "Select a menu" event:
      ActionBarSearchVisible(True)
  5. Save changes by clicking Save element in the quick access buttons.
  6. Close the code window (click the "X" icon in the upper-right corner of the code editor).
  7. Select the Action Bar and open the associated code (press F2 or select "Code" in the context menu).
  8. In the code editor, type the following WLanguage code in the "Validation of the search" event:
    QRY_Products.ParamCaption = ACTB_ActionBar.SearchValue
    LOOP_QRY_Products.Display(taReExecuteQuery)
  9. Let's take a look at this WLanguage code:
    • The query parameter is initialized with the search value typed in the Action Bar.
    • Then, the Looper control is redisplayed by <Looper>.Display. The taReExecuteQuery constant re-executes the base query of the Looper control and takes the new parameter into account.
  10. Save changes by clicking Save element in the quick access buttons.
  11. Close the code window (click the "X" icon in the upper-right corner of the code editor).
  12. You can also insert a button to add a new product in this window. We have already done this in lesson 2, "Creating a new product". You just need to follow the same steps. Simply adapt the code of the "+" button.
  13. Test the window you have just created in the simulator (click Test window in the quick access buttons).
    • Click the search icon.
    • Type "Polo" in the search area.
    • Validate (Press Enter).
    • The list of products containing "Polo" is displayed.
      Search in the window
  14. Close the simulator.
Improving the window
We will implement the following features to improve the window:
  • Pull to refresh,
  • A sliding menu.
We will take a look at how to implement these features, which are widely used in mobile applications.

Pull to refresh

We will add a new feature to the window: the pull-to-refresh gesture.
This feature allows users to refresh a Table or Looper control with a swipe down gesture. For example, this feature can be used in an application in HFSQL Client/Server mode, where other users would update or add products. These changes could be displayed using the "Pull-to-refresh" gesture.
When the user "pulls" the control to refresh its content, a refresh bar automatically appears in the area that is uncovered:
  • The bar indicates that you must pull to refresh.
  • It then indicates that you must release to refresh.
  • It also indicates that the refresh operation is in progress. A progress bar is displayed during the refresh operation.
  • The control is refreshed.
To enable the "Pull-to-refresh" functionality:
  1. Open the "WIN_Advanced_LIST_Products" window in the editor.
  2. Select the Looper control and open the control description window.
  3. In the "Details" tab of the control description window, in the "Moves and gestures" area, check "Pull to refresh".
    Pull-to-refresh settings

    A specific internal window can be used to manage the "Pull-to-refresh" gesture. We will use the default window in this example.
    For more details, see Pull to refresh (Android/iOS).
  4. Validate the control description window.
The "Pull-to-refresh" configuration has added:
  • the refresh bar that will be displayed to the user during the operation.
  • the "Pull to refresh" event in the Looper control events. This event is automatically called when users perform a pull-to-refresh gesture. We will modify the WLanguage code of this event to manage how the control is refreshed.
To edit the WLanguage code in the "Pull to refresh" event:
  1. Select the Looper control and open the associated events (F2).
  2. In the code editor, write the following WLanguage code in the "Pull to refresh" event:
    LOOP_QRY_Products.Display(taReExecuteQuery)
  3. As previously seen for the search feature, <Looper>.Display redisplays the Looper control. The taReExecuteQuery constant re-executes the base query of the Looper control and takes into account the new records in the database.
  4. Save changes by clicking Save element in the quick access buttons.
  5. Close the code window (click the "X" icon in the upper-right corner of the code editor).
Test the window in the simulator (click Test window in the quick access buttons).
  1. Click and drag the top of the looper down.
  2. Release the mouse. The looper is refreshed.
    Pull-to-refresh at runtime
  3. Close the simulator.

Using a sliding menu

In several mobile applications, the menu does not correspond to a "static" window. Instead, it is a sliding window displayed via an option of the Action Bar and/or via a swipe gesture.
Sliding windows can appear from the right, left or bottom of the screen.
We will modify the "WIN_Advanced_LIST_Products" window to add a sliding menu. This menu will use the Multiline Zone control of the "WIN_Menu" window we created in lesson 2.

To create a sliding menu, we will:
  • Create an internal window. This internal window will contain the menu options.
  • Modify the "WIN_Advanced_LIST_Products" window to display the menu.
    An internal window is a simple window with no Action Bar and no toolbar. An internal window is used to easily include a set of controls in another window.
To create the internal window containing the menu:
  1. Click Create an element in the quick access buttons. The new element window appears: click "Window" then "Internal window".
  2. The internal window is automatically opened in the editor.
  3. The save window appears. Name the internal window: "IW_MLZ_Options".
    Saving the element
  4. Validate.
  5. Open the internal window description ("Description" in the context menu).
  6. In the "UI" tab, specify the dimensions of this internal window:
    • Width: any desired value. It must be wide enough to see the controls of the drop-down menu in their entirety. In theory, the sliding menu must be narrower than the window on which it is displayed (260 for example).
    • Height: This height must correspond to the height of the window on which the sliding menu is displayed. In our case, this height is set to 248.
      Dimensions of the internal window
  7. Specify a background color for the internal window in the "Style" tab. To avoid a transparent menu, "Background color of the internal window" must be set to "White".
  8. Validate.
  9. Save the window by clicking Save an element in the quick access buttons.
To add the menu options to the internal window:
  1. Open the "WIN_Menu" window previously created (double-click on it in the "Project explorer" pane, for example).
  2. Copy the controls from "WIN_Menu" to "IW_MLZ_Options":
    • Select all the elements in "WIN_Menu" (Ctrl + A).
    • Copy the elements (Ctrl + C).
    • Open the "IW_MLZ_Options" window (click on it in the open document tabs).
    • Paste the elements (Ctrl + V).
  3. Change the width of the Multiline Zone control using the sizing handles so that it fits in the internal window. When anchors are used, the size of all the controls in the Multiline Zone control also changes. You get the following window:
    Internal window in the editor
We will change the WLanguage code that opens the list of products. We will change this code since:
  • we work on the "WIN_Advanced_LIST_Products" window and no longer on "WIN_List_of_products".
  • the "WIN_Advanced_LIST_Products" window contains the sliding menu. The "List of products" menu option in the sliding menu should not open this window again.
We will change the WLanguage code used to select the Multiline Zone control.
  1. Select the Multiline Zone control.
  2. Open the associated WLanguage events (F2).
  3. Replace the line:
    CASE 1 // List of products
    WIN_List_of_products.OpenMobileWindow()
    with:
    CASE 1 // List of products
    WinSlidingVisible(swLeft, False)
    In this WLanguage code, WinSlidingVisible hides the sliding window that appears from the left. Therefore, the list of products is displayed.
  4. Save changes by clicking Save element in the quick access buttons.
  5. Close the code window (click the "X" icon in the upper-right corner of the code editor).
To associate the internal window with "WIN_Advanced_LIST_Products":
  1. Open the "WIN_Advanced_LIST_Products" window (click on it in the open document tabs).
  2. Open the description window.
  3. In the "Details" tab, in "Left sliding window", select "IW_MLZ_Options".
    The "Swipe" option automatically manages how the sliding window is displayed during a swipe gesture.
  4. Validate.
  5. Since the window is associated with an Action Bar, the editor prompts you to enable the option to open the sliding window.
    Enabling the option
  6. Accept.
We will test the sliding menu in the simulator:
  1. In the "Project explorer" pane, set "WIN_Advanced_LIST_Products" as the first window in the project ("WIN_Menu" is no longer useful).
    • Select "WIN_Advanced_LIST_Products" in the "Project explorer" pane.
    • Open the context menu.
    • Select "First project window". A specific icon (with a small 1) appears to the left of the window name, in the "Project explorer" pane.
  2. Click Test project in the quick access buttons.
  3. When clicking the Action Bar menu, the menu sliding window appears.
To sum up
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 - Develop an Android/iOS application", double-click "Android/iOS product management - Answers".
In this lesson, we discovered some of the most commonly used features in mobile applications:
  • The ability to perform a search in the Action Bar.
  • The implementation of the pull-to-refresh functionality.
  • The implementation of sliding windows.
In the next lesson, we will see a new feature specific to mobile applications: swipe gestures.
Previous LessonTable of contentsNext Lesson
Minimum version required
  • Version 2024
Comments
Click [Add] to post a comment

Last update: 12/15/2023

Send a report | Local help