Overview

Frimble is short for Frame-able. Yes, we know it is daft.

It is a helper package that lets a developer of an application develop their application as a panel and use what ever type of frame-like containment that Jesktop may be configured to use.

Why do we need Frimble

Because there is no common interface that JFrame and JInternalFrame implement. You cannot as a Swing developer abstract your frame-like containment. Even if Sun chose to make them implement a future interface called Frameable, it could not work perfectly as the event structures are too incompatible to have a common interface.

Frimble itself is not a JComponent, it is a helper class so changes nothing about the implementation of JFrame or JInteralFrame.

See one of the bugs logged at Sun's bug parade on the subject here

What types of Frimble are available?

Today we have two types of frimble. JFrameFrimble and JInternalFrameFrimble. These encapsulate the the two swing classes of similar name. These are 99% complete and both work with the example applications that we have delivered.

Where types of Frimble will be available?

We see frimbles being created for general use that would give different views of contained components. We could develop a Frimble that uses a tabbed pane concept of containment. The tabs would be the windows and they might have a common menu bar that switched as the tabbed were changed. The thing would be novel but flawed as it is often nice to arrange your frames for special needs... i.e. reading from window A, whilst typing something else in Window B.

A Network appliance manufacturer that wanted to deliver a new appliance might create their own frimble mechanism with some way of preserving pixel space on their resolution restricted device, whilst still allowing all of the benefits of downloaded and hot installable java GUI applications. They might choose some drop-down type of launcher and running app changer. The same for hand held appliance manufacturers. Of course, the chips would have to beefier that today's (Dec 2000) Dragonball processors as The full JVM is required for NanoContainer and Jesktop and not the KVM as is popular at the moment.

How to port your GUI app to use Frimble

Assuming you have already got to the stage where your app is an executable jar file.

Step by Step

Stop using AWT, start using Swing (we guess you have already done this).
The only real place you will have to make changes is at the outermost JComponent. We'll call this the root JCompnent This JComponent should contain all visible aspects of your GUI. Usually it is the class that is instantiated and also has the main(args) method.
Take your JFrame instantiation out of the root JComponent's constructor, turning the root JCompnent into more of JComponent extended bean. If you used to extend JFrame, don't, extend JPanel instead please.
Implement the Interface "FrimbleAware" (jar supplied)
In you main(args) method use JFrameFrimble.getJFrameFrimble(new JFrame()) to get an instance of Frimble which you then pass into your instance with setFrimble(). Jesktop itself will call setFrimble() for the configuration it's chosen Frimble compatible container.
You can continue to have whatever other classes, helper classes, decorator classes, sub components etc.
Try to avoid static variables as Jesktop will allow a second and subsequent launches of the same app. If you genuinely have something that would be useful for all possible apps (of the same type) then static is fine. E.g. the word "Exit" for a menu, assuming you have hard coded English, is fine, but a static JMenuItem for exit will not be a good idea.
Jesktop, of course, does its own thing with Frimble and does not call your main(args) method. You keep that method to allow you to still be standalone (if your want).
In your META-INF/manifest, specify the dependant library from JesktopFrimble.jar to allow the standalone side of your app to run with double click. See http://java.sun.com/docs/books/tutorial/ext/basics/download.html for how to do this.
Add a file to your jar called JESKTOP-INF/applications.xml (see our examples) to indicate name and launchable class.
Your app should function identically. with your referring to a member instance of Frimble instead of JFrame

By Example

See FrimbleDemo for how easy this is. Execute this to see it in standalone mode (JFrame):

	  java -jar jesktop_frimble_demo.jar

or load the same jar into Jesktop via Jesktop's installer. See jesktop_frimble_demo.jar's MANIFEST.MF and applications.xml for the differences.

To see the source for Frimble demo click here.
To see the manifest for Frimble demo click here.
To see the applications.xml file for Frimble demo click here.

How they should be packaged in the jar file to be both standalone and Jesktop compatible:

            JESKTOP-INF/applications.xml

            META-INF/MANIFEST.MF

            org/jesktop/frimble/demo/FrimbleDemo.class

How to package your app that uses a Frimble

Whether you are going to intending your app to be Jesktop only or Standalone and Jesktop, you should not include the frimble package and it's classes in your apps main jar file. For Jesktop dependant mode, your app will automatically have the frimble classes available to it's class loading environment. For standalone mode, you should use a custom MANIFEST.MF file to indicate that a second jar is needed by the app. Sun have a few pages that talk about this (here), or your could just look at FrimbleDemo (TODO-link) and the section of the build.xml file concerning it for inspiration.