+ * + * A legacy banner Ads API. This has been replaced by more modern approaches mainly thru cn1libs. + *
+ *+ * Currently inner-active ads Network is supported + * please refer to + * inner-active + * for more information + *
+ */ +package com.codename1.ads; diff --git a/CodenameOne/src/com/codename1/analytics/package-info.java b/CodenameOne/src/com/codename1/analytics/package-info.java new file mode 100644 index 0000000000..e71c7fdb92 --- /dev/null +++ b/CodenameOne/src/com/codename1/analytics/package-info.java @@ -0,0 +1,11 @@ +/** + *+ * The analytics API allows tracking your mobile application usage in the field to give you real-time + * data on how your application is used. This API currently delegates to the Google analytics service. + *
+ *+ * Notice that analytics is automatically added GUI applications created by the old GUI builder, you only need + * to enable Analytics specifically by invoking the init method and the pages will be logged automatically. + *
+ */ +package com.codename1.analytics; diff --git a/CodenameOne/src/com/codename1/background/package-info.java b/CodenameOne/src/com/codename1/background/package-info.java new file mode 100644 index 0000000000..b31dcac3dd --- /dev/null +++ b/CodenameOne/src/com/codename1/background/package-info.java @@ -0,0 +1,7 @@ +/** + *Background fetch is a mechanism whereby an application is granted permission by the operating system to update its + * data periodically. At times of the native platform's choosing, an app that supports background fetch will be started + * up (in the background), and its {@link com.codename1.background.BackgroundFetch#performBackgroundFetch(long, + * com.codename1.util.Callback) } method will be called.
+ */ +package com.codename1.background; diff --git a/CodenameOne/src/com/codename1/capture/package-info.java b/CodenameOne/src/com/codename1/capture/package-info.java new file mode 100644 index 0000000000..d83f5b6231 --- /dev/null +++ b/CodenameOne/src/com/codename1/capture/package-info.java @@ -0,0 +1,11 @@ +/** + *+ * Package for capturing photos, audio or video from the camera/microphone. + *
+ *+ * The code below demonstrates capturing and playing back audio files using this API: + *
+ * + *
+ */
+package com.codename1.capture;
diff --git a/CodenameOne/src/com/codename1/charts/compat/package-info.java b/CodenameOne/src/com/codename1/charts/compat/package-info.java
new file mode 100644
index 0000000000..2c99784079
--- /dev/null
+++ b/CodenameOne/src/com/codename1/charts/compat/package-info.java
@@ -0,0 +1,4 @@
+/**
+ * This package contains compatibility classes for internal use
+ */
+package com.codename1.charts.compat;
diff --git a/CodenameOne/src/com/codename1/charts/models/package-info.java b/CodenameOne/src/com/codename1/charts/models/package-info.java
new file mode 100644
index 0000000000..45f3674034
--- /dev/null
+++ b/CodenameOne/src/com/codename1/charts/models/package-info.java
@@ -0,0 +1,4 @@
+/**
+ * Provides the classes that handle the data values (data model) to be used by displaying the charts.
+ */
+package com.codename1.charts.models;
diff --git a/CodenameOne/src/com/codename1/charts/package-info.java b/CodenameOne/src/com/codename1/charts/package-info.java
new file mode 100644
index 0000000000..a8fd169d2c
--- /dev/null
+++ b/CodenameOne/src/com/codename1/charts/package-info.java
@@ -0,0 +1,97 @@
+/**
+ *
+ * The charts package enables Codename One developers to add charts and
+ * visualizations to their apps without having to include external libraries or embedding web views.
+ * We also wanted to harness the new features in the graphics pipeline to maximize performance.
+ * Since the charts package makes use of 2D transformations and shapes, it requires some + * of the graphics features that are not yet available on all platforms. Currently the following + * platforms are supported: + *
+ *
+ * The com.codename1.charts package includes models and renderers for many
+ * different types of charts. It is also extensible so that you can add your own chart types if required.
+ * The following screen shots demonstrate a small sampling of the types of charts that can be
+ * created.
+ *
+ * 
+ *
+ * 
+ * 
+ * 
+ * 
+ * 
+ * 
+ * 
+ * 
+ * 
+ * 
+ *
+ * | + * | + * The above screenshots were taken from the + * ChartsDemo app. Y + * ou can start playing with this app by checking it out from our git repository. + * | + *
Adding a chart to your app involves four steps:
+ *com.codename1.charts.models package. Essentially, this
+ * is just where you add the data that you want to display.
+ * com.codename1.charts.renderers package. The renderer
+ * allows you to specify how the chart should look. E.g. the colors, fonts, styles, to use.
+ * com.codename1.charts.views package.
+ * You can check out the ChartsDemo + * app for specific examples, but here is a high level view of some code that creates a Pie Chart.
+ * + * + * + *+ * The charts package is derived work from the excellent open source + * aChartEngine API. + *
+ */ +package com.codename1.charts; diff --git a/CodenameOne/src/com/codename1/charts/renderers/package-info.java b/CodenameOne/src/com/codename1/charts/renderers/package-info.java new file mode 100644 index 0000000000..b967ac9ccc --- /dev/null +++ b/CodenameOne/src/com/codename1/charts/renderers/package-info.java @@ -0,0 +1,4 @@ +/** + * Provides renderer classes that keep the chart rendering / drawing styles. + */ +package com.codename1.charts.renderers; diff --git a/CodenameOne/src/com/codename1/charts/util/package-info.java b/CodenameOne/src/com/codename1/charts/util/package-info.java new file mode 100644 index 0000000000..218abf975c --- /dev/null +++ b/CodenameOne/src/com/codename1/charts/util/package-info.java @@ -0,0 +1,4 @@ +/** + * Utility classes that provide helper methods used by most of the other packages. + */ +package com.codename1.charts.util; diff --git a/CodenameOne/src/com/codename1/charts/views/package-info.java b/CodenameOne/src/com/codename1/charts/views/package-info.java new file mode 100644 index 0000000000..6c0fda0747 --- /dev/null +++ b/CodenameOne/src/com/codename1/charts/views/package-info.java @@ -0,0 +1,4 @@ +/** + * Provides the classes that handle the actual rendering / drawing of the charts, based on the provided model and renderer. + */ +package com.codename1.charts.views; diff --git a/CodenameOne/src/com/codename1/codescan/package-info.java b/CodenameOne/src/com/codename1/codescan/package-info.java new file mode 100644 index 0000000000..8f1822e75d --- /dev/null +++ b/CodenameOne/src/com/codename1/codescan/package-info.java @@ -0,0 +1,8 @@ +/** + *Deprecated!!: Please use the cn1-codescan + * library instead.
+ *+ * Bar/QR code scanning API, currently based on the zxing implementation + *
+ */ +package com.codename1.codescan; diff --git a/CodenameOne/src/com/codename1/components/package-info.java b/CodenameOne/src/com/codename1/components/package-info.java new file mode 100644 index 0000000000..20e520a7e2 --- /dev/null +++ b/CodenameOne/src/com/codename1/components/package-info.java @@ -0,0 +1,7 @@ +/** + *+ * Generic elaborate components that make use of both UI elements and storage. + * These are relatively high level components such as RSS reader, IO progress indication etc. + *
+ */ +package com.codename1.components; diff --git a/CodenameOne/src/com/codename1/contacts/package-info.java b/CodenameOne/src/com/codename1/contacts/package-info.java new file mode 100644 index 0000000000..1d34464a0a --- /dev/null +++ b/CodenameOne/src/com/codename1/contacts/package-info.java @@ -0,0 +1,24 @@ +/** + *+ * Provides access to the contacts list from the device address book + *
+ *+ * The contacts API provides us with the means to query the phone�s address book, delete elements from + * it and create new entries into it. + *
+ *+ * Notice that on some platforms this will prompt the user for permissions and the user might choose not + * to grant that permission. To detect whether this is the case you can invoke + * {@link com.codename1.Display#isContactsPermissionGranted()} after invoking the contact listing API. + * This can help you adapt your error message to the user. + *
+ *+ * The sample below demonstrates listing all the contacts within the device with their photos, notice that + * this API is very performance sensitive and should be invoked on a separate thread unlike most + * Codename One API's: + *
+ * + *
+ */
+package com.codename1.contacts;
diff --git a/CodenameOne/src/com/codename1/db/package-info.java b/CodenameOne/src/com/codename1/db/package-info.java
new file mode 100644
index 0000000000..99d877e093
--- /dev/null
+++ b/CodenameOne/src/com/codename1/db/package-info.java
@@ -0,0 +1,53 @@
+/**
+ * + * Most new devices contain one version of sqlite or another; sqlite is a very lightweight SQL database + * designed for embedding into devices. For portability we recommend avoiding SQL altogether since + * it is both fragmented between devices (different sqlite versions) and isn't supported on all devices. + *
+ * + *In general SQL seems overly complex for most embedded device programming tasks.
+ * + *SQLite is supported on iOS, Android, UWP (Universal Windows Platform), RIM, Desktop & JavaScript builds. However, + * the JavaScript + * version of SQL has been deprecated and isn't supported on all platforms.
+ *You will notice that at this time support is still missing from the Windows builds.
+ *The biggest issue with SQLite portability is in iOS. The SQLite version for most platforms is + * threadsafe and as a result very stable. However, the iOS version is not!
+ *This might not seem like a big deal normally, however if you forget to close a connection the GC might + * close it for you thus producing a crash. This is such a common occurrence that Codename One logs + * a warning when the GC collects a database resource on the simulator.
+ * + *SQL is pretty powerful and very well suited for common tabular data. The Codename One SQL + * API is similar in spirit to JDBC but considerably simpler since many of the abstractions of JDBC + * designed for pluggable database architecture make no sense for a local database.
+ * + *The {@link com.codename1.db.Database} API is a high level abstraction that allows you to open an + * arbitrary database file using syntax such as:
+ * + * + * + *Some SQLite apps ship with a "ready made" database. We allow you to replace the DB file by using the code:
+ * + * + * + *You can then use the {@link com.codename1.io.FileSystemStorage} class to write the content of your + * DB file into the path. Notice that it must be a valid SQLite file!
+ * + *This is very useful for applications that need to synchronize with a central server or applications that + * ship with a large database as part of their core product.
+ * + *Working with a database is pretty trivial, the application logic below can send arbitrary queries to the + * database and present the results in a {@link com.codename1.ui.table.Table}. You can probably integrate + * this code into your app as a debugging tool:
+ * + * + * + *
+ * 
+ */
+package com.codename1.db;
diff --git a/CodenameOne/src/com/codename1/facebook/package-info.java b/CodenameOne/src/com/codename1/facebook/package-info.java
new file mode 100644
index 0000000000..551731f908
--- /dev/null
+++ b/CodenameOne/src/com/codename1/facebook/package-info.java
@@ -0,0 +1,7 @@
+/**
+ * + * Legacy generic implementation of the Facebook API with simplified OAuth integration to allow social sharing. + * It is recommended to migrate to the new social package services + *
+ */ +package com.codename1.facebook; diff --git a/CodenameOne/src/com/codename1/facebook/ui/package-info.java b/CodenameOne/src/com/codename1/facebook/ui/package-info.java new file mode 100644 index 0000000000..4a505ad9bd --- /dev/null +++ b/CodenameOne/src/com/codename1/facebook/ui/package-info.java @@ -0,0 +1,6 @@ +/** + *+ * User interface for integrating with basic Facebook features currently mostly the Like button + *
+ */ +package com.codename1.facebook.ui; diff --git a/CodenameOne/src/com/codename1/impl/package-info.java b/CodenameOne/src/com/codename1/impl/package-info.java new file mode 100644 index 0000000000..5affca0bba --- /dev/null +++ b/CodenameOne/src/com/codename1/impl/package-info.java @@ -0,0 +1,14 @@ +/** + *+ * The implementation package should not be used by developers, it is an internal implementation detail + * which will break compatibility between major Codename One releases. The purpose of this package is to provide + * ISVs, vendors and operators with the ability to customize & enhance Codename One from within without + * breaking compatability with existing Codename One applications. + *
+ *+ * A vendor extension begins by extending the CodenameOneImplementation class and implementing the abstract + * methods within. To use this version of the implementation a user can use the Display class and link + * to a vendor JAR that doesn't include any portion of Codename One. + *
+ */ +package com.codename1.impl; diff --git a/CodenameOne/src/com/codename1/io/gzip/package-info.java b/CodenameOne/src/com/codename1/io/gzip/package-info.java new file mode 100644 index 0000000000..77be4f8304 --- /dev/null +++ b/CodenameOne/src/com/codename1/io/gzip/package-info.java @@ -0,0 +1,6 @@ +/** + *+ * gzip support based on https://github.com/ymnk/jzlib + *
+ */ +package com.codename1.io.gzip; diff --git a/CodenameOne/src/com/codename1/io/package-info.java b/CodenameOne/src/com/codename1/io/package-info.java new file mode 100644 index 0000000000..21bda66443 --- /dev/null +++ b/CodenameOne/src/com/codename1/io/package-info.java @@ -0,0 +1,712 @@ +/** + *+ * The IO package includes all of the main features related to storage and networking with the exception + * of {@link com.codename1.db SQL} & XML parsing. + *
+ * + *
+ * {@link com.codename1.io.Storage} is accessed via the Storage
+ * class. It is a flat filesystem like interface and contains the ability to list/delete and
+ * write to named storage entries.
+ *
+ * The {@link com.codename1.io.Storage} API also provides convenient methods to write objects to
+ * {@link com.codename1.io.Storage} and read them from {@link com.codename1.io.Storage} specifically
+ * readObject & writeObject.
+ * Notice that objects in {@link com.codename1.io.Storage} are deleted when an app is uninstalled but are
+ * retained between application updates.
+ *
+ * The sample code below demonstrates listing the content of the storage, adding/viewing and + * deleting entries within the storage: + *
+ * + * + * + *
+ * 
+ *
+ * + * {@link com.codename1.io.Storage} also offers a very simple API in the form of the + * {@link com.codename1.io.Preferences} + * class. The {@link com.codename1.io.Preferences} class allows developers to store simple variables, strings, + * numbers, booleans etc. in storage without writing any storage code. This is a common use case + * within applications e.g. you have a server token that you need to store you can store & read it like this: + *
+ * + * + * + *
+ * This gets somewhat confusing with primitive numbers e.g. if you use
+ * Preferences.set("primitiveLongValue", myLongNumber) then invoke
+ * Preferences.get("primitiveLongValue", 0) you might get an exception!
+ * This would happen because the value is physically a Long object but you are
+ * trying to get an Integer. The workaround is to remain consistent and use code
+ * like this Preferences.get("primitiveLongValue", (long)0).
+ *
+ * {@link com.codename1.io.FileSystemStorage} provides file system access. It maps to the underlying
+ * OS's file system API providing most of the common operations expected from a file API somewhat in
+ * the vain of java.io.File & java.io.FileInputStream e.g. opening,
+ * renaming, deleting etc.
+ *
+ * Notice that the file system API is somewhat platform specific in its behavior. All paths used the API + * should be absolute otherwise they are not guaranteed to work. + *
+ * + *
+ * The main reason java.io.File & java.io.FileInputStream
+ * weren't supported directly has a lot to do with the richness of those two API's. They effectively
+ * allow saving a file anywhere, however mobile devices are far more restrictive and don't allow
+ * apps to see/modify files that are owned by other apps.
+ *
+ * All paths in {@link com.codename1.io.FileSystemStorage} are absolute, this simplifies the issue of portability + * significantly since the concept of relativity and current working directory aren't very portable. + *
+ * + *
+ * All URL's use the / as their path separator we try to enforce this behavior even in
+ * Windows.
+ *
+ * Directories end with the / character and thus can be easily distinguished by their name.
+ *
+ * The {@link com.codename1.io.FileSystemStorage} API provides a getRoots() call to list the root
+ * directories of the file system (you can then "dig in" via the listFiles API). However,
+ * this is confusing and unintuitive for developers.
+ *
+ * To simplify the process of creating/reading files we added the getAppHomePath() method.
+ * This method allows us to obtain the path to a directory where files can be stored/read.
+ *
+ * We can use this directory to place an image to share as we did in the + * share sample. + *
+ * + *+ * Warning: A common Android hack is to write files to the SDCard storage to share + * them among apps. Android 4.x disabled the ability to write to arbitrary directories on the SDCard + * even when the appropriate permission was requested. + *
+ * + *
+ * A more advanced usage of the {@link com.codename1.io.FileSystemStorage} API can be a
+ * {@link com.codename1.io.FileSystemStorage} Tree:
+ *
+ *
+ * + * The question of storage vs. file system is often confusing for novice mobile developers. This embeds + * two separate questions:
+ *Why are there 2 API's where one would have worked?
+ *Which one should I pick?
+ *
+ * The main reasons for the 2 API's are technical. Many OS's provide 2 ways of accessing data
+ * specific to the app and this is reflected within the API. E.g. on Android the
+ * {@link com.codename1.io.FileSystemStorage} maps to API's such as java.io.FileInputStream
+ * whereas the {@link com.codename1.io.Storage} maps to Context.openFileInput().
+ *
+ * The secondary reason for the two API's is conceptual. {@link com.codename1.io.FileSystemStorage} is + * more powerful and in a sense provides more ways to fail, this is compounded by the complex + * on-device behavior of the API. {@link com.codename1.io.Storage} is designed to be friendlier to the + * uninitiated and more portable. + *
+ * + *
+ * You should pick {@link com.codename1.io.Storage} unless you have a specific requirement that prevents it.
+ * Some API's such as Capture expect a {@link com.codename1.io.FileSystemStorage} URI
+ * so in those cases this would also be a requirement.
+ *
+ * Another case where {@link com.codename1.io.FileSystemStorage} is beneficial is the case of hierarchy or
+ * native API usage. If you need a a directory structure or need to communicate with a native
+ * API the {@link com.codename1.io.FileSystemStorage} approach is usually easier.
+ * Warning: In some OS's the {@link com.codename1.io.FileSystemStorage} API can find the
+ * content of the {@link com.codename1.io.Storage} API. As one is implemented on top of the other. This is
+ * undocumented behavior that can change at any moment!
+ *
+ * One of the more common problems in Network programming is spawning a new thread to handle + * the network operations. In Codename One this is done seamlessly and becomes unessential + * thanks to the {@link com.codename1.io.NetworkManager}. + *
+ *+ * {@link com.codename1.io.NetworkManager} effectively alleviates the need for managing network threads by + * managing the complexity of network threading. The connection request class can be used to + * facilitate web service requests when coupled with the JSON/XML parsing capabilities. + *
+ *+ * To open a connection one needs to use a {@link com.codename1.io.ConnectionRequest} + * object, which has some similarities to the networking mechanism in JavaScript but is obviously somewhat more + * elaborate.
+ *You can send a get request to a URL using something like:
+ * + * + * + *+ * Notice that you can also implement the same thing and much more by avoiding the response + * listener code and instead overriding the methods of the {@link com.codename1.io.ConnectionRequest} class + * which offers multiple points to override e.g. + *
+ * + * + * + *
+ * Notice that overriding buildRequestBody(OutputStream) will only work for
+ * POST requests and will replace writing the arguments.
+ *
+ * Important: You don't need to close the output/input streams passed to the + * request methods. They are implicitly cleaned up. + *
+ * + *
+ * {@link com.codename1.io.NetworkManager} also supports synchronous requests which work in a similar
+ * way to Dialog via the invokeAndBlock call and thus don't block
+ * the EDT illegally. E.g. you can do something like this:
+ *
+ * Notice that in this case the addToQueueAndWait method returned after the
+ * connection completed. Also notice that this was totally legal to do on the EDT!
+ *
+ * By default the {@link com.codename1.io.NetworkManager} launches with a single network thread. This is + * sufficient for very simple applications that don't do too much networking but if you need to + * fetch many images concurrently and perform web services in parallel this might be an issue. + *
+ * + *+ * Warning: Once you increase the thread count there is no guarantee of order for your requests. + * Requests + * might not execute in the order with which you added them to the queue! + *
+ *To update the number of threads use:
+ * + * + * + *+ * All the callbacks in the {@code ConnectionRequest} occur on the network thread and + * not on the EDT! + *
+ * + *
+ * There is one exception to this rule which is the postResponse() method designed
+ * to update the UI after the networking code completes.
+ *
+ * Important: Never change the UI from a {@link com.codename1.io.ConnectionRequest}
+ * callback. You can either use a listener on the {@link com.codename1.io.ConnectionRequest}, use
+ * postResponse() (which is the only exception to this rule) or wrap your UI code with
+ * {@link com.codename1.ui.Display#callSerially(java.lang.Runnable)}.
+ *
+ * HTTP/S is a complex protocol that expects complex encoded data for its requests. Codename + * One tries to simplify and abstract most of these complexities behind common sense API's while + * still providing the full low level access you would expect from such an API. + *
+ * + *
+ * HTTP supports several "request methods", most commonly GET &
+ * POST but also a few others such as HEAD, PUT,
+ * DELETE etc.
+ *
Arguments in HTTP are passed differently between GET and POST
+ * methods. That is what the setPost method in Codename One determines, whether
+ * arguments added to the request should be placed using the GET semantics or the
+ * POST semantics.
So if we continue our example from above we can do something like this:
+ * + * + *
+ * This will implicitly add a get argument with the content of value. Notice that we
+ * don't really care what value is. It's implicitly HTTP encoded based on the get/post semantics.
+ * In this case it will use the get encoding since we passed false to the constructor.
+ *
A simpler implementation could do something like this:
+ * + * + * + *
+ * This would be almost identical but doesn't provide the convenience for switching back and
+ * forth between GET/POST and it isn't as fluent.
+ *
We can skip the encoding in complex cases where server code expects illegal HTTP
+ * characters (this happens) using the addArgumentNoEncoding method. We can
+ * also add multiple arguments with the same key using addArgumentArray.
+ *
+ * As we explained above, the setPost() method allows us to manipulate the
+ * get/post semantics of a request. This implicitly changes the POST
+ * or GET method submitted to the server.
+ *
+ * However, if you wish to have finer grained control over the submission process e.g. for making a
+ * HEAD request you can do this with code like:
+ *
+ * When communicating with HTTP servers we often pass data within headers mostly for + * authentication/authorization but also to convey various properties. + *
+ * + *+ * Some headers are builtin as direct API's e.g. content type is directly exposed within the API + * since it's a pretty common use case. We can set the content type of a post request using: + *
+ * + * + * + *+ * We can also add any arbitrary header type we want, e.g. a very common use case is basic + * authorization where the authorization header includes the Base64 encoded user/password + * combination as such: + *
+ * + * + * + * + *This can be quite tedious to do if you want all requests from your app to use this header. + * For this use case you can just use:
+ * + * + * + *
+ * Server returned headers are a bit trickier to read. We need to subclass the connection request
+ * and override the readHeaders method e.g.:
+ *
+ * Here we can extract the headers one by one to handle complex headers such as cookies, + * authentication etc. + *
+ * + *
+ * As you noticed above practically all of the methods in the ConectionRequest
+ * throw IOException. This allows you to avoid the try/catch
+ * semantics and just let the error propagate up the chain so it can be handled uniformly by
+ * the application.
+ *
There are two distinct placed where you can handle a networking error:
+ *The {@link com.codename1.io.ConnectionRequest} - by overriding callback methods
+ *The {@link com.codename1.io.NetworkManager} error handler
+ *+ * Notice that the {@link com.codename1.io.NetworkManager} error handler takes precedence thus allowing + * you to define a global policy for network error handling by consuming errors. + *
+ *+ * E.g. if I would like to block all network errors from showing anything to the user I could do + * something like this:
+ * + * + * + *+ * The error listener is invoked first with the {@link com.codename1.io.NetworkEvent} matching the + * error. Consuming the event prevents it from propagating further down the chain into the + * {@link com.codename1.io.ConnectionRequest} callbacks. + *
+ *+ * We can also override the error callbacks of the various types in the request e.g. in the case of a + * server error code we can do: + *
+ * + * + * + * + *
+ * Important: The error callback callback is triggered in the network thread!
+ * As a result it can't access the UI to show a Dialog or anything like that.
+ *
+ * Another approach is to use the setFailSilently(true) method on the
+ * {@link com.codename1.io.ConnectionRequest}. This will prevent the
+ * {@link com.codename1.io.ConnectionRequest} from displaying any errors to the user. It's a very
+ * powerful strategy if you use the synchronous version of the API's e.g.:
+ *
+ * This code will only work with the synchronous "AndWait" version of the method since the response + * code will take a while to return for the non-wait version. + *
+ * + *+ * When we get an error code that isn't 200/300 we ignore the result. This is problematic as the + * result might contain information we need. E.g. many webservices provide further XML/JSON + * based details describing the reason for the error code. + *
+ *
+ * Calling setReadResponseForErrors(true) will trigger a mode where even errors
+ * will receive the readResponse callback with the error stream. This also means
+ * that API's like getData and the listener API's will also work correctly in
+ * case of error.
+ *
+ * Gzip is a very common compression format based on the lz algorithm, it's used by web servers + * around the world to compress data. + *
+ * + *+ * Codename One supports {@link com.codename1.io.gzip.GZIPInputStream} and + * {@link com.codename1.io.gzip.GZIPOutputStream}, which allow you to compress data + * seamlessly into a stream and extract compressed data from a stream. This is very useful and + * can be applied to every arbitrary stream. + *
+ * + *
+ * Codename One also features a {@link com.codename1.io.gzip.GZConnectionRequest}, which
+ * will automatically unzip an HTTP response if it is indeed gzipped. Notice that some devices (iOS)
+ * always request gzip'ed data and always decompress it for us, however in the case of iOS it
+ * doesn't remove the gziped header. The GZConnectionRequest is aware of such
+ * behaviors so its better to use that when connecting to the network (if applicable).
+ *
+ * By default GZConnectionRequest doesn't request gzipped data (only unzips it
+ * when its received) but its pretty easy to do so just add the HTTP header
+ * Accept-Encoding: gzip e.g.:
+ *
Do the rest as usual and you should have smaller responses from the servers.
+ * + *+ * {@link com.codename1.io.MultipartRequest} tries to simplify the process of uploading a file from + * the local device to a remote server. + *
+ * + *
+ * You can always submit data in the buildRequestBody but this is flaky and has
+ * some limitations in terms of devices/size allowed. HTTP standardized file upload capabilities
+ * thru the multipart request protocol, this is implemented by countless servers and is well
+ * documented. Codename One supports this out of the box.
+ *
+ * Since we assume most developers reading this will be familiar with Java here is the way to + * implement the multipart upload in the servlet API. + *
+ * + * + * + *+ * {@link com.codename1.io.MultipartRequest} is a {@link com.codename1.io.ConnectionRequest} + * most stuff you expect from there should work. Even addArgument etc. + *
+ * + * + *Codename One has several built in parsers for JSON, XML, CSV & Properties formats. You can + * use those parsers to read data from the Internet or data that is shipping with your product. E.g. use the + * CSV data to setup default values for your application.
+ * + *+ * All our parsers are designed with simplicity and small distribution size; they don't validate and will fail + * in odd ways when faced with broken data. The main logic behind this is that validation takes up CPU + * time on the device where CPU is a precious resource. + *
+ * + *+ * CSV is probably the easiest to use, the "Comma Separated Values" format is just a list of values + * separated by commas (or some other character) with new lines to indicate another row in the table. + * These usually map well to an Excel spreadsheet or database table and are supported by default in all + * spreadsheets. + *
+ * + *+ * To parse a CSV just use the + * CSVParser class as such: + *
+ * + * + *
+ *
+ *
+ * + * The data contains a two dimensional array of the CSV content. You can change the delimiter character + * by using the {@code CSVParser} constructor that accepts a character. + *
+ * + *+ * IMPORTANT: Notice that we used {@link com.codename1.io.CharArrayReader} for + * this sample. Normally you would want to use {@link java.util.InputStreamReader} for real world data. + *
+ * + *+ * The JSON ("Java Script Object Notation") format is popular on the web for passing values to/from + * webservices since it works so well with JavaScript. Parsing JSON is just as easy but has two + * different variations. You can use the + * {@link com.codename1.io.JSONParser} class to build a tree of the JSON data as such: + *
+ * + * + * + *+ * The response is a {@code Map} containing a nested hierarchy of {@code Collection} ({@code java.util.List}), + * Strings and numbers to represent the content of the submitted JSON. To extract the data from a specific + * path just iterate the {@code Map} keys and recurs into it. + *
+ * + *+ * The sample below uses results from an API of ice and fire + * that queries structured data about the "Song Of Ice & Fire" book series. Here is a sample result + * returned from the API for the query + * http://www.anapioficeandfire.com/api/characters?page=5&pageSize=3: + *
+ * + * + * + *+ * We will place that into a file named "anapioficeandfire.json" in the src directory to make the next + * sample simpler: + *
+ * + * + * + *
+ *
+ * + * Tip: The structure of the returned map is sometimes unintuitive when looking at the raw JSON. The easiest + * thing to do is set a breakpoint on the method and use the inspect variables capability of your IDE to + * inspect the returned element hierarchy while writing the code to extract that data + *
+ * + * + *+ * An alternative approach is to use the static data parse() method of the {@code JSONParser} class and + * implement a callback parser e.g.: {@code JSONParser.parse(reader, callback);} + *
+ * + *+ * Notice that a static version of the method is used! The callback object is an instance of the + * {@code JSONParseCallback} interface, which includes multiple methods. These methods are invoked + * by the parser to indicate internal parser states, this is similar to the way traditional XML SAX event + * parsers work. + *
+ * + *+ * The {@link com.codename1.xml.XMLParser} started its life as an HTML parser built for displaying + * mobile HTML. That usage has since been deprecated but the parser can still parse many HTML + * pages and is very "loose" in terms of verification. This is both good and bad as the parser will work + * with invalid data without complaining. + *
+ * + *+ * The simplest usage of {@link com.codename1.xml.XMLParser} looks a bit like this: + *
+ * + * + * + *+ * The {@link com.codename1.xml.Element} contains children and attributes. It represents a tag within the + * XML document and even the root document itself. You can iterate over the XML tree to extract the + * data from within the XML file. + *
+ * + *+ * We have a great sample of working with {@code XMLParser} in the + * {@link com.codename1.ui.tree.Tree} class. + *
+ * + *+ * Codename One ships with support to a subset of XPath processing, you can read more about it in + * the {@link com.codename1.processing processing package docs}. + *
+ * + *+ * Codename One provides the {@link com.codename1.io.Externalizable} interface, which is similar + * to the Java SE {@link com.codename1.io.Externalizable} interface. + * This interface allows an object to declare itself as {@link com.codename1.io.Externalizable} for + * serialization (so an object can be stored in a file/storage or sent over the network). However, due to the + * lack of reflection and use of obfuscation these objects must be registered with the + * {@link com.codename1.io.Util} class. + *
+ * + *+ * Codename One doesn't support the Java SE Serialization API due to the size issues and + * complexities related to obfuscation. + *
+ * + *
+ * The major objects that are supported by default in the Codename One
+ * {@link com.codename1.io.Externalizable} are:
+ * String, Collection, Map, ArrayList,
+ * HashMap, Vector, Hashtable,
+ * Integer, Double, Float, Byte,
+ * Short, Long, Character, Boolean,
+ * Object[], byte[], int[], float[],
+ * long[], double[].
+ *
Externalizing an object such as h below should work just fine:
+ * + * + * + *
+ * However, notice that some things aren't polymorphic e.g. if we will externalize a
+ * String[] we will get back an Object[] since String
+ * arrays aren't detected by the implementation.
+ *
+ * Important: The externalization process caches objects so the app will seem to + * work and only fail on restart! + *
+ * + *
+ * Implementing the {@link com.codename1.io.Externalizable} interface is only important when we
+ * want to store a proprietary object. In this case we must register the object with the
+ * com.codename1.io.Util class so the externalization algorithm will be able to
+ * recognize it by name by invoking:
+ *
+ * You should do this early on in the app e.g. in the init(Object) but you shouldn't do
+ * it in a static initializer within the object as that might never be invoked!
+ *
+ * An {@link com.codename1.io.Externalizable} object must have a + * default public constructor and must implement the following 4 methods: + *
+ * + * + *
+ * The getVersion() method returns the current version of the object allowing the
+ * stored data to change its structure in the future (the version is then passed when internalizing
+ * the object). The object id is a String uniquely representing the object;
+ * it usually corresponds to the class name (in the example above the Unique Name should be
+ * MyClass).
+ *
+ * Warning: It's a common mistake to use getClass().getName()
+ * to implement getObjectId() and it would seem to work in the
+ * simulator. This isn't the case though!
+ * Since devices obfuscate the class names this becomes a problem as data is stored in a random
+ * name that changes with every release.
+ *
+ * Developers need to write the data of the object in the externalize method using the methods in the + * data output stream and read the data of the object in the internalize method e.g.: + *
+ * + * + * + *+ * Since strings might be null sometimes we also included convenience methods to implement such + * externalization. This effectively writes a boolean before writing the UTF to indicate whether the string + * is null: + *
+ * + * + * + *
+ * Assuming we added a new date field to the object we can do the following. Notice that a
+ * Date is really a long value in Java that can be null.
+ * For completeness the full class is presented below:
Notice that we only need to check for compatibility during the reading process as the writing + * process always writes the latest version of the data.
+ */ +package com.codename1.io; diff --git a/CodenameOne/src/com/codename1/io/rest/package-info.java b/CodenameOne/src/com/codename1/io/rest/package-info.java new file mode 100644 index 0000000000..69aa54423e --- /dev/null +++ b/CodenameOne/src/com/codename1/io/rest/package-info.java @@ -0,0 +1,8 @@ +/** + *+ * A builder pattern based API to make REST requests with a terse API. These mask the parsing, networking + * and error handling behind one simplified call. + *
+ */ +package com.codename1.io.rest; diff --git a/CodenameOne/src/com/codename1/io/services/package-info.java b/CodenameOne/src/com/codename1/io/services/package-info.java new file mode 100644 index 0000000000..3c6ffaf96d --- /dev/null +++ b/CodenameOne/src/com/codename1/io/services/package-info.java @@ -0,0 +1,6 @@ +/** + *+ * Default WebService implementations + *
+ */ +package com.codename1.io.services; diff --git a/CodenameOne/src/com/codename1/io/tar/package-info.java b/CodenameOne/src/com/codename1/io/tar/package-info.java new file mode 100644 index 0000000000..0fa6712962 --- /dev/null +++ b/CodenameOne/src/com/codename1/io/tar/package-info.java @@ -0,0 +1,9 @@ +/** + *+ * Tar support allowing us to package multiple separate files into a single package which is useful in supporting + * hierarchies in a portable way. + * This is based on the work contributed in + * Issue 754. + *
+ */ +package com.codename1.io.tar; diff --git a/CodenameOne/src/com/codename1/javascript/package-info.java b/CodenameOne/src/com/codename1/javascript/package-info.java new file mode 100644 index 0000000000..94257d85d5 --- /dev/null +++ b/CodenameOne/src/com/codename1/javascript/package-info.java @@ -0,0 +1,723 @@ +/* + * Copyright (c) 2012, Steve Hannah/Codename One and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Codename One designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Codename One through http://www.codenameone.com/ if you + * need additional information or have any questions. +*/ + +/** + *NOTE: The {@link com.codename1.javascript } package is now deprecated. The preferred method of + * Java/Javascript interop is to use {@link BrowserComponent#execute(java.lang.String) }, {@link + * BrowserComponent#execute(java.lang.String, com.codename1.util.SuccessCallback) }, + * {@link BrowserComponent#executeAndWait(java.lang.String) }, etc.. as these work asynchronously (except in the + * XXXAndWait() variants, which use invokeAndBlock() to make the calls synchronously.
+ * + *The Codename One JS Bridge package includes classes that facilitate the + * interaction between Java and Javascript in a Codename One application. + * It allows both Java to Javascript communication and the reverse via a + * mechanism similar to the one employed by Phone Gap/Apache Cordova.
+ * + *The bridge will only run on platforms that include a native browser component. This includes iOS, + * Android, Windows, Desktop & JavaScript at this time.
+ * + * + *The {@link com.codename1.javascript.JavascriptContext} class lays the foundation by enabling you to call + * Javascript code directly from Java. It provides automatic type conversion + * between Java and Javascript types as follows:
+ * + *| Java Type | + *Javascript Type + * |
|---|---|
| String | + *String | + *
| Double/Integer/Float/Long | + *Number | + *
| Boolean | + *Boolean | + *
| JSObject | + *Object | + *
| null | + *null | + *
| Other | + *Not Allowed | + *
| Javascript Type | + *Java Type | + *
|---|---|
| Number | + *Double | + *
| String | + *String | + *
| Boolean | + *Boolean | + *
| Object | + *JSObject | + *
| Function | + *JSObject | + *
| Array | + *JSObject | + *
| null | + *null | + *
| undefined | + *null | + *
+ * Note that this conversion table is more verbose than necessary, since Javascript functions + * and arrays are, in fact Objects themselves, so those rows are redundant. All Javascript + * objects are converted to {@link com.codename1.javascript.JSObject}s. + *
+ * + *In order to start interacting with a Javascript environment, you need to create + * a WebBrowser and load a page. Then inside the WebBrowser's onLoad() handler, you + * can create a JavascriptContext on the internal BrowserComponent object:
+ * + * + * + *The {@link com.codename1.javascript.JavascriptContext#get(String)} method is used to get values from Javascript. + * It takes an arbitrary Javascript expression, executes it, and returns the + * result, after converting it to the corresponding Java type. E.g. if the result + * is a String, it will return a String and if it is a Number it will return a + * java Double object. If the result is an Object, it will return a {@link com.codename1.javascript.JSObject}.
+ * + *The following is a simple example that retrieves the document content, which + * is a string:
+ * + * + * + *If you run this example in the simulator, you'll see something like the following:
+ * + *+ *
+ * Note: You don't see the WebBrowser in the background here due to a bug in the simulator. + * If you run this example on a device, you will see the WebBrowser component in the background.
+ * + *As mentioned in the conversion table above, numeric values are automatically + * converted to java.lang.Double objects. The following example, returns the width and height + * properties of the window for use in Java.
+ * + * + * + *The result, when run in the simulator would be something like:
+ * + *+ *
The previous examples involved only primitive return values. The {@link com.codename1.javascript.JavascriptContext} + * abstraction, + * in these cases, doesn't offer a whole lot of added-value over just using the + * BrowserComponent.executeJavascriptAndReturnString() + * method. The real value is when we are dealing with objects.
+ *The following example obtains a reference to the window object and wraps it in a
+ * proxy {@link com.codename1.javascript.JSObject} class so that we can work directly with the window object:
This code produces the exact same result as the previous example. The difference + * is the intermediary step of wrapping the window object in a {@link com.codename1.javascript.JSObject}, and + * obtaining the outerHeight and outerWidth properties directly via that proxy object.
+ * + *You can obtain a {@link com.codename1.javascript.JSObject} proxy for any Javascript object, even ones that you create + * on the fly. The following example creates an anonymous object with some keys and values + * and uses a {@link com.codename1.javascript.JSObject} proxy to interact with this object from Java.
+ * + * + * + *The result is as follows:
+ * + *+ *
See Working With Objects for more information + * about working with the {@link com.codename1.javascript.JSObject} class.
+ * + *In Javascript, functions and arrays are just objects, so these are also encapsulated as {@link + * com.codename1.javascript.JSObject} + * proxies. See Working with Arrays and + * Workin with Functions for more details on how to work + * with these values via the {@link com.codename1.javascript.JSObject} interface.
+ * + *Just as you can get values from Javascript using {@link com.codename1.javascript.JavascriptContext}'s get() method, + * you can + * also set values via {@link com.codename1.javascript.JavascriptContext#set(String,Object)}.
+ * + *The following is a simple example that sets the location, and causes it to redirect to + * a different page:
+ * + * + * + * + *If you run this example, you should see your browser display the Codename One website after + * a redirect.
+ *+ *
The previous example showed us setting a primitive String value. You can do the same with other + * primitives like numbers and booleans, but you can also set Object values using the set() method. + *
+ * + *The following example creates an anonymous Javascript object, wraps it in a {@link com.codename1.javascript.JSObject} + * proxy, + * sets some values on it, then sets the object as a property of the top-level window object.
+ * + * + * + *As a result, you should see the following content set as the body of the HTML page in the + * WebBrowser. Note that we can refer to the "steve" object that we just set directly/globally + * because the "window" object's properties are always available directly through the global + * namespace in Javascript.
+ *+ *
Previously examples showed how to obtain a {@link com.codename1.javascript.JSObject} proxy to a Javascript object. + * There are 4 ways to get a {@link com.codename1.javascript.JSObject}:
+ *JSObject obj = (JSObject)ctx.get("{}");JSObject obj = (JSObject)ctx.get("window.location");
+ * JSObject obj = (JSObject)ctx.get("document.getElementById('mydiv')")
+ * JSObject obj = (JSObject)otherObj.get("aPropertyThatIsAnObject")
+ * {@link com.codename1.javascript.JSObject}s are essentially just proxies around a Javascript object. Any calls to + * retrieve + * properties from a {@link com.codename1.javascript.JSObject} are just sent directly to the Javascript context, and + * the result + * returned. The {@link com.codename1.javascript.JSObject} object doesn't store copies the javascript object's + * properties. It just + * retrieves them as they are required via the {@link com.codename1.javascript.JSObject#get(String)} method.
+ * + *You can always retrieve the properties of an object using the {@link com.codename1.javascript.JSObject#get(String)} + * method. It takes the name of the property + * as a parameter, and returns its value, converted to the appropriate Java type. (e.g. if it is a String, + * it returns a String, if it is a number it returns a Double, and if it is an Object, it returns an object.
+ * + *E.g.
+ * + *
+ * String name = (String)obj.get("name");
+ * Double age = (Double)obj.get("age");
+ *
+ *
+ * Is equivalent to the following javascript:
+ *
+ *
+ * var name = obj.name;
+ * var age = obj.age;
+ *
+ *
+ * Assuming that the obj variable in Java is a proxy for the same obj variable
+ * in the javascript example.
+ *
Often, in Javascript, an object contains a heirarchy of nested child objects. E.g.
+ * + *
+ * var obj = {
+ * name : 'Steve',
+ * position : {
+ * x : 100,
+ * y : 105,
+ * z : -25
+ * }
+ * }
+ *
+ *
In this case you may want to obtain the x coordinate of the nested position object. {@link JSObject}
+ * allows
+ * you to use the dot '.' notation for referencing sub-properties like this. E.g.
+ *
+ *
+ * Double x = (Double)obj.get("position.x")
+ *
This feature raises the issue of how, then, to access properties that contain a '.' in its name. E.g.
+ *
+ * var obj = {
+ * name : 'Steve',
+ * position : {
+ * x : 100,
+ * y : 105,
+ * z : -25
+ * },
+ * 'position.x' : 200
+ * }
+ *
+ *
In this example there is a top-level property named 'position.x' as well as a property at the component address position.x. + * This is a contrived example that is meant to be somewhat confusing in order to demonstrate how to differentiate + * between requests for properties in the child object heirarchy and top-level properties that happen to + * include a '.' in the property name.
+ * + *We can force the retrieval of a top-level property by wrapping the key in single quotes:
+ *
+ * Double x1 = (Double)obj.get("'position.x'")
+ *
This would return
+ *
+ * Double x2 = (Double)obj.get("position.x")
+ *
Would return
+ *
The {@link com.codename1.javascript.JSObject#set(String,Object)} method works the same as the {@link + * com.codename1.javascript.JavascriptContext#set(String,Object)} method except that it treats the local + * object as the root node. It allows you to easily set properties on the object. Values set here should + * be provided using Java values as they will automatically be converted to the appropriate associated Javascript + * type. If you are setting an Object as a value, then you'll need to set it as a {@link + * com.codename1.javascript.JSObject} and not a string + * representation of the object. This is because Strings will just be converted to Javascript strings.
+ * + *Properties set via the {@link com.codename1.javascript.JSObject#set(String,Object)} method modify the underlying + * Javascript object directly so that the change + * is immediately effective inside the javascript environment. + *
+ *Just as with the {@link com.codename1.javascript.JSObject#get(String)} method, you can set the values of direct + * properties or nested properties using + * the dot '.' notation. And just like {@link com.codename1.javascript.JSObject#get(String)}, you can force setting a + * direct property in cases where the property + * name includes a '.', by wrapping the key inside single quotes. + * + *
+ *E.g.:
+ *
+ * // Create a team object , and leave city null for now.
+ * JSObject blueJays = (JSObject)ctx.get("{name : 'Blue Jays', city : null}");
+ *
+ * // Create a city object and leave country null for now.
+ * JSObject toronto = (JSObject)ctx.get("{name : 'Toronto', country : null}");
+ *
+ * // Create a country object
+ * JSObject canada = (JSObject)ctx.get("{name : 'Canada'}");
+ *
+ * // Set the team's city to toronto
+ * blueJays.set("city", toronto);
+ *
+ * // Set toronto's country to canada
+ * toronto.set("country", canada);
+ *
+ * // Retrieve the name of the country where the blue jays play
+ * String countryName = (String)blueJays.get("city.country.name");
+ * // Should contain "Canada"
+ *
+ * // Change the name of Canada to "Canuck land" using nested
+ * // dot notation on the blueJays object.
+ *
+ * blueJays.set("city.country.name", "Canuck land");
+ *
+ * String blueJaysCountry = (String)blueJays.get("city.country.name");
+ * String torontoCountry = (String)tornoto.get("country.name");
+ * String canadaName = (String)canada.get("name");
+ *
+ * //Note that all of these should be equal and contain "Canuck land"
+ *
+ *
The {@link com.codename1.javascript.JSObject#call(String,Object)} method allows you to call javascript methods that + * are members of the underlying object. It arguments are passed as an + * Object[] array. These will be automatically converted from the Java type to the corresponding + * Javascript type. Java type conversion are the same as using the {@link + * com.codename1.javascript.JavascriptContext#set(String,Object)} method. + *
+ * + *The following example shows an object with a simple add() method
+ * that just adds two numbers together:
+ * JSObject obj = (JSObject)ctx.get("{ add : function(a,b){ return a+b;}}");
+ * Double result = (Double)obj.call("add",
+ * new Object[]{new Integer(1), new Integer(3)}
+ * );
+ *
+ * // Result should be 4.0
+ *
+ *
In javascript, arrays are just objects that include a special ability to be iterated. You can use the alternate + * version of {@link com.codename1.javascript.JSObject#get(int)} which takes an int as a parameter to + * retrieve the elements of an array.
+ * + *For example, consider the following javascript object:
+ *
+ * var obj = {
+ * name : 'Blue Jays',
+ * players : [
+ * { name : 'George Bell', age : 31},
+ * { name : 'Tony Fernandez', age : 34},
+ * { name : 'Lloyd Moseby', age : 29}
+ * ]
+ * }
+ *
+ *
+ *
Then assuming we have a {@link com.codename1.javascript.JSObject} proxy for this object, we could loop through the + * players + * array and output the name and age of each player as follows:
+ * + *
+ * JObject players = (JObject)obj.get("players");
+ * int len = ((Double)players.get("length")).intValue();
+ * for ( int i=0; i<len; i++){
+ * JSObject player = (JSObject)players.get(i);
+ * Log.p("Name : "+player.get("name")+" age : "+player.get("age"));
+ * }
+ *
+ *
So far, our examples have been limited to Java calling into Javascript. However, it may be + * useful to be able to also go the other way: call java methods from Javascript. Some applications + * of this might include:
+ *The Codename One JS bridge supports javascript to java method calling by way of the {@link + * com.codename1.javascript.JSFunction} interface + * and the {@link com.codename1.javascript.JSObject#set(String,Object)} methods on the {@link + * com.codename1.javascript.JSObject} class. You can implement a {@link com.codename1.javascript.JSFunction} + * object and register it as a callback with a {@link com.codename1.javascript.JSObject}, then you will be able to + * execute this object's apply method via a Javascript proxy.
+ * + *As an example, let's implement a simple logging function:
+ * + *
+ * JSObject logger = (JSObject)ctx.get("{}");
+ * logger.set("log", new JSFunction(){
+ *
+ * public void apply(JSObject self, Object[] args) {
+ * String msg = (String)args[0];
+ * Log.p("[Javascript Logger] "+msg);
+ * }
+ *
+ * });
+ *
+ * ctx.set("window.logger", logger);
+ *
+ *
+ * c.executeAndReturnString("logger.log('This is a test message');");
+ *
+ *
If you execute this code in the simulator, you'll see the following output in the console:
+ * + *[EDT] 0:0:0,0 - [Javascript Logger] This is a test message+ * + *
Running it on a device will yield similar output in the device log file.
+ * + *Let's step through this code to see what is happening. First we create a new, empty javascript object + * and wrap it in a JSObject proxy. Then we use the {@link com.codename1.javascript.JSObject}'s {@link + * com.codename1.javascript.JSObject#set(String,Object)} method to add an anonymous {@link + * com.codename1.javascript.JSFunction} + * object to it with the propery of "log". This step registers a method proxy on the Javascript side that acts just + * like a normal javascript method, but which actually triggers the {@link com.codename1.javascript.JSFunction}'s + * {@link com.codename1.javascript.JSFunction#apply(JSObject,Object[])} method.
+ * + *We then set this logger object to the global javascript scope by making it a direct child
+ * of the window object. Finally we issue a Javascript method call to logger.log(). This
+ * is what effectively calls the apply() method on our {@link com.codename1.javascript.JSFunction} object.
JSFunction callbacks are executed asynchronously so as to prevent deadlocks. This means that you + * cannot + * return a value from this method using a return statement (hence the reason why the interface definition for {@link + * com.codename1.javascript.JSFunction#apply(JSObject,Object[])} is void. + *
+ *If you want to return a value back to Javascript, then you'll need to do it by providing a + * callback function as one of the parameters, and call this callback method from inside the {@link + * com.codename1.javascript.JSFunction#apply(JSObject,Object[])} + * method upon completion.
+ * + *Since {@link com.codename1.javascript.JSFunction} callbacks are executed asynchronously, if you want to be able to + * return a result back to Javascript, you will + * need to do this via a Javascript callback. This is quite a common pattern in Javascript since it is single threaded + * and relies + * upon non-blocking patterns.
+ * + *As an example, let's create a {@link com.codename1.javascript.JSFunction} callback that adds two numbers together and + * returns the result to Javascript via a callback:
+ * + *First we will create the {@link com.codename1.javascript.JSFunction} object to perform the addition, as follows:
+ *
+ * WebBrowser b = new WebBrowser(){
+ * protected void onLoad(String url){
+ * JSObject window = (JSObject)ctx.get("window");
+ * window.set("addAsync", new JSFunction(){
+ *
+ * public void apply(JSObject self, final Object[] args) {
+ * Double a = (Double)args[0];
+ * Double b = (Double)args[1];
+ * JSObject callback = (JSObject)args[2];
+ *
+ * double result = a.doubleValue() + b.doubleValue();
+ * callback.call(new Object[]{new Double(result)});
+ *
+ * }
+ *
+ * });
+ * }
+ * };
+ *
+ * b.setURL("jar:///ca/weblite/codename1/tests/AddAsync.html");
+ *
+ *
In this snippet, we start by obtaining a reference to the "window" object. We then add a method to this object named + * "addAsync". This method is a {@link com.codename1.javascript.JSFunction} + * object that we implement inline. The apply() method of the {@link com.codename1.javascript.JSFunction} object is the + * Java method that will be executed when the addAsync method is called + * from Javascript. In this case the addAsync method expects three parameters:
+ *Notice that all numerical arguments are converted to Java Double objects, and the callback function is converted to a + * {@link com.codename1.javascript.JSObject} object. Also notice the use + * of callback.call(), which just calls the callback as a function itself. With this variant of + * the call() method, + * the window object is used as this. Notice also that we pass the result inside an + * Object[] array. This array will be expanded to + * the direct javascript function parameters. (i.e. it will not pass an array as the parameter to the javascript + * method, the array elements are extracted + * and passed individually.
+ * + * + *Now, let's look at the HTML page contents for our example:
+ *
+ * <!DOCTYPE html>
+ * <html>
+ * <head>
+ * <title>Addition Example</title>
+ * </head>
+ * <body>
+ * <div>Addition Example</div>
+ * <p><input type="text" size="4" id="input1"/> +
+ * <input type="text" size="4" id="input2"/> =
+ * <span id="result"></span>
+ * </p>
+ * <p><button id="calculate">Calculate</button></p>
+ * <script src="AddAsync.js"></script>
+ * </body>
+ * </html>
+ *
+ *
Our HTML simply includes two text fields (to input the values to be added together), a button to initiate the + * calculation, + * and a <span> tag where the result will be placed when the calculation is complete.
+ *Finally it includes the AddAsync.js Javascript file (which is placed in the same directory as the AddAsync.html file. + * Its + * contents are as follows:
+ *
+ *
+ * document
+ * .getElementById('calculate')
+ * .addEventListener('click', function(){
+ * var aField = document.getElementById('input1');
+ * var bField = document.getElementById('input2');
+ * var a = parseFloat(aField.value);
+ * var b = parseFloat(bField.value);
+ * window.addAsync(a, b, function(result){
+ * document.getElementById('result').innerHTML = result;
+ * });
+ * }, true);
+ *
+ *
+ *
This script attaches an event handler to the calculate + * button that gets the values from the two input fields and + * passes it to the window.addAsync() method for calculation. The addAsync() + * method is actually our java JSFunction that we implemented earlier. + *
+ * + *+ * One small word about the placement of these files: This example is taken from a class ca.weblite.codename1.tests.CodenameOneTests. + * The AddAsync.html and AddAsync.js files are included in the same directory as the CodenameOneTests.java file ( + * i.e. /ca/weblite/codename1/tests). We used the WebBrowser's setURL() method to load the AddAsync.html + * file from an + * absolute path using jar: protocol. Currently this is the best way of loading local HTML files into + * a WebBrowser object (i.e. use the jar: protocol and provide an absolute path). + *
+ * + *The result of running this app is as follows:
+ *+ *
The following creates a Javascript function for taking photos on a mobile device. It involves a simple webpage with a + * "Capture" button. When the user + * clicks this button, it will dispatch a function call to CodenameOne to access the device's camera. After the user + * takes a picture, CodenameOne will + * execute a Javascript callback to add the picture to the webpage.
+ * + *The HTML page source is as follows:
+ * + * + *This loads the CameraExample.js script:
+ *
+ * document.getElementById('capture')
+ * .addEventListener('click', function(){
+ * camera.capture(function(url){
+ * if ( url == null ){
+ * // No image was provided
+ * return;
+ * }
+ * var results = document.getElementById('results');
+ * results.appendChild(document.createTextNode("testing"));
+ * var img = document.createElement('img');
+ * img.setAttribute('src',url);
+ * img.setAttribute('width', '100');
+ * img.setAttribute('height', '100');
+ * results.appendChild(img);
+ * })
+ * }, true);
+ *
+ * The CameraExample.js script attaches a listener to the 'click' event of the "Capture" button which simply calls the
+ * camera.capture() method,
+ * which is actually a JSFunction that has been registered with the Javascript runtime. This actually calls into Java.
+ *
We pass a callback function into camera.capture() which will be executed upon successfully completion of
+ * the camera. This is a common
+ * programming pattern in Javascript. If a non-null URL is passed to this callback function, it is expected to be the
+ * URL of the image (it will be
+ * a local file URL.
The Java code that powers this example is as follows:
+ * + * + *This example puts together most of the features of the CodenameOne-JS library.
+ *call() method of JSObject to call the callback function that
+ * was
+ * provided by Javascript from inside
+ * the JSFunction's apply() method.
+ * + * The Localization API allows developers to adapt their applications to different geographic locales and + * conventions. + *
+ *+ * Most of the classes within this package are clones of Java SE classes such as {@link + * com.codename1.l10n.SimpleDateFormat} + * vs. {@link java.text.SimpleDateFormat}. The main motivation of placing these classes here and using the + * cloned version is portability. + *
+ *+ * If we would use {@link java.text.SimpleDateFormat} its behavior would be slightly different on Android + * or in the simulator vs. its behavior on iOS. That is because the implementation would be radically different. + * When you use {@link com.codename1.l10n.SimpleDateFormat} the implementation might be missing + * some pieces but it would be more consistent with the implementation you would get on the device which + * is always preferable. + *
+ *
+ * The localization manager allows adapting values for display in different locales thru parsing and formatting
+ * capabilities (similar to JavaSE's DateFormat/NumberFormat). It also includes language/locale/currency
+ * related API's similar to Locale/currency API's from JavaSE.
+ * The sample code below just lists the various capabilities of the API:
+ *
+ */
+package com.codename1.l10n;
diff --git a/CodenameOne/src/com/codename1/location/package-info.java b/CodenameOne/src/com/codename1/location/package-info.java
new file mode 100644
index 0000000000..5b8ecb352d
--- /dev/null
+++ b/CodenameOne/src/com/codename1/location/package-info.java
@@ -0,0 +1,29 @@
+/*
+ Document : package
+ Created on : Oct 11, 2007, 10:38:26 AM
+ Author : Shai Almog
+*/
+
+/**
+ * + * Abstraction of location services (GPS/Geofencing etc.) providing user global positioning and monitoring over + * such changes both in the foreground and background. + *
+ * + *+ * Trivial one time usage of location data can look like this sample: + *
+ * + * + *+ * You can also track location in the foreground using API calls like this: + *
+ * + * + *+ * Geofencing allows tracking whether a user entered a specific region, this can work when the app is completely + * in the background and is very efficient in terms of battery life: + *
+ * + */ +package com.codename1.location; diff --git a/CodenameOne/src/com/codename1/maps/layers/package-info.java b/CodenameOne/src/com/codename1/maps/layers/package-info.java new file mode 100644 index 0000000000..ab8c9ee354 --- /dev/null +++ b/CodenameOne/src/com/codename1/maps/layers/package-info.java @@ -0,0 +1,12 @@ +/* + Document : package + Created on : Oct 11, 2007, 10:38:26 AM + Author : Shai Almog +*/ + +/** + *+ * The Layers are elements that are displayed on the map. + *
+ */ +package com.codename1.maps.layers; diff --git a/CodenameOne/src/com/codename1/maps/package-info.java b/CodenameOne/src/com/codename1/maps/package-info.java new file mode 100644 index 0000000000..b52a4c6ac5 --- /dev/null +++ b/CodenameOne/src/com/codename1/maps/package-info.java @@ -0,0 +1,17 @@ +/* + Document : package + Created on : Oct 11, 2007, 10:38:26 AM + Author : Shai Almog +*/ + +/** + *
+ * The mapping API allows developers to use maps in their applications, add layers
+ * on top of the map and to enhance the API with additional Layers, Providers and functionality.
+ *
+ * The mapping was contributed by Roman Kamyk
+ *
+ * These are the map providers, currently http://www.openstreetmap.org/ is supported. + *
+ */ +package com.codename1.maps.providers; diff --git a/CodenameOne/src/com/codename1/media/package-info.java b/CodenameOne/src/com/codename1/media/package-info.java new file mode 100644 index 0000000000..57725ca95b --- /dev/null +++ b/CodenameOne/src/com/codename1/media/package-info.java @@ -0,0 +1,33 @@ +/* + Document : package + Created on : Oct 11, 2007, 10:38:26 AM + Author : Shai Almog +*/ + +/** + *+ * Video and Audio playback support are handled within this package using the + * {@link com.codename1.media.Media} & {@link com.codename1.media.MediaManager} APIs. + * Said API's allow for video playback both within a native full screen player and embedded within + * an application screen. + *
+ *+ * Simplified video playback API is also available via the {@link com.codename1.components.MediaPlayer} class. + * Capture/recording is handled separately for the most part thru the + * {@link com.codename1.capture.Capture} API. However, there is some basic low level recording + * functionality within {@link com.codename1.media.MediaManager} as well. + *
+ * + *+ * The code below demonstrates capturing and playing back audio files using this API: + *
+ * + *
+ *
+ * + * The sample code below demonstrates simple video playback. + *
+ * + *
+ */
+package com.codename1.media;
diff --git a/CodenameOne/src/com/codename1/messaging/package-info.java b/CodenameOne/src/com/codename1/messaging/package-info.java
new file mode 100644
index 0000000000..87b7ef60c0
--- /dev/null
+++ b/CodenameOne/src/com/codename1/messaging/package-info.java
@@ -0,0 +1,21 @@
+/*
+ Document : package
+ Created on : Feb 12, 2012, 10:38:26 AM
+ Author : Chen Fishbein
+*/
+
+/**
+ * + * Send e-mail messages through underlying platforms e-mail clients or thru the Codename One cloud. + *
+ *+ * You can send messages and include attachments by using the platform native email client like this: + *
+ * + *+ * The following code demonstrates sending an email via the Codename One cloud, notice that this is a pro + * specific feature: + *
+ * + */ +package com.codename1.messaging; diff --git a/CodenameOne/src/com/codename1/notifications/package-info.java b/CodenameOne/src/com/codename1/notifications/package-info.java new file mode 100644 index 0000000000..75097e837f --- /dev/null +++ b/CodenameOne/src/com/codename1/notifications/package-info.java @@ -0,0 +1,106 @@ +/** + *Local notifications are similar to push notifications, except that they are initiated locally by the app, rather than + * remotely. + * They are useful for communicating information to the user while the app is running in the background, since they + * manifest + * themselves as pop-up notifications on supported devices. + *
+ * + *The process for sending a notification is:
+ * + *Notifications can either be set up as one-time only or as repeating.
+ * + *
+ * {@code
+ * LocalNotification n = new LocalNotification();
+ * n.setId("demo-notification");
+ * n.setAlertBody("It's time to take a break and look at me");
+ * n.setAlertTitle("Break Time!");
+ * n.setAlertSound("/notification_sound_bells.mp3"); //file name must begin with notification_sound
+ *
+ *
+ * Display.getInstance().scheduleLocalNotification(
+ * n,
+ * System.currentTimeMillis() + 10 * 1000, // fire date/time
+ * LocalNotification.REPEAT_MINUTE // Whether to repeat and what frequency
+ * );
+ * }
+ *
+ * The resulting notification will look like
+ * + *
The above screenshot was taken on the iOS simulator.
+ * + *The API for receiving/handling local notifications is also similar to push. Your application's main lifecycle class + * needs + * to implement the {@link com.codename1.notifications.LocalNotificationCallback} interface which includes a single + * method: {@link com.codename1.notifications.LocalNotificationCallback#notificationReceived(String)}
+ * + * + *The {@literal notificationId } parameter will match the {@literal id} value of the notification as set using + * {@link com.codename1.notifications.LocalNotification#setId(String)}.
+ * + *
+ * {@code
+ * public class BackgroundLocationDemo implements LocalNotificationCallback {
+ * //...
+ *
+ * public void init(Object context) {
+ * //...
+ * }
+ *
+ * public void start() {
+ * //...
+ *
+ * }
+ *
+ * public void stop() {
+ * //...
+ * }
+ *
+ * public void destroy() {
+ * //...
+ * }
+ *
+ * public void localNotificationReceived(String notificationId) {
+ * System.out.println("Received local notification "+notificationId);
+ * }
+ * }
+ * }
+ *
+ *
+ * NOTE: {@link + * com.codename1.notifications.LocalNotificationCallback#localNotificationReceived(String)} + * is only called when the user responds to the notification by tapping on the alert. If the user doesn't opt to + * click on the notification, then this event handler will never be fired.
+ * + *Repeating notifications will continue until they are canceled by the app. You can cancel a single notification by + * calling {@link com.codename1.ui.Display#cancelLocalNotification(String)}
+ * + *Where {@literal notificationId} is the string id that was set for the notification using {@link + * com.codename1.notifications.LocalNotification#setId(String)}. + * + *
You can see a full sample that uses the new local notifications API + * here. + *
+ */ +package com.codename1.notifications; diff --git a/CodenameOne/src/com/codename1/payment/package-info.java b/CodenameOne/src/com/codename1/payment/package-info.java new file mode 100644 index 0000000000..2a1ac6f785 --- /dev/null +++ b/CodenameOne/src/com/codename1/payment/package-info.java @@ -0,0 +1,7 @@ +/** + *+ * In-App Billing/Purchase API's are abstracted by this package. It encapsulates the different types + * of vendor stores and payment API's available on the market. + *
+ */ +package com.codename1.payment; diff --git a/CodenameOne/src/com/codename1/processing/package-info.java b/CodenameOne/src/com/codename1/processing/package-info.java new file mode 100644 index 0000000000..cb9ba807c3 --- /dev/null +++ b/CodenameOne/src/com/codename1/processing/package-info.java @@ -0,0 +1,117 @@ +/** + *+ * The {@link com.codename1.processing.Result} class provides a subset of + * XPath, but it is not limited to just XML + * documents, it can also work with JSON documents, and even with raw {@link java.util.Map} objects. + *
+ * + *+ * As an example, we'll demonstrate how to process a response from the + * Google Reverse Geocoder API. + * Lets start with this XML snippet: + *
+ * + * + * + *+ * We want to extract some of the data above into simpler string results. We can do this using: + *
+ * + * + * + *+ * If you are at all familiar with processing responses from webservices, you will notice that what would + * normally require several lines of code of selecting and testing nodes in regular java can now be + * done in a single line using the new path expressions. + *
+ * + *+ * In the code above, input can be any of: + *
+ *+ * To use the expression processor when calling a webservice, you could use something like the following to + * parse JSON (notice this is interchangeable between JSON and XML): + *
+ * + * + * + *+ * The returned JSON looks something like this (notice it's snipped because the data is too long): + *
+ * + * + * + *
+ *
+ *
+ * The XML processor currently handles global selections by using a double slash anywhere within the + * expression, for example:
+ * + * + * + *NOTE: Notice that Google's JSON webservice uses plural form for each of + * the node names in that API (ie. results, address_components, and types) where they don't in the XML services + * (ie result, address_component etc.). + *+ * + *
It also possible to do some more complex expressions. We'll use the following XML fragment for the next batch of + * examples:
+ * + * + * + *Above, if you want to select the IDs of all players that are ranked in the top 2, you can use an + * expression like:
+ * + * + *(Notice above that the expression is using an attribute for selecting both rank and id. In JSON + * documents, if you attempt to select an attribute, it will look for a child node under the attribute name you ask + * for).
+ * + *If a document is ordered, you might want to select nodes by their position, for example:
+ * + * + *It is also possible to select parent nodes, by using the �..' expression. For example:
+ * + * + *Above, we globally find a lastname element with a value of �Hewitt', then grab the parent node of + * lastname which happens to be the player node, then grab the id attribute from the player node. + * Alternatively, you could get the same result from the following simpler statement:
+ * + * + * + *It is also possible to nest expressions, for example:
+ * + * + * + *In the above example, if the player node had an address object, we'd be selecting all players from Canada.
+ * This is a simple example of a nested expression, but they can get much more complex, which will be
+ * required as the documents themselves get more complex.
Moving on, to select a node based
+ * on the existence of an attribute:
Above, we selected the IDs of all ranked players. Conversely, we can select the non-ranked players like this:
+ * + * + * + *(Logical not (!) operators currently are not implemented).
You can also select by the existence
+ * of a child node.
Above, we selected all players that have a middle name.
+ * Keep in mind that the Codename One path expression language is not a full implementation of
+ * XPath 1.0, but does already handle many of the most useful features of the specification.
+ * High level property objects that allow us to replace getters/setters in business objects with more convenient + * storage/parsing mappings while retaining type safety. + *
+ */ +package com.codename1.properties; diff --git a/CodenameOne/src/com/codename1/push/package-info.java b/CodenameOne/src/com/codename1/push/package-info.java new file mode 100644 index 0000000000..fbac132bda --- /dev/null +++ b/CodenameOne/src/com/codename1/push/package-info.java @@ -0,0 +1,6 @@ +/** + *+ * Push notification support using either device specific protocols when available + *
+ */ +package com.codename1.push; diff --git a/CodenameOne/src/com/codename1/share/package-info.java b/CodenameOne/src/com/codename1/share/package-info.java new file mode 100644 index 0000000000..b420bc7c0c --- /dev/null +++ b/CodenameOne/src/com/codename1/share/package-info.java @@ -0,0 +1,6 @@ +/** + *+ * Sharing services, that can be registered on the ShareButton + *
+ */ +package com.codename1.share; diff --git a/CodenameOne/src/com/codename1/social/package-info.java b/CodenameOne/src/com/codename1/social/package-info.java new file mode 100644 index 0000000000..1f8fad929a --- /dev/null +++ b/CodenameOne/src/com/codename1/social/package-info.java @@ -0,0 +1,6 @@ +/** + *+ * Connectors for native social network SDK's + *
+ */ +package com.codename1.social; diff --git a/CodenameOne/src/com/codename1/system/package-info.java b/CodenameOne/src/com/codename1/system/package-info.java new file mode 100644 index 0000000000..3a17072a33 --- /dev/null +++ b/CodenameOne/src/com/codename1/system/package-info.java @@ -0,0 +1,92 @@ +/** + *+ * Low level calls into the Codename One system, including + * + * support for making platform native API calls. Notice + * that when we say "native" we do not mean C/C++ always but rather the platforms "native" environment. So in the + * case of Android the Java code will be invoked with full access to the Android API's, in case of iOS an Objective-C + * message would be sent and so forth. + *
+ *
+ * Native interfaces are designed to only allow primitive types, Strings, arrays (single dimension only!) of primitives
+ * and PeerComponent values. Any other type of parameter/return type is prohibited. However, once in the native layer
+ * the native code can act freely and query the Java layer for additional information.
+ * Furthermore, native methods should avoid features such as overloading, varargs (or any Java 5+ feature for that
+ * matter)
+ * to allow portability for languages that do not support such features (e.g. C).
+ * Important! Do not rely on pass by reference/value behavior since they vary between platforms.
+ *
+ * Implementing a native layer effectively means: + *
+ *+ * E.g. to create a simple hello world interface do something like: + *
+ *
+ * package com.my.code;
+ * public interface MyNative extends NativeInteface {
+ * String helloWorld(String hi);
+ * }
+ *
+ *
+ * Then to use that interface use MyNative my = (MyNative)NativeLookup.create(MyNative.class);
+ * Notice that for this to work you must implement the native code on all supported platforms!
+ *
+ * To implement the native code use the following convention. For Java based platforms (Android, RIM, J2ME): + *
+ *+ * Just create a Java class that resides in the same package as the NativeInterface you created + * and bares the same name with Impl appended e.g.: MyNativeImpl. So for these platforms the code + * would look something like this: + *
+ *
+ * package com.my.code;
+ * public class MyNativeImpl implements MyNative {
+ * public String helloWorld(String hi) {
+ * // code that can invoke Android/RIM/J2ME respectively
+ * }
+ * }
+ *
+ * + * Notice that this code will only be compiled on the server build and is not compiled on the client. + * These sources should be placed under the appropriate folder in the native directory and are sent to the + * server for compilation. + *
+ *+ * For Objective-C, one would need to define a class matching the name of the package and the class name + * combined where the "." elements are replaced by underscores. One would need to provide both a header and + * an "m" file following this convention e.g.: + *
+ *
+ * @interface com_my_code_MyNative : NSObject {
+ * }
+ * - (id)init;
+ * - (NSString*)helloWorld:(NSString *)param1;
+ * @end
+ *
+ * + * Notice that the parameters in Objective-C are named which has no equivalent in Java. That is why the native + * method in Objective-C MUST follow the convention of naming the parameters "param1", "param2" etc. for all + * the native method implementations. Java arrays are converted to NSData objects to allow features such as length + * indication. + *
+ * + *
+ * PeerComponent return values are automatically translated to the platform native peer as an expected return
+ * value. E.g. for a native method such as this: PeerComponent createPeer();
+ * Android native implementation would need: View createPeer();
+ * While RIM would expect: Field createPeer()
+ * The iphone would need to return a pointer to a view e.g.: - (UIView*)createPeer;
+ * J2ME doesn't support native peers hence any method that returns a native peer would always return null.
+ *
+ * This package contains everything necessary for unit tests, automation of tests and everything in between. + *
+ */ +package com.codename1.testing; diff --git a/CodenameOne/src/com/codename1/ui/animations/package-info.java b/CodenameOne/src/com/codename1/ui/animations/package-info.java new file mode 100644 index 0000000000..21008f1921 --- /dev/null +++ b/CodenameOne/src/com/codename1/ui/animations/package-info.java @@ -0,0 +1,14 @@ +/* + Document : package + Created on : Oct 11, 2007, 10:38:26 AM + Author : Shai Almog +*/ + +/** + * All components are animatable by potential and additional animations (unrelated + * to a specific component) can be installed on the fly, transitions between + * forms are also handled as part of this package. Animation thread handling + * and painting is handled uniformly to avoid the complexity of threading and + * its potential performance penalty on small devices. + */ +package com.codename1.ui.animations; diff --git a/CodenameOne/src/com/codename1/ui/events/package-info.java b/CodenameOne/src/com/codename1/ui/events/package-info.java new file mode 100644 index 0000000000..892cfaf0a6 --- /dev/null +++ b/CodenameOne/src/com/codename1/ui/events/package-info.java @@ -0,0 +1,14 @@ +/* + Document : package + Created on : Oct 11, 2007, 10:38:26 AM + Author : Shai Almog +*/ + +/** + *+ * Observable pattern event listeners in the spirit of AWT 1.1's event + * dispatching architecture, all events are dispatched on the EDT (Event Dispatch Thread). + * See the overview documentation for further information and {@link com.codename1.ui.Display}. + *
+ */ +package com.codename1.ui.events; diff --git a/CodenameOne/src/com/codename1/ui/geom/package-info.java b/CodenameOne/src/com/codename1/ui/geom/package-info.java new file mode 100644 index 0000000000..8054d275f7 --- /dev/null +++ b/CodenameOne/src/com/codename1/ui/geom/package-info.java @@ -0,0 +1,7 @@ +/** + *+ * Contains classes related to geometry locations and calculations such as + * rectangle and size + *
+ */ +package com.codename1.ui.geom; diff --git a/CodenameOne/src/com/codename1/ui/html/package-info.java b/CodenameOne/src/com/codename1/ui/html/package-info.java new file mode 100644 index 0000000000..ea4b630f42 --- /dev/null +++ b/CodenameOne/src/com/codename1/ui/html/package-info.java @@ -0,0 +1,16 @@ +/* + Document : package + Created on : Jan 24, 2010 + Author : Ofir Leitner +*/ + +/** + *+ * This package is deprecated and used only for legacy support, use the WebBrowser component + * from the components package. + * The HTML package allows rendering XHTML-MP 1.0 documents including WCSS support. + *
+ *+ *
+ */ +package com.codename1.ui.html; diff --git a/CodenameOne/src/com/codename1/ui/layouts/package-info.java b/CodenameOne/src/com/codename1/ui/layouts/package-info.java new file mode 100644 index 0000000000..36792eeb82 --- /dev/null +++ b/CodenameOne/src/com/codename1/ui/layouts/package-info.java @@ -0,0 +1,75 @@ +/** + *+ * Layout managers allow a {@link com.codename1.ui.Container} to + * arrange its components by a set of rules that adapt to specific + * densities (ppi - pixels per inch). A layout manager is an arranging algorithm encapsulated + * by an abstract class implementation that places components absolutely based + * on the "hints" received. + *
+ *+ * {@link com.codename1.ui.layouts.FlowLayout} is default layout manager, simple, flexible and with a few caveats. + *
+ *
+ *
+ * + * {@link com.codename1.ui.layouts.BorderLayout} is ubiquitous thru Codename One code. + *
+ *
+ *
+ * + * {@link com.codename1.ui.layouts.BorderLayout} can also behave differently based on the center behavior flag + *
+ *
+ *
+ * + * {@link com.codename1.ui.layouts.BoxLayout} Y axis is a the work-horse of component lists + *
+ *
+ *
+ * + * {@link com.codename1.ui.layouts.BoxLayout} X axis is a simpler replacement to flow layout and has grow/no grow + * variants. + *
+ *
+ *
+ * + * {@link com.codename1.ui.layouts.GridLayout} arranges elements in a grid where all elements have an equal size. It + * can auto adapt + * the column count. + *
+ *
+ * 
+ *
+ *
+ * {@link com.codename1.ui.table.TableLayout} is similar in many regards to HTML tables. Notice that its
+ * in the com.codename1.ui.table package and not in this package.
+ *
+ * 
+ *
+ * + * {@link com.codename1.ui.layouts.LayeredLayout} is unique in the sense that it is meant to costruct layers + * and not the UI positions. It only lays out on the Z axis. + *
+ *
+ *
+ * + * {@link com.codename1.ui.layouts.GridBagLayout} was added to Codename One to ease the porting of Swing/AWT + * applications. + *
+ *
+ *
+ * + * {@link com.codename1.ui.layouts.mig.MigLayout} is a popular 3rd party layout manager its Codename One + * port is experimental. + *
+ *
+ */
+package com.codename1.ui.layouts;
diff --git a/CodenameOne/src/com/codename1/ui/list/package-info.java b/CodenameOne/src/com/codename1/ui/list/package-info.java
new file mode 100644
index 0000000000..189aa8a911
--- /dev/null
+++ b/CodenameOne/src/com/codename1/ui/list/package-info.java
@@ -0,0 +1,27 @@
+/*
+ Document : package
+ Created on : Oct 11, 2007, 10:38:26 AM
+ Author : Shai Almog
+*/
+
+/**
+ *
+ * Lists are highly customizable and serve as the basis for {@link com.codename1.ui.ComboBox} and
+ * other components (such as carousels etc) they employ a similar MVC approach to
+ * Swing including the renderer pattern, notice that we strongly
+ * discourage usage of lists...
{@link com.codename1.ui.list.ListCellRenderer}
+ * allows us to customize the appearance of a list entry, it works as a
+ * "rubber stamp" by drawing the rendered component and discarding its state thus
+ * allowing very large lists with very little component state overhead.
+ *
+ * {@link com.codename1.ui.list.ListModel} allows us to represent the underlying + * data structure for the {@link com.codename1.ui.List}/{@link com.codename1.ui.ComboBox} + * without requiring all the data to reside in memory or in a specific structure. + * This allows a model to represent a data source of any type, coupled with the renderer the + * data source can be returned in an internal representation state and still be rendered + * properly to the screen. + *
+ */ +package com.codename1.ui.list; diff --git a/CodenameOne/src/com/codename1/ui/package-info.java b/CodenameOne/src/com/codename1/ui/package-info.java new file mode 100644 index 0000000000..40b4b06c16 --- /dev/null +++ b/CodenameOne/src/com/codename1/ui/package-info.java @@ -0,0 +1,425 @@ +/** + *+ * Main widget package containing the component/container "composite" similar + * both in terminology and design to Swing/AWT. + *
+ *+ * Containers can be nested one within the other to form elaborate UI's. Containers use + * {@link com.codename1.ui.layouts} to arrange the components within. This is important + * as it allows a container can adapt to changing resolution, DPI, orientation, font size etc. + *
+ *
+ * + * A container doesn't implicitly reflow its elements and in that regard follows the direction of AWT/Swing. As + * a result the layout can be animated to create a flowing effect for UI changes. This also provides improved + * performance as a bonus. See this sample of {@code Container} animation: + *
+ * + * + *+ * You can learn more about layout managers {@link com.codename1.ui.layouts here} and about + * event handling {@link com.codename1.ui.events here}. + *
+ * + *+ * The component gallery below isn't complete or exhaustive but it should give you a sense of the + * types of widgets available within Codename One in a glance. + *
+ * + * + *
+ *
+ * 
+ *
+ * 
+ *
+ * 
+ *
+ * 
+ *
+ * 
+ *
+ * 
+ *
+ * 
+ *
+ * 
+ *
+ * 
+ *
+ * 
+ *
+ * 
+ *
+ * 
+ *
+ * 
+ *
+ * 
+ *
+ * 
+ *
+ * 
+ *
+ * 
+ *
+ *
+ *
+ * 
+ *
+ * 
+ *
+ * 
+ *
+ *
+ *
+ * 
+ *
+ * 
+ *
+ * 
+ *
+ * 
+ *
+ * 
+ *
+ * 
+ *
+ * 
+ *
+ * 
+ *
+ * 
+ *
+ * 
+ *
+ * 
+ *
+ * 
+ *
+ * + * {@link com.codename1.ui.Painter} allows us to draw arbitrary elements + * of graphics from plain/scaled/tiled images to gradients and pretty + * much any form of graphic drawing we can imagine. Painters are + * "hooked" into the core of the API thus allowing us to customize + * every aspect of it. See {@link com.codename1.ui.Component} and + * {@link com.codename1.ui.Form}. + *
+ */ +package com.codename1.ui.painter; diff --git a/CodenameOne/src/com/codename1/ui/plaf/package-info.java b/CodenameOne/src/com/codename1/ui/plaf/package-info.java new file mode 100644 index 0000000000..160b6f7d3d --- /dev/null +++ b/CodenameOne/src/com/codename1/ui/plaf/package-info.java @@ -0,0 +1,21 @@ +/* + Document : package + Created on : Oct 11, 2007, 10:38:26 AM + Author : Shai Almog +*/ + +/** + *+ * Look of the application can be fully customized via this package, it represents + * a rendering layer that can be plugged in separately in runtime and themed to + * provide any custom look. Unlike the Swing PLAF this layer does not support any + * aspect of "feel" as in event handling etc. since these aspects would require a + * much bigger and more elaborate layer unfit for small device OTA delivery. + *
+ *+ * Sizes of components are also calculated by the {@link com.codename1.ui.plaf.LookAndFeel} + * since the size is very much affected by the look of the application e.g. the thickness + * of the border and the font sizes. + *
+ */ +package com.codename1.ui.plaf; diff --git a/CodenameOne/src/com/codename1/ui/scene/package-info.java b/CodenameOne/src/com/codename1/ui/scene/package-info.java new file mode 100644 index 0000000000..27f17bcaa1 --- /dev/null +++ b/CodenameOne/src/com/codename1/ui/scene/package-info.java @@ -0,0 +1,13 @@ +/* + Document : package + Created on : May 15, 2018 10:38:26 AM + Author : Steve Hannah +*/ + +/** + *+ * This package provides a light-weight scene graph for Codename One. It is marked deprecated because it is + * for internal use only. + *
+ */ +package com.codename1.ui.scene; diff --git a/CodenameOne/src/com/codename1/ui/spinner/package-info.java b/CodenameOne/src/com/codename1/ui/spinner/package-info.java new file mode 100644 index 0000000000..95b876b0f5 --- /dev/null +++ b/CodenameOne/src/com/codename1/ui/spinner/package-info.java @@ -0,0 +1,13 @@ +/* + Document : package + Created on : Oct 11, 2007, 10:38:26 AM + Author : Shai Almog +*/ + +/** + *+ * Spinners allows picking of simple sequential values similarly to combo boxes but of a much wider value set. + * They are mostly designed for picking dates, numbers or hours of the day. + *
+ */ +package com.codename1.ui.spinner; diff --git a/CodenameOne/src/com/codename1/ui/table/package-info.java b/CodenameOne/src/com/codename1/ui/table/package-info.java new file mode 100644 index 0000000000..c651216e5d --- /dev/null +++ b/CodenameOne/src/com/codename1/ui/table/package-info.java @@ -0,0 +1,12 @@ +/* + Document : package + Created on : Oct 11, 2007, 10:38:26 AM + Author : Shai Almog +*/ + +/** + *+ * Table component for editing and viewing tabular data and arranging Codename One components in a tabular form + *
+ */ +package com.codename1.ui.table; diff --git a/CodenameOne/src/com/codename1/ui/tree/package-info.java b/CodenameOne/src/com/codename1/ui/tree/package-info.java new file mode 100644 index 0000000000..fe74f40e2c --- /dev/null +++ b/CodenameOne/src/com/codename1/ui/tree/package-info.java @@ -0,0 +1,12 @@ +/* + Document : package + Created on : Oct 11, 2007, 10:38:26 AM + Author : Shai Almog +*/ + +/** + *+ * Tree component for displaying hierarchy based information and its related classes + *
+ */ +package com.codename1.ui.tree; diff --git a/CodenameOne/src/com/codename1/ui/util/package-info.java b/CodenameOne/src/com/codename1/ui/util/package-info.java new file mode 100644 index 0000000000..712afa4468 --- /dev/null +++ b/CodenameOne/src/com/codename1/ui/util/package-info.java @@ -0,0 +1,13 @@ +/* + Document : package + Created on : Oct 11, 2007, 10:38:26 AM + Author : Shai Almog +*/ + +/** + *+ * Utility features that are either too domain specific or don't "fit" into any + * other packages including the Resource file format loading API. + *
+ */ +package com.codename1.ui.util; diff --git a/CodenameOne/src/com/codename1/ui/validation/package-info.java b/CodenameOne/src/com/codename1/ui/validation/package-info.java new file mode 100644 index 0000000000..1e92e4b002 --- /dev/null +++ b/CodenameOne/src/com/codename1/ui/validation/package-info.java @@ -0,0 +1,7 @@ +/** + *+ * The validation framework allows us to mark invalid input in text components and disable components + * in the case of invalid input + *
+ */ +package com.codename1.ui.validation; diff --git a/CodenameOne/src/com/codename1/util/package-info.java b/CodenameOne/src/com/codename1/util/package-info.java new file mode 100644 index 0000000000..15219d8fbe --- /dev/null +++ b/CodenameOne/src/com/codename1/util/package-info.java @@ -0,0 +1,12 @@ +/* + Document : package + Created on : Oct 11, 2007, 10:38:26 AM + Author : Shai Almog +*/ + +/** + *+ * General utilities classes + *
+ */ +package com.codename1.util; diff --git a/CodenameOne/src/com/codename1/util/regex/package-info.java b/CodenameOne/src/com/codename1/util/regex/package-info.java new file mode 100644 index 0000000000..fcb55cb486 --- /dev/null +++ b/CodenameOne/src/com/codename1/util/regex/package-info.java @@ -0,0 +1,12 @@ +/* + Document : package + Created on : Oct 11, 2007, 10:38:26 AM + Author : Shai Almog +*/ + +/** + *+ * A simple regular expression API that is portable across all platforms + *
+ */ +package com.codename1.util.regex; diff --git a/CodenameOne/src/com/codename1/xml/package-info.java b/CodenameOne/src/com/codename1/xml/package-info.java new file mode 100644 index 0000000000..9a0fdea098 --- /dev/null +++ b/CodenameOne/src/com/codename1/xml/package-info.java @@ -0,0 +1,14 @@ +/* + Document : package + Created on : Jul 1, 2010 + Author : Ofir Leitner +*/ + +/** + *+ * The XML package allows parsing XML documents into DOM objects. + *
+ *+ *
+ */ +package com.codename1.xml; diff --git a/CodenameOneDesigner/src/com/l2fprod/common/beans/editor/package-info.java b/CodenameOneDesigner/src/com/l2fprod/common/beans/editor/package-info.java new file mode 100644 index 0000000000..6114830615 --- /dev/null +++ b/CodenameOneDesigner/src/com/l2fprod/common/beans/editor/package-info.java @@ -0,0 +1,4 @@ +/** + * Provides PropertyEditors for various Object types. + */ +package com.l2fprod.common.beans.editor; diff --git a/CodenameOneDesigner/src/com/l2fprod/common/propertysheet/package-info.java b/CodenameOneDesigner/src/com/l2fprod/common/propertysheet/package-info.java new file mode 100644 index 0000000000..7c3bfb7505 --- /dev/null +++ b/CodenameOneDesigner/src/com/l2fprod/common/propertysheet/package-info.java @@ -0,0 +1,4 @@ +/** + * Provides a component to edit Properties in a table-like user interface. + */ +package com.l2fprod.common.propertysheet; diff --git a/CodenameOneDesigner/src/com/l2fprod/common/swing/plaf/basic/package-info.java b/CodenameOneDesigner/src/com/l2fprod/common/swing/plaf/basic/package-info.java new file mode 100644 index 0000000000..36f2c9aeaf --- /dev/null +++ b/CodenameOneDesigner/src/com/l2fprod/common/swing/plaf/basic/package-info.java @@ -0,0 +1,4 @@ +/** + * Basic implementation of Pluggable look and feel classes. + */ +package com.l2fprod.common.swing.plaf.basic; diff --git a/CodenameOneDesigner/src/com/l2fprod/common/swing/plaf/blue/package-info.java b/CodenameOneDesigner/src/com/l2fprod/common/swing/plaf/blue/package-info.java new file mode 100644 index 0000000000..20e0e5f54f --- /dev/null +++ b/CodenameOneDesigner/src/com/l2fprod/common/swing/plaf/blue/package-info.java @@ -0,0 +1,4 @@ +/** + * Blue theme implementation. + */ +package com.l2fprod.common.swing.plaf.blue; diff --git a/CodenameOneDesigner/src/com/l2fprod/common/swing/plaf/package-info.java b/CodenameOneDesigner/src/com/l2fprod/common/swing/plaf/package-info.java new file mode 100644 index 0000000000..e819e70cef --- /dev/null +++ b/CodenameOneDesigner/src/com/l2fprod/common/swing/plaf/package-info.java @@ -0,0 +1,4 @@ +/** + * Pluggable look and feel classes for Common Components. + */ +package com.l2fprod.common.swing.plaf; diff --git a/CodenameOneDesigner/src/com/l2fprod/common/swing/plaf/windows/package-info.java b/CodenameOneDesigner/src/com/l2fprod/common/swing/plaf/windows/package-info.java new file mode 100644 index 0000000000..bc1154996a --- /dev/null +++ b/CodenameOneDesigner/src/com/l2fprod/common/swing/plaf/windows/package-info.java @@ -0,0 +1,4 @@ +/** + * Windows-like implementation of Pluggable look and feel classes. + */ +package com.l2fprod.common.swing.plaf.windows; diff --git a/Ports/J2ME/src/com/codename1/impl/midp/package-info.java b/Ports/J2ME/src/com/codename1/impl/midp/package-info.java new file mode 100644 index 0000000000..67e8e3ccb8 --- /dev/null +++ b/Ports/J2ME/src/com/codename1/impl/midp/package-info.java @@ -0,0 +1,6 @@ +/** + *+ * Codename One's MIDP implementation classes reside in this package + *
+ */ +package com.codename1.impl.midp; From 993906d16ae0a34a89bb5954e7b44452a035ce0b Mon Sep 17 00:00:00 2001 From: Shai Almog <67850168+shai-almog@users.noreply.github.com> Date: Mon, 2 Feb 2026 21:08:51 +0200 Subject: [PATCH 2/2] Fix non-ASCII in generated package docs --- CodenameOne/src/com/codename1/contacts/package-info.java | 2 +- CodenameOne/src/com/codename1/processing/package-info.java | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/CodenameOne/src/com/codename1/contacts/package-info.java b/CodenameOne/src/com/codename1/contacts/package-info.java index 1d34464a0a..a0915f6c5d 100644 --- a/CodenameOne/src/com/codename1/contacts/package-info.java +++ b/CodenameOne/src/com/codename1/contacts/package-info.java @@ -3,7 +3,7 @@ * Provides access to the contacts list from the device address book * *- * The contacts API provides us with the means to query the phone�s address book, delete elements from + * The contacts API provides us with the means to query the phone's address book, delete elements from * it and create new entries into it. *
*diff --git a/CodenameOne/src/com/codename1/processing/package-info.java b/CodenameOne/src/com/codename1/processing/package-info.java index cb9ba807c3..36ab732925 100644 --- a/CodenameOne/src/com/codename1/processing/package-info.java +++ b/CodenameOne/src/com/codename1/processing/package-info.java @@ -82,10 +82,10 @@ *
If a document is ordered, you might want to select nodes by their position, for example:
* * - *It is also possible to select parent nodes, by using the �..' expression. For example:
+ *It is also possible to select parent nodes, by using the '..' expression. For example:
* * - *Above, we globally find a lastname element with a value of �Hewitt', then grab the parent node of + *
Above, we globally find a lastname element with a value of 'Hewitt', then grab the parent node of * lastname which happens to be the player node, then grab the id attribute from the player node. * Alternatively, you could get the same result from the following simpler statement:
*
+ * 
+ * 
+ * 
+ *