===================[ Layouts ]===================

Layouts are a special kind of View that contain other Views and know
how to calculate their positions on the screen (more precisely, in the
Window rectangle that an Activity gets from the WindowManager). 

Layout classes are derived from ViewGroup, which is derived from
View. This should give you an idea that Layouts can contain other
layouts, in a nested fashion. This is indeed the case. 

Read:
  https://developer.android.com/guide/topics/ui/declaring-layout.html

There are many ways to achieve the same geometric effects with Layouts.
For example, to place some Views such as TextViews, TextEedits, Buttons,
etc., in several rows and columns, you may employ a TableLayout or 
the newer GridLayout (simple examples here: 
http://www.techotopia.com/index.php/Understanding_Android_Views,_View_Groups_and_Layouts,
http://www.techotopia.com/index.php/Working_with_the_Android_GridLayout_in_XML_Layout_Resources)
or create a LinearLayout with   android:orientation="vertical"   
and nest several LinearLayouts with  android:orientation="horizontal"
inside it (we've seen this approach used in the MyRuns app layout
that we extracted from its APK in class; see below).

RelativeLayout expresses another useful idea about positioning
Views: it allows you to specify how they align with each other.
For example, you can specify that some View must lie above another,
below it, to the left of another, centered vertically in its parent, 
or aligned against its parent's margin of choice (respectively, 
   android:layout_above="@id/another"
   android:layout_below="@id/another"
   android:layout_toLeftOf="@id/another"
   android:layout_centerVertical = "true"
   android:layout_alignParentRight="true").
See 
   https://developer.android.com/guide/topics/ui/layout/relative.html

Android SDK developers keep introducing new, more flexible layouts.
The newer layouts include ConstraintLayout (now the default in the
HelloWorld code that the Studio generates for every new project)
and CoordinatorLayout, which supports floating buttons and fancy
animated action bars. 

===================[ ConstraintLayout ]===================

I found these links very useful to understand ConstraintLayout: 
  https://medium.com/exploring-android/exploring-the-new-android-constraintlayout-eed37fe8d8f1
  http://www.techotopia.com/index.php/Working_with_ConstraintLayout_Chains_and_Ratios_in_Android_Studio
  https://medium.com/@loutry/guide-to-constraintlayout-407cd87bc013

(Note that "match_parent" should not be used in ConstraintLayout at
   all. Negative margins are not supported (which is confusing).  
   Also, it took me forever to figure out that, to respond
   correctly to the weights property, height or width of elements in
   the chain must be set to 0dp *and* chain style must be _spread*_,
   not _packed_!  The Studio doesn't warn you if you mix-and-match
   properties that don't work in ConstraintLayout; so read the
   www.techotopia.com guide above carefully. I actually bought their
   ~$20 e-book after finding they had _the only_ clear and detailed
   explanation of constraint chains, at the URL above.)
 
==================[ CoordinatorLayout ]==================

(You can skip this for now, until you are confident with
 other layouts and feel the need for fancier behaviors
 like the collapsing toolbar, swipe gestures, etc.)

I found this is a good intro: 
  http://www.androidauthority.com/using-coordinatorlayout-android-apps-703720/

An example of adding a fancy behavior: 
  https://lab.getbase.com/introduction-to-coordinator-layout-on-android/
 
This has both examples and technical details:
  http://saulmm.github.io/mastering-coordinator

Finally, this will help you experiment with Behaviors:
  https://medium.com/google-developers/intercepting-everything-with-coordinatorlayout-behaviors-8c6adc140c26

To understand how Android layouts work algorithmically, read 
  https://developer.android.com/guide/topics/ui/how-android-draws.html

==================[ Extracting and analyzing layouts from APKs ]==================

When learning layouts, it helps to look at how other people's apps
are laid out, and pick up their tricks. Layouts and other XML 
are stored inside the APK, but in a pre-processed binary format 
(for efficiency). The inflaters (see below) can only consume this
format, not plain XML.

So APKtool extracts this format. In class, I ran

  java -jar apktool_2.2.4.jar d MyRuns-Android-chk1.apk 

and obtained its activity_main.xml.

Compare the screenshot of the app's screen in apktool-example/MyRuns1-screenshot.png
and this layout. In it, you can see that the main activity's entire
collection of views is wrapped in a <ScrollView ..>, then uses a LinearLayout
with android:orientation="vertical" to arrange the elements. Inside that
layout, you see first a TextView that holds the label retrieved from
"@string/ui_profile_photo" in res/values/strings.xml, i.e.,

   <string name="ui_profile_photo">Profile Photo:</string>

