PC SOFT

WINDEVWEBDEV AND WINDEV MOBILE
ONLINE HELP

Home | Sign in | English UK
New WINDEV 24 feature!
  • This lesson will teach you the following concepts
  • Overview
  • A window for sending emails
  • Creating the window
  • Creating the controls used to configure the sending
  • Creating the controls used to type the email characteristics
  • Sending the email
  • Improving the window
  • Closing the window
  • Formatting
  • Non-modal opening of window
Lesson 4.9. Sending an email
This lesson will teach you the following concepts
  • How to send an email from a WINDEV application.
  • How to include a supercontrol in a window.
  • How to define the tab order in a window.
  • How to open a non-modal window.

Estimated time: 20 mn
Previous LessonTable of contentsNext Lesson
Overview
Several WLanguage functions allow you to manage the incoming and outgoing emails. You also have the ability to access the email characteristics:
  • sender, recipients,
  • outgoing date, subject, message,
  • attachments...
WINDEV proposes several methods for managing emails:
  • Management via Lotus Notes, Outloook or MS Exchange:
    • The Lotus Notes or Outlook messaging software: these programs allow you to send and receive emails.
    • The "Simple Mail API" (also called SMAPI or Simple MAPI): this management mode of emails is used by most of the Microsoft applications, especially by Microsoft Exchange.
  • Management via the POP3, IMAP and SMTP protocols:
    • The POP3 protocol: this protocol for receiving emails is recognized by all service providers. It is used to communicate with the server directly, available at your ISP. This protocol is used to list the incoming messages and to read them.
    • The IMAP protocol: this protocol for receiving emails is used to leave the emails the server so that they can be consulted from different messaging clients or webmails.
    • The SMTP protocol: this protocol for sending emails is recognized by all service providers.
In this lesson, we are going to create a window allowing the user to send an email from the "WD Full Application" application. This window is as follows:
Window for sending an email
We are going to use the SMTP protocol. Indeed, this mode is commonly used all over the world.
See the online help for more details about the other methods.

Answer

To follow this lesson, you must have followed the lessons of this part until "Lesson 4.7. Printing a list of customers".
A full corrected application project is also available: in the WINDEV home page (Ctrl + <), click "Tutorial" and select "Full application (Answer)".

Example

See the "WD Mail" example (full example supplied with WINDEV) for more details. This example is accessible from the WINDEV home page (Ctrl + <).
A window for sending emails
This window will contain all controls allowing the user to type the different email elements. A "Send" button will group all processes used to send the email.

Creating the window

  • Create a new window:
    1. Open the "WD Full Application" project if necessary.
    2. Create a new blank window.
      • Click on the New among the quick access buttons.
      • The window for creating a new element is displayed: click "Window" then "Window".
      • The window creation wizard starts.
      • In the "Based on a template" tab, select "Use: WINTPL_Template" and validate the wizard.
    3. The window for saving an element is displayed. The title of this window being "Sending an email", its name is automatically proposed: "WIN_Sending_an_email". Validate the proposed information.

Creating the controls used to configure the sending

In a first time, we are going to create all controls for configuring the SMTP server used to send messages. Four edit controls are required:
  • SMTP server,
  • Port of SMTP server,
  • User name,
  • User password.
  • To create the edit control corresponding to the name of SMTP server:
    1. On the "Creation" pane, in the "Usual controls" group, click .
    2. The control shape appears under the mouse cursor.
    3. Click the top left corner of window: the edit control is automatically created.
    4. Select the control and press Enter on the keyboard. The caption becomes editable. Type "SMTP server" and validate. The control name automatically corresponds to EDT_SMTP_Server.
  • To create the edit control corresponding to the port:
    1. On the "Creation" pane, in the "Usual controls" group, expand "Edit".
    2. Select a preset Integer edit control.
    3. The control shape appears under the mouse cursor.
    4. Click below the "SMTP server" control: the edit control is automatically created.
    5. Select the control and press Enter on the keyboard. The caption becomes editable. Type "Port" and validate. The control name automatically corresponds to EDT_Port.
  • To create the edit control corresponding to the user name:
    1. On the "Creation" pane, in the "Usual controls" group, click .
    2. The control shape appears under the mouse cursor.
    3. Click below the "Port" control: the edit control is automatically created.
    4. Select the control and press Enter on the keyboard. The caption becomes editable. Type "User" and validate. The control name automatically corresponds to EDT_User.
  • To create the edit control corresponding to the user password:
    1. On the "Creation" pane, in the "Usual controls" group, expand "Edit".
    2. Select a preset "Password" edit control.
    3. The control shape appears under the mouse cursor.
    4. Click below the "User" control: the edit control is automatically created.

      Tip

      The "Password" edit control appears in the editor with a bullet and an eye.
      At run time, when the user types his password, the characters will be replaced by bullets. A click on the eye will allow the user to see his password in clear: this allows the user to check his password.
      This feature can be disabled by programming if necessary. See the online help for more details.
  • Align the created controls:
    1. Select the four controls.
    2. On the "Alignment" pane, in the "Inside and outside" group, click "Justify (Ins. and Out.)".
    3. Save the window ( or Ctrl + S).

