Working with events
Event handling code vs. initialization code
In building your Java program, you can think of your code as being divided into two categories: initialization code and event-handling code.
- Initialization code is the code that is executed when the UI components are created. You can think of this primarily as "start up" code for the components. This initialization code includes anything in the jbInit() method that all JBuilder-designed classes have. This is code that you had JBuilder generate for you by using the visual design tools. An example of this would be a button.setLabel() method that was generated because you set the label property of a button using the Inspector.
- Event-handling code is the code that you want to have executed when the user performs some action, such as pressing a button or using a menu item. This is code that you will write inside the body of event-handling methods. JBuilder will create the stub (empty) event-handling method for you when you double-click on an event in the Inspector for the component. By doing that, you are telling JBuilder that you want to execute some lines of code in your program when the user causes that event to occur on that component. You will place those lines of code in an event-handling method that JBuilder will create in your code.
Your entire program, then, consists of the initialization code, which says how things should look when they first appear, and the event-handling code, which says what should happen when the user performs operations in the UI.
There are some JBuilder components, most notably the dialogs, which normally appear only when event-handling code is executed. For example, although you may place a dialog into your class using the Component Palette and the Component Tree, it isn't part of the UI surface you are designing in the UI Designer. Instead, it is a separate piece of UI which appears transiently as a result of a user operation such as a menu choice or a button press. Therefore, some of the code associated with using the dialog, such as a call to its show() method, will have to be placed into the event-handling method. The nature of this code is completely custom, and so you will have to understand how to create and edit it.
Attaching event-handling code to a component event
Using the Events page of the Component Inspector, you can attach handlers to component events and delete existing event handlers.
To attach event-handling code to a component event,
- Select the component in the Component Tree or in the UI Designer.
- Select the Events tab to display the Events for that component.
- Click on an event, then double-click on its name or press Enter. JBuilder creates an event handler with a default name (which you can override), and switches to that event handler in the source code. JBuilder also inserts some additional code into your class, called an Adapter, to make the connection from the event to your event handling method. See Code that JBuilder generates to connect events below.
- Write the code inside the body of the event handler that specifies how you want the program to respond to that component event.
Note: To find out what methods and events a component supports, double-click that component in the Structure Pane to load the class into the AppBrowser, then click the Doc tab to view the documentation for that class.
Shortcut for creating an event handler
To quickly create an event handler for a component's default event,
- Select a component on the Component Palette and add it to your UI.
- Double-click the component in the UI Designer. An event stub is created and focus switches to that event handler in the source code.
- Add the necessary code to the event handler to complete it.
Note: The default event is defined by beanInfo, or as actionPerformed if none was specified.
Example: Display "Hello World" when a button is pressed
Here is a simple example of connecting code that displays "Hello world!" in response to a button being pushed. To generate this code yourself,
- Use the Application Wizard to start a new project. On page 2 of 2 of the wizard, check only the "Center frame on screen" option. Then click Finish.
- Select Frame1.java in the Navigation pane.
- Click on the Design tab at the bottom of the AppBrowser to display the UI Designer.
- Place an AWT TextField and Button in the UI Designer.
- Select the button in the UI Designer, then switch to the Events page in the Inspector and double-click on the actionPerformed event. You will be taken to a newly generated stub in the source code for the event-handling method.
- Enter the following code inside the braces of the event-handling method:
textField1.setText("Hello world!");
- Run the application to try it out. (Click the Run button
on the toolbar.)
When your application appears, click the button to see the text "Hello world!" appear in the text field.
In this example, the frame component listens for the actionPerformed event on the button. When that event occurs, the frame sets the text in the TextField.
Code JBuilder generates to connect events
When you double-click on an event in the Inspector, in addition to generating an event-handling method stub, JBuilder also automatically generates two other pieces of code in your class to hook up the event from the control to your event-handling method: an EventAdapter and an EventListener. You do not need to understand or edit this extra code to create events, but here is an explanation of what it does.
- JBuilder creates an EventAdapter class for that specific component/event connection and gives it a name which corresponds to that particular component and event. This is several lines of code (which you do not need to edit) that are added in a new class at the bottom of your file.
For example, in the "Hello world!" application above, JBuilder generates a type of EventAdapter called an ActionAdapter with the following code:
class Frame1_button1_actionAdapter implements java.awt.event.ActionListener {
Frame1 adaptee;
Frame1_button1_actionadapter(Frame1 adaptee) {
this.adaptee = adaptee;
}
public void actionPerformed(java.awt.event.ActionEvent e) {
adaptee.button1_actionPerformed(e);
}
}
- JBuilder also creates a line of code in the jbInit() method which connects the component's event source through the EventAdapter to your event-handling method by calling an addListener method of the component. The addListener method takes a parameter of the matching EventAdapter, and in this case the EventAdapter is constructed in place. Its constructor parameter is the this reference to your Frame that contains the event-handling method.
For example, the following is the line of code that performs this in the "Hello world!" application above:
button1.addActionListener(new Frame1_button1_ActionAdapter(this));
The adaptor class name is arbitrary and can be anything as long as the reference matches.
JBuilder creates the adapter class with the implementation for the only method in the ActionListener interface. The method that handles the selected event calls another method in the adaptee (Frame1) to perform the desired response.
Note: There will be more than one overridden method if more events from one set are handled, like mousePressed and mouseReleased.
Example event handler
Below is a specific example of a frequently used event handler. For additional examples of event handling code, see the tutorial Building a simple text editor at the end of the User's Guide.
Invoking a JBCL Filer dialog box from a menu item
When you design your own programs, you will typically need to add several lines of custom code in the event-handling methods. For example, you might want to extract the file name the user entered from a FileDialog or JBCL Filer dialog and use it to open or manipulate a file. You can often add the necessary code with the Interaction Wizard, or you can write it by hand.
To display Borland's Filer file open dialog box when the user chooses File|Open, you would do the following:
- If you do not already have a UI frame under development, use the Application or Frame Wizard to put one in your project.
- In the Navigation pane, select the frame file, then click the Design tab on the Content Pane to open the visual design tools.
- If you don't already have a MenuBar component, click it on the AWT tab of the Component Palette and drop one into the Component Tree or the UI Designer.
- Add a Filer component to the UI from the Dialogs tab of the Component Palette. You should see it appear in the "Others" section of the Component Tree.
- In the Inspector, select the frame property of the Filer component and set it to this. (This is necessary because all the dialog components must be attached to a parent frame before they can be shown.)
- In the Component Tree, double-click on the MenuBar component to open the Menu Designer.
- Create a File menu with an Open menu item. The example code below was generated with Open as menuItem1.
- Select the Open menu item in the Menu Designer, or on the Component Tree, then click the Events tab in the Inspector.
- Double-click the actionPerformed event in the Inspector to generate the following event-handling method stub in the source code:
void menuItem1_actionPerformed(java.awt.event.ActionEvent e) {
}
JBuilder will take you to a new existing event-handling method in the source code, or to an existing one if there already is one.
- Inside the braces of the actionPerformed event-handling method, type the following:
filer1.show();
- Now save your files then run your program and try File|Open.
Deleting event handlers
To delete an existing event handler,
- Select the component in the Component Tree or in the UI Designer.
- Select the Events tab in the Inspector, and click on the event you want to delete.
- Highlight the entire name of the event handler in the right hand column.
- Press the Delete key to remove the event handler name.
JBuilder automatically deletes the associated event-handling method and adapter class from the source code if the handler is empty.