Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 5352d237 authored by Scott Main's avatar Scott Main Committed by Android Git Automerger
Browse files

am 38137d7a: Merge "docs: lots of additions to the resources docs new drawable... 

am 38137d7a: Merge "docs: lots of additions to the resources docs new drawable resources add <merge> and <include> to layout resource update drawable class descriptioons to point to resources guide add ID resource type" into froyo

Merge commit '38137d7a' into gingerbread

* commit '38137d7a':
  docs: lots of additions to the resources docs
parents d6a85a21 38137d7a

core/java/android/view/View.java

+3 −1
Original line number Diff line number Diff line
@@ -7900,7 +7900,9 @@ public class View implements Drawable.Callback, KeyEvent.Callback, Accessibility 
     * without resorting to another data structure.

     *

     * The specified key should be an id declared in the resources of the

     * application to ensure it is unique. Keys identified as belonging to

     * application to ensure it is unique (see the <a

     * href={@docRoot}guide/topics/resources/more-resources.html#Id">ID resource type</a>).

     * Keys identified as belonging to

     * the Android framework or not associated with any package will cause

     * an {@link IllegalArgumentException} to be thrown.

     *

docs/html/guide/topics/resources/available-resources.jd

+0 −17
Original line number Diff line number Diff line
@@ -18,23 +18,6 @@ of application resource that you can provide in your resources directory ({@code 


<p>Here's a brief summary of each resource type:</p>



<div class="sidebox-wrapper">

<div class="sidebox">

<h2>{@code R.id} Is Not a Resource</h2>



<p>You will often use an {@code R.id} integer to handle {@link android.view.View} objects in

your UI. Although the {@code id} is a subclass of the {@code R} class, it is not considered a

"resource" because it is not a reference to an externalized application resource. The {@code id}

is simply a unique identifier that allows you to handle elements in your UI by instantiating

objects with {@link android.app.Activity#findViewById(int) findViewById()}.</p>



<p>For information about using {@code R.id} with your UI, see <a

href="{@docRoot}guide/topics/ui/declaring-layout.html#attributes">Declaring Layout</a>.</p>



</div>

</div>





<dl>

  <dt><a href="{@docRoot}guide/topics/resources/animation-resource.html">Animation Resources</a></dt>

    <dd>Define pre-determined animations.<br/>

docs/html/guide/topics/resources/drawable-resource.jd

+1177 −170

File changed.

Preview size limit exceeded, changes collapsed.

docs/html/guide/topics/resources/layout-resource.jd

+66 −15
Original line number Diff line number Diff line
@@ -35,12 +35,12 @@ In XML: <code>@[<em>package</em>:]layout/<em>filename</em></code> 
<pre class="stx">

&lt;?xml version="1.0" encoding="utf-8"?>

&lt;<a href="#viewgroup-element"><em>ViewGroup</em></a> xmlns:android="http://schemas.android.com/apk/res/android"

    android:id="@+id/<em>name</em>"

    android:id="@[+][<em>package</em>:]id/<em>resource_name</em>"

    android:layout_height=["<em>dimension</em>" | "fill_parent" | "wrap_content"]

    android:layout_width=["<em>dimension</em>" | "fill_parent" | "wrap_content"]

    [<em>ViewGroup-specific attributes</em>] &gt;

    &lt;<a href="#view-element"><em>View</em></a>

        android:id="@+id/<em>name</em>"

        android:id="@[+][<em>package</em>:]id/<em>resource_name</em>"

        android:layout_height=["<em>dimension</em>" | "fill_parent" | "wrap_content"]

        android:layout_width=["<em>dimension</em>" | "fill_parent" | "wrap_content"]

        [<em>View-specific attributes</em>] &gt;
@@ -49,10 +49,12 @@ In XML: <code>@[<em>package</em>:]layout/<em>filename</em></code> 
    &lt;<a href="#viewgroup-element"><em>ViewGroup</em></a> &gt;

        &lt;<a href="#view-element"><em>View</em></a> /&gt;

    &lt;/<em>ViewGroup</em>&gt;

    &lt;<a href="#include-element">include</a> layout="@layout/<i>layout_resource</i>"/&gt;

&lt;/<em>ViewGroup</em>&gt;

</pre>

<p class="note"><strong>Note:</strong> The root element can be either a

{@link android.view.ViewGroup} or a {@link android.view.View}, but there must be only

{@link android.view.ViewGroup}, a {@link android.view.View}, or a <a

href="#merge-element">{@code &lt;merge&gt;}</a> element, but there must be only

one root element and it must contain the {@code xmlns:android} attribute with the {@code android}

namespace as shown.</p>

</dd>
@@ -74,10 +76,9 @@ namespace as shown.</p> 
      <p class="caps">attributes:</p>

      <dl class="atn-list">

        <dt><code>android:id</code></dt>

        <dd><em>Resource name</em>. A unique resource name for the element, which you can

use to obtain a reference to the {@link android.view.ViewGroup} from your application.

          The value takes the form: <code>"@+id/<em>name</em>"</code>. See more about the

          <a href="#idvalue">value for {@code android:id}</a> below.

        <dd><em>Resource ID</em>. A unique resource name for the element, which you can

use to obtain a reference to the {@link android.view.ViewGroup} from your application. See more

about the <a href="#idvalue">value for {@code android:id}</a> below.

        </dd>

        <dt><code>android:layout_height</code></dt>

        <dd><em>Dimension or keyword</em>. <strong>Required</strong>. The height for the group, as a
@@ -107,10 +108,9 @@ attributes</a>).</p> 
      <p class="caps">attributes:</p>

      <dl class="atn-list">

        <dt><code>android:id</code></dt>

        <dd><em>Resource name</em>. A unique resource name for the element, which you can use to

          obtain a reference to the {@link android.view.View} from your application.

          The value takes the form: <code>"@+id/<em>name</em>"</code>. See more about the

          <a href="#idvalue">value for {@code android:id}</a> below.

        <dd><em>Resource ID</em>. A unique resource name for the element, which you can use to

          obtain a reference to the {@link android.view.View} from your application. See more about

the <a href="#idvalue">value for {@code android:id}</a> below.

        </dd>

        <dt><code>android:layout_height</code></dt>

        <dd><em>Dimension or keyword</em>. <strong>Required</strong>. The height for the element, as
@@ -137,20 +137,71 @@ or {@code "wrap_content"}). See the <a href="#layoutvalues">valid values</a> bel 
    which gives it's parent initial focus on the screen. You can have only one of these

    elements per file.</dd>



  <dt id="include-element"><code>&lt;include&gt;</code></dt>

    <dd>Includes a layout file into this layout.

      <p class="caps">attributes:</p>

      <dl class="atn-list">

        <dt><code>layout</code></dt>

        <dd><em>Layout resource</em>. <strong>Required</strong>. Reference to a layout

resource.</dd>

        <dt><code>android:id</code></dt>

        <dd><em>Resource ID</em>. Overrides the ID given to the root view in the included layout.

        </dd>

        <dt><code>android:layout_height</code></dt>

        <dd><em>Dimension or keyword</em>. Overrides the height given to the root view in the

included layout.

        </dd>

        <dt><code>android:layout_width</code></dt>

        <dd><em>Dimension or keyword</em>. Overrides the width given to the root view in the

included layout.

        </dd>

      </dl>

      <p>You can include any other layout attributes in the <code>&lt;include&gt;</code> that are

supported by the root element in the included layout and they will override those defined in the

root element.</p>



    <p>Another way to include a layout is to use {@link android.view.ViewStub}. It is a lightweight

View that consumes no layout space until you explicitly inflate it, at which point, it includes a

layout file defined by its {@code android:layout} attribute. For more information about using {@link

android.view.ViewStub}, read <a href="{@docRoot}resources/articles/layout-tricks-stubs.html">Layout

Tricks: ViewStubs</a>.</p>

    </dd>



  <dt id="merge-element"><code>&lt;merge&gt;</code></dt>

    <dd>An alternative root element that is not drawn in the layout hierarchy. Using this as the

root element is useful when you know that this layout will be placed into a layout

that already contains the appropriate parent View to contain the children of the

<code>&lt;merge&gt;</code> element. This is particularly useful when you plan to include this layout

in another layout file using <a href="#include-element"><code>&lt;include&gt;</code></a> and

this layout doesn't require a different {@link android.view.ViewGroup} container. For more

information about merging layouts, read <a

href="{@docRoot}resources/articles/layout-tricks-merging.html">Layout

Tricks: Merging</a>.</dd>



  </dl>







<h4 id="idvalue">Value for <code>android:id</code></h4>



<p>For the ID value, you should use this syntax form: <code>"@+id/<em>name</em>"</code>. The plus symbol,

{@code +}, indicates that this is a new resource ID and the aapt tool will create

a new resource number to the {@code R.java} class, if it doesn't already exist. For example:</p>

<p>For the ID value, you should usually use this syntax form: <code>"@+id/<em>name</em>"</code>. The

plus symbol, {@code +}, indicates that this is a new resource ID and the <code>aapt</code> tool will

create a new resource integer in the {@code R.java} class, if it doesn't already exist. For

example:</p>

<pre>

&lt;TextView android:id="@+id/nameTextbox"/>

</pre>

<p>You can then refer to it this way in Java:</p>

<p>The <code>nameTextbox</code> name is now a resource ID attached to this element. You can then

refer to the {@link android.widget.TextView} to which the ID is associated in Java:</p>

<pre>

findViewById(R.id.nameTextbox);

</pre>

<p>This code returns the {@link android.widget.TextView} object.</p>



<p>However, if you have already defined an <a

href="{@docRoot}guide/topics/resources/drawable-resource.html#Id">ID resource</a> (and it is not

already used), then you can apply that ID to a {@link android.view.View} element by excluding the

plus symbol in the <code>android:id</code> value.</p>



<h4 id="layoutvalues">Value for <code>android:layout_height</code> and

<code>android:layout_width</code>:</h4>

docs/html/guide/topics/resources/menu-resource.jd

+6 −6
Original line number Diff line number Diff line
@@ -35,7 +35,7 @@ In XML: <code>@[<em>package</em>:]menu.<em>filename</em></code> 
<pre>

&lt;?xml version="1.0" encoding="utf-8"?>

&lt;<a href="#menu-element">menu</a> xmlns:android="http://schemas.android.com/apk/res/android">

    &lt;<a href="#item-element">item</a> android:id="@+id/<em>id_name</em>"

    &lt;<a href="#item-element">item</a> android:id="@[+][<em>package</em>:]id/<em>resource_name</em>"

          android:menuCategory=["container" | "system" | "secondary" | "alternative"]

          android:orderInCategory="<em>integer</em>"

          android:title="<em>string</em>"
@@ -46,7 +46,7 @@ In XML: <code>@[<em>package</em>:]menu.<em>filename</em></code> 
          android:checkable=["true" | "false"]

          android:visible=["visible" | "invisible" | "gone"]

          android:enabled=["enabled" | "disabled"] /&gt;

    &lt;<a href="#group-element">group</a> android:id="<em>resource ID</em>"

    &lt;<a href="#group-element">group</a> android:id="@[+][<em>package</em>:]id/<em>resource name</em>"

           android:menuCategory=["container" | "system" | "secondary" | "alternative"]

           android:orderInCategory="<em>integer</em>"

           android:checkableBehavior=["none" | "all" | "single"]
@@ -84,8 +84,8 @@ child of a <code>&lt;menu&gt;</code> element. 
      <p class="caps">attributes:</p>

      <dl class="atn-list">

        <dt><code>android:id</code></dt>

        <dd><em>Resource name</em>. A unique resource name. The value takes the form:

<code>"@+id/<em>name</em>"</code>.</dd>

        <dd><em>Resource ID</em>. A unique resource ID. To create a new resource ID for this item, use the form:

<code>"@+id/<em>name</em>"</code>. The plus symbol indicates that this should be created as a new ID.</dd>

        <dt><code>android:menuCategory</code></dt>

          <dd><em>Keyword</em>. Value corresponding to {@link android.view.Menu} {@code CATEGORY_*}

          constants, which define the group's priority. Valid values:
@@ -124,8 +124,8 @@ on the data that is currently displayed.</td></tr> 
      <p class="caps">attributes:</p>

      <dl class="atn-list">

        <dt><code>android:id</code></dt>

        <dd><em>Resource name</em>. A unique resource name. The value takes the form:

<code>"@+id/<em>name</em>"</code>.</dd>

        <dd><em>Resource ID</em>. A unique resource ID. To create a new resource ID for this item, use the form:

<code>"@+id/<em>name</em>"</code>. The plus symbol indicates that this should be created as a new ID.</dd>

        <dt><code>android:menuCategory</code></dt>

          <dd><em>Keyword</em>. Value corresponding to {@link android.view.Menu} {@code CATEGORY_*}

          constants, which define the item's priority. Valid values: