צורות

‫Google Maps API ל-Android מציע כמה דרכים פשוטות להוסיף צורות למפות כדי להתאים אותן אישית לאפליקציה.

• Polyline הוא סדרה של קטעי קו מחוברים שיכולים ליצור כל צורה שרוצים, ואפשר להשתמש בהם כדי לסמן נתיבים ומסלולים במפה.
• Polygon היא צורה סגורה שאפשר להשתמש בה כדי לסמן אזורים במפה.
• Circle הוא היטל מדויק מבחינה גיאוגרפית של מעגל על פני כדור הארץ, שמשורטט במפה.

אפשר להתאים אישית את המראה של כל הצורות האלה על ידי שינוי של כמה מאפיינים.

דוגמאות קוד

המדריך להוספת פוליגונים וקווים פוליגוניים לייצוג אזורים ומסלולים כולל את כל הקוד לאפליקציית Android פשוטה.

בנוסף, מאגר הנתונים ApiDemos ב-GitHub כולל דוגמאות שממחישות את השימוש בצורות ובתכונות שלהן:

• ‫CircleDemoActivity‏ (Java / Kotlin): מעגל
• ‫PolygonDemoActivity‏ (Java / Kotlin): פוליגון
• ‫PolylineDemoActivity‏ (Java / Kotlin): קו פוליגוני

קווים פוליגוניים

הכיתה Polyline מגדירה קבוצה של מקטעי קווים מחוברים במפה. אובייקט Polyline מורכב מקבוצה של מיקומי LatLng, ויוצר סדרה של קטעי קו שמחברים בין המיקומים האלה ברצף מסודר.

בסרטון הזה נציג רעיונות שיעזרו למשתמשים להגיע ליעד שלהם, באמצעות קווים פוליגוניים לשרטוט מסלול במפה.

כדי ליצור קו פוליגוני, קודם יוצרים אובייקט PolylineOptions ומוסיפים לו נקודות. נקודות מייצגות נקודה על פני כדור הארץ, והן מיוצגות כאובייקט LatLng. קטעי הקו משורטטים בין הנקודות לפי הסדר שבו מוסיפים אותן לאובייקט PolylineOptions.

כדי להוסיף נקודות לאובייקט PolylineOptions, צריך להפעיל את PolylineOptions.add(). שימו לב שה-method הזו מקבלת מספר משתנה של פרמטרים, כך שאפשר להוסיף כמה נקודות בבת אחת (אפשר גם להפעיל את PolylineOptions.addAll(Iterable<LatLng>) אם הנקודות כבר נמצאות ברשימה).

לאחר מכן אפשר להוסיף את הקו הפוליגוני למפה באמצעות קריאה ל-GoogleMap.addPolyline(PolylineOptions). ה-method מחזירה אובייקט Polyline שבאמצעותו אפשר לשנות את הקו הפוליגוני בשלב מאוחר יותר.

בקטע הקוד הבא אפשר לראות איך מוסיפים מלבן למפה:

// Instantiates a new Polyline object and adds points to define a rectangle
val polylineOptions = PolylineOptions()
    .add(LatLng(37.35, -122.0))
    .add(LatLng(37.45, -122.0)) // North of the previous point, but at the same longitude
    .add(LatLng(37.45, -122.2)) // Same latitude, and 30km to the west
    .add(LatLng(37.35, -122.2)) // Same longitude, and 16km to the south
    .add(LatLng(37.35, -122.0)) // Closes the polyline.

// Get back the mutable Polyline
val polyline = map.addPolyline(polylineOptions)

      

// Instantiates a new Polyline object and adds points to define a rectangle
PolylineOptions polylineOptions =
        new PolylineOptions()
                .add(new LatLng(37.35, -122.0))
                .add(
                        new LatLng(
                                37.45,
                                -122.0)) // North of the previous point, but at the same
                // longitude
                .add(new LatLng(37.45, -122.2)) // Same latitude, and 30km to the west
                .add(new LatLng(37.35, -122.2)) // Same longitude, and 16km to the south
                .add(new LatLng(37.35, -122.0)); // Closes the polyline.

// Get back the mutable Polyline
Polyline polyline = map.addPolyline(polylineOptions);

      

המלבן מופיע במפה כמו שמוצג כאן:

