20/04/13

Basic Components - App Inventor for Android

Learn about App Inventor

Learn > Reference > Basic >

About

Learn

Forum

Basic Components
Table of Contents
Button Canvas CheckBox Clock Image Label ListPicker PasswordTextBox Screen TextBox TinyDB

Button

Buttons are components that users touch to perform some action in your app. Buttons detect when users tap them. Many aspects of a button's appearance can be changed. You can use the E n a b l e d property to choose whether a button can be tapped.

Properties
B a c k g r o u n d C o l o r Color for button background. E n a b l e d If set, user can tap button to cause action. F o n t B o l d If set, button text is displayed in bold. F o n t I t a l i c If set, button text is displayed in italics. F o n t S i z e Point size for button text. F o n t T y p e f a c e Font family for button text. H e i g h t Button height (y-size). W i d t h Button width (x-size). I m a g e Image to display on button. T e x t Text to display on button. T e x t A l i g n m e n t Left, center, or right. T e x t C o l o r Color for button text.

Events
C l i c k ( ) User tapped and released the button. G o t F o c u s ( ) Button became the focused component. L o s t F o c u s ( ) Button stopped being the focused component.

Canvas

A two-dimensional touch-sensitive rectangular panel on which drawing can be done and sprites can be moved. The B a c k g r o u n d C o l o r, P a i n t C o l o r, B a c k g r o u n d I m a g e, W i d t h , and H e i g h t of the Canvas can be set in either the Designer or in the Blocks Editor. The W i d t h and H e i g h t are measured in pixels and must be positive. Any location on the Canvas can be specified as a pair of (X, Y) values, where

beta.appinventor.mit.edu/learn/reference/components/basic.html#ListPicker

1/8

20/04/13

Basic Components - App Inventor for Android

X is the number of pixels away from the left edge of the Canvas Y is the number of pixels away from the top edge of the Canvas

There are events to tell when and where a Canvas has been touched or a S p r i t e(I m a g e S p r i t e or B a l l ) has been dragged. There are also methods for drawing points, lines, and circles.

Properties
B a c k g r o u n d C o l o r The color of the canvas background. B a c k g r o u n d I m a g e The name of a file containing the background image for the canvas H e i g h t L i n e W i d t h The width of lines drawn on the canvas. P a i n t C o l o r The color in which lines are drawn V i s i b l e Whether the component is visible W i d t h

Events
D r a g g e d ( n u m b e rs t a r t X ,n u m b e rs t a r t Y ,n u m b e rp r e v X ,n u m b e rp r e v Y ,n u m b e rc u r r e n t X ,n u m b e rc u r r e n t Y ,b o o l e a nd r a g g e d S p r i t e ) When the user does a drag from one point (prevX, prevY) to another (x, y). The pair (startX, startY) indicates where the user first touched the screen, and "draggedSprite" indicates whether a sprite is being dragged. F l u n g ( n u m b e rs t a r t X ,n u m b e rs t a r t Y ,n u m b e rx S p e e d ,n u m b e ry S p e e d ) When the user performs a fling (quick swipe) on the screen. Provides the (x, y) position of the start of the fling, relative to the upper left of the canvas. Also provides the x velocity and y velocity of the fling. T o u c h D o w n ( n u m b e rx ,n u m b e ry ) When the user starts touching the canvas (putting finger down for the first time). Provides the (x,y) position of the touch relative to the upper-left corner of the canvas. T o u c h e d ( n u m b e rx ,n u m b e ry ,b o o l e a nt o u c h e d S p r i t e ) When the user touches a canvas, providing the (x, y) position of the touch relative to the upper left corner of the canvas. The value "touchedSprite" is true if a sprite was also in this position. T o u c h U p ( n u m b e rx ,n u m b e ry ) When the user stops touching the canvas (lifting his/her finger up). Provides the (x, y) position of the touch relative to the upper left corner of the canvas.

