public class

Callout

extends Object
java.lang.Object
   ↳ com.esri.android.map.Callout

Class Overview

The Callout class draws a callout window on a MapView and manages its behavior. You obtain a Callout object for a MapView by calling getCallout().

By default, the callout window is empty and it is likely that you will want to work with the setContent(View) method to populate the callout window with some Android View (for example, TextView).

By default the size of the callout window will stretch to accommodate the content that is to appear inside it, potentially becoming almost as large as the entire MapView. The maximum width and height are customizable using setMaxWidth(int), setMaxHeight(int), setMaxWidthDp(int) and setMaxHeightDp(int).

When the anchor position is set to ANCHOR_POSITION_FLOATING, the callout window will automatically adjust itself to try to remain within the MapView when panning. Use the setAnchor(int) method and pass in one of the ANCHOR_POSITION static fields to set the position of the anchor relatively to the callout window.

When the callout window is displayed, it is anchored to a location. This location is defined by the developer by calling the setCoordinates(Point) method, where a point is passed in. This point must have coordinates supplied in the MapView's spatial coordinate system. See the MapView for convenience methods to convert screen pixels to map coordinates, or to obtain the spatial coordinate system used by the MapView, as needed.

If the callout is visible, it will be temporarily hidden during any animated map navigation, for example if:

  • Any animated map navigation methods are called, for example the zoomin() or setExtent(Geometry) methods, among others.
  • The user double-taps the map to zoom in, rotates the map using a pinch gesture, or performs an animated pan using a fling gesture (the callout remains visible during single-finger pan gestures).

The callout's look and feel can be customized by creating an XML file in the res/xml folder of your application. The XML must contain a <calloutViewStyle> element with a number of optional attributes as follows:

Attribute Description Default Value
anchor Position style of the anchor of the callout window. An integer in the range 0-8 (see ANCHOR_POSITION constants below). 5
ANCHOR_POSITION_LOWER_MIDDLE
backgroundAlpha Alpha (opacity) value in the range 0(transparent) to 255(opaque). 255
backgroundColor Background color of the callout window. May be a color value or a reference to a color resource, for example "#FF0000" or "@android:color/white". @android:color/white
cornerCurve Radius of curvature of corners of the callout window in pixels. Provided for backward compatibility. You are recommended to use cornerCurveDp instead.
cornerCurveDp Radius of curvature of corners of the callout window in density-independent pixels. 5
frameColor Color of frame of the callout window. May be a color value or a reference to a color resource, for example "#FF0000" or "@android:color/black". @android:color/black
maxHeight Maximum height of the callout window in pixels. Provided for backward compatibility. You are recommended to use maxHeightDp instead. Full height of the MapView
maxHeightDp Maximum height of the callout window in density-independent pixels. Full height of the MapView
maxWidth Maximum width of the callout window in pixels. Provided for backward compatibility. You are recommended to use maxWidthDp instead. Full width of the MapView
maxWidthDp Maximum width of the callout window in density-independent pixels. Full width of the MapView
titleTextColor Color of title text - deprecated at 10.2.4 because callouts no longer have title text.
titleTextSize Size of title text - deprecated at 10.2.4 because callouts no longer have title text.
titleTextStyle Style of title text - deprecated at 10.2.4 because callouts no longer have title text.
titleTextTypeface Typeface of title text - deprecated at 10.2.4 because callouts no longer have title text.

For example:

 
  <?xml version="1.0" encoding="utf-8"?>
  <resources>
      <calloutViewStyle
          anchor="5"
          backgroundAlpha="255"
          backgroundColor="#ffffff"
          cornerCurveDp="20"
          frameColor="#000000"
          maxHeightDp="300"
          maxWidthDp="500" />
  </resources>
 
 