כדי לשנות את הצורה של הקו הפוליגוני אחרי שהוא נוסף, אפשר להפעיל את Polyline.setPoints() ולספק רשימה חדשה של נקודות לקו הפוליגוני.

אפשר להתאים אישית את המראה של הקו הפוליגוני לפני שמוסיפים אותו למפה וגם אחרי שמוסיפים אותו למפה. למידע נוסף, עיינו בקטע התאמה אישית של המראה שבהמשך.

התאמה אישית של קו פוליגוני

יש כמה דרכים להתאים אישית את המראה של קווים פוליגוניים:

• קווים פוליגוניים בכמה צבעים מגדירים מקטעים של קווים פוליגוניים בצבעים שונים.
• קווים פוליגוניים עם מעבר צבעים צובעים קו פוליגוני באמצעות מעבר בין שני צבעים.
• קווים פוליגוניים עם חותמות מעצבים קו פוליגוני באמצעות מפות סיביות חוזרות.

כדי להשתמש בהתאמות אישיות של קווים פוליגוניים, צריך להשתמש בגרסה 18.1.0 ואילך של ה-SDK של מפות ל-Android ולהשתמש במנוע הרינדור העדכני ביותר של ה-SDK של מפות ל-Android.

יצירת קו פוליגוני בכמה צבעים

כדי לצבוע קטעים נפרדים של קו פוליגוני, אפשר להשתמש במקטעים. לשם כך, יוצרים אובייקטים מסוג StyleSpan ומוסיפים אותם אל PolylineOptions באמצעות השיטות addSpan() או addSpans(). כברירת מחדל, כל פריט במערך יגדיר את הצבע של קטע הקו התואם. בדוגמה הבאה מוגדרים צבעי מקטעים כדי ליצור קו פוליגוני עם מקטעים אדומים וירוקים:

val line = map.addPolyline(
    PolylineOptions()
        .add(LatLng(47.6677146, -122.3470447), LatLng(47.6442757, -122.2814693))
        .addSpan(StyleSpan(Color.RED))
        .addSpan(StyleSpan(Color.GREEN)),
)

      

Polyline line =
        map.addPolyline(
                new PolylineOptions()
                        .add(
                                new LatLng(47.6677146, -122.3470447),
                                new LatLng(47.6442757, -122.2814693))
                        .addSpan(new StyleSpan(Color.RED))
                        .addSpan(new StyleSpan(Color.GREEN)));

      

יצירת קו פוליגוני עם הדרגתיות

כדי להגדיר מעבר צבעים, מציינים שני מספרים שלמים של 32 ביט בפורמט אלפא-אדום-ירוק-כחול (ARGB) שמייצגים את צבעי ההתחלה והסיום של הקו. מגדירים את המאפיין הזה באובייקט האפשרויות של הצורה באמצעות קריאה ל-PolylineOptions.addSpan(). בדוגמה הבאה מוצגת יצירה של קו פוליגוני עם מעבר הדרגתי בין אדום לצהוב, מגן החיות וודלנד פארק (Woodland Park Zoo) ועד קירקלנד, וושינגטון.

val line = map.addPolyline(
    PolylineOptions()
        .add(LatLng(47.6677146, -122.3470447), LatLng(47.6442757, -122.2814693))
        .addSpan(
            StyleSpan(
                StrokeStyle.gradientBuilder(
                    Color.RED,
                    Color.YELLOW,
                ).build(),
            ),
        ),
)

      

Polyline line =
        map.addPolyline(
                new PolylineOptions()
                        .add(
                                new LatLng(47.6677146, -122.3470447),
                                new LatLng(47.6442757, -122.2814693))
                        .addSpan(
                                new StyleSpan(
                                        StrokeStyle.gradientBuilder(Color.RED, Color.YELLOW)
                                                .build())));

      

יצירת קו פוליגוני מוטבע

אתם יכולים להגדיר את המראה של קו פוליגוני למרקם של מפת סיביות (bitmap) שחוזר על עצמו. כדי לעשות את זה, יוצרים StampStyle של TextureStyle, ואז מגדירים את המאפיין הזה באובייקט האפשרויות של הצורה על ידי קריאה ל-PolylineOptions.addSpan(), כמו שמוצג כאן:

