[Contents] [Previous] [Next] [Last]
To give the user more choices, display plug-in results, or allow text editing, you can include a dialog box in a Composer Plug-in.
This chapter describes using the Java Abstract Windowing Toolkit (AWT) or Netscape Internet Foundation Classes (IFC) to add dialog boxes, and, by extension, other user interface elements, to your plug-ins. Go through the tutorial in this chapter to create a plug-in that just displays a dialog box.
Composer Plug-ins of the menu option type can have either a dialog box or a direct interface:
To create a dialog box, you can use either AWT or IFC, which is part of Communicator 4.0. This chapter describes creating dialog boxes, but you can use the same approach to create any of the other user interface elements available through AWT and IFC. Go through the tutorial in this chapter, DialogOnly, to create a plug-in that just displays a dialog box with AWT.
Examples in this chapter come from two of the samples included in your Composer Plug-in Kit, EditRaw and IFCTest. These samples are identical, except that one uses AWT and the other uses IFC to create a dialog box. You can compare the two plug-ins to see the differences between the two tool kits.
[Top]
It is important to remember some basic features of Composer Plug-in dialog boxes as you design plug-ins:
Composer Plug-in dialog boxes are modal; that is, they do not allow access to the Navigator Composer window while they are displayed. The user must click OK or Cancel to dismiss the dialog box before access to the rest of the user interface is restored. Make sure that you code your plug-ins to support this mode of operation.
The Composer Plug-in dialog box user interface has three buttons: OK, Cancel, and Apply.
Make sure that you support this three-button dialog UI in your plug-ins. The user clicks OK or Cancel to dismiss the dialog box. The user can set up a change in the dialog box, such as a color change, and click Apply to view the results. If satisfied, the user clicks OK to apply the change to the document and close the dialog box. If not satisfied, the user can continue to use Apply to test changes.
As is standard Java behavior, each Composer Plug-in window runs in its own thread.
Note:
If the user clicks Apply first, and later clicks Cancel,
the plug-in framework automatically restores the original document state.
[Top]
To implement a dialog box, you can use either the Java Abstract Windowing Toolkit (AWT) package, which is part of standard Java, or the Netscape Internet Foundation Classes (IFC), part of Communicator 4.0. IFC extends AWT with additional features for building and customizing the user interface.
For more information about AWT, see your Java documentation. For more information about IFC, see your IFC documentation.
[Top]
This sample uses the Abstract Windowing ToolKit (AWT) to bring up a dialog box for user interaction. This class creates a dialog box with button and panel AWT UI elements. It extends Frame, which is a simple Java window. This chapter includes a tutorial, DialogOnly, that focuses on creating a dialog box with AWT. The sample code below demonstrates these steps in more detail, with examples from EditRaw, a sample included in the Composer Plug-in Kit.
The code for an AWT dialog box must provide these services:
 |