and then another LinearLayout, this time horizontal, to align the ImageView
and the Button side-by-side instead of vertically. Notice where else
this trick is used in this layout.

Developer Guide encourages reducing the number of layouts for drawing
efficiency. So think about how you could redo the same layout with
a single RelativeLayout instead of nested linear ones.

You will find the full results of disassembly in apktool-example/ ;
read https://ibotpeaches.github.io/Apktool/ documentation to interpret
them.

==================[ UI without XML layouts ]==================

It's important to know that you can create layouts and views entirely
from Java, without any XML ("programmatically" or "dynamically").
Look at the examples/NoXmlLayout/ code to see how. Observe that
this project has no  activity_main.xml  layout file!

In particular, note that the line "setContentView(R.layout.activity_main);",
which normally retrieves the (pre-processed) XML layout by its ID
and displays it is commented out. Instead, you manually create all the Views
you need such as a Button in this example, and attach them to the Window
or to the specific parent views where you want them to go. Instead
of specifying the desired height, width, and alignment (gravity) as
XML properties of the <Button ..> element, you set them as properties
of the newly created Button object. Note that width and height parameters
must be wrapped in a LayoutParams object, and these are Java constants
of this class instead of XML strings. 

You must also manually attach the new Button with either addContentView(..)
when adding to the main content view of the app, or with parent.addView(..)
when adding to some parent Layout or ViewGroup. 

You can see how much effort XML saves you.

   @Override protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        // setContentView(R.layout.activity_main);

        Button button = new Button (this);
        LayoutParams params = new LayoutParams(
                LayoutParams.WRAP_CONTENT, LayoutParams.WRAP_CONTENT);
        params.topMargin = 8;
        params.gravity = Gravity.TOP | Gravity.CENTER_HORIZONTAL;

        button.setText("dynamic Button");

        getWindow().addContentView(button, params);

What if you want to dynamically add an View that is specified in XML,
like the second Button?

setContentView(..) automatically created all the View objects in the
main layout tree and attached them to each other. Now you have to do
both of these steps manually.

The key concept here is _inflating_. This is what creates a Java View
object from XML. Inflating is done by a special Inflater object, which
acts as a loader and creator of Views. You must feed it
(pre-processed) XML by ID, together with the ViewGroup or Layout
object into which you want to inflate it, then collect the created
View and add it to the desired parent.

        LayoutInflater inflater =
                (LayoutInflater)getSystemService(Context.LAYOUT_INFLATER_SERVICE);
        View inflated = inflater.inflate(R.layout.button, vg, /* try both vg and null */
					 false);
        vg.addView(inflated); // You can save this step by specifying "true" above

With XML layouts, setContentView(..) calls the inflater for you for all the objects,
and takes care of adding them, too.

Note that the second button gets attached in the middle of the action bar
in my example. It's not the most natural thing to do, but why not?

Note that you also need to attach the OnClickListener to the button if you
want it to be clickable. This is the code that gets called behind the scenes
when you specify an  android:onClick  attribute in XML.

------------------[ Internals of layout inflation ]------------------

(You may skip this at a first reading.)

If you are curious what this Android internals code looks like:

setContentView() for Activity is defined here, but it merely calls
to setContentView() in the Activity's Window, obtained by getWindow():
https://github.com/android/platform_frameworks_base/blob/master/core/java/android/app/Activity.java 

Next you look at the Window.java code,

but that class is an abstact class that has no method implementations,
only declarations. So what class do you actually get?

To see this, insert some logging statements into onCreate(..):

     Log.d( "WINDOW", getWindow().toString() );

LogCat prints:
               D/WINDOW: com.android.internal.policy.PhoneWindow@c439a5f
So you get an  com.android.internal.policy.PhoneWindow . Looking in PhoneWindow.java

   https://github.com/android/platform_frameworks_base/blob/master/core/java/com/android/internal/policy/PhoneWindow.java

you'll see that setContentView(..) is indeed overridden there, and calls

     mLayoutInflater.inflate(layoutResID, mContentParent);

To get that inflator, add more logging,

     Log.d( "WINDOW", getWindow().getLayoutInflater().toString() );

