I’m trying to use this flag SYSTEM_UI_FLAG_LOW_PROFILE on a view. My problem goes deeper than that though. My real problem is that I’m really bad at navigating the documentation to find out how to actually implement this. I find myself in this predicament a lot. Can anyone tell me how to learn how to set a flag, but by using the documentation and not looking for someone to post some sample code for me to “steal”? Let’s say all I had was eclipse and all of the downloaded android documentation, and I didn’t know how to set this, how could I learn? This is more of a “learning to program” type of question, but a genuine question nonetheless and I hope someone can help me out.
The best I can comeup with from reading the documentation:
setContentView(R.layout.start);
setSystemUiVisibility(SYSTEM_UI_FLAG_LOW_PROFILE):
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.
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.
I recommend you bookmark the package index page (if you haven’t already) of your reference documentation:
On Windows, the full default path should be similar to:
Packages Index Page
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.
Package Pages
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".
Class Pages
Example: Intent class
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:
Finding Useful References
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.
I’ll leave View for you to read later since you said you wanted to learn how to learn 🙂
Navigating a Class Page
Continuing to use the android.content.Intent class page as an example, clicking the jump link for Methods will quickly reveal addFlags(), and a bit of scrolling will reveal setFlags(). Both methods take a single int as their argument; however, the text refers to this single int 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.)
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:
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).
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.
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:
How to Add and Set Flags in a bit-mask
To apply both to an intent, you can use either setFlags (discard pre-existing flags) or addFlags (keep all flags) like so:
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!
So bitwise-or comparison of our bit-masks will yield:
Be careful to never use addition (+) with bit-masks! 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):
..EXCEPT 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:
Please, do the right thing(tm) and use ‘|’ (not ‘+’) for merging bit-masks.
Here’s a simple Java example of bitwise-or and the pitfalls of using addition on them.
Just found an excellent explanation of bit-masks, too.