ONLINE HELP
 WINDEVWEBDEV AND WINDEV MOBILE

New WINDEV 2024 feature!
Help / WINDEV Tutorial / Tutorial - External components
  • Reuse code via external components
  • Overview
  • Creating an external component
  • Opening the example project
  • Creating a project configuration
  • Component generation
  • Using the external component
  • Creating a project
  • Importing external components
  • Creating a window
  • Calling the component
  • Testing the component
  • Conclusion

Tutorial - External components

Reuse code via external components
We will cover the following topics:
  • What is an external component?
  • Practical example:
    • Creating an external component.
    • Using an external component.
Durée de la leçon 40 mn
Overview
WINDEV offers various methods for sharing code:
  1. Sets of procedures.
  2. Classes.
  3. External components.
  4. Internal components.
In this tutorial, we will focus on external components.
An external component is a building block that can be reused in an unlimited number of projects (and therefore executable files).
Principle of an external component
An external component allows you to have an identical process with a single source code to perform a given operation even if this process must be performed by several projects.
The projects that use an external component have access in the WINDEV editor to the name of objects, procedures or methods made visible by the component creator. Projects cannot read or change the source code. This ensures confidentiality and stability of the source code.
Creating an external component is very easy. In this tutorial, you will:
  • create an external component from an existing project.
  • use the previously created external component in a new project.
An external component can contain code, windows, data files, an analysis, etc.
Creating an external component

Opening the example project

We are going to create an external component from the "WD Full Application" project. This project is used to manage orders, products and customers.
The external component will be used to immediately find the customers of a given city in another application.
During the call to the external component, you will have the ability to:
  • Pass a city as parameter.
  • Retrieve a string containing the customer name and the total amount of their orders.
This tutorial uses the "WD Full Application" project. To open this example:
  1. Go to the WINDEV home page (Ctrl + <).
  2. On the home page, click "Tutorial", then in "Tutorial - WINDEV Application: Manage data", double-click "Full application - Answers".
For the component needs, the project contains:
  • a "QRY_OrdersByCity" query. This is a query with parameters used to identify the customers of a given city as well the total amount of their orders.
  • a set of procedures "SET_Component". This set of procedures contains:
    • the "GiveOrdersByCity" procedure that returns, for the city passed as parameter, a string containing the customer name and the total amount of the orders.
    • the "DataLocation" procedure that is used to localize the data required by the component.
  • an analysis to describe the data files that store the information.

Creating a project configuration

We will now create the external component from the "WD Full Application" project.
To do so, we will use an "External component" project configuration.
Key information: Project configurations allow you to adapt the same project to multiple "targets": 64-bit application, Linux application, component, etc.
You can choose the desired configuration and generate the corresponding elements at any time. For more details, see Project configuration.

To create an "External component" project configuration and associate it with the desired elements:
  1. On the "Project" tab, in the "Project configuration" group, expand "New configuration" and select "External component (WDK)".
  2. The project configuration creation wizard starts. WINDEV proposes to create a "Component" project configuration. Go to the next step.
  3. Give a name to your project configuration: "CompoOrdersByCity" for example. Go to the next step.
  4. Our component is intended for a Windows or Linux application. Keep the default options. Go to the next step.
  5. Select the elements that will be included in the project configuration. In this example, these elements will also be included in the component.
    • Click the "None" button.
    • Select the "QRY_OrdersByCity" and "SET_Component" elements.
      Project configuration
  6. Go to the next step and validate the configuration creation.
  7. The new configuration automatically becomes the current configuration.
    To identify and modify the current configuration, use the "Project explorer" pane.
    'Project explorer' pane
    The configuration in bold corresponds to the current configuration. To change the current configuration, double-click the name of the configuration you want to enable.

Component generation

We will generate the component:
  1. On the "Project" tab, in the "Generation" group, click "Generate".
  2. The component generation wizard starts. Proceed to the next step of the wizard.
  3. The wizard asks you to select the component elements that will be accessible from the client application. In our example, we will only use the "SET_Component" set of procedures:
    Generate a component - Accessible elements
  4. Go to the next step.
  5. You can enable the translation of the component. This feature may be useful if the component must be used in multilingual applications.
    Generate a component - Component translation options
    If the "Allow component translation" option is checked, the specified elements of the component can be translated from the application that uses the component.
    The elements will be translated via WDMSG, an independent module that extracts and reintegrates the project messages to be translated.

    For this example, keep the default option. Go to the next step.
  6. The wizard proposes to manage the different component versions. In our example, the component was just created.
    Keep the default options. Go to the next step.
  7. Enter the component information:
    • Owner,
    • Caption, Copyright, etc.
    Go to the next step.
  8. You have the ability to associate an image with your component. Go to the next step.
  9. Specify the main component overview. This overview will allow the user to understand the purpose of the component. Type for example:
    Generate a component - Component overview
  10. Go to the next step. The wizard will automatically generate the component documentation. This documentation can be based on the source code comments.
  11. Go to the next step. You have the ability to modify the generated documentation. Don't do anything. Go to the next step.
  12. You can create a help file associated with your component (CHM format). This help file will be provided along with the component. Users will be able to access it by pressing F1 from the component code.
    We will generate no help file. Go to the next step.
  13. The component will not be published in the SCM. Go to the next step.
  14. Give a physical name to the component.
    Component generation
  15. Validate ("Finish"). A message indicates that the component was generated. Click "End" to validate the message.
