Window and Dialog
Window emulates the typical window behavior of operating systems allowing you to create modal dialogs and draggable content. Window is just a fancy Table very much like other widgets in Scene2D. In fact, it's just a table added directly to the stage and enhanced with a few input listeners and convenience features.
The background is the main drawable that controls the appearance of the widget. All of your content appears within the bounds of the background. The defined padding of the drawable is applied to the contentTable where the children will be applied. A strange quirk in the design of the class places special importance to the top padding. This defines the area that the titleTable will be placed.
Although background is optional, there aren't many practical uses without defining one. Having no background also disables some functionality.
This is the font used to draw the title of the Window. This is used exclusively for the label placed inside the titleTable of the window.
Unfortunately, this is a required value even if you do not intend to create a Window with a title. Nevertheless, you can specify any font here and it won't matter unless you set a title.
This is the color for the title Label. Leave this as null to use the default color of the font. You must leave the color as null if you intend to use color markup in your text.
If you want your Window to stand out from the rest of your UI, set a stageBackground. This will completely obscure any widgets underneath the Window. To only dim the stage slightly, set a semi-transparent stageBackground.
Create a Window and add it to your Stage.
Although you have to provide a value for the titleFont of the style, you don't have to provide an actual title to the widget. Null will cause a crash, but you can pass in an empty String instead.
The title is a Label and that Label is placed in a special Table along the top of the Window called the titleTable.
You can add anything you want to this Table. The most common use is adding a button to close the Window.
You need to code the button to actually close the window.
Setting a new title is easy.
Setting the alignment of the label is pretty easy too.
You can also control the settings of the title cell for more placement options.
By default, the player may move the Window around by clicking and dragging the title Table. You can disable that functionality by calling Window#setMoveable()
Perhaps you want to manually position the window through code. It gets positioned to (0,0) by default. Since it's just an actor added directly to the stage, you can set the position using normal methods.
Maybe you just want to make sure that the Window cannot be pushed offscreen. In that case, use the method Window#setKeepWithinStage()
Set it to the center of the Stage.
Notice that there is some slight blurring of the edges. That's because setPosition() does not automatically round the position to an integer value.
Commonly in operating systems, a modal dialog will prevent the user from interacting with the rest of an application's interface until the dialog is confirmed or dismissed. The same can be done in Window.
Note that a modal Window will not pause the operation of your game or your UI. It just prevents the player's click event to propagate through to the rest of the Actors on the Stage.
Window does not automatically resize itself after you add children to it. Call Window#pack()
pack() resizes the Window to the preferred size of the widgets. Perhaps you want to have more finite control over the size of the Window. Since the Window is not added to a Table layout, you'll use the direct methods to manipulate it.
You can allow the user to change the size of the Window.
It's rather difficult for the user to touch the precise edge of the Window border. You can change the size of the border to make it easier.
As previously stated, Window is just a fancy Table. If you are unsatisfied with the behavior of Window, you can create your own class that extends Table and add that directly to your stage.
You will soon see that you are basically recreating the features of Window as you add more functionality on your own. Nevertheless, having control is sometimes more valuable. That's why I created PopTable. This covers a variety of my personal needs that weren't met with Window and related classes. Perhaps you too will have a use for its advanced features such as attaching to other actors, highlighting actors for tutorial styled pop ups, and more.
Dialog is a derivative of Window that gives you various helper methods to make pop up dialogs simple and easy to implement throughout your game. They use the same WindowStyle as Window does.
You don't have to add a dialog to the stage or call pack() to resize it. That is automatically handled by Dialog#show().
This uses a Fade transition to add the Dialog to the stage. If you want to use a different Action, you may use the overloaded method.
The same options are available for Dialog#hide() if you want to remove the Dialog.
Dialog adds two new convenience Tables to your Window: contentTable and buttonTable. If you incorrectly use the Window technique to add a widget to your Dialog, you will get the following.
Instead, you should call Dialog#getContentTable() to add to the right part of the layout.
You can also just use the convenience methods to add labels.
Similarly, there are methods to automatically add text buttons to the buttonTable.
The advantage is that you can string these method calls together if you want to be brief.
button() uses the default style for TextButton, but you may want to have more control over their appearance and functionality. You'll still want to register the button with the Dialog so that you can handle the clicks later.
What is the point of creating these buttons if they are not going to do anything? You are actually expected to override Dialog#result() and interpret the object parameter.
What object is equal to depends on what value you passed in when you called button(). Let's revisit that code and add some options.
Boolean values work well for a typical "OK" and "Cancel" dialog, but what if you have something more complicated?
Integers or an Enum will work well in this case.
You may want your Dialog to react to the keyboard as well. Commonly, "escape" will dismiss a dialog.
You can add as many keys as you want. You can even string them along with your button or text calls.
Learn about PopTable which is an advanced alternative to Window.
Proceed with 13 - Advanced Layout or return to the table of contents.