User Interface Components - AppyBuilder for Android

Table of Contents

• Button
• CheckBox
• Clock
• Image
• Label
• ListPicker
• Notifier
• PasswordTextBox
• Screen
• Slider
• TextBox
• WebViewer

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 Enabled property to choose whether a button can be tapped.

Properties

BackgroundColor

Color for button background.

Enabled

If set, user can tap button to cause action.

FontBold

If set, button text is displayed in bold.

FontItalic

If set, button text is displayed in italics.

FontSize

Point size for button text.

FontTypeface

Font family for button text.

Height

Button height (y-size).

Width

Button width (x-size).

Image

Image to display on button.

Text

Text to display on button.

TextAlignment

Left, center, or right.

TextColor

Color for button text.

Events

Click()

User tapped and released the button.

GotFocus()

Button became the focused component.

LostFocus()

Button stopped being the focused component.

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

BackgroundColor

Color for check box background.

Checked

True if the box is checked, false otherwise.

Enabled

If set, user can tap check box to cause action.

Height

Check box height (y-size).

Width

Check box width (x-size).

Text

Text to display on check box.

TextColor

Color for check box text.

Visible

If set, check box is visible.

Events

Click()

User tapped and released check box.

GotFocus()

Check box became the focused component.

LostFocus()

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

TimerInterval

timer interval in milliseconds

TimerEnabled

If true, then the timer will fire

TimerAlwaysFires

if true, the timer will fire even if the application is not showing on the screen

Events

Timer()

This event is signaled when the timer fires

Methods

SystemTime()

The phone's internal time in milliseconds

Now()

The instant in time read from phone's clock

MakeInstant(Text from)

Make an instant specified by MM/DD/YYYY hh:mm:ss or MM/DD/YYYY or hh:mm.

MakeInstantFromMillis(Number millis)

Make an instant specified by time in milliseconds

GetMillis(instant)

The instant in time measured as milliseconds since 1970

AddSeconds(instant, Number seconds)

An instant in time some number of seconds after the given instant

AddMinutes(instant, Number minutes)

An instant in time some number of minutes after the given instant

AddHours(instant, Number hours)

An instant in time some number of hours after the given instant

AddDays(instant, Number days)

An instant in time some number of days after the given instant

AddWeeks(instant, Number weeks)

An instant in time some number of weeks after the given instant

AddMonths(instant, Number months)

An instant in time some number of months after the given instant

AddYears(instant, Number years)

An instant in time some number of years after the given instant

Duration(Calendar start, Calendar end)

Milliseconds between instants

Second(Calendar instant)

The second of the minute

Minute(Calendar instant)

The minute of the hour

Hour(Calendar instant)

The hour of the day

DayOfMonth(Calendar instant)

The day of the month,a number from 1 to 31

Weekday(Calendar instant)

The day of the week. a number from 1 (Sunday) to 7 (Saturday)

WeekdayName(Calendar instant)

The name of the day of the week

Month(Calendar instant)

The month of the year, a number from 1 to 12)

MonthName(Calendar instant)

The name of the month

Year(Calendar instant)

The year

FormatDateTime(Calendar instant)

Text describing the date and time of an instant

FormatDate(Calendar instant)

Text describing the date of an instant

FormatTime(Calendar instant)

Text describing time time of an instant

Image

Component for displaying images. The picture to display, and other aspects of the Image's appearance, can be specified in the Designer or in the Blocks Editor.

Properties

Animation

This is a limited form of animation that can attach a small number of motion types to images. The allowable motions are ScrollRightSlow, ScrollRight, ScrollRightFast, ScrollLeftSlow, ScrollLeft, ScrollLeftFast, and Stop

Height

Picture

Visible

Specifies whether the component should be visible on the screen. Value is true if the component is showing and false if hidden.

Width

Events

none

Methods

none

Label

Labels are components used to show text.

A label displays text which is specified by the Text property. Other properties, all of which can be set in the Designer or Blocks Editor, control the appearance and placement of the text.

Properties

BackgroundColor

Color for label background.

FontBold

If set, label text is displayed in bold.

FontItalic

If set, label text is displayed in italics.

FontSize

Point size for label text.

FontTypeface

Font family for label text.

Height

Label height (y-size).

Width

Label width (x-size).

Text

Text to display on label.

TextAlignment

Left, center, or right.

TextColor

Color for label text.

Visible

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 ElementsFromString property to their comma-separated concatenation (for example, choice 1, choice 2, choice 3 ) or by setting the Elements property to a List in the Blocks Editor.

Other properties, including TextAlignment and BackgroundColor , affect the appearance of the button and whether it can be tapped ( Enabled ).

Properties

Selection

Selected list element.

Items

Comma-separated list of items to display in component.

ElementsFromString

(Description to come.)

BackgroundColor

Color for list picker background.

FontBold

If set, list picker text is displayed in bold.

FontItalic

