Java Doc for JEditorPane.java in  » 6.0-JDK-Core » swing » javax » swing » Java Source Code / Java DocumentationJava Source Code and Java Documentation

This component uses implementations of the EditorKit to accomplish its behavior. It effectively morphs into the proper kind of text editor for the kind of content it is given. The content type that editor is bound to at any given time is determined by the EditorKit currently installed. If the content is set to a new URL, its type is used to determine the EditorKit that should be used to load the content.

By default, the following types of content are known:

text/plain

Plain text, which is the default the type given isn't recognized. The kit used in this case is an extension of DefaultEditorKit that produces a wrapped plain text view.

text/html

HTML text. The kit used in this case is the class javax.swing.text.html.HTMLEditorKit which provides HTML 3.2 support.

text/rtf

RTF text. The kit used in this case is the class javax.swing.text.rtf.RTFEditorKit which provides a limited support of the Rich Text Format.

There are several ways to load content into this component.

1. The JEditorPane.setText setText method can be used to initialize the component from a string. In this case the current EditorKit will be used, and the content type will be expected to be of this type.
2. The JEditorPane.read read method can be used to initialize the component from a Reader. Note that if the content type is HTML, relative references (e.g. for things like images) can't be resolved unless the <base> tag is used or the Base property on HTMLDocument is set. In this case the current EditorKit will be used, and the content type will be expected to be of this type.
3. The JEditorPane.setPage setPage method can be used to initialize the component from a URL. In this case, the content type will be determined from the URL, and the registered EditorKit for that content type will be set.

Some kinds of content may provide hyperlink support by generating hyperlink events. The HTML EditorKit will generate hyperlink events if the JEditorPane is not editable (JEditorPane.setEditable(false); has been called). If HTML frames are embedded in the document, the typical response would be to change a portion of the current document. The following code fragment is a possible hyperlink listener implementation, that treats HTML frame events specially, and simply displays any other activated hyperlinks.

      class Hyperactive implements HyperlinkListener {
  
          public void hyperlinkUpdate(HyperlinkEvent e) {
  	          if (e.getEventType() == HyperlinkEvent.EventType.ACTIVATED) {
  		      JEditorPane pane = (JEditorPane) e.getSource();
  		      if (e instanceof HTMLFrameHyperlinkEvent) {
  		          HTMLFrameHyperlinkEvent  evt = (HTMLFrameHyperlinkEvent)e;
  		          HTMLDocument doc = (HTMLDocument)pane.getDocument();
  		          doc.processHTMLFrameHyperlinkEvent(evt);
  		      } else {
  		          try {
  			      pane.setPage(e.getURL());
  		          } catch (Throwable t) {
  			      t.printStackTrace();
  		          }
  		      }
  	          }
  	      }
      }
 

For information on customizing how text/html is rendered please see JEditorPane.W3C_LENGTH_UNITS and JEditorPane.HONOR_DISPLAY_PROPERTIES

Culturally dependent information in some documents is handled through a mechanism called character encoding. Character encoding is an unambiguous mapping of the members of a character set (letters, ideographs, digits, symbols, or control functions) to specific numeric code values. It represents the way the file is stored. Example character encodings are ISO-8859-1, ISO-8859-5, Shift-jis, Euc-jp, and UTF-8. When the file is passed to an user agent (JEditorPane) it is converted to the document character set (ISO-10646 aka Unicode).

There are multiple ways to get a character set mapping to happen with JEditorPane.

1. One way is to specify the character set as a parameter of the MIME type. This will be established by a call to the setContentType method. If the content is loaded by the setPage method the content type will have been set according to the specification of the URL. It the file is loaded directly, the content type would be expected to have been set prior to loading.
2. Another way the character set can be specified is in the document itself. This requires reading the document prior to determining the character set that is desired. To handle this, it is expected that the EditorKit.read operation throw a ChangedCharSetException which will be caught. The read is then restarted with a new Reader that uses the character set specified in the ChangedCharSetException (which is an IOException).

Newlines

For a discussion on how newlines are handled, see DefaultEditorKit.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeans^TM has been added to the java.beans package. Please see java.beans.XMLEncoder .
author:
   Timothy Prinzing
version:
   1.145 05/05/07

