Tuỳ chỉnh bố cục điều hướng

Sản phẩm hoặc tính năng này đang trong giai đoạn thử nghiệm (giai đoạn trước khi phát hành rộng rãi). Các sản phẩm và tính năng ở giai đoạn trước khi phát hành rộng rãi có thể bị hạn chế về dịch vụ hỗ trợ, đồng thời những thay đổi đối với các sản phẩm và tính năng ở giai đoạn trước khi phát hành rộng rãi có thể không tương thích với các phiên bản ở giai đoạn trước khi phát hành rộng rãi khác. Các Sản phẩm/dịch vụ ở giai đoạn trước khi phát hành rộng rãi tuân theo Điều khoản dành riêng cho dịch vụ của Nền tảng Google Maps. Để biết thêm thông tin, hãy xem nội dung mô tả về giai đoạn ra mắt.

Sử dụng chế độ tuỳ chỉnh bố cục để kiểm soát hệ phân cấp khung hiển thị và vị trí trên màn hình cho cả khung hiển thị do Google cung cấp và khung hiển thị tuỳ chỉnh của riêng bạn.

Thay vì thêm các khung hiển thị tuỳ chỉnh vào các vị trí đầu trang hoặc chân trang được xác định trước, hãy triển khai một uỷ quyền bố cục để quản lý bố cục cho toàn bộ màn hình. Trong quá trình chuyển đổi trạng thái điều hướng, đại biểu bố cục của bạn sẽ nhận được các thành phần do Google cung cấp, chẳng hạn như thẻ rẽ, thẻ thời gian đến dự kiến và các nút. Đặt các phần tử này cùng với nội dung tuỳ chỉnh của riêng bạn bằng cách sử dụng các hệ thống bố cục Android tiêu chuẩn như ConstraintLayout, CoordinatorLayout hoặc LinearLayout.

Sử dụng khung này để đặt thông tin doanh nghiệp tuỳ chỉnh (chẳng hạn như trạng thái đơn đặt hàng hoặc hướng dẫn nhận hàng) một cách chính xác trên màn hình trong khi ngăn các khung hiển thị của bạn chồng lên nhau.

Cách hoạt động của tính năng tuỳ chỉnh bố cục

Chế độ tuỳ chỉnh bố cục sử dụng mẫu thiết kế uỷ quyền. Thay vì tự động vẽ hoặc định vị các thành phần giao diện người dùng trên màn hình, SDK sẽ truyền trực tiếp các thành phần đó đến một lớp tuỳ chỉnh mà bạn viết: đại biểu bố cục.

Để tuỳ chỉnh bố cục, hãy tạo một lớp mở rộng lớp trừu tượng NavigationLayoutDelegate và chỉ định một thực thể cho NavigationView hoặc SupportNavigationFragment. Bất cứ khi nào trạng thái điều hướng chuyển đổi (chẳng hạn như di chuyển từ bản đồ cơ sở sang hướng dẫn từng chặng đang hoạt động), SDK sẽ thực thi các phương thức gọi lại trên đại biểu của bạn và cung cấp các thành phần giao diện người dùng có sẵn cho trạng thái cụ thể đó.

Để mang đến trải nghiệm người dùng liền mạch và tích hợp, khung này thiết lập một sự phân tách rõ ràng về trách nhiệm giữa ứng dụng và SDK của bạn. Sử dụng uỷ quyền bố cục để tuỳ chỉnh những nội dung sau:

• Tạo hệ phân cấp thành phần hiển thị: Chọn chính xác những thành phần của Google và thành phần hiển thị tuỳ chỉnh của doanh nghiệp cần thêm vào màn hình cho từng trạng thái giao diện người dùng.
• Định vị mọi phần tử: Đặt các điểm neo, lề và vị trí bố cục chính xác trên màn hình. Tránh áp dụng các quy tắc ràng buộc về chiều rộng hoặc chiều cao tuỳ chỉnh cho các thành phần của Google vì các thành phần của Google sẽ tính toán kích thước nội bộ của riêng chúng.
• Đóng khung bản đồ cơ sở: Xác định ranh giới có thể nhìn thấy của camera bản đồ bằng cách sử dụng toạ độ của thành phần khung nhìn.
• Xếp lớp màn hình: Quyết định xem các khung hiển thị tuỳ chỉnh sẽ xuất hiện phía trên, phía dưới hay cùng với các chế độ điều khiển tích hợp của Google.

Trong khi đó, bạn không thể tuỳ chỉnh các thành phần sau đây của Google bằng layout delegate:

• Phương diện thành phần: Kích thước và phương diện nội bộ của các thành phần do Google cung cấp mà SDK tự động tính toán.
• Điều kiện kích hoạt: Khi cảnh báo hoặc lời nhắc linh hoạt xuất hiện dựa trên dữ liệu tuyến đường theo thời gian thực.

Nguyên tắc triển khai

Khi viết một uỷ quyền bố cục, hãy lưu ý các quy tắc sau để ngăn lỗi bố cục hoặc sự cố thời gian chạy:

• Màn hình trống là màn hình mặc định: Các thành phần do Google cung cấp chỉ xuất hiện nếu uỷ quyền của bạn thêm rõ ràng các thành phần đó vào hệ phân cấp khung hiển thị và định vị các thành phần đó.
• Không hỗ trợ các API cũ: Các thuộc tính và phương thức kiểm soát mô hình bố cục dựa trên khe cắm cũ sẽ không được hỗ trợ và có thể không hoạt động như mong đợi khi một uỷ quyền tuỳ chỉnh đang hoạt động.
• Không sửa đổi cấu trúc khung hiển thị nội bộ: Không sử dụng các phương thức như findViewById() để di chuyển hoặc sửa đổi hệ phân cấp khung hiển thị của các thành phần do Google cung cấp (chẳng hạn như thẻ rẽ hoặc thẻ thời gian đến dự kiến). Vì các hệ phân cấp khung hiển thị nội bộ này là thông tin triển khai chi tiết cơ bản, nên chúng có thể thay đổi trong các bản phát hành SDK. Việc sửa đổi các thuộc tính này có thể khiến bố cục của bạn bị lỗi trong các bản cập nhật SDK sau này.

Khả năng tương thích với API cũ

Để có hành vi bố cục đáng tin cậy khi sử dụng một uỷ quyền bố cục tuỳ chỉnh, hãy tránh sử dụng các API dựa trên khe cắm cũ sau đây (dự kiến sẽ không được dùng nữa). Để di chuyển một ứng dụng hiện có, hãy thay thế việc sử dụng các API này bằng mã trong uỷ quyền bố cục tuỳ chỉnh:

Hiện các API cũ dựa trên khe

API cũ	Thay thế Layout Delegate
setCustomControl(View, CustomControlPosition)	Thêm trực tiếp các thành phần hiển thị vào ConstraintLayout hoặc nhóm view khác.
removeCustomControl(View)	Xoá khung hiển thị ngay trong hệ phân cấp view.
setEtaCardEnabled(boolean)	Đọc chế độ xem etaCard trong onEnterActiveGuidance.
setHeaderEnabled(boolean)	Đọc chế độ xem turnCard trong onEnterActiveGuidance.
setReportIncidentButtonEnabled(boolean)	Tìm nút REPORTING trong getActiveGuidanceButtons().
setTripProgressBarEnabled(boolean)	Đọc chế độ xem tripProgressBar trong onEnterActiveGuidance.
addOnNavigationUiChangedListener(...)	Dựa vào các lệnh gọi lại chuyển đổi trạng thái NavigationLayoutDelegate.
removeOnNavigationUiChangedListener(...)	Quản lý trực tiếp các hiệu ứng chuyển đổi trạng thái bố cục bằng cách sử dụng uỷ quyền.
addPromptVisibilityChangedListener(...)	Dựa vào các lệnh gọi lại câu lệnh NavigationLayoutDelegate (chẳng hạn như onShowPrompt()).
removePromptVisibilityChangedListener(...)	Quản lý trực tiếp logic hiển thị lời nhắc bằng cách sử dụng uỷ quyền.
setCompassEnabled(boolean)	Tìm la bàn trong getNavigationReadyButtons() hoặc getActiveGuidanceButtons().

