1/*******************************************************************************
2 * Copyright 2011 See AUTHORS file.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *   http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 ******************************************************************************/
16
17package com.badlogic.gdx;
18
19import com.badlogic.gdx.utils.Clipboard;
20
21/** <p>
22 * An <code>Application</code> is the main entry point of your project. It sets up a window and rendering surface and manages the
23 * different aspects of your application, namely {@link Graphics}, {@link Audio}, {@link Input} and {@link Files}. Think of an
24 * Application being equivalent to Swing's <code>JFrame</code> or Android's <code>Activity</code>.
25 * </p>
26 *
27 * <p>
28 * An application can be an instance of any of the following:
29 * <ul>
30 * <li>a desktop application (see <code>JglfwApplication</code> found in gdx-backends-jglfw.jar)</li>
31 * <li>an Android application (see <code>AndroidApplication</code> found in gdx-backends-android.jar)</li>
32 * <li>a HTML5 application (see <code>GwtApplication</code> found in gdx-backends-gwt.jar)</li>
33 * <li>an iOS application (see <code>IOSApplication</code> found in gdx-backends-robovm.jar)</li>
34 * </ul>
35 * Each application class has it's own startup and initialization methods. Please refer to their documentation for more
36 * information.
37 * </p>
38 *
39 * <p>
40 * While game programmers are used to having a main loop, libgdx employs a different concept to accommodate the event based nature
41 * of Android applications a little more. You application logic must be implemented in a {@link ApplicationListener} which has
42 * methods that get called by the Application when the application is created, resumed, paused, disposed or rendered. As a
43 * developer you will simply implement the ApplicationListener interface and fill in the functionality accordingly. The
44 * ApplicationListener is provided to a concrete Application instance as a parameter to the constructor or another initialization
45 * method. Please refer to the documentation of the Application implementations for more information. Note that the
46 * ApplicationListener can be provided to any Application implementation. This means that you only need to write your program
47 * logic once and have it run on different platforms by passing it to a concrete Application implementation.
48 * </p>
49 *
50 * <p>
51 * The Application interface provides you with a set of modules for graphics, audio, input and file i/o.
52 * </p>
53 *
54 * <p>
55 * {@link Graphics} offers you various methods to output visuals to the screen. This is achieved via OpenGL ES 2.0 or 3.0
56 * depending on what's available an the platform. On the desktop the features of OpenGL ES 2.0 and 3.0 are emulated via desktop
57 * OpenGL. On Android the functionality of the Java OpenGL ES bindings is used.
58 * </p>
59 *
60 * <p>
61 * {@link Audio} offers you various methods to output and record sound and music. This is achieved via the Java Sound API on the
62 * desktop. On Android the Android media framework is used.
63 * </p>
64 *
65 * <p>
66 * {@link Input} offers you various methods to poll user input from the keyboard, touch screen, mouse and accelerometer.
67 * Additionally you can implement an {@link InputProcessor} and use it with {@link Input#setInputProcessor(InputProcessor)} to
68 * receive input events.
69 * </p>
70 *
71 * <p>
72 * {@link Files} offers you various methods to access internal and external files. An internal file is a file that is stored near
73 * your application. On Android internal files are equivalent to assets. On the desktop the classpath is first scanned for the
74 * specified file. If that fails then the root directory of your application is used for a look up. External files are resources
75 * you create in your application and write to an external storage. On Android external files reside on the SD-card, on the
76 * desktop external files are written to a users home directory. If you know what you are doing you can also specify absolute file
77 * names. Absolute filenames are not portable, so take great care when using this feature.
78 * </p>
79 *
80 * <p>
81 * {@link Net} offers you various methods to perform network operations, such as performing HTTP requests, or creating server and
82 * client sockets for more elaborate network programming.
83 * </p>
84 *
85 * <p>
86 * The <code>Application</code> also has a set of methods that you can use to query specific information such as the operating
87 * system the application is currently running on and so forth. This allows you to have operating system dependent code paths. It
88 * is however not recommended to use this facilities.
89 * </p>
90 *
91 * <p>
92 * The <code>Application</code> also has a simple logging method which will print to standard out on the desktop and to logcat on
93 * Android.
94 * </p>
95 *
96 * @author mzechner */
97public interface Application {
98	/** Enumeration of possible {@link Application} types
99	 *
100	 * @author mzechner */
101	public enum ApplicationType {
102		Android, Desktop, HeadlessDesktop, Applet, WebGL, iOS
103	}
104
105	public static final int LOG_NONE = 0;
106	public static final int LOG_DEBUG = 3;
107	public static final int LOG_INFO = 2;
108	public static final int LOG_ERROR = 1;
109
110	/** @return the {@link ApplicationListener} instance */
111	public ApplicationListener getApplicationListener ();
112
113	/** @return the {@link Graphics} instance */
114	public Graphics getGraphics ();
115
116	/** @return the {@link Audio} instance */
117	public Audio getAudio ();
118
119	/** @return the {@link Input} instance */
120	public Input getInput ();
121
122	/** @return the {@link Files} instance */
123	public Files getFiles ();
124
125	/** @return the {@link Net} instance */
126	public Net getNet ();
127
128	/** Logs a message to the console or logcat */
129	public void log (String tag, String message);
130
131	/** Logs a message to the console or logcat */
132	public void log (String tag, String message, Throwable exception);
133
134	/** Logs an error message to the console or logcat */
135	public void error (String tag, String message);
136
137	/** Logs an error message to the console or logcat */
138	public void error (String tag, String message, Throwable exception);
139
140	/** Logs a debug message to the console or logcat */
141	public void debug (String tag, String message);
142
143	/** Logs a debug message to the console or logcat */
144	public void debug (String tag, String message, Throwable exception);
145
146	/** Sets the log level. {@link #LOG_NONE} will mute all log output. {@link #LOG_ERROR} will only let error messages through.
147	 * {@link #LOG_INFO} will let all non-debug messages through, and {@link #LOG_DEBUG} will let all messages through.
148	 * @param logLevel {@link #LOG_NONE}, {@link #LOG_ERROR}, {@link #LOG_INFO}, {@link #LOG_DEBUG}. */
149	public void setLogLevel (int logLevel);
150
151	/** Gets the log level. */
152	public int getLogLevel ();
153
154	/** @return what {@link ApplicationType} this application has, e.g. Android or Desktop */
155	public ApplicationType getType ();
156
157	/** @return the Android API level on Android, the major OS version on iOS (5, 6, 7, ..), or 0 on the desktop. */
158	public int getVersion ();
159
160	/** @return the Java heap memory use in bytes */
161	public long getJavaHeap ();
162
163	/** @return the Native heap memory use in bytes */
164	public long getNativeHeap ();
165
166	/** Returns the {@link Preferences} instance of this Application. It can be used to store application settings across runs.
167	 * @param name the name of the preferences, must be useable as a file name.
168	 * @return the preferences. */
169	public Preferences getPreferences (String name);
170
171	public Clipboard getClipboard ();
172
173	/** Posts a {@link Runnable} on the main loop thread.
174	 *
175	 * @param runnable the runnable. */
176	public void postRunnable (Runnable runnable);
177
178	/** Schedule an exit from the application. On android, this will cause a call to pause() and dispose() some time in the future,
179	 * it will not immediately finish your application.
180	 * On iOS this should be avoided in production as it breaks Apples guidelines*/
181	public void exit ();
182
183	/** Adds a new {@link LifecycleListener} to the application. This can be used by extensions to hook into the lifecycle more
184	 * easily. The {@link ApplicationListener} methods are sufficient for application level development.
185	 * @param listener */
186	public void addLifecycleListener (LifecycleListener listener);
187
188	/** Removes the {@link LifecycleListener}.
189	 * @param listener */
190	public void removeLifecycleListener (LifecycleListener listener);
191}
192