From f7cf263b9dd3279840df622f8b1b8d8fdb9c84ec Mon Sep 17 00:00:00 2001 From: "nathan.sweet" Date: Wed, 3 Nov 2010 07:28:07 +0000 Subject: [PATCH] [added] Javadocs. --- .../badlogic/gdx/backends/lwjgl/LwjglApplet.java | 4 ++ .../gdx/backends/lwjgl/LwjglApplication.java | 3 ++ .../badlogic/gdx/backends/lwjgl/LwjglCanvas.java | 5 +++ .../gdx-twl/src/com/badlogic/gdx/twl/Layout.java | 19 +++++++++ .../twl/gdx-twl/src/com/badlogic/gdx/twl/TWL.java | 45 ++++++++++++++++++++-- gdx/src/com/badlogic/gdx/Game.java | 14 +++++++ gdx/src/com/badlogic/gdx/InputMultiplexer.java | 9 +++++ gdx/src/com/badlogic/gdx/Screen.java | 34 +++++++++++++--- 8 files changed, 123 insertions(+), 10 deletions(-) diff --git a/backends/gdx-backend-lwjgl/src/com/badlogic/gdx/backends/lwjgl/LwjglApplet.java b/backends/gdx-backend-lwjgl/src/com/badlogic/gdx/backends/lwjgl/LwjglApplet.java index 79b24dbac..5dc4704c3 100644 --- a/backends/gdx-backend-lwjgl/src/com/badlogic/gdx/backends/lwjgl/LwjglApplet.java +++ b/backends/gdx-backend-lwjgl/src/com/badlogic/gdx/backends/lwjgl/LwjglApplet.java @@ -7,6 +7,10 @@ import java.awt.Canvas; import com.badlogic.gdx.ApplicationListener; +/** + * An OpenGL surface in an applet. + * @author Nathan Sweet + */ public class LwjglApplet extends Applet { final Canvas canvas; LwjglApplication app; diff --git a/backends/gdx-backend-lwjgl/src/com/badlogic/gdx/backends/lwjgl/LwjglApplication.java b/backends/gdx-backend-lwjgl/src/com/badlogic/gdx/backends/lwjgl/LwjglApplication.java index 1d2c31317..067f2365a 100644 --- a/backends/gdx-backend-lwjgl/src/com/badlogic/gdx/backends/lwjgl/LwjglApplication.java +++ b/backends/gdx-backend-lwjgl/src/com/badlogic/gdx/backends/lwjgl/LwjglApplication.java @@ -16,6 +16,9 @@ import com.badlogic.gdx.Graphics; import com.badlogic.gdx.Input; import com.badlogic.gdx.utils.GdxRuntimeException; +/** + * An OpenGL surface fullscreen or in a lightweight window. + */ public class LwjglApplication implements Application { LwjglGraphics graphics; LwjglAudio audio; diff --git a/backends/gdx-backend-lwjgl/src/com/badlogic/gdx/backends/lwjgl/LwjglCanvas.java b/backends/gdx-backend-lwjgl/src/com/badlogic/gdx/backends/lwjgl/LwjglCanvas.java index 238cbaa4f..7dbdc8a4d 100644 --- a/backends/gdx-backend-lwjgl/src/com/badlogic/gdx/backends/lwjgl/LwjglCanvas.java +++ b/backends/gdx-backend-lwjgl/src/com/badlogic/gdx/backends/lwjgl/LwjglCanvas.java @@ -18,6 +18,11 @@ import com.badlogic.gdx.Graphics; import com.badlogic.gdx.Input; import com.badlogic.gdx.utils.GdxRuntimeException; +/** + * An OpenGL surface on an AWT Canvas, allowing OpenGL to be embedded in a Swing application. All OpenGL calls are done on the + * EDT. This is slightly less efficient then a dedicated thread, but greatly simplifies synchronization. + * @author Nathan Sweet + */ public class LwjglCanvas implements Application { final LwjglGraphics graphics; final LwjglAudio audio; diff --git a/extensions/twl/gdx-twl/src/com/badlogic/gdx/twl/Layout.java b/extensions/twl/gdx-twl/src/com/badlogic/gdx/twl/Layout.java index f77acee9f..e2e4ba762 100644 --- a/extensions/twl/gdx-twl/src/com/badlogic/gdx/twl/Layout.java +++ b/extensions/twl/gdx-twl/src/com/badlogic/gdx/twl/Layout.java @@ -4,6 +4,10 @@ package com.badlogic.gdx.twl; import de.matthiasmann.twl.DialogLayout; import de.matthiasmann.twl.Widget; +/** + * Adds convenience methods to {@link DialogLayout}. + * @author Nathan Sweet + */ public class Layout extends DialogLayout { public Layout () { setTheme(""); @@ -24,6 +28,9 @@ public class Layout extends DialogLayout { this.horizontal = horizontal; } + /** + * @param widgets Either {@link Widget} or {@link Integer} objects. Integers are used to specify the gap size. + */ public Group sequence (Object... widgets) { DialogLayout.Group dialogGroup = createSequentialGroup(); if (horizontal) @@ -33,6 +40,9 @@ public class Layout extends DialogLayout { return new Group(null, dialogGroup).add(widgets); } + /** + * @param widgets Either {@link Widget} or {@link Integer} objects. Integers are used to specify the gap size. + */ public Group parallel (Object... widgets) { DialogLayout.Group dialogGroup = createParallelGroup(); if (horizontal) @@ -51,18 +61,27 @@ public class Layout extends DialogLayout { this.dialogGroup = dialogGroup; } + /** + * @param widgets Either {@link Widget} or {@link Integer} objects. Integers are used to specify the gap size. + */ public Group sequence (Object... widgets) { DialogLayout.Group dialogGroup = createSequentialGroup(); this.dialogGroup.addGroup(dialogGroup); return new Group(this, dialogGroup).add(widgets); } + /** + * @param widgets Either {@link Widget} or {@link Integer} objects. Integers are used to specify the gap size. + */ public Group parallel (Object... widgets) { DialogLayout.Group dialogGroup = createParallelGroup(); this.dialogGroup.addGroup(dialogGroup); return new Group(this, dialogGroup).add(widgets); } + /** + * @param widgets Either {@link Widget} or {@link Integer} objects. Integers are used to specify the gap size. + */ public Group add (Object... widgets) { for (int i = 0, n = widgets.length; i < n; i++) { Object object = widgets[i]; diff --git a/extensions/twl/gdx-twl/src/com/badlogic/gdx/twl/TWL.java b/extensions/twl/gdx-twl/src/com/badlogic/gdx/twl/TWL.java index 4cfc0b8e3..525d35b45 100644 --- a/extensions/twl/gdx-twl/src/com/badlogic/gdx/twl/TWL.java +++ b/extensions/twl/gdx-twl/src/com/badlogic/gdx/twl/TWL.java @@ -12,6 +12,7 @@ import java.net.URLStreamHandler; import com.badlogic.gdx.Files.FileType; import com.badlogic.gdx.Gdx; import com.badlogic.gdx.Input; +import com.badlogic.gdx.InputMultiplexer; import com.badlogic.gdx.InputProcessor; import com.badlogic.gdx.files.FileHandle; import com.badlogic.gdx.twl.renderer.GdxRenderer; @@ -22,15 +23,38 @@ import de.matthiasmann.twl.GUI; import de.matthiasmann.twl.Widget; import de.matthiasmann.twl.theme.ThemeManager; +/** + * Convenience class for using TWL. This provides all the basics sufficient for most UIs. TWL can be used without this class if + * more complex configurations are required (eg, multiple GUI instances).
+ *
+ * This class provides a single {@link GUI} instance with a root pane set to a widget that takes up the whole screen. + * {@link #setWidget(Widget)} puts a widget into the root pane, making it easy to layout your widgets using the whole screen.
+ *
+ * This class is relatively heavyweight because it loads a TWL theme. Generally only one instance should be created for an entire + * application. Use {@link #setWidget(Widget)} and {@link #clear()} to change the widgets displayed on various application + * screens.
+ *
+ * This class implements {@link InputProcessor} and the input methods return true if TWL handled an event. Generally you will want + * to use {@link InputMultiplexer} to avoid dispatching events that TWL handled to your application.
+ *
+ * If an instance of this call will no longer be used, {@link #dispose()} must be called to release resources. + * @author Nathan Sweet + */ public class TWL implements InputProcessor { private final GdxRenderer renderer = new GdxRenderer(); private final GUI gui; + /** + * Creates a new TWL instance with the specified theme file. The specified widget is added to the root pane. + */ public TWL (String themeFile, FileType fileType, Widget widget) { this(themeFile, fileType); setWidget(widget); } + /** + * Creates a new TWL instance with the specified theme file. + */ public TWL (String themeFile, FileType fileType) { Widget root = new Widget() { protected void layout () { @@ -47,24 +71,32 @@ public class TWL implements InputProcessor { } } - public GdxRenderer getRenderer () { - return renderer; - } - + /** + * Returns the GUI instance, which is the root of the TWL UI hierachy and manages timing, inputs, etc. + */ public GUI getGUI () { return gui; } + /** + * Sets the widget in the GUI's root pane. By default the root pane takes up the whole screen. + */ public void setWidget (Widget widget) { Widget root = gui.getRootPane(); root.removeAllChildren(); root.add(widget); } + /** + * Removes all widgets from the GUI's root pane. This effectively means that no TWL UI will be drawn. + */ public void clear () { gui.getRootPane().removeAllChildren(); } + /** + * Draws the TWL UI. + */ public void render () { GUI gui = this.gui; int viewWidth = Gdx.graphics.getWidth(); @@ -174,6 +206,11 @@ public class TWL implements InputProcessor { return Event.KEY_NONE; } + /** + * Returns a URL to a theme file, which can be used with + * {@link ThemeManager#createThemeManager(URL, de.matthiasmann.twl.renderer.Renderer) ThemeManager} to create a theme for + * {@link GUI#applyTheme(ThemeManager)}. This is only needed if not using the TWL class make use of TWL. + */ static public URL getThemeURL (String themeFile, final FileType fileType) throws MalformedURLException { File file = new File(themeFile); final File themeRoot = file.getParentFile(); diff --git a/gdx/src/com/badlogic/gdx/Game.java b/gdx/src/com/badlogic/gdx/Game.java index e96e19a52..b3d0f0c73 100644 --- a/gdx/src/com/badlogic/gdx/Game.java +++ b/gdx/src/com/badlogic/gdx/Game.java @@ -1,6 +1,12 @@ package com.badlogic.gdx; +/** + * An {@link ApplicationListener} that delegates to a {@link Screen}. This allows an application to easily have multiple screens.
+ *
+ * Screens are not disposed automatically. You must handle whether you want to keep screens around or dispose of them when another + * screen is set. + */ public abstract class Game implements ApplicationListener { Screen screen; @@ -24,9 +30,17 @@ public abstract class Game implements ApplicationListener { if (screen != null) screen.resize(width, height); } + /** + * Sets the current screen. {@link Screen#hide()} is called on any old screen, and {@link Screen#show()} is called on the new + * screen. + */ public void setScreen (Screen screen) { if (this.screen != null) this.screen.hide(); this.screen = screen; screen.show(); } + + public Screen getScreen () { + return screen; + } } diff --git a/gdx/src/com/badlogic/gdx/InputMultiplexer.java b/gdx/src/com/badlogic/gdx/InputMultiplexer.java index 2c4c71baf..3d57cac8b 100644 --- a/gdx/src/com/badlogic/gdx/InputMultiplexer.java +++ b/gdx/src/com/badlogic/gdx/InputMultiplexer.java @@ -3,6 +3,11 @@ package com.badlogic.gdx; import java.util.ArrayList; +/** + * An {@link InputProcessor} that delegates to an ordered list of other InputProcessors. Delegation for an event stops if a + * processor returns true, which indicates that the event was handled. + * @author Nathan Sweet + */ public class InputMultiplexer implements InputProcessor { private ArrayList processors = new ArrayList(4); @@ -10,6 +15,10 @@ public class InputMultiplexer implements InputProcessor { processors.add(processor); } + public void removeProcessor (InputProcessor processor) { + processors.remove(processor); + } + public boolean keyDown (int keycode) { for (int i = 0, n = processors.size(); i < n; i++) if (processors.get(i).keyDown(keycode)) return true; diff --git a/gdx/src/com/badlogic/gdx/Screen.java b/gdx/src/com/badlogic/gdx/Screen.java index 01284d291..baeeff206 100644 --- a/gdx/src/com/badlogic/gdx/Screen.java +++ b/gdx/src/com/badlogic/gdx/Screen.java @@ -1,30 +1,52 @@ package com.badlogic.gdx; +/** + * Represents one of many application screens.
+ *
+ * Note that {@link #dispose()} is not called automatically. + * @see Game + */ public abstract class Screen { - public final Game game; - - public Screen (Game game) { - this.game = game; - } - + /** + * Called when the screen should render itself. + * @param delta The time in seconds since the last render. + */ public abstract void render (float delta); + /** + * @see ApplicationListener#resize(int, int) + */ public void resize (int width, int height) { } + /** + * Called when this screen becomes the current screen for a {@link Game}. + */ public void show () { } + /** + * Called when this screen is no longer the current screen for a {@link Game}. + */ public void hide () { } + /** + * @see ApplicationListener#pause() + */ public void pause () { } + /** + * @see ApplicationListener#resume() + */ public void resume () { } + /** + * Called when this screen should release all resources. + */ public void dispose () { } } -- 2.11.0