The default varies based on the look and feel; to enable it set the client JEditorPane.putClientProperty property with this name to Boolean.TRUE.
since:
   1.5

By default this is not enabled; to enable it set the client JEditorPane.putClientProperty property with this name to Boolean.TRUE.
since:
   1.5

Once a prototype EditorKit instance is successfully located, it is cloned and the clone is returned.
Parameters:
  type - the content type the editor kit, or null if there is nothingregistered for the given type

This method can be reimplemented to use some other kind of type registry. This can be reimplemented to use the Java Activation Framework, for example.
Parameters:
  type - the non-null content type the editor kit

This method is expected to have the the side effect of establishing the content type, and therefore setting the appropriate EditorKit to use for loading the stream.

If this the stream was an http connection, redirects will be followed and the resulting URL will be set as the Document.StreamDescriptionProperty so that relative URL's can be properly resolved.
Parameters:
  page - the URL of the page

This method is thread safe, although most Swing methods are not. Please see How to Use Threads for more information.
Parameters:
  content - the content to replace the selection with. Thisvalue can be null

If there is a charset definition specified as a parameter of the content type specification, it will be used when loading input streams using the associated EditorKit. For example if the type is specified as text/html; charset=EUC-JP the content will be loaded using the EditorKit registered for text/html and the Reader provided to the EditorKit to load unicode into the document will use the EUC-JP charset for translating to unicode. If the type is not recognized, the content will be loaded using the EditorKit registered for plain text, text/plain.
Parameters:
  type - the non-null mime type for the content editingsupport
See Also:   JEditorPane.getContentType
throws:
  NullPointerException - if the type parameteris null

NOTE: This has the side effect of changing the model, because the EditorKit is the source of how a particular type of content is modeled. This method will cause setDocument to be called on behalf of the caller to ensure integrity of the internal state.
Parameters:
  kit - the desired editor behavior
See Also:   JEditorPane.getEditorKit

 Document doc = jEditorPane.getDocument();
 doc.putProperty(Document.StreamDescriptionProperty, null);
 

This may load either synchronously or asynchronously depending upon the document returned by the EditorKit. If the Document is of type AbstractDocument and has a value returned by AbstractDocument.getAsynchronousLoadPriority that is greater than or equal to zero, the page will be loaded on a separate thread using that priority.

If the document is loaded synchronously, it will be filled in with the stream prior to being installed into the editor with a call to setDocument, which is bound and will fire a property change event. If an IOException is thrown the partially loaded document will be discarded and neither the document or page property change events will be fired. If the document is successfully loaded and installed, a view will be built for it by the UI which will then be scrolled if necessary, and then the page property change event will be fired.

If the document is loaded asynchronously, the document will be installed into the editor immediately using a call to setDocument which will fire a document property change event, then a thread will be created which will begin doing the actual loading. In this case, the page property change event will not be fired by the call to this method directly, but rather will be fired when the thread doing the loading has finished. It will also be fired on the event-dispatch thread. Since the calling thread can not throw an IOException in the event of failure on the other thread, the page property change event will be fired when the other thread is done whether the load was successful or not.
Parameters:
  page - the URL of the page
exception:
  IOException - for a null or invalidpage specification, or exception from the stream being read
See Also:   JEditorPane.getPage

This is implemented to remove the contents of the current document, and replace them by parsing the given string using the current EditorKit. This gives the semantics of the superclass by not changing out the model, while supporting the content type currently set on this component. The assumption is that the previous content is relatively small, and that the previous content doesn't have side effects. Both of those assumptions can be violated and cause undesirable results. To avoid this, create a new document, getEditorKit().createDefaultDocument(), and replace the existing Document with the new one. You are then assured the previous Document won't have any lingering state.

1. Leaving the existing model in place means that the old view will be torn down, and a new view created, where replacing the document would avoid the tear down of the old view.
2. Some formats (such as HTML) can install things into the document that can influence future contents. HTML can have style information embedded that would influence the next content installed unexpectedly.

An alternative way to load this component with a string would be to create a StringReader and call the read method. In this case the model would be replaced after it was initialized with the contents of the string.

This method is thread safe, although most Swing methods are not. Please see How to Use Threads for more information.
Parameters:
  t - the new text to be set; if null the oldtext will be deleted
See Also:   JEditorPane.getText