Skip to content

Commit

Permalink
Large documentation changes
Browse files Browse the repository at this point in the history 
The entire GreenDroid documentation has been reviewed. The main purpose is to create and maintain an online reference for the library.
  • Loading branch information
Cyril Mottier committed Oct 4, 2011
1 parent 2fc5128 commit 85295d6
Show file tree
Hide file tree
Showing 46 changed files with 1,063 additions and 369 deletions.
21 changes: 11 additions & 10 deletions GreenDroid/src/greendroid/app/ActionBarActivity.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,6 @@
import greendroid.widget.ActionBar;
import greendroid.widget.ActionBarItem;
import android.app.Activity;
import android.app.Application;
import android.view.View;
import android.widget.FrameLayout;

Expand Down Expand Up @@ -62,8 +61,8 @@ public interface ActionBarActivity {

/**
* Returns the content view. Please note the content view is not the entire
* view but a {@link FrameLayout} that contains everything but the
* {@link ActionBar}.
* view but a FrameLayout that contains everything but the {@link ActionBar}
* .
*
* @return The content view
*/
Expand All @@ -75,16 +74,16 @@ public interface ActionBarActivity {
* {@link ActionBarActivity#onHandleActionBarItemClick(ActionBarItem, int)}
* method. Most of the time, this method don't need to be used directly.
*
* @see {@link ActionBarActivity#onHandleActionBarItemClick(ActionBarItem, int)}
* @see {@link ActionBarActivity#addActionBarItem(ActionBarItem)}
* @see {@link ActionBarActivity#addActionBarItem(greendroid.widget.ActionBarItem.Type)}
* @see ActionBarActivity#onHandleActionBarItemClick(ActionBarItem, int)
* @see ActionBarActivity#addActionBarItem(ActionBarItem)
* @see ActionBarActivity#addActionBarItem(greendroid.widget.ActionBarItem.Type)
* @return The {@link ActionBar} currently displayed on screen
*/
ActionBar getActionBar();

/**
* A simple utility method that casts the {@link Application} returned by
* {@link #getApplication()} into a {@link GDApplication}
* A simple utility method that casts the Application returned by
* Activity.getApplication() into a {@link GDApplication}
*
* @return The current {@link GDApplication}
*/
Expand All @@ -107,14 +106,16 @@ public interface ActionBarActivity {
ActionBarItem addActionBarItem(ActionBarItem item, int itemId);

/**
* Adds a new item of type <em>type</em> to the {@link ActionBar}.
* Adds a new item of the given {@link ActionBar.Type} to the
* {@link ActionBar}.
*
* @param actionBarItemType The item to add to the {@link ActionBar}
*/
ActionBarItem addActionBarItem(ActionBarItem.Type actionBarItemType);

/**
* Adds a new item of type <em>type</em> to the {@link ActionBar}.
* Adds a new item of the given {@link ActionBar.Type} to the
* {@link ActionBar}.
*
* @param actionBarItemType The item to add to the {@link ActionBar}
* @param itemId Unique item ID. Use {@link ActionBar#NONE} if you do not
Expand Down
137 changes: 112 additions & 25 deletions GreenDroid/src/greendroid/app/GDActivity.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,13 +36,12 @@

/**
* <p>
* An {@link GDActivity} is a regular Activity that always hosts an
* {@link ActionBar}. It is extremely simple to use as you have nothing
* particular to do. Indeed, the ActionBar is automatically added to your own
* layout when using the {@link #getContentView()} method. You can also use one
* of the setActionBarContentView utility methods. As a result, a basic
* {@link GDActivity} will often be initialized using the following snippet of
* code:
* An GDActivity is a regular Activity that hosts an {@link ActionBar}. It is
* extremely simple to use as you have nothing particular to do. Indeed, the
* {@link ActionBar} is automatically added to your own layout when using the
* {@link #getContentView()} method. You can also use one of the
* setActionBarContentView utility methods. As a result, a basic GDActivity will
* often be initialized using the following snippet of code:
* </p>
*
* <pre>
Expand All @@ -53,9 +52,9 @@
* }
* </pre>
* <p>
* An ActionBar is a widget that may contains actions items and a title. You can
* also set the title putting an extra string with the key
* {@link GD_ACTION_BAR_TITLE} in your Intent:
* An {@link ActionBar} is a widget that may contains actions items and a title.
* You can also set the title putting an extra string with the key
* {@link ActionBarActivity#GD_ACTION_BAR_TITLE} in your Intent:
* </p>
*
* <pre>
Expand All @@ -64,10 +63,11 @@
* startActivity(intent);
* </pre>
* <p>
* Note: An {@link GDActivity} automatically handle the type of the ActionBar
* (Dashboard or Normal) depending on the value returned by the
* getHomeActivityClass of your {@link GDApplication}. However you can force the
* type of the action bar in your constructor.
* <em><strong>Note</strong>: An GDActivity automatically handle the type of the {@link ActionBar}
* (taken from {@link ActionBar.Type}) depending on the value returned by the
* {@link GDApplication#getHomeActivityClass()} method. However you can force the
* type of the action bar in your constructor. Make the Activity declared in the AndroidManifest.xml
* has at least a constructor with no arguments as required by the Android platform.</em>
* </p>
*
* <pre>
Expand All @@ -76,16 +76,17 @@
* }
* </pre>
* <p>
* All Activities that inherits from an {@link GDActivity} are notified when an
* action button is tapped in the onHandleActionBarItemClick(ActionBarItem, int)
* method. By default this method does nothing but return false.
* All Activities that inherits from an GDActivity are notified when an action
* button is tapped in the
* {@link #onHandleActionBarItemClick(ActionBarItem, int)} method. By default
* this method does nothing but return false.
* </p>
*
* @see {@link GDApplication#getHomeActivityClass()}
* @see {@link ActionBarActivity#GD_ACTION_BAR_TITLE}
* @see {@link GDActivity#setActionBarContentView(int)}
* @see {@link GDActivity#setActionBarContentView(View)}
* @see {@link GDActivity#setActionBarContentView(View, LayoutParams)}
* @see GDApplication#getHomeActivityClass()
* @see ActionBarActivity#GD_ACTION_BAR_TITLE
* @see GDActivity#setActionBarContentView(int)
* @see GDActivity#setActionBarContentView(View)
* @see GDActivity#setActionBarContentView(View, LayoutParams)
* @author Cyril Mottier
*/
public class GDActivity extends Activity implements ActionBarActivity {
Expand All @@ -97,11 +98,33 @@ public class GDActivity extends Activity implements ActionBarActivity {
private Type mActionBarType;
private ActionBarHost mActionBarHost;

/**
* <p>
* Default constructor.
* </p>
* <p>
* <em><strong>Note</strong>: This constructor should never be used manually.
* In order to instantiate an Activity you should let the Android system do
* it for you by calling startActivity(Intent)</em>
* </p>
*/
public GDActivity() {
this(Type.Normal);
mDefaultConstructorUsed = true;
}

/**
* <p>
* Create a new Activity with an {@link ActionBar} of the given type.
* </p>
* <p>
* <em><strong>Note</strong>: This constructor should never be used manually.
* In order to instantiate an Activity you should let the Android system do
* it for you by calling startActivity(Intent)</em>
* </p>
*
* @param actionBarType The {@link ActionBar.Type} for this Activity
*/
public GDActivity(ActionBar.Type actionBarType) {
super();
mActionBarType = actionBarType;
Expand All @@ -118,7 +141,7 @@ protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);

if (mDefaultConstructorUsed) {
// HACK cyril: This should have been done is the default
// HACK cyril: This should have been done in the default
// constructor. Unfortunately, the getApplication() method returns
// null there. Hence, this has to be done here.
if (getClass().equals(getGDApplication().getHomeActivityClass())) {
Expand All @@ -133,6 +156,12 @@ protected void onPostCreate(Bundle savedInstanceState) {
ensureLayout();
}

/**
* The current {@link ActionBar.Type} of the hosted {@link ActionBar}
*
* @return The current {@link ActionBar.Type} of the hosted
* {@link ActionBar}
*/
public ActionBar.Type getActionBarType() {
return mActionBarType;
}
Expand All @@ -149,12 +178,25 @@ public int createLayout() {
}
}

/**
* Call this method to ensure a layout has already been inflated and
* attached to the top-level View of this Activity.
*/
protected void ensureLayout() {
if (!verifyLayout()) {
setContentView(createLayout());
}
}

/**
* Verify the given layout contains everything needed by this Activity. A
* GDActivity, for instance, manages an {@link ActionBarHost}. As a result
* this method will return true of the current layout contains such a
* widget.
*
* @return true if the current layout fits to the current Activity widgets
* requirements
*/
protected boolean verifyLayout() {
return mActionBarHost != null;
}
Expand All @@ -174,8 +216,7 @@ public void onContentChanged() {
public void onPreContentChanged() {
mActionBarHost = (ActionBarHost) findViewById(R.id.gd_action_bar_host);
if (mActionBarHost == null) {
throw new RuntimeException(
"Your content must have an ActionBarHost whose id attribute is R.id.gd_action_bar_host");
throw new RuntimeException("Your content must have an ActionBarHost whose id attribute is R.id.gd_action_bar_host");
}
mActionBarHost.getActionBar().setOnActionBarListener(mActionBarListener);
}
Expand Down Expand Up @@ -246,18 +287,64 @@ public FrameLayout getContentView() {
return mActionBarHost.getContentView();
}

/**
* <p>
* Set the activity content from a layout resource. The resource will be
* inflated, adding all top-level views to the activity.
* </p>
* <p>
* This method is an equivalent to setContentView(int) that automatically
* wraps the given layout in an {@link ActionBarHost} if needed..
* </p>
*
* @param resID Resource ID to be inflated.
* @see #setActionBarContentView(View)
* @see #setActionBarContentView(View, LayoutParams)
*/
public void setActionBarContentView(int resID) {
final FrameLayout contentView = getContentView();
contentView.removeAllViews();
LayoutInflater.from(this).inflate(resID, contentView);
}

/**
* <p>
* Set the activity content to an explicit view. This view is placed
* directly into the activity's view hierarchy. It can itself be a complex
* view hierarchy.
* </p>
* <p>
* This method is an equivalent to setContentView(View, LayoutParams) that
* automatically wraps the given layout in an {@link ActionBarHost} if
* needed.
* </p>
*
* @param view The desired content to display.
* @param params Layout parameters for the view.
* @see #setActionBarContentView(View)
* @see #setActionBarContentView(int)
*/
public void setActionBarContentView(View view, LayoutParams params) {
final FrameLayout contentView = getContentView();
contentView.removeAllViews();
contentView.addView(view, params);
}

/**
* <p>
* Set the activity content to an explicit view. This view is placed
* directly into the activity's view hierarchy. It can itself be a complex
* view hierarchy.
* </p>
* <p>
* This method is an equivalent to setContentView(View) that automatically
* wraps the given layout in an {@link ActionBarHost} if needed.
* </p>
*
* @param view The desired content to display.
* @see #setActionBarContentView(int)
* @see #setActionBarContentView(View, LayoutParams)
*/
public void setActionBarContentView(View view) {
final FrameLayout contentView = getContentView();
contentView.removeAllViews();
Expand Down
Loading

0 comments on commit 85295d6

Please sign in to comment.