StackOverflow2013

Note that there are some explanatory texts on larger screens.

plurals

PO
text
Body
copied!<p>I have to work offline quite often (while travelling) and am quite experienced problem-solving with just the reference documentation; so it is possible! I'll start with a quick overview of the Android SDK Reference, and ease into some information about flags while preserving your chance (and hopefully tools) to solve your particular problem yourself.</p> <p>Most API reference documents, especially those generated using Javadoc-type tools, follow similar conventions; so once you're comfortable with Android's reference documentation, you should be able to translate other documentation as well.</p> <p>I recommend you <em>bookmark the package</em> index page (if you haven't already) of your reference documentation:</p> <ul> <li>http: // developer.android.com/reference/packages.html <em>-or-</em></li> <li>{your local "android-sdk" folder}/docs/reference/packages.html.</li> </ul> <p>On Windows, the full default path should be similar to:</p> <ul> <li>file:///C:/Program%20Files/Android/android-sdk/docs/reference/packages.html <em>-or-</em></li> <li>file:///C:/Program%20Files%20(x86)/Android/android-sdk/docs/reference/packages.html</li> </ul> <blockquote> <ul> <li><strong>Header Search Box</strong>: The search box in the upper right is great for searching the documentation.</li> <li>When <em>online</em>, a search for "flags" will result in all references throughout the documentation.</li> <li>When <em>offline</em>, the search box will only provide hints/links for form of package and class names; typing "intent" will offer "android.content.Intent", but you will find "flags" decidedly unhelpful.</li> </ul> </blockquote> <h1>Packages Index Page</h1> <p>On the left you'll find the Android Packages List with links to each package, while the body of the page lists the packages with a short introduction and link to each.</p> <h1>Package Pages</h1> <p>Clicking on a package (such as "android.content") will bring up a page summarizing the package and its contents, as well as populating the Package Contents List (beneath the Android Packages List) with the package's constituent interfaces, exceptions, and classes such as "Intent".</p> <h1>Class Pages</h1> <p><em>Example: Intent class</em></p> <ul> <li>http: // developer.android.com/reference/android/content/Intent.html</li> <li>android-sdk/docs/reference/android/content/Intent.html</li> </ul> <p>Clicking on a interface, exception, or class (such as "Intent") will bring up an extremely long page of information about it. At the top of each class page you'll find the Class Definition (aka Signature) followed by the Class Overview section which explains the object's purpose and implementation. There is also a list of jump links to the other sections of the page:</p> <blockquote> <p>Nested Classes | Constants | Inherited Constants | Fields | Ctors | Methods | Inherited Methods</p> </blockquote> <h1>Finding Useful References</h1> <p>If you don't know what you're looking for, I suppose you can start reading pretty much anywhere; but given a specific need, such as implementing flags, a basic knowledge of OOP will get you started. Since you want to learn how to add flags (actions are Methods) to a View (an Object,) looking at the Methods for a View is an excellent place to start your search, as is View's Class Overview section.</p> <p>I'll leave View for you to read later since you said you wanted to learn how to learn :)</p> <blockquote> <p><strong>Browser Search</strong>: Don't forget to make use of your browser's built-in search feature, often [CTRL]+[F] on windows. Searching for a term such as "flag" will allow us to quickly browse through all occurrences of it (217 of flag!) on the page, but you can quickly try a few related terms and phrases (the more precise the better) to get a more refined/reduced match set, then iterate through some. By quickly trying a few more terms, I was able to find what I wanted: "flags"(67), "add flag"(0), and "addflag"(6 matches - winner!)</p> </blockquote> <h1>Navigating a Class Page</h1> <p>Continuing to use the android.content.Intent class page as an example, clicking the jump link for Methods will quickly reveal <strong>addFlags()</strong>, and a bit of scrolling will reveal <strong>setFlags()</strong>. Both methods take a single <em>int</em> as their argument; however, the text refers to this single <em>int</em> using the plural name "flags" for good reason: you can squeeze quite a few flags into a single int, because each flag is stored as a specific bit! (I'll explain this a bit more below.)</p> <p>At the bottom of each method is a "see also" subsection that often contains usefully related links. Both the flag methods we found, addFlags() and setFlags(), reference each other in their "see also" section, and setFlags() also contains links to all of the relevant flag constants. These flag constants, each have a name beginning with "FLAG_" by convention. Here are the "Constants" entries for a couple commonly used intent flags:</p> <blockquote> <ul> <li><p>int FLAG_ACTIVITY_NEW_TASK If set, this activity will become the start of a new task on this history stack.</p></li> <li><p>int FLAG_ACTIVITY_CLEAR_TOP If set, and the activity being launched is already running in the current task, then instead of launching a new instance of that activity, all of the other activities on top of it will be closed and this Intent will be delivered to the (now on top) old activity as a new Intent.</p></li> </ul> </blockquote> <p>Clicking on the constants' names will jump us further down the page, to where each of these constants is explained in greater detail including listing their actual values in both base-10 (decimal) and base-16 (hex).</p> <p><em>Remember that Java uses a C-style prefix of '0x' to differentiate hexadecimal numbers, and that this prefix does not affect the value aside from identifying it's numeric base.</em></p> <blockquote> <ul> <li>FLAG_ACTIVITY_NEW_TASK shows a constant value of 268435456 (0x10000000).</li> <li>FLAG_ACTIVITY_SINGLE_TOP has a constant value of 536870912 (0x20000000).</li> </ul> </blockquote> <p>These numbers may seem random and arbitrary, but they aren't - each is actually a single switched-on bit in an otherwise zero byte, making our flags in base-2 (binary) seem more logical:</p> <blockquote> <ul> <li>00010000000000000000000000000000 and</li> <li>00100000000000000000000000000000.</li> </ul> </blockquote> <h1>How to Add and Set Flags in a bit-mask</h1> <p>To apply both to an intent, you can use either setFlags (discard pre-existing flags) or addFlags (keep all flags) like so:</p> <blockquote> <ul> <li>someExampleIntent.setFlags(FLAG_ACTIVITY_NEW_TASK | FLAG_ACTIVITY_SINGLE_TOP);</li> <li><em>Take special notice of the vertical bar, "|", between our flags; in Java it is the "bitwise-or" operator.</em></li> </ul> </blockquote> <p>Basically, the bitwise-or does a bit-by-bit comparison of the input int's that returns true(1) if any comparison bit is true, otherwise returning false(0). bitwise-or, Yea!</p> <p>So bitwise-or comparison of our bit-masks will yield:</p> <blockquote> <ul> <li>00010000000000000000000000000000 |</li> <li>00100000000000000000000000000000 =</li> <li>00110000000000000000000000000000</li> </ul> </blockquote> <p>Be careful to <strong>never use addition (+) with bit-masks</strong>! It's perfect for creating intermittent bugs; it will yield the same result as bitwise-or when merging two numbers.. (hold for the exception - literally): </p> <blockquote> <ul> <li>00010000000000000000000000000000 +</li> <li>00100000000000000000000000000000 =</li> <li>00110000000000000000000000000000 (same result as bitwise-or)</li> </ul> </blockquote> <p>..<strong>EXCEPT</strong> if the masks you add have any set bits in common, such as adding FLAG_ACTIVITY_SINGLE_TOP to a bit-mask that already contains it- then we get pictures of crying kittens or some-such nonsense:</p> <blockquote> <ul> <li>00110000000000000000000000000000 +</li> <li>00100000000000000000000000000000 =</li> <li>01010000000000000000000000000000 /!\ Oops.</li> </ul> <p>Accidentally removed FLAG_ACTIVITY_SINGLE_TOP and accidentally added FLAG_ACTIVITY_NO_HISTORY; <em>two errors for the price of one keystroke!</em></p> </blockquote> <p><strong>Please, do the right thing(tm) and use '|' (not '+') for merging bit-masks.</strong></p> <p>Here's a simple Java example of <a href="http://snipt.org/vgxg5" rel="noreferrer">bitwise-or</a> and the pitfalls of using addition on them.</p> <p>Just found an excellent explanation of <a href="http://softwareblog.alcedo.com/post/2011/05/31/Using-e2809core2809d-to-combine-A-and-B-Explaining-that-bitmask-thing.aspx" rel="noreferrer">bit-masks</a>, too.</p>

Querying!

Guidance

An individual column

Larger individual text columns get their own page to allow for proper reading.

SQuiL has stopped working due to an internal error.

If you are curious you may find further information in the browser console, which is accessible through the devtools (F12).

Reload