If set, list picker text is displayed in italics.

FontSize

Point size for list picker text.

FontTypeface

Font family for list picker text.

Height

List picker height (y-size).

Image

Specifies the path of the button's image. If there is both an Image and a BackgroundColor, only the Image will be visible.

Selection

The selected item. When directly changed by the programmer, the SelectionIndex property is also changed to the first item in the ListPicker with the given value. If the value does not appear, SelectionIndex will be set to 0.

SelectionIndex

The index of the currently selected item, starting at 1. If no item is selected, the value will be 0. If an attempt is made to set this to a number less than 1 or greater than the number of items in the ListPicker, SelectionIndex will be set to 0, and Selection will be set to the empty text.

Shape (designer only)

Specifies the button's shape (default, rounded, rectangular, oval). The shape will not be visible if an Image is being displayed.

ShowFeedback

Specifies if a visual feedback should be shown for a button that as an image as background.

ShowFilterBar

Returns current state of ShowFilterBar indicating if Search Filter Bar will be displayed on ListPicker or not

Text

Title text to display on list picker.

TextAlignment

Left, center, or right.

TextColor

Color for list picker text.

Visible

If set, list picker is visible.

Width

List picker width (x-size).

Events

AfterPicking()

User selected an item from the list picker.

BeforePicking()

User has tapped the list picker but hasn't yet selected an item.

GotFocus()

List picker became the focused component.

LostFocus()

List picker is no longer the focused component.

Methods

Open()

Opens the picker, as though the user clicked on it.

Notifier

Notifier

The Notifier component displays alert messages and creates Android log entries through the following methods:

• ShowMessageDialog: user must dismiss the message by pressing a button.
• ShowChooseDialog: displays two buttons to let the user choose one of two responses, for example, yes or no, after which the AfterChoosing event is raised.
• ShowTextDialog: lets the user enter text in response to the message, after which the AfterTextInput event is raised.
• ShowAlert: displays an alert that goes away by itself after a short time.
• LogError: logs an error message to the Android log.
• LogInfo: logs an info message to the Android log.
• LogWarning: logs a warning message to the Android log.

Properties

BackgroundColor

Specifies the alert's background color.

NotifierLength (designer only)

specifies the length of time that the alert is shown -- either "short" or "long".

TextColor

Specifies the alert's text color.

Events

AfterChoosing(text choice)

Event after the user has made a selection for ShowChooseDialog.

AfterTextInput(text response)

Event raised after the user has responded to ShowTextDialog.

Methods

LogError(text message)

Writes an error message to the Android log.

LogInfo(text message)

Writes an information message to the Android log.

LogWarning(text message)

Writes a warning message to the Android log.

ShowAlert(text notice)

Display a temporary notification

ShowChooseDialog(text message, text title, text button1Text, text button2Text, boolean cancelable)

Displays an alert with two buttons that have specified text, and additional button marked CANCEL if cancelable is set. Raises the AfterChoosing event when the choice has been made, and returns the text of the button that was pressed.

ShowMessageDialog(text message, text title, text buttonText)

Display an alert dialog with a single button that dismisses the alert.

ShowTextDialog(text message, text title, boolean cancelable)

Shows a dialog box in which the user can enter text, after which the AfterTextInput event is raised.

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 TextBox 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 Text property. If Text is blank, you can use the Hint property to provide the user with a suggestion of what to type. The Hint 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

BackgroundColor

Color for text box background.

Enabled

If set, user can enter a password in the box.

FontBold

If set, text is displayed in bold.

FontItalic

If set, text is displayed in italics.

FontSize

Point size for text.

FontTypeface

Font family for text.

Height

Box height (y-size).

Width

Box width (x-size).

TextAlignment

Left, center, or right.

TextColor

Color for text.

Hint

Password hint.

Events

GotFocus()

Box became the focused component.

LostFocus()

Box 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

BackgroundColor

Color for screen background.

BackgroundImage

An image that forms the screen's background.

CloseScreenAnimation

The animation for closing current screen and returning to the previous screen. Valid options are default, fade, zoom, slidehorizontal, slidevertical, and none

Height

Screen height (y-size).

Icon

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 AppyBuilder from being able to package the application.

OpenScreenAnimation

The animation for switching to another screen. Valid options are default, fade, zoom, slidehorizontal, slidevertical, and none

ScreenOrientation

The requested screen orientation. Commonly used values are unspecified (-1), landscape (0), portrait (1), sensor (4), and user (2). See the Android developer docuemntation for ActivityInfo.Screen_Orientation for the complete list of possible settings.

Scrollable

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.

Title

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.

VersionCode

An integer value which must be incremented each time a new Android Application Package File (APK) is created for the Google Play Store.

VersionName

A string which can be changed to allow Google Play Store users to distinguish between different versions of the App.

Width

Screen width (x-size).

Events

BackPressed()

Device back button pressed.

