Joshua Marinacci's Blog

Community: Java Tools Archives

JavaFX Innovations: Inline Examples and Screenshots

One of the innovations in the JavaFX toolchain is our new javafxdoc tool. Rather than producing a set of html files like regular 'javadoc' does, we produce a single large XML file representing the entire codebase's API. This lets us easily add extra processing steps, such as producing semantic wellformed XHTML as you see today. It also lets us do a few other things. I think I've mentioned before the custom doclet tags for things like default value and read only attributes. Now we've added inline examples.

Before today if you wanted some example code with a screenshot in your docs you had to mark up the code manually (assuming you wanted any syntax highlighting), then copy the code into a separate project, compile it, run it, then save a screenshot of the running app. And finally you must copy the screenshot back into your docs. This system is really bad for several reasons:

• It's time consuming, so we do less of it.
• The repository becomes polluted with screenshots
• The sample code may not compile if the API changes before you release the SDK
• The screenshots can get quickly out of date
• The code snippets aren't syntax highlighted

Inline Examples

With our new inline examples system all of these are taken care of. Just use the @example doc tag and the rest is handled for you. The doc tool will compile and run your code into a buffered image. Then it will insert nicely syntax highlighted code back into the final page along with a link to the screenshot.

Here's an example:

@example
import javafx.scene.geometry.*;
import javafx.scene.paint.*;

ShapeSubtract {
    fill: Color.BLACK
    a: Rectangle { width: 100 height: 50 }
    b: Ellipse { centerX: 100 centerY: 25 radiusX: 50 radiusY: 25}
}

Will produce the page you see here:

Live page here

That's it. No muss! No fuss. Everything is taken care of for you.

So what doesn't work?

Well, there are a few rough edges still. Specifically:

• The syntax highlighting is very primitive. Essentially just a couple of quick regex's.
• The text the code: and produces: are generated, rather than being text the author specifies.
• There is no good way to know when the @example ends. For the time being I'm hacking it by marking the end with another doc tag @endexample.
• You can't have nicely formatted and highlighted code without also getting a screenshot.
• This won't work for non-graphics classes.
• This won't work for animation.

So there's still lots to do. In a future version I'd like to produce running applets rather than just screenshots, but I think that will have to wait until after the preview SDK. This is enough that we can get on with the task of writing great docs.

Stay tuned for more documentation improvements in the future.

My First Screencast: Visually build an RSS reader using NetBeans 6

With NetBeans 6 beta 2 out (and the final version going into High Resistance-"thou shall not break things" mode) I thought it might take the opportunity to show you some of the cool things you can do with it. I am a client guy, of course, so I'm very excited by the new features we've built to let you create and deploy desktop applications easily and quickly. I also wanted to try experimenting with screencasts. Since development of client apps is so visual I think a visual way of explaining them is good. This is my first screencast so please provide feedback of what you like and don't like.

The key to getting the most out of the new client tools in NetBeans 6 is the use of beans. Not just visual beans like Swing components, but also non-visual beans. When you wrap your functionality up as beans you can visually attach them together very easily.

In this screencast I will show you how to use a simple RSS reader bean to build a feed reading application with almost no code. The screencast is 12 minutes long, but I could build and deploy the app in about 4 minutes if I wasn't talking. That's how productive NetBeans 6 can make you.

Visually build an RSS reader with NetBeans 6, by Josh Marinacci

Here is the NetBeans project with all of the source and support jars.

The votes are in.

I've got a free moment here at the MidWest Tech Days (and if you are in the MidWest you should be here too!) so I thought I would tally the votes generated by my previous blog: You vote for your favorite article and I'll write it!

Before I get to the results themselves I must say that I was quite surprised by the response. 34 comments with some very good suggestions. I'm glad to see that there is such passion in these topics.

So here's the breakdown (and please correct me if I miscounted) :

• Graphic Design for Engineers: 18
• Intro to Painters: 14
• JavaFX Script: 10
• JXMapViewer: 8
• Swing App & Beans Binding in NetBeans: 7
• Nice feedback with Drag and Drop in Java 6.0: 2
• 1 each for JNLP'd Derby driven app and some stuff with lucene / solr / hibernate

