Titanium Mobile

# Titanium.UI.iPad.Popover

A Popover is used to manage the presentation of content in a popover.

Availability
1.2.0
9.2.0
Extends
Titanium.UI.View

# Overview

A popover is created using the Titanium.UI.iPad.createPopover method or <Popover> Alloy element.

Popovers are used to present information temporarily, but in a way that does not take over the entire screen in the way that a modal view does. The popover content is layered on top of the existing content in a special type of window. The popover remains visible until the user taps outside of the popover window or it is explicitly dismissed.

Do not add top-level view containers, such as a SplitWindow or TabGroup, to a popover. Adding top-level view containers may have unintended side effects. See the Titanium.UI.iPad.Popover.contentView property for more information.

# Examples

# Simple Popover with a Title and Right Button

In this example, we create a simple popover and position it near the button.

var win = Ti.UI.createWindow({backgroundColor: 'white'});

var button = Ti.UI.createButton({title: 'Open Popover!'});
button.addEventListener('click', function(e){
    popover.show({ view: button });
})
win.add(button);

var rightButton = Ti.UI.createButton({title: 'Robin'});
rightButton.addEventListener('click', function(e){
    alert("But green's the color of spring.");
});

var contentWindow = Ti.UI.createWindow({
    rightNavButton: rightButton,
    title: 'Kermit'
});
contentWindow.add(Ti.UI.createLabel({text: "It's not easy being green."}));

var popover = Ti.UI.iPad.createPopover({
    backgroundColor: 'green',
    contentView: Ti.UI.createNavigationWindow({
        width: 250,
        height: 100,
        window: contentWindow
    })
});

win.open();

# Alloy XML Markup

Previous example as an Alloy project.

app/views/index.xml:

<Alloy>
    <Window>
        <Button id="button" onClick="openPopover">Open Popover!</Button>
    </Window>
</Alloy>

app/controllers/index.js:

function openPopover() {
    var popover = Alloy.createController('popover').getView();
    popover.show({view:$.button});
};

$.index.open();

app/views/popover.xml:

<Alloy>
    <Popover backgroundColor='green'>
        <ContentView>
            <NavigationWindow height='100' width='250'>
                <Window title='Kermit'>
                    <RightNavButton onClick="showAlert" title="Robin" />
                    <Label>It's not easy being green.</Label>
                </Window>
            </NavigationWindow>
        </ContentView>
    </Popover>
</Alloy>

app/controllers/popover.js:

function showAlert(e) {
    alert('But green is the color of spring.');
};

// Prior to Alloy 1.1.0, the rightNavButton property was set in the controller.
// var button = Ti.UI.createButton({title: 'Robin'});
// button.addEventListener('click', showAlert);
// $.popover.rightNavButton = button;

# Properties

# arrowDirection

Availability
1.2.0
9.2.0
arrowDirection :Number

Indicates the arrow direction of the popover.

Use this property to indicate the popover arrows to use. You can bitwise-OR the constant values together.

Do not set this property to POPOVER_ARROW_DIRECTION_UNKNOWN.

This API can be assigned the following constants:

# backgroundColor CREATION ONLY

Availability
5.2.0
9.2.0
backgroundColor :String | Titanium.UI.Color

Sets the background color of the popover.

It is recommended to set this property to colorize the whole popover instead of only its content view.

Default: undefined (behaves as transparent)

# contentView

Availability
3.2.0
9.2.0
contentView :Titanium.UI.View

View to use for the popover content. Must be set before calling the show() method.

Set this property to any Titanium.UI.View object, including a Titanium.UI.Window or Titanium.UI.NavigationWindow object.

This property does not support the Titanium.UI.iOS.SplitWindow or Titanium.UI.TabGroup objects.

When this property is set to a valid object, the popover does not include the navigation controller unless it is set to a Titanium.UI.NavigationWindow object.

In an Alloy application, you can specify this property as a <ContentView> child element of the <Popover> element:

<Alloy>
    <Popover>
        <ContentView>
            <Window title="Popover">
                <Label>Popover!</Label>
            </Window>
        </ContentView>
    </Popover>
</Alloy>

# height DEPRECATED

Availability
1.2.0
9.2.0
height :Number | String

DEPRECATED SINCE 3.4.2

This property is deprecated. Set the height on the contentView property instead.

Height of the popover.

Defaults to: If undefined, defaults to either FILL or SIZE depending on the view. See "View Types and Default Layout Behavior" in Transitioning to the New UI Layout System.

Can be either a float value or a dimension string (for example, '50%' or '40dp'). Can also be one of the following special values:

  • SIZE. The view should size itself to fit its contents.
  • FILL. The view should size itself to fill its parent.
  • 'auto'. Represents the default sizing behavior for a given type of view. The use of 'auto' is deprecated, and should be replaced with the SIZE or FILL constants if it is necessary to set the view's behavior explicitly.

This is an input property for specifying the view's height dimension. To determine the view's size once rendered, use the rect or size properties.

This API can be assigned the following constants:

# passthroughViews

Availability
1.2.0
9.2.0
passthroughViews :Array<Titanium.UI.View>

Passthrough views to use when the popover is shown.

Specify view objects that the user can interact with while the popover is open. While interacting with these view, the popover will not be dismissed.

# width DEPRECATED

Availability
1.2.0
9.2.0
width :Number | String

DEPRECATED SINCE 3.4.2

This property is deprecated. Set the width on the contentView property instead.

Width of the popover.

Defaults to: If undefined, defaults to either FILL or SIZE depending on the view. See "View Types and Default Layout Behavior" in Transitioning to the New UI Layout System.

Can be either a float value or a dimension string (for example, '50%' or '40dp'). Can also be one of the following special values:

  • SIZE. The view should size itself to fit its contents.
  • FILL. The view should size itself to fill its parent.
  • 'auto'. Represents the default sizing behavior for a given type of view. The use of 'auto' is deprecated, and should be replaced with the SIZE or FILL constants if it is necessary to set the view's behavior explicitly.

This is an input property for specifying the view's width dimension. To determine the view's size once rendered, use the rect or size properties.

This API can be assigned the following constants:

# Methods

# hide

Availability
1.2.0
9.2.0
hide([options]) → void

Hides the popover.

Parameters

Name Type Description
options AnimatedOptions

Display properties to use when hiding the popover. Note that the default here is equivalent to passing in { animated: false }

Returns

Type
void

# show

Availability
1.2.0
9.2.0
show(options) → void

Displays the popover.

Parameters

Name Type Description
options ShowPopoverParams

Display properties to use when displaying the popover. Note that the default here is to be animated.

Returns

Type
void

# Events

# hide

Availability
1.2.0
9.2.0

Fired when the popover is hidden.

Contents