Creating the controls used to type the email characteristics

To write an email, the user must have:
  • A control used to type the sender address.
  • A control used to type or select the recipient address.
  • A control used to type the email subject.
  • A control used to type the email text. The user must have the ability to format the email text.
  • A control used to add attachments.
We are now going to create these controls in our window.
  • To create the edit control corresponding to the sender address:
    1. On the "Creation" pane, in the "Usual controls" group, expand "Edit".
    2. Select the preset "Email" edit control.
    3. The control shape appears under the mouse cursor.
    4. Click below the "Password" control: the edit control is automatically created.
    5. Select the control and press Enter on the keyboard. The caption becomes editable. Type "Sender" and validate.
  • The control used to type the recipient address must list the addresses of the customers found in the database but it must also allow the user to type another address. To do so, we will be using an "Editable combo box" control linked to the Customer data file.
    1. On the "Creation" pane, in the "Usual controls" group, click "Combo Box".
    2. The control shape appears under the mouse cursor.
    3. Click below the "Sender" control: the wizard for creating the Combo Box control is automatically started.
    4. Select "Display the data found in a file or in an existing query". Go to the next step.
    5. Select the Customer data file. Go to the next step.
    6. The email addresses of customers must be displayed in the control:
      • Uncheck the "CustomerID" item.
      • Check the "Email" item.
      Go to the next step.
    7. The sort item is the "Email" item. Go to the next step.
    8. The return value is the "Email" item. Go to the next step.
    9. Keep the default options. Go to the next step.
    10. In the "Additional parameters" screen, check "Allow the input". Indeed, the user must have the ability to type a new email address. Go to the next step.
    11. Modify the name and caption of Combo Box control:
      • The control name is "COMBO_Recipient".
      • The control caption becomes "Recipient".
    12. Validate the wizard. The control is automatically created in the window.
  • To create the edit control corresponding to the email subject:
    1. On the "Creation" pane, in the "Usual controls" group, click .
    2. The control shape appears under the mouse cursor.
    3. Click below the "Recipient" control: the edit control is automatically created.
    4. Select the control and press Enter on the keyboard. The caption becomes editable. Type "Subject" and validate.
  • For the message body, we will be using an HTML edit control: the user will have the ability to format the email text via a specific toolbar.
    1. On the "Creation" pane, in the "Usual controls" group, expand "Edit".
    2. Select a preset "HTML text" edit control.
    3. The control shape appears under the mouse cursor.
    4. Click below the "Subject" control: the edit control is automatically created.
    5. Enlarge the control in order for several lines to be visible.
    6. Display the description window of control (double-click the control).
      • On the "General" tab, modify the mode for displaying the formatting toolbar. This toolbar must always be visible.
      • Validate the description window of control.
    7. Reposition the control if necessary in order for the toolbar to be displayed properly.
  • We are going to create a file picker allowing the user to add an attachment. Instead of creating it from scratch, we will be using a preset edit control of file type. Via the popup menu of control ("Browse" option), the user will be able to select the file to attach.
    1. On the "Creation" pane, in the "Usual controls" group, expand "Edit". The list of preset controls proposed by default is displayed.
    2. Select the "File" control and perform a Drag and Drop toward the "WIN_Sending_an_email" window: drop the control below the "HTML text" control. The file picker is immediately created.
  • Align the different controls found in the window.
We are now going to create the button used to send the emails.

