UserGuide

iOS Picker Controls

From Xojo Documentation

These controls are part of the Pickers group in the Library and are used to select a value.

Date Picker (iOSDatePicker)

The Date Picker control is used to let the user choose a date or date-related value. The Date Picker can display date values in these formats:

  • Time
  • Date
  • Date and Time
  • Countdown Timer

By using a Date Picker, you can ensure that you get a valid date value from the user.

The Date Picker has these event handlers:

ValueChanged

Called when the user selects a date (or time or countdown). Use the properties below to get the value that was selected.

These are the commonly used properties: CountdownDuration

Specifies the initial duration (in seconds) to display when Mode is Countdown Timer. It is also the currently displayed countdown duration, so use this to get the value the user has picked.

DefaultDate

A Date value that specified the intial date to have centered in the Date Picker. It is also the currently displayed date, so use this to get the date value the user has picked. This is applicable when Mode is Date or DateAndTime.

Enabled

A boolean that indicates if the date picker is enabled and can be used or disabled and cannot be used.

MaximumDate

The maximum date that can be selected.

MinimumDate

The minimum date that can be selected.

MinuteInterval

The number of minutes to show in the selector when Mode is Countdown Timer. The default is 1.

Mode

Specifies the type of Date Picker that is displayed (using the DatePickerMode enumeration): Time, Date, DateAndTime and CountDownTimer.

There is a single method that can also be useful: DefaultDate

Allows you to set the default date, showing a scrolling animation to the specified date.

Usage

If you want to get notified every time the Date Picker value is changed, then use the ValueChanged event handler. If you would prefer to get the value at a time or your own choosing, you can refer to the properties.

For example, if you want to have a button that says "Get Selected Date", then it's Action event handler could have code like this:

Dim selectedDate As Date
selectedDate = MyDatePicker.DefaultDate

That same code can also go in the ValueChanged event handler, which means it will be called every time the date changes.

By default the Date Picker shows the current date (when in Date or DateAndTime modes). You can also have a different date as the default by setting the DefaultDate property. This code in the Open event handler for the Date Picker sets the default date:

Dim halloween As New Date(2015, 10, 31, TimeZone.Current)
MyDatePicker.DefaultDate = halloween

If you are using the Time mode and want to display a specific time, you would also set it using the CurrentDate property. In this case, be sure to set the time component of the date:

Dim halloween As New Date(2015, 10, 31, 11, 15, 00, TimeZone.Current) // 11:15 am
MyDatePicker.DefaultDate = halloween

When using a CountDown Timer, you can set the initial countdown time by setting CountdownDuration in seconds. This sets the initial value to 15 minutes:

MyCountdownPicker.CountdownDuration = 60 * 15

Location (iOSLocation)

The Location control provides a way for you to get location information for the device. This is not a visual control, so dragging it appears on the Shelf when dragged to the layout.

Use the Debug ↠ Location menu in the iOS Simulator to provide locations for testing.

Frequently getting the location can cause significant battery drain, so only be sure to set Enabled = False when it is not needed.

The primary event is:

LocationChanged

Called when a location update is received from iOS.

You can change how location works using these properties:

Accuracy

Specifies the level of accuracy for the location using the Accuracies enum. The "Best" accuracy is used by default, but you can increase or decrease the accuracy as necessary to manage battery usage.

AuthorizationState

Indicates the level of authorization that is allowed for location. Check this before enabling.

Enabled

When enabled is True, the LocationChanged event is called with location updates. You should set this to False when the location is not needed.

Usage

Before you can get the location you must request authorization. This is typically done like this:

If MyLocation.AuthorizationState = iOSLocation.AuthorizationStates.AuthorizedWhenInUse Then
// we've got our requested authorization state, start getting LocationChanged events
MyLocation.Enabled = True
Else
// we don't have authorization yet, so ask for it
MyLocation.RequestInUseAuthorization
End If

Once the control is enabled you will start getting LocationChanged events when the location is updated.

Message Box (iOSMessageBox)

