be.arci.applet
Class JApplicet.Context

java.lang.Object
  |
  +--be.arci.applet.JApplicet.Context

All Implemented Interfaces:

java.applet.AppletContext

Enclosing class:

JApplicet

public class JApplicet.Context

extends java.lang.Object

implements java.applet.AppletContext

The execution environment for JApplicet applications (implementing the java.applet.AppletContext interface); also adds functionality, specific for JApplicet applications, that need not be distributed with JApplicet applets.

The methods in this class can be used by an JApplicet to obtain information about its environment.

Note:
If the JApplicet is loaded as an applet by a web browser, the AppletContext will not be of this class type. The methods in this class that we added in addition the AppletContext implementation will not be available for JApplicet applets. These extra methods were selected so that you should only want to call them in the 'as-application' part of your code, typically the main method or it's callees; in that part of it will be safe to blindly typecast ((JApplicet.Context)getAppletContext()). If you do have to call them from other parts of your code (like init() and start() and their callees), you will have to test for isApplication() before casting, and may have to publish the JApplicet$Context.class file together with your applet on your website, because some browser JVM will try to load JApplicet.Context for bytecode verification if they find a typecast in an executed method. You can avoid this by dedoubling that part of code as follows:

 void methodA() {
     if (isApplication())
         ((JApplicet.Context)getAppletContext()).doSomeThing();
 void methodB() {
     if (isApplication())
         methodC();
 }
 void methodC() {
     ((JApplicet.Context)getAppletContext()).doSomeThing();
 }
 

When the browser executes methodA, it might try to load the file JApplicet$Context.class to verify the typecast, though it will never be used because isApplication() will always be false in a browser. methodB + methodC give you the same functionality, but methodC will never be executed by the browser because of the isApplication() test in methodB. So the bytecode for methodC will not be verified and JApplicet$Context.class will not be loaded.

Method Summary

java.applet.Applet	getApplet(java.lang.String sName) Finds and returns the applet with the given name in this execution context.
java.util.Enumeration	getApplets() Finds all the applets in this execution context.
java.applet.AudioClip	getAudioClip(java.net.URL url) Creates an audio clip.
java.awt.Image	getImage(java.net.URL url) Returns an Image object that can then be painted on the screen.
javax.swing.JTextField	getStatusField() Returns the status field of the JApplicet applition's AppletContext.
java.io.InputStream	getStream(java.lang.String key)
java.util.Iterator	getStreamKeys()
void	setActive(boolean swActive) Activates or deactivates the JApplicet application.
void	setBrowser(Browser browser) Sets the Browser for showing HTML and other documents from the JApplicet application.
void	setStatusField(javax.swing.JTextField tfStatus) Sets the status field of the JApplicet applition's AppletContext; all subsequent showStatus() messages are directed to this field.
void	setStream(java.lang.String key, java.io.InputStream stream)
void	showDocument(java.net.URL urlDocument) Equivalent to showDocument(url, "_top");.
void	showDocument(java.net.URL urlDocument, java.lang.String sTarget) Requests to show local document or the Web page indicated by the url argument.
void	showStatus(java.lang.String status) You should not call this method: call JApplicet.showStatus() instead. This method is public only because it is defined in an interface (java.applet.AppletContext).
void	showUsage(java.lang.String sMessage, boolean swExit) Convenience method to pop up a 'typical use' dialog with parameter help, and exit.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getAudioClip

public java.applet.AudioClip getAudioClip(java.net.URL url)

Creates an audio clip. We prefer to use JApplicet's getAudioClip(String) however.

Specified by:

getAudioClip in interface java.applet.AppletContext

Parameters:

url - an absolute URL giving the location of the audio clip.

Returns:

the audio clip at the specified URL.

See Also:

JApplicet.getAudioClip(String sName)

getImage

public java.awt.Image getImage(java.net.URL url)

Returns an Image object that can then be painted on the screen. The url argument that is passed as an argument must specify an absolute URL. We prefer to use JApplicet's getImage(String) however.

This method always returns immediately, whether or not the image exists. When the applet attempts to draw the image on the screen, the data will be loaded. The graphics primitives that draw the image will incrementally paint on the screen.

Specified by:

getImage in interface java.applet.AppletContext

Parameters:

url - an absolute URL giving the location of the image.

Returns:

the image at the specified URL.

See Also:

JApplicet.getImage(String sName)

getApplet

public java.applet.Applet getApplet(java.lang.String sName)

Finds and returns the applet with the given name in this execution context. The execution context can be seen as the ensemble of JApplicet applications activated from the same main() method; a JApplicet application enters this execution context during the explicit or implicit call to setActive(true), immediately before the init() method is called, and leaves it again during the explicit or implicit call to setActive(false), immediately after the destroy() method is called. The name can be set in the call to runAsApplication that is necessary to run an JApplicet application.

Specified by:

getApplet in interface java.applet.AppletContext

Parameters:

sName - an applet name.

Returns:

the applet with the given name, or null if not found.

See Also:

JApplicet.runAsApplication

getApplets

public java.util.Enumeration getApplets()

Finds all the applets in this execution context. The execution context can be seen as the ensemble of JApplicet applications activated from the same main() method; a JApplicet application enters this execution context during the explicit or implicit call to setActive(true), immediately before the init() method is called, and leaves it again during the explicit or implicit call to setActive(false), immediately after the destroy() method is called.

Specified by:

getApplets in interface java.applet.AppletContext

Returns:

an enumeration of all applets in this execution context.

showDocument

public void showDocument(java.net.URL urlDocument)

Equivalent to showDocument(url, "_top");.

Specified by:

showDocument in interface java.applet.AppletContext

See Also:

showDocument(URL urlDocument, String sTarget)

showDocument

public void showDocument(java.net.URL urlDocument,
                         java.lang.String sTarget)

Requests to show local document or the Web page indicated by the url argument. The target argument indicates in which HTML frame or window the document is to be displayed. The target argument is interpreted as follows:

"_self"	Not applicable when running as application; acts the same as _top.
"_parent"	Not applicable when running as application; acts the same as _top.
"_top"	Show in the top-level frame of the current Browser window.
"_blank"	Show in a new, unnamed top-level window.
name	Show in the frame or window named name. If a target named name does not already exist, a new top-level window with the specified name is created, and the document is shown there.

JApplicet.Context delegates the display of documents to an implementation of the Browser interface, that can be set by a call to setBrowser(Browser). The default Browser implementation is DummyBrowser, that does nothing at all. A Browser is free to ignore sTarget (just as it is free to ignore the complete showDocument() request).

Specified by:

showDocument in interface java.applet.AppletContext

Parameters:

urlDocument - an absolute URL giving the location of the document.

sTarget - a String indicating where to display the page.

See Also:

Browser, setBrowser, JApplicet.getResource, Viewing HTML documents

showStatus

public void showStatus(java.lang.String status)

You should not call this method: call JApplicet.showStatus() instead. This method is public only because it is defined in an interface (java.applet.AppletContext).

Requests that the argument string be displayed in the status field. The status field for JApplicet application is normally placed in the JFrame containing the JApplicet panel, though subclasses can access the field and place it elsewhere.

Specified by:

showStatus in interface java.applet.AppletContext

Parameters:

status - a string to display in the status window.

See Also:

getStatusField, "java.applet.Applet.showStatus(status)"

setActive

public void setActive(boolean swActive)
               throws java.lang.IllegalStateException

Activates or deactivates the JApplicet application. Activating includes calling your JApplicet's init() and start() methods. Deactivating includes calling your JApplicet's stop() and destroy() methods. As for any Applet, you need never call any of these 4 methods yourself, as they are called under control of the execution environment (your browser or JApplicet.Context), and calling them from within the applet or from another applet via intra-applet communication will not influence the 'active' state as reflected by isActive().

You only need to call this method if you initialized the JApplicet's application execution context with either or both swSetActive or swCreateFrame set to false in the call to runAsApplication.

Throws:

java.lang.IllegalStateException - if the JApplicet's isActive() state already equals the specified swActive paramater.

See Also:

JApplicet.runAsApplication, "java.applet.Applet.isActive()"

getStatusField

public javax.swing.JTextField getStatusField()

Returns the status field of the JApplicet applition's AppletContext. You can put this field in your own container if you do not let JApplicet create the application JFrame for you.

Use as follows:
((JApplicet.Context)getAppletContext).getStatusField();

Do not call this method if runAsApplication() has not been invoked.

See Also:

showStatus

setStatusField

public void setStatusField(javax.swing.JTextField tfStatus)

Sets the status field of the JApplicet applition's AppletContext; all subsequent showStatus() messages are directed to this field.

Normally when running as an application, this AppletContext will have added it's own status field to the parenting JFrame it created. If the user creates his own parenting Container, this AppletContext will not have created a status field, and the user can create one himself. It is the user's responsibility to add the status field Component to a container.

Use as follows:
((JApplicet.Context)getAppletContext).setStatusField(myTextField);

Do not call this method if runAsApplication() has not been invoked.

See Also:

showStatus

setBrowser

public void setBrowser(Browser browser)

Sets the Browser for showing HTML and other documents from the JApplicet application.

Use as follows:
((JApplicet.Context)getAppletContext).setBrowser(new MyBrowser());

Do not call this method if runAsApplication() has not been invoked.

See Also:

Browser, showDocument

showUsage

public void showUsage(java.lang.String sMessage,
                      boolean swExit)

Convenience method to pop up a 'typical use' dialog with parameter help, and exit.

The parameter help will contain the return value of getAppletInfo(), followed by sMessage, if not null, followed by the return value of getUsage(), if you override this method in your JApplicet. The default getUsage() implementation returns null, causing the display of the return values of getParameterInfo() and getReservedParameterInfo(), formatted according to the MessageFormat pattern definitions called "usage01" and "usage02" in Applicet_locale.properties.

Parameter help is shown in a modal JDialog .

Parameters:

sMessage - Extra message to show in the usage dialog.

swExit - if true, this method calls System.exit(-1) to stop execution immediately after disposal of the usage dialog.

See Also:

JApplicet.getUsage, formatI18NString, JApplicet.getI18NParameterInfo, JApplicet.getReservedParameterInfo

setStream

public void setStream(java.lang.String key,
                      java.io.InputStream stream)
               throws java.io.IOException

getStream

public java.io.InputStream getStream(java.lang.String key)

getStreamKeys

public java.util.Iterator getStreamKeys()