[Android] Start API javadoc
Geoffrey Métais
git at videolan.org
Wed Dec 23 18:14:59 CET 2015
vlc-android | branch: master | Geoffrey Métais <geoffrey.metais at gmail.com> | Wed Dec 23 18:14:35 2015 +0100| [578d53ec46f7c9266f5e706df5884b57b5e12faf] | committer: Geoffrey Métais
Start API javadoc
> https://code.videolan.org/videolan/vlc-android/commit/578d53ec46f7c9266f5e706df5884b57b5e12faf
---
.../vlc/extensions/api/VLCExtensionItem.java | 137 +++++++++++++++++++--
.../vlc/extensions/api/VLCExtensionService.java | 36 +++++-
2 files changed, 164 insertions(+), 9 deletions(-)
diff --git a/api/src/main/java/org/videolan/vlc/extensions/api/VLCExtensionItem.java b/api/src/main/java/org/videolan/vlc/extensions/api/VLCExtensionItem.java
index 4586eab..e7651af 100644
--- a/api/src/main/java/org/videolan/vlc/extensions/api/VLCExtensionItem.java
+++ b/api/src/main/java/org/videolan/vlc/extensions/api/VLCExtensionItem.java
@@ -26,13 +26,48 @@ package org.videolan.vlc.extensions.api;
import android.os.Parcel;
import android.os.Parcelable;
+/**
+ * A parcelable, serializable object containing information about medium to be sent to VLC
+ * for browsing of playback
+ *
+ * <p>
+ * This class follows the <a href="http://en.wikipedia.org/wiki/Fluent_interface">fluent
+ * interface</a> style, using method chaining to provide for more readable code. For example, to set
+ * the title and link of this data, use {@link #setTitle(String)} and {@link #setLink(String)}
+ * methods like so:
+ *
+ * <pre class="prettyprint">
+ * VLCExtensionItem data = new VLCExtensionItem(id, null)
+ * .setTitle("My Video")
+ * .setLink("http://mysite.net/myvideo.ogv");
+ * </pre>
+ *
+ */
public class VLCExtensionItem implements Parcelable {
+ /**
+ * Item type to show it as a directory in VLC browser
+ */
public static final int TYPE_DIRECTORY = 0;
+ /**
+ * Item type to show it as a video medium in VLC browser
+ */
public static final int TYPE_VIDEO = 1;
+ /**
+ * Item type to show it as an audio medium in VLC browser
+ */
public static final int TYPE_AUDIO = 2;
+ /**
+ * Item type to show it as a playlist item in VLC browser
+ */
public static final int TYPE_PLAYLIST = 3;
+ /**
+ * Item type to show it as a subtitle file in VLC browser
+ */
public static final int TYPE_SUBTITLE = 4;
+ /**
+ * Unknown type, VLC will guess from its {#link link} or title
+ */
public static final int TYPE_OTHER_FILE = 5;
public String stringId;
@@ -42,26 +77,114 @@ public class VLCExtensionItem implements Parcelable {
public String title;
public String subTitle;
- //TODO choose how to deal with icons
public String imageLink; // for content provider
public int type; // Using VLC icons. maybe with iconRes?
- public VLCExtensionItem(String stringId, int intId, String link, String title, String subTitle, String imageLink, int type) {
+ /**
+ * Simple constructor, with only ids.
+ * You have to provide a String or int id for browsable elements (with type #TYPE_DIRECTORY)
+ *
+ * @param stringId The String to use as an ID, set to #null if you prefer to use the #intId
+ * @param intId The int to use as an ID, set to 0 if you prefer to use the #stringId
+ */
+ public VLCExtensionItem(String stringId, int intId) {
this.stringId = stringId;
this.intId = intId;
+ }
+
+ public VLCExtensionItem() {}
+
+ private VLCExtensionItem(Parcel in) {
+ readFromParcel(in);
+ }
+
+ /**
+ * Returns the subTitle of this item. e.g. media artist or album
+ */
+ public String getSubTitle() {
+ return subTitle;
+ }
+
+ /**
+ * Sets the subTitles string of this item.
+ *
+ * @param subTitle The subTitle string to set.
+ */
+ public VLCExtensionItem setSubTitle(String subTitle) {
+ this.subTitle = subTitle;
+ return this;
+ }
+
+ /**
+ * Returns the uri string of the {#link VLCExtensionItem} for playback or download
+ */
+ public String getLink() {
+ return link;
+ }
+
+ /**
+ * Sets the uri String of the {#link VLCExtensionItem}
+ *
+ * @param link The medium link.
+ */
+ public VLCExtensionItem setLink(String link) {
this.link = link;
+ return this;
+ }
+
+ /**
+ * returns the {#link VLCExtensionItem} title
+ */
+ public String getTitle() {
+ return title;
+ }
+
+ /**
+ * Sets the {#link VLCExtensionItem} title
+ *
+ * @param title The string to set as title.
+ */
+ public VLCExtensionItem setTitle(String title) {
this.title = title;
- this.subTitle = subTitle;
+ return this;
+ }
+
+ /**
+ * Returns the {#link VLCExtensionItem} icon image link
+ */
+ public String getImageLink() {
+ return imageLink;
+ }
+
+ /**
+ * Sets the uri string of the {#link VLCExtensionItem} icon image.
+ *
+ * @param imageLink The uri string to set.
+ */
+ public VLCExtensionItem setImageLink(String imageLink) {
this.imageLink = imageLink;
- this.type = type;
+ return this;
}
- public VLCExtensionItem() {
+ /**
+ * Returns the {#link VLCExtensionItem} type
+ * @see {#link setType}.
+ */
+ public int getType() {
+ return type;
}
- private VLCExtensionItem(Parcel in) {
- readFromParcel(in);
+ /**
+ * Sets the type of the {#link VLCExtensionItem}
+ *
+ * @param type The type among {#link TYPE_DIRECTORY}, {#link TYPE_VIDEO},
+ * {#link TYPE_AUDIO} or {#link TYPE_OTHER_FILE}.
+ */
+ public VLCExtensionItem setType(int type) {
+ this.type = type;
+ return this;
}
+
public static final Parcelable.Creator<VLCExtensionItem> CREATOR = new
Parcelable.Creator<VLCExtensionItem>() {
public VLCExtensionItem createFromParcel(Parcel in) {
diff --git a/api/src/main/java/org/videolan/vlc/extensions/api/VLCExtensionService.java b/api/src/main/java/org/videolan/vlc/extensions/api/VLCExtensionService.java
index 3899211..924eaea 100644
--- a/api/src/main/java/org/videolan/vlc/extensions/api/VLCExtensionService.java
+++ b/api/src/main/java/org/videolan/vlc/extensions/api/VLCExtensionService.java
@@ -10,6 +10,7 @@ import android.os.HandlerThread;
import android.os.IBinder;
import android.os.Looper;
import android.os.RemoteException;
+import android.support.annotation.NonNull;
import android.support.annotation.Nullable;
import java.util.List;
@@ -29,7 +30,18 @@ public abstract class VLCExtensionService extends Service{
private volatile Looper mServiceLooper;
protected volatile Handler mServiceHandler;
- protected abstract void browse(int intId, String stringId);
+ /**
+ * Called by VLC when users wants to browse one of your {#link VLCExtensionItem.TYPE_DIRECTORY}
+ * VLC provides {#intId} and {#stringId} from chosen item
+ *
+ * @param intId int id of the item to browse
+ * @param stringId String id of the item to browse
+ */
+ protected abstract void browse(int intId, @Nullable String stringId);
+
+ /**
+ * Called by VLC when user wants to refresh the current list displayed by the extension.
+ */
protected abstract void refresh();
@Override
@@ -59,13 +71,28 @@ public abstract class VLCExtensionService extends Service{
mServiceLooper.quit();
}
- public void playUri(Uri uri, String title) {
+ /**
+ * Starts playback of the given uri by VLC
+ *
+ * @param uri The uri to play
+ * @param title Optional - Set the media title to be displayed.
+ * Otherwise, it will be guessed from uri.
+ */
+ public void playUri(@NonNull Uri uri, @Nullable String title) {
try {
mHost.playUri(uri, title);
} catch (RemoteException e) {
e.printStackTrace();
}
}
+
+ /**
+ * Displays given items in VLC browser.
+ *
+ * @param title The title shown in VLC action bar for this list display.
+ * @param items The items to show.
+ * @param showParams Wether you want to show the FAB to launch your extension settings activity.
+ */
protected void updateList(String title, List<VLCExtensionItem> items, boolean showParams){
try {
mHost.updateList(title, items, showParams);
@@ -74,6 +101,11 @@ public abstract class VLCExtensionService extends Service{
}
}
+ /**
+ * Called once VLC is binded to your service.
+ * Use it to call {@link #updateList(String, List, boolean)} with root level elements
+ * if you want VLC to handle your extension browsing.
+ */
protected void onInitialize() {};
private final IExtensionService.Stub mBinder = new IExtensionService.Stub() {
More information about the Android
mailing list