Once this file has been created, you can either use setStyle(int) and pass it the reference of the file (R.xml.MyXmlFileName) or declare an attribute "calloutStyle" for the MapView in your layout. e.g.:
 
 <com.esri.android.map.MapView
     xmlns:android="http://schemas.android.com/apk/res/android"
     android:id="@+id/mapview" 
     android:layout_height="fill_parent" 
     android:layout_width="fill_parent" 
     calloutStyle="@xml/style3" />
 
 

Summary

Constants
int ANCHOR_POSITION_FLOATING Positions the anchor in the best position that will keep the callout window as much as possible within the MapView when panning or zooming.
int ANCHOR_POSITION_LEFT_MIDDLE Positions the anchor at the left center of the callout window.
int ANCHOR_POSITION_LOWER_LEFT_CORNER Positions the anchor at the bottom left corner of the callout window.
int ANCHOR_POSITION_LOWER_MIDDLE Positions the anchor at the bottom center of the callout window.
int ANCHOR_POSITION_LOWER_RIGHT_CORNER Positions the anchor at the bottom right corner of the callout window.
int ANCHOR_POSITION_RIGHT_MIDDLE Positions the anchor at the right center of the callout window.
int ANCHOR_POSITION_UPPER_LEFT_CORNER Positions the anchor at the top left corner of the callout window.
int ANCHOR_POSITION_UPPER_MIDDLE Positions the anchor at the top center of the callout window.
int ANCHOR_POSITION_UPPER_RIGHT_CORNER Positions the anchor at the top right corner of the callout window.
Public Methods
void animatedHide()
Hides the callout window with animation.
void animatedShow(Point coordinates, View newContent)
Displays the callout window with animation at the given coordinates with the provided content.
Point getCoordinates()
Returns the map coordinates of the anchor point of the callout window.
int getMaxHeight()
Returns the maximum height of the callout window in pixels.
int getMaxHeightDp()
Returns the maximum height of the callout window in density-independent pixels.
int getMaxWidth()
Returns the maximum width of the callout window in pixels.
int getMaxWidthDp()
Returns the maximum width of the callout window in density-independent pixels.
int[] getOffset()
Returns an array of 2 integer values containing horizontal and vertical offsets in pixels of the anchor point relative to the coordinates set for the anchor.
int[] getOffsetDp()
Returns an array of 2 integer values containing horizontal and vertical offsets in density-independent pixels of the anchor point relative to the coordinates set for the anchor.
CalloutStyle getStyle()
Returns the style parameters used by the callout window.
void hide()
Hides the callout window.
boolean isPassTouchEventsToMapView()
Returns whether or not touch events on the callout window are passed up to the parent MapView.
boolean isShowing()
Returns whether or not the callout is currently displayed.
void move(Point newCoordinates)
Moves the callout window to the provided coordinates.
void refresh()
Refreshes the content of the callout window.
void setContent(View v)
Sets the content of the callout window.
void setCoordinates(Point coordinates)
Sets the anchor of the callout window to the given point in the map spatial reference.
void setMaxHeight(int maxHeight)
Sets the maximum height of the callout window in pixels.
void setMaxHeightDp(int maxHeight)
Sets the maximum height of the callout window in density-independent pixels.
void setMaxWidth(int maxWidth)
Sets the maximum width of the callout window in pixels.
void setMaxWidthDp(int maxWidth)
Sets the maximum width of the callout window in density-independent pixels.
void setOffset(int x, int y)
Sets the horizontal and vertical offsets in pixels of the anchor point relative to the coordinates set for the anchor.
void setOffsetDp(int x, int y)
Sets the horizontal and vertical offsets in density-independent pixels of the anchor point relative to the coordinates set for the anchor.
void setPassTouchEventsToMapView(boolean passToMapView)
Sets whether or not touch events on the callout window are passed up to the parent MapView.
void setStyle(int xmlId)
Sets the style of the callout window from an XML resource id.
void setStyle(CalloutStyle style)
Sets the style of the callout window.
void show(Point coordinates, View newContent)
Displays the callout window at the given point with the provided content.
void show()
Displays the callout window.
void show(Point coordinates)
Displays the callout window at the given point in the spatial reference of the MapView.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final int ANCHOR_POSITION_FLOATING

