Awesome

PieMenu

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.

Table of Content

• Demo
  • Basic widgets
  • Custom-animated widgets
• Including in your project
• Usage
  • Wiki
• Final word
  • Games showcases
  • Contributing
  • Thanks to
    • Credits

Demo

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).

Basic widgets

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.

Custom-animated widgets

You can also create your own animations:

It's surprisingly easy. Check out the Animated Widget wiki page to find out!

Including in your project

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.

Usage

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à!

Wiki

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.

Final word

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!

Games showcases

Here are a few GIFs of games that have integrated this library.

Crawl Tactics, by icefill

Hadal Calm, by donpommelo

lurkers.io, by bergice

Contributing

If you feel like helping this library grow, make sure to check out the Contributing Wiki page.

Thanks to

• 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.

Credits

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!