Common Controls user's guide

Legal Notice

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no "Invariant Sections" , "Front-Cover Texts" or "Back-Cover Texts" , each as defined in the license. A copy of the license can be found in the file COPYING.DOC.txt included with jEdit.


Table of Contents

Chapter 1. Purpose

The plugin provides some set of common controls which can be useful for development of various jEdit plugins. These are the controls not included into the jEdit distribution

At the moment, the following controls are included:

You can also refer to the javadoc documentation.

Chapter 2. Description of controls

HelpfulJTable

Author:  Dirk Moebius

An extension of the default Swing JTable, that passes action key events, displays tooltips and autoresizes columns.

In detail, the following features are provided:

  • Fires an ActionEvent ,if Enter , Tab or Shift-Tab is pressed.

    Therefore, addActionListener(ActionListener) and removeActionListener(ActionListener) methods are provided.

  • Displays tooltips for partially visible text entries.

    To use this feature, you must use a TableCellRenderer that implements the methods getToolTipText() and/or getToolTipText(MouseEvent) , otherwise you won't see any tooltips.

  • utoresizes all columns to the length of its longest content string.

    As a drawback, this HelpfulJTable can only be used to with a String cell renderer, nothing complicated as a JList. (Complex components may be used a CellEditor, however).

Only the default constructor of JTable is provided. Please use setModel(TableModel) to set another model.

JMouseComboBox

Author:  Dirk Moebius

This is a combo-box that allows listeners to be informed of mouse entered and mouse exited events.

Note that other mouse events besides MOUSE_ENTERED and MOUSE_EXITED still do not get delivered. This is because sending a MOUSE_PRESSED, MOUSE_CLICKED or MOUSE_RELEASED event would cause the combo box popup to be hidden immediately after it has been shown, resulting in that it would not be shown at all.

This class was created as a fix/workaround for Swing bug #4144505.

Kappa and Lambda layout managers

Author:  Dale Anson

URL:  http://kappalayout.sourceforge.net/

Advanced layout managers.

PathBuilder

Author:  David Taylor

Nice panel for composing some path ($PATH or $CLASSPATH).

PopupList

Author:  Calvin Yu

The control is a generic popup component that displays a list of items.

Here's a list of potential uses for it:

  • Pop up a list of Templates to apply;

  • Pop up a list of dockables to switch between, much like the fast views concept in Eclipse;

  • Pop up a list of open buffers (yet another buffer switching mechanism);

  • Pop up list of auto-completions.

OkCancelButtons

Author:  Marcelo Vanzin

A panel with two buttons that tie to an instance of jEdit's EnhancedDialog and provide a GUI for the ok() and cancel() methods (aside from the regular enter/esc key bindings). The button label are configurable (defaults to OK and Cancel).

CloseableTabbedPane

A JTabbedPane that can have a "close" icon. This is a Java 5 version of the feature added to JTabbedPane in Java 1.6.

Usage is simple, use it exactly like a JTabbedPane, but add icons to the tabs:

        
                import common.gui.CloseableTabbedPane;
                
                ...
                
                tabs = new CloseableTabbedPane();
                Icon close_icon = GUIUtilities.loadIcon( "closebox.gif" );
                Icon hover_icon = GUIUtilities.loadIcon( "closebox.gif" );
                Icon pressed_icon = GUIUtilities.loadIcon( "closebox.gif" );
                tabs.setCloseIcons(close_icon, hover_icon, pressed_icon);
                JPanel panel = new JPanel();
                tabs.add(panel);
        
        

The "setCloseIcons" method has the possibility of adding separate icons for 'normal', 'hover', and 'pressed' mouse events.

It is also possible to specify that a tab be not closeable:

        
                tabs = new CloseableTabbedPane();
                Icon close_icon = GUIUtilities.loadIcon( "closebox.gif" );
                tabs.setCloseIcons(close_icon, close_icon, close_icon);
                JPanel panel = new JPanel();
                panel.putClientProperty("isCloseable", Boolean.FALSE);
                tabs.add(panel);
        
        