and see that it's a PhoneLayoutInflater:
               D/WINDOW: com.android.internal.policy.PhoneLayoutInflater@64bdcac

Next you locate the PhoneLayoutInflater.java,

  https://github.com/android/platform_frameworks_base/blob/master/core/java/com/android/internal/policy/PhoneLayoutInflater.java

but that class does not define inflate(). It inherits it from
LayoutInflater, which it extends.  Finally, you look up
LayoutInflater.java,

https://github.com/android/platform_frameworks_base/blob/master/core/java/android/view/LayoutInflater.java

and see a bunch of inflate() methods, which parse XML and then descend
the parsed XML tree recursively (see rInflateChildren(..)). You can also
see a number of error conditions, such as trying to attach a node
that has been already attached. 

Isn't open source great? :)

==================[ Margins, Padding, Gravity ]==================

Margins and padding:
https://stackoverflow.com/questions/21959050/android-beginner-difference-between-padding-and-margin

Gravity:
https://thinkandroid.wordpress.com/2010/01/14/how-to-position-views-properly-in-layouts/
http://sandipchitale.blogspot.co.uk/2010/05/linearlayout-gravity-and-layoutgravity.html
  (skip to the picture, it's worth a thousand words)

Note that gravity doesn't quite work as you might expect in LinearLayout:
say, in a horizontal LinearLayout,  android:layout_gravity="right" or "left"
on its children will be ignored. Note the difference between gravity (specified
on the parent, affecting placement of parent's entire content) and 
layout_gravity (specified on children, affecting their placement inside the 
parent, with respect to parent's boundaries). 

==================[ The Dialog example ]==================

In class, I showed an example of an Activity that calls what looks
like a sign-in dialog box with a username and a password. The calling
activity gets grayed out for the duration of this dialog.

The code for this is in examples/Dialog/ .

There are two ways to achieve this behavior. One is to create an
Activity, much like the Greeter's Edit activity, with a layout that
has no surprises (see activity_auth.xml). Specifying a special style
in the Manifest (not in the activity's layout itself!) makes it look
like a dialog instead of taking full screen:

     <activity android:name=".AuthActivity"
            android:theme="@android:style/Theme.Holo.Dialog.NoActionBar" />

Everything else about this activity's flow should be familiar from the
Greeter: startActivityForResult(..), finish() in it, onActivityResult(..)
to pick up the entered data.

This activity in my example implements some behaviors in response to
typing, text changes in TextEdit boxes, and focus received and lost by
a EditText. These behaviors are standard for modern UIs. See below.

The other way uses Fragments, a feature introduced in Android 3.0 SDK.
In it, you extent a DialogFragment base class, and then build up
an AlertDialog, and pass data between it and the main activity via
interfaces that the main activity implements. We will discuss this
new method in class on Friday.

Fragments can be tricky, and some major Android development shops like
Square actually made a decision to stop using them
(https://medium.com/square-corner-blog/advocating-against-android-fragments-81fd0b462c97).
Still, they are an important part of the Android ecosystem, and you
will need to understand them, if only to read others' code.

==================[ Events: text changes, key presses, focus ]==================

The game here is finding and implementing the right listeners (really,
glorified callback lambda functions; Kotlins' native support for
lambdas makes the code a lot less verbose that Java).

In order to have an Activity react to text changes in a TextEdit, implement a
TextWatcher and attach it to the TextEdit (say, te):

   te.addTextChangedListener(new TextWatcher() { .. } );

on that TextEdit. Explore the three kinds of callbacks in a TextWatcher
by logging their calls and arguments. This code also shows how to disable
(and gray-out) a Button, and how to re-enable it once some text has been
entered.

To react to a particular key pressed, implement

   te.setOnKeyListener(new View.OnKeyListener() {
            public boolean onKey(..)
	    //...
	 });

There are many kinds of events that this listener can catch, so
make sure to filter for the right one before acting (see code).

Finally, to react to focus changes, implement

   te.setOnFocusChangeListener(new View.OnFocusChangeListener() {
            @Override
            public void onFocusChange(..)
	    //...
       });

This event will fire when a TAB keypress or a click would take the
user away from entering text in the box. Note that the user can then
return to entering text by clicking in the box or tabbing back to it.
Add logging to see when this kind of event fires.

With these examples, you will be able to implement most of the require
functionality in Lab1. See documentation for the TextEdit in the
Android Reference for more events you can catch (e.g., OnTouch).