From 648901ceaaa43f45745cc5aacdf14c806f1b4cc7 Mon Sep 17 00:00:00 2001 From: Eric Kok Date: Mon, 17 Jun 2013 18:30:52 +0200 Subject: [PATCH] Added JavaDoc comments and some formatting of code. --- .../transdroid/core/gui/DetailsActivity.java | 6 +++ .../transdroid/core/gui/DetailsFragment.java | 48 ++++++++++--------- .../core/gui/SearchHistoryProvider.java | 26 +++++----- .../transdroid/core/gui/TorrentsActivity.java | 12 ++++- .../transdroid/core/gui/TorrentsFragment.java | 8 +++- 5 files changed, 62 insertions(+), 38 deletions(-) diff --git a/core/src/org/transdroid/core/gui/DetailsActivity.java b/core/src/org/transdroid/core/gui/DetailsActivity.java index 1803ce63..0186ac60 100644 --- a/core/src/org/transdroid/core/gui/DetailsActivity.java +++ b/core/src/org/transdroid/core/gui/DetailsActivity.java @@ -52,6 +52,12 @@ import com.actionbarsherlock.app.SherlockFragmentActivity; import de.keyboardsurfer.android.widget.crouton.Crouton; +/** + * An activity that holds a single torrents details fragment. It is used on devices (i.e. phones) where there is no room + * to show details in the {@link TorrentsActivity} directly. Task execution, such as loading of more details and + * updating file priorities, is performed in this activity via background methods. + * @author Eric Kok + */ @EActivity(resName = "activity_details") @OptionsMenu(resName = "activity_details") public class DetailsActivity extends SherlockFragmentActivity implements TorrentTasksExecutor { diff --git a/core/src/org/transdroid/core/gui/DetailsFragment.java b/core/src/org/transdroid/core/gui/DetailsFragment.java index 4a2f78e6..c53722ea 100644 --- a/core/src/org/transdroid/core/gui/DetailsFragment.java +++ b/core/src/org/transdroid/core/gui/DetailsFragment.java @@ -1,6 +1,7 @@ package org.transdroid.core.gui; import java.util.ArrayList; +import java.util.Collections; import java.util.List; import org.androidannotations.annotations.AfterViews; @@ -35,11 +36,12 @@ import de.keyboardsurfer.android.widget.crouton.Crouton; /** * Fragment that shows detailed statistics about some torrent. These come from some already fetched {@link Torrent} - * object, but it also retrieves further detailed statistics. + * object, but it also retrieves further detailed statistics. The actual execution of tasks is performed by the activity + * that contains this fragment, as per the {@link TorrentTasksExecutor} interface. * @author Eric Kok */ -@EFragment(resName="fragment_details") -@OptionsMenu(resName="fragment_details") +@EFragment(resName = "fragment_details") +@OptionsMenu(resName = "fragment_details") public class DetailsFragment extends SherlockFragment { // Local data @@ -54,7 +56,7 @@ public class DetailsFragment extends SherlockFragment { protected boolean isLoadingTorrent = false; // Views - @ViewById(resName="details_list") + @ViewById(resName = "details_list") protected SherlockListView detailsList; @ViewById protected TextView emptyText; @@ -122,12 +124,13 @@ public class DetailsFragment extends SherlockFragment { // Check if these are actually the details of the torrent we are now showing if (!torrent.getUniqueID().equals(checkTorrent.getUniqueID())) return; + Collections.sort(newTorrentFiles); this.torrentFiles = newTorrentFiles; ((DetailsAdapter) detailsList.getAdapter()).updateTorrentFiles(newTorrentFiles); } /** - * Can be called if some outside activity returned new torrents, so we can perhaps piggyback on this by update our + * Can be called if some outside activity returned new torrents, so we can perhaps piggyback on this by update our * data as well. * @param torrents The last of retrieved torrents */ @@ -150,8 +153,8 @@ public class DetailsFragment extends SherlockFragment { public void clear() { detailsList.setAdapter(new DetailsAdapter(getActivity())); detailsList.setVisibility(View.GONE); - emptyText.setVisibility(!isLoadingTorrent? View.VISIBLE: View.GONE); - loadingProgress.setVisibility(isLoadingTorrent? View.VISIBLE: View.GONE); + emptyText.setVisibility(!isLoadingTorrent ? View.VISIBLE : View.GONE); + loadingProgress.setVisibility(isLoadingTorrent ? View.VISIBLE : View.GONE); // Note: this.torrent is not cleared as we need to know later what the fragment was originally bound to torrentDetails = null; torrentFiles = null; @@ -170,7 +173,7 @@ public class DetailsFragment extends SherlockFragment { @Override public void onPrepareOptionsMenu(Menu menu) { super.onPrepareOptionsMenu(menu); - + if (torrent == null) { menu.findItem(R.id.action_resume).setVisible(false); menu.findItem(R.id.action_pause).setVisible(false); @@ -195,50 +198,50 @@ public class DetailsFragment extends SherlockFragment { menu.findItem(R.id.action_setlabel).setVisible(setLabel); boolean setTrackers = Daemon.supportsSetTrackers(torrent.getDaemon()); menu.findItem(R.id.action_updatetrackers).setVisible(setTrackers); - + } - @OptionsItem(resName="action_resume") + @OptionsItem(resName = "action_resume") protected void resumeTorrent() { getTasksExecutor().resumeTorrent(torrent); } - @OptionsItem(resName="action_pause") + @OptionsItem(resName = "action_pause") protected void pauseTorrent() { getTasksExecutor().pauseTorrent(torrent); } - @OptionsItem(resName="action_start_default") + @OptionsItem(resName = "action_start_default") protected void startTorrentDefault() { getTasksExecutor().startTorrent(torrent, false); } - @OptionsItem(resName="action_start_forced") + @OptionsItem(resName = "action_start_forced") protected void startTorrentForced() { getTasksExecutor().startTorrent(torrent, true); } - @OptionsItem(resName="action_stop") + @OptionsItem(resName = "action_stop") protected void stopTorrent() { getTasksExecutor().stopTorrent(torrent); } - @OptionsItem(resName="action_remove_default") + @OptionsItem(resName = "action_remove_default") protected void removeTorrentDefault() { getTasksExecutor().removeTorrent(torrent, false); } - @OptionsItem(resName="action_remove_withdata") + @OptionsItem(resName = "action_remove_withdata") protected void removeTorrentWithData() { getTasksExecutor().removeTorrent(torrent, true); } - @OptionsItem(resName="action_setlabel") + @OptionsItem(resName = "action_setlabel") protected void setLabel() { // TODO: Show label selection dialog } - @OptionsItem(resName="action_updatetrackers") + @OptionsItem(resName = "action_updatetrackers") protected void updateTrackers() { // TODO: Show trackers edit dialog } @@ -269,8 +272,8 @@ public class DetailsFragment extends SherlockFragment { // TODO: Start FTP download command for the selected torrents Crouton.showText(getActivity(), "TODO: Start FTP download command for the selected torrents", NavigationHelper.CROUTON_INFO_STYLE); - //for (TorrentFile file : checked) { - //} + // for (TorrentFile file : checked) { + // } mode.finish(); return true; } else { @@ -297,7 +300,8 @@ public class DetailsFragment extends SherlockFragment { && detailsList.getAdapter().getItem(detailsList.getCheckedItemPositions().keyAt(i)) instanceof TorrentFile) checkedCount++; } - mode.setTitle(getResources().getQuantityString(R.plurals.navigation_filesselected, checkedCount, checkedCount)); + mode.setTitle(getResources().getQuantityString(R.plurals.navigation_filesselected, checkedCount, + checkedCount)); } @Override @@ -319,5 +323,5 @@ public class DetailsFragment extends SherlockFragment { // NOTE: Assumes the activity implements all the required torrent tasks return (TorrentTasksExecutor) getActivity(); } - + } diff --git a/core/src/org/transdroid/core/gui/SearchHistoryProvider.java b/core/src/org/transdroid/core/gui/SearchHistoryProvider.java index a0391f96..4a85ebfa 100644 --- a/core/src/org/transdroid/core/gui/SearchHistoryProvider.java +++ b/core/src/org/transdroid/core/gui/SearchHistoryProvider.java @@ -5,22 +5,22 @@ import android.content.SearchRecentSuggestionsProvider; import android.provider.SearchRecentSuggestions; /** - * Provides search suggestions by simply returning previous user entries + * Provides search suggestions by simply returning previous user entries. * @author Eric Kok */ public class SearchHistoryProvider extends SearchRecentSuggestionsProvider { - public final static String AUTHORITY = "org.transdroid.core.gui.SearchHistoryProvider"; - public final static int MODE = DATABASE_MODE_QUERIES; + public final static String AUTHORITY = "org.transdroid.core.gui.SearchHistoryProvider"; + public final static int MODE = DATABASE_MODE_QUERIES; - public SearchHistoryProvider() { - super(); - setupSuggestions(AUTHORITY, MODE); - } - - public static void clearHistory(Context context) { - SearchRecentSuggestions suggestions = new SearchRecentSuggestions(context, - SearchHistoryProvider.AUTHORITY, SearchHistoryProvider.MODE); - suggestions.clearHistory(); - } + public SearchHistoryProvider() { + super(); + setupSuggestions(AUTHORITY, MODE); + } + + public static void clearHistory(Context context) { + SearchRecentSuggestions suggestions = new SearchRecentSuggestions(context, SearchHistoryProvider.AUTHORITY, + SearchHistoryProvider.MODE); + suggestions.clearHistory(); + } } diff --git a/core/src/org/transdroid/core/gui/TorrentsActivity.java b/core/src/org/transdroid/core/gui/TorrentsActivity.java index f54599d4..ae218244 100644 --- a/core/src/org/transdroid/core/gui/TorrentsActivity.java +++ b/core/src/org/transdroid/core/gui/TorrentsActivity.java @@ -83,6 +83,13 @@ import com.actionbarsherlock.widget.SearchView; import de.keyboardsurfer.android.widget.crouton.Crouton; +/** + * Main activity that holds the fragment that shows the torrents list, presents a way to filter the list (via an action + * bar spinner or list side list) and potentially shows a torrent details fragment too, if there is room. Task execution + * such as loading of and adding torrents is performs in this activity, using background methods. Finally, the activity + * offers navigation elements such as access to settings and showing connection issues. + * @author Eric Kok + */ @EActivity(resName = "activity_torrents") @OptionsMenu(resName = "activity_torrents") public class TorrentsActivity extends SherlockFragmentActivity implements OnNavigationListener, TorrentTasksExecutor { @@ -700,8 +707,9 @@ public class TorrentsActivity extends SherlockFragmentActivity implements OnNavi public void removeTorrent(Torrent torrent, boolean withData) { DaemonTaskResult result = RemoveTask.create(currentConnection, torrent, withData).execute(); if (result instanceof DaemonTaskResult) { - onTaskSucceeded((DaemonTaskSuccessResult) result, getString(withData ? R.string.result_removed_with_data - : R.string.result_removed, torrent.getName())); + onTaskSucceeded( + (DaemonTaskSuccessResult) result, + getString(withData ? R.string.result_removed_with_data : R.string.result_removed, torrent.getName())); } else { onCommunicationError((DaemonTaskFailureResult) result, false); } diff --git a/core/src/org/transdroid/core/gui/TorrentsFragment.java b/core/src/org/transdroid/core/gui/TorrentsFragment.java index 4d70e720..afdbccec 100644 --- a/core/src/org/transdroid/core/gui/TorrentsFragment.java +++ b/core/src/org/transdroid/core/gui/TorrentsFragment.java @@ -33,6 +33,12 @@ import com.actionbarsherlock.view.MenuItem; import com.actionbarsherlock.view.SherlockListView; import com.actionbarsherlock.view.SherlockListView.MultiChoiceModeListenerCompat; +/** + * Fragment that shows a list of torrents that are active on the server. It supports sorting and filtering and can show + * connection progress and issues. However, actual task starting and execution and overall navigation elements are part + * of the containing activity, not this fragment. + * @author Eric Kok + */ @EFragment(resName = "fragment_torrents") public class TorrentsFragment extends SherlockFragment { @@ -95,7 +101,7 @@ public class TorrentsFragment extends SherlockFragment { /** * Clears the currently visible list of torrents. - * @param b + * @param b */ public void clear(boolean clearError) { this.torrents = null;