Available Resource Types

This page describes the different types of resources that you can externalize from your code and package with your application.

For more details on how to use resources in your application, please see the Resources and Internationalization documentation.

Simple Values

All simple resource values can be expressed as a string, using various formats to unambiguously indicate the type of resource being created. For this reason, these values can be defined both as standard resources (under res/values/), as well as direct values supplied for mappings in styles and themes, and attributes in XML files such as layouts.

Color Values

A color value specifies an RGB value with an alpha channel, which can be used in various places such as specifying a solid color for a Drawable or the color to use for text. A color value always begins with a pound (#) character and then followed by the Alpha-Red-Green-Blue information in one of the following formats:

• #RGB
• #ARGB
• #RRGGBB
• #AARRGGBB

#RGB
#ARGB
#RRGGBB
#AARRGGBB

If you want to retrieve the color represented by a resource ID, you can call the Resources.getColor() method.

Source file format: XML file requiring a <?xml version="1.0" encoding="utf-8"?> declaration, and a root <resources> element containing one or more <color> tags.

Resource source file location: res/values/colors.xml (File name is arbitrary.)

Compiled resource datatype: Resource pointer to a Java int.

Resource reference name:

• Java: R.color.some_name
• XML: @[package:]color/some_name (where some_name is the name of a specific color)

Java: R.color.some_name
XML: @[package:]color/some_name (some_name은 특정 컬러명임)

Syntax

<color name=color_name>#color_value</color>

<color>

Value is a color, using web-style syntax, as describe above. Has only one attribute:

• name - The name used in referring to this color.

<color>

값은 위에서 설명한 것처럼 웹 스타일 구문을 사용하는 컬러이며 오직 하나의 애트리뷰트만을 가진다.

• name - 이 컬러를 가리키는데 사용되는 이름.

Example XML Declaration

The following code declares two colors, the first fully opaque, and the second translucent.

<resources>
   <color name="opaque_red">#f00</color>
   <color name="translucent_red">#80ff0000</color>
</resources>

Example Code Use

Example Java code

// Retrieve a color value.
int color = getResources.getColor(R.color.opaque_red);

Example XML code

<TextView android:layout_width="fill_parent"
          android:layout_height="wrap_content"
          android:textAlign="center"
          android:textColor="@color/translucent_red"
          android:text="Some Text"/>

Strings and Styled Text

Strings, with optional simple formatting, can be stored and retrieved as resources. You can add formatting to your string by using three standard HTML tags: <b>, <i>, and <u>. To guarantee getting an unstyled string only (the raw text) call the toString() method of the retrieved CharSequence object. Methods that accept string resources should be able to process these styling tags.

If you want to retrieve the String represented by a resource ID, you can call the Context.getString() method.

Note: If you use an apostrophe or a quote in your string, you must either escape it or enclose the whole string in the other kind of enclosing quotes:

<string name="good_example">"This'll work"</string>
<string name="good_example_2">This\'ll also work</string>
<string name="bad_example">This won't work!</string>
<string name="bad_example_2">XML encodings won&apos;t work either!</string>

Source file format: XML file requiring a <?xml version="1.0" encoding="utf-8"?> declaration, and a root <resources> element containing one or more <string> tags.

Resource source file location: res/values/strings.xml (File name is arbitrary.)

Compiled resource datatype: Resource pointer to a Java CharSequence.

Resource reference name:

• Java: R.string.some_name
• XML: @[package:]string/some_name (where some_name is the name of a specific string)

Java: R.string.some_name
XML: @[package:]string/some_name (some_name 은 특정 문자열의 이름임)

Syntax

<string name=string_name>string_value</string>

<string>

Value is a string, with optional styling tags. Has only one attribute:

• name - The name used in referring to this string.

<string>

값은 선택사항으로 스타일링 태그를 가지는 문자열이며 오직 하나의 애트리뷰트를 가진다.

• name - 이 문자열을 가리키는데 사용되는 이름.

Example XML Declaration

The following declares two strings: the first simple text with no formatting (resulting in a CharSequence that is simply a String object) the second includes formatting information in the string (resulting in a CharSequence that is a complex data structure). If you are using the custom editor for string files in Eclipse, the HTML formatting tags will automatically be escaped and you will need to use Context.getString() and fromHtml(String) to retreive the resource and then convert it to formatted text.

<resources>
   <string name="simple_welcome_message">Welcome!</string>
   <string name="styled_welcome_message">We are <b><i>so</i></b> glad to see you.</string>
</resources>

Example Code Use

Example Java code

// Assign a styled string resource to a TextView
// on the current screen.
CharSequence str = getString(R.string.styled_welcome_message);
TextView tv = (TextView)findViewByID(R.id.text);
tv.setText(str);

Example XML code

<TextView android:layout_width="fill_parent"
          android:layout_height="wrap_content"
          android:textAlign="center"
          android:text="@string/simple_welcome_message"/> 

Using Styled Text as a Format String

Sometimes you may want to create a styled text resource that is also used as a format string. This cannot be done directly because there is no way of passing the styled text as the format string argument of String.format() without stripping out the style information. The workaround is to store the style tags as escaped HTML tags, and then convert the escaped HTML string into a styled text after formatting has taken place.

To use styled text as a format string, do the following.

1. Store your styled text resource as an escaped string, so that the HTML tags in your text resource are not interpreted as if they were XML tags:

   <resources>
     <string name="search_results_resultsTextFormat">%1$d results for &lt;b>&amp;quot;%2$s&amp;quot;&lt;/b></string>
   </resources>
   

   In this example the format string has two arguments: %1$d is a decimal number, %2$s is a string.

2. Make sure any String arguments are properly escaped if they might contain '<' or '&' characters. The htmlEncode(String) method will do this:

   String escapedTitle = TextUtil.htmlEncode(title);
   

3. Use String.format() to format the HTML text, then use fromHtml(String) to convert the HTML text into styled text:

   String resultsTextFormat = getContext().getResources().getString(R.string.search_results_resultsTextFormat);
   String resultsText = String.format(resultsTextFormat, count, escapedTitle);
   CharSequence styledResults = Html.fromHtml(resultsText);
   

여러분의 텍스트 리소스에 있는 HTML 태그들이 마치 XML 태크인 것처럼 해석되지 않도록 하기 위해, 이스케이프된escaped 문자열로 여러분의 스타일이 있는 텍스트를 저장하라.

<resources>
  <string name="search_results_resultsTextFormat">%1$d results for &lt;b>&amp;quot;%2$s&amp;quot;&lt;/b></string>
</resources>

이 예제에서 포맷 문자열은 두 개의 아규먼트를 가진다. %1$d는 숫자, %2$s는 문자열임.

만약 문자열 아규먼트들이 ‘<’ 또는 ‘&’ 문자를 포함한다면, 그 문자열 아규먼트들이 적절하게 이스케이프escape 되도록 하라. htmlEncode(String) 메쏘드는 이것을 할 것이다.

String escapedTitle = TextUtil.htmlEncode(title);

HTML 텍스트를 포맷하기 위해 String.format()을 사용하라. 그리고 나서 HTML 텍스트를 스타일을 가진 텍스트로 변환하기 위해 fromHtml (String)을 사용하라.

String resultsTextFormat = getContext().getResources().getString(R.string.search_results_resultsTextFormat);
String resultsText = String.format(resultsTextFormat, count, escapedTitle);
CharSequence styledResults = Html.fromHtml(resultsText);

Dimension Values

You can create common dimensions to use for various screen elements by defining dimension values in XML. A dimension resource is a number followed by a unit of measurement. For example: 10px, 2in, 5sp. Here are the units of measurement supported by Android:

px

Pixels - corresponds to actual pixels on the screen.

in

Inches - based on the physical size of the screen.

mm

Millimeters - based on the physical size of the screen.

pt

Points - 1/72 of an inch based on the physical size of the screen.

dp

Density-independent Pixels - an abstract unit that is based on the physical density of the screen. These units are relative to a 160 dpi screen, so one dp is one pixel on a 160 dpi screen. The ratio of dp-to-pixel will change with the screen density, but not necessarily in direct proportion. Note: The compiler accepts both "dip" and "dp", though "dp" is more consistent with "sp".

sp

Scale-independent Pixels - this is like the dp unit, but it is also scaled by the user's font size preference. It is recommend you use this unit when specifying font sizes, so they will be adjusted for both the screen density and user's preference.

px

픽셀 - 스크린 상의 실제 픽셀에 대응한다.

in

인치 ? 스크린의 물리적 크기에 기반한다.

mm

밀리미터 - 스크린의 물리적 크기에 기반한다.

pt

포인트 - 스크린의 물리적 크기에 기반한 인치(inch)의 1/72.

dp

밀도 독립적 픽셀Density-independent Pixels - 스크린의 물리적 밀도에 기반한 추상적 단위. 이 단위는 160 dpi의 스크린에 비례한다. 그래서 1 dp는 160 dpi 스크린 상의 1 픽셀이다. dp-to-pixel 비율은 스크린 밀도에 따라 변할 것이다. 하지만 반드시 정비례는 아니다. 주의: “dp”가 “sp”와 더 잘 맞음에도 불구하고, 컴파일러는 “dip”와 “dp” 모두를 허용한다.

sp

스케일 독립적 픽셀Scale-independent Pixels - 이것은 dp 단위와 같다. 그러나 이것은 또한 사용자의 폰트 크기 설정에 의해 스케일된다. 여러분이 폰트 크기를 지정할 때 이 단위를 사용할 것을 권장한다. 따라서 폰트 크기는 스크린 밀도와 사용자 설정 모두에 대해서 조정될 것이다.

Dimension values are not normally used as raw resources, but rather as attribute values in XML files. You can, however, create plain resources containing this data type.

Source file format: XML file requiring a <?xml version="1.0" encoding="utf-8"?> declaration, and a root <resources> element containing one or more <dimen> tags.

Resource source file location: res/values/dimens.xml (File name is arbitrary, but standard practice is to put all dimensions in one file devoted to dimensions.)

Compiled resource datatype: Resource pointer to a dimension.

Resource reference name:

• Java: R.dimen.some_name
• XML: @[package:]dimen/some_name (where some_name is the name of a specific <dimen> element)

Java: R.dimen.some_name
XML: @[package:]dimen/some_name (some_name 은 특정 <dimen> 엘리먼트임)

Syntax

<dimen name=dimen_name>dimen_value</dimen>

<dimen>

A valid dimension value.

• name - The name used in referring to this dimension.

<dimen>

유효한 치수 값.

• name - 이 치수를 가리키는데 사용되는 이름.

Example XML Declaration

The following code declares several dimension values.

<resources>
    <dimen name="one_pixel">1px</dimen>
    <dimen name="double_density">2dp</dimen>
    <dimen name="sixteen_sp">16sp</dimen>
</resources>

Example Code Use

Example Java code:

float dimen = Resources.getDimen(R.dimen.one_pixel);

Example XML code:

<TextView android:layout_width="fill_parent"
          android:layout_height="wrap_content"
          android:textSize="@dimen/sixteen_sp"/>

Drawables

A Drawable is a type of resource that you retrieve with Resources.getDrawable() and use to draw to the screen. There are a number of drawable resources that can be created.

Bitmap Files

Android supports bitmap resource files in a few different formats: png (preferred), jpg (acceptable), gif (discouraged). The bitmap file itself is compiled and referenced by the file name without the extension (so res/drawable/my_picture.png would be referenced as R.drawable.my_picture).

Source file formats: png (preferred), jpg (acceptable), gif (discouraged). One resource per file.

Resource file location: res/drawable/some_file.png

Compiled resource datatype: Resource pointer to a BitmapDrawable.

Resource reference name:

• Java: R.drawable.some_file
• XML: @[package:]drawable/some_file

Java: R.drawable.some_file
XML: @[package:]drawable/some_file

For more discussion and examples using drawable resources, see the discussion in 2D Graphics.

Color Drawables

You can create a PaintDrawable object that is a rectangle of color, with optionally rounded corners. This element can be defined in any of the files inside res/values/.

Source file format: XML file requiring a <?xml version="1.0" encoding="utf-8"?> declaration, and a root <resources> element containing one or more <drawable> tags.

Resource source file location: res/values/colors.xml (File name is arbitrary, but standard practice is to put the PaintDrawable items in the file along with the numeric color values.)

Compiled resource datatype: Resource pointer to a PaintDrawable.

Resource reference name:

• Java: R.drawable.some_name
• XML: @[package:]drawable/some_name (where some_name is the name of a specific resource)

Java: R.drawable.some_name
XML: @[package:]drawable/some_name (some_name은 특정 리소스의 이름임)

Syntax

<drawable name=color_name>color_value</drawable>

<drawable>

A valid color value.

• name - The name used in referring to this drawable.

<drawable>

유효한 컬러 값.

• name - 이 드로어블drawable을 가리키는데 사용되는 이름.

Example XML Declaration

The following code declares several color drawables.

<resources>
    <drawable name="solid_red">#f00</drawable>
    <drawable name="solid_blue">#0000ff</drawable>
    <drawable name="solid_green">#f0f0</drawable>
</resources>

Example Code Use

Example Java code

// Assign a PaintDrawable as the background to
// a TextView on the current screen.
Drawable redDrawable = Resources.getDrawable(R.drawable.solid_red);
TextView tv = (TextView)findViewByID(R.id.text);
tv.setBackground(redDrawable);

Example XML code

<TextView android:layout_width="fill_parent"
          android:layout_height="wrap_content"
          android:textAlign="center"
          android:background="@drawable/solid_red"/>

Nine-Patch (stretchable) Images

Android supports a stretchable bitmap image, called a NinePatch graphic. This is a PNG image in which you define stretchable sections that Android will resize to fit the object at display time to accommodate variable sized sections, such as text strings. You typically assign this resource to the View's background. An example use of a stretchable image is the button backgrounds that Android uses; buttons must stretch to accommodate strings of various lengths.

Source file format: PNG one resource per file

Resource source file location: res/drawable/some_name.9.png (Filename must end in .9.png)

Compiled resource datatype: Resource pointer to a NinePatchDrawable.

Resource reference name:

• Java: R.drawable.some_file
• XML: @[package:]drawable.some_file

Java: R.drawable.some_file
XML: @[package:]drawable.some_file

For more information and examples using NinePatch drawables, see the discussion in 2D Graphics.

Animation

Tweened Animation

Android can perform simple animation on a graphic, or a series of graphics. These include rotations, fading, moving, and stretching.

Source file format: XML file, one resource per file, one root tag with no <?xml> declaration

Resource file location: res/anim/some_file.xml

Compiled resource datatype: Resource pointer to an Animation.

Resource reference name:

• Java: R.anim.some_file
• XML: @[package:]anim/some_file

Java: R.anim.some_file
XML: @[package:]anim/some_file

Syntax

The file must have a single root element: this will be either a single <alpha>, <scale>, <translate>, <rotate>, interpolator element, or <set> element that holds groups of these elements (which may include another <set>). By default, all elements are applied simultaneously. To have them occur sequentially, you must specify the startOffset attribute.

<set android:shareInterpolator=boolean>  // Only required if multiple tags are used.
   <alpha android:fromAlpha=float
          android:toAlpha=float >   |
   <scale android:fromXScale=float
          android:toXScale=float
          android:fromYScale=float
          android:toYScale=float
          android:pivotX=string
          android:pivotY=string >    |
   <translate android:fromX=string
              android:toX=string
              android:fromY=string
              android:toY=string >   |
   <rotate android:fromDegrees=float
           android:toDegrees=float
           android:pivotX=string
           android:pivotY=string > |
   <interpolator tag>
   <set>
</set>

Elements and Attributes

<set>

A container that can recursively hold itself or other animations. Represents an AnimationSet. You can include as many child elements of the same or different types as you like. Supports the following attribute:

• shareInterpolator - Whether to share the same Interpolator among all immediate child elements.

<alpha>

A fading animation. Represents an AlphaAnimation. Supports the following attributes:

• fromAlpha - 0.0 to 1.0, where 0.0 is transparent.
• toAlpha - 0.0 to 1.0, where 0.0 is transparent.

<scale>

A resizing animation. Represents a ScaleAnimation. You can specify what is the center point of the image (the pinned center), from which it grows outward (or inward), by specifying pivotX and pivotY. So, for example, if these were 0, 0 (top left corner), all growth would be down and to the right. scale supports the following attributes:

• fromXScale - Starting X size, where 1.0 is no change.
• toXScale - Ending X size, where 1.0 is no change.
• fromYScale - Starting Y size, where 1.0 is no change.
• toYScale - Ending Y size, where 1.0 is no change.
• pivotX - The X coordinate of the pinned center.
• pivotY - The Y coordinate of the pinned center.

<translate>

A vertical/horizontal motion animation. Represents a TranslateAnimation. Supports the following attributes in any of the following three formats: values from -100 to 100, ending with "%", indicating a percentage relative to itself; values from -100 to 100, ending in "%p", indicating a percentage relative to its parent; a float with no suffix, indicating an absolute value.

• fromXDelta - Starting X location.
• toXDelta - Ending X location.
• fromYDelta - Starting Y location.
• toYDelta - Ending Y location.

<rotate>

A rotation animation. Represents a RotateAnimation. Supports the following attributes:

• fromDegrees - Starting rotation, in degrees.
• toDegrees - Ending rotation, in degrees.
• pivotX - The X coordinate of the center of rotation, in pixels, where (0,0) is the top left corner.
• pivotY - The Y coordinate of the center of rotation, in pixels, where (0,0) is the top left corner.

<interpolator tag>

You can also use any of the interpolator subclass elements defined in R.styleable. Examples include <CycleInterpolator>, <EaseInInterpolator>, and <EaseOutInterpolator>. These objects define a velocity curve that describes how quickly a visual action takes place on a timeline (fast at first and slow later, slow at first and gradually faster, and so on).

<set>

자기 자신 또는 다른 애니메이션을 재귀적으로 보유할 수 있는 컨테이너. AnimationSet을 표현한다. 여러분이 원하는 만큼, 동일하거나 또는 다른 타입의 자식child 엘리먼트를 많이 포함할 수 있다. 다음의 애트리뷰트를 지원한다.

• shareInterpolator - 모든 인접한 자식child 엘리먼트 사이에서 같은 인터폴레이터interpolator를 공유하는지에 대한 여부.

<alpha>

페이딩fading 애니메이션. AlphaAnimation을 표현한다. 다음의 애트리뷰트를 지원한다.

• fromAlpha - 0.0 에서 1.0, 여기에서 0.0은 투명임.
• toAlpha - 0.0 에서 1.0, 여기에서 0.0은 투명임.

<scale>

크기를 변경하는 애니메이션. ScaleAnimation를 표현한다. 여러분은 pivotX와 pivotY를 지정함으로써 그것으로부터 바깥 쪽(또는 안 쪽)으로 커지는 이미지의 중심 지점(핀이 꼿힌 중심)을 지정할 수 있다. 예를 들어 만약 이것들이 0,0(왼쪽 상단 모서리)인 경우, 모든 증가는 아래와 우측으로 될 것이다. 스케일은 다음의 애트리뷰트를 지원한다.

• fromXScale - 시작하는 X 크기(여기에서 1.0은 어떤 변화도 없는 것임)
• toXScale - 끝나는 X 크기(여기에서 1.0이 어떤 변화도 없는 것임)
• fromYScale - 시작하는 Y 크기(여기에서 1.0은 어떤 변화도 없는 것임)
• toYScale - 끝나는 Y 크기(여기에서 1.0은 어떤 변화도 없는 것임)
• pivotX - 핀이 꽂힌 중심의 X 좌표.
• pivotY - 핀이 꽂힌 중심의 Y 좌표.

<translate>

수직/수평 움직임 애니메이션. TranslateAnimation을 표현한다. 뒤따르는 세 개의 포맷으로 된 어떤 애트리뷰트든 지원한다. “%”로 끝나는 -100에서 100까지 값은, 그것 자신에 상대적인 백분율을 가리킨다. “%p”로 끝나는 -100에서 100까지 값은, 자신의 부모parent에 상대적인 백분율을 가리킨다. 접미어가 없는 부동소수점은 절대 값을 가리킨다.

• fromXDelta - 시작하는 X 위치.
• toXDelta -끝나는 X 위치.
• fromYDelta - 시작하는 Y 위치.
• toYDelta - 끝나는 Y 위치.

<rotate>

회전 애니메이션. RotateAnimation을 표현한다. 다음의 애트리뷰트를 지원한다.

• fromDegrees - 회전을 시작하는 각도.
• toDegrees - 회전을 끝내는 각도.
• pivotX - 회전의 중심에 대한 픽셀 X 좌표, 여기에서 (0,0)은 왼쪽 상단 모서리.
• pivotY - 회전의 중심에 대한 픽셀 Y 좌표, 여기에서 (0,0)은 왼쪽 상단 모서리.

<interpolator tag>

여러분은 또한 R.styleable에서 정의된 임의의 interpolator 서브클래스 엘리먼트를 사용할 수 있다. 예제들은 <CycleInterpolator>, <EaseInInterpolator>, 그리고 <EaseOutInterpolator>를 포함한다. 이 오브젝트는 타임라인 상에서 시각적 액션이 얼마나 빠르게 일어나는가를 설명하는 속도 곡선을 정의한다(먼저 빠르게 그리고 나중에 느리게, 먼저 느리게 그리고 점차적으로 빠르게, 그리고 기타 등등).

In addition to the attributes defined for each element above, the elements <alpha>, <scale>, <translate>, <rotate>, and <set> all support the following attributes (inherited from the Animation class):

duration

Duration, in milliseconds, for this effect.

startOffset

Offset start time for this effect, in milliseconds.

fillBefore

When set true, the animation transformation is applied before the animation begins.

fillAfter

When set true, the animation transformation is applied after the animation ends.

repeatCount

Defines the number of times the animation should repeat.

repeatMode

Defines the animation behavior when it reaches the end and the repeat count is greater than 0. Options are to either restart or reverse the animation.

zAdjustment

Defines the z-axis ordering mode to use when running the animation (normal, top, or bottom).

interpolator

You can optionally set an interpolator for each element to determine how quickly or slowly it performs its effect over time. For example, slow at the beginning and faster at the end for EaseInInterpolator, and the reverse for EaseOutInterpolator. A list of interpolators is given in R.anim. To specify these, use the syntax @android:anim/interpolatorName.

duration

이 효과가 대한 기간. (단위, 1/1000초)

startOffset

이 효과에 대한 오프셋 시작 시각. (단위, 1/1000초)

fillBefore

참(true)으로 설정할 때, 애니메이션이 시작되기 전에 애니메이션 변형이 적용된다.

fillAfter

참(true)으로 설정할 때, 애니메이션이 끝난 후에 애니메이션 변형이 적용된다.

repeatCount

애니메이션이 반복되어야 하는 횟수를 정의한다.

repeatMode

애니메이션이 반복 횟수repeat count가 0보다 클 때, 애니메이션이 끝나는 순간의 동작을 정의한다. 옵션은 애니메이션을 다시 시작하거나 또는 역으로 진행시키는 것이다.

zAdjustment

애니메이션을 실행할 때 사용하는 z-축 지시 모드 (normal, top, 또는 bottom).

interpolator

여러분은 선택사항으로 각각의 엘리먼트에 대해 전체 애니메이션 시간동안 그것의 효과를 얼마나 빠르게 또는 느리게 수행할 것인가를 결정하는 인터폴레이터interpolator를 지정할 수 있다. 예를 들어 EaseInInterpolator는 처음에는 느리게 그리고 끝에서 더 빠르며, 그리고 EaseOutInterpolator는 그 반대이다. Interpolators 리스트는 R.anim에서 제공된다. 이들을 지정하기 위해서는 @android:anim/interpolatorName 구문을 이용하라.

For more discussion and animation code samples, see the discussion in the 2D Graphics document.

Menus

Application menus (Options Menu, Context Menu, or Sub Menu) can be defined as XML resources and inflated by your application using MenuInflater.

Source file format: XML file, one resource per file, one root tag, <?xml> declaration not required.

Resource file location: res/menu/some_file.xml

Compiled resource datatype: Resource pointer to a Menu (or subclass) resource.

Resource reference name:

• Java: R.menu.some_file

Java: R.menu.some_file

Syntax

The file must have a single root element: a <menu> element. In all, there are three valid elements: <menu>, <group> and <item>. The <item> and <group> elements must be the children of a <menu>, but <item> elements can also be the children of a <group>, and another <menu> element may be the child of an <item> (to create a Sub Menu).

<menu xmlns:android="http://schemas.android.com/apk/res/android">

    <item android:id="@+id/example_item
          android:title="Example Item"
          android:icon="@drawable/example_item_icon" />

    <group android:id="@+id/example_group">
        <item android:id="@+id/example_item2
              android:title="Example Item 2"
              android:icon="@drawable/example_item2_icon" />
    </group>

    <item android:id="@+id/example_submenu
          android:title="Example Sub Menu" >
        <menu>
            <item android:id="@+id/example_submenu_item
                  android:title="Example Sub Menu Item" />
        </menu>
    </item>

</menu>

Elements and Attributes

All attributes must be defined with the android namespace (e.g., android:icon="@drawable/icon").

<menu>

The root of a menu. Contains <item> and <group> nodes. No attributes.

<group>

A menu group. Contains <item> elements. Valid attributes:

• id - A unique integer ID for the group.
• menuCategory - Value corresponding to Menu CATEGORY_* constants defines the priority of the group. Valid values: container, system, secondary, and alternative.
• orderInCategory - An integer that defines the default order of the items within the category.
• checkableBehavior - Whether the items are checkable. Valid values: none, all (exclusive / radio buttons), single (non-exclusive / checkboxes)
• visible - Whether the group is visible. true or false.
• enabled - Whether the group is enabled. true or false.

<item>

A menu item. May contain a <menu> element (for a Sub Menu). Valid attributes:

• id - A unique resource ID for the item.
• menuCategory - Used to define the menu category.
• orderInCategory - Used to define the order of the item, within a group.
• title - A string for the menu title.
• titleCondensed - A condensed string title, for situations in which the normal title is too long.
• icon - A resource identifier for a drawable icon.
• alphabeticShortcut - A character for the alphabetic shortcut key.
• numericShortcut - A number for the numeric shortcut key.
• checkable - Whether the item is checkable. true or false.
• checked - Whether the item is checked by default. true or false.
• visible - Whether the item is visible by default. true or false.
• enabled - Whether the item is enabled by default. true or false.

<menu>

메뉴의 루트. <item> 과 <group> 노드들을 포함한다. 어떠한 애트리뷰트도 가지지 않는다.

<group>

메뉴 그룹. <item> 엘리먼트를 포함한다. 유효한 애트리뷰트는 다음과 같다.

• id - 그룹에 대한 고유한 정수integer ID.
• menuCategory - 메뉴 CATEGORY_*상수에 대응하는 값 ? 그룹의 우선순위를 정의한다. 유효한 값: container, system, secondary, 그리고 alternative.
• orderInCategory - 카테고리 내에서 아이템의 디폴트 순서를 정의하는 정수integer.
• checkableBehavior - 아이템의 체크 가능 여부. 유효한 값: none, all(상호배타적인/라디오 버튼), single(배타적이지 않은/체크박스)
• visible - 그룹이 보여지는 지 여부. 참true 또는 거짓false.
• enabled - 그룹이 활성화 가능한 지 여부. 참true 또는 거짓false.

<item>

메뉴 아이템. 하나의 <menu> 엘리먼트(서브 메뉴를 위해)를 포함할 수 있다. 유효한 애트리뷰트는 다음과 같다.

• id - 아이템에 대한 고유한 리소스 ID.
• menuCategory - 메뉴 카테고리를 정의하기 위해 사용된다.
• orderInCategory - 그룹 안에서 아이템의 순서를 정의하기 위해 사용된다.
• title - 메뉴 타이틀에 대한 문자열.
• titleCondensed - 일반적인 타이틀이 너무 긴 상황을 위해 간결한 문자열 타이틀.
• icon - 드로어블drawable 아이콘에 대한 리소스 식별자.
• alphabeticShortcut - 알파벳 단축키에 대한 문자.
• numericShortcut - 숫자 단축키에 대한 숫자.
• checkable - 아이템의 체크 가능 여부. 참true 또는 거짓false.
• checked - 아이템의 디폴트 체크 여부. 참true 또는 거짓false.
• visible - 아이템이 디폴드로 보여지는 지 여부. 참true 또는 거짓false.
• enabled - 아이템이 디폴트로 활성화 가능한 지 여부. 참true 또는 거짓false.

For more discussion on how to create menus in XML and inflate them in your application, read Creating Menus.

Layout

Android lets you specify screen layouts using XML elements inside an XML file, similar to designing screen layout for a webpage in an HTML file. Each file contains a whole screen or a part of a screen, and is compiled into a View resource that can be passed in to Activity.setContentView or used as a reference by other layout resource elements. Files are saved in the res/layout/ folder of your project, and compiled by the Android resource compiler, aapt.

Every layout XML file must evaluate to a single root element. First we'll describe how to use the standard XML tags understood by Android as it is shipped, and then we'll give a little information on how you can define your own custom XML elements for custom View objects.

The root element must have the Android namespace "http://schemas.android.com/apk/res/android" defined in the root element.

For a complete discussion on creating layouts, see the User Interface topic.

Source file format: XML file requiring a <?xml version="1.0" encoding="utf-8"?> declaration, and a root element of one of the supported XML layout elements.

Resource file location: res/layout/some_file.xml.

Compiled resource datatype: Resource pointer to a View (or subclass) resource.

Resource reference name:

• Java: R.layout.some_file
• XML: @[package:]layout/some_file

Java: R.layout.some_file
XML: @[package:]layout/some_file

Syntax

<ViewGroupClass xmlns:android="http://schemas.android.com/apk/res/android"
                android:id="@+id/string_name" (attributes)>
   <widget or other nested ViewGroupClass>+
   <requestFocus/>(0 or 1 per layout file, assigned to any element)
</ViewGroupClass>

<ViewGroupClass>

The file must have a single root element. This can be a ViewGroup class that contains other elements, or a widget (or custom item) if it's only one object. By default, you can use any (case-sensitive) Android widget or ViewGroup class name as an element. These elements support attributes that apply to the underlying class, but the naming is not as clear. How to discover what attributes are supported for what tags is discussed below. You should not assume that any nesting is valid (for example you cannot enclose <TextView> elements inside a <ListLayout>).

If a class derives from another class, the XML element inherits all the attributes from the element that it "derives" from. So, for example, <EditText> is the corresponding XML element for the EditText class. It exposes its own unique attributes (EditText_numeric), as well as all attributes supported by <TextView> and <View>. For the id attribute of a tag in XML, you should use a special syntax: "@+id/somestringvalue". The "@+" syntax creates a resource number in the R.id class, if one doesn't exist, or uses it, if it does exist. When declaring an ID value for an XML tag, use this syntax. Example: <TextView android:id="@+id/nameTextbox"/>, and refer to it this way in Java: findViewById(R.id.nameTextbox). All elements support the following values:

• id - An ID value used to access this element in Java. Typically you will use the syntax @+id/string_name to generate an ID for you in the id.xml file if you haven't created one yourself.
• xmlns:android="http://schemas.android.com/apk/res/android" - Required for the root element only.

<requestFocus>

Any element representing a View object can include this empty element, which gives it's parent tag initial focus on the screen. You can have only one of these elements per file.

<ViewGroupClass>

그 파일은 하나의 루트 엘리먼트를 가져야 한다. 이것은 다른 엘리먼트를 포함하는 뷰그룹 클래스가 될 수 있으며, 또한 만약 그것이 오직 하나의 오브젝트라면 위젯 (또는 커스텀 아이템)이 될 수도 있다. 디폴트로, 여러분은 엘리먼트로 어떤 (대소문자를 구분하는) 안드로이드 위젯이나 뷰그룹 클래스 이름을 사용할 수 있다. 이러한 엘리먼트들은 그 아래에 놓인(역주: 대응대는) 클래스에 적용하는 애트리뷰트를 지원한다. 하지만 그 네이밍naming은 분명하지 않다. 어떤 태그에서 어떤 어떤 애트리뷰트가 지원되는가를 찾는 방법이 아래에 설명되었다. 여러분은 어떤 네스팅nesting이든 유효하다고 가정해서는 안된다(예를 들어 여러분은 <ListLayout> 안에 <TextView> 엘리먼트를 포함할 수 없다).

만약 클래스가 다른 클래스로부터 파생된다면, XML 엘리먼트는 그것이 파생된 그 엘리먼트로 부터 모든 애트리뷰트를 상속한다. 그러므로 예를 들어 <EditText>는 EditText 클래스에 대응되는 XML 엘리먼트이다. 그것은 <TextView>와 <View>에 의해 지원되는 모든 애트리뷰트 뿐만 아니라, 그것 자신의 고유한 애트리뷰트(EditText_numeric)를 제시한다. XML 안에 있는 태그의 id 애트리뷰트에 대해, 여러분은 특별한 구문(“@+id/somestringvalue”)을 사용해야 한다. “@+” 구문은 만약 R.id 클래스에 리소스 숫자가 존재하지 않는다면 그것을 생성하며, 만약 그것이 존재한다면 그것을 사용한다. XML 태그에 대한 ID 값를 선언할 때, 이 구문을 사용하라. 예제: <TextView id= “@+id/nameTextbox”/>, 그리고 Java에서 이러한 방법, findViewById(R.id.nameTextbox)로 그것을 레퍼런스하라. 모든 엘리먼트는 다음의 값들을 지원한다.

• id - Java에서 이 엘리먼트에 접근하기 위해 사용되는 ID 값. 만일 여러분이 id.xml에서 스스로 그것을 생성하지 않았다면, 여러분은 일반적으로 여러분을 위한 ID를 생성하기 위해 @+id/string_name 구문을 사용할 것이다. (역주 : 만약 id.xml 에서 id를 일괄적으로 생성하고자 한다면, 아래와 같은 방식으로 간단하게 id를 생성할 수 있다. <resources> <item type=”id” name=”string_name” /></resources>)
• xmlns:android=”http://schemas.android.com/apk/res/android” ? 루트 엘리먼트에서 요구된다.

<requestFocus>

뷰 오브젝트에 해당하는 임의의 엘리먼트는 이런 빈empty 엘리먼트를 포함할 수 있다. 이것은 그것의 부모parent 태그에게 스크린 상의 초기 포커스를 제공한다. 여러분은 파일 별로 이 엘리먼트를 오직 하나만 가질 수 있다.

What Attributes Are Supported for What Elements?

Android uses the LayoutInflater class at run time to load an XML layout resource and translate it into visual elements. By default, all widget class names are supported directly as tags, but a full list of supported tags and attributes is listed in the R.styleable reference page. However, the attribute names are somewhat obscure. If an underscore appears in the name, this indicates that it is an attribute typically of the element before the underscore. So, for example, EditText_autoText means that the <EditText> tag supports an attribute autoText. When you actually use the attribute in that element, use only the portion after the last underscore, and prefix the attribute with the prefix "android:". So, for example, if R.styleable lists the following values:

• TextView
• TextView_lines
• TextView_maxlines

TextView
TextView_lines
TextView_maxlines

You could create an element like this:

<TextView android:lines="10" android:maxlines="20"/>

This would create a TextView object and set its lines and maxlines properties.

Attributes come from three sources:

• Attributes exposed directly by the element. For example, TextView supports TextView_text, as discussed above.
• Attributes exposed by all the superclasses of that element. For example, the TextView class extends the View class, so the <TextView> element supports all the attributes that the <View> element exposes a long list, including View_paddingBottom and View_scrollbars. These too are used without the class name: <TextView android:paddingBottom="20" android:scrollbars="horizontal" />.
• Attributes of the object's ViewGroup.LayoutParams subclass. All View objects support a LayoutParams member (see Declaring Layout). To set properties on an element's LayoutParams member, the attribute to use is "android:layout_layoutParamsProperty". For example: android:layout_gravity for an object wrapped by a <LinearLayout> element. Remember that each LayoutParams subclass also supports inherited attributes. Attributes exposed by each subclass are given in the format someLayoutParamsSubclass_Layout_layout_someproperty. This defines an attribute "android:layout_someproperty". Here is an example of how Android documentation lists the properties of the LinearLayout.LayoutParams class:

엘리먼트에 의해 직접적으로 보여지는 애트리뷰트. 예를 들어 위에서 논의된 것과 같이 TextView는 TextView_text를 지원한다.
해당 엘리먼트의 모든 슈퍼클래스에 의해 보여지는 애트리뷰트. 예를 들어 TextView 클래스는 View 클래스를 확장한다. 그러므로 <TextView> 엘리먼트는 <View> 엘리먼트가 보여주는 모든 애트리뷰트 - View_paddingBottom과 View_scrollbars를 포함하는 긴 리스트 ? 를 지원한다. 이것들 또한 클래스 이름없이 사용된다. <TextView android:padding Bottom=”20” android: scrollbars=”horizontal”/>.
오브젝트의 ViewGroup.LayoutParams 서브클래스의 애트리뷰트. 모든 뷰 오브젝트는 LayoutParams 멤버를 지원한다(3장. “사용자 인터페이스”의 “레이아웃 선언하기”를 보라). 엘리먼트의 LayoutParams 멤버에 속성들을 설정하기 위해, 사용할 애트리뷰트는 “android:layout_layoutParamsProperty”이다. 예를 들어 <LinearLayout> 엘리먼트에 의해 감싸여진 오브젝트에 대한 android:layout_gravity가 그것이다. 각각의 LayoutParams 서브클래스는 또한 상속된 애트리뷰트를 지원한다는 것을 기억하라. 각각의 서브클래스에 의해 보여지는 애트리뷰트들은 someLayoutParamsSubclass_Layout_layout_someproperty 포맷으로 주어진다. 이것은 애트리뷰트 “android:layout_someproperty”를 정의한다. 여기에 안드로이드 문서가 LinearLayout.LayoutParams 클래스의 속성을 어떻게 나열하는 지에 대한 예제가 있다.

• LinearLayout_Layout // The actual object not used.
• LinearLayout_Layout_layout_gravity // Exposes a gravity attribute
• LinearLayout_Layout_layout_height // Exposes a height attribute
• LinearLayout_Layout_layout_weight // Exposes a weight attribute
• LinearLayout_Layout_layout_width // Exposes a width attribute

LinearLayout_Layout // 실제 오브젝트 ? 사용되지 않음.
LinearLayout_Layout_layout_gravity // gravity 애트리뷰트를 보여줌.
LinearLayout_Layout_layout_height // height 애트리뷰트를 보여줌.
LinearLayout_Layout_layout_weight // weight 애트리뷰트를 보여줌.
LinearLayout_Layout_layout_width // width 애트리뷰트를 보여줌.

Here is an example that sets some of these values on a few objects, including direct attributes, inherited attributes, and LayoutParams attributes:

<?xml version="1.0" encoding="utf-8"?>
<!-- res/main_screen.xml -->
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
              android:orientation="vertical"    // The object's own orientation property
              android:padding="4"               // Inherited View property
              android:gravity="center"          // The object's own property
              android:layout_width="fill_parent"  // Parent object's LinearLayout.LayoutParams.width
              android:layout_height="fill_parent"> // Parent object's LinearLayout.LayoutParams.height

   <TextView android:layout_width="fill_parent"   // TextView.LayoutParams.width
             android:layout_height="wrap_content" // TextView.LayoutParams.height
             android:layout_weight="0"            // TextView.LayoutParams.weight
             android:paddingBottom="4"            // TextView.paddingBottom
             android:text="@string/redirect_getter"/> // TextView.text

   <EditText android:id="@+id/text"
             android:layout_width="fill_parent"   // EditText.LayoutParams.width
             android:layout_height="wrap_content" // EditText.LayoutParams.height
             android:layout_weight="0"            // EditText.LinearLayoutParams.weight
             android:paddingBottom="4">           // EditText.paddingBottom
       <requestFocus />
   </EditText>

   <Button android:id="@+id/apply"
           android:layout_width="wrap_content"  // Button.LayoutParams.width
           android:layout_height="wrap_content" // Button.LayoutParams.height
           android:text="@string/apply" />      // TextView.text
</LinearLayout>

Example Code Use

The most common use is to load the XML file (located at res/main_screen.xml) and use it as the current screen, as shown here with the preceding file:

setContentView(R.layout.main_screen); 

However, layout elements can also represent repeating elements used as templates.

Also see User Interface for more information on layouts.

Custom Layout Resources

You can define custom elements to use in layout resources. These custom elements can then be used the same as any Android layout elements: that is, you can use them and specify their attributes in other resources. The ApiDemos sample application has an example of creating a custom layout XML tag, LabelView. To create a custom element, you will need the following files:

• Java implementation file - The implementation file. The class must extend View or a subclass. See LabelView.java in ApiDemos.
• res/values/attrs.xml - Defines the XML element, and the attributes that it supports, for clients to use to instantiate your object in their layout XML file. Define your element in a <declare-styleable name=your_java_class_name>. See res/values/attrs.xml in ApiDemos.
• res/layout/your_class.xml [optional] - An optional XML file to describe the layout of your object. This could also be done in Java. See custom_view_1.xml in ApiDemos.

Java 구현 파일 ? 그 구현 파일. 이 클래스는 뷰View 또는 서브클래스를 확장해야 한다. ApiDemos에 있는 LabelView.java를 보라.
res/values/attrs.xml ? 클라이언트가 자신의 레이아웃 XML 파일에서 여러분의 오브젝트를 인스턴스화 하기 위해, 그것이 지원하는 XML 엘리먼트와 애트리뷰트를 정의한다. 여러분의 엘리먼트를 <declare-styleable id=your_java_class_name>에 정의하라. ApiDemos에 있는 res/layout/attrs.xml을 보라.
res/layout/your_class.xml [선택사항] - 여러분의 오브젝트의 레이아웃를 기술하기 위한 옵션사항인 XML 파일. 이것은 또한 Java 코드에서 이루어질 수도 있다. ApiDemos에 있는 custom_view_1.xml을 보라.

Source file format: XML file without an <?xml> declaration, and a <resources> root element containing one or more custom element tags.

Resource file location: res/values/attrs.xml (File name is arbitrary.)

Compiled resource datatype: Resource pointer to a View (or subclass) resource.

Resource reference name: R.styleable.some_file (Java).

Styles and Themes

A style is one or more attributes applied to a single element (for example, 10 point red Arial font, applied to a TextView). A style is applied as an attribute to an element in a layout XML file.

A theme is one or more attributes applied to a whole screen for example, you might apply the stock Android Theme.dialog theme to an activity designed to be a floating dialog box. A theme is assigned as an attribute to an Activity in the manifest file.

Both styles and themes are defined in a <style> block containing one or more string or numerical values (typically color values), or references to other resources (drawables and so on). These elements support inheritance, so you could have MyBaseTheme, MyBaseTheme.Fancy, MyBaseTheme.Small, and so on.

For a complete discussion on styles and themes, read Applying Styles and Themes.

Source file format: XML file requiring a <?xml version="1.0" encoding="utf-8"?> declaration, and a root <resources> element containing one or more <style> tags.

Resource source file location: res/values/styles.xml (File name is arbitrary, but standard practice is to put all styles into a file named styles.xml.)

Compiled resource datatype: Resource pointer to a Java CharSequence.

Resource reference name:

• Java: R.style.styleID for the whole style, R.style.styleID.itemID for an individual setting
• XML: @[package:]style/styleID for a whole style, @[package:]style/styleID/itemID for an individual item. Note: to refer to a value in the currently applied theme, use "?" instead of "@" as described below (XML).

Java: 전체 스타일에 대한 R.style.styleID, 개별적인 설정에 대한 R.style.styleID.itemID
XML: 전체 스타일에 대한 @[package:]style/styleID, 개별적 아이템에 대한 @[package:]style/styleID/itemID. 노트: 현재 적용된 테마에서 사용된 값을 레퍼런스하기 위해서는 아래의 XML에서 설명되듯이 “@” 대신에 “?”를 사용하라.

Syntax

<style name=string [parent=string] >
   <item name=string>Hex value | string value | reference</item>+
</style>

<style>

Holds one or more <item> elements, each describing one value. This style, which is a bundle of values, can be referred to as a theme.

• name - The name used in referring to this theme.
• parent - An optional parent theme. All values from the specified theme will be inherited into this theme. Any values with identical names that you specify will override inherited values. The name must be qualified by the package, but you don't need the /style directive (for example, android:Theme for the base Android theme, or MyTheme for a theme defined in your package).

<item>

A value to use in this theme. It can be a standard string, a hex color value, or a reference to any other resource type.

<style>

하나 또는 그 이상의 <item> 엘리먼트를 보유하며, 그것들 각각은 하나의 값을 설명하고 있다. 이 값들의 하나의 묶음인 스타일은 테마로써 레퍼런스될 수도 있다.

• name - 이 테마를 가리키는데 사용되는 이름.
• parent - 선택사항인 parent 테마. 지정된 테마의 모든 값들은 이 테마로 상속될 것이다. 여러분이 지정한 동일한 이름을 갖는 임의의 값은 상속한 값을 오버라이드 할 것이다. 그 이름은 그 패키지 수식어를 가져야 한다. 그러나 여러분은 /style 지시어를 필요로 하지 않는다(예를 들어 기본적인 안드로이드 테마에 대해서는 android:Theme, 또는 여러분 패키지에 정의된 하나의 테마에 대해서는 MyTheme).

<item>

이 아이템에서 사용되는 값. 그것은 표준 문자열, 16진수 컬러 값, 또는 임의의 다른 리소스 타입에 대한 레퍼런스가 될 수 있다.

For examples of how to declare and apply styles and themes, read Applying Styles and Themes.

Searchable

To make search appear to the user as a seamless system-wide feature, the Android framework offers APIs that let applications control how they are searched. Applications can customize how search is invoked, how the search dialog looks, and what type of search results are available, including suggestions that are shown as the user types.

In order to utilize the Android search framework, an application must provide a search configuration in the form of an XML resource. This section describes the search configuration XML in terms of its syntax and usage. For a more complete discussion about how to implement search features for your application, see SearchManager.

Source file format: XML file requiring a <?xml version="1.0" encoding="utf-8"?> declaration, and a root <searchable> element.

Resource source file location: res/xml/searchable.xml (The file name is arbitrary, but standard practice is to use searchable.xml.)

Compiled resource datatype: Resource pointer to an xml object.

Resource reference name:

• Java: R.xml.filename.
• XML: @[package:]xml/filename (e.g., @xml/searchable).

Java: R.xml.filename.
XML: @[package:]xml/filename (예,@xml/searchable).

Syntax

<searchable xmlns:android="http://schemas.android.com/apk/res/android
     android:label="@string/search_label" 
     ... >
     <actionkey
          android:keycode="KEYCODE_CALL"
          ... >     
</searchable>

<searchable>

Defines all application search configurations, including settings for text and voice searches performed within the application. It accepts the following attributes:

• label - Required. This is the name for your application, as it will appear to the user. This will be visible only if searchMode is set to "showSearchLabelAsBadge" (see below).
• hint - This is the text to display in the search text field when no text has been entered. This is recommended in order to provide context to the search about to be performed (e.g., "Search the Dictionary").
• searchMode - If provided and non-zero, this sets additional modes for control of the search presentation. The following mode values are accepted:
  • showSearchLabelAsBadge - If set, this enables the display of the search target (label) within the search bar.
  • queryRewriteFromData - If set, this causes the suggestion column SUGGEST_COLUMN_INTENT_DATA to be considered as the text for suggestion query rewriting. This should only be used when the values in SUGGEST_COLUMN_INTENT_DATA are suitable for user inspection and editing - typically, HTTP/HTTPS Uri's.
  • queryRewriteFromText - If set, this causes the suggestion column SUGGEST_COLUMN_TEXT_1 to be considered as the text for suggestion query rewriting. This should be used for suggestions in which no query text is provided and the SUGGEST_COLUMN_INTENT_DATA values are not suitable for user inspection and editing.

  More than one of the above values for searchMode can be used at once. For example, you can declare two modes at once, like this: searchMode="queryRewriteFromData|queryRewriteFromText"

• inputType - If provided, supplies a hint about the type of search text the user will be entering. For most searches, in which free form text is expected, this attribute is not needed. See inputType for a list of suitable values for this attribute.
• imeOptions - If provided, supplies additional options for the input method. For most searches, in which free form text is expected, this attribute is not needed, and will default to "actionSearch". See imeOptions for a list of suitable values for this attribute.

If you have defined a content provider to generate search suggestions, you need to provide some more searchable metadata in order to configure communications with the content provider. The following are additional <searchable> attributes for use when providing search suggestions:

• searchSuggestAuthority - Required to provide search suggestions. This value must match the authority string provided in the provider section of your manifest.
• searchSuggestPath - If provided, this path will be inserted in the suggestions query Uri, after the authority you have provide but before the standard suggestions path. This is only required if you have a single content provider issuing different types of suggestions (e.g. for different data types) and you need a way to disambiguate the suggestions queries when they are received.
• searchSuggestSelection - If provided, this value will be passed into your query function as the selection parameter. Typically this will be a WHERE clause for your database, and will contain a single question mark, which represents the actual query string that has been typed by the user. However, you can also use any non-null value to simply trigger the delivery of the query text (via selection arguments), and then use the query text in any way appropriate for your provider (ignoring the actual text of the selection parameter.)
• searchSuggestIntentAction - The default Intent action to be used when a user clicks on a search suggestion. If provided, and not overridden by the selected suggestion, this value will be placed in the action field of the Intent when the user clicks a suggestion.
• searchSuggestIntentData - The default Intent data to be used when a user clicks on a search suggestion. If provided, and not overridden by the selected suggestion, this value will be placed in the data field of the Intent when the user clicks a suggestion.

Beyond providing search suggestions while using your application's local search, you can also configure your search suggestions to be made available to Quick Search Box, which will allow users so receive search suggestions from your application content from outside your application. The following are additional <searchable> attributes for use when providing search suggestions to Quick Search Box:

• includeInGlobalSearch - Required to provide search suggestions in Quick Search Box. If true, this indicates the search suggestions provided by your application should be included in the globally accessible Quick Search Box. The user must still enable your application as a searchable item in the system search settings in order for your suggestions to appear in Quick Search Box.
• searchSettingsDescription - If provided, this provides a brief description of the search suggestions that you provide to Quick Search Box, and will be displayed in the search settings entry for your application.
• queryAfterZeroResults - Indicates whether a source should be invoked for supersets of queries it has returned zero results for in the past. For example, if a source returned zero results for "bo", it would be ignored for "bob". If set to false, this source will only be ignored for a single session; the next time the search dialog is invoked, all sources will be queried. The default value is false.
• searchSuggestThreshold - Indicates the minimum number of characters needed to trigger a source lookup from Quick Search Box. Only guarantees that a source will not be queried for anything shorter than the threshold. The default value is 0.

To enable voice search for your Activity, you can add fields to the searchable metadata that enable and configure voice search. The following are additional <searchable> attributes for use when implementing voice search:

• voiceSearchMode - Required to provide voice search capabilities. If provided and non-zero, enables voice search. (Voice search may not be provided by the device, in which case these flags will have no effect.) The following mode values are accepted:
  • showVoiceSearchButton - If set, display a voice search button. This only takes effect if voice search is available on the device. If set, then "launchWebSearch" or "launchRecognizer" must also be set.
  • launchWebSearch - If set, the voice search button will take the user directly to a built-in voice web search activity. Most applications will not use this flag, as it will take the user away from the activity in which search was invoked.
  • launchRecognizer - If set, the voice search button will take the user directly to a built-in voice recording activity. This activity will prompt the user to speak, transcribe the spoken text, and forward the resulting query text to the searchable activity, just as if the user had typed it into the search UI and clicked the search button.
• voiceLanguageModel - A string constant from RecognizerIntent. If provided, this specifies the language model that should be used by the voice recognition system. See EXTRA_LANGUAGE_MODEL for more information. If not provided, the default value LANGUAGE_MODEL_FREE_FORM will be used.
• voicePromptText - A string. If provided, this specifies a prompt that will be displayed during voice input. If not provided, a default prompt will be displayed.
• voiceLanguage - A string constant from Locale. If provided, this specifies the spoken language to be expected. This is only needed if it is different from the current value of getDefault().
• voiceMaxResults - If provided, enforces the maximum number of results to return, including the "best" result which will always be provided as the SEARCH intent's primary query. Must be one or greater. Use EXTRA_RESULTS to get the results from the intent. If not provided, the recognizer will choose how many results to return.

<actionkey>

Defines a shortcut key for a search action.

• keycode - Required. This attribute denotes the action key you wish to respond to. Note that not all action keys are actually supported using this mechanism, as many of them are used for typing, navigation, or system functions. This will be added to the ACTION_SEARCH Intent that is passed to your searchable Activity. To examine the key code, use getIntExtra(SearchManager.ACTION_KEY). Note that, in addition to the keycode, you must also provide one or more of the action specifier attributes below.
• queryActionMsg - If you wish to handle an action key during normal search query entry, you must define an action string here. This will be added to the ACTION_SEARCH Intent that is passed to your searchable Activity. To examine the string, use getStringExtra(SearchManager.ACTION_MSG).
• suggestActionMsg - If you wish to handle an action key while a suggestion is being displayed and selected, there are two ways to handle this. If all of your suggestions can handle the action key, you can simply define the action message using this attribute. This will be added to the ACTION_SEARCH Intent that is passed to your searchable Activity. To examine the string, use getStringExtra(SearchManager.ACTION_MSG).
• suggestActionMsgColumn - If you wish to handle an action key while a suggestion is being displayed and selected, but you do not wish to enable this action key for every suggestion, then you can use this attribute to control it on a suggestion-by-suggestion basis. First, you must define a column (and name it here) where your suggestions will include the action string. Then, in your content provider, you must provide this column, and when desired, provide data in this column. The search manager will look at your suggestion cursor, using the string provided here in order to select a column, and will use that to select a string from the cursor. That string will be added to the ACTION_SEARCH Intent that is passed to your searchable Activity. To examine the string, use getStringExtra(SearchManager.ACTION_MSG). If the data does not exist for the selection suggestion, the action key will be ignored.

<searchable>

애플리케이션내에서 수행되는 텍스트와 음성 검색들을 위한 셋팅settings을 포함하는 모든 애플리케이션 검색 설정configurations을 정의하라. 다음과 같은 애트리뷰트들이 허용된다.

• label - 필수임. 이것은 사용자에게 보여지게 될 애플리케이션에 대한 이름이다. 이것은 searchMode가 “showSearchLabelAsBadge”로 지정되었을 때에만 보여질 것이다(아래를 보라).
• hint - 이것은 검색 텍스트 필드에 어떤 텍스트도 입력되지 않았을 때 보여지는 텍스트이다. 이것은 해당 검색이 수행하게 되는 것에 대한 컨텍스트context를 제공하기 위해 권장된다(예, “사전 검색”).
• searchMode - 만약 이것이 제공되고 비어있지 않다면, 이것은 검색 화면의 제어를 위한 추가적인 모드mode를 지정한다. 다음과 같은 모드mode 값들이 허용된다.
  • showSearchLabelAsBadge - 만약 이것이 지정되면, 해당 검색바내에 검색 대상target(라벨label)을 보여주는 것을 활성화한다.
  • queryRewriteFromData - 만약 이것이 지정되면, 추천어suggestion 컬럼column SUGGEST_COLUMN_INTENT_DATA가 추천어 쿼리 정정을 위한 텍스트로써 간주되도록 한다. 이것은 SUGGEST_COLUMN_INTENT_DATA에 있는 그 값들이 사용자의 검열inspection과 편집editing에 적합할 때에만 사용되어야 한다 - 전형적으로, HTTP/HTTPS Uri.
  • queryRewriteFromText - 만약 이것이 지정되면, 추천어suggestion 컬럼column SUGGEST_COLUMN_TEXT_1이 추천어 쿼리 정정을 위한 텍스트로써 간주되도록 한다. 이것은 쿼리 텍스트가 제공되지 않고 SUGGEST_COLUMN_INTENT_DATA 값들이 사용자 검열inspection과 편집editing에 적합하지 않는 경우에 추천어suggestions를 위해 사용되어야 한다.

  searchMode에 대한 위의 값들 중 한 개 이상이 한번에 사용될 수 있다. 예를들어, 여러분은 아래와 같이 한번에 두개의 모드를 선언할 수 있다. searchMode="queryRewriteFromData|queryRewriteFromText"

• inputType - 만약 이것이 지정되면, 사용자가 입력하게 될 검색 텍스트의 유형에 대한 힌트를 제공한다. 자유로운 형식의 텍스트가 기대되는 대부분의 검색에 대해서는, 이 애트리뷰트는 필요하지 않다. 이 애트리뷰트에 대한 적합한 값들의 목록에 대해서는 inputType을 보라.
• imeOptions - 만약 이것이 지정되면, 입력 방법에 대한 추가적인 옵션을 제공한다. 자유로운 형식의 텍스트가 기대되는 대부분의 검색에 대해서는, 이 애트리뷰트는 필요하지 않으며, 디폴트로 “actionSearch”일 것이다. 이 애트리뷰트에 대한 적합한 값들의 목록에 대해서는 imeOptions을 보라.

만약 여러분이 검색 추천어suggestions를 생성하기 위해 컨텐트 프로바이더를 정의했다면, 여러분은 컨텐트 프로바이더와의 커뮤니케이션을 설정하기 위해 약간 더 많은 searchable 메타데이터를 제공할 필요가 있다. 다음에 나오는 것이 검색 추천어suggestsions를 제공할 때 사용할 추가적인 <searchable> 애트리뷰트들이다.

• searchSuggestAuthority - 검색 추천어suggestions를 제공하기 위해 필수임. 이 값은 여러분의 매니페스트의 프로바이더 섹션에서 제공되는 authority(권위) 문자열과 일치해야 한다.
• searchSuggestPath - 만약 이것이 지정되면, 이 경로path는 추천어suggestions 쿼리 Uri에 삽입될 것이며, 그 위치는 여러분이 제공한 authority(권위) 뒤쪽이지만, 표준 추천어suggestions 경로의 앞쪽이다. 이것은 여러분이 다른 유형의 추천어(예, 다른 데이터 유형에 대해)를 제시하는 하나의 컨텐트 프로바이드를 가질 때에만 필요하며, 여러분은 그것들이 수신될 때 추천어suggestions 쿼리들을 명확하게 하는 방법이 필요하다.
• searchSuggestSelection - 만약 이것이 지정되면, 이 값은 selection 파라미터로써 여러분이 쿼리 함수안으로 전달될 것이다. 전형적으로, 이것은 여러분의 데이터베이스에 대한 WHERE절이 될 것이며, 사용자에 의해 입력되었던 실제 쿼리 문자열을 가리키는 하나의 물음표를 포함할 것이다. 하지만, 여러분은 또한 (selection 아큐먼트를 통해) 쿼리 텍스트의 전달을 간단하게 발생시키는 임의의 공백이 아닌 값을 사용할 수도 있으며, 그런 다음에 여러분의 프로바이더에 (selection 파라미터의 실제 텍스트를 무시하는) 임의의 적절한 방식으로 쿼리 텍스트를 사용하라.
• searchSuggestIntentAction - 사용자가 검색 추천어suggestion를 클릭할 때 사용되는 디폴트 인텐트 액션. 만약 이것이 지정되고 선택된 추천어suggestion에 의해 오버라이드되지overriden 않는다면, 이 값은 사용자가 추천어suggestion를 클릭할 때 인텐트의 액션 필드에 위치하게 될 것이다.
• searchSuggestIntentData - 사용자가 검색 추천어suggestion를 클릭할 때 사용되는 디폴트 인텐트 데이터. 만약 이것이 지정되고 선택된 추천어suggestion에 의해 오버라이드되지overriden 않는다면, 이 값은 사용자가 추천어suggestion를 클릭할 때 인텐트의 데이터 필드에 위치하게 될 것이다.

여러분의 애플리케이션의 로컬 검색을 사용하는 동안 검색 추천어suggestions 제공을 넘어서, 여러분은 또한 Quick Search Box(역주: 홈 런처에 있는 검색창)에서 여러분의 검색 추천어suggestions가 유용하도록 설정할 수 있다. 이것은 사용자가 여러분의 애플리케이션 외부에서 여러분의 애플리케이션 컨텐트로부터 검색 추천어suggestions를 수신하는 것을 가능하게 할 것이다. 다음에 나오는 것이 Quick Search Box에 검색 추천어suggestions를 제공할 때 사용하는 추가적인 <searchable> 애트리뷰트들이다.

• includeInGlobalSearch - Quick Search Box에 검색 추천어suggestions를 제공하기 위해 필수임. 만약 참true라면, 이것은 여러분의 애플리케이션에 의해 제공되는 검색 추천어suggestions가 글로벌하게 접근가능한 Quick Search Box에 포함되어야 한다는 것을 가리킨다. 사용자는 Quick Search Box에 여러분의 추천어가 나타나도록 하기 위해 여전히 시스템 검색 셋팅에서 검색가능한 아이템으로써 여러분의 애플리케이션을 활성화해야 한다.
• searchSettingsDescription - 만약 이것이 제공되면, 이것은 여러분이 Quick Search Box에 제공하는 검색 추천어suggestions에 대한 간단한 설명을 제공하며, 그것은 여러분의 애플리케이션에 대한 검색 셋팅란에서 보여지게 될 것이다.
• queryAfterZeroResults - 과거에 빈 결과를 리턴했던 쿼리들의 슈퍼셋들supersets에 대해 소스source가 호출되어야 하는지 여부를 가리킨다. 예를들어, 만약 소스source가 “bo”에 대해 빈 결과를 리턴했다면, 그것은 “bob”에 대해서 무시될 것이다. 만약 이것이 거짓false으로 지정되면, 이 소스source는 하나의 세션에 대해서만 무시될 것이다; 다음번 검색 다이얼로그는 호출되며, 모든 소스source들은 쿼리될 것이다. 디폴트 값은 거짓false이다.
• Quick Search Box로부터 소스source 검색lookup을 일으키기 위해 필요한 글자의 최소 갯수를 가리킨다. 임계치threshold보다 더 짧은 어떤 것에 대해서는 소스source가 쿼리되지 않는다는 것을 보장할 뿐이다. 디폴트 값은 0이다.

여러분의 액티비티에 대한 음성 검색을 활성화하기 위해, 여러분은 음성 검색을 활성화하고 설정하는 searchable 메타데이터에 필드들을 추가할 수 있다. 다음에 나오는 것이 음성 검색을 구현할 때 사용하는 추가적인 <searchable> 애트리뷰트들이다.

• voiceSearchMode - 음성 검색 능력을 제공하기 위해 필수임. 만약 이것이 제공되고 비워있지 않다면, 음성 검색을 활성화한다. (음성 검색은 디바이스에 의해 제공되지 않을 수도 있다. 이러한 경우에 이 플래그들은 아무런 영향을 주지 않을 것이다.) 다음에 나오는 모드mode 값들이 허용된다.
  • showVoiceSearchButton - 만약 이것이 지정되면, 음성 검색 버튼을 표시한다. 이것은 음성 검색이 디바이스에서 유용한 경우에만 영향을 가진다. 만약 이것이 지정되면, “launchWebSearch” 또는 “launchRecognizer” 또한 지정되어야 한다.
  • launchWebSearch - 만약 이것이 지정되면, 음성 검색 버튼은 해당 사용자를 직접적으로 내장된 음성 웹 검색 액티비티에 이르게 할 것이다. 대부분의 애플리케이션은 이 플래그를 사용하지 않을 것이다. 왜냐하면 그것은 그러한 검색이 호출되었던 액티비티로부터 사용자를 벗어나게 할 것이기 때문이다.
  • launchRecognizer - 만약 이것이 지정되면, 음성 검색 버튼은 해당 사용자를 직접적으로 내장된 음성 녹음 액티비티에 이르게 할 것이다. 이 액티비티는 사용자가 말하도록 요구할 것이며, 말했던 텍스트를 문자로 기록하고, 그리고 마치 사용자가 검색 UI에 그것을 타이프하고 검색 버튼을 클릭한 것처럼, 검색가능한 액티비티에 생성된 쿼리 텍스트를 전달할 것이다.
• voiceLanguageModel - RecognizerIntent로부터의 문자열 상수. 만약 이것이 제공되면, 이것은 음성 인식 시스템에 의해 사용되어야 하는 언어 모델을 지정한다. 더 많은 정보에 대해서는 EXTRA_LANGUAGE_MODEL을 보라. 만약 이것이 제공되지 않으면, 디폴트 값으로 LANGUAGE_MODEL_FREE_FORM이 사용될 것이다.
• voicePromptText - 문자열. 만약 이것이 제공되면, 이것은 음성 입력 동안 보여지게 될 프롬프트를 지정한다. 만약 이것이 제공되지 않으면, 디폴트 프롬프트가 보여지게 될 것이다.
• voiceLanguage - 로케일Locale로부터의 문자열 상수. 만약 이것이 제공되면, 이것은 기대되는 구어spoken language를 지정한다. 이것은 현재의 getDefault()의 값과 다른 경우에만 필요하다.
• voiceMaxResults - 만약 이것이 제공되면, SEARCH 인텐트의 기본 쿼리로써 항상 제공될 “최적의best” 결과를 포함하는 리턴 결과의 최대 개수를 강제한다. 1 또는 그것보다 더 커야 한다. 인텐트로부터 그 결과를 얻기 위해 EXTRA_RESULTS를 사용하라. 만약 이것이 제공되지 않으면, 인식기는 리턴할 많은 결과를 선택할 것이다.

<actionkey>

검색 액션에 대한 쇼트컷shortcut 키를 정의한다.

• keycode - 필수임. 이 애트리뷰트는 여러분이 응답하고자 하는 액션 키를 나타낸다. 모든 액션 키들이 실질적으로 이러한 메커니즘을 사용하는 것이 지원되지는 않는다는 것에 주의하라. 그것들 중 많은 것은 타이핑, 네비게이션, 또는 시스템 기능을 위해 사용된다. 이것은 여러분의 검색가능한 액티비티에 전달되는 ACTION_SEARCH 인텐트에 추가될 것이다. 해당 키코드keycode를 보려면, getIntExtra(SearchManager.ACTION_KEY)를 사용하라. 키코드keycode와 더불어, 여러분은 또한 하나 또는 그 이상의 아래에 있는 액션 지정자specifier 애트리뷰트들을 제공해야 한다는 것에 주의하라.
• queryActionMsg - 만약 여러분이 보통의 검색 쿼리를 입력하는 동안 액션 키를 제어하고자 한다면, 여러분은 여기에 액션 문자열을 정의해야 한다. 이것은 여러분의 검색가능한 액티비티에 전달되는 ACTION_SEARCH 인텐트에 추가될 것이다. 그 문자열을 보려면, getStringExtra(SearchManager.ACTION_MSG)를 사용하라.
• suggestActionMsg - 만약 여러분이 추천어suggestion가 보여지고 선택되는 동안에 액션 키를 제어하고자 한다면, 이것을 제어하는 두 가지 방법이 있다. 만약 여러분의 모든 추천어suggestions가 액션 키를 제어할 수 있다면, 여러분은 간단하게 이 애트리뷰트를 사용하는 액션 메시지를 정의할 수 있다. 이것은 여러분의 검색가능한 액티비티에 전달되는 ACTION_SEARCH 인텐트에 추가될 것이다. 그 문자열을 보려면, getStringExtra(SearchManager.ACTION_MSG)를 사용하라.
• suggestActionMsgColumn - 만약 여러분이 추천어suggestion가 보여지고, 선택되는 동안에 액션 키를 제어하고자 하지만, 모든 추천어suggestion에 대해 이 액션 키를 활성화하길 원하지 않는다면, 여러분은 추천어들suggestion-by-suggestion의 기반에 그것을 제어하기 위해 이 애트리뷰트를 사용할 수 있다. 먼저, 여러분은 액션 문자열을 포함할 여러분의 추천어suggestion가 있는 하나의 컬럼을 정의해야 한다. 그리고 나서 여러분의 컨텐트 프로바이더에서 이 컬럼을 제공해야 한다. 그리고 필요할 때, 이 컬럼에 데이터를 제공하라. 검색 관리자는 하나의 컬럼을 선택하기 위해 여기에서 제공되는 문자열을 사용하는 여러분의 추천어suggestion 커서를 확인할 것이다. 그리고 커서로부터 하나의 문자열을 선택하기 위해 그것을 사용할 것이다. 그 문자열은 여러분의 검색가능한 액티비티에 전달되는 ACTION_SEARCH 인텐트에 추가될 것이다. 그 문자열을 보려면, getStringExtra(SearchManager.ACTION_MSG)를 사용하라. 만약 선택된 추천어suggestion에 대한 데이터가 존재하지 않는다면, 액션 키는 무시될 것이다.