The "isCloseable" client property must be set before the component is added to the tabbed pane.

EasyOptionPane

Author:  Marcelo Vanzin

An implementation of jEdit's AbstractOptionPane that is easily configurable by using strings to define the component. Loading and saving of configuration data is handled automatically for the user of the class.

FileTextField

Author:  Marcelo Vanzin

A text field with an "attached" button that opens up a File Chooser so the user can pick up a file or directory.

ModalJFileChooser

Author:  Marcelo Vanzin

A JFileChooser implementation that fixes an annoying problem with the standard Java chooser when opening it from a dialog window (such as the options dialogs in jEdit). This wil ensure that the parent of the file chooser is the dialog, so the "modal" behavior will be correct. It also provides a "show all files even hidden ones" filter.

AtomicOutputStream

Author:  Marcelo Vanzin

An output stream that uses a temporary file to write the data, and only overwrites the target file at close time.

WorkerThreadPool

Author:  Marcelo Vanzin

A thread pool for executing non-GUI related tasks in a separate thread, avoiding blocking the GUI.

The pool working by adding "requests", which are instances of java.lang.Runnable, which are then picked up by the running worker threads and executed asynchronously. By adding a collection of requests instead of a single request the user forces the pool to create enough threads to handle all the requests simultaneouslty, so that tasks that need this functionality (such as reading from forked processes) can be easily run using this mechanism.

Normally plugins use the "single request" add method, which means that only one worker thread will be created. The caller can force new threads to be created by first calling the class's "ensureCapacity(int)" method, which will guarantee that at least the number of requested worker threads are running.

This is a simplified version of Java 5's ThreadPoolExecutor, and also provides a simplified version of the "Future" class (called "WorkRequest"). Callers can use the WorkRequest instances returned by the pool to control when the requests are finished.

SwingWorker (Java 5 version)

This is a Java 5 version of the SwingWorker included in Java 6. This version is a backport of the 1.6 version. The home page for this project is at https://swingworker.dev.java.net/.

When writing a multi-threaded application using Swing, there are two constraints to keep in mind: (refer to How to Use Threads for more details):

  • Time-consuming tasks should not be run on the Event Dispatch Thread. Otherwise the application becomes unresponsive.

  • Swing components should be accessed on the Event Dispatch Thread only.

These constraints mean that a GUI application with time intensive computing needs at least two threads: 1) a thread to perform the lengthy task and 2) the Event Dispatch Thread (EDT) for all GUI-related activities. This involves inter-thread communication which can be tricky to implement.

SwingWorker is designed for situations where you need to have a long running task run in a background thread and provide updates to the UI either when done, or while processing. Subclasses of SwingWorker must implement the doInBackground() method to perform the background computation.

See the SwingWorker javadoc for details and examples.

Appendix A. Change log

  • Version 1.1. 

    Added CloseableTabbedPane, a Java 5 version of a Java 6 feature added to JTabbedPane.

  • Version 1.0. 

    Added a Java 5 version of SwingWorker.

  • Version 0.9.4. 

    Add a few new classes: EasyOptionPane, FileTextField, ModalJFileChooser and AtomicOutputStream.

  • Version 0.9.2. 

    Small change to pathbuilder so it uses File.getPath() instead of getCanonicalPath() filenames returned from the file browser.

  • Version 0.9.0. 

    Adds a worker thread pool, fixes jEdit 4.3 compatibility for PopupList.

  • Version 0.8.1. 

    Uses deferred loading with jEdit 4.2.

  • Version 0.8. 

    Some fixes and improvements inHelpfulJTable. Now it can use the width of the headers in autoresize mode. Also, autoresizing does not exclude manual resizing any more.

  • Version 0.7. 

    The version of Kappa and Lambda layout managers is updated.

  • Version 0.6. 

    More stuff in PopupList.

  • Version 0.5. 

    Some additions to PopupList.

  • Version 0.4. 

    PopupList added

  • Version 0.3. 

    Kappa and Lambda layout managers added

  • Version 0.2. 

    PathBuilder package added

  • Version 0.1. 

    First release.