Creating Sub-windows
Handling user events

There are two important differences between main windows and sub-windows:

• When you close a main window, the application closes; when you close a sub-window, only it closes.
• Also unlike main windows, sub-windows do not include the Droplet icon and its menu of Droplets-related items like "Send to a Friend".

In addition, when you are using a Droplets Dialog instead of a Frame (which is not required for sub-windows), your sub-windows cannot be maximized and minimized.

In order to illustrate the concept of sub-windows — and to explain how you write sub-windows into your Droplet's application logic — we're going to alter the Hello World demo that we built in the last tutorial. As you can see from the image below, we're deleting the main window's two labels and leaving only a button in the center of the window that says "Press This Button Now!":

When the end-user clicks the button, a sub-window appears. This sub-window's only component is a label announcing the purpose of our demo:

We're not going to review the entire code for the application, since we've covered most of this in Hello World. If you'd like to see the complete code for the window, you can find it within your Droplets installation at java/examples/Subwindows. There are two major alterations that have been made to Hello World in order to add our sub-window:

• We've turned our Hello World label into a button and created a ClickListener to handle button clicks;
• We've defined a sub-window object.

Creating the Subwindow

Handling button clicks (and positioning sub-windows)

Our sub-window application must handle a user-initiated event, the click of the main window's button. All Droplets components have some variety of ActionListener interface, specific to their attributes, that listens for events; since a button is clicked, its listener is a ClickListener.

Important Note: Remember to import the com.droplets.api.event.* package for Droplets that require event handling.

There are five items that we'll need from the Droplets API in order to handle any click event:

• A ClickEvent that is fired whenever our button is clicked.
This is automatically created by the Droplets Platform whenever a button is clicked, so we simply have to include it as an argument to the ClickListener.

• An implementation of the ClickListener interface
This is an object that will listen for any ClickEvents.

• A handleClick() method within the ClickListener
This will define the action to be taken whenever our button is clicked. The name is required, not optional.

• A call to AddClickListener()
This is a method of Button (and other clickable components) that associates our ClickListener with the button.

Here is the code for our ClickListener:

Note first off that in our constructor we pass the ClickListener the current application as an argument. You'll see how to do that when we come to the main window.

After defining a constructor and indicating that it takes an Application object as its argument, the actual handling of the click is performed by the handleClick() method. handleClick(ClickEvent e) is a method of the interface ClickListener which we are implementing, and is called by the framework when the button is clicked.

In response to a button click, our application pops up a sub-window. While that sub-window is defined within its own class, we do some formatting work here, including the creation of a SubWindow instance; the locating of the sub-window on the user's screen; the insertion of text into the Title Bar; and the placement of the new sub-window into the application (which causes it to appear on the client side).

Of these steps, the least immediately obvious is locate(), which is a method which Frame inherits from Window. It takes four arguments; the first two define its location on the user's screen, the second two its absolute size in pixels:

The first two arguments, which define the sub-window's screen position, are both set at -1; this centers the sub-window within the end-user's screen. If you don't want the sub-window centered in the user's window, you'll instead have to indicate the exact location in pixels, which is a bit more complicated. In order to do this you'll have to:

• Determine the size of the end-user's computer screen
• Assign the sub-window a position in pixels relative to the size of the screen.

The first step is possible because the Droplets Client always passes this information to the Droplets Server on application start-up as a Variable Value, information about the end-user's computer environment that might be useful for your applications.

You can access these Variable Values by calling the Application object's GetVariableValue() method and specifying the height and width of the computer screen. This method has built-in variables called ScreenWidth and ScreenHeight that you can reference to get the exact size in pixels of the end-user's screen. With our demo, it might look something like this:

Once you've created int variables to hold the width and height of the user's screen, you can then position the window relative to the screen size. For example, if you wanted to place the sub-window in the top left corner of the screen, the first two arguments to locate would be (0, 0); if you wanted to place it in the bottom right corner it would be ((screenWidth - 300), (screenHeight - 500), 300, 500), where 300 and 500 are the actual pixel size of the sub-window. Something in between these two extremes will require a bit of experimentation.

The ClickListener is associated with the main window's button in the addAllComponents() method of the main window:

The code for associating the ClickListener with its component is invariable (except of course for the two variable names) and can be used pretty much as-is for all applications that involve a listener:

ClickListener is associated with its main window by creating an instance of it within the window's addAllComponents(). Its necessary argument is always provided with a call to the window's getApplication() method. We then call the component's addClickListener() method with the new ClickListener object as an argument.

Feel free to check out the complete code for this demo at Java/Examples/Subwindows within your Droplets installation directory, or move on within the SDK documentation by clicking the Droplet icon at the bottom of this page.

  Return to Droplets SDK documentation home.