Methods
C l e a r ( ) Clears the canvas, without removing the background image, if one was provided. D r a w C i r c l e ( n u m b e rx ,n u m b e ry ,n u m b e rr ) Draws a circle (filled in) at the given coordinates on the canvas, with the given radius. D r a w L i n e ( n u m b e rx 1 ,n u m b e ry 1 ,n u m b e rx 2 ,n u m b e ry 2 ) Draws a line between the given coordinates on the canvas. D r a w P o i n t ( n u m b e rx ,n u m b e ry ) Draws a point at the given coordinates on the canvas. S a v e ( ) Saves a picture of this Canvas to the device's external storage and returns the full path name of the saved file. If an error occurs the Screen's E r r o r O c c u r r e d event will be called. S a v e A s ( t e x tf i l e n a m e ) Saves a picture of this Canvas to the device's external storage in the file named fileName. fileName must end with one of ".jpg", ".jpeg", or ".png" (which determines the file type: JPEG, or PNG). Returns the full path name of the saved file.

CheckBox

Check box components can detect user taps and can change their boolean state in response. A check box component raises an event when the user taps it. There are many properties affecting its appearance that can be set in the Designer or Blocks Editor.

Properties
B a c k g r o u n d C o l o r Color for check box background. C h e c k e d True if the box is checked, false otherwise. E n a b l e d If set, user can tap check box to cause action. H e i g h t Check box height (y-size). W i d t h Check box width (x-size). T e x t Text to display on check box. T e x t C o l o r

beta.appinventor.mit.edu/learn/reference/components/basic.html#ListPicker

2/8

20/04/13
Color for check box text. V i s i b l e If set, check box is visible.

Basic Components - App Inventor for Android

Events
C l i c k ( ) User tapped and released check box. G o t F o c u s ( ) Check box became the focused component. L o s t F o c u s ( ) Check box stopped being the focused component.

Clock

Use a clock component to create a timer that signals events at regular intervals. The clock component also does various conversions and manipulations with time units. One use of the clock component is a a timer : set the timer interval, and the timer will fire repeatedly at the interval, signalling a timer event. A second use of the clock component is to manipulate time, and express time in various units. The internal time format used by the clock is called an instant . The clock's N o w method returns the current time as an instant. The clock provides methods to manipulate instants, for example, return an instant that is several seconds, or months, or years from the given instant. It also provides methods to show the second, minute, hour, day, , corresponding to a given instant.

Properties
T i m e r I n t e r v a l timer interval in milliseconds T i m e r E n a b l e d If true, then the timer will fire T i m e r A l w a y s F i r e s if true, the timer will fire even if the application is not showing on the screen

Events
T i m e r ( ) This event is signaled when the timer fires

Methods
S y s t e m T i m e ( ) The phone's internal time in milliseconds N o w ( ) The instant in time read from phone's clock M a k e I n s t a n t ( T e x tf r o m ) Make an instant specified by MM/DD/YYYY hh:mm:ss or MM/DD/YYYY or hh:mm. M a k e I n s t a n t F r o m M i l l i s ( N u m b e rm i l l i s ) Make an instant specified by time in milliseconds G e t M i l l i s ( i n s t a n t ) The instant in time measured as milliseconds since 1970 A d d S e c o n d s ( i n s t a n t ,N u m b e rs e c o n d s ) An instant in time some number of seconds after the given instant A d d M i n u t e s ( i n s t a n t ,N u m b e rm i n u t e s ) An instant in time some number of minutes after the given instant A d d H o u r s ( i n s t a n t ,N u m b e rh o u r s ) An instant in time some number of hours after the given instant A d d D a y s ( i n s t a n t ,N u m b e rd a y s ) An instant in time some number of days after the given instant A d d W e e k s ( i n s t a n t ,N u m b e rw e e k s ) An instant in time some number of weeks after the given instant A d d M o n t h s ( i n s t a n t ,N u m b e rm o n t h s ) An instant in time some number of months after the given instant A d d Y e a r s ( i n s t a n t ,N u m b e ry e a r s ) An instant in time some number of years after the given instant D u r a t i o n ( C a l e n d a rs t a r t ,C a l e n d a re n d ) Milliseconds between instants S e c o n d ( C a l e n d a ri n s t a n t ) The second of the minute M i n u t e ( C a l e n d a ri n s t a n t ) The minute of the hour H o u r ( C a l e n d a ri n s t a n t ) The hour of the day D a y O f M o n t h ( C a l e n d a ri n s t a n t ) The day of the month,a number from 1 to 31 W e e k d a y ( C a l e n d a ri n s t a n t ) The day of the week. a number from 1 (Sunday) to 7 (Saturday)

