Commit 578d53ec authored by Geoffrey Métais's avatar Geoffrey Métais

Start API javadoc

parent 3f61a5bb
......@@ -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) {
......
......@@ -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() {
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment