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

Commit dfe5c204 authored by Scott Main's avatar Scott Main
Browse files

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

Change-Id: I733eec50bb2671f28c9e6dd7dec14eb6586f5193
parent 457738e6

core/java/android/view/View.java

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

     * without resorting to another data structure.

     *

     *

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

     * 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

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

     * an {@link IllegalArgumentException} to be thrown.

     * an {@link IllegalArgumentException} to be thrown.

     *

     *

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

+0 −17
Original line number Original line 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>

<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>

<dl>

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

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

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

    <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 Original line Diff line number Diff line
@@ -35,12 +35,12 @@ In XML: <code>@[<em>package</em>:]layout/<em>filename</em></code> 
<pre class="stx">

<pre class="stx">

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

&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"

&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_height=["<em>dimension</em>" | "fill_parent" | "wrap_content"]

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

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

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

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

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

    &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_height=["<em>dimension</em>" | "fill_parent" | "wrap_content"]

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

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

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

        [<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="#viewgroup-element"><em>ViewGroup</em></a> &gt;

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

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

    &lt;/<em>ViewGroup</em>&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;

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

</pre>

</pre>

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

<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}

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

namespace as shown.</p>

namespace as shown.</p>

</dd>

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

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

      <dl class="atn-list">

      <dl class="atn-list">

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

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

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

        <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.

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

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

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

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

        </dd>

        </dd>

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

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

        <dd><em>Dimension or keyword</em>. <strong>Required</strong>. The height for the group, as a

        <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>

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

      <dl class="atn-list">

      <dl class="atn-list">

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

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

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

        <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.

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

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

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

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

        </dd>

        </dd>

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

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

        <dd><em>Dimension or keyword</em>. <strong>Required</strong>. The height for the element, as

        <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

    which gives it's parent initial focus on the screen. You can have only one of these

    elements per file.</dd>

    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>

      </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>

<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,

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

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

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

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

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

example:</p>

<pre>

<pre>

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

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

</pre>

</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>

<pre>

findViewById(R.id.nameTextbox);

findViewById(R.id.nameTextbox);

</pre>

</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

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

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

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

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

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

<pre>

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

&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="#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:menuCategory=["container" | "system" | "secondary" | "alternative"]

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

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

          android:title="<em>string</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:checkable=["true" | "false"]

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

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

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

          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:menuCategory=["container" | "system" | "secondary" | "alternative"]

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

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

           android:checkableBehavior=["none" | "all" | "single"]

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

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

      <dl class="atn-list">

      <dl class="atn-list">

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

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

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

        <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>.</dd>

<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>

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

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

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

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

          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>

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

      <dl class="atn-list">

      <dl class="atn-list">

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

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

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

        <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>.</dd>

<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>

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

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

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

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

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