Set up the perform method to handle the dialog box. |
|
Define the AWT dialog box class. The class must: |
|
Handle the window close event. |
|
Handle the actions of the dialog box, including AWT exception handling. |
|
Copy the text from the document to the dialog box. |
|
Move text into the dialog box and copy it back into the document. |
|
Thread handling: Signal the termination of the dialog box thread. |
|
Declare and initialize the variables used by the plug-in class. You can place these definitions anywhere in the plug-in code. For convenience, EditRaw collects them at the end. |
Note:
It is recommended that you use AWT 1.0 features for developing
Composer Plug-ins because some JDK 1.1 methods (especially features of
AWT 1.1) are not supported by Communicator 4.0. Using the older AWT 1.0
features may result in JDK 1.1 deprecated interface warnings when you compile
some of the samples; you can safely ignore these warnings.
[Top] [ Displaying a Dialog Box with AWT]
This code demonstrates the steps above in more detail, with examples from EditRaw, a sample included in the Composer Plug-in Kit. The EditRaw sample, included in your Composer Plug-in Kit, creates a dialog box with button and panel AWT UI elements and calls other methods to carry out dialog box actions.
To see the complete text of this sample, see the source code in EditRaw.java in the source directory of the Composer Plug-in Kit.
Note on DialogOnly
Tutorial:
You can follow along and write a very basic plug-in that
you can compile and build, and run in the Testbed. This plug-in performs
one simple operation: it creates an empty dialog box. For this reason,
it does not illustrate every topic that this chapter describes. To see
this tutorial, click 
.
To return to this chapter, click 
in the tutorial file.
Set up the perform method to
handle the dialog box. Among other things, this perform method
creates a dialog box and runs the UI element code in the AWT section.
public boolean perform(Document document) throws IOException{
MyDialog dialog = new MyDialog("Edit Raw HTML", document);
Initialize the dialog box and set
its size.
dialog.reshape(50,50,300,300);
dialog.show();
Make sure the dialog box is on top and
gets focus.
dialog.requestFocus();
Arrange for the dialog box to wait for
the user to exit.
boolean result = dialog.waitForExit();
Dispose of the dialog box. Clean
up the native OS window associated with the dialog box.
dialog.dispose();
Write the changed text to the document. This perform method also contains the result code for making the change to the document. For more information on using these methods, see "Writing HTML to the Document."
if ( result ) {
document.setText(dialog.getText());
}
return result;
}
}
Define the AWT dialog box class for interacting
with the user. The dialog box class extends Frame, so that
it can have its own menu bar, and includes standard Java AWT code that
sets the buttons as instance variables.
class MyDialog extends Frame {
public MyDialog(String title, Document document) {
super(title);
Save the document in an instance variable.
this.document = document;
Set the buttons as instance variables,
using standard Java AWT code.
Panel buttons = new Panel();
buttons.add("East", ok = new Button("OK"));
buttons.add("Center", apply = new Button("Apply"));
buttons.add("West", cancel = new Button("Cancel"));
add("Center", text = new TextArea());
add("South", buttons);
Move text from the document to the dialog box. The copyTextFromDocument method is defined in this sample plug-in.
copyTextFromDocument();
}
Handle the window close event. This
method makes the dialog box invisible and signals that the dialog box is
closing.
public boolean handleEvent(Event event) {
if (event.id == Event.WINDOW_DESTROY) {
hide();
signalExit();
return true;
} else {
return super.handleEvent(event);
}
}
Handle the actions of the dialog box,
including exception handling. The action method includes standard
AWT code that is called whenever the user clicks a button. If action
succeeds, the success line executes. Composer Plug-ins use standard
Java exception handling.
public boolean action(Event evt, Object what){
if ( evt.target == ok || evt.target == cancel) {
success = evt.target == ok;
hide();
signalExit();
return true;
}
else if ( evt.target == apply ) {
try {
document.setText(getText());
} catch(IOException e){
System.err.println("Error writing document:");
e.printStackTrace();
}
return true;
}
return false;
}
Copy the text from the document to the dialog box. The copyTextFromDocument method moves text from the document to the dialog box. It uses a Reader object to read the document text, and a loop to move the text.
protected void copyTextFromDocument() {
try {
setText(document.getText());
} catch(IOException e){
System.err.println("Error reading document:");
e.printStackTrace();
}
}
Move text into the dialog box and copy it back into the document. Use get and set functions to handle dialog box text. You can change these methods without changing the functionality of the program, thus taking advantage of the object-oriented feature of encapsulation. The variable bExited can be Cancel or OK.
Move text into the dialog box from the document.
public void setText(String text){
this.text.setText(text);
}
Copy text out of the dialog box into the document.
public String getText(){
return this.text.getText();
}
Signal the termination of the dialog box thread.
Called from the main plug-in thread: This method waits
for the dialog thread to call signalExit(), and then it returns.
synchronized public boolean waitForExit() {
while ( ! bExited ) {
try {
wait();
} catch ( InterruptedException e){
}
}
return success;
}
Called from the dialog thread:
Signal the plug-in thread that the dialog is finished.
synchronized public void signalExit() {
bExited = true;
notifyAll();
Declare and initialize the variables
used by the plug-in class. You can place these definitions anywhere
in the plug-in code. For convenience, EditRaw collects them at
the end.
private Button ok;
private Button apply;
private Button cancel;
private TextArea text;
private boolean bExited = false;
private boolean success = false;
private Document document;
[Top] [ Displaying a Dialog Box with AWT]
The IFCTest sample plug-in, included in the Composer Plug-in Kit, uses the Internet Foundation Classes (IFC), part of Communicator 4.0, to display a dialog box for user interaction. The IFC sits on top of AWT and provides more capabilities. The sample below shows how to use the IFC from within a Composer Plug-in, with examples from IFCTest. In addition, it demonstrates using the Java resource bundle functionality, which allows you to collect your plug-in's text strings into one easily localizable file.
The code for an IFC dialog box must provide these services:
Note:
As of Netscape Navigator 4.0.1, the File Load and Save menu
items are not implemented on some platforms.
[Top] [ Displaying a Dialog Box with IFC]
This code demonstrates the preceding steps in more detail, with examples from IFCTest, a sample included in the Composer Plug-in Kit. Among the tasks involved in using IFC to create a dialog box are creating an IFC application to implement the plug-in, writing the method that provides the action of the dialog box, and copying the text back to the document from the dialog box.
To see the complete text of this sample, see the source code in IFCTest.java and IFCTestBundle.java in the source directory of the Composer Plug-in Kit.
Set up the perform method to handle the dialog box. Among other things, this perform method creates an IFCTest application that runs the UI element code in the IFC section, followed by a conditional result section.
public boolean perform(Document document) throws IOException {
IFCTestApp app = new IFCTestApp(document);
app.run();
boolean result = app.result();
if ( result ) {
document.setText(app.getText());
}
return result;
}
Define the resource bundle; this plug-in uses the resource bundle represented by the IFCTestBundle sample.
static public ResourceBundle bundle() {
if ( bundle_ == null ){
bundle_ = ResourceBundle.getBundle(
"netscape.test.plugin.composer.IFCTestBundle");
}
return bundle_;
}
private static ResourceBundle bundle_;
}
Define the IFC application that implements the plug-in.
class IFCTestApp extends Application implements Target,
WindowOwner
{
public IFCTestApp(Document document){
Save the document in an instance variable.
this.document = document;
}
public boolean result() {
return this.bresult;
}
public void init() {
try {
super.init();
init2();
}
catch(Throwable t){
t.printStackTrace();
}
}
private void init2(){
mainWindow = new ExternalWindow();
mainWindow.setOwner(this);
mainWindow.setTitle(IFCTest.bundle().getString("title"));
setMainRootView(mainWindow.rootView());
mainWindow.sizeTo(620, 450);
mainWindow.setResizable(false);
RootView v = mainWindow.rootView();
v.setColor(Color.lightGray);
Copy the text from the document to the dialog box. Note the call to the copyTextFromDocument() method, which is defined below.
textView_ = new TextView();
textView_.setBounds(0,0,600-5,1000);
copyTextFromDocument();
Define IFC dialog box features.
ScrollGroup scrollGroup = new ScrollGroup(0,0,600,385);
scrollGroup.scrollView().setContentView(textView_);
scrollGroup.setHorizScrollBarDisplay(ScrollGroup.NEVER_DISPLAY);
scrollGroup.setVertScrollBarDisplay(ScrollGroup.AS_NEEDED_DISPLAY);
scrollGroup.setBackgroundColor(Color.white);
v.addSubview(scrollGroup);
int buttonY = 400;
Button ok = Button.createPushButton(25, buttonY, 150, 20);
ok.setTitle(IFCTest.bundle().getString("ok"));
ok.setCommand("ok");
ok.setTarget(this);
v.addSubview(ok);
Button apply = Button.createPushButton(185, buttonY, 150, 20);
apply.setTitle(IFCTest.bundle().getString("apply"));
apply.setCommand("apply");
apply.setTarget(this);
v.addSubview(apply);
Button cancel = Button.createPushButton(345, buttonY, 150, 20);
cancel.setTitle(IFCTest.bundle().getString("cancel"));
cancel.setCommand("cancel");
cancel.setTarget(this);
v.addSubview(cancel);
mainWindow.show();
}
Define the performCommand method. This method handles user choices of OK, Apply, and Cancel.
public void performCommand(String command, Object arg) {
try {
if (command.equals("ok")){
bresult = true;
stopRunning();
}
else if (command.equals("apply")){
try {
document.setText(getText());
} catch(IOException e){
System.err.println("Error writing document:");
e.printStackTrace();
}
}
else if (command.equals("cancel")){
bresult = false;
stopRunning();
}
else {
System.err.println("Unknown command " + command);
}
}
catch (Throwable t){
System.err.println("Caught exception while performing command:");
t.printStackTrace();
}
}
Copy the text from the document to the dialog box. Use the copyTextFromDocument method for this purpose.
protected void copyTextFromDocument() {
try {
setText(document.getText());
} catch(IOException e){
System.err.println("Error reading document:");
e.printStackTrace();
}
}
Call get and set functions to handle dialog box text. You can change these methods without changing the functionality of the program, thus taking advantage of encapsulation.
Copy text into the dialog box.
public void setText(String text){
textView_.setString(text);
}
Copy text out of the dialog box.
public String getText(){
return textView_.string();
}
Define the boilerplate code to allow the sample to run as an application.
public RootView rootView(){
if ( mainWindow != null ){
return mainWindow.rootView();
}
return super.mainRootView();
}
[Top] [ Displaying a Dialog Box with IFC] [Contents] [Previous] [Next] [Last]
Copyright © 1997 Netscape Communications Corporation