beta.appinventor.mit.edu/learn/reference/components/basic.html#ListPicker

3/8

20/04/13
W e e k d a y N a m e ( C a l e n d a ri n s t a n t ) The name of the day of the week M o n t h ( C a l e n d a ri n s t a n t ) The month of the year, a number from 1 to 12) M o n t h N a m e ( C a l e n d a ri n s t a n t ) The name of the month Y e a r ( C a l e n d a ri n s t a n t ) The year F o r m a t D a t e T i m e ( C a l e n d a ri n s t a n t ) Text describing the date and time of an instant F o r m a t D a t e ( C a l e n d a ri n s t a n t ) Text describing the date of an instant F o r m a t T i m e ( C a l e n d a ri n s t a n t ) Text describing time time of an instant

Basic Components - App Inventor for Android

Image

You use image components to represent images that users select and manipulate. An image component displays an image. You can specify the picture to display and other aspects of the image's appearance in the Designer or in the Blocks Editor.

Properties
P i c t u r e Picture displayed by this image. V i s i b l e If true, image is displayed. H e i g h t Image height (y-size). W i d t h Image width (x-size).

Label

Labels are components used to show text. A label displays text which is specified by the T e x t property. Other properties, all of which can be set in the Designer or Blocks Editor, control the appearance and placement of the text.

Properties
B a c k g r o u n d C o l o r Color for label background. F o n t B o l d If set, label text is displayed in bold. F o n t I t a l i c If set, label text is displayed in italics. F o n t S i z e Point size for label text. F o n t T y p e f a c e Font family for label text. H e i g h t Label height (y-size). W i d t h Label width (x-size). T e x t Text to display on label. T e x t A l i g n m e n t Left, center, or right. T e x t C o l o r Color for label text. V i s i b l e If set, label is visible.

ListPicker

Users tap a list picker component to select one item from a list of text strings. When a user taps a list picker, it displays a list of text items for the user to choose from. The text items can be specified through the Designer or Blocks Editor by setting the E l e m e n t s F r o m S t r i n g property to their comma-separated concatenation (for example, c h o i c e1 ,c h o i c e2 ,c h o i c e 3 ) or by setting the E l e m e n t s

beta.appinventor.mit.edu/learn/reference/components/basic.html#ListPicker

4/8

20/04/13
property to a L i s t in the Blocks Editor.

Basic Components - App Inventor for Android

Other properties, including T e x t A l i g n m e n t and B a c k g r o u n d C o l o r , affect the appearance of the button and whether it can be tapped ( E n a b l e d ).

Properties
S e l e c t i o n Selected list element. I t e m s Comma-separated list of items to display in component. E l e m e n t s F r o m S t r i n g (Description to come.) B a c k g r o u n d C o l o r Color for list picker background. F o n t B o l d If set, list picker text is displayed in bold. F o n t I t a l i c If set, list picker text is displayed in italics. F o n t S i z e Point size for list picker text. F o n t T y p e f a c e Font family for list picker text. H e i g h t List picker height (y-size). W i d t h List picker width (x-size). T e x t Title text to display on list picker. T e x t A l i g n m e n t Left, center, or right. T e x t C o l o r Color for list picker text. V i s i b l e If set, list picker is visible.

Events
A f t e r P i c k i n g ( ) User selected an item from the list picker. B e f o r e P i c k i n g ( ) User has tapped the list picker but hasn't yet selected an item. G o t F o c u s ( ) List picker became the focused component. L o s t F o c u s ( ) List picker is no longer the focused component.

Screen
The screen does not appear in the palette like other components, but if comes automatically with the project. Each project has exactly one screen, named Screen1. This name cannot be changed.

