I agree totally with what Tim wrote. Lots of deficiencies and undocumented things. I just spent 2 days trying to figure out why my ItemizedOverlay subclass was not rendering OverlayItems that had their own marker. Finally found something that mentioned setting the bounds of the marker. Totally undocumented. They could at least provide their source code so we could figure this stuff out ourselves.
Also, on a similar topic (poor documentation) I've been trying to figure out how to get a MapView zoom controls to stay visible and not disappear after a few seconds. Seems like you have to call this undocumented method: mapView.getZoomButtonsController() and then call setVisible(true) on that object : mapView.getZoomButtonsController ().setVisible(true); Of course for some weird reason the user still has to touch the map once before the zoom controls appear. -Paul On Nov 3, 5:20 pm, Tim Hutt <tdh...@gmail.com> wrote: > Hi, this has been noted by many people previously, but I thought I'd > have a little rant about it. Simply put, the Android SDK documentation > is shockingly incomplete. I can't believe Google doesn't have the > resources to employ someone full-time to work on it. Here are just a > few examples: > > 1. You need to call ItemizedOverlay.populate() even if you have added > no items. This is mentioned no-where, and I've even seen people create > crazy work-arounds because they didn't know it. > > 2. populate() isn't explained at all well. Let's compare a few > function descriptions with what *I* would write: > > ItemizedOverlay intro, current version: > > "A base class for an Overlay which consists of a list of OverlayItems. > This handles sorting north-to-south for drawing, creating span bounds, > drawing a marker for each point, and maintaining a focused item. It > also matches screen-taps to items, and dispatches Focus-change events > to an optional listener. " > > My version: > > "ItemizedOverlay is an Overlay that allows you to easily draw small > collections of [OverlayItem]s on top of the map. Typically the items > will be some kind of pin or marker. A default [Drawable] to use can be > passed to the constructor, and individual [OverlayItem]s can have > specific [Drawable]s. This class handles sorting the items > north-to-south so that the overlap as expected, and drawing a marker > for each point. It also maintains a focused item, matches screen-taps > to items, and dispatches Focus-change events to an optional listener. > Typically it is subclassed and used as described below. See the > documentation for populate() and createItem() for further information > on how to specify the [OverlayItem]s. <then I would give an example of > deriving a simple class from ItemizedOverlay, but I'm not paid to > write this so meh>" > > ItemizedOverlay.populate(), current version: > > "Utility method to perform all processing on a new ItemizedOverlay. > Subclasses provide Items through the createItem(int) method. The > subclass should call this as soon as it has data [note that this is > *wrong*!], before anything else gets called." > > My version: > > "ItemizedOverlay maintains an internal cache of [OverlayItem]s in > order to draw them efficiently. This function must be called in order > to populate the internal cache. Note that it must be called before the > draw() method is even if you have added no items. When it is called it > first uses ItemizedOverlay.size() to determine how many [OverlayItem]s > there are to draw. You must override this method in your subclass. > Once the number of items has been determined it calls > ItemizedOverlay.createItem(int i) for i=0 to size() in order to > retrieve each [OverlayItem]. These items are then sorted from north to > south to facilitate drawing. Whenever you change the items to be drawn > you must call populate() in order to update the cache." > > Actually I've just noted that that description isn't quite true and > has caused a bug in my program - size() is apparently only ever called > once. This is pretty stupid but hey, my point stands. > > 3. At http://developmentality.net/there is a note about how setMarker() > doesn't work unless you set the bounds on the drawable. > This should clearly be mentioned in the documentation. > 4. fill_parent, wrap_content, gravity and so on aren't adequately > explained *at all*. > 5. Not a documentation issue, but boundCenterBottom() should be really > be public. > 6. I strongly encourage you to look at the documentatio for > ProgressDialog. It is truly > shocking:http://developer.android.com/reference/android/app/ProgressDialog.htm...() > > I know there are a lot of classes, but *really*. > > 7. There are so many classes where the documentation is the type that > I would write *to myself* as I was writing the code. e.g. Bundle is > described as "A mapping from String values to various Parcelable > types.". That's it. Helpful. > > This mailing list is clearly too high volume for anyone from Google to > read, but I feel better for having ranted. Back me up here people. > > :-) -- You received this message because you are subscribed to the Google Groups "Android Developers" group. To post to this group, send email to android-developers@googlegroups.com To unsubscribe from this group, send email to android-developers+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/android-developers?hl=en
