Autogui: an automatic GUI binding library

English | 日本語

Autogui is a library for automatically creating Java/Swing GUI apps from plain-old Java objects. It analyzes class-definitions of given objects through reflection APIs, and composes Swing-based components for each type of property and action defined in the classes.

License

Apache License v2

Building from source

GitHub Project Page

git clone https://github.com/ppp-kohe/autogui.git
cd autogui

The project uses apache-maven and depends on a recent version of Java.

• 1.7- : Java 21 or later
• 1.2- : Java 11 or later
• -1.1.x : Java 8 or later

mvn package
  # the command will generate target/autogui-1.8.jar

mvn install
  # the command makes the built library available locally to other projects. 

Note that the main part of the project does not depend on any libraries other than JDK classes. So you can manually compile source files placed in src/main/java (also src/main/resources for resources).

Maven usage

To use the library in your apache-maven project, you can insert the following dependency section into pom.xml.

    <dependency>
        <groupId>org.autogui</groupId>
        <artifactId>autogui</artifactId>
        <version>1.8</version>
    </dependency>

The library jar is available from Maven Central Repository: org.autogui:autogui.

API documents

• latest

Quick tutorial: A tiny example with jshell

The library can be used with jshell that is the official REPL-tool bundled with JDK since Java 9. To use the library, you first need to include the jar file of the library to your class-path. In jshell, you can do that by /env -class-path <path/to/jar>.

Simple steps for using the library with jshell is like following.

1. In the terminal, as described in Building from source, move to the directory autogui and build the library. (supposing the environment JDK, Git and Maven are installed)
2. start jshell
3. type /env -class-path target/autogui-1.8.jar in order to enable accessing the library.
4. next, type the following lines of code: it defines the class Hello.

   class Hello {
       String value;
       void action() {
           System.out.println(value);
       }
   }
   

5. also, type the following 3 lines of code: it uses the library and a window will be displayed.

   import org.autogui.swing.*;
   Hello h = new Hello();
   AutoGuiShell.showLive(h);
   

After following the steps above, the terminal should look something like this:

$ git clone https://github.com/ppp-kohe/autogui.git
$ cd autogui
$ mvn package
$ jshell
|  Welcome to JShell -- Version 21.0.3
|  For an introduction type: /help intro

jshell> 
class Hello {
   String value;
   void action() {
      System.out.println(value);
   }
}

/env -class-path target/autogui-1.8.jar

import org.autogui.swing.*;
Hello h = new Hello();
AutoGuiShell.showLive(h);

The above code defines the class Hello with an instance field and a method. After that, org.autogui.swing.AutoGuiShell.showLive(Object) starts creating a GUI window from the given object and shows the window.

The created window will contain a text field labeled as "Value" and a button on the tool-bar labeled as "Action". You can fill the text field with the string "hello, world" by typing the keyboard and click the button, then you will see "hello, world" on the console of jshell.

<img src="docs/images/image-hello-h.png" srcset="docs/images/image-hello-h.png 1x, docs/images/image-hello.png 2x" alt="Hello">

This means that the library creates the text field from the field value. The type of the field String specifies the type of the component as a text field. If you edit the text of the text field on the created window, the library automatically sets the value of the field of the given object h to the text input in the text field. This can be confirmed by jshell> h.value.

Also, the method action is bound to the action of the button on the tool-bar. If you click the button, the method will be invoked with the given object.

Example applications

See src/test/java/autogui/demo.

You can execute the code in the directory, by mvn test-compile exec:java -Dexec.classpathScope=test -Dexec.mainClass=....

ImageFlipDemo

For example:

 mvn test-compile exec:java -Dexec.classpathScope=test -Dexec.mainClass=org.autogui.demo.ImageFlipDemo

ImageFlipDemo.java is a bit interesting and useful example:

package org.autogui.demo;

import org.autogui.swing.AutoGuiShell;
import javax.imageio.ImageIO;
import java.awt.image.BufferedImage;
import java.io.File;

