|
deCarta Android API Documentation - Copyright | |||||||||
| PREV NEXT | FRAMES NO FRAMES | |||||||||
See:
Description
deCarta Android Mapping API
deCarta confidential and proprietary.
Copyright deCarta. All rights reserved.
The deCarta Android API provides a framework for rapid development of Android based mapping applications. This framework provides modular fluid maps, panning, zooming, geocoding, routing, search, pin overlays, with infowindows.
We ask that you participate in the forum on the deCarta Developer Zone (developer.decarta.com) to report bugs and share ideas. Use the links on the left frame of this page to see javadocs for the Java public objects.
All of the examples below, plus a lot more, can be found in the example package. Please use this source to help jump start your development
In order to use this API you must be a registered user on the deCarta Developer Zone (developer.decarta.com). When you register you receive a clientName and clientPassword for authenticating on our web services. You must configure the API with these values in: CONFIG.java.
NOTE: The API will not work until your configure these values before initialize MapViewCONFIG.clientName="YOUR_CLIENT_NAME"; CONFIG.clientPassword="YOUR_CLIENT_PASSWORD"; CONFIG.host="YOUR_HOST"; CONFIG.configuration="YOUR_CONFIGURATION"; CONFIG.transparentConfiguration="YOUR_TRANSPARENT_CONFIGURATION";CONFIG.java also holds many other configurable items.You can configure the use of OPENGL/Canvas for the rendering of the map
/** * DRAW_BY_OPENGL sets whether to use OpenGL (or Canvas) * for the rendering of the map view */ CONFIG.DRAW_BY_OPENGL=true;You can configure a variety of other options for the internals of the API. The default values are the optimal setting for performance based on our testing.
/** TILE_SIZE sets tile image size default is 256 */ CONFIG.TILE_SIZE=256; /** TILE_THREAD_COUNT for tile network thread pool default 5 */ CONFIG.TILE_THREAD_COUNT=5; /** * CACHE_SIZE for storing tiles default 5000. */ CONFIG.CACHE_SIZE=5000;
The most basic building block of any location application is a map. The Map object provides this basic functionality. To create the simplest of Maps you need only to follow the example below. To cause the Map object to display content to the user, we call the centerOnPosition. This brings up a map display centered on the supplied Position object (aka. Latitude and Longitude coordinate).
By default a basic draggable map is created. To maneuver around the map, simply click and hold on your map and then move around. This will fluidly pan the map in whatever direction you drag.
private MapView mMapView; private ZoomControls mZoom; private LinearLayout mZoomView; public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); CONFIG.clientName="YOUR_CLIENT_NAME"; CONFIG.clientPassword="YOUR_CLIENT_PASSWORD"; CONFIG.host="YOUR_HOST"; CONFIG.configuration="YOUR_CONFIGURATION"; Position pos = new Position(37.781841,-122.417564); // get zoom view mZoomView = (LinearLayout) findViewById(R.id.zoomview); // get map view mMapView = (MapView) findViewById(R.id.mapview); mZoom = mMapView.getZoomControls(); // add zoom controller to zoom view mZoomView.addView(mZoom); try { mMapView.centerOnPosition(pos); } catch (APIException e) { // handle exception e.printStackTrace(); } }This is the referenced layout for the zoom controls<LinearLayout android:id="@+id/zoomview" android:layout_width="wrap_content" android:layout_height="wrap_content" android:layout_alignParentRight="true"/>This is the referenced layout for the map view<com.decarta.android.map.MapView android:id="@+id/mapview" android:layout_width="fill_parent" android:layout_height="fill_parent" />
For many reasons, mainly performance, the underlying geospatial engine requires information in latitude and longitude coordinates. But, human beings don't think in terms of latitude and longitude. You've most likely never heard someone say, "Hey Bob, meet me at 37.1232, -121.43566 for a beer at 5 o'clock." Instead, human beings reference locations by address. Geocoding is the act of taking an address (example: "4 N Second St., San Jose, CA 95113") and translating it into a pair of coordinates on a map.
When working with user input, we always need to use a Geocoder. Many times a user will put in an incomplete address, misspell a street name, or might only have a partial address available to input. Example: The distance between 2000 N. Main St., Anytowne USA and 2000 S. Main St., Anytowne USA might be miles; providing an address of 2000 Main St., Anytowne USA, without the directional before the street name, has a chance of inconveniently misplacing a user. As you can see, to assume your users will correctly enter addresses is not wise.
The Geocoder object has a method geocode that takes a FreeFormAddress type. The API returns a List of GeocodeResponse's. By using the Geocoder object, you'll be able to let the user choose the best match for vague inputs.
public void doGeocoding(final Address address){ final Context context=this; final ProgressDialog loadingDialog = ProgressDialog.show(context, null, "geocoding for '"+address+"'", true); new Thread(){ @Override public void run() { try{ Geocoder geocoder=new Geocoder(); geocoder.setReturnFreeFormAddress(false); ArrayList<GeocodeResponse> results=geocoder.geocode(address); loadingDialog.dismiss(); Intent intent = new Intent(ReferenceAppActivity.this, GeocodeResultActivity.class); intent.putExtra(ReferenceAppActivity.this.getPackageName()+".geocode_response_list",(Serializable)results); ReferenceAppActivity.this.startActivityForResult(intent,GEOCODE_LIST_ACTIVITY_CODE); }catch(Exception e){ e.printStackTrace(); AppUtil.alert(e.getMessage(), ReferenceAppActivity.this,"WARNING"); }finally{ if(loadingDialog!=null && loadingDialog.isShowing()){ loadingDialog.dismiss(); } } } }.start(); }
Besides visualizing locations, maps are essential to finding your way from one point to another. Using the Geocoder object to translate user input addresses into Positions, the waypoints, or stop off points, along a path.
Prior to generating a route, configure the routing engine with the RoutePreference object. The RoutePreference object determines what routing style and ultimately affects the path and turn-by-turn directions. Finding the fastest route is the default. A shortest distance route, one that might not necessarily be the fastest, could also be generated. A route suitable for pedestrian travel could also be generated, along with many other types of routes.
public void doRoute(final ArrayList<RouteAddress> routeAddrs, final RoutePreference prefs){ final Context context=this; final ProgressDialog loadingDialog = ProgressDialog.show(context, null, "routing", true); new Thread(){ @Override public void run() { try{ mMapView.removeShapesByName("ROUTE"); mMapView.deleteOverlaysByName("ROUTE_PIN"); viewHandler.sendEmptyMessage(LIST_BUTTON_HIDE); mListButton.setOnClickListener(null); RouteQuery routeQuery=new RouteQuery(); ArrayList<Position> positions=new ArrayList<Position>(); for(int i=0;i<routeAddrs.size();i++){ positions.add(routeAddrs.get(i).getPosition()); } Route route=routeQuery.query(positions,prefs); if(route!=null){ mMapView.getMapPreference().setRouteId(route.getRouteId()); Polyline routeLine=new Polyline(route.getRouteGeometry(),"ROUTE"); mMapView.addShape(routeLine); ItemizedOverlay overlay=new ItemizedOverlay("ROUTE_PIN"); Options ops=new Options(); ops.inScaled=false; Bitmap startBm=BitmapFactory.decodeResource(getResources(), R.drawable.ic_red_circle_a, ops); Icon startIc=new Icon(startBm, new XYInteger(startBm.getWidth(),startBm.getHeight()), new XYInteger(startBm.getWidth()/2,startBm.getHeight())); Bitmap endBm=BitmapFactory.decodeResource(getResources(), R.drawable.ic_red_circle_b, ops); Icon endIc=new Icon(endBm, new XYInteger(endBm.getWidth(),endBm.getHeight()), new XYInteger(endBm.getWidth()/2,endBm.getHeight())); overlay.addOverlayItem(new OverlayItem(routeAddrs.get(0).getPosition(),startIc,"", new RotationTilt(RotateReference.SCREEN,TiltReference.SCREEN) )); overlay.addOverlayItem(new OverlayItem(routeAddrs.get(routeAddrs.size()-1).getPosition(),endIc,"", new RotationTilt(RotateReference.SCREEN,TiltReference.SCREEN))); mMapView.addOverlay(overlay); final ArrayList<RouteInstruction> routeInstrucs=route.getRouteInstructions(); final String routeSummary=route.getSummary(); invokeRouteInstrucActivity(routeInstrucs,routeSummary, routeAddrs); mListButton.setOnClickListener(new OnClickListener(){ @Override public void onClick(View v) { // TODO Auto-generated method stub invokeRouteInstrucActivity(routeInstrucs,routeSummary,routeAddrs); return; } }); //mMapView.refreshMap(); } }catch(Exception e){ e.printStackTrace(); Activity activity=ReferenceAppActivity.this; AppUtil.alert(e.getMessage(), activity,"WARNING"); }finally{ if(loadingDialog!=null && loadingDialog.isShowing()){ loadingDialog.dismiss(); } } } }.start(); }
The POIQuery object can be used to search for POIs (Points of Interest) that are hosted on the deCarta server. By default the search hits the database named: You can either search by business name (queryType = POIName) or category (queryType = CATEGORY). If you are search by category, here are some of the common categories supported by our default database:
ATM | Bar,Nightlife | Attraction | Cinema | Coffee | Hotel | Museum | Petrol | Restaurant | Shopping | Theater | Transportpublic void doSearch(String searchTerm, String searchType, final boolean corridorSearch){ final String searchTermL=searchTerm; final String searchTypeL=searchType; final Context context=this; final ProgressDialog loadingDialog = ProgressDialog.show(context, null, "searching for '"+searchTermL+"'", true, true,new OnCancelListener() { @Override public void onCancel(DialogInterface dialog) { // TODO Auto-generated method stub } }); new Thread(){ @Override public void run() { try{ double radius=Math.max(mMapView.getRadiusY(),mMapView.getRadiusX()); POISearchCriteria crit = new POISearchCriteria(); crit.centerPosition=mMapView.getCenterPosition(); crit.radius=radius; crit.queryString=searchTermL; crit.queryType=searchTypeL; crit.rankCriteria="Score"; crit.sortCriteria="Distance"; crit.sortDirection="Ascending"; if(searchTypeL.equals("CATEGORY")){ crit.rankCriteria=null; } if(corridorSearch){ crit.routeId=mMapView.getMapPreference().getRouteId(); if(crit.routeId==null || crit.routeId.equals("")){ AppUtil.alert("No route available", ReferenceAppActivity.this,"WARNING"); return; } } if(AppConfig.search_db_name!=null && !AppConfig.search_db_name.equals("")){ crit.database=AppConfig.search_db_name; } ArrayList<POI> pois=POIQuery.query(crit); if(!loadingDialog.isShowing()){ return; } loadingDialog.dismiss(); //add pins mMapView.deleteOverlaysByName("SEARCH_PIN"); mMapView.getInfoWindow().setVisible(false); ItemizedOverlay overlay=new ItemizedOverlay("SEARCH_PIN"); Options ops=new Options(); ops.inScaled=false; Bitmap bm; if(searchTypeL.equals("CATEGORY")){ String pinIconName = searchTermL.toLowerCase()+"_pin"; int resource = getResources().getIdentifier(pinIconName, "drawable", getPackageName()); bm=BitmapFactory.decodeResource(getResources(), resource, ops); } else { bm=BitmapFactory.decodeResource(getResources(), R.drawable.basic_pin, ops); } Icon icon=new Icon(bm, new XYInteger(bm.getWidth(),bm.getHeight()), new XYInteger(bm.getWidth()/2,bm.getHeight())); for(int i=0;i<pois.size();i++){ POI poi=pois.get(i); RotationTilt rt=new RotationTilt(RotateReference.SCREEN,TiltReference.SCREEN); //RotationTilt rt=new RotationTilt(RotateReference.MAP,TiltReference.MAP); //rt.setRotation(30); //rt.setTilt(45); OverlayItem overlayItem=new OverlayItem(poi.getPosition(),icon,poi.getName(),rt); overlayItem.addEventListener(EventType.TOUCH, new OverlayItem.TouchEventListener() { @Override public void onTouchEvent(EventSource eventSource) { OverlayItem overlayItem=(OverlayItem) eventSource; mMapView.getInfoWindow().setAssociatedOverlayItem(overlayItem); mMapView.getInfoWindow().setMessage(overlayItem.getMessage()); try{ mMapView.getInfoWindow().setPosition(overlayItem.getPosition()); }catch(Exception e){ e.printStackTrace(); } mMapView.getInfoWindow().setOffset(new XYFloat(0f,(float)(overlayItem.getIcon().getOffset().y)), overlayItem.getRotationTilt()); mMapView.getInfoWindow().setVisible(true); } }); overlayItem.setPoi(poi); overlay.addOverlayItem(overlayItem); } mMapView.addOverlay(overlay); mMapView.refreshMap(); }catch(Exception e){ e.printStackTrace(); AppUtil.alert(e.getMessage(), ReferenceAppActivity.this,"WARNING"); }finally{ if(loadingDialog!=null && loadingDialog.isShowing()){ loadingDialog.dismiss(); } } } }.start(); }
|
deCarta Android API Documentation - Copyright | |||||||||
| PREV NEXT | FRAMES NO FRAMES | |||||||||