I'm surprised that the JXMapViewer was so popular, and that the Swing App Framework and Beans Binding in NetBeans was so low. Most of all, however, I'm quite surprised to see the graphic design article score so high. Clearly "making GUIs that don't suck" is a high priority for a lot of you.

Thank you all for your feedback. It looks like I've got some writing to do. Keep watching for new articles coming soon.

Java FX updated, and a visit to the future of client Java

Open JFX updated

OpenJFX, the open source version of Java FX, was just updated. It has lots of improvements and demos, but the biggest thing is the first compiler, which will compile Java FX Script directly into bytecode rather than interpreting it. This is huge, because it makes FX Script a first class Java language, as well as being several orders of magnitude faster than interpretation.

Another big feature of this release is the better integration with NetBeans. FX Pad can now run directly inside NetBeans, further cementing NB as the Emacs of the 21st century. Now we just need a mail reader and mp3 player. :) I won't go into all of the new features, you can check it out for yourself here. Be sure to take a look at the SVG converter and chat client demo app: Casual. Lots of cool stuff in there.

The future of client Java

I've spent the last week in the bay area at secret clandestine meetings secretly planning the amazing top secret future of client Java and Java FX! Okay, that makes an endless week of meetings sound a lot more interesting than it really is, but there's some truth to it. We promised a lot of things at JavaOne, from designer tools to the consumer release of the JRE, and based on what I've seen in the last week I can say that we are really making all of this stuff happen. In fact, I'm going to come out here and make a bold (and not approved by my employer) statement:

2008 will be the year that client Java starts taking market share from Flash.

There, I said it. By JavaOne we will have completely re-energized client Java. And I mean client Java, not just desktop Java. Everything will be faster, prettier, easier to use, and easier to deploy. We will be better in the browser. We will be better on the desktop. We will be better on the phones. Existing technologies are being updated and new technologies will see their debut at JavaOne, if not earlier.

I'm not going to spoil things by telling you what's coming up. I'll just say that I have never been this excited about the direction client Java is going. Never! Exciting times are ahead for the Java community!

Beans binding rocks!

I was working on one of our NetBeans demos for Monday's Matisse session and it occurred to me. I was actually having fun putting together a little program! I grabbed some of our cool little beans from SwingLabs then wired them up to some text fields using zero code. Just binding expressions created visually using NetBeans M9. It was really easy and kinda fun. Beans binding makes the beans we've assembled in SwingX-WS in particular a whole lot more useful.

I'm starting to think that we may just have something here with the Beans Binding and Swing App Framework JSRs. They really are going to make building Swing apps a lot more enjoyable. And the demo we are pulling together will show you how to do some pretty powerful stuff with almost no code. I think you'll really enjoy it.

Okay, back to coding up demos.

Posse Brain Dump: JavaDocs from the year 2020

At the Java Posse Roundup last week we had some wonderful evening sessions called Lighting Talks. During these sessions each participant had 5 minutes to give their entire presentation. This necessitates, of course, brevity and clarity above all. And of course, since this was the evening, we were all sitting around munching on BBQ, drinking beer, and laughing away during the proceedings. So in short, it was a lot of fun. Some of the talks were Java related at all. Ido Green from Yahoo introduced us to the sport of orienteering and Joe Nuxoll from the Java Posse gave several presentations about the physics of race car driving. Fascinating stuff.

Anyway, back to what I came to talk about. What I'm about to show you is several demos that have been sitting on my harddrive for a while. I pulled them out and showed them to the Roundup attendees with a warm reception. This convinced me that some of you might like to see them too.

I want to state at this point that these are not SwingLabs projects. They are simply demos to try out ideas. However they all have the potential to be great SwingLabs projects. If you think they would be a good project and would like to help run it then please email me and Rich so we can get you started. Thanks.

No on with the show! I'll send out a different blog with each of these. Here's the first:

JavaDocs from the year 2020