Danh sách kiểm tra Essentials

Hãy làm theo các bước và yêu cầu cần thiết sau đây để triển khai thành công uỷ quyền bố cục:

• Khởi chạy uỷ quyền trước khi tạo giao diện người dùng: Gọi setLayoutDelegate() trước khi SDK khởi chạy giao diện người dùng điều hướng. Hãy xem các ví dụ sau đây về cách triển khai mã để xác minh thời gian thiết lập chính xác cho cấu trúc ứng dụng của bạn. Việc khởi chạy uỷ quyền sau khi tạo giao diện người dùng sẽ kích hoạt ApiIllegalStateException.

  Kotlin

  // For SupportNavigationFragment
  override fun onCreate(savedInstanceState: Bundle?) {
      super.onCreate(savedInstanceState)
      setContentView(R.layout.activity_main)
      val navFragment = supportFragmentManager.findFragmentById(R.id.nav_fragment) as SupportNavigationFragment
      navFragment.setLayoutDelegate(MyLayoutDelegate())
  }
  
  // For a programmatic NavigationView
  val navigationView = NavigationView(context)
  navigationView.setLayoutDelegate(MyLayoutDelegate())
  navigationView.onCreate(savedInstanceState)
          

  Java

  // For SupportNavigationFragment
  @Override
  protected void onCreate(Bundle savedInstanceState) {
      super.onCreate(savedInstanceState);
      setContentView(R.layout.activity_main);
      SupportNavigationFragment navFragment = (SupportNavigationFragment) getSupportFragmentManager().findFragmentById(R.id.nav_fragment);
      navFragment.setLayoutDelegate(new MyLayoutDelegate());
  }
  
  // For a programmatic NavigationView
  NavigationView navigationView = new NavigationView(context);
  navigationView.setLayoutDelegate(new MyLayoutDelegate());
  navigationView.onCreate(savedInstanceState);
          

• Tạo vùng chứa bố cục của riêng bạn: Tạo một nhóm khung hiển thị tuỳ chỉnh (chẳng hạn như ConstraintLayout) để chứa các phần tử giao diện người dùng tuỳ chỉnh và khung hiển thị do Google cung cấp.

• Đính kèm các khung hiển thị bắt buộc: Bạn phải thêm biểu trưng Google (getGoogleLogo()) và Khung hiển thị (getViewport()) vào vùng chứa bố cục trong mọi trạng thái điều hướng. Nếu không đưa cả hai khung hiển thị này vào, ứng dụng sẽ kích hoạt ApiIllegalStateException trong thời gian chạy và gặp sự cố.

• Tôn trọng kích thước cố định: SDK xác định kích thước cho một số thành phần do Google cung cấp. Không áp dụng các ràng buộc về chiều rộng hoặc chiều cao tuỳ chỉnh cho các phần tử sau:

  • Lật thẻ
  • Thẻ ETA
  • Câu lệnh đến
  • Biểu trưng Google
  • Tiện ích tốc độ

• Đính kèm bố cục vào khung hiển thị: Gọi navigationView.setNavigationLayout() bên trong các lệnh gọi lại onEnterNavigationReady() và onEnterActiveGuidance() để đính kèm vùng chứa vào hệ phân cấp view khung hiển thị bản đồ.

• Dọn dẹp khi thoát trạng thái: Gọi navigationView.removeNavigationLayout() và xoá các thành phần hiển thị tuỳ chỉnh bên trong các lệnh gọi lại onLeave để ngăn tình trạng rò rỉ bộ nhớ và các trạng thái giao diện người dùng chồng chéo.

• Tránh dùng các API bố cục cũ: Đừng gọi các API dựa trên khe cắm không dùng nữa như setCustomControl() hoặc setHeaderEnabled() khi một uỷ quyền tuỳ chỉnh đang hoạt động. SDK có thể bỏ qua các lệnh gọi cũ này khi một uỷ quyền tuỳ chỉnh được đính kèm.

Trạng thái giao diện người dùng và các thành phần của Google

Khi quá trình chuyển đổi trạng thái điều hướng diễn ra, SDK sẽ truyền một đối tượng UiState chỉ có thể đọc đến lệnh gọi lại uỷ quyền của bạn. Đối tượng này kết hợp các cờ cấu hình bố cục hiện tại với các thành phần của Google (ví dụ: các thực thể View) mà bạn cần để kết xuất màn hình.

Uỷ quyền bố cục quản lý hệ phân cấp view trên 4 trạng thái hoạt động. Sơ đồ trạng thái sau đây minh hoạ cách SDK chuyển đổi giữa các trạng thái điều hướng và phương thức gọi lại mà SDK thực thi trên đại biểu của bạn:

Các thành phần cụ thể của Google được cung cấp cho đại biểu của bạn phụ thuộc vào giai đoạn hiện tại của vòng đời điều hướng.

Thành phần bắt buộc (tất cả các trạng thái điều hướng)

Bất kể giai đoạn điều hướng hiện tại, bạn phải đưa, đặt và giữ cho các thành phần sau đây của Google hiển thị trong hệ phân cấp view của bạn:

• Biểu trưng của Google (getGoogleLogo()): Thành phần này hiển thị biểu trưng bắt buộc của Google Maps. Nếu nút Định tâm lại được bật, thì biểu trưng sẽ tự động chuyển đổi thành nút này khi người lái xe di chuyển bản đồ ra khỏi xe. Do đó, vị trí đặt biểu trưng sẽ quyết định nơi nút Đặt lại tâm xuất hiện. Bạn nên đặt biểu trưng ở góc dưới cùng bên trái của bố cục để đáp ứng các yêu cầu về giao diện người dùng bản đồ tiêu chuẩn.

• Khung nhìn (getViewport()): Một View vô hình xác định ranh giới khung hình của camera. Vị trí của cửa sổ xem sẽ quyết định chính xác vị trí mà SDK đặt biểu tượng hình chữ V của xe ở giữa và vẽ đường tuyến đường đang hoạt động. Đặt khung hiển thị sao cho khung này bao phủ vùng mở, không bị che khuất trên màn hình, đồng thời tránh các lớp phủ mờ như trang tính tuỳ chỉnh ở dưới cùng một cách an toàn.

Các thành phần hỗ trợ điều hướng

Trong trạng thái sẵn sàng điều hướng, giao diện người dùng vẫn ở mức tối thiểu để tập trung vào bản đồ cơ sở. Đối tượng NavigationReadyUiState của bạn cung cấp quyền truy cập vào những nội dung sau:

• getNavigationReadyButtons(): Danh sách các khung hiển thị nút hành động nổi được định cấu hình cho bản đồ cơ sở (thường chỉ là nút La bàn). Vì Google có thể thêm hoặc sắp xếp lại các nút trong các bản phát hành SDK sau này, nên bạn cần tránh dựa vào các chỉ mục danh sách cố định. Thay vào đó, hãy lặp lại danh sách, đọc loại của từng nút bằng cách so sánh getType() với ButtonKnownType.COMPASS và trích xuất khung hiển thị thực bằng cách gọi getView(). Xin lưu ý rằng các nút chính xác trong danh sách này khác với các nút có sẵn trong quá trình hướng dẫn đang hoạt động.

Các thành phần hướng dẫn đang hoạt động

Khi hướng dẫn theo từng chặng bắt đầu, SDK sẽ mở khoá đủ bộ điều khiển điều hướng. Đối tượng ActiveGuidanceUiState cung cấp quyền truy cập vào các thành phần sau của Google:

• getTurnCard(): Biểu ngữ tiêu đề chính hiển thị chỉ dẫn về thao tác sắp tới, số đo khoảng cách và hướng dẫn làn đường. Đặt thành phần này ở đầu bố cục để thiết lập một hệ thống phân cấp điều hướng quen thuộc và cố định các khung hiển thị tuỳ chỉnh xung quanh thành phần đó.

• getEtaCard(): Biểu ngữ chân trang hiển thị thời gian đến dự kiến, thời gian còn lại của hành trình và khoảng cách còn lại đến đích đến. Đặt tiện ích này dọc theo cạnh dưới của màn hình hoặc tích hợp toạ độ của tiện ích này với các trang quản lý tác vụ tuỳ chỉnh.

• getTripProgressBar(): Thanh tiến trình dọc cho biết quãng đường mà người lái xe đã đi được trên tuyến đường hiện tại. Không giống như các bố cục cũ chỉ cố định thành phần này ở rìa bản đồ, bạn hoàn toàn có thể tự do đặt thành phần này ở bất kỳ đâu, chẳng hạn như dọc theo một cạnh bên của vùng chứa tuỳ chỉnh.

• getSpeedWidget(): Một chế độ điều khiển nổi cho đồng hồ tốc độ và giới hạn tốc độ được đăng. Tuỳ thuộc vào chế độ cài đặt API và tình trạng sẵn có của dữ liệu, khung hiển thị này sẽ tự động điều chỉnh kích thước giữa 4 trạng thái trực quan trong thời gian chạy (không hiển thị gì, chỉ hiển thị tốc độ hiện tại, chỉ hiển thị giới hạn tốc độ hoặc hiển thị cả hai chỉ số). Vì tiện ích có thể chuyển đổi giữa các kích thước này mà không có thông báo, nên hãy luôn cố định các khung hiển thị xung quanh bằng cách sử dụng các ràng buộc để bố cục của bạn tự động điều chỉnh nhằm ngăn chặn tình trạng chồng chéo không gian.

• getActiveGuidanceButtons(): Danh sách mở rộng gồm các khung hiển thị nút hành động nổi cho trạng thái hướng dẫn đang hoạt động (thường bao gồm cả nút La bàn và nút Báo cáo sự cố). Giống như ở trạng thái sẵn sàng điều hướng, bạn có thể xác định vị trí và trích xuất từng khung hiển thị nút bằng cách lọc danh sách theo ButtonKnownType (COMPASS hoặc REPORTING) và trích xuất khung hiển thị bằng getView(). Sau đó, bạn có thể định vị chúng một cách độc lập hoặc sử dụng một bố cục như AutoHidingLinearLayout để xếp chồng mảng một cách an toàn mà không có xung đột về không gian.

Lưu ý: Phương pháp hay nhất để lấy khung hình camera. Thẻ rẽ sử dụng chiều cao cố định là 150 dp, có thể truy cập thông qua StyleValues.headerNominalHeightDp(). Để giữ khung hình camera ổn định, đừng ràng buộc phần trên cùng của getViewport() trực tiếp với cạnh dưới của getTurnCard(). Thay vào đó, hãy ràng buộc khung hiển thị với phần trên cùng của chế độ xem của cha mẹ và đặt lề trên cùng thành StyleValues.headerNominalHeightDp(), như minh hoạ trong ví dụ về cách triển khai.

Thành phần Lời nhắc linh hoạt

Các lời nhắc, chẳng hạn như cảnh báo về sự cố hoặc cảnh báo của camera an toàn, sẽ kích hoạt độc lập trong quá trình hướng dẫn đang hoạt động.

Khi một lời nhắc đã sẵn sàng hiển thị, SDK sẽ gọi lệnh gọi lại onShowPrompt() của uỷ quyền và truyền một khung hiển thị newPrompt. Uỷ quyền của bạn chịu trách nhiệm định vị lời nhắc này một cách mượt mà trên bố cục của bạn (thường được neo vào cạnh dưới của vùng chứa bản đồ).

Vì lời nhắc đến sẽ che phủ phần dưới của màn hình, nên bạn phải cập nhật bố cục để lời nhắc không chồng lên khung nhìn, biểu trưng của Google hoặc bất kỳ nút nào được căn chỉnh ở dưới cùng.

Xử lý kích thước màn hình và chế độ màn hình rộng

Để xử lý các thay đổi về kích thước bản đồ và hướng màn hình, uỷ quyền bố cục sẽ sử dụng các tính năng sau:

• Xem đổi kích thước: Điều chỉnh bố cục của bạn bất cứ khi nào kích thước thực của bản đồ thay đổi.

• Chế độ rộng: Chuyển sang một biến thể bố cục định dạng rộng khi bản đồ đủ rộng.

Phản hồi việc đổi kích thước khung hiển thị

Bất cứ khi nào kích thước thực của vùng chứa bản đồ thay đổi, SDK sẽ thực thi lệnh gọi lại onSizeChanged(). Bố cục chia màn hình, thanh trượt bố cục và thao tác xoay thiết bị thường kích hoạt lệnh gọi lại onSizeChanged(). Sử dụng lệnh gọi lại này để điều chỉnh chung cho phù hợp với giao diện người dùng tuỳ chỉnh của bạn. Triển khai onSizeChanged() để định vị lại các phần tử tuỳ chỉnh cho tỷ lệ khung hình màn hình mới, áp dụng các điểm ngắt chiều rộng hoặc chiều cao tuỳ chỉnh của riêng bạn và phát hiện thời điểm sự kiện thay đổi kích thước chuyển đổi chế độ rộng để hoán đổi các biến thể bố cục một cách an toàn.

Tìm hiểu về chế độ rộng

Chế độ rộng sẽ kích hoạt khi vùng chứa bản đồ đủ rộng để hiển thị các thành phần giao diện người dùng cạnh nhau.

Đọc giá trị boolean isWideMode() từ đối tượng trạng thái để định vị lại các phần tử giao diện người dùng tuỳ chỉnh và giữ cho tâm bản đồ không bị che khuất đối với người lái xe. Vì các thành phần do Google cung cấp (chẳng hạn như thẻ rẽ và thẻ thời gian đến dự kiến) tự động thu nhỏ và định hình lại ở chế độ rộng, nên việc đọc giá trị boolean này sẽ đảm bảo bố cục của bạn thích ứng ngay tại thời điểm các thành phần của Google cập nhật.

Hãy xem xét các ví dụ sau đây để định vị các thành phần bố cục ở chế độ tiêu chuẩn và chế độ rộng:

• Chế độ chân dung tiêu chuẩn: Đặt thẻ rẽ ở đầu màn hình và thẻ thời gian đến dự kiến ở cuối màn hình.

• Chế độ rộng: Di chuyển thẻ rẽ sang phía đầu của màn hình và thẻ thời gian đến dự kiến sang phía cuối.

Kiểm tra chế độ rộng trong quá trình chuyển đổi trạng thái

Nếu bố cục của bạn hỗ trợ một biến thể ở chế độ rộng, hãy đánh giá boolean isWideMode() bên trong mọi lệnh gọi lại chuyển đổi trạng thái, thay vì chỉ dựa vào onSizeChanged().

Kiểm tra đối tượng trạng thái trong các lệnh gọi lại như onEnterNavigationReady() và onEnterActiveGuidance() để xử lý các lần khởi chạy ứng dụng ban đầu ở chế độ ngang. Phương pháp này bảo vệ bố cục của bạn khỏi các sự kiện vòng đời của hệ thống Android (chẳng hạn như việc tạo lại Hoạt động mặc định) hoàn toàn bỏ qua lệnh gọi lại thay đổi kích thước, đảm bảo rằng biến thể bố cục tiêu chuẩn hoặc bố cục rộng chính xác sẽ kích hoạt ngay khi bắt đầu một trạng thái điều hướng mới.

Phù hợp với kiểu dáng của Google

Để giúp giao diện người dùng tuỳ chỉnh của bạn phù hợp với nhịp điệu hình ảnh của Google, SDK cung cấp lớp tiện ích StyleValues. Bạn có thể đọc các giá trị này bằng pixel không phụ thuộc vào mật độ (dp) để căn chỉnh các khung hiển thị một cách hoàn hảo với các thành phần của Google.

Ví dụ: nếu muốn đặt một nút tuỳ chỉnh ở góc trên cùng của màn hình đối diện với thẻ rẽ, bạn có thể gọi StyleValues.headerTopPaddingDp() và chỉ định giá trị trả về làm lề trên cùng của nút. Việc này giúp đảm bảo nút tuỳ chỉnh của bạn căn chỉnh trực quan với cạnh trên của thẻ chỉ dẫn, duy trì tính đối xứng của màn hình.

Sau đây là các khoảng đệm và kích thước kiểu có sẵn:

• StyleValues.headerNominalHeightDp()
• StyleValues.headerTopPaddingDp()
• StyleValues.headerFooterSidePaddingDp()
• StyleValues.mapControlSidePaddingDp()
• StyleValues.buttonMapControlSidePaddingDp()

Ví dụ: Triển khai bố cục dựa trên ràng buộc

Ví dụ sau đây minh hoạ một uỷ quyền bố cục cơ bản quản lý các quá trình chuyển đổi trạng thái bằng cách sử dụng các định nghĩa ConstraintLayout và ConstraintSet theo chương trình.

Mặc dù ví dụ này tạo các ràng buộc về khung hiển thị trong mã, nhưng các uỷ quyền bố cục cũng có thể mở rộng các bố cục XML tiêu chuẩn của Android.

Kotlin

/*
 * Copyright 2026 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

@file:Suppress("PackageName")

package com.example.navigationapidemo.layoutdelegate

import android.content.Context
import android.util.TypedValue
import android.view.View
import android.view.ViewGroup
import androidx.constraintlayout.widget.ConstraintLayout
import androidx.constraintlayout.widget.ConstraintSet
import com.google.android.libraries.navigation.layoutcustomization.ActiveGuidanceUiState
import com.google.android.libraries.navigation.layoutcustomization.AutoHidingVerticalLayout
import com.google.android.libraries.navigation.layoutcustomization.NavigationLayoutDelegate
import com.google.android.libraries.navigation.layoutcustomization.NavigationReadyUiState
import com.google.android.libraries.navigation.layoutcustomization.NavigationUiButton.ButtonKnownType.COMPASS
import com.google.android.libraries.navigation.layoutcustomization.NavigationUiParent
import com.google.android.libraries.navigation.layoutcustomization.StyleValues.headerNominalHeightDp

/** Kotlin equivalent of StandardUiElementsLayoutDelegate. */
class StandardUiElementsLayoutDelegateKt : NavigationLayoutDelegate() {

  private val layoutId = View.generateViewId()
  private val buttonsContainerId = View.generateViewId()

  private var layout: ConstraintLayout? = null
  private var buttonsContainer: AutoHidingVerticalLayout? = null

  private var navigationReadyConstraintSet: ConstraintSet? = null
  private var activeGuidanceConstraintSet: ConstraintSet? = null
  private var activeGuidanceWithPromptConstraintSet: ConstraintSet? = null

  private var activeGuidanceUiState: ActiveGuidanceUiState? = null

  override fun onEnterNavigationReady(
    navigationUiParent: NavigationUiParent,
    newState: NavigationReadyUiState,
  ) {
    val context = navigationUiParent.viewContext

    var currentLayout = layout
    if (currentLayout == null) {
      currentLayout =
        ConstraintLayout(context).apply {
          layoutParams =
            ViewGroup.LayoutParams(
              ViewGroup.LayoutParams.MATCH_PARENT,
              ViewGroup.LayoutParams.MATCH_PARENT,
            )
          id = layoutId
        }
      layout = currentLayout
    }

    removeFromParentView(newState.viewport)
    currentLayout.addView(
      newState.viewport,
      ViewGroup.LayoutParams(
        ViewGroup.LayoutParams.MATCH_PARENT,
        ViewGroup.LayoutParams.MATCH_PARENT,
      ),
    )

    removeFromParentView(newState.googleLogo)
    currentLayout.addView(
      newState.googleLogo,
      ViewGroup.LayoutParams(
        ViewGroup.LayoutParams.MATCH_PARENT,
        ViewGroup.LayoutParams.WRAP_CONTENT,
      ),
    )

    var currentButtonsContainer = buttonsContainer
    if (currentButtonsContainer == null) {
      currentButtonsContainer = AutoHidingVerticalLayout(context).apply { id = buttonsContainerId }
      buttonsContainer = currentButtonsContainer
    }

    removeFromParentView(currentButtonsContainer)
    currentLayout.addView(
      currentButtonsContainer,
      ViewGroup.LayoutParams(
        ViewGroup.LayoutParams.WRAP_CONTENT,
        ConstraintLayout.LayoutParams.MATCH_CONSTRAINT,
      ),
    )

    for (button in newState.navigationReadyButtons) {
      removeFromParentView(button.view)
      currentButtonsContainer.addView(button.view)
    }

    if (navigationReadyConstraintSet == null) {
      navigationReadyConstraintSet = buildNavigationReadyConstraintSet(newState)
    }
    navigationReadyConstraintSet?.applyTo(currentLayout)

    navigationUiParent.removeNavigationLayout(currentLayout)
    navigationUiParent.setNavigationLayout(currentLayout)
  }

  private fun buildNavigationReadyConstraintSet(uiState: NavigationReadyUiState): ConstraintSet {
    return ConstraintSet().apply {
      clone(layout)

      connect(
        uiState.viewport.id,
        ConstraintSet.START,
        ConstraintSet.PARENT_ID,
        ConstraintSet.START,
      )
      connect(uiState.viewport.id, ConstraintSet.TOP, ConstraintSet.PARENT_ID, ConstraintSet.TOP)
      connect(uiState.viewport.id, ConstraintSet.END, ConstraintSet.PARENT_ID, ConstraintSet.END)
      connect(
        uiState.viewport.id,
        ConstraintSet.BOTTOM,
        ConstraintSet.PARENT_ID,
        ConstraintSet.BOTTOM,
      )

      connect(
        uiState.googleLogo.id,
        ConstraintSet.BOTTOM,
        ConstraintSet.PARENT_ID,
        ConstraintSet.BOTTOM,
      )
      connect(
        uiState.googleLogo.id,
        ConstraintSet.START,
        ConstraintSet.PARENT_ID,
        ConstraintSet.START,
      )

      constrainButtonsToBottomEnd()
    }
  }

  override fun onLeaveNavigationReady(
    navigationUiParent: NavigationUiParent,
    oldState: NavigationReadyUiState,
  ) {
    buttonsContainer?.removeAllViews()
    layout?.removeAllViews()
    layout?.let { navigationUiParent.removeNavigationLayout(it) }
  }

  override fun onEnterActiveGuidance(
    navigationUiParent: NavigationUiParent,
    oldState: NavigationReadyUiState,
    newState: ActiveGuidanceUiState,
  ) {
    activeGuidanceUiState = newState
    val context = navigationUiParent.viewContext
    val currentLayout = checkNotNull(layout) { "layout must be initialized" }
    val currentButtonsContainer =
      checkNotNull(buttonsContainer) { "buttonsContainer must be initialized" }

    removeFromParentView(newState.turnCard)
    currentLayout.addView(
      newState.turnCard,
      ViewGroup.LayoutParams(
        ViewGroup.LayoutParams.WRAP_CONTENT,
        ViewGroup.LayoutParams.WRAP_CONTENT,
      ),
    )

    removeFromParentView(newState.etaCard)
    currentLayout.addView(
      newState.etaCard,
      ViewGroup.LayoutParams(
        ViewGroup.LayoutParams.WRAP_CONTENT,
        ViewGroup.LayoutParams.WRAP_CONTENT,
      ),
    )

    for (button in oldState.navigationReadyButtons) {
      removeFromParentView(button.view)
    }

    for (button in newState.activeGuidanceButtons) {
      val buttonLayoutParams =
        AutoHidingVerticalLayout.LayoutParams(
          ViewGroup.LayoutParams.WRAP_CONTENT,
          ViewGroup.LayoutParams.WRAP_CONTENT,
        )
      if (button.type == COMPASS) {
        buttonLayoutParams.isHighPriority = true
      }
      removeFromParentView(button.view)
      currentButtonsContainer.addView(button.view, buttonLayoutParams)
    }

    if (activeGuidanceConstraintSet == null) {
      activeGuidanceConstraintSet = buildActiveGuidanceConstraintSet(context, newState)
    }

    activeGuidanceConstraintSet?.applyTo(currentLayout)
  }

  override fun onLeaveActiveGuidance(
    navigationUiParent: NavigationUiParent,
    oldState: ActiveGuidanceUiState,
    newState: NavigationReadyUiState,
  ) {
    removeFromParentView(oldState.etaCard)
    removeFromParentView(oldState.turnCard)
    buttonsContainer?.removeAllViews()

    val currentButtonsContainer =
      checkNotNull(buttonsContainer) { "buttonsContainer must be initialized" }
    for (button in newState.navigationReadyButtons) {
      currentButtonsContainer.addView(
        button.view,
        ViewGroup.LayoutParams(
          ViewGroup.LayoutParams.WRAP_CONTENT,
          ViewGroup.LayoutParams.WRAP_CONTENT,
        ),
      )
    }

    navigationReadyConstraintSet?.applyTo(layout)
  }

  private fun buildActiveGuidanceConstraintSet(
    context: Context,
    uiState: ActiveGuidanceUiState,
  ): ConstraintSet {
    return ConstraintSet().apply {
      clone(layout)

      connect(uiState.turnCard.id, ConstraintSet.TOP, ConstraintSet.PARENT_ID, ConstraintSet.TOP)
      connect(
        uiState.turnCard.id,
        ConstraintSet.START,
        ConstraintSet.PARENT_ID,
        ConstraintSet.START,
      )

      clear(uiState.viewport.id)
      connect(
        uiState.viewport.id,
        ConstraintSet.START,
        ConstraintSet.PARENT_ID,
        ConstraintSet.START,
      )
      connect(uiState.viewport.id, ConstraintSet.TOP, ConstraintSet.PARENT_ID, ConstraintSet.TOP)
      setMargin(uiState.viewport.id, ConstraintSet.TOP, dpToPx(headerNominalHeightDp(), context))
      connect(uiState.viewport.id, ConstraintSet.END, ConstraintSet.PARENT_ID, ConstraintSet.END)
      connect(uiState.viewport.id, ConstraintSet.BOTTOM, uiState.etaCard.id, ConstraintSet.TOP)

      clear(uiState.googleLogo.id, ConstraintSet.BOTTOM)
      constrainLogoToTopOfEtaCard(uiState)
      constrainEtaCardToBottomStart(uiState)
      constrainButtonsToTopOfEtaCard(context, uiState)
    }
  }

  private fun ConstraintSet.constrainEtaCardToBottomStart(uiState: ActiveGuidanceUiState) {
    connect(uiState.etaCard.id, ConstraintSet.START, ConstraintSet.PARENT_ID, ConstraintSet.START)
    connect(uiState.etaCard.id, ConstraintSet.BOTTOM, ConstraintSet.PARENT_ID, ConstraintSet.BOTTOM)
  }

  private fun ConstraintSet.constrainLogoToTopOfEtaCard(uiState: ActiveGuidanceUiState) {
    connect(uiState.googleLogo.id, ConstraintSet.BOTTOM, uiState.etaCard.id, ConstraintSet.TOP)
  }

  private fun ConstraintSet.constrainButtonsToBottomEnd() {
    clear(buttonsContainerId, ConstraintSet.BOTTOM)
    clear(buttonsContainerId, ConstraintSet.TOP)
    connect(buttonsContainerId, ConstraintSet.TOP, ConstraintSet.PARENT_ID, ConstraintSet.TOP)
    connect(buttonsContainerId, ConstraintSet.BOTTOM, ConstraintSet.PARENT_ID, ConstraintSet.BOTTOM)
    connect(buttonsContainerId, ConstraintSet.END, ConstraintSet.PARENT_ID, ConstraintSet.END)
  }

  private fun ConstraintSet.constrainButtonsToTopOfEtaCard(
    context: Context,
    uiState: ActiveGuidanceUiState,
  ) {
    clear(buttonsContainerId, ConstraintSet.BOTTOM)
    clear(buttonsContainerId, ConstraintSet.TOP)
    connect(buttonsContainerId, ConstraintSet.BOTTOM, uiState.etaCard.id, ConstraintSet.TOP)
    connect(buttonsContainerId, ConstraintSet.TOP, ConstraintSet.PARENT_ID, ConstraintSet.TOP)
    connect(buttonsContainerId, ConstraintSet.END, ConstraintSet.PARENT_ID, ConstraintSet.END)
    setMargin(buttonsContainerId, ConstraintSet.TOP, dpToPx(headerNominalHeightDp(), context))
  }

  override fun onShowPrompt(navigationUiParent: NavigationUiParent, newPrompt: View) {
    val context = navigationUiParent.viewContext
    layout?.addView(newPrompt)

    if (activeGuidanceUiState != null) {
      activeGuidanceWithPromptConstraintSet =
        buildActiveGuidanceWithPromptConstraintSet(context, newPrompt)
      activeGuidanceWithPromptConstraintSet?.applyTo(layout)
    }
  }

  override fun onChangePrompt(
    navigationUiParent: NavigationUiParent,
    oldPrompt: View,
    newPrompt: View,
  ) {
    val context = navigationUiParent.viewContext
    activeGuidanceWithPromptConstraintSet?.clear(oldPrompt.id)

    val currentLayout = checkNotNull(layout) { "layout must be initialized" }
    currentLayout.removeView(oldPrompt)
    currentLayout.addView(newPrompt)

    if (activeGuidanceUiState != null) {
      activeGuidanceWithPromptConstraintSet =
        buildActiveGuidanceWithPromptConstraintSet(context, newPrompt)
      activeGuidanceWithPromptConstraintSet?.applyTo(currentLayout)
    }
  }

  override fun onHidePrompt(navigationUiParent: NavigationUiParent, oldPrompt: View) {
    activeGuidanceWithPromptConstraintSet?.clear(oldPrompt.id)
    layout?.removeView(oldPrompt)

    activeGuidanceConstraintSet?.applyTo(layout)
  }

  private fun buildActiveGuidanceWithPromptConstraintSet(
    context: Context,
    prompt: View,
  ): ConstraintSet {
    return ConstraintSet().apply {
      clone(layout)

      val state =
        checkNotNull(activeGuidanceUiState) { "activeGuidanceUiState must be initialized" }

      clear(state.viewport.id)
      connect(state.viewport.id, ConstraintSet.START, ConstraintSet.PARENT_ID, ConstraintSet.START)
      connect(state.viewport.id, ConstraintSet.TOP, ConstraintSet.PARENT_ID, ConstraintSet.TOP)
      setMargin(state.viewport.id, ConstraintSet.TOP, dpToPx(headerNominalHeightDp(), context))
      connect(state.viewport.id, ConstraintSet.END, ConstraintSet.PARENT_ID, ConstraintSet.END)
      connect(state.viewport.id, ConstraintSet.BOTTOM, prompt.id, ConstraintSet.TOP)

      clear(state.googleLogo.id, ConstraintSet.BOTTOM)
      connect(state.googleLogo.id, ConstraintSet.BOTTOM, prompt.id, ConstraintSet.TOP)

      connect(prompt.id, ConstraintSet.START, ConstraintSet.PARENT_ID, ConstraintSet.START)
      connect(prompt.id, ConstraintSet.BOTTOM, ConstraintSet.PARENT_ID, ConstraintSet.BOTTOM)
    }
  }

  private fun removeFromParentView(view: View?) {
    if (view?.parent != null) {
      (view.parent as ViewGroup).removeView(view)
    }
  }

  private fun dpToPx(dp: Int, context: Context): Int {
    return TypedValue.applyDimension(
        TypedValue.COMPLEX_UNIT_DIP,
        dp.toFloat(),
        context.resources.displayMetrics,
      )
      .toInt()
  }
}

    

Java

/*
 * Copyright 2026 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.example.navigationapidemo.layoutdelegate;

import static android.view.ViewGroup.LayoutParams.MATCH_PARENT;
import static android.view.ViewGroup.LayoutParams.WRAP_CONTENT;
import static androidx.constraintlayout.widget.ConstraintLayout.LayoutParams.MATCH_CONSTRAINT;
import static com.google.android.libraries.navigation.layoutcustomization.NavigationUiButton.ButtonKnownType.COMPASS;

import android.content.Context;
import android.util.TypedValue;
import android.view.View;
import android.view.ViewGroup;
import android.view.ViewGroup.LayoutParams;
import androidx.constraintlayout.widget.ConstraintLayout;
import androidx.constraintlayout.widget.ConstraintSet;
import com.google.android.libraries.navigation.layoutcustomization.ActiveGuidanceUiState;
import com.google.android.libraries.navigation.layoutcustomization.AutoHidingVerticalLayout;
import com.google.android.libraries.navigation.layoutcustomization.NavigationLayoutDelegate;
import com.google.android.libraries.navigation.layoutcustomization.NavigationReadyUiState;
import com.google.android.libraries.navigation.layoutcustomization.NavigationUiButton;
import com.google.android.libraries.navigation.layoutcustomization.NavigationUiParent;
import com.google.android.libraries.navigation.layoutcustomization.StyleValues;

/**
 * A sample implementation of {@link NavigationLayoutDelegate} demonstrating a basic,
 * portrait-optimized layout using {@link ConstraintLayout}.
 *
 * <p><b>Understanding the Layout Delegate State Machine:</b> Navigation SDK transitions through
 * distinct states, each calling corresponding lifecycle methods on this delegate:
 *
 * <ul>
 *   <li><b>Navigation Ready:</b> Initiated by {@link #onEnterNavigationReady}. We initialize the
 *       layout here and add non-guidance views, then pass it to {@link NavigationUiParent} as the
 *       navigation layout.
 *   <li><b>Active Guidance (Turn-by-Turn Mode):</b> Initiated by {@link #onEnterActiveGuidance}. We
 *       set up the layout for Active Guidance, adding elements such as the turn card and ETA card.
 *   <li><b>Prompts:</b> Prompts (e.g., incident alerts) may be triggered during Active Guidance
 *       mode and can be added to the layout via {@link #onShowPrompt}.
 * </ul>
 *
 * This class caches its {@link ConstraintSet}s to ensure smooth transitions without needing to
 * recreate or inflate layouts continuously.
 */
public class StandardUiElementsLayoutDelegate extends NavigationLayoutDelegate {
  private final int layoutId;
  private final int buttonsContainerId;

  private ConstraintLayout layout;
  private AutoHidingVerticalLayout buttonsContainer;

  // We cache our ConstraintSet definitions to avoid cloning or rebuilding
  // constraint configurations programmatically on every transition. This optimization
  // keeps UI state switches (such as entering active guidance or popping up prompts) highly
  // performant.
  private ConstraintSet navigationReadyConstraintSet;
  private ConstraintSet activeGuidanceConstraintSet;
  private ConstraintSet activeGuidanceWithPromptConstraintSet;

  private ActiveGuidanceUiState activeGuidanceUiState;

  public StandardUiElementsLayoutDelegate() {
    layoutId = View.generateViewId();
    buttonsContainerId = View.generateViewId();
  }

  @Override
  public void onEnterNavigationReady(
      NavigationUiParent navigationUiParent, NavigationReadyUiState newState) {
    Context context = navigationUiParent.getViewContext();

    // Implementation Tip: For simplicity, this sample instantiates views and constraints
    // programmatically. In a production application, you can safely inflate standard XML
    // layout templates to build your layout hierarchies and define base UI constraints.

    // Create the root layout
    if (layout == null) {
      layout = new ConstraintLayout(context);
      LayoutParams layoutParams = new LayoutParams(MATCH_PARENT, MATCH_PARENT);
      layout.setLayoutParams(layoutParams);
      layout.setId(layoutId);
    }

    // Add the Viewport (REQUIRED):
    // The viewport is an invisible bounding box used by Nav SDK to frame the vehicle
    // chevron and the upcoming route line. We want to position this view such that it avoids
    // being obscured by fully-opaque UI elements (like the turn card or the ETA card).
    removeFromParentView(newState.getViewport());
    LayoutParams viewportLayoutParams = new LayoutParams(MATCH_PARENT, MATCH_PARENT);
    layout.addView(newState.getViewport(), viewportLayoutParams);

    // Add the Google Logo / Re-center Button (REQUIRED):
    // This view displays the Google logo during guidance and may transition into a
    // "Re-center" button if the user scrolls away from the vehicle chevron. It must
    // be added to the view hierarchy in all states.
    removeFromParentView(newState.getGoogleLogo());
    LayoutParams googleLogoLayoutParams = new LayoutParams(MATCH_PARENT, WRAP_CONTENT);
    layout.addView(newState.getGoogleLogo(), googleLogoLayoutParams);

    // Add the container for UI buttons
    if (buttonsContainer == null) {
      // We use AutoHidingVerticalLayout to create an adaptive vertical button container that
      // automatically hides or shows child views based on available screen height.
      buttonsContainer = new AutoHidingVerticalLayout(context);
      buttonsContainer.setId(buttonsContainerId);
    }
    removeFromParentView(buttonsContainer);
    LayoutParams buttonsContainerLayoutParams = new LayoutParams(WRAP_CONTENT, MATCH_CONSTRAINT);
    layout.addView(buttonsContainer, buttonsContainerLayoutParams);

    // Add UI buttons to the container
    for (NavigationUiButton button : newState.getNavigationReadyButtons()) {
      removeFromParentView(button.getView());
      buttonsContainer.addView(button.getView());
    }

    // Build constraint set for Navigation Ready state
    if (navigationReadyConstraintSet == null) {
      navigationReadyConstraintSet = buildNavigationReadyConstraintSet(newState);
    }

    // Apply the constraints
    navigationReadyConstraintSet.applyTo(layout);

    // Set the layout in NavigationUiParent
    navigationUiParent.removeNavigationLayout(layout);
    navigationUiParent.setNavigationLayout(layout);
  }

  private ConstraintSet buildNavigationReadyConstraintSet(NavigationReadyUiState uiState) {
    ConstraintSet constraintSet = new ConstraintSet();
    constraintSet.clone(layout);

    // Constrain viewport to the edges of its parent
    constraintSet.connect(
        uiState.getViewport().getId(),
        ConstraintSet.START,
        ConstraintSet.PARENT_ID,
        ConstraintSet.START);
    constraintSet.connect(
        uiState.getViewport().getId(),
        ConstraintSet.TOP,
        ConstraintSet.PARENT_ID,
        ConstraintSet.TOP);
    constraintSet.connect(
        uiState.getViewport().getId(),
        ConstraintSet.END,
        ConstraintSet.PARENT_ID,
        ConstraintSet.END);
    constraintSet.connect(
        uiState.getViewport().getId(),
        ConstraintSet.BOTTOM,
        ConstraintSet.PARENT_ID,
        ConstraintSet.BOTTOM);

    // Constrain the logo to the bottom start corner
    constraintSet.connect(
        uiState.getGoogleLogo().getId(),
        ConstraintSet.BOTTOM,
        ConstraintSet.PARENT_ID,
        ConstraintSet.BOTTOM);
    constraintSet.connect(
        uiState.getGoogleLogo().getId(),
        ConstraintSet.START,
        ConstraintSet.PARENT_ID,
        ConstraintSet.START);

    constrainButtonsToBottomEnd(constraintSet);

    return constraintSet;
  }

  @Override
  public void onLeaveNavigationReady(
      NavigationUiParent navigationUiParent, NavigationReadyUiState oldState) {
    buttonsContainer.removeAllViews();
    layout.removeAllViews();
    navigationUiParent.removeNavigationLayout(layout);
  }

  @Override
  public void onEnterActiveGuidance(
      NavigationUiParent navigationUiParent,
      NavigationReadyUiState oldState,
      ActiveGuidanceUiState newState) {
    activeGuidanceUiState = newState;

    Context context = navigationUiParent.getViewContext();

    // Sizing Guideline: The turn card and ETA card are internally configured to adapt and size
    // themselves dynamically based on the layout width (non-wideMode vs. wideMode). Forcing fixed
    // widths or heights on these elements via layouts is unsupported. Always use WRAP_CONTENT to
    // let the elements determine their optimal proportions.

    // Add the turn card
    removeFromParentView(newState.getTurnCard());
    LayoutParams turnCardLayoutParams = new LayoutParams(WRAP_CONTENT, WRAP_CONTENT);
    layout.addView(newState.getTurnCard(), turnCardLayoutParams);

    // Add the ETA card
    removeFromParentView(newState.getEtaCard());
    LayoutParams etaCardLayoutParams = new LayoutParams(WRAP_CONTENT, WRAP_CONTENT);
    layout.addView(newState.getEtaCard(), etaCardLayoutParams);

    // Remove the Navigation Ready UI buttons
    for (NavigationUiButton button : oldState.getNavigationReadyButtons()) {
      removeFromParentView(button.getView());
    }

    // By adding all buttons to the AutoHidingVerticalLayout, we can easily incorporate the latest
    // set of buttons when upgrading without any code changes required
    for (NavigationUiButton button : newState.getActiveGuidanceButtons()) {
      AutoHidingVerticalLayout.LayoutParams buttonLayoutParams =
          new AutoHidingVerticalLayout.LayoutParams(
              ViewGroup.LayoutParams.WRAP_CONTENT, ViewGroup.LayoutParams.WRAP_CONTENT);

      // Mark critical buttons (such as the compass) as high priority so they are the last to be
      // hidden by AutoHidingVerticalLayout when layout space is limited.
      if (button.getType() == COMPASS) {
        buttonLayoutParams.isHighPriority = true;
      }

      removeFromParentView(button.getView());
      buttonsContainer.addView(button.getView(), buttonLayoutParams);
    }

    // Build constraint set for Active Guidance state
    if (activeGuidanceConstraintSet == null) {
      activeGuidanceConstraintSet = buildActiveGuidanceConstraintSet(context, newState);
    }

    // Apply the constraints
    activeGuidanceConstraintSet.applyTo(layout);
  }

  @Override
  public void onLeaveActiveGuidance(
      NavigationUiParent navigationUiParent,
      ActiveGuidanceUiState oldState,
      NavigationReadyUiState newState) {

    // Remove Active Guidance UI elements
    removeFromParentView(oldState.getEtaCard());
    removeFromParentView(oldState.getTurnCard());
    buttonsContainer.removeAllViews();

    // Add Navigation Ready UI buttons
    for (NavigationUiButton button : newState.getNavigationReadyButtons()) {
      LayoutParams buttonLayoutParams = new LayoutParams(WRAP_CONTENT, WRAP_CONTENT);
      buttonsContainer.addView(button.getView(), buttonLayoutParams);
    }

    navigationReadyConstraintSet.applyTo(layout);
  }