public class ImageFlipDemo {
    public static void main(String[] args) {
        AutoGuiShell.showLive(new ImageFlipDemo());
    }
    BufferedImage image;
    File output = new File("output.png");
    
    void flipY() {
        int w = image.getWidth();
        int h = image.getHeight();
        BufferedImage newImage = new BufferedImage(w, h, image.getType());
        for (int y = 0; y < h; ++y) {
            for (int x = 0; x < w; ++x) {
                newImage.setRGB(x, h - y - 1, image.getRGB(x, y));
            }
        }
        image = newImage;
    }
    
    void save() throws Exception {
        if (output.exists()) {
            System.err.println("File already exists: " + output);
        } else {
            ImageIO.write(image, "png", output);
        }
    }
}

The program will show a GUI window like the following image:

<img src="docs/images/image-flip-demo-h.png" srcset="docs/images/image-flip-demo-h.png 1x, docs/images/image-flip-demo.png 2x" alt="ImageFlipDemo">

The displayed window has the following GUI components:

• The image pane Image created from the field BufferedImage image : You can drag & drop an image file to supply an input image data. The dropped image will be automatically loaded as a BufferedImage object and displayed in the pane and assigned to the field.

• The action button Flip Y created from the method void flipY() : After dropping an image, you can click the button to flip Y coordinate of the image. The created newImage will be assigned to the image field. After the execution of the method, the image pane will show the flipped image.

• The file name field Output created from the field File output : You can put the name of saving the flipped image. The field initially displays "output.png"　in the working directory as the initial value of the field. User input for the text field will change the field value to a new File object.

• The action button Save created from void save() : The action can write the flipped image as a new file specified by the Output field.

FileRenameDemo

Here is another example for demonstrating table feature of the library.

mvn test-compile exec:java -Dexec.classpathScope=test -Dexec.mainClass=org.autogui.demo.FileRenameDemo

The command will show a GUI window like the following image:

<img src="docs/images/image-rename-demo-h.png" srcset="docs/images/image-rename-demo-h.png 1x, docs/images/image-rename-demo.png 2x" alt="ImageFlipDemo">

You can drag & drop a directory to the Dir field and then listing files in the directory as the Entries table. Note the Rename button actually changes names of the listed files to New Names without any warning.

This is constructed from the following code:

package org.autogui.demo;

import org.autogui.GuiIncluded;
import org.autogui.swing.AutoGuiShell;

import java.io.File;
import java.util.*;

@GuiIncluded public class FileRenameDemo {
    public static void main(String[] args) {
        AutoGuiShell.get().showWindow(new FileRenameDemo());
    }

    File dir;

    @GuiIncluded public File getDir() { return dir; }
    @GuiIncluded public void setDir(File dir) {
        boolean update = 
             dir != null && !Objects.equals(this.dir, dir);
        this.dir = dir;
        if (update && dir.isDirectory()) {
            List<RenameEntry> es = new ArrayList<>();
            int i = 0;
            List<File> files = new ArrayList<>(
                            Arrays.asList(dir.listFiles()));
            files.sort(Comparator.naturalOrder());
            for (File file : files) {
                es.add(new RenameEntry(file, 
                  String.format("%03d-%s", 
                                i, file.getName())));
                ++i;
            }
            entries = es;
        }
    }

    List<RenameEntry> entries = new ArrayList<>();

    @GuiIncluded public List<RenameEntry> getEntries() { 
        return entries; 
    }

    @GuiIncluded public static class RenameEntry {
        File file;
        String newName;
        public RenameEntry(File file, String newName) {
            this.file = file;
            this.newName = newName;
        }
        @GuiIncluded public File getFile() {
            return file;
        }
        @GuiIncluded public String getNewName() {
            return newName; 
        }
        @GuiIncluded public void setNewName(String newName) {
            this.newName = newName;
        }
    }

    @GuiInclud