This was an experiment in what we could do with Javadocs now that most browsers support Javascript and CSS very well. The code is pretty simple: a custom doclet which produces XML, then run through XSLTs to produce HTML which uses custom CSS and Javascript. All as spec compliant and clean as possible. The design of the new interface is both prettier and more functional than standard javadocs. It shows off lots of interest ideas like:

click to view live

• organizing docs by category using tabs
• grouping properties into a single unit
• conditionally hiding advanced and deprecated methods
• collapsing inherited methods into open/close strips
• pinning common features to a fixed header at the top
• reducing the vertical space used to show more docs at once.
• better styles for the overview and code snippets
• rollover/tooltips to show the full classname

Note that I've only done the classes themselves, not the class list or package level docs, so that's very spare right now.

Let me know what you think. More coming soon.

- Josh

First release of JSR 296

Hans just announced the first prototype implementation of JSR 296, the Swing Application Framework. I'm very excited about this because it will make Swing applications a lot easier to build and more maintainable. I'm even more excited because we will have top notch support for JSR 296 in NetBeans 6.0. I know this because I'm one of the developers working on it.

Our current work in NetBeans isn't very usable yet, but I thought I'd give you a few screenshots to let you see how it's developing.

Using JSR 296 you can create actions from plain methods by using the @Action annotation. Once you have done this NetBeans can search through your application to find all actions and then let you edit them.

There are three ways to work with Actions. First, you can select from a list of known actions in the property sheet (Fig 1)

Fig 1: the Action Property Editor in the property sheet

Second you can press the '...' button to open the full Action Property Editor dialog.(Fig 2)

Fig 2: the Action Property Editor Dialog

And finally you can use the global action list to see all actions and edit them. (Fig 3)

Fig 3: the Global Action List

Coming soon, more Swing Labs updates!

Free Projects Part 4: an LCD Controller

My sincere apologies. I completely forgot to post the code from the last free project, sketch pad, so here it is. I also forgot that I have one more project to give away, one very different than anything else I've ever done. This one involves some hardware.

Another crazy idea

You see, every so often I get a crazy idea for a startup, put some effort into it, and then realize that I know nothing about hardware or how to start a company. That means my harddrive is filled with interesting and bizarre company ideas, some of which are more developed than others. This is one of the more developed ones.

My idea was that when you play a full screen game or are doing something else which takes you full attention it would be nice to have a little LCD screen which would sit next to your computer and show you ambient information such as the time, weather, or the currently playing song on your MP3 player. If the gadget had buttons then you could use it to switch tracks, change the volume, look at different weather settings, or anything else you wanted to with it. Showing instant message alerts, for example.

There would be software on your computer which controlled this little gadget and had a set of plugins for doing different things. Since this would be written in Java you could easily write your own plugins to look at cool webservices or hook into native applications and system resources. The possibilities are endless!

Of course the possibilities are always endless, and I spent endless amounts of time playing around with it before I went on to other things. Maybe it's still a good idea. After all, this gadget seems to be selling, and mine would have been better. It's blue! Anyway, there is still a lot of interesting code hiding in here so it might still be useful to some of you.

The LCD controller

First of all, I purchased and wrote a little Java device driver for the Crystal Fontz 631 LCD display (the 601 as well, I think). It is a two line LCD display with four buttons and a USB connection. Given the poor state of USB in Java I had to install a USB to Serial device drive on my computer and then connect to the LCD as if it was a real serial port with the RXTX serial library.

Once I had access to the serial port I wrote some Java code to implement the LCD's packet protocol. This drove me crazy for days because I could get the word NOON to show up just fine but the word MOON would not. I finally figured out that the C code I was working from was written for Linux and assumed a little endian processor. Since Java is big-endian (which, like gravity, is the right way), my code only worked when the text happened to be symmetric! *sigh*. Bugs like these were the reason I stopped writing C code a decade ago.

Here is what the desktop control app looked like:

The clock plugin

As you can see, it has a simulation of the real LCD panel which shows you what the plugin or animation will look like when it running. You can configure each plugin and set which ones the panel will cycle through. The LCD lets you define custom glyphs, which is how I created the fake large font for the time numbers.

weather plugin