val stampStyle =
    TextureStyle.newBuilder(BitmapDescriptorFactory.fromResource(R.drawable.walking_dot)).build()
val span = StyleSpan(StrokeStyle.colorBuilder(Color.RED).stamp(stampStyle).build())
map.addPolyline(
    PolylineOptions()
        .add(LatLng(47.6677146, -122.3470447), LatLng(47.6442757, -122.2814693))
        .addSpan(span),
)

      

StampStyle stampStyle =
        TextureStyle.newBuilder(
                        BitmapDescriptorFactory.fromResource(R.drawable.walking_dot))
                .build();
StyleSpan span =
        new StyleSpan(StrokeStyle.colorBuilder(Color.RED).stamp(stampStyle).build());
map.addPolyline(
        new PolylineOptions()
                .add(
                        new LatLng(47.6677146, -122.3470447),
                        new LatLng(47.6442757, -122.2814693))
                .addSpan(span));

      

אירועים של קו פוליגוני

כברירת מחדל, אי אפשר ללחוץ על קווים פוליגוניים. כדי להפעיל ולהשבית את האפשרות ללחוץ על המודעה, מפעילים את Polyline.setClickable(boolean).

משתמשים ב-OnPolylineClickListener כדי להאזין לאירועים מסוג קליק בקו פוליגוני שניתן ללחוץ עליו. כדי להגדיר את המאזין הזה במפה, צריך להפעיל את GoogleMap.setOnPolylineClickListener(OnPolylineClickListener). כשמשתמש לוחץ על קו פוליגוני, מתקבלת קריאה חוזרת (callback) מסוג onPolylineClick(Polyline).

פוליגונים

אובייקטים מסוג Polygon דומים לאובייקטים מסוג Polyline בכך שהם מורכבים מסדרה של קואורדינטות ברצף מסודר. עם זאת, במקום להיות פתוחים, פוליגונים מיועדים להגדיר אזורים בתוך לולאה סגורה עם מילוי פנימי.

אפשר להוסיף Polygon למפה באותו אופן שבו מוסיפים Polyline. קודם כל יוצרים אובייקט PolygonOptions ומוסיפים לו כמה נקודות. הנקודות האלה יהיו קווי המתאר של הפוליגון. לאחר מכן מוסיפים את הפוליגון למפה באמצעות קריאה ל-GoogleMap.addPolygon(PolygonOptions), שתחזיר אובייקט Polygon.

קטע הקוד הבא מוסיף מלבן למפה.

// Instantiates a new Polygon object and adds points to define a rectangle
val rectOptions = PolygonOptions()
    .add(
        LatLng(37.35, -122.0),
        LatLng(37.45, -122.0),
        LatLng(37.45, -122.2),
        LatLng(37.35, -122.2),
        LatLng(37.35, -122.0),
    )

// Get back the mutable Polygon
val polygon = map.addPolygon(rectOptions)

      

// Instantiates a new Polygon object and adds points to define a rectangle
PolygonOptions polygonOptions =
        new PolygonOptions()
                .add(
                        new LatLng(37.35, -122.0),
                        new LatLng(37.45, -122.0),
                        new LatLng(37.45, -122.2),
                        new LatLng(37.35, -122.2),
                        new LatLng(37.35, -122.0));

// Get back the mutable Polygon
Polygon polygon = map.addPolygon(polygonOptions);

      

כדי לשנות את הצורה של המצולע אחרי שהוא נוסף, אפשר להפעיל את Polygon.setPoints() ולספק רשימה חדשה של נקודות לקווי המתאר של המצולע.

אתם יכולים להתאים אישית את המראה של הפוליגון לפני שאתם מוסיפים אותו למפה וגם אחרי שהוספתם אותו למפה. למידע נוסף, עיינו בקטע התאמה אישית של המראה שבהמשך.

השלמה אוטומטית של פוליגונים

הפוליגון בדוגמה שלמעלה מורכב מחמש קואורדינטות, אבל שימו לב שהקואורדינטה הראשונה והאחרונה הן באותו מיקום, וזה מה שמגדיר את הלולאה. בפועל, מכיוון שמצולעים מגדירים אזורים סגורים, אין צורך להגדיר את הקואורדינטה האחרונה. אם הקואורדינטה האחרונה שונה מהראשונה, ה-API "יסגור" את הפוליגון באופן אוטומטי על ידי הוספת הקואורדינטה הראשונה בסוף רצף הקואורדינטות.