ErrorOccurred(component component, text functionName, number errorNumber, text message)

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.

Initialize()

Signaled when the application starts. It can be used setting initial values and performing other setup operations.

OtherScreenClosed(text otherScreenName, any result)

Event raised when another screen has closed and control has returned to this screen.

ScreenOrientationChanged()

Screen orientation changed

Slider

A Slider is a progress bar that adds a draggable thumb. You can touch the thumb and drag left or right to set the slider thumb position. As the Slider thumb is dragged, it will trigger the PositionChanged event, reporting the position of the Slider thumb. The reported position of the Slider thumb can be used to dynamically update another component attribute, such as the font size of a TextBox or the radius of a Ball.

Properties

ColorLeft

The color of slider to the left of the thumb.

ColorRight

The color of slider to the left of the thumb.

MaxValue

Sets the maximum value of slider. Changing the maximum value also resets Thumbposition to be halfway between the minimum and the (new) maximum. If the new maximum is less than the current minimum, then minimum and maximum will both be set to this value. Setting MaxValue resets the thumb position to halfway between MinValue and MaxValue and signals the PositionChanged event.

MinValue

Sets the minimum value of slider. Changing the minimum value also resets Thumbposition to be halfway between the (new) minimum and the maximum. If the new minimum is greater than the current maximum, then minimum and maximum will both be set to this value. Setting MinValue resets the thumb position to halfway between MinValue and MaxValue and signals the PositionChanged event.

ThumbPosition

Sets the position of the slider thumb. If this value is greater than MaxValue, then it will be set to same value as MaxValue. If this value is less than MinValue, then it will be set to same value as MinValue.

Visible

Specifies whether the component should be visible on the screen. Value is true if the component is showing and false if hidden.

Width

Events

PositionChanged(number thumbPosition)

Indicates that position of the slider thumb has changed.

Methods

none

TextBox

Users enter text in a text box component.

The initial or user-entered text value in a text box component is in the Text property. If Text is blank, you can use the Hint property to provide the user with a suggestion of what to type. The Hint appears as faint text in the box.

The MultiLine 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 NumbersOnly property restricts the keyboard to accept numeric input only.

Other properties affect the appearance of the text box ( TextAlignment , BackgroundColor , etc.) and whether it can be used ( Enabled ).

Text boxes are usually used with the Button component, with the user clicking on the button when text entry is complete.

If the text entered by the user should not be displayed, use PasswordTextBox instead.

Properties

BackgroundColor

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 3-D look).

Enabled

Whether the user can enter text into this input box. By default, this is true.

FontBold (designer only)

Whether the font for the text should be bold. By default, it is not.

FontItalic (designer only)

Whether the text should appear in italics. By default, it does not.

FontSize

The font size for the text. By default, it is 14.0 points.

FontTypeface (designer only)

The font for the text. The value can be changed in the Designer.

Height

Hint

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 Text property is empty.

MultiLine

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.

NumbersOnly

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.

Text

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 Enabled property is false).

TextAlignment (designer only)

Whether the text should be left justified, centered, or right justified. By default, text is left justified.

TextColor

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.

Visible

Whether the component is visible

Width

Events

GotFocus()

Event raised when this component is selected for input, such as by the user touching it.

LostFocus()

Event raised when this component is no longer selected for input, such as if the user touches a different text box.

Methods

HideKeyboard()

Hide the keyboard. Only multiline text boxes need this. Single line text boxes close the keyboard when the users presses the Done key.

WebViewer

Component for viewing Web pages. The Home URL can be specified in the Designer or in the Blocks Editor. The view can be set to follow links when they are tapped, and users can fill in Web forms. Warning: This is not a full browser. For example, pressing the phone's hardware Back key will exit the app, rather than move back in the browser history.

Properties

CurrentPageTitle

Title of the page currently viewed

CurrentUrl

URL of the page currently viewed. This could be different from the Home URL if new pages were visited by following links.

FollowLinks

Determines whether to follow links when they are tapped in the WebViewer. If you follow links, you can use GoBack and GoForward to navigate the browser history.

Height

HomeUrl

URL of the page the WebViewer should initially open to. Setting this will load the page.

PromptforPermission

If True, then prompt the user of the WebView to give permission to access the geolocation API. If False, then assume permission is granted.

UsesLocation (designer only)

Whether or not to give the application permission to use the Javascript geolocation API. This property is available only in the designer.

Visible

Whether the component is visible

Width

Events

none

Methods

boolean CanGoBack()

Returns true if the WebViewer can go back in the history list.

boolean CanGoForward()

Returns true if the WebViewer can go forward in the history list.

GoBack()

Go back to the previous page in the history list. Does nothing if there is no previous page.

GoForward()

Go forward to the next page in the history list. Does nothing if there is no next page.

GoHome()

Loads the home URL page. This happens automatically when the home URL is changed.

GoToUrl(text url)

Load the page at the given URL.