The Java Application Markup Language (JAML) Libary Version: 0.1.1 Copyright (c) 2005 Michael Lam DESCRIPTION This library provides data structures and methods for building Java interfaces based on XML markup code. Besides laying a foundation for developer-defined interpretation of XML interface files, the library provides a basic interpretation that builds Swing components based on a very simple XML syntax called JAML. NOTE: THIS IS A PRERELEASE VERSION. EXPECT INCOMPLETE, INCORRECT AND/OR MISSING FEATURES AND DOCUMENTATION, AS WELL AS LOTS OF SOFTWARE DEFECTS (BUGS). I AM NOT RESPONSIBLE FOR ANY DAMAGE, LOSS OR MENTAL INSANITY RESULTING FROM THE USE OR MISUSE OF THIS SOFTWARE. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License (GPL) for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to: Free Software Foundation, Inc. 51 Franklin St, Fifth Floor Boston, MA 02110-1301 USA INSTALLATION Installation is pretty straightforward: unzip the distribution file and place jaml.jar into a folder that is in your CLASSPATH. Note that you will also need to distribute the jaml.jar file with your application unless you include the JAML classes in your own JAR file. QUICKSTART NOTE: THE CODE PROVIDED IN THIS SECTION DOES NOT WORK YET SINCE THE SWING JAML INTERPRETER IS NOT YET WRITTEN. SEE MAIN.JAML AND THE JAMLMAIN CLASS FOR EXAMPLES OF WORKING CODE. Using the JAML library to build the interface for your application is very easy. First, create a .jaml file in the same directory as your application and write your interface using the Java Application Markup Language (JAML): Name: Then, use the JAMLEngine object to load, parse, build and access the objects in your interface: class HelloApp { private JFrame mainWindow; private JTextField txtName; private JButton btnOK; private JButton btnCancel; public static void Main(String[] args) { try { // set up the engine JAMLEngine.setDefaultBuilder(new JAMLSwingBuilder()); JAMLEngine.setDefaultValidator(new JAMLSwingValidator()); // parse and build the interface file JAMLEngine.addCodeFile("main.jaml"); // get references to objects from the mapping collection mainWindow = (JPanel)JAMLEngine.get("mainWindow"); txtName = (JTextField)JAMLEngine.get("txtName"); btnOK = (JButton)JAMLEngine.get("btnOK"); btnCancel = (JButton)JAMLEngine.get("btnCancel"); // add event handlers and show the window btnOK.addActionListener(new ActionListener() { void ActionPerformed(ActionEvent e) { JOptionPane.showMessageDialog(mainWindow, "Hello, " + txtName.getText() + "!"); System.exit(0); } }); btnCancel.addActionListener(new ActionListener() { void ActionPerformed(ActionEvent e) { System.exit(0); } }); mainWindow.setVisible(true); } catch (IOException ex) { JOptionPane.showMessageDialog(null, "Error accessing main.jaml: " + ex.getMessage(); System.exit(-1); } catch (JAMLException ex) { JOptionPane.showMessageDialog(null, "Error building interface: " + ex.getMessage(); System.exit(-1); } } } It's that easy! :-) Of course, there are a lot more ways to use the JAML library than shown here (see the JAMLMain documentation for an even simpler way), and there are many ways to modify and/or extend the library to customize its behavior. For more information, see the 'DEVGUIDE' document or the JAML website at http://www.freearrow.com/jaml/. JAMLPAD If you execute the jar file using the following: java -jar JAML.jar it will launch an application called JAMLPad. Users of Microsoft's XAMLPad will feel right at home here. The idea is simple: enter your JAML in the edit area provided, and click Refresh to get an immediate preview of your interface. Errors will appear at the bottom of the screen as you edit to provide validation feedback. You can also load and save your code to .jaml files. If you want the preview window to refresh as you edit, simply check the "auto-refresh" box. Unfortunately, this only works if your root object is a panel. If it is a frame, focus shifts to the preview window as soon as you press a key, and I couldn't figure out how to grab the focus back (the standard requestFocus() functions don't do the trick). If this doesn't make sense, just try it and you'll soon understand the problem. :-) Right now the interface for JAMLPad is maintained by the NetBeans 5.0 visual editor. Eventually I will rewrite the interface in JAML as an example. I think I will also try to keep the old NetBeans code as an example of how much better things are using JAML. FURTHER INFORMATION This library is licensed under the GNU General Public License, which means that it is open-source software. You should have recieved a copy of the source and the GNU GPL license (see file 'LICENSE') along with the JAML library; if not, you can download them from the JAML website (see below). Since this software is GPL'ed, you may use it in any other free or open-source software, provided you include the library source code along with notes about any changes made to it. See the GPL for full details concerning usage, distribution and modification. NOTE: THIS LIBRARY MAY *NOT* BE USED IN A CLOSED-SOURCE SOFTWARE PROJECT. If you wish to contact the author (me) write to: Michael Lam mlam@freearrow.com For more details about how the JAML library works and how to modify or extend it for your own use, see the DEVGUIDE document or the JAML website: http://www.freearrow.com/jaml/ Enjoy! CHANGELOG v. 0.1.1 (Dec 05 2005) MAJOR: - added menu objects (w/ regular, check, option and separator items) - added menu accelerators and shorcuts - added option (radio) button and menu groups - added combobox, list box, slider, spinner and progress bar widgets - added tabbedpanel, tab and splitpanel components (all of the above apply only to the Simple JAML interpreter) - fixed design flaw that caused trouble adding objects to JAMLEngine - added main() method to JAMLSimpleValidator and toString() method to JAMLValidObject to more easily generate JavaDoc header for JAMLSimpleBuilder class MINOR: - modified JAMLPad to read initial contents from "jamlpad.sjaml" if available - added tests for all new objects into "jamlpad.sjaml" file - removed old layout code (commented out in previous version) - default window decorations no longer forced to use default look & feel - changed size properties to set size and preferred size instead of just size - added setDefaultValidator() method to JAMLEngine - one or two other minor problems fixed v. 0.1.0 (Nov 14 2005) - basic framework functionality written in less than one week!