public class GuiModalWindow
extends net.risingworld.api.gui.GuiPanel
implements net.risingworld.api.events.Listener
This class is not aimed at being used as it is; it is the base class of several, more specialised, classes which should be used instead. It can also be sub-classed, to implement specific structures or behaviours. The main panel is one of the GuiLayout subclasses, with its specific arrangement of children, according to the layoutType of the constructor. To the panel, standard GuiElement's can be added with addChild().
GuiModalWindow manages its own event Listener; it also turns the mouse cursor on on display and off on hiding.
GuiModalWindow manages the close button in the title bar, hiding the box from the player screen and turning off the mouse cursor. The callback object is notified of a close event by passing an id parameter with a value of RWGui.ABORT_ID. The consumer plug-in needs not to do any additional management of the dialogue box itself in response to this notification (of course, it would do any management of its own resources, including freeing the modal window itself with its free() method, if no longer needed).
GuiModalWindow notifies of click and text entry events via an RWGuiCallback object passed to the constructor or set after construction with the setCallback() method.
On events, the onCall() method of the callback object is called with parameters for the player originating the event, the id of the GuiElement and any additional data set for the GuiElement. Id and data for each child are set when the child is added.
This class implements a 'display stack' of modal windows: 'pushing' a new window with the push() method displays the new window and 'popping' it, with the pop() method, restores the window previously displayed.
Important: due to the way Rising World plug-ins are loaded, this class cannot instantiated or used in any way from within the onEnable() method of a plug-in, as it is impossible to be sure that, at that moment, the RWGui plug-in has already been loaded.
The first moment one can be sure that all plug-ins have been loaded, and it is safe to use this class, is when (or after) the first player connects to the server (either dedicated or local).
Modifier and Type | Field and Description |
---|---|
protected boolean |
autoClose |
protected RWGui.RWGuiCallback |
callback |
protected GuiLayout |
layout |
protected int |
listenerRef |
protected net.risingworld.api.Plugin |
plugin |
protected GuiModalWindow |
prevWindow |
protected GuiTitleBar |
titleBar |
Constructor and Description |
---|
GuiModalWindow(net.risingworld.api.Plugin plugin,
java.lang.String title,
int layoutType,
RWGui.RWGuiCallback callback)
Creates a new GuiModalWindow.
|
Modifier and Type | Method and Description |
---|---|
void |
addChild(net.risingworld.api.gui.GuiElement element)
Adds an inactive GuiElement (with no associated data) as a direct child
of the window.
|
void |
addChild(net.risingworld.api.gui.GuiElement element,
java.lang.Integer id,
java.lang.Object data)
Adds a GuiElement with the associated id and data as a direct child of
the window.
|
void |
close(net.risingworld.api.objects.Player player)
Closes (hides) the window from the player screen, turning the
mouse cursor off.
|
void |
free()
Releases the resources used by the window.
|
java.lang.Integer |
getItemId(net.risingworld.api.gui.GuiElement element)
Returns the id associated with element, if element is one of the
children of the window (recursively); or null otherwise.
|
void |
layout()
Lays the window out, arranging all the children of the layout
hierarchy.
|
void |
onClick(net.risingworld.api.events.player.gui.PlayerGuiElementClickEvent event) |
void |
onTextEntry(net.risingworld.api.events.player.gui.PlayerGuiInputEvent event) |
void |
pop(net.risingworld.api.objects.Player player)
Pops this window away from the 'display stack'.
|
void |
poppush(net.risingworld.api.objects.Player player,
GuiModalWindow win)
Combines pop() and push(), removing (and destroying) this window and
pushing win in its place.
|
void |
push(net.risingworld.api.objects.Player player,
GuiModalWindow win)
Chains another GuiModalWindow in the 'display stack'.
|
void |
removeChild(net.risingworld.api.gui.GuiElement element)
Removes a GuiElement from the direct children of the window.
|
void |
setCallback(RWGui.RWGuiCallback callback)
Sets the callback function called upon click and text entry events.
|
void |
setMargin(int value)
Sets the margin between the contents of the window and its edges.
|
void |
setPadding(int value)
Sets the padding (i.e.
|
void |
show(net.risingworld.api.objects.Player player)
Displays the window on the player screen.
|
destroy, equals, getAlpha, getBorderColor, getBorderThickness, getColor, getHeight, getHoverColor, getID, getParent, getParentID, getPivot, getPositionX, getPositionY, getWidth, hashCode, isRelativeBorderThickness, isRelativePosition, isRelativeSize, isVisible, refresh, removeFromParent, setAlpha, setBorderColor, setBorderColor, setBorderThickness, setColor, setColor, setPivot, setPosition, setSize, setVisible
protected boolean autoClose
protected RWGui.RWGuiCallback callback
protected GuiLayout layout
protected int listenerRef
protected GuiModalWindow prevWindow
protected net.risingworld.api.Plugin plugin
protected GuiTitleBar titleBar
public GuiModalWindow(net.risingworld.api.Plugin plugin, java.lang.String title, int layoutType, RWGui.RWGuiCallback callback)
plugin
- the plug-in the GuiModalWindow is intended for. This
is only needed to manage the internal event listener
and has no effects on the plug-in itself.title
- the text of the title.layoutType
- the type of the layout (one of the RWGui.LAYOUT_HORIZ
or RWGui.LAYOUT_VERT values)callback
- the callback object to which to report events. Can
be null, but in this case no event will reported
until an actual callback object is set with the
setCallback() method.public void onClick(net.risingworld.api.events.player.gui.PlayerGuiElementClickEvent event)
public void onTextEntry(net.risingworld.api.events.player.gui.PlayerGuiInputEvent event)
public void setCallback(RWGui.RWGuiCallback callback)
callback
- the new callbackpublic void setMargin(int value)
value
- the new margin (in pixels).public void setPadding(int value)
value
- the new padding (in pixels).public void layout()
public void addChild(net.risingworld.api.gui.GuiElement element)
addChild
in class net.risingworld.api.gui.GuiElement
element
- the element to add.public void addChild(net.risingworld.api.gui.GuiElement element, java.lang.Integer id, java.lang.Object data)
id can be any Integer and id's should be all different from one another within each window.
The data parameter can be any Java object and can store additional information required to deal with the element, when a click event is reported for it via the callback object. It can also be null if no additional info is needed for the element.
id and data are reported by the callback object upon click and text entry events. GuiTextField's would generate both click and text entry events: they can be distinguished because click events on a GuiTextField will call the callback object with null data parameter, while text entry events will have the data parameter set to the element current text.
element
- the element to add.id
- the id associated with the element; may be null for
inactive elements.data
- the data associated with the element; may be null for
elements which need no additional data other than their id.public void removeChild(net.risingworld.api.gui.GuiElement element)
removeChild
in class net.risingworld.api.gui.GuiElement
element
- The GuiElement to removepublic void show(net.risingworld.api.objects.Player player)
player
- the player to show the window to.public void close(net.risingworld.api.objects.Player player)
The window resources are not freed and the window can be re-used if needed; when the window is no longer needed, its resources must be freed with the free() method, in addition to closing it.
player
- the player from whose screen to remove the window.
Removing the same window from the same player multiple
times has no effect and does no harm.public void push(net.risingworld.api.objects.Player player, GuiModalWindow win)
The new window is displayed on the player screen 'over' this window, keeping the mouse cursor on.
As the Rising World API does not have the concept of window or of modality and any uncovered element of this window would remain clickable, this window is hidden (but not freed or destroyed); popping the new window away (with its pop() method) will show this window back as it was at the push time.
player
- the player on whose screen to display the new window.win
- the new GuiModalWindow to display.public void pop(net.risingworld.api.objects.Player player)
This window is closed down and freed and the window (if any) which pushed it will be shown back at the state it had at the push time.
If this window was not pushed, nothing will be displayed and the mouse cursor will be turned off.
After using this method, the window is no longer functional: none of its methods can be used and the window cannot be shown again or used in any way.
player
- the player from whose screen to pop this window.public void poppush(net.risingworld.api.objects.Player player, GuiModalWindow win)
The new window will become the 'next window'
player
- the player on whose screen to display the new window.win
- the new GuiModalWindow to display.public java.lang.Integer getItemId(net.risingworld.api.gui.GuiElement element)
element
- the GuiElement to look for.public void free()