שני המצולעים הבאים זהים, והפעלת הפונקציה polygon.getPoints() בכל אחד מהם תחזיר את כל 4 הנקודות.

val polygon1 = map.addPolygon(
    PolygonOptions()
        .add(
            LatLng(0.0, 0.0),
            LatLng(0.0, 5.0),
            LatLng(3.0, 5.0),
            LatLng(0.0, 0.0),
        )
        .strokeColor(Color.RED)
        .fillColor(Color.BLUE),
)
val polygon2 = map.addPolygon(
    PolygonOptions()
        .add(
            LatLng(0.0, 0.0),
            LatLng(0.0, 5.0),
            LatLng(3.0, 5.0),
        )
        .strokeColor(Color.RED)
        .fillColor(Color.BLUE),
)

      

Polygon polygon1 =
        map.addPolygon(
                new PolygonOptions()
                        .add(
                                new LatLng(0, 0),
                                new LatLng(0, 5),
                                new LatLng(3, 5),
                                new LatLng(0, 0))
                        .strokeColor(Color.RED)
                        .fillColor(Color.BLUE));

Polygon polygon2 =
        map.addPolygon(
                new PolygonOptions()
                        .add(new LatLng(0, 0), new LatLng(0, 5), new LatLng(3, 5))
                        .strokeColor(Color.RED)
                        .fillColor(Color.BLUE));

      

יצירת פוליגון חלול

אפשר לשלב כמה נתיבים באובייקט Polygon אחד כדי ליצור צורות מורכבות, כמו טבעות מלאות או "דונאטס" (אזורים מצולעים שמופיעים בתוך המצולע כ "איים"). צורות מורכבות הן תמיד שילוב של כמה נתיבים פשוטים יותר.

צריך להגדיר שני נתיבים באותו אזור. האזור הגדול יותר מבין השניים מגדיר את אזור המילוי, והוא פוליגון פשוט ללא אפשרויות נוספות. לאחר מכן, מעבירים נתיב שני ל-method‏ addHole(). כשהנתיב השני, הקטן יותר, מוקף כולו בנתיב הגדול יותר, נראה כאילו חלק מהמצולע הוסר. אם החור מצטלב עם קווי המתאר של הפוליגון, הפוליגון יוצג ללא מילוי.

קטע הקוד הבא ייצור מלבן אחד עם חור מלבני קטן יותר.

val hole = listOf(
    LatLng(1.0, 1.0),
    LatLng(1.0, 2.0),
    LatLng(2.0, 2.0),
    LatLng(2.0, 1.0),
    LatLng(1.0, 1.0),
)
val hollowPolygon = map.addPolygon(
    PolygonOptions()
        .add(
            LatLng(0.0, 0.0),
            LatLng(0.0, 5.0),
            LatLng(3.0, 5.0),
            LatLng(3.0, 0.0),
            LatLng(0.0, 0.0),
        )
        .addHole(hole)
        .fillColor(Color.BLUE),
)

      

List<LatLng> hole =
        Arrays.asList(
                new LatLng(1, 1),
                new LatLng(1, 2),
                new LatLng(2, 2),
                new LatLng(2, 1),
                new LatLng(1, 1));
Polygon hollowPolygon =
        map.addPolygon(
                new PolygonOptions()
                        .add(
                                new LatLng(0, 0),
                                new LatLng(0, 5),
                                new LatLng(3, 5),
                                new LatLng(3, 0),
                                new LatLng(0, 0))
                        .addHole(hole)
                        .fillColor(Color.BLUE));

      

הפוליגון החלול מופיע במפה כמו שמוצג כאן:

אירועים ב-Polygon

כברירת מחדל, אי אפשר ללחוץ על מצולעים. כדי להפעיל ולהשבית את האפשרות ללחוץ על המודעה, מפעילים את Polygon.setClickable(boolean).

משתמשים ב-OnPolygonClickListener כדי להאזין לאירועים מסוג קליק בפוליגון שניתן ללחוץ עליו. כדי להגדיר את המאזין הזה במפה, צריך להפעיל את GoogleMap.setOnPolygonClickListener(OnPolygonClickListener). כשמשתמש לוחץ על פוליגון, מתקבלת קריאה חוזרת (callback) מסוג onPolygonClick(Polygon).

מעגלים

בנוסף למחלקה הגנרית Polygon, ה-Maps API כולל גם מחלקות ספציפיות לאובייקטים מסוג Circle, כדי לפשט את הבנייה שלהם.

כדי ליצור מעגל, צריך לציין את שני המאפיינים הבאים:

• center בתור LatLng.
• ‫radius במטרים.

לאחר מכן, מעגל מוגדר כקבוצה של כל הנקודות על פני כדור הארץ שנמצאות במרחק של radius מטרים מהנקודה center הנתונה. בגלל האופן שבו היטל מרקטור שבו משתמשים ב-Maps API מציג כדור על משטח שטוח, הוא יופיע כעיגול כמעט מושלם במפה כשהוא ממוקם ליד קו המשווה, ויופיע פחות ופחות כעיגול (במסך) ככל שהעיגול מתרחק מקו המשווה.

כדי לשנות את צורת המעגל אחרי שהוא נוסף, אפשר להפעיל את Circle.setRadius() או את Circle.setCenter() ולספק ערכים חדשים.

אתם יכולים להתאים אישית את המראה של העיגול לפני שמוסיפים אותו למפה וגם אחרי שמוסיפים אותו למפה. למידע נוסף, עיינו בקטע התאמה אישית של המראה שבהמשך.

בקטע הקוד הבא, כדי להוסיף עיגול למפה, יוצרים אובייקט CircleOptions וקוראים ל-GoogleMap.addCircle(CircleOptions):

// Instantiates a new CircleOptions object and defines the center and radius
val circleOptions = CircleOptions()
    .center(LatLng(37.4, -122.1))
    .radius(1000.0) // In meters

// Get back the mutable Circle
val circle = map.addCircle(circleOptions)

      

// Instantiates a new CircleOptions object and defines the center and radius
CircleOptions circleOptions =
        new CircleOptions().center(new LatLng(37.4, -122.1)).radius(1000); // In meters

// Get back the mutable Circle
Circle circle = map.addCircle(circleOptions);

      

אירועים במעגל

כברירת מחדל, אי אפשר ללחוץ על העיגולים. כדי להפעיל ולהשבית את האפשרות ללחוץ על המודעה, אפשר להפעיל את GoogleMap.addCircle() עם CircleOptions.clickable(boolean) או להפעיל את Circle.setClickable(boolean).

משתמשים ב-OnCircleClickListener כדי להאזין לאירועים מסוג קליק על עיגול שניתן ללחוץ עליו. כדי להגדיר את המאזין הזה במפה, צריך להפעיל את GoogleMap.setOnCircleClickListener(OnCircleClickListener).

כשמשתמש לוחץ על עיגול, אתם מקבלים קריאה חוזרת (callback) מסוג onCircleClick(Circle), כמו שמוצג בדוגמת הקוד הבאה:

val circle = map.addCircle(
    CircleOptions()
        .center(LatLng(37.4, -122.1))
        .radius(1000.0)
        .strokeWidth(10f)
        .strokeColor(Color.GREEN)
        .fillColor(Color.argb(128, 255, 0, 0))
        .clickable(true),
)
map.setOnCircleClickListener {
    // Flip the r, g and b components of the circle's stroke color.
    val strokeColor = it.strokeColor xor 0x00ffffff
    it.strokeColor = strokeColor
}

      

Circle circle =
        map.addCircle(
                new CircleOptions()
                        .center(new LatLng(37.4, -122.1))
                        .radius(1000)
                        .strokeWidth(10)
                        .strokeColor(Color.GREEN)
                        .fillColor(Color.argb(128, 255, 0, 0))
                        .clickable(true));

map.setOnCircleClickListener(
        new GoogleMap.OnCircleClickListener() {
            @Override
            public void onCircleClick(Circle circle) {
                // Flip the r, g and b components of the circle's stroke color.
                int strokeColor = circle.getStrokeColor() ^ 0x00ffffff;
                circle.setStrokeColor(strokeColor);
            }
        });

      

התאמה אישית של המראה