Positions the anchor in the best position that will keep the callout window as much as possible within the MapView when panning or zooming.

Constant Value: 8 (0x00000008)

public static final int ANCHOR_POSITION_LEFT_MIDDLE

Positions the anchor at the left center of the callout window.

Constant Value: 7 (0x00000007)

public static final int ANCHOR_POSITION_LOWER_LEFT_CORNER

Positions the anchor at the bottom left corner of the callout window.

Constant Value: 6 (0x00000006)

public static final int ANCHOR_POSITION_LOWER_MIDDLE

Positions the anchor at the bottom center of the callout window.

Constant Value: 5 (0x00000005)

public static final int ANCHOR_POSITION_LOWER_RIGHT_CORNER

Positions the anchor at the bottom right corner of the callout window.

Constant Value: 4 (0x00000004)

public static final int ANCHOR_POSITION_RIGHT_MIDDLE

Positions the anchor at the right center of the callout window.

Constant Value: 3 (0x00000003)

public static final int ANCHOR_POSITION_UPPER_LEFT_CORNER

Positions the anchor at the top left corner of the callout window.

Constant Value: 0 (0x00000000)

public static final int ANCHOR_POSITION_UPPER_MIDDLE

Positions the anchor at the top center of the callout window.

Constant Value: 1 (0x00000001)

public static final int ANCHOR_POSITION_UPPER_RIGHT_CORNER

Positions the anchor at the top right corner of the callout window.

Constant Value: 2 (0x00000002)

Public Methods

public void animatedHide ()

Hides the callout window with animation.

public void animatedShow (Point coordinates, View newContent)

Displays the callout window with animation at the given coordinates with the provided content.

Parameters
coordinates Point: the coordinates of the anchor point of the callout window
newContent View: the view to display in the callout window

public Point getCoordinates ()

Returns the map coordinates of the anchor point of the callout window.

Returns
Point the coordinates of the anchor point of the callout window

public int getMaxHeight ()

Returns the maximum height of the callout window in pixels.

Returns
int the maximum height of the callout window in pixels, or 0 if none has been set

See also:

public int getMaxHeightDp ()

Returns the maximum height of the callout window in density-independent pixels.

Returns
int the maximum height of the callout window in density-independent pixels, or 0 if none has been set

See also:

public int getMaxWidth ()

Returns the maximum width of the callout window in pixels.

Returns
int the maximum width of the callout window in pixels, or 0 if none has been set

See also:

public int getMaxWidthDp ()

Returns the maximum width of the callout window in density-independent pixels.

Returns
int the maximum width of the callout window in density-independent pixels, or 0 if none has been set

See also:

public int[] getOffset ()

Returns an array of 2 integer values containing horizontal and vertical offsets in pixels of the anchor point relative to the coordinates set for the anchor.

Returns
int[] an array of 2 integer values containing offsets in pixels. Element 0 is the horizontal offset, element 1 the vertical offset.

See also:

public int[] getOffsetDp ()

Returns an array of 2 integer values containing horizontal and vertical offsets in density-independent pixels of the anchor point relative to the coordinates set for the anchor.

Returns
int[] an array of 2 integer values containing offsets in density-independent pixels. Element 0 is the horizontal offset, element 1 the vertical offset.

See also:

public CalloutStyle getStyle ()

Returns the style parameters used by the callout window.

Returns
CalloutStyle the style parameters used by the callout window

public void hide ()

Hides the callout window.

public boolean isPassTouchEventsToMapView ()

Returns whether or not touch events on the callout window are passed up to the parent MapView.

Returns
boolean true if touch events are passed to the parent MapView, false otherwise

public boolean isShowing ()

Returns whether or not the callout is currently displayed.