Sending the email

  • To create the send button:
    1. On the "Creation" pane, in the "Usual controls" group, click .
    2. Click the location where the button will be created (at the bottom of the window for example).
    3. Select the button and modify its caption (press the Enter key for example). The new caption is "Send".
    4. Edit the code of this button: select "Code" from the popup menu of button (right mouse click).
    5. Type the following codes in the "Click" event:
      • the code for opening the connection and for starting the SMTP session:
        MySession is emailSMTPSession
        MySession..Name = EDT_User
        MySession..Password = EDT_Password
        MySession..ServerAddress = EDT_SMTP_Server
        MySession..Port = EDT_Port
        // Starts the SMTP session
        IF not EmailStartSession(MySession) THEN
        Error("Unable to connect to the SMTP server.", ...
        ErrorInfo())
        RETURN
        END
        This code is using an advanced emailSMTPSession variable. The different properties of this variable are used to define the characteristics of SMTP session. Then, EmailStartSession associated with this variable is used to start the session.
      • the code for preparing the email:
        MyMessage is Email

        MyMessage..Sender = EDT_Sender
        MyMessage..Subject = EDT_Subject
        MyMessage..HTML = EDT_HTML_Text
        MyMessage..Message = HTMLToText(EDT_HTML_Text)

        // Adds a recipient
        Add(MyMessage..Recipient,...
        COMBO_Recipient..DisplayedValue)

        // Adds the attachment if necessary
        IF EDT_File <> "" THEN
        EmailLoadAttachment(MyMessage, EDT_File)
        END
        This code is using an Email variable. The different properties of this variable are used to define the characteristics of email to send. This code associates the content of different window controls to the properties of Email variable.
      • the code for sending the email:
        // Send the email
        IF EmailSendMessage(MySession, MyMessage) = False THEN
        Error("Message not sent.", ErrorInfo())
        ELSE
        // Message sent
        ToastDisplay("Message sent", toastShort, ...
        vaMiddle, haCenter)
        END
        The email is sent by EmailSendMessage. All you have to do is pass in parameter the variable containing the characteristics of SMTP session and the variable containing the characteristics of email to send.
        If the email is sent, a Toast message is displayed, indicating that the email was sent. A Toast message corresponds to a furtive message.
      • the code for closing the SMTP session:
        // Closes the SMTP session
        EmailCloseSession(MySession)
        This code closes the session with EmailCloseSession.
  • Save the window and its code ( or Ctrl + S).
Improving the window
We are going to perform improvements in our window:
  • Add a closing button
  • Format the window via the management of anchors and the tab order.
  • Start the window from the "WIN_Menu" window.

Closing the window

  • To add a button used to close the window:
    1. On the "Creation" pane, in the "Usual controls" group, expand "Button": the list of preset buttons is displayed.
    2. Click the "Close" button.
    3. Click the position where the button will be created in the window (bottom right of Send button for example).

Formatting

  • To define the anchors:
    • Select the "Sender", "Recipient" and "Subject" controls: these controls must be anchored in width.
    • Select the "HTML text" control: this control must be anchored in width and in height.
    • Select the buttons: these controls must be anchored to the right and at the bottom.
    • Select the control for file selection: this control must be anchored in width and at the bottom.
  • To define the tab order:

    Note

    The tab order of controls is the order in which the user can type the values in the different window controls. Going from a control to another one is performed when pressing the Tab key at run time. The default tab order corresponds to the creation order of controls. It can be modified:
    • by specifying an automatic tab order: the first control in edit will be the control found in the top left corner of window, the second one will be the one found immediately to its right or below...
    • by specifying a tab order by selection.
    1. Display the tab order via the F5 key.
    2. Define the automatic tab order: on the "Window" pane, in the "Order" group, expand "Navigation" and select "Define automatically".
    3. The numbers are modified and they now appear in order.
    4. Press the F5 key again to hide the numbers.
    5. Save the window ( or Ctrl + S).

Non-modal opening of window

The window for email management will be opened from the "WIN_Menu" window. Its opening mode is specific because this window must not prevent the information displayed in the "WIN_Menu" window from being viewed.
  • To open the "WIN_Sending_an_email" window from the "WIN_MENU" window:
    1. Display the "WIN_Menu" window in the editor (double-click its name in the "Explorer" pane for example).
    2. In the editor, expand the "Menu" option and select "Exit".
    3. Display the popup menu of "Exit" option (right mouse click) and select "Add before".
    4. Type the option caption ("Send an email") and validate.
    5. Select the "Exit" option again.
    6. Display the popup menu of "Exit" option (right mouse click) and select "Insert a separator".
    7. Display the popup menu of "Send an email" option (right mouse click) and select "Code".
    8. Write the following code:
      // Opens the window for sending emails
      OpenChild(WIN_Send_an_email)
      In this code, OpenChild is used to open the window in "non-modal" mode: the user will be able to write an email and to see the information displayed in the main window at the same time.
  • Save the window and its code ( or Ctrl + S).
  • Run the project test ( among the quick access buttons) and open the window for sending emails via "Menu .. Send an email".
Previous LessonTable of contentsNext Lesson
Minimum version required
  • Version 24
Comments
Click [Add] to post a comment