How do I create a help overlay like you see in a few Android apps and ICS?

Let's assume you ordinarily would call setContentView(R.layout.main), but on first run, you want to have this overlay.

Step #1: Create a FrameLayout in Java code and pass that to setContentView().

Step #2: Use LayoutInflater to inflate R.layout.main into the FrameLayout.

Step #3: Use LayoutInflater to inflate the overlay into the FrameLayout.

Step #4: When the user taps the button (or whatever) to dismiss the overlay, call removeView() to remove the overlay from the FrameLayout.

Since the overlay is a later child of the FrameLayout, it will float over top of the contents of R.layout.main.

"Coach mark" is "Help overlay" in UX talk :-)

coach_mark.xml is your coach mark layout

coach_mark_master_view is the id of the top most view (root) in coach_mark.xml

public void onCoachMark(){

    final Dialog dialog = new Dialog(this);
    dialog.requestWindowFeature(Window.FEATURE_NO_TITLE);
    dialog.getWindow().setBackgroundDrawable(new ColorDrawable(android.graphics.Color.TRANSPARENT));
    dialog.setContentView(R.layout.coach_mark);
    dialog.setCanceledOnTouchOutside(true);
    //for dismissing anywhere you touch
    View masterView = dialog.findViewById(R.id.coach_mark_master_view);
    masterView.setOnClickListener(new View.OnClickListener() {
        @Override
        public void onClick(View view) {
            dialog.dismiss();
        }
    });
    dialog.show();
}

Adding sample of coach_mark.xml (to this excellent solution given by Oded Breiner), so its easy for ppl to copy & paste to see working example quickly.

Sample of coach_mark.xml here, change the -> drawable/coach_marks to your image:

coach_mark.xml

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="vertical"
    android:id="@+id/coach_mark_master_view">
    <RelativeLayout
        android:layout_width="match_parent"
        android:layout_height="match_parent" >
         <ImageView
             android:id="@+id/coach_marks_image"
             android:layout_width="match_parent"
             android:layout_height="match_parent"
             android:layout_centerInParent="true"
             android:layout_gravity="center_horizontal"
             android:src="@drawable/coach_marks" />
    </RelativeLayout>
</LinearLayout>

And optionally use this theme to remove padding:

<style name="WalkthroughTheme" parent="Theme.AppCompat">
    <item name="android:windowIsTranslucent">true</item>
    <item name="android:windowBackground">@android:color/transparent</item>
    <item name="android:windowContentOverlay">@null</item>
    <item name="android:windowNoTitle">true</item>
    <item name="android:backgroundDimEnabled">false</item>
</style>

You can do that pretty quickly. You add, for exemple a LinearLayout where you put a picture with alpha which correspond to your help information and what do you want to draw like an overlay. In you xml of your activity you put this layout in a RelativeLayout after the layout of your activity with the Gone visibility. When you want to draw the help information, you just neeed to set this visibility to visible.

I hope, I'm clear, if you have any question,I'm be please to answer them.

See my another answer how programmatically show an overlay layout on top of the current activity. Activity's layout.xml does not need to know anything about the overlay skin. You can put overlay semi-transparent, cover only part of the screen, one or more textview and buttons on it... How to overlay a button programmically?

• create res/layout/paused.xml RelativeLayout template or use any layout toplevel
• create a function to show overlay skin
• key is to get handle to layout.xml, use LayoutInflater class to parse xml to view object, add overlay view to current layout structure
• My example uses a timer to destroy overlay object by completely removing it from the view structure. This is probably what you want as well to get rid of it without a trace.

My goal was that main activities are not aware of any overlay skin, overlays come and go, many different overlays, still able to use overlay1.xml text files as a template, and content should programmatically be updated. I do pretty much what CommonsWare told us my post shows the actual program code to get started.

disclaimer: OPs "Thanks for your input. This is how I pictured it being done. I have to give credit to the answer below" comment does not mean my answer but CommonsWare answer. Stackoverflow have changed post orderings.