אפשר לשנות את המראה של צורה לפני שמוסיפים אותה למפה (על ידי ציון המאפיין הרצוי באובייקט האפשרויות) או אחרי שמוסיפים אותה למפה. גם פונקציות getter חשופות לכל המאפיינים, כדי שתוכלו לגשת בקלות למצב הנוכחי של הצורה.

קטע הקוד הבא מוסיף קו פוליגוני כחול עבה עם קטעים גיאודזיים ממלבורן לפרת'. בקטעים הבאים נסביר על המאפיינים האלה בפירוט.

val polyline = map.addPolyline(
    PolylineOptions()
        .add(LatLng(-37.81319, 144.96298), LatLng(-31.95285, 115.85734))
        .width(25f)
        .color(Color.BLUE)
        .geodesic(true),
)

      

Polyline polyline =
        map.addPolyline(
                new PolylineOptions()
                        .add(
                                new LatLng(-37.81319, 144.96298),
                                new LatLng(-31.95285, 115.85734))
                        .width(25)
                        .color(Color.BLUE)
                        .geodesic(true));

      

המפה מופיעה כמו שמוצג כאן:

הערה: אפשר להחיל את רוב המאפיינים האלה על כל אחת מהצורות שמתוארות, אבל יכול להיות שחלק מהמאפיינים לא יתאימו לצורות מסוימות (לדוגמה, אי אפשר להגדיר צבע מילוי לקו פוליגוני כי אין לו שטח פנימי).

צבע משיכה

צבע הקו הוא מספר שלם של 32 ביט בפורמט ARGB (אלפא-אדום-ירוק-כחול) שמציין את האטימות והצבע של קו הצורה. מגדירים את המאפיין הזה באובייקט האפשרויות של הצורה על ידי קריאה ל-*Options.strokeColor() (או ל-PolylineOptions.color() במקרה של קו פוליגוני). אם לא מציינים צבע, צבע ברירת המחדל של הקו הוא שחור (Color.BLACK).

אחרי שמוסיפים את הצורה למפה, אפשר לגשת לצבע הקו באמצעות קריאה ל-getStrokeColor() (או ל-getColor() בשביל קו פוליגוני) ולשנות אותו באמצעות קריאה ל-setStrokeColor() (setColor() for a polyline).

צבע מילוי

צבע המילוי חל רק על מצולעים ועיגולים. הוא לא חל על קווים פוליגוניים כי אין להם חלק פנימי מוגדר. בפוליגון, האזורים בתוך החורים שלו הם לא חלק מהפנים של הפוליגון, והם לא ייצבעו אם מוגדר צבע מילוי.

צבע המילוי הוא מספר שלם של 32 ביט בפורמט ARGB (אלפא-אדום-ירוק-כחול) שמציין את האטימות והצבע של החלק הפנימי של הצורה. כדי להגדיר את המאפיין הזה באובייקט האפשרויות של הצורה, צריך להפעיל את *Options.fillColor(). אם לא מצוין, צבע ברירת המחדל של קו המתאר הוא שקוף (Color.TRANSPARENT).

אחרי שמוסיפים את הצורה למפה, אפשר לגשת לצבע המילוי באמצעות קריאה ל-getFillColor() ולשנות אותו באמצעות קריאה ל-setFillColor().

רוחב משיכה

רוחב הקו, כערך מסוג float בפיקסלים (px). הרוחב לא משתנה כשמגדילים או מקטינים את המפה (כלומר, לצורה יהיה אותו רוחב קו בכל רמות הזום). מגדירים את המאפיין הזה באובייקט האפשרויות של הצורה באמצעות קריאה ל-*Options.strokeWidth() (או ל-PolylineOptions.width() בשביל קו פוליגוני). אם לא מצוין ערך, רוחב הקו שמוגדר כברירת המחדל הוא 10 פיקסלים.

אחרי שמוסיפים את הצורה למפה, אפשר לגשת לרוחב הקו באמצעות קריאה ל-getStrokeWidth() (או ל-getWidth() בשביל קו פוליגוני) ולשנות אותו באמצעות קריאה ל-setStrokeWidth() (setWidth() for a polyline).

תבנית קו

תבנית ברירת המחדל של קו המתאר היא קו רציף לקווים פוליגוניים ולקווי המתאר של פוליגונים ועיגולים. אפשר לציין תבנית קו מותאמת אישית של אובייקטים מסוג PatternItem, שבה כל פריט הוא מקף, נקודה או רווח.