The app also had a really bad glyph editor which you can see here:

glyph editor

But it did let you do some funky animations like this:

funky animation in progress

The code you are probably interested if you want to hack on this particular LCD panel is the CF601LCDPanel and Packet classes in the net.joshy.lcdbrick.serial package. There is interesting code in the plugins packages for reading weather, getting the current DHS threat level, and checking for new email. There is also some Mac specific code for controlling iTunes, getting the current battery level, setting the system volume.

So if you want it, let me know.

NetBeans Action Property Editor update

And to tide you over until we have something more to show, here is the latest screenshot of the Action Property Editor for JSR 296. It's a bit cleaner than the previous one and now you can edit icons! Let me know what you think.

Update: code download

The code is available here

Subversion Support in NetBeans 5.5

I've been so busy with NetBeans 6.0 work that I haven't commented at all on NetBeans 5.5. We just went final about a month ago and had a big party in Prague. 5.5 is a big release, though most of the work is under the hood or on the server side and being a client side developer it doesn't affect me much.. The new Visual Web Pack is pretty nice though. There is one feature, however, that I am really excited about and that I use every day. Subversion support. With NetBeans 5.5 you can download Subversion support through the Module Update center, and it will be built in to NetBeans 6.0. So let's dive in. What is Subversion anyway?

What is Subversion?

Why is Subversion Awesome?

Subversion is basically CVS with the bugs fixed and the sharp pointy bits rounded off. It improves upon CVS in pretty much every way while still keeping the same basic model. Here's just a few of the things that Subversion (also called SVN after it's 'svn' commandline program) get's right.

• Atomic commits. When you commit a bunch of files at once in CVS they are turned into a whole bunch of separate commits instead of one big one. This means you can't roll them back as a unit, or track them as a unit. With SVN you aren't changing a file, you are changing the entire structure of the tree as a unit. This means you can easily track and rollback changes as a group, the same way the developer committed them.
• Working offline. You can edit files and to diffs and status checks without having access to the server. Only when you actually commit does the server need to be there. This is great for hacking code on long trans-atlantic flights.
• Standard Protocols. Subversion uses HTTP and WebDAV as it's main transport protocol. This has two huge benefits. One, you can easily set up a Subversion server by using the mod_dav and mod_svn modules for Apache. This gives you easy maintenance and access control through a standard mechanism. You can even use HTTPS! Second, HTTP goes through firewalls better than anything else. No more futzing with SOCKS proxies and ssh tunnels to make CVS connect when you are at work.

Why is NetBeans Subversion Support Awesome?

Works like CVS. Previously Subversion support was an addon to the older versioning control system. Only CVS uses the modern API. Now Subversion does too, and it acts the same way. This makes switching between the two very easy. (very common when switching between java.net projects which can be either)

Built in. For 5.5 you can download it from the update center and in 6.0 it will be built in (I use it every day, actually). Nothing extra required.

You can still use the commandline. NetBeans acts like a good Subversion client, storing all of the versioning information in .svn directories. This means you can easily switch between the NetBeans client and the commandline version. For doing advanced Subversion tasks that aren't built into NetBeans this can be quite useful. For day to day use I say in NetBeans but it's nice to know that I could drop down to the command line if I need to.

change visualization NetBeans will icon badge and change the color of every buffer you have open as well as the source files in your Project view. This lets you know at a glance what has changed. You can also use the Show Changes command to see a list of changed files project wide and compare it to the server. You can also call the Show Changes command on just a directory branch of the tree. I do this all the time when I want to update something in the painters part of swingx, but not the whole project.

diff view NetBeans has a diff view which will show you both the server version and your current local version of any given file. When merging it will show you a third version at the bottom combining the changes of the two. You can use this tool to see what a merge will do. My only complaint is that you can't edit the file being diffed as I could in jEdit. I've been told that's coming in a future version, however.

Conclusion

Subversion really is a great tool. It provides almost everything I've ever wanted out of a revision control system. You can now choose Subversion instead of CVS when you create a java.net project, so it's great to finally have good support for it in NetBeans. You can learn more about the subversion support in Netbeans at http://subversion.netbeans.org/. Let me know what you think. What are you're favorite Subversion features and tips?