Well done, you've just created your first ready-to-use component!
Using the external component
Once created, your component can be used in any other WINDEV project. Let's see how to reuse the component.

Creating a project

To do so, we will create a new project and import the component into it.
  1. Close the current project: on the "Home" tab, in the "General" group, expand "Close" and select "Close project".
  2. Close the project and save changes if necessary.
  3. The WINDEV home page appears.
  4. Create a new project: click "Create a project" in the home page.
    • This project will be a Windows application.
    • Name this project "CompUse" and include no analysis.

Importing external components

  1. On the "Project" tab, in the "Project" group, expand "Import" and select "An External component ... From a file".
  2. In the directory of the "WD Full Application" project, select the "EXE\CompoOrdersByCity" subdirectory, then the "CompoOrdersByCity.wdi" file.
  3. Click "Open", the description of our component is displayed. This description contains:
    • On the "General" tab, the elements typed when creating the external component as well as its location.
      Component description
    • On the "Details" tab, the component description as well as the help that was automatically generated. This allows you to identify the usable component elements.
      The component description can be accessed at any time. Simply select the component in the "Project explorer" pane and select "Description" in the context menu. In this case, you can also define the component loading mode.
  4. Validate ("Close" button). The component is included in your project.

Creating a window

We will create a blank window to use the component.
  1. Create a blank window.
    • Enter "Customers by city" in the title.
    • The window name becomes "WIN_Customers_by_city".
    • Save.
  2. Open the WLanguage events associated with the window (select "Code" in the context menu).
  3. We are going to call the DataLocation function of the component in the "End of initialization" event. This function expects as parameter the path used to access the data files handled by the component. Enter the access path to the data in the "WD Full Application" example. For example:
    DataLocation(...// Specify the path of YOUR data
    "C:\My Projects\My examples\WD Full Application (Exercises)\Exe\Windows 32-bit executable")

    If the project uses another procedure named "DataLocation", the name of the component procedure must be prefixed with the name of the set of procedures used. The code becomes:
    SET_Component.DataLocation(...
  4. Close the code editor.
  5. Add the following controls to the window:
    • A text Edit control with "City" as caption and "EDT_City" as name.
    • A Table control named "TABLE_Result", populated programmatically and containing 2 columns:
      • a "Name" column of type Text.
      • a "Total sales" column of type Currency.
    • A Button control with "Search" as caption and "BTN_Search" as name.

Calling the component

You can now edit the WLanguage events associated with "BTN_Search". The search procedure in the component will be executed when the control is clicked on. This procedure:
  • expects the city name as parameter
  • returns a string in the following format:
    Name of customer 1 + TAB + Total sales 1 + CR +
    Name of customer 2 + TAB + Total sales 2 + ...
    So, the code of the "Click" event from "BTN_Search" should:
  • call the GiveOrdersByCity procedure of the component while passing the content of the EDT_City control as parameter.
  • process the returned string to add it to the Table control. Write the following WLanguage code:
    ResultList is string
    // Gets the list of customers and their orders
    // for the specified city
    ResultList = GiveOrdersByCity(EDT_City)
    // If the list is not empty
    IF ResultList <> "" THEN
    // Clears the Table control
    TABLE_Result.DeleteAll()
    // Iterates over the results
    FOR EACH STRING ACustomer OF ResultList SEPARATED BY CR
    // Adds this client to the Table control
    TABLE_Result.Add(ACustomer)
    END
    ELSE // If the list is empty
    InfoBuild("No customer found for %1", EDT_City)
    END
Close the code editor and save your window.

Testing the component

Test the window:
  1. Click Test window in the quick access buttons.
  2. In the edit control, enter "Paris" (keep uppercase and lowercase characters) and click "Search". The list of customers is displayed.
    Window test
And that's it! As you can see, it's very simple.
We have seen how to create a component and reuse it in the applications. You can also use setup procedures for you components, in order to distribute them separately from your applications, for example.
Conclusion
In this tutorial, we have seen how to create and use an external component.
The next step is to distribute this component. We won't go into details about the different setup modes of a component.
For more details on the setup of components, see Distributing an external component.
Table of contents
Minimum version required
  • Version 2024
Comments
Click [Add] to post a comment

Last update: 12/04/2023

Send a report | Local help