A library to obtain a circular WidgetGroup within libGDX, an open-source game development application framework written in Java.
It aims at providing users with the so-called RadialGroup: a simple container that places its children Actors in a circular fashion.
The more interesting feature might be the PieMenu class : it wraps the RadialGroup with a bunch of functionalities that allow assigning callback functions to listeners on the highlight and selection of items within the Group.
In terms of User Interface, circular context menus "are faster and more reliable to select from than linear menus, because selection depends on direction instead of distance" (Wikipedia source). That is the whole motivation behind this library.
First, let us demonstrate what you might be able to get out of this library (those are just examples and the variety of possiblities is much larger, if not endless).
An online demo is available.
The trickier controls are:
RIGHT-CLICK: opens a PieMenu meant for selection through dragging (don't release the right-click until you're done with your selection). It was configured to let you preview the selection's effect.MIDDLE-CLICK: opens a PieMenu meant for "normal" selection. You can release the button and select as you wish with a left-click.
If you want to check out the same demo, but within a desktop setup, check out the Demonstration class.
You can also create your own animations:
It's surprisingly easy. Check out the Animated Widget wiki page to find out!
To use this in your gradle project, add the version number and jitpack repository information to your root build.gradle file:
allprojects {
ext {
...
pieMenuVersion = '5.0.0' // add this line
}
repositories {
...
maven { url 'https://jitpack.io' } // add this line if it isn't there
}
}And in your core project (still inside the root build.gradle) add the dependency:
project(":core") {
apply plugin: "java-library"
dependencies {
...
api "com.github.payne911:PieMenu:$pieMenuVersion" // add this line
}
}See the jitpack website for more info.
If you plan on releasing your project with an html ("HTML5/GWT") or android module, check out the Wiki page on integration.
The basic idea looks like this:
/* Setting up and creating the widget. */
PieMenu.PieMenuStyle style = new PieMenu.PieMenuStyle();
style.sliceColor = new Color(.33f,.33f,.33f,1); // "style" variables affect the way the widget looks
PieMenu menu = new PieMenu(skin.getRegion("white"), style, 80); // "white" would be a 1x1 white pixel
/* Adding a listener. */
menu.addListener(new ChangeListener() {
@Override
public void changed(ChangeEvent event, Actor actor) {
System.out.println("The selected index is: " + menu.getSelectedIndex());
}
});
/* Populating the widget. */
final int PIE_SLICES = 8;
for (int i = 0; i < PIE_SLICES; i++) {
Label label = new Label(Integer.toString(i), skin);
menu.addActor(label);
}
/* Including the widget in the Stage. */
stage.addActor(menu);And voilà!
This library offers you many types of behaviors related to pie-menus. Many of those are well-documented in the Wiki (with description, code and gif), so make sure to check it out.
More specifically, you might be interested in:
- Complete examples of code, along with textual descriptions of the expected behavior
- Understanding how to customize your widget's look and behavior.
Very well: you've made it this far in the README! If you ever end up integrating this library into your cool projects, feel free to send a Pull Request of a GIF showcasing this library and with the name of your game; just make sure it's pushed in the media/games folder!
Here are a few GIFs of games that have integrated this library.
Crawl Tactics, by icefill
Hadal Calm, by donpommelo
lurkers.io, by bergice
If you feel like helping this library grow, make sure to check out the Contributing Wiki page.
- EarlyGrey (PieMenu is actually partly dependent on his library: ShapeDrawer)
- raeleus (for the logo of the library)
- mgsx
- TEttinger
- Albert Pétoncle
For their sustained help through the libGDX Discord channel. Their extensive knowledge was greatly appreciated.
I used some images from Game-Icons.net, more specifically the 5 icons displayed when clicking the "Toggle Radial" button. To be even more specific, the credits go to Lorc. Those are under the CC BY 3.0 license.
Also, raeleus made the background image for the "middle-click menu" (which is also used in this library's logo), and the test application uses the Plain James UI Skin created by Raymond "Raeleus" Buckley under the CC BY 4.0 license. Check out the others!
The structure and build scripts of this repository were strongly inspired by RafaSKB's typing-label library.
Parts of this README were lazily copied and adapted from EarlyGrey's library (with his agreement). Cheers!