My first two weeks at Netbeans

Greetings from Prague. I've been at Netbeans for about two weeks now and it's been quite a busy time. I think I'm really going to like it here. Everyone is very friendly, the city is beautiful, and they have excellent and cheap beer (cheaper than soda!). I know you are all busy, so for the speed readers in the group I've bolded the important bits.

So what have I been working on? For starters, I have fixed my first two bugs in Matisse: Drop target is painted on the wrong order for Flow Layout and Improve retrieval of BeanInfos. Fixing a few bugs has been a great way to learn the codebase and get to know the team. When you click on the bug links be sure to note the new look of the website. Being a fan of good design I'm very happy that the pages look so much cleaner.

So what will I be doing for NetBeans? While I will no doubt be poking my head into lots of areas, my main task is working on Matisse. In particular, I am helping to add support for the Swing Application Framework, aka: JSR 296. I was already on the JSR expert group so that made me a perfect fit to work on Matisse. I'll have another blog with details on what we are doing, but for now I'll just say that this will make the common tasks of dealing with resources, strings, and actions ridiculously easy. In particular I will be working on the new Actions support, so look for design discussions over the next few weeks.

I should mention something at this point. It's ironic that I now work in NetBeans because until the last year or so I hated IDEs. As a diehard text editor user I started with Pico, graduated to Emacs, and eventually JEdit (when I figured out that no one hacks on Lisp anymore). I never liked IDEs because it felt like the got in the way, hid important details, and didn't really let me do anything new. Debugging is what println's are for. All of that changed when I first saw Matisse, the NetBeans visual GUI builder. Matisse let me build screens that are qualitatively better than anything I could ever do with GridBagLayout or other layout tools. Not only does it make the screens look better by using proper insets, I can also produce layouts in a tenth the time. This means that I am more likely to improve the layout, taking it through several iterations and show the results to other. This is what makes it such a great tool.

After getting hooked on Matisse I began trying other features of the IDE. Refactoring in particular impressed me. I have played around with the new editor and refactoring tools coming in NetBeans 6 and I'm very excited about them. A lot of long standing problems will be fixed, and most importantly the NetBeans 6 editor will be very fast!

Well, I've got get back to work on some design docs. In the meantime I'll leave you with a few photographs from my weekend trip to Cesky Krumlov (sp?) with the NetBeans evangelist team. Since I don't want to bore you with a constant travelog I think I'll just include a few photos in each blog entry until I run out. Since I've already taken about 800 shots, I've got a lot of blogging to do.

Enjoy!

- Josh

How to get code completion with Javadocs in Netbeans on Mac OS X

I'm sure I'm the last Mac Java developer here to figure this out so I'm posting it not so much for you but for future generations intrepid googlers to find.

How to get Netbeans code completion with Javadocs to work in Mac OS X

Netbeans is a great IDE and I'm really starting to warm up to it (starting to warm up to IDEs in general, actually). One of my big complaints so far has been the lack of Javadocs in the code completion popup window. Since I had some extra time today I thought I'd finally figure it out.

The reason Netbeans doesn't have javadoc code completion on the Mac, but does on other operating systems, is that Apple doesn't ship the src.jar by default. This is the jar which contains the source code to Java (at least the public APIs, go to the jdk project for the rest), and more importantly: all of the Javadocs. No src.jar, no javadocs. So the simple remedy is to install them. Here's how you do it:

1. Download the J2SE 5.0 Documentation bundle from Sun at http://java.sun.com/j2se/1.5.0/download.jsp
2. Unzip the downloaded file and place it wherever you want to store your documentation.
3. Open netbeans and go to the Tools -> Java Platform Manager menu.
4. Select the default platform (you may have only one), select the Javadocs tab, then press the Add Zip/Folder button.
5. In the file chooser navigate to the docs directory and select the api directory.
6. Pat yourself on the back. You now have code completion with javadocs.

Sweet!

Once more Matisse Rocks