  private ConstraintSet buildActiveGuidanceConstraintSet(
      Context context, ActiveGuidanceUiState uiState) {
    ConstraintSet constraintSet = new ConstraintSet();
    constraintSet.clone(layout);

    // Constrain turn card to top start corner
    constraintSet.connect(
        uiState.getTurnCard().getId(),
        ConstraintSet.TOP,
        ConstraintSet.PARENT_ID,
        ConstraintSet.TOP);
    constraintSet.connect(
        uiState.getTurnCard().getId(),
        ConstraintSet.START,
        ConstraintSet.PARENT_ID,
        ConstraintSet.START);

    // Constrain viewport to top of ETA card
    constraintSet.clear(uiState.getViewport().getId());
    constraintSet.connect(
        uiState.getViewport().getId(),
        ConstraintSet.START,
        ConstraintSet.PARENT_ID,
        ConstraintSet.START);
    constraintSet.connect(
        uiState.getViewport().getId(),
        ConstraintSet.TOP,
        ConstraintSet.PARENT_ID,
        ConstraintSet.TOP);

    // Instead of constraining the viewport's top directly to the bottom of the turn card
    // (which varies in height and would trigger jumpy camera framing updates), we use a fixed
    // nominal height to estimate the height of the turncard.
    constraintSet.setMargin(
        uiState.getViewport().getId(),
        ConstraintSet.TOP,
        dpToPx(StyleValues.headerNominalHeightDp(), context));

    constraintSet.connect(
        uiState.getViewport().getId(),
        ConstraintSet.END,
        ConstraintSet.PARENT_ID,
        ConstraintSet.END);
    constraintSet.connect(
        uiState.getViewport().getId(),
        ConstraintSet.BOTTOM,
        uiState.getEtaCard().getId(),
        ConstraintSet.TOP);

    constraintSet.clear(uiState.getGoogleLogo().getId(), ConstraintSet.BOTTOM);
    constrainLogoToTopOfEtaCard(uiState, constraintSet);

    constrainEtaCardToBottomStart(uiState, constraintSet);

    constrainButtonsToTopOfEtaCard(context, uiState, constraintSet);

    return constraintSet;
  }

  private static void constrainEtaCardToBottomStart(
      ActiveGuidanceUiState uiState, ConstraintSet constraintSet) {
    constraintSet.connect(
        uiState.getEtaCard().getId(),
        ConstraintSet.START,
        ConstraintSet.PARENT_ID,
        ConstraintSet.START);
    constraintSet.connect(
        uiState.getEtaCard().getId(),
        ConstraintSet.BOTTOM,
        ConstraintSet.PARENT_ID,
        ConstraintSet.BOTTOM);
  }

  private static void constrainLogoToTopOfEtaCard(
      ActiveGuidanceUiState uiState, ConstraintSet constraintSet) {
    constraintSet.connect(
        uiState.getGoogleLogo().getId(),
        ConstraintSet.BOTTOM,
        uiState.getEtaCard().getId(),
        ConstraintSet.TOP);
  }

  private void constrainButtonsToBottomEnd(ConstraintSet constraintSet) {
    constraintSet.clear(buttonsContainerId, ConstraintSet.BOTTOM);
    constraintSet.clear(buttonsContainerId, ConstraintSet.TOP);
    constraintSet.connect(
        buttonsContainerId, ConstraintSet.TOP, ConstraintSet.PARENT_ID, ConstraintSet.TOP);
    constraintSet.connect(
        buttonsContainerId, ConstraintSet.BOTTOM, ConstraintSet.PARENT_ID, ConstraintSet.BOTTOM);
    constraintSet.connect(
        buttonsContainerId, ConstraintSet.END, ConstraintSet.PARENT_ID, ConstraintSet.END);
  }

  private void constrainButtonsToTopOfEtaCard(
      Context context, ActiveGuidanceUiState uiState, ConstraintSet constraintSet) {
    constraintSet.clear(buttonsContainerId, ConstraintSet.BOTTOM);
    constraintSet.clear(buttonsContainerId, ConstraintSet.TOP);
    constraintSet.connect(
        buttonsContainerId, ConstraintSet.BOTTOM, uiState.getEtaCard().getId(), ConstraintSet.TOP);
    constraintSet.connect(
        buttonsContainerId, ConstraintSet.TOP, ConstraintSet.PARENT_ID, ConstraintSet.TOP);
    constraintSet.connect(
        buttonsContainerId, ConstraintSet.END, ConstraintSet.PARENT_ID, ConstraintSet.END);
    constraintSet.setMargin(
        buttonsContainerId,
        ConstraintSet.TOP,
        dpToPx(StyleValues.headerNominalHeightDp(), context));
  }

  @Override
  public void onShowPrompt(NavigationUiParent navigationUiParent, View newPrompt) {
    Context context = navigationUiParent.getViewContext();

    layout.addView(newPrompt);

    // When a prompt is displayed at the bottom of the screen, we update our active constraints so
    // that the invisible Viewport sits entirely above the prompt. This automatically forces the
    // Nav SDK camera to adjust its zoom and framing so that the route chevron is always visible to
    // the driver.
    activeGuidanceWithPromptConstraintSet =
        buildActiveGuidanceWithPromptConstraintSet(context, newPrompt);
    activeGuidanceWithPromptConstraintSet.applyTo(layout);
  }

  @Override
  public void onChangePrompt(
      NavigationUiParent navigationUiParent, View oldPrompt, View newPrompt) {
    Context context = navigationUiParent.getViewContext();

    activeGuidanceWithPromptConstraintSet.clear(oldPrompt.getId());

    layout.removeView(oldPrompt);
    layout.addView(newPrompt);

    // When a prompt is displayed at the bottom of the screen, we update our active constraints so
    // that the invisible Viewport sits entirely above the prompt. This automatically forces the
    // Nav SDK camera to adjust its zoom and framing so that the route chevron is always visible to
    // the driver.
    activeGuidanceWithPromptConstraintSet =
        buildActiveGuidanceWithPromptConstraintSet(context, newPrompt);
    activeGuidanceWithPromptConstraintSet.applyTo(layout);
  }

  @Override
  public void onHidePrompt(NavigationUiParent navigationUiParent, View oldPrompt) {
    activeGuidanceWithPromptConstraintSet.clear(oldPrompt.getId());

    layout.removeView(oldPrompt);

    activeGuidanceConstraintSet.applyTo(layout);
  }

  private ConstraintSet buildActiveGuidanceWithPromptConstraintSet(Context context, View prompt) {
    ConstraintSet constraintSet = new ConstraintSet();
    constraintSet.clone(layout);

    // Constrain viewport to top of prompt
    constraintSet.clear(activeGuidanceUiState.getViewport().getId());
    constraintSet.connect(
        activeGuidanceUiState.getViewport().getId(),
        ConstraintSet.START,
        ConstraintSet.PARENT_ID,
        ConstraintSet.START);
    constraintSet.connect(
        activeGuidanceUiState.getViewport().getId(),
        ConstraintSet.TOP,
        ConstraintSet.PARENT_ID,
        ConstraintSet.TOP);
    constraintSet.setMargin(
        activeGuidanceUiState.getViewport().getId(),
        ConstraintSet.TOP,
        dpToPx(StyleValues.headerNominalHeightDp(), context));
    constraintSet.connect(
        activeGuidanceUiState.getViewport().getId(),
        ConstraintSet.END,
        ConstraintSet.PARENT_ID,
        ConstraintSet.END);
    constraintSet.connect(
        activeGuidanceUiState.getViewport().getId(),
        ConstraintSet.BOTTOM,
        prompt.getId(),
        ConstraintSet.TOP);

    // Constrain prompt to bottom start corner
    constraintSet.connect(
        prompt.getId(), ConstraintSet.START, ConstraintSet.PARENT_ID, ConstraintSet.START);
    constraintSet.connect(
        prompt.getId(), ConstraintSet.BOTTOM, ConstraintSet.PARENT_ID, ConstraintSet.BOTTOM);

    return constraintSet;
  }

  private void removeFromParentView(View view) {
    if (view != null && view.getParent() != null) {
      ((ViewGroup) view.getParent()).removeView(view);
    }
  }

  private static int dpToPx(int dp, Context context) {
    return (int)
        TypedValue.applyDimension(
            TypedValue.COMPLEX_UNIT_DIP, dp, context.getResources().getDisplayMetrics());
  }
}