Lesson 7: Work with EGL source code

In this lesson you will bind a simple function, written in EGL source code, to the Submit button.
The EGL Rich UI Handler is entirely composed of EGL code. The EGL editor provides shortcuts that you can use to create code in the program, but you can easily write the equivalent code yourself. In this lesson, you will learn how to create a text field widget and write a function in the Source mode of the editor. Then you will bind the function to the Submit button to test it.

Create a text field in source code

The EGL Rich UI widgets that you see on a Web page are specific examples of general widget types.Those types are found in the com.ibm.egl.rui project that was automatically placed in your workspace when you first started EGL. To create a new example of one of these types, write a statement with the following syntax:
msgField com.ibm.egl.rui.widgets.TextField;

msgField is the name of the field that you are creating, and com.ibm.egl.rui.widgets.TextField specifies the model that the new field is based on. When you drag a TextField widget from the palette and assign a name to it, EGL writes code that is similar to this declaration.

You can shorten a type name by using an EGL import statement. The import statement tells EGL to look in the specified location to resolve unqualified references. For example, you can add the following statement to the beginning of the source file, after the package statement, but before the handler declaration:
import com.ibm.egl.rui.widgets.*;
With this statement in place, you can use the types without qualifying them:
uidField TextField{};

If you have the import statement in your code, EGL also omits the qualifiers for the widget declarations that it generates.

  1. Open logon2.egl in the editor, if it is not already open.
  2. Click Source. Note the various sections of the code:
    • The first line identifies the package that contains the program.
    • The first line of the handler declaration specifies a Rich UI Handler and lists the properties of the handler, in braces.
    • The next lines list the variables for the handler and their properties, in braces.
    • After the list of variables there is a list of function declarations. Unlike a main EGL program, a handler does not require a main() function.
  3. On a new line at the end of the list of variables, declare a new variable:
    msgField TextField{ color = "red" };
    The following screen shot shows that section of code:
    Lines of EGL code from the Source mode of the editor

    Although you have created the variable, you have not placed it on the screen. To do that, you must list the variable as a child of an existing container.

  4. Locate the ui declaration in the source code and find the children property. Add msgField to the end of the list, after submitButton. Be sure to separate msgField from submitButton with a comma. The following screen shot shows that section of code:
    Lines of EGL code from the Source mode of the editor
  5. Save the file.
  6. Switch to Preview mode. You can now see the new text field.
    The new text field is displayed to the right of the Submit button

Bind a simple function to the Submit button

Functions that bind to elements of the interface respond to events that take place in that interface. EGL uses standard terms for these events, such as "onClick" or "onKeyDown", all of which are specific examples of the EGL Event type. When you create a function to handle one of these events, you must include the event as a parameter for the function:
function logon(e Event in)

In this example, e is an arbitrary name for an Event type variable, and in indicates that the function reads the parameter for input only.

The onClick property is actually an array; you can use it to call multiple functions, in order. You will only call one function, but you must still use the proper syntax for an array:
onClick ::= functionName
This adds functionName() to the end of the list of arrays to call. In a Rich UI Handler, you can add to this array, but you cannot replace it. The following code causes EGL to throw an exception:
onClick = [functionName]   // does not work in RUIHandler

In this task, you will use the EGL editor to automatically create a stub function, which contains no executable code, and then bind that function to a widget.

The following demonstration shows the steps in this task:

To bind a function to a widget:

  1. With the logon2.egl file still open in the Rich UI text editor, switch to Design mode.
  2. Click the Submit button to select it. The button is surrounded by a dotted line.
  3. In the Properties view, click the Events tab, which is next to the Properties tab. Locate the onClick event in the list. Double-click the corresponding table cell in the Function column to release the dropdown list. The list shows all of the available event-handling functions. In this case the list is blank because you have not created any functions to handle events.
    A menu for the Function column shows the logon function
  4. Locate the plus sign in the far right column for the onClick event. You might have to scroll to the right to see it. Click the plus sign to add a stub function.
    The plus sign is in the far right column
  5. In the New Event Handler window, type the following name for the new function:
    logon
    A menu for the Function column shows the logon function
  6. Click OK. The editor switches automatically to Source mode and positions the cursor in the stub logon() function.
  7. Type the following text to complete the function:
    msgField.text = "Button clicked";
    Note that the editor automatically added the onClick property to submitButton:
    submitButton Button{ text = "Submit", onClick ::= logon };

    On the Events page of the Properties view, logon is now available in the drop-down function list.

  8. Save the file.
  9. Switch to Preview mode. Type a name and password; note that the password is displayed as bullet characters. Click Submit. The new text field displays the notification message:
    The words "Button clicked" are displayed next to the Submit button

Lesson checkpoint

You saw how changes in the editor are reflected in the EGL code, and you bound a simple function to the Submit button.
You learned how to perform the following tasks:
  • How to create a widget in the EGL code
  • How to write a function to handle an event
  • How to bind the function to a widget

Feedback