Class Callout


  • public final class Callout
    extends java.lang.Object
    Draws a callout on a MapView and manages its behavior. A callout displays an Android View that contains text and/or other content. It has a leader that points to the location the callout refers to. The body of the callout is a rectangular area with curved corners that contains the content view provided by the application. A thin border line is drawn around the entire callout.

    The application must get a Callout object from the MapView by calling MapView.getCallout(). This always returns the same object for a particular MapView. There are then four alternative ways to set the content and location and show the callout:

    There are options to animate the drawing of the callout and to recenter the map when the callout is drawn. These can be configured by creating a Callout.ShowOptions object and passing it to the callout using setShowOptions(ShowOptions).

    A number of style parameters can be configured by creating a Callout.Style object and passing it to the callout using setStyle(Style). These control how the callout looks, for example its size, color, and the size and position of the leader. There are two ways to set the parameters in the CalloutStyle, from Java code using setter methods or from an XML file. See Callout.Style for details.

    Since:
    100.0.0
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  Callout.ShowOptions
      Encapsulates a set of parameters that control how a callout is shown and dismissed.
      static class  Callout.Style
      Encapsulates a set of parameters that control how a callout looks.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void dismiss()
      Dismisses the callout, removing it from the screen.
      android.view.View getContent()
      Gets the content of the callout.
      GeoElement getGeoElement()
      Gets the GeoElement the callout relates to, if any.
      Point getLocation()
      Gets the location of the callout as a Point in map coordinates.
      Callout.ShowOptions getShowOptions()
      Gets the CalloutShowOptions object used by the callout.
      Callout.Style getStyle()
      Gets the CalloutStyle object used by the callout.
      Point getTapLocation()
      Gets the tap location associated with the callout if the callout is related to a GeoElement.
      boolean isPassTouchEventsToMapView()
      Returns whether or not touch events on the callout are passed up to the parent MapView.
      boolean isShowing()
      Returns whether or not the callout is currently shown.
      void refresh()
      Refreshes the content of the callout.
      void setContent​(android.view.View contentView)
      Sets the content of the callout.
      void setGeoElement​(GeoElement geoElement, Point tapLocation)
      Sets the location of the callout by specifying a GeoElement it relates to and an optional tap location.
      void setLocation​(Point location)
      Sets the location of the callout by specifying a Point in map coordinates.
      void setPassTouchEventsToMapView​(boolean passToMapView)
      Sets whether or not touch events on the callout are passed up to the parent MapView.
      void setShowOptions​(Callout.ShowOptions showOptions)
      Sets options for how the callout is shown.
      void setStyle​(Callout.Style style)
      Sets the style parameters used by the callout.
      void show()
      Shows the callout.
      void show​(android.view.View contentView, Point location)
      Sets the content and location of the callout and shows it.
      void show​(android.view.View contentView, GeoElement geoElement, Point tapLocation)
      Sets the content of the callout and shows it, with its location specified by a GeoElement it relates to and an optional tap location.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Method Detail

      • getContent

        public android.view.View getContent()
        Gets the content of the callout.
        Returns:
        the content View of the callout
        Since:
        100.0.0
        See Also:
        setContent(View), show(View, Point)
      • getLocation

        public Point getLocation()
        Gets the location of the callout as a Point in map coordinates. This is the Point the callout leader points to.
        Returns:
        a Point that specifies the location of the callout in map coordinates, or null if no location has been specified
        Since:
        100.0.0
        See Also:
        setLocation(Point), show(View, Point)
      • getShowOptions

        public Callout.ShowOptions getShowOptions()
        Gets the CalloutShowOptions object used by the callout.
        Returns:
        an object specifying how the callout will be shown
        Since:
        100.0.0
        See Also:
        setShowOptions(ShowOptions)
      • getStyle

        public Callout.Style getStyle()
        Gets the CalloutStyle object used by the callout.
        Returns:
        an object specifying style parameters used by the callout
        Since:
        100.0.0
        See Also:
        setStyle(Style)
      • getTapLocation

        public Point getTapLocation()
        Gets the tap location associated with the callout if the callout is related to a GeoElement.
        Returns:
        the tap location that was specified together with a GeoElement the callout relates to, or null if the callout is not related to a GeoElement or if no tap location was specified
        Since:
        100.0.0
        See Also:
        setGeoElement(GeoElement, Point), show(View, GeoElement, Point)
      • isPassTouchEventsToMapView

        public boolean isPassTouchEventsToMapView()
        Returns whether or not touch events on the callout are passed up to the parent MapView.
        Returns:
        true if touch events are passed to the parent MapView, false otherwise
        Since:
        100.0.0
        See Also:
        setPassTouchEventsToMapView(boolean)
      • isShowing

        public boolean isShowing()
        Returns whether or not the callout is currently shown.
        Returns:
        true if the callout is shown, false otherwise
        Since:
        100.0.0
      • setContent

        public void setContent​(android.view.View contentView)
        Sets the content of the callout.
        Parameters:
        contentView - the View to display in the callout
        Throws:
        java.lang.IllegalArgumentException - if contentView is null
        Since:
        100.0.0
      • setGeoElement

        public void setGeoElement​(GeoElement geoElement,
                                  Point tapLocation)
        Sets the location of the callout by specifying a GeoElement it relates to and an optional tap location. If a tap location is specified, the callout location will be the nearest point to the tap location that lies within or on the GeoElement's geometry. If no tap location is specified, the callout location will be the position of the GeoElement (for Point geometries) or the point on the GeoElement's geometry that is closest to the center of its bounding envelope.

        If the symbol associated with the GeoElement has a leader offset, that leader offset will be honored.

        Parameters:
        geoElement - the GeoElement the callout relates to
        tapLocation - a Point the user has tapped, or null if the callout is not associated with a tap
        Throws:
        java.lang.IllegalArgumentException - if geoElement is null
        Since:
        100.0.0
      • setLocation

        public void setLocation​(Point location)
        Sets the location of the callout by specifying a Point in map coordinates. This is the Point the callout leader points to.
        Parameters:
        location - the Point at which to display the callout
        Throws:
        java.lang.IllegalArgumentException - if location is null
        Since:
        100.0.0
      • setPassTouchEventsToMapView

        public void setPassTouchEventsToMapView​(boolean passToMapView)
        Sets whether or not touch events on the callout 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 - true to pass touch events to the parent MapView
        Since:
        100.0.0
      • setShowOptions

        public void setShowOptions​(Callout.ShowOptions showOptions)
        Sets options for how the callout is shown. For example if it appears immediately or with animation, and what happens if the location is not currently visible in the MapView.
        Parameters:
        showOptions - an object specifying how the callout will be shown
        Throws:
        java.lang.IllegalArgumentException - if showOptions is null
        Since:
        100.0.0
      • setStyle

        public void setStyle​(Callout.Style style)
        Sets the style parameters used by the callout. These control how the callout looks, for example its size, color, and the size and position of the leader.
        Parameters:
        style - an object specifying style parameters used by the callout
        Throws:
        java.lang.IllegalArgumentException - if style is null
        Since:
        100.0.0
      • show

        public void show​(android.view.View contentView,
                         Point location)
        Sets the content and location of the callout and shows it. The way it is shown is controlled by Callout.ShowOptions which can be configured using setShowOptions(ShowOptions).
        Parameters:
        contentView - the View to display in the callout; replaces any View that may have been set by setContent(View)
        location - the Point at which to display the callout; replaces any Point that may have been set by setLocation(Point)
        Throws:
        java.lang.IllegalArgumentException - if contentView or location is null
        Since:
        100.0.0
      • show

        public void show​(android.view.View contentView,
                         GeoElement geoElement,
                         Point tapLocation)
        Sets the content of the callout and shows it, with its location specified by a GeoElement it relates to and an optional tap location. If a tap location is specified, the callout location will be the nearest point to the tap location that lies within or on the GeoElement's geometry. If no tap location is specified, the callout location will be the position of the GeoElement (for Point geometries) or the point on the GeoElement's geometry that is closest to the center of its bounding envelope.

        If the symbol associated with the GeoElement has a leader offset, that leader offset will be honored.

        The way the callout is shown is controlled by Callout.ShowOptions which can be configured using setShowOptions(ShowOptions).

        Parameters:
        contentView - the View to display in the callout; replaces any View that may have been set by setContent(View)
        geoElement - the GeoElement the callout relates to; replaces any GeoElement that may have been set by setGeoElement(GeoElement, Point)
        tapLocation - a Point the user has tapped, or null if the callout is not associated with a tap; replaces any tap location that may have been set by setGeoElement(GeoElement, Point)
        Throws:
        java.lang.IllegalArgumentException - if contentView or geoElement is null
        Since:
        100.0.0
      • refresh

        public void refresh()
        Refreshes the content of the callout. The application should call this method if it changes any of the Callout.Style parameters after showing the callout.
        Since:
        100.0.0