Properties
B a c k g r o u n d C o l o r Color for screen background. B a c k g r o u n d I m a g e An image that forms the screen's background. H e i g h t Screen height (y-size). i c o n An image to be used as the icon for the installed application on the phone. This should be a PNG or a JPG image; 48x48 is a good size. Warning: Specifying images other than PNG or JPG, for example GIF or .ico files, may prevent App Inventor from being able to package the application. S c r o l l a b l e This is set by a checkbox in the designer. When checked, there will be a vertical scrollbar on the screen, and the height of the application can exceed the physical height of the device. When unchecked, the application height is constrained to the height of the device. T i t l e Title for the screen (text). This will appear at the upper left of the phone when the application runs. A natural choice for the title is the title of the App, but you could make it something else, or even change it while the app is running. V e r s i o n C o d e An integer value which must be incremented each time a new Android Application Package File (APK) is created for the Google Play Store. V e r s i o n N a m e A string which can be changed to allow Google Play Store users to distinguish between different versions of the App. W i d t h Screen width (x-size).

Events

beta.appinventor.mit.edu/learn/reference/components/basic.html#ListPicker

5/8

20/04/13

Basic Components - App Inventor for Android

I n i t i a l i z e ( ) Signaled when the application starts. It can be used setting initial values and performing other setup operations. E r r o r O c c u r r e d ( c o m p o n e n tc o m p o n e n t ,t e x tf u n c t i o n N a m e ,n u m b e re r r o r N u m b e r ,t e x tm e s s a g e ) Signaled when an error occurs. The ErrorOccurred event is currently used for a small set of errors including: Errors that occur in the LEGO MINDSTORMS Nxt* components Errors that occur in the Bluetooth components Errors that occur in the Twitter component Errors that occur in the SoundRecorder component ActivityStarter - when StartActivity is called, but there is no activity that corresponds to the activity properties. LocationSensor - when LatitudeFromAddress or LongitudeFromAddress fails Player - when setting the Source property fails Sound - when setting the Source property fails or when the Play function fails VideoPlayer - when setting the Source property fails For those errors, the system will show a notification by default, with an error number and a message. You can use this event handler to prescribe an error behavior different than the default, by testing errorNumber and taking the appropriate action.

PasswordTextBox

Users enter passwords in a password text box component, which hides the text that has been typed in it. A password text box is the same as the ordinary T e x t B o x component, except that it does not display the characters typed by the user. You can get or set the value of the text in the box with the T e x t property. If T e x t is blank, you can use the H i n t property to provide the user with a suggestion of what to type. The H i n t appears as faint text in the box. Password text box components are usually used with a button component. The user taps the button after entering text.

Properties
B a c k g r o u n d C o l o r Color for text box background. E n a b l e d If set, user can enter a password in the box. F o n t B o l d If set, text is displayed in bold. F o n t I t a l i c If set, text is displayed in italics. F o n t S i z e Point size for text. F o n t T y p e f a c e Font family for text. H e i g h t Box height (y-size). W i d t h Box width (x-size). T e x t A l i g n m e n t Left, center, or right. T e x t C o l o r Color for text. H i n t Password hint.

Events
G o t F o c u s ( ) Box became the focused component. L o s t F o c u s ( ) Box is no longer the focused component.

TextBox

Users enter text in a text box component. The initial or user-entered text value in a text box component is in the T e x t property. If T e x t is blank, you can use the H i n t property to provide the user with a suggestion of what to type. The H i n t appears as faint text in the box. The M u l t i L i n e property determines if the text can have more than one line. For a single line text box, the keyboard will close automatically when the user presses the Done key. To close the keyboard for multiline text boxes, the app should use the HideKeyboard method or rely on the user to press the Back key. The N u m b e r s O n l y property restricts the keyboard to accept numeric input only. Other properties affect the appearance of the text box ( T e x t A l i g n m e n t, B a c k g r o u n d C o l o r , etc.) and whether it can be used ( E n a b l e d ). Text boxes are usually used with the B u t t o n component, with the user clicking on the button when text entry is complete.

beta.appinventor.mit.edu/learn/reference/components/basic.html#ListPicker

6/8

20/04/13

Basic Components - App Inventor for Android