בדוגמה הבאה, התבנית של הקו הפוליגוני מוגדרת לרצף חוזר של נקודה, ואחריה רווח באורך 20 פיקסלים, קו מפריד באורך 30 פיקסלים ורווח נוסף של 20 פיקסלים.

val pattern = listOf(
    Dot(),
    Gap(20F),
    Dash(30F),
    Gap(20F),
)
polyline?.pattern = pattern

      

List<PatternItem> pattern =
        Arrays.asList(new Dot(), new Gap(20), new Dash(30), new Gap(20));
polyline.setPattern(pattern);

      

התבנית חוזרת על עצמה לאורך הקו, החל מהפריט הראשון בתבנית בקודקוד הראשון שצוין לצורה.

סוגי מפרקים

בקו פוליגוני ובקווי מתאר של פוליגונים, אפשר לציין שיפוע או עיגול JointType כדי להחליף את סוג החיבור הקבוע של ברירת המחדל.

הדוגמה הבאה מחילה סוג חיבור מעוגל על קו פוליגוני:

polyline?.jointType = JointType.ROUND

      

polyline.setJointType(JointType.ROUND);

      

סוג החיבור משפיע על העיקולים הפנימיים בקו. אם לקו יש דפוס קו שכולל מקפים, סוג החיבור חל גם כשמקף חוצה חיבור. סוגי החיבורים לא משפיעים על הנקודות, כי הן תמיד עגולות.

קצוות קווים

אפשר לציין סגנון Cap לכל קצה של קו פוליגוני. האפשרויות הן: butt (ברירת המחדל), square,‏ round או מפת סיביות בהתאמה אישית. מגדירים את הסגנון ב-PolylineOptions.startCap וב-PolylineOptions.endCap, או משתמשים בשיטות המתאימות של getter ו-setter.

קטע הקוד הבא מציין קצה מעוגל בתחילת קו פוליגוני.

polyline?.startCap = RoundCap()

      

polyline.setStartCap(new RoundCap());

      

קטע הקוד הבא מציין מפת סיביות (bitmap) מותאמת אישית לפקק:

polyline?.endCap = CustomCap(BitmapDescriptorFactory.fromResource(R.drawable.arrow), 16F)

      

polyline.setEndCap(
        new CustomCap(BitmapDescriptorFactory.fromResource(R.drawable.arrow), 16));

      

כשמשתמשים במפת סיביות בהתאמה אישית, צריך לציין רוחב קו ייחוס בפיקסלים. ה-API משנה את קנה המידה של מפת הסיביות בהתאם. רוחב הקו של קובץ העזר הוא רוחב הקו שבו השתמשתם כשעיצבתם את תמונת מפת הסיביות של הקצה, בממדים המקוריים של התמונה. רוחב ברירת המחדל של קו הייחוס הוא 10 פיקסלים. טיפ: כדי לקבוע את רוחב קו הייחוס, פותחים את תמונת מפת הסיביות בזום של 100% בעורך תמונות, ומשרטטים את הרוחב הרצוי של קו המתאר ביחס לתמונה.

אם אתם משתמשים ב-BitmapDescriptorFactory.fromResource() כדי ליצור את מפת הסיביות, חשוב להשתמש במשאב שלא תלוי בצפיפות (nodpi).

קטעים גיאודזיים

ההגדרה הגיאודזית חלה רק על קווים פוליגוניים ופוליגונים. הוא לא חל על עיגולים כי הם לא מוגדרים כאוסף של קטעים.

ההגדרה הגיאודזית קובעת איך משורטטים מקטעי הקו בין קודקודים עוקבים של הקו הפוליגוני או המצולע. קטעים גיאודזיים הם קטעים שעוקבים אחרי הנתיב הקצר ביותר לאורך פני השטח של כדור הארץ (כדור), ולעיתים קרובות הם מופיעים כקווים מעוקלים במפה עם היטל מרקטור. קטעים לא גיאודזיים משורטטים כקווים ישרים במפה.

