libgdx API

com.badlogic.gdx.scenes.scene2d.ui
Class ComboBox

java.lang.Object
  extended by com.badlogic.gdx.scenes.scene2d.Actor
      extended by com.badlogic.gdx.scenes.scene2d.ui.Widget
          extended by com.badlogic.gdx.scenes.scene2d.ui.ComboBox
All Implemented Interfaces:
Layout

public class ComboBox
extends Widget

A dropdown or combo box.

Functionality

A ComboBox contains a list of Strings, with one of the strings being selected and displayed in the main area of the ComboBox. Clicking the ComboBox brings up a popup list showing all the entries. This popup list will grab the touch focus while it is displayed. This is achieved by temporarily adding a new Actor to the root of the Stage the ComboBox is contained in. As soon as an item is selected or a mouse click outside the area of the popup list is registered, the popup will disappear again and the focus is given back.

A ComboBox.SelectionListener can be registered with the ComboBox to receive notification of selection changes.

Layout

A ComboBox's (preferred) width and height are determined by the border patches in the background NinePatch as well as the bounding box of the widest entry in the list of strings. Use Widget.setPrefSize(int, int) to change this size programmatically. In case the set size is to small to contain the widest entry, artifacts may appear.

The additional popup list will be positioned at the bottom edge of the ComboBox, displaying all entries. The width and size is governed by the background NinePatch of the popup list as well as the bounding box around the list entries.

Style

A ComboBox is a Widget displaying a background NinePatch as well as the selected list entry as a label via a BitmapFont and a corresponding Color. Additionally a popup menu might be displayed, using a NinePatch for the background, another NinePatch for highlighting the current selection and the same BitmapFont and Color used to display the selected entry in the actual ComboBox.

The style is defined via an instance of the ComboBox.ComboBoxStyle class, which can be either done programmatically or via a Skin.

A ComboBox's style definition in a skin XML file should look like this:
 <combobox name="styleName"  			 
           background="backgroundNinePatch" 
           listBackground="popupBackgroundNinePatch" 
           listSelection="popupSelectionNinePatch"
           font="fontName" 
           fontColor="colorName" />
 
 

Author:
mzechner

Nested Class Summary
static class ComboBox.ComboBoxStyle
          Defines the style of a combo box.
protected  class ComboBox.ComboList
           
static interface ComboBox.SelectionListener
          Interface for listening to selection events.
 
Field Summary
 
Fields inherited from class com.badlogic.gdx.scenes.scene2d.ui.Widget
invalidated, prefHeight, prefWidth
 
Fields inherited from class com.badlogic.gdx.scenes.scene2d.Actor
actions, color, height, name, originX, originY, parent, rotation, scaleX, scaleY, touchable, visible, width, x, y
 
Constructor Summary
ComboBox(java.lang.String[] entries, Stage stage, ComboBox.ComboBoxStyle style)
           
ComboBox(java.lang.String[] entries, Stage stage, Skin skin)
           
ComboBox(java.lang.String name, java.lang.String[] entries, Stage stage, ComboBox.ComboBoxStyle style)
          Creates a new combo box.
 
Method Summary
 void draw(SpriteBatch batch, float parentAlpha)
          Draws the Actor.
 java.lang.String getSelection()
           
 int getSelectionIndex()
           
 void layout()
          Positions and sizes each child of this actor.
 void setEntries(java.lang.String[] entries)
          Sets the entries of this combo box.
 void setSelection(int selection)
          Sets the selected item via it's index
 void setSelectionListener(ComboBox.SelectionListener listener)
          Sets the ComboBox.SelectionListener.
 void setStyle(ComboBox.ComboBoxStyle style)
          Sets the style of this widget.
 boolean touchDown(float x, float y, int pointer)
           
 void touchDragged(float x, float y, int pointer)
           
 void touchUp(float x, float y, int pointer)
           
 
Methods inherited from class com.badlogic.gdx.scenes.scene2d.ui.Widget
getPrefHeight, getPrefWidth, hit, invalidate, invalidateHierarchy, setPrefSize
 
Methods inherited from class com.badlogic.gdx.scenes.scene2d.Actor
act, action, clearActions, isMarkedToRemove, keyDown, keyTyped, keyUp, markToRemove, remove, scrolled, toLocalCoordinates, toString, touchMoved
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ComboBox

public ComboBox(java.lang.String[] entries,
                Stage stage,
                Skin skin)

ComboBox

public ComboBox(java.lang.String[] entries,
                Stage stage,
                ComboBox.ComboBoxStyle style)

ComboBox

public ComboBox(java.lang.String name,
                java.lang.String[] entries,
                Stage stage,
                ComboBox.ComboBoxStyle style)
Creates a new combo box. The width and height are determined by the widets entry and the style.

Parameters:
name - the name
entries - the single-line entries
stage - the stage, used for the popup
style - the ComboBox.ComboBoxStyle
Method Detail

setStyle

public void setStyle(ComboBox.ComboBoxStyle style)
Sets the style of this widget. Calls Widget.invalidateHierarchy() internally.

Parameters:
style -

layout

public void layout()
Description copied from interface: Layout
Positions and sizes each child of this actor. Subsequent calls will not have any affect unless Layout.invalidate() is called.


draw

public void draw(SpriteBatch batch,
                 float parentAlpha)
Description copied from class: Actor
Draws the Actor. The spriteBatch is configured so that the Actor can draw in its parents coordinate system. The parent's alpha is passed to the method in order for the Actor to multiply it with its own alpha. This will allow FadeIn and other Actions to have an effect even if they are only set on the parent of the Actor.

Specified by:
draw in class Actor
Parameters:
batch - the spritebatch to render with
parentAlpha - the parent's alpha value.

touchDown

public boolean touchDown(float x,
                         float y,
                         int pointer)
Specified by:
touchDown in class Actor

touchUp

public void touchUp(float x,
                    float y,
                    int pointer)
Specified by:
touchUp in class Actor

touchDragged

public void touchDragged(float x,
                         float y,
                         int pointer)
Specified by:
touchDragged in class Actor

setSelectionListener

public void setSelectionListener(ComboBox.SelectionListener listener)
Sets the ComboBox.SelectionListener.

Parameters:
listener - the listener or null

setSelection

public void setSelection(int selection)
Sets the selected item via it's index

Parameters:
selection - the selection index

getSelectionIndex

public int getSelectionIndex()
Returns:
the index of the current selection. The top entry has an index of 0

getSelection

public java.lang.String getSelection()
Returns:
the string of the currently selected entry

setEntries

public void setEntries(java.lang.String[] entries)
Sets the entries of this combo box. Invalidates all parents.

Parameters:
entries - the entries

libgdx API

Copyright 2010 Mario Zechner (contact@badlogicgames.com), Nathan Sweet (admin@esotericsoftware.com)