Jachievement

An achievement notification library

View the Project on GitHub cereda/jachievement

Welcome!

JAchievement is a small library written in Java that provides achievement notification features to any Java application. In short, this library provides an easy way for you to display achievements within an application.

The authors

JAchievement is maintained by Antoine Neveux  France   and Paulo Roberto Massa Cereda  Brazil.

License

The library is licensed under the New BSD License. The New BSD License has been verified as a GPL-compatible free software license by the Free Software Foundation, and has been vetted as an open source license by the Open Source Initiative.

The default achievement icon is provided by WPZOOM and licensed under the Creative Commons Attribution-Share Alike 3.0 Unported License.

Usage

JAchievement relies on a few lines of code. There are two dependencies, Trident and MigLayout libraries, so please add them to your classpath. And of course, don't forget to include the JAchievement library as well. We also provide a special jar file with "batteries-included", that is, with all dependencies packed together. The minimum working example is presented as follows:

Achievement achievement = new Achievement("Achievement unlocked", "My first Java code.");
AchievementQueue queue = new AchievementQueue();
queue.add(achievement);

That's it. In line 1, we created a new Achievement, in line 2 we created a new AchievementQueue and finally in line 3 we added the newly created object to the queue. By running it, we get the following output:

Achievement 1

The achievement is displayed in the top left corner of the screen. If you add

UIManager.setLookAndFeel(UIManager.getSystemLookAndFeelClassName());

in your application, the achievement notification will use the UI elements from the system look and feel. If you are in Windows, your achievement will look like:

Achievement 2

There are two constructors available for Achievement:

public Achievement(String title, String description)
public Achievement(String title, String description, AchievementConfig config)

Now let's take a look in the constructors arguments: title is the title of the achievement, that is, the highlighted text in the window. The description argument refers to the body text, the one right below the title. An optional config parameter can be used to configure the achievement behaviour, such as colours, fonts and icons.

For a more complex example, consider the following code:

UIManager.setLookAndFeel(UIManager.getSystemLookAndFeelClassName());

AchievementConfig config = new AchievementConfig();
config.setBackgroundColor(Color.CYAN);
config.setTitleColor(Color.BLUE);
config.setDescriptionColor(Color.BLUE);
config.setBorderColor(Color.BLUE);

Achievement achievement = new Achievement("Achievement unlocked", "My second Java code.", config);
AchievementQueue queue = new AchievementQueue();
queue.add(achievement);

The code is self-explanatory. We created an instance of AchievementConfig and called some methods to set how our new achievement should look. The output is presented as follows:

Achievement 3

Let's take a look at the complete list of setters from AchievementConfig:

public void setAchievementPosition(AchievementPosition achievementPosition)
public void setDistanceFromScreen(int distanceFromScreen)
public void setDuration(long milliseconds)
public void setInDuration(long milliseconds)
public void setOutDuration(long milliseconds)
public void setBackgroundColor(Color backgroundColor)
public void setBackgroundImage(ImageIcon backgroundImage)
public void setBorderColor(Color borderColor)
public void setBorderThickness(int borderThickness)
public void setDescriptionColor(Color descriptionColor)
public void setDescriptionFont(Font descriptionFont)
public void setIcon(ImageIcon icon)
public void setTitleColor(Color titleColor)
public void setTitleFont(Font titleFont)
public void setAudioEnabled(boolean audioEnabled)
public void setAudioInputStream(AudioInputStream audioInputStream)

We should also mention that you can define the position of the achievement on screen by using one of the values from the AchievementPosition enumeration:

public enum AchievementPosition {
    TOP_CENTER,
    TOP_LEFT,
    TOP_RIGHT,
    BOTTOM_CENTER,
    BOTTOM_LEFT,
    BOTTOM_RIGHT
}

From version 1.0 of JAchievement on, multiple achievement notifications are provided by the AchievementQueue manager class, which ensures that only a single achievement notification is displayed at a time.

The AchievementQueue manager class handles the calls for methods of the Achievement class. After adding an achievement to the queue, there is no need of calling any methods of the achievement itself.

To add an achievement to the queue, it's just a matter of calling the proper method:

public synchronized void add(Achievement achievement)

If there is no achievement notifications in the queue, the achievement notification is displayed right after the call of the add method. Otherwise, it will be queued until there is no achievement notifications currently in display. Please note this is a simple first in first out queue, so no priorities are estabilished when adding achievement notifications.

Download

The .jar files can be found on our GitHub downloads page. One of the .jar contains all the dependencies, so it can be used without anything else, while the other one contains only the JAchievement classes, so you'll need to add the dependencies manually to your application's classpath. And you can also get a .zip file of the source code from GitHub ZipBall feature.

Contribute

We'd be really happy if you'd like to fork JAchievement. Feel free to submit some pull requests. And don't hesitate to submit issues too if you have some comments about our work!

Contact

You can contact us through our Twitter accounts, @antoineneveux and @paulocereda, but of course there are other ways of reaching us:

Special thanks

To these two libraries used in the project: Trident and MigLayout.