If the text entered by the user should not be displayed, use P a s s w o r d T e x t B o x instead.

Properties
B a c k g r o u n d C o l o r The background color of the input box. You can choose a color by name in the Designer or in the Blocks Editor. The default background color is 'default' (shaded 3D look). E n a b l e d Whether the user can enter text into this input box. By default, this is true. F o n t B o l d (designer only) Whether the font for the text should be bold. By default, it is not. F o n t I t a l i c (designer only) Whether the text should appear in italics. By default, it does not. F o n t S i z e The font size for the text. By default, it is 14.0 points. F o n t T y p e f a c e (designer only) The font for the text. The value can be changed in the Designer. H e i g h t H i n t Text that should appear faintly in the input box to provide a hint as to what the user should enter. This can only be seen if the T e x t property is empty. M u l t i L i n e If true, then this text box accepts multiple lines of input, which are entered using the return key. For single line text boxes there is a Done key instead of a return key, and pressing Done hides the keyboard. The app should call the HideKeyboard method to hide the keyboard for a mutiline text box. N u m b e r s O n l y If true, then this text box accepts only numbers as keyboard input. Numbers can include a decimal point and an optional leading minus sign. This applies to keyboard input only. Even if NumbersOnly is true, you can use [set Text to] to enter any text at all. T e x t The text in the input box, which can be set by the programmer in the Designer or Blocks Editor, or it can be entered by the user (unless the E n a b l e d property is false). T e x t A l i g n m e n t (designer only) Whether the text should be left justified, centered, or right justified. By default, text is left justified. T e x t C o l o r The color for the text. You can choose a color by name in the Designer or in the Blocks Editor. The default text color is black. V i s i b l e Whether the component is visible W i d t h

Events
G o t F o c u s ( ) Event raised when this component is selected for input, such as by the user touching it. L o s t F o c u s ( ) Event raised when this component is no longer selected for input, such as if the user touches a different text box.

Methods
H i d e K e y b o a r d ( ) Hide the keyboard. Only multiline text boxes need this. Single line text boxes close the keyboard when the users presses the Done key.

TinyDB
Use a TinyDB component to store data that will be available each time the app runs. TinyDB is a non-visible component. Apps created with App Inventor are initialized each time they run. If an app sets the value of a variable and the user then quits the app, the value of that variable will not be remembered the next time the app is run. TinyDB is a persistent data store for the app, that is, the data stored there will be available each time the app is run. An example might be a game that saved the high score, and retrieved it each time the game is played. Data items are stored under tags . To store a data item, you specify the tag it should be stored under. Subsequently, you can retrieve the data item that was stored under a given tag. If there is no value stored under a tag, then the value returned is the empty text. Consequently, to see if a tag has a value stored under it, test whether the return value is equal to the empty text (i.e., a text box with no text filled in). There is only one data store per app. If you have multiple TinyDB components, they will use the same data store. To get the effect of separate stores, use different keys. Also each app has its own data store. You cannot use TinyDB to pass data between two different apps on the phone.

Properties
none

Events
none

Methods
S t o r e V a l u e ( t e x tt a g ,v a l u e T o S t o r e ) Store the value under the given tag. The t a g must be a text string; the value can be a string or a list. G e t V a l u e ( t e x tt a g ) Gets the value that was stored under the given tag. If no value was stored, returns the empty text.

beta.appinventor.mit.edu/learn/reference/components/basic.html#ListPicker

7/8

20/04/13

Basic Components - App Inventor for Android

To clear out the data base for an app, go on the phone under Settings Applications Manage Applications, the pick the app, and press "Clear Data". The data in TinyDB is persistent only when you have packaged and downloading your app. If you are developing connected to the phone, and you restart the Appinventor application, or if you disconnect and reconnect the phone, then the data base will start fresh. This is a case where the application is not merely being stopped and restarted; it is being removed from the phone and then reloaded.

This work is licensed under a Creative Commons Attribution 3.0 Unported License. Privacy Policy and Terms of Use.

Page last updated: 04/20/2013

beta.appinventor.mit.edu/learn/reference/components/basic.html#ListPicker

8/8