Skip to main content

Route Bookmarks

|

This guide explains how to store, manage, and retrieve route collections as bookmarks between application sessions.

Create a bookmarks collection​

Create a new bookmarks collection using the RouteBookmarks::produce method with a unique name:

auto bookmarks = RouteBookmarks::produce("my_trips");

If a collection with the same name exists, it opens the existing collection.

Access the file path using the getFilePath getter:

String path = bookmarks->getFilePath();

Add routes​

Add a route to the collection using the add method. Provide a unique name and waypoints list. Optionally include route preferences and specify whether to overwrite existing routes.

bookmarks->add(
    "Home to Office",
    { homeLandmark, officeLandmark },
    myPreferences,
    false
    );

Parameters:

  • name - Unique route name
  • waypoints - List of landmarks defining the route
  • preferences - Optional route preferences
  • overwrite - Replace existing route with same name (default: false)
info

If a route with the same name exists and overwrite is false, the operation fails.

Import routes from files​

Import multiple routes from a file using addTrips. Returns the number of imported routes or error::KInvalidInput on failure.

int count = bookmarks->addTrips("/path/to/bookmarks_file");
if (count == error::KInvalidInput){
    GEM_INFO_LOG("Invalid file path provided for import.");
} else {
    GEM_INFO_LOG("%d trips imported successfully.", count);
}

Export routes to files​

Export a specific route to a file using exportToFile with the route index and destination path.

auto result = bookmarks->exportToFile(0, "/path/to/exported_route");
GEM_INFO_LOG("Export completed with result: %d", result);

Return values:

  • KNoError - Export successful
  • error::KNotFound - Route does not exist
  • error::KIo - File cannot be created

Access route details​

Get the number of routes in the collection using the size property:

int count = bookmarks->size();

Get details of a specific route by index:

auto name = bookmarks->getName(0);
auto waypoints = bookmarks->getWaypoints(0);
auto prefs = bookmarks->getPreferences(0);
auto timestamp = bookmarks->getTimestamp(0);
info

Methods return default if the index is out of bounds or data is unavailable. The getTimestamp method returns when the route was added or modified.

Find the index of a route by name using the find method:

int index = bookmarks->find("Home to Office");
if (index >= 0) {
    GEM_INFO_LOG("Route found at index %d", index);
} else {
    GEM_INFO_LOG("Error finding route: %d", index);
}

Return values:

  • Route index if found (positive value)
  • error::KNotFound if not found

Sort bookmarks​

Change the sort order using the setSortOrder method:

Available sort orders:

  • ERouteBookmarksSortOrder::RBSO_SortByDate (default) - Most recent first
  • ERouteBookmarksSortOrder::RBSO_SortByName - Alphabetical order

Configure auto-delete mode​

Enable or disable auto-delete mode using the setAutoDeleteMode method. When enabled, the bookmarks database is deleted when the object is destroyed.

Update routes​

Update an existing route using the update method with the route index and new details:

bookmarks->update(
    0,
    "New Name",
    { newStart, newEnd },
    newPrefs
);
info

The update method only modifies provided fields, leaving others unchanged.

Remove routes​

Remove a route by index using the remove method:

bookmarks->remove(0);

Clear all routes from the collection using the clear method:

bookmarks->clear();
Last updated on