Returns
boolean true if the callout is displayed, false otherwise

public void move (Point newCoordinates)

Moves the callout window to the provided coordinates.

Parameters
newCoordinates Point: the new coordinates of the anchor point of the callout window

public void refresh ()

Refreshes the content of the callout window. Call this method if you set callout parameters after showing the callout.

public void setContent (View v)

Sets the content of the callout window.

Parameters
v View: the view to display in the callout window

public void setCoordinates (Point coordinates)

Sets the anchor of the callout window to the given point in the map spatial reference.

Parameters
coordinates Point: the coordinates of the anchor point of the callout window

public void setMaxHeight (int maxHeight)

Sets the maximum height of the callout window in pixels. By default it will stretch to accommodate the content that is to appear inside it, limited only by the height of the MapView. Note that the maximum callout height will be that set by setStyle(int), setStyle(CalloutStyle), setMaxHeight(int) or setMaxHeightDp(int), whichever is called last.

Parameters
maxHeight int: the maximum height of the callout window in pixels

public void setMaxHeightDp (int maxHeight)

Sets the maximum height of the callout window in density-independent pixels. By default it will stretch to accommodate the content that is to appear inside it, limited only by the height of the MapView. Note that the maximum callout height will be that set by setStyle(int), setStyle(CalloutStyle), setMaxHeight(int) or setMaxHeightDp(int), whichever is called last.

Parameters
maxHeight int: the maximum height of the callout window in density-independent pixels

See also:

public void setMaxWidth (int maxWidth)

Sets the maximum width of the callout window in pixels. By default it will stretch to accommodate the content that is to appear inside it, limited only by the width of the MapView. Note that the maximum callout width will be that set by setStyle(int), setStyle(CalloutStyle), setMaxWidth(int) or setMaxWidthDp(int), whichever is called last.

Parameters
maxWidth int: the maximum width of the callout window in pixels

See also:

public void setMaxWidthDp (int maxWidth)

Sets the maximum width of the callout window in density-independent pixels. By default it will stretch to accommodate the content that is to appear inside it, limited only by the width of the MapView. Note that the maximum callout width will be that set by setStyle(int), setStyle(CalloutStyle), setMaxWidth(int) or setMaxWidthDp(int), whichever is called last.

Parameters
maxWidth int: the maximum width of the callout window in density-independent pixels

See also:

public void setOffset (int x, int y)

Sets the horizontal and vertical offsets in pixels of the anchor point relative to the coordinates set for the anchor.

Parameters
x int: the horizontal offset in pixels
y int: the vertical offset in pixels

public void setOffsetDp (int x, int y)

Sets the horizontal and vertical offsets in density-independent pixels of the anchor point relative to the coordinates set for the anchor.

Parameters
x int: the horizontal offset in density-independent pixels
y int: the vertical offset in density-independent pixels

public void setPassTouchEventsToMapView (boolean passToMapView)

Sets whether or not touch events on the callout window are passed up to the parent MapView. The default value is true. Note that child Views of the callout may consume touch events upon them, for example clicks on a Button, in which case these touch events may not be passed to the callout or, in turn, to the MapView, regardless of this setting.

Parameters
passToMapView boolean: true to pass touch events to the parent MapView

public void setStyle (int xmlId)

Sets the style of the callout window from an XML resource id.

Parameters
xmlId int: the Android ID of the XML style for the callout window

public void setStyle (CalloutStyle style)

Sets the style of the callout window.

Parameters
style CalloutStyle: the style parameters used by the callout window

public void show (Point coordinates, View newContent)

Displays the callout window at the given point with the provided content.

Parameters
coordinates Point: the coordinates of the anchor point of the callout window
newContent View: the view to display in the callout window

public void show ()

Displays the callout window.

public void show (Point coordinates)

Displays the callout window at the given point in the spatial reference of the MapView.

Parameters
coordinates Point: the coordinates of the anchor point of the callout window