Package com.esri.arcgisruntime.mapping.view

Class Callout

  • All Implemented Interfaces:
    Styleable, EventTarget, Skinnable
    public final class Callout
extends Control
    A Callout typically displays text and image content from a GeoElement, such as a Feature. A callout is displayed on the GeoView at a given map coordinate. The callout is displayed with a leader (arrow) that points to the given location.

    The callout can't be created directly, it must be retrieved from the view by calling GeoView.getCallout(). A GeoView has only one Callout. Call showCalloutAt(com.esri.arcgisruntime.geometry.Point) to display the Callout and dismiss() to hide it (this will clean up any internal resources, so prefer calling it over changing the visibility directly.)

    A callout with default view looks like this:

    typical looking callout

    The following screenshot shows a callout with intentionally exaggerated properties that you would never see in a real-world application. The image does, however, label the main properties of a callout, and the table describes how to access and modify them.

    callout with exaggerated visual properties

    Callout properties in screenshot labeled by number
    Label Properties
    1

    Title - Short description of callout's purpose. See titleProperty(), titleColorProperty().
    2

    Detail - Detail text for the callout, which might be location-specific, as in both screenshots above. See detailProperty(), detailColorProperty().
    3

    Image - Optional image. See imageProperty().

    Default View

    The default view is a rectangular area composed of 1, 2, and 3 (title, detail, and image). The default view is assigned if you do not provide a custom view.

    Custom View

    You can provide a custom view, which covers the same area as the default view. See customViewProperty().
    4

    Margin - Empty space surrounding the custom or default view. See marginProperty().
    5

    Border - borderWidthProperty(), borderColorProperty().
    6

    Leader length - How much the point of the leader sticks out from the callout rectangle. (Dotted lines in the labeled screenshot are for illustration only. They do not appear on the actual callout.) See leaderLengthProperty().
    7

    Leader width - The leader's width can occupy most of the open side of the callout rectangle, as in the labeled screenshot, or a smaller portion of it, as in the default screenshot. (Dotted lines in the labeled screenshot are for illustration only. They do not appear on the actual callout.) See leaderWidthProperty().
    8

    Corner radius - In the default screenshot, the corner radius is the default of 10 device-independent pixels (dp). In the labeled screenshot, the corner radius is set to 1 dp, which appears as a right angle. See cornerRadiusProperty().
    9

    Callout location - Location on the map to which the callout is pointing. See showCalloutAt(Point), showCalloutAt(GeoElement, Point), showCalloutAt(Point, Duration), showCalloutAt(GeoElement, Point, Duration), or showCalloutAt(Point, Point2D, Duration).

    Leader position - Side of the callout on which leader appears: TOP, BOTTOM, LEFT, RIGHT, ANY. See leaderPositionProperty().
    Background Color

    You can set the background color of the callout. See backgroundColorProperty().

    Styling

    Callout can be styled using CSS. See the individual properties for details.

    • Styles can be applied inline, as below: 
       geoView.getCallout().setStyle("border-width:20; border-color: red;");
    • Styles can be applied using a stylesheet, on the .callout class, as below: 
       scene.getStylesheets().add("myCallout.css");
 
       Content of stylesheet (myCallout.css):
 
 .callout {
   auto-adjust-width: true;
   background-color: red;
   border-color: black;
   border-width: 10;
   corner-radius: 16;
   detail-color: white;
   image-uri: "file:///C://JavaRuntimeTestData//icons//globe-16x16.png";
   leader-length: 24;
   leader-position: top;
   leader-width: 24;
   margin: 16;
   title-color: yellow;
 }
    Since:
    100.0.0

    • Method Detail

      • autoAdjustWidthProperty

        public BooleanProperty autoAdjustWidthProperty()
        Gives access to the auto-adjust-width of the default callout.

        If set to true, the callout's width will change dynamically, within the range of Region.minWidthProperty() and Region.maxWidthProperty().

        If set to false, the callout's width will be kept constant at Region.prefWidthProperty().

        This can be set in CSS with the auto-adjust-width property.

        Returns:
        the auto-adjust-width property
        Since:
        100.1.0

      • getAutoAdjustWidth

        public boolean getAutoAdjustWidth()
        Gets whether the width of the callout is auto-adjusted based on its content.
        Returns:
        true if the width of the callout is auto-adjusted based on its content
        Since:
        100.1.0

      • setAutoAdjustWidth

        public void setAutoAdjustWidth​(boolean autoAdjustWidth)
        Sets whether to auto-adjust the width of the callout based on its content.

        If set to true, the callout's width will change dynamically, within the range of Region.minWidthProperty() and Region.maxWidthProperty().

        If set to false, the callout's width will be kept constant at Region.prefWidthProperty().

        Parameters:
        autoAdjustWidth - true to auto-adjust the width of the callout based on its content
        Since:
        100.1.0

      • titleProperty

        public StringProperty titleProperty()
        Gives access to the title text of the default callout.

        The text can be styled via the .mapview .callout .title CSS class and supports all the properties of Label.

        Returns:
        the title text property
        Since:
        100.0.0

      • getTitle

        public String getTitle()
        Gets the title text of the default callout.
        Returns:
        the title of the default callout
        Since:
        100.0.0

      • setTitle

        public void setTitle​(String title)
        Sets the title text of the default callout. The default is 'Title'.
        Parameters:
        title - the new title
        Since:
        100.0.0

      • detailProperty

        public StringProperty detailProperty()
        Gives access to the detail text of the default callout.

        The text can be styled via the .mapview .callout .detail CSS class and supports all the properties of Label .

        Returns:
        the detail text property
        Since:
        100.0.0

      • getDetail

        public String getDetail()
        Gets the detail text of the default callout.
        Returns:
        the detail text of the default callout
        Since:
        100.0.0

      • setDetail

        public void setDetail​(String detail)
        Sets the detail text of the default callout. The default is 'Detail'.
        Parameters:
        detail - the new detail text of the default callout
        Since:
        100.0.0

      • imageProperty

        public ObjectProperty<Image> imageProperty()
        Gives access to the image displayed on the default callout.

        The image can be set in CSS using the image-uri property.

        Returns:
        the image property of the default callout
        Since:
        100.0.0

      • getImage

        public Image getImage()
        Gets the image displayed on the default callout.
        Returns:
        the image displayed on the default callout
        Since:
        100.0.0

      • setImage

        public void setImage​(Image image)
        Sets the image displayed on the default callout.
        Parameters:
        image - the new image to display on the default callout
        Since:
        100.0.0

      • backgroundColorProperty

        public ObjectProperty<Paint> backgroundColorProperty()
        Gives access to the background color of the callout.

        This can be set in CSS with the background property.

        Returns:
        the background color property
        Since:
        100.0.0

      • getBackgroundColor

        public Paint getBackgroundColor()
        Gets the background color.
        Returns:
        the background color
        Since:
        100.0.0

      • setBackgroundColor

        public void setBackgroundColor​(Paint backgroundColor)
        Sets the background color. By default this is Color.WHITE with an alpha of 0.9.
        Parameters:
        backgroundColor - the background color
        Throws:
        IllegalArgumentException - if backgroundColor is null
        Since:
        100.0.0

      • borderColorProperty

        public ObjectProperty<Color> borderColorProperty()
        Gives access to the border color of the callout.

        This can be set in CSS with the border property.

        Returns:
        the border color property
        Since:
        100.0.0

      • getBorderColor

        public Color getBorderColor()
        Gets the border color.
        Returns:
        the border color
        Since:
        100.0.0

      • setBorderColor

        public void setBorderColor​(Color borderColor)
        Sets the border color. By default this is Color.BLACK.
        Parameters:
        borderColor - the border color
        Throws:
        IllegalArgumentException - if borderColor is null
        Since:
        100.0.0

      • titleColorProperty

        public ObjectProperty<Paint> titleColorProperty()
        Gives access to the title color property of the default callout.

        This can be set in CSS with the title-color property

        Returns:
        the title color property
        Since:
        100.0.0

      • getTitleColor

        public Paint getTitleColor()
        Gets the title color. Note that this only applies to the default callout content: it won't affect any custom content.
        Returns:
        the title color
        Since:
        100.0.0

      • setTitleColor

        public void setTitleColor​(Paint titleColor)
        Sets the title color. Note that this only applies to the default callout content: it won't affect any custom content. By default this is Color.BLACK.
        Parameters:
        titleColor - the new title color
        Since:
        100.0.0

      • detailColorProperty

        public ObjectProperty<Paint> detailColorProperty()
        Gives access to the detail text color of the default callout.

        This can be set in CSS with the detail-color property.

        Returns:
        the title color property
        Since:
        100.0.0

      • getDetailColor

        public Paint getDetailColor()
        Gets the detail text color. Note that this only applies to the default callout content: it won't affect any custom content.
        Returns:
        the detail text color
        Since:
        100.0.0

      • setDetailColor

        public void setDetailColor​(Paint detailColor)
        Sets the detail text color. Note that this only applies to the default callout content: it won't affect any custom content. By default this is Color.BLACK.
        Parameters:
        detailColor - the new detail color
        Since:
        100.0.0

      • borderWidthProperty

        public IntegerProperty borderWidthProperty()
        Gives access to the callout's border width.

        This can be set in CSS with the border-size property.

        Returns:
        the border width property
        Since:
        100.0.0

      • getBorderWidth

        public int getBorderWidth()
        Gets the border width.
        Returns:
        the border width in device-independent pixels (dp)
        Since:
        100.0.0

      • setBorderWidth

        public void setBorderWidth​(int borderWidth)
        Sets the border width. By default this is 0 pixels. In other words the default is to have no visible border.
        Parameters:
        borderWidth - the border width in device-independent pixels (dp)
        Since:
        100.0.0

      • marginProperty

        public IntegerProperty marginProperty()
        Gives access to the margin between the callout's border and its content.

        This can be set in CSS with the margin property.

        Returns:
        the margin size property
        Since:
        100.0.0

      • getMargin

        public int getMargin()
        Gets the size of the margin around the callout's content. This size applies to all four sides.
        Returns:
        the margin currently set
        Since:
        100.0.0

      • setMargin

        public void setMargin​(int margin)
        Sets the size of the margin around the callout's content. This size will be applied to all four sides of the content. This defaults to five device-independent pixels (dp).
        Parameters:
        margin - the new margin
        Since:
        100.0.0

      • cornerRadiusProperty

        public IntegerProperty cornerRadiusProperty()
        Gives access to the corner radius of the callout.

        This can be set in CSS with the corner-radius property.

        Returns:
        the corner radius property
        Since:
        100.0.0

      • getCornerRadius

        public int getCornerRadius()
        Gets the corner curve radius.
        Returns:
        the corner curve radius in device-independent pixels (dp)
        Since:
        100.0.0

      • setCornerRadius

        public void setCornerRadius​(int cornerRadius)
        Sets the corner curve radius. By default this is 10 device-independent pixels (dp). A value of zero will give square corners.
        Parameters:
        cornerRadius - the corner curve radius in pixels
        Since:
        100.0.0

      • leaderLengthProperty

        public IntegerProperty leaderLengthProperty()
        Gives access to the leader length.

        This can be set in CSS with the leader-length property.

        Returns:
        the leader length property
        Since:
        100.0.0

      • getLeaderLength

        public int getLeaderLength()
        Gets the leader length.
        Returns:
        the leader length in device-independent pixels (dp)
        Since:
        100.0.0

      • setLeaderLength

        public void setLeaderLength​(int leaderLength)
        Sets the leader length. By default this is 15 device-independent pixels (dp).
        Parameters:
        leaderLength - the leader length in device-independent pixels (dp)
        Since:
        100.0.0

      • leaderWidthProperty

        public IntegerProperty leaderWidthProperty()
        Gives access to the leader width.

        This can be set in CSS with the leader-width property.

        Returns:
        the leader width property
        Since:
        100.0.0

      • getLeaderWidth

        public int getLeaderWidth()
        Gets the leader width where it joins the body of the callout.
        Returns:
        the leader width in device-independent pixels (dp)
        Since:
        100.0.0

      • setLeaderWidth

        public void setLeaderWidth​(int leaderWidth)
        Sets the leader width where it joins the body of the callout. By default this is 30 device-independent pixels (dp).
        Parameters:
        leaderWidth - the leader width in pixels
        Since:
        100.0.0

      • leaderPositionProperty

        public ObservableValue<Callout.LeaderPosition> leaderPositionProperty()
        Gives access to the leader position property.

        This can be set in CSS with the leader-position property.

        Returns:
        the leader position property
        Since:
        100.0.0

      • getLeaderPosition

        public Callout.LeaderPosition getLeaderPosition()
        Gets the position of the leader relative to the body of the callout.
        Returns:
        the position of the leader
        Since:
        100.0.0

      • setLeaderPosition

        public void setLeaderPosition​(Callout.LeaderPosition leaderPosition)
        Sets the position of the leader relative to the body of the callout. By default this is Callout.LeaderPosition.LEFT .
        Parameters:
        leaderPosition - the position of the leader
        Since:
        100.0.0

      • customViewProperty

        public ObjectProperty<Region> customViewProperty()
        Gives access to the custom view property.
        Returns:
        the custom view property
        Since:
        100.0.0

      • getCustomView

        public Region getCustomView()
        Gets the custom content of the callout.
        Returns:
        the content content of the callout. If none was a set, a default is returned.
        Since:
        100.0.0

      • setCustomView

        public void setCustomView​(Region customView)
        Sets the custom content of the callout. This is null by default which will result in the default content being used.
        Parameters:
        customView - the view to display in the callout
        Since:
        100.0.0

      • locationProperty

        public ReadOnlyObjectProperty<Point> locationProperty()
        Gives access to the read only location property.
        Returns:
        the location property
        Since:
        100.0.0

      • getMapView

        public MapView getMapView()
        Returns the map view of this callout.
        Returns:
        the map view
        Since:
        100.0.0

      • getGeoView

        public GeoView getGeoView()
        Returns the geoview this callout belongs to.
        Returns:
        the geoview this callout belongs to
        Since:
        100.1.0

      • 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

      • getLocationOnScreen

        public Point2D getLocationOnScreen()
        Gets the local location. This is the top-left point of the bounds in device-independent pixels (dp).
        Returns:
        the local location in device-independent pixels (dp), null if the location is not visible (for example, hidden by a mountain)
        Since:
        100.0.0

      • getClassCssMetaData

        public static List<CssMetaData<? extends Styleable,​?>> getClassCssMetaData()
        Gets the class CSS meta data.
        Returns:
        the class CSS meta data

      • showCalloutAt

        public void showCalloutAt​(Point location)
        Shows the callout at the given map location with no offset.
        Parameters:
        location - the Point at which to display the callout. This is in the map's coordinates.
        Throws:
        IllegalArgumentException - if location is null or if the location's spatial reference is null
        Since:
        100.0.0

      • showCalloutAt

        public void showCalloutAt​(Point location,
                          Duration animateDuration)
        Shows the callout at the given map location with no offset.
        Parameters:
        location - the Point at which to display the callout. This is in the map's coordinates
        animateDuration - duration of animation. If the Node.opacityProperty() is bounded, then the animation is disabled
        Throws:
        IllegalArgumentException - if any input is null or if the location's spatial reference is null
        RuntimeException - if opacity property is bounded
        Since:
        100.0.0

      • showCalloutAt

        public void showCalloutAt​(GeoElement geoElement,
                          Point interactionLocation)
        Shows the callout at a computed location based on a geo element.
        Parameters:
        geoElement - geo element to calculate the callout location
        interactionLocation - if specified, the computed location will be the geometry's nearest point of this target location; can be null in which case the computed location will be based on geometry alone
        Throws:
        IllegalArgumentException - if geoElement is null or if the geoElement geometry's spatial reference is null
        Since:
        100.0.0

      • showCalloutAt

        public void showCalloutAt​(GeoElement geoElement,
                          Point interactionLocation,
                          Duration animateDuration)
        Shows the callout at a computed location based on a geo element.
        Parameters:
        geoElement - geo element to calculate the callout location
        interactionLocation - if specified, the computed location will be the geometry's nearest point of this target location; can be null in which case the computed location will be based on geometry alone
        animateDuration - duration of animation. If the Node.opacityProperty() is bounded, then the animation is disabled
        Throws:
        IllegalArgumentException - if geoElement is null or if the geoElement geometry's spatial reference is null
        RuntimeException - if opacity property is bounded
        Since:
        100.0.0

      • showCalloutAt

        public void showCalloutAt​(Point locationOnMap,
                          Point2D screenOffset,
                          Duration animateDuration)
        Shows the callout at the given map location with the given offset in device-independent pixels (dp).
        Parameters:
        locationOnMap - the Point at which to display the callout. This is in the map's coordinates.
        screenOffset - an offset in device-independent pixels (dp) to apply to the callout
        animateDuration - duration of animation. If the Node.opacityProperty() is bounded, then the animation is disabled
        Throws:
        IllegalArgumentException - if any input is null or if the spatial reference of locationOnMap is null
        RuntimeException - if opacity property is bounded
        Since:
        100.0.0

      • dismiss

        public void dismiss()
        Hides the callout.

        Call this method for the callout to cleanup any internal resources.

        Since:
        100.0.0

      • update

        public void update()
        Updates the callout.
        Since:
        100.0.0