A Message Box displays a prompt for the user. The control is not a UI control so it appears on the Shelf rather than the UI layout.

Refer to the Dialog Boxes topic for details on how to use a Message Box.

Picture Picker (iOSPicturePicker)

A Picture Picker provides a way for the user to choose an existing picture from the camera roll, photo library, or they can choose to take a new picture. This control does not have UI that displays on the layout so it appears in the Shelf when dragged to the layout.

These two events can be used:

Cancelled

Called when the user cancels picking a picture.

Selected

Called when the user selects a picture or takes a picture. The picture is provided as a parameter.

These properties control what the Picture PIcker lets you choose from: IsEditable

Enables some basic editing controls in the Picture Picker.

Source

Specifies the where the user can choose the picture from using the Sources enum: Camera, CameraRoll, PhotoLibrary.

This method displays the Picture Picker: Show

Displays the Picture Picker. You have to provide the parent view.

Usage

This code lets the user pick a picture from the photo library:

PicturePicker1.Source = iOSPicturePicker.Sources.PhotoLibrary
PicturePicker1.Show(Self)

This code in the Selected event handler displays the selected picture in an Image View:

MyImageView.Image = pic

Video

Watch this short video to see how to use the Picture Picker control:

Sharing Panel (iOSSharingPanel)

The Sharing Panel allows the application to share text, a URL, or a picture with any registered system service or app. This control does not have a user interface that displays on the layout so it appears in the Shelf when dragged to the layout. However when is is activated it does display a user interface. This is an example of a simple sharing panel as shown on an iPhone:

These events can be used:

Cancelled

Called if the user cancels the sharing operation.

Completed

Called when the sharing operation is completed.

These methods are used to display the different sharing panels: SharePicture

Shares a picture. You need to provide the picture, the parent view and parent control.

ShareText

Shares text. You need to provide the text, the parent view and parent control.

ShareURL

Share a URL. You need to provide the URL, the parent view and parent control.

Usage

This code on a button's Action event handler shares text:

SharingPanel1.ShareText("Hello world!", Self, Me)

Video

Watch this short video to see how to use the Sharing Panel control:

Slider (iOSSlider)

The Slider control provides an interface that is used for increasing or decreasing a numeric value. The Slider can only be displayed horizontally.

You can use the Set Default Value feature to set the default position of the slider.

The most commonly used event is:

ValueChanged

Called when the Slider value changes, either by the user adjusting the Slider or by code changing its Value property.

These properties are often used with a Slider:

Enabled

A boolean that indicates if the slider is enabled and can be adjusted or disabled and cannot be adjusted.

MaxValue

The maximum Double value for the slider.

MinValue

The minimum Double value for the slider.

Value

An Double value that indicates the position of the Slider. If Value is assigned a value less than MinValue, then MinValue is used. If Value is assigned a value greater than MaxValue, then MaxValue is used.

Visible

A boolean that indicates whether the button is shown on the layout when the app is running.

Usage

To have a Slider update a Label with its Value as the Slider is adjusted, you can put this code in the Slider's ValueChanged event handler:

SliderLabel.Text = Me.Value.ToText

Switch (iOSSwitch)

A Switch has an on/off position and is used to choose a preference. When the Switch is on, it appears with a green background.

This event is most used with a Switch:

ValueChanged

Called when the value for the Switch is changed, either by the user clicking on it or by code changing its Value property.

These properties are often used with Switch:

Enabled

A boolean that indicates if the switch is enabled and can be tapped or disabled and cannot be changed.

Value

A boolean that indicates the state of the Switch. When True, the Switch is on and displays with a green background. When False, the Switch is off.

Visible

A boolean that indicates whether the button is shown on the layout when the app is running.

Usage

To turn a switch on, set its value property:

MySwitch.Value = True

This code in the ValueChanged event handler enables or disables a Text Field depending on whether a Switch is on or off:

If Me.Value Then
MyTextField.Enabled = True
Else
MyTextField.Enabled = False
End If