The TreeModel returned by {@link
+ * Bookmarks#getBookmarks} is composed of instances of this class.
New instances of this class may only be created with {@link + * Bookmarks#newBookmarkEntry}. Instances may be added to and removed + * from the bookmarks tree by calling {@link Bookmarks#addBookmark} and + * {@link Bookmarks#removeBookmark} respectively. A special entry that is a + * folder may be created with {@link Bookmarks#newBookmarkFolder}.
+ * + *The meta-data for the bookmark is contained in a
+ * Properties
Properties table.
+ *
+ */
-/**
+public interface BookmarkEntry extends MutableTreeNode {
+
+ /**
+ * The date on which this bookmark entry was added.
+ */ + + public final static String ADD_DATE = "AddDate"; - * Property names + /** + *The date on which this bookmark entry was last modified.
+ */ - */ + public final static String LAST_MODIFIED_DATE = "LastModifiedDate"; -public final static String ADD_DATE = "AddDate"; -public final static String LAST_MODIFIED_DATE = "LastModifiedDate"; -public final static String LAST_VISIT_DATE = "LastVisitDate"; -public final static String NAME = "Name"; -public final static String URL = "URL"; -public final static String DESCRIPTION = "Description"; -public final static String IS_FOLDER = "IsFolder"; + /** + *The date on which this bookmark entry was last visited by the + * browser.
+ */ -public Properties getProperties(); + public final static String LAST_VISIT_DATE = "LastVisitDate"; -public boolean isFolder(); + /** + *The name of this bookmark entry.
+ */ + public final static String NAME = "Name"; + /** + *The URL of this bookmark entry.
+ */ + + public final static String URL = "URL"; + + /** + *The optional user given description of this bookmark + * entry.
+ */ + + public final static String DESCRIPTION = "Description"; + + /** + *If this bookmark entry is a folder, the value of this property
+ * is the string "true" without the quotes.
Returns the Properties for this instance. Valid
+ * keys are given by the constants of this interface. Other keys
+ * may exist depending on the implementation.
Returns true if and only if this instance is a
+ * bookmark folder.
Provide an abstraction around the bookmarks facility provided by + * the underlying browser.
+ */ -public void addBookmark(BookmarkEntry mayBeNullParent, - BookmarkEntry bookmark); +public interface Bookmarks { + + /** + *Add the argument bookmark as a child of the
+ * argument mayBeNullParent. If
+ * mayBeNullParentis null, the bookmark is
+ * added as a child of the root node.
null the parent of
+ * this bookmark. The parent must return true from
+ * {@link BookmarkEntry#isFolder}.
+ */
+
+ public void addBookmark(BookmarkEntry mayBeNullParent,
+ BookmarkEntry bookmark);
+
+ /**
+ * Return a TreeModel representation of the
+ * bookmarks for the current profile.
Remove the argument bookmark from its current position in the + * tree.
+ */ -public TreeModel getBookmarks() throws IllegalStateException; - -public void removeBookmark(BookmarkEntry bookmark); + public void removeBookmark(BookmarkEntry bookmark); -public BookmarkEntry newBookmarkEntry(String url); + /** + *Create a new, un-attached {@link BookmarkEntry} instance + * suitable for passing to {@link #addBookmark}.
+ */ -public BookmarkEntry newBookmarkFolder(String name); + public BookmarkEntry newBookmarkEntry(String url); + + /** + *Create a new, un-attached {@link BookmarkEntry} instance
+ * suitable for passing to {@link #addBookmark} that is a
+ * folder for containing other BookmarkEntry instances.
Delete a {@link BrowserControl} instance created with {@link
* #newBrowserControl}. This method must be called when the user no
* longer needs a BrowserControl instance. For
- * example, when a browser tab closes.
BrowserControl
+ * are completely useless.
*
* @param toDelete the BrowserControl instance to
* delete.
diff --git a/mozilla/java/webclient/classes_spec/org/mozilla/webclient/CurrentPage.java b/mozilla/java/webclient/classes_spec/org/mozilla/webclient/CurrentPage.java
index d8e6aa3e724..b0dd9dad10b 100644
--- a/mozilla/java/webclient/classes_spec/org/mozilla/webclient/CurrentPage.java
+++ b/mozilla/java/webclient/classes_spec/org/mozilla/webclient/CurrentPage.java
@@ -1,4 +1,4 @@
-/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
+/* -*- Mode: java; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
*
* The contents of this file are subject to the Mozilla Public
* License Version 1.1 (the "License"); you may not use this file
@@ -81,26 +81,98 @@ package org.mozilla.webclient;
import java.util.Properties;
import org.w3c.dom.Document;
-public interface CurrentPage
-{
-public void copyCurrentSelectionToSystemClipboard();
-
-public void findInPage(String stringToFind, boolean forward, boolean matchCase);
-
-public void findNextInPage();
-
-public String getCurrentURL();
-
-public Document getDOM();
+/**
+ * Get information about and perform operations on the page currently
+ * being shown in the {@link BrowserControlCanvas} for the {@link
+ * BrowserControl} instance from which this CurrentPage
+ * instance was obtained.
Copy the current selection to the system clipboard so its
+ * contents can be obtained using the standard Java
+ * Toolkit.getDefaultToolkit().getSystemClipboard()
+ * method. The selection that is copied may be made either by the
+ * user, or programmatically via the {@link #selectAll} or {@link
+ * CurrentPage2#highlightSelection} methods.
Search for the argument stringToFind in the
+ * current page, highlighting it and scrolling the view to show
+ * it.
true, search forward from the
+ * previous hit
+ *
+ * @param matchCase if true, the case must match in
+ * order to be considered a hit.
+ *
+ * @deprecated this method has been replaced by {@link
+ * CurrentPage2#find}.
+ */
-public String getSource();
+ public void findInPage(String stringToFind, boolean forward, boolean matchCase);
+
+ /**
+ * Find the next occurrence of the String found with {@link + * #findInPage}.
+ * + * @deprecated this method has been replaced by {@link + * CurrentPage2#findNext}. + */ + + public void findNextInPage(); + + /** + *Return the URL of the document currently
+ * showing.
Return a W3C DOM Document of the document currently
+ * showing.
Unimplemented Return meta-information for the current + * page.
+ */ + + public Properties getPageInfo(); + + /** + *Return the source for the current page as a String.
+ */ + public String getSource(); -public byte [] getSourceBytes(); + /** + *Return the source for the current page as a byte
+ * array.
Reset the find so that the next find starts from the beginning + * or end of the page.
+ */ -public void resetFind(); + public void resetFind(); -public void selectAll(); + /** + *Tell the underlying browser to select all text in the current + * page.
+ */ + + public void selectAll(); } // end of interface CurrentPage diff --git a/mozilla/java/webclient/classes_spec/org/mozilla/webclient/CurrentPage2.java b/mozilla/java/webclient/classes_spec/org/mozilla/webclient/CurrentPage2.java index 35bb572af4d..98e606ee08c 100644 --- a/mozilla/java/webclient/classes_spec/org/mozilla/webclient/CurrentPage2.java +++ b/mozilla/java/webclient/classes_spec/org/mozilla/webclient/CurrentPage2.java @@ -23,20 +23,65 @@ package org.mozilla.webclient; +/** + *Extended current page functionality.
+ */ public interface CurrentPage2 extends CurrentPage { + + /** + *Return a {@link Selection} instance for the current selection.
+ * This is the only way to obtain a Selection
+ * instance.
Take the argument {@link Selection} and highlight it in the + * current page.
+ * + * @param selection the selection, obtained from {@link + * #getSelection} to be highlighted. + */ public void highlightSelection(Selection selection); + /** + *Make it so the current page has nothing selected.
+ */ + public void clearAllSelections(); + + /** + *Pop up a native print dialog to allow the user to print the + * current page.
+ */ public void print(); + + /** + *Turn the browser into print preview mode depending on the
+ * value of the argument preview.
Enhanced version of {@link CurrentPage#findInPage} that allows + * the caller to discover the result of the find.
+ */ public boolean find(String stringToFind, boolean forward, boolean matchCase); + /** + *Enhanced version of {@link CurrentPage#findNextInPage} that allows + * the caller to discover the result of the find.
+ */ + public boolean findNext(); } // end of interface CurrentPage2 diff --git a/mozilla/java/webclient/classes_spec/org/mozilla/webclient/DocumentLoadEvent.java b/mozilla/java/webclient/classes_spec/org/mozilla/webclient/DocumentLoadEvent.java index 321087e5aee..bf7c5356d97 100644 --- a/mozilla/java/webclient/classes_spec/org/mozilla/webclient/DocumentLoadEvent.java +++ b/mozilla/java/webclient/classes_spec/org/mozilla/webclient/DocumentLoadEvent.java @@ -1,4 +1,4 @@ -/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- +/* -*- Mode: java; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- * * The contents of this file are subject to the Mozilla Public * License Version 1.1 (the "License"); you may not use this file @@ -22,26 +22,88 @@ package org.mozilla.webclient; -public class DocumentLoadEvent extends WebclientEvent -{ +/** + *Event class for the {@link DocumentLoadListener} interface.
+ * + */ -public static final long START_DOCUMENT_LOAD_EVENT_MASK = 1; -public static final long END_DOCUMENT_LOAD_EVENT_MASK = 1 << 2; -public static final long START_URL_LOAD_EVENT_MASK = 1 << 3; -public static final long END_URL_LOAD_EVENT_MASK = 1 << 4; -public static final long PROGRESS_URL_LOAD_EVENT_MASK = 1 << 5; -public static final long STATUS_URL_LOAD_EVENT_MASK = 1 << 6; -public static final long UNKNOWN_CONTENT_EVENT_MASK = 1 << 7; -public static final long FETCH_INTERRUPT_EVENT_MASK = 1 << 8; +public class DocumentLoadEvent extends WebclientEvent { + + /** + *The type of the event to indicate the start of a
+ * document load.
The type of the event to indicate the end of a
+ * document load.
If the current document is a compound document, this event + * will be generated, indicating the start of a URL load within a + * document load for that compound document.
+ */ + + public static final long START_URL_LOAD_EVENT_MASK = 1 << 3; + + /** + *If the current document is a compound document, this event + * will be generated, indicating the end of a URL load within a + * document load for that compound document.
+ */ + + public static final long END_URL_LOAD_EVENT_MASK = 1 << 4; + + /** + *This event indicates a progress message from the browser.
+ */ + + public static final long PROGRESS_URL_LOAD_EVENT_MASK = 1 << 5; + + /** + *This event indicates a status message from the browser. For + * example, "completed."
+ */ + public static final long STATUS_URL_LOAD_EVENT_MASK = 1 << 6; + + /** + *This event indicates the browser encountered an unknown + * content that it does not know how to display.
+ */ + + public static final long UNKNOWN_CONTENT_EVENT_MASK = 1 << 7; + + /** + *This event indicates the current fetch was interrupted.
+ */ + + public static final long FETCH_INTERRUPT_EVENT_MASK = 1 << 8; // // Constructors // + /** + *Create a new DocumentLoadListener instance.
super. This will be the {@link EventRegistration}
+ * instance for this {@link BrowserControl}.
+ *
+ * @param newType the eventType. Depends on the {@link
+ * WebclientEventListener} sub-interface.
+ *
+ * @param newEventData the eventType. Depends on the {@link
+ * WebclientEventListener} sub-interface.
+ */
-public DocumentLoadEvent(Object source, long newType,
- Object newEventData)
-{
- super(source, newType, newEventData);
-}
-
+ public DocumentLoadEvent(Object source, long newType,
+ Object newEventData) {
+ super(source, newType, newEventData);
+ }
+
} // end of class DocumentLoadEvent
diff --git a/mozilla/java/webclient/classes_spec/org/mozilla/webclient/DocumentLoadListener.java b/mozilla/java/webclient/classes_spec/org/mozilla/webclient/DocumentLoadListener.java
index 8fbbd35d2a0..4d0a2e7c84e 100644
--- a/mozilla/java/webclient/classes_spec/org/mozilla/webclient/DocumentLoadListener.java
+++ b/mozilla/java/webclient/classes_spec/org/mozilla/webclient/DocumentLoadListener.java
@@ -1,4 +1,4 @@
-/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
+/* -*- Mode: java; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
*
* The contents of this file are subject to the Mozilla Public
* License Version 1.1 (the "License"); you may not use this file
@@ -23,21 +23,25 @@
package org.mozilla.webclient;
/**
- * The eventDispatched() method is passed a {@link
- * DocumentLoadEvent} instance. The type property of the
- * event will be one of the types defined as a public static final
- * int in DocumentLoadEvent.
The {@link WebclientEventListener#eventDispatched} method is
+ * passed a {@link DocumentLoadEvent} instance. The type
+ * property of the event will be one of the types defined as a
+ * public static final int constant in
+ * DocumentLoadEvent.
The eventData property of the
* DocumentLoadEvent instance will be a
- * java.util.Map. For all EVENT_MASK types in
+ * java.util.Map. For all types in
* DocumentLoadEvent the map will contain an entry under
* the key "URI" without the quotes. This will be the
* fully qualified URI for the event.
For the PROGRESS_URL_LOAD_EVENT_MASK there will be an
- * entry in the map for the key "message". This will be
- * the progress message from the browser.
message" without the
+ * quotes. This will be the progress message from the browser.
+ *
+ * For extended information about the event, implement {@link + * PageInfoListener}.
* */ diff --git a/mozilla/java/webclient/classes_spec/org/mozilla/webclient/NewWindowListener.java b/mozilla/java/webclient/classes_spec/org/mozilla/webclient/NewWindowListener.java index 6cae1e9db77..961743edb72 100644 --- a/mozilla/java/webclient/classes_spec/org/mozilla/webclient/NewWindowListener.java +++ b/mozilla/java/webclient/classes_spec/org/mozilla/webclient/NewWindowListener.java @@ -1,4 +1,4 @@ -/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- +/* -*- Mode: java; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- * * The contents of this file are subject to the Mozilla Public * License Version 1.1 (the "License"); you may not use this file @@ -22,50 +22,134 @@ package org.mozilla.webclient; +/** + *This interface allows the implementer to be notified of {@link + * NewWindowEvent}s that occur as a result of user browsing. For + * example, pop-ups.
+ * + *The constants defined in this interface should really be defined
+ * on {@link NewWindowEvent}, but they remain here for backwards
+ * compatability. They are given to the user as the value of the
+ * type property of the NewWindowEvent. They
+ * advise the user on the characteristics of the new window to be
+ * created. They should be anded with the argument eventType to
+ * determine if they are indicated for this event. Here is an example
+ * of how to create a new window in response to a
+ * NewWindowEvent:
+ *
+ *
+public void eventDispatched(WebclientEvent newWindowEvent) {
+
+ BrowserControl newBrowserControl = null;
+ BrowserControlCanvas newCanvas = null;
+
+ Frame newFrame = new Frame();
+
+ long type = newWindowEvent.getType();
+ if (type & NewWindowListener.CHROME_MENUBAR) {
+ // create a menu bar for the new window
+ }
+ if (type & NewWindowListener.CHROME_WINDOW_CLOSE) {
+ // Make it so this window cannot be closed
+ }
+
+ try {
+ newBrowserControl = BrowserControlFactory.newBrowserControl();
+ newCanvas = (BrowserControlCanvas)
+ newBrowserControl.queryInterface(BrowserControl.BROWSER_CONTROL_CANVAS_NAME);
+ // obtain any other interfaces you need.
+ } catch (Throwable e) {
+ System.out.println(e.getMessage());
+ }
+
+ newFrame.add(newCanvas, BorderLayout.CENTER);
+ newFrame.setVisible(true);
+ newCanvas.setVisible(true);
+}
+
+ * Base event class for browser specific events coming from the + * browser.
+ */ -// -// Attribute ivars -// +public class WebclientEvent extends EventObject { -private long type; + // + // Attribute ivars + // + + private long type; + + private Object eventData; + + // + // Constructors + // -private Object eventData; + /** + *Construct a new instance with the given source,
+ * type, and eventData. This method is
+ * typically not called by user code.
super. Depends on the {@link
+ * WebclientEventListener} sub-interface.
+ *
+ * @param newType the eventType. Depends on the {@link
+ * WebclientEventListener} sub-interface.
+ *
+ * @param newEventData the eventType. Depends on the {@link
+ * WebclientEventListener} sub-interface.
+ */
+
+ public WebclientEvent(Object source, long newType,
+ Object newEventData) {
+ super(source);
+ type = newType;
+ eventData = newEventData;
+ }
-//
-// Constructors
-//
-
-public WebclientEvent(Object source, long newType,
- Object newEventData)
-{
- super(source);
- type = newType;
- eventData = newEventData;
-}
-
-public long getType()
-{
- return type;
-}
-
-public Object getEventData()
-{
- return eventData;
-}
+ /**
+ * Return the type of this event. Depends on the {@link + * WebclientEventListener} sub-interface.
+ */ + + public long getType() { + return type; + } + + /** + *Return the event data for this event. Depends on the {@link + * WebclientEventListener} sub-interface.
+ */ + public Object getEventData() { + return eventData; + } + } // end of class WebclientLoadEvent diff --git a/mozilla/java/webclient/classes_spec/org/mozilla/webclient/WebclientEventListener.java b/mozilla/java/webclient/classes_spec/org/mozilla/webclient/WebclientEventListener.java index 27859f2f625..2f06bc3f1ab 100644 --- a/mozilla/java/webclient/classes_spec/org/mozilla/webclient/WebclientEventListener.java +++ b/mozilla/java/webclient/classes_spec/org/mozilla/webclient/WebclientEventListener.java @@ -1,4 +1,4 @@ -/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- +/* -*- Mode: java; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- * * The contents of this file are subject to the Mozilla Public * License Version 1.1 (the "License"); you may not use this file @@ -22,16 +22,28 @@ package org.mozilla.webclient; -public interface WebclientEventListener -{ - /** - - * Important: do not call any webclient methods during this callback. - * It may caus your app to deadlock. - + *The base interface for many, but not all, events coming from the
+ * browser. For example, it is possible to add a
+ * java.awt.event.MouseListener or
+ * java.awt.event.KeyListener to the {@link
+ * BrowserControlCanvas}. Doing so will cause events specific to those
+ * interfaces to be generated. See the sub-interface javadoc for more
+ * details.
This method will be called by the browser when a particular
+ * event occurs. The nature of the argument event
+ * depends on the particular WebclientEventListener
+ * sub-interface that is implemented. See the sub-interface javadoc
+ * for more details.
if called before {@link - * BrowserControlFactory#setAppData(java.lang.String)}, this will - * cause the profile used for starting up the underlying browser to - * be set. If not called, the default will be "webclient"
+ * + *See {@link + * BrowserControlFactory#setProfile}.
+ * */ public void setProfile(String profileName); + /** + * + *See {@link + * BrowserControlFactory#appTerminate}.
+ * + */ + public void appTerminate() throws Exception; + /** + * + *See {@link + * BrowserControlFactory#newBrowserControl}.
+ * + */ + public BrowserControl newBrowserControl() throws InstantiationException, IllegalAccessException, IllegalStateException; /** - - * BrowserControlFactory.deleteBrowserControl is called with a - * BrowserControl instance obtained from - * BrowserControlFactory.newBrowserControl. This method renders the - * argument instance completely un-usable. It should be called when the - * BrowserControl instance is no longer needed. This method simply - * calls through to the non-public BrowserControlImpl.delete() method. - - * @see org.mozilla.webclient.ImplObject#delete - - */ + * + *See {@link + * BrowserControlFactory#deleteBrowserControl}.
+ * + */ public void deleteBrowserControl(BrowserControl toDelete); diff --git a/mozilla/java/webclient/classes_spec/org/mozilla/webclient/overview.html b/mozilla/java/webclient/classes_spec/org/mozilla/webclient/overview.html index b8ef13b0802..b31042f6353 100644 --- a/mozilla/java/webclient/classes_spec/org/mozilla/webclient/overview.html +++ b/mozilla/java/webclient/classes_spec/org/mozilla/webclient/overview.html @@ -33,16 +33,16 @@The API Javadocs for the Webclient specification.
-Brief usage available in the package docs for the
-org.mozilla.webclient package. Detailed usage instructions
-are available at Brief usage available in the package docs for the org.mozilla.webclient package. Detailed usage
+instructions are available at http://www.mozilla.org/projects/blackwood/webclient/#Using.