מגדירים את המאפיין הזה באובייקט האפשרויות של הצורה באמצעות קריאה ל-*Options.geodesic(), כאשר true מציין שצריך לשרטט את הקטעים כקווים גיאודזיים ו-false מציין שצריך לשרטט את הקטעים כקווים ישרים. אם לא מציינים ערך, ברירת המחדל היא קטעים לא גיאודזיים (false).

אחרי שמוסיפים את הצורה למפה, אפשר לגשת להגדרה הגיאודזית באמצעות קריאה ל-isGeodesic() ולשנות אותה באמצעות קריאה ל-setGeodesic().

Z-index

ה-z-index מציין את סדר הערימה של הצורה הזו, ביחס לשכבות-על אחרות (צורות אחרות, שכבות-על של הקרקע ושכבות-על של קטעי מפה) במפה. שכבת-על עם ערך z-index גבוה משורטטת מעל שכבות-על עם ערכי z-index נמוכים יותר. שתי שכבות-על עם אותו ערך z-index משורטטות בסדר שרירותי.

חשוב לזכור שסמנים תמיד משורטטים מעל שכבות-על אחרות, בלי קשר לערך ה-z-index של שכבות-העל האחרות.

כדי להגדיר את המאפיין הזה באובייקט האפשרויות של הצורה, צריך להפעיל את *Options.zIndex(). אם לא מצוין ערך, ברירת המחדל של z-index היא 0. אחרי שמוסיפים את הצורה למפה, אפשר לגשת ל-z-index באמצעות קריאה ל-getZIndex() ולשנות אותו באמצעות קריאה ל-setZIndex().

חשיפה

החשיפה מציינת אם הצורה צריכה להופיע במפה, כאשר true מציין שהיא צריכה להופיע ו-false מציין שהיא לא צריכה להופיע. היא מאפשרת להסתיר זמנית צורה במפה. כדי להסיר צורה מהמפה באופן סופי, צריך להפעיל את remove() על הצורה הזו.

כדי להגדיר את המאפיין הזה באובייקט האפשרויות של הצורה, צריך להפעיל את *Options.visible(). אם לא מציינים ערך, ברירת המחדל היא true. אחרי שמוסיפים את הצורה למפה, אפשר לגשת לסטטוס החשיפה באמצעות קריאה ל-isVisible() ולשנות אותו באמצעות קריאה ל-setVisible().

שיוך נתונים לצורה

אפשר לאחסן אובייקט נתונים שרירותי עם קו פוליגוני, פוליגון או עיגול באמצעות ה-method‏ setTag() של הצורה, ולאחזר את האובייקט באמצעות getTag(). לדוגמה, קוראים ל-Polyline.setTag() כדי לאחסן אובייקט נתונים עם קו פוליגוני, וקוראים ל-Polyline.getTag() כדי לאחזר את אובייקט הנתונים.

הקוד הבא מגדיר תג שרירותי (A) לקו הפוליגוני שצוין:

val polyline = map.addPolyline(
    PolylineOptions()
        .clickable(true)
        .add(
            LatLng(-35.016, 143.321),
            LatLng(-34.747, 145.592),
            LatLng(-34.364, 147.891),
            LatLng(-33.501, 150.217),
            LatLng(-32.306, 149.248),
            LatLng(-32.491, 147.309),
        ),
)
polyline?.tag = "A"

      

Polyline polyline =
        map.addPolyline(
                (new PolylineOptions())
                        .clickable(true)
                        .add(
                                new LatLng(-35.016, 143.321),
                                new LatLng(-34.747, 145.592),
                                new LatLng(-34.364, 147.891),
                                new LatLng(-33.501, 150.217),
                                new LatLng(-32.306, 149.248),
                                new LatLng(-32.491, 147.309)));

polyline.setTag("A");

      

הנה כמה דוגמאות לתרחישים שבהם כדאי לאחסן ולאחזר נתונים באמצעות צורות:

• יכול להיות שהאפליקציה שלכם תומכת בסוגים שונים של צורות, ואתם רוצים להתייחס אליהם בצורה שונה כשהמשתמש לוחץ עליהם.
• יכול להיות שאתם מתממשקים עם מערכת שיש בה מזהי רשומות ייחודיים, שבהם הצורות מייצגות רשומות ספציפיות במערכת הזו.
• נתוני הצורה עשויים לציין עדיפות לקביעת ה-z-index של הצורה.