I would just like to say that I'm more and more impressed with Matisse. It does it's absolute best to provide a realistic preview of running components at design time. Today I was building some component tests and was amazed to see that indeterminate progress bars are animated while in the designer! Have a look!

Easily Use Custom Swing Components with Matisse

I know it's been quite a while since I've written anything. I've been busy with quite a few project and I'll have some cool stuff to share soon. In the meantime I thought I'd show you an interesting tidbit I discovered in Matisse and Netbeans.

I've recently begun using Matisse for all of my GUI building tasks and overall I'm pretty pleased. I can quickly whip up dialog boxes and basic layouts very easily. However, I often use custom components and it's not easy to integrate them with Matisse. Sure, I could package my components up as full Java Beans and install them in the palette, but that's a whole lot of work for a single instance or two. I don't really want to have Matisse create the component for me, I just want the ability to use it's layout.

In the past I have created a panel with a zero width border and then put my custom components inside that. This will work most of the time but it still doesn't feel quite right. I'd rather have Matisse lay out my real component. I can't quite do that but I have found a nice little workaround that's pretty close.

The property palette has three tabs: Properties, Events, and Code. On the code tab there is a property (probably the last one) called Custom Creation Code. This property will let you use a custom constructor and initialization code. If you leave it blank then Matisse will generate something like "new JButton()" but you can override it to use your own code, as long as the result is some compatible class.

This may all sound a bit confusing so lets go with an example. I have a custom JButton subclass that I use for selecting colors. It's just like the normal JButton except it overrides the paintComponent() method to draw a box with the current background color. When you click on the button it will open a JColorChooser dialog to select a new color. Simple enough and not something I'd want to add to the designer palette. Instead I'll use the custom creation code.

I start by creating a normal JButton in the designer like this:

Then I go to the Custom Creation Code property in the code tab of the Properties palette and type in: new ColorSelectionButton(); Note that I didn't type in the jButton1 = part.

If I switch to code view and look at the generated code I can see this.

    private void initComponents() {
        jButton1 = new ColorSelectionButton();

        jButton1.setText("jButton1");

Then when I run my program it will look like this:

This system works great and I think I'm going to start using it from now on. It does have a couple of downsides though:

1. You can only use the parent class of your component. Your custom component will be cast down to a standard one so if you use a custom JButton then you must use a JButton in the designer rather than, say, a JLabel. As a consequence..
2. You can't use direct subclasses of JComponent because there is no JComponent in the standard palette. Most of the time this is fine (I usually subclass JButton or JPanel), but it might be a problem depending on your code.
3. Your preview in design mode won't match the running application. Matisse does a very good job of making design and runtime views match up, but using this hack defeats Matisse's efforts. In my example I see my custom button at runtime but still get the standard button in the design view.

So it's not perfect, but for most cases I have found it to be quite acceptable and plan to use this technique more in the future.

Update

Approximately 4.8 milliseconds after I posted this gfx informed me that Netbeans actually has a way to add components to the palette without creating a full Java bean. :) You can use the Palette Manager to add any public component class to the palette. *sigh*. Anyway, using the palette only works if you have a public class with no-arg constructor, so my technique is still useful if you want to use a special constructor or an anonymous inline subclass.

Enjoy!

Quick Tip for OSX Users

If you are like me you have broken finger bindings. Probably from years of bash use or maybe you just have to switch platforms all the time. Since finger bindings are difficult to change this little utility will change the key bindings instead.

Okay, so this isn't a Java tip, but it's useful nonetheless. If you are an OSX user, like me, then you may often run into the problem that the control, alt (option) and Open Apple (command) keys aren't where you think they should be. Maybe you are using a Windows keyboard with your iBook (like me). Maybe you have Emacs hard-wired into your brain and the control key should be closer. Whatever the reason, you need to remap a few keys. OSX doesn't come with a control panel to do this, but I recently found a little GPLed plugin that does it.

Double Command (so named because it lets you have two command keys on your powerbook), has the ability to remap lots of useful keys on your Mac.

Your highly recommended utility of the day. Isn't open source grand! :)

This work is licensed under a Creative Commons License.