CWAC Layouts: Custom Containers, Concisely Coded

This project has a handful of Android containers (ViewGroup implementations) designed to handle specific scenarios:

• AspectLockedFrameLayout that resizes itself, and its children, to fit within a specific aspect ratio

• MirroringFrameLayout and an associated Mirror that duplicates and scales the contents of the MirroringFrameLayout onto the Mirror

This Android library project is available as a JAR or as an artifact for use with Gradle. To use that, add the following blocks to your build.gradle file:

repositories {
    maven {
        url "https://s3.amazonaws.com/repo.commonsware.com"
    }
}

dependencies {
    implementation 'com.commonsware.cwac:layouts:0.4.5'
}

Or, if you cannot use SSL, use http://repo.commonsware.com for the repository URL.

NOTE: The JAR name, as of v0.4.1, has a cwac- prefix, to help distinguish it from other JARs.

Usage: AspectLockedFrameLayout

AspectLockedFrameLayout inherits from FrameLayout, and so you start by setting it up much like you would any other FrameLayout. In fact, if you do nothing else, it behaves the same as a regular FrameLayout.

However, if you call setAspectRatio() (supplying a double of the aspect ratio you want) or setAspectRatioSource() (supplying a View whose aspect ratio should be matched), then AspectLockedFrameLayout will reduce its height or width to maintain the requested aspect ratio. This affects the children of the AspectLockedFrameLayout as well, of course.

Since the AspectLockedFrameLayout effectively overrides and reduces its size, you can use android:layout_gravity to position the shrunken AspectLockedFrameLayout within its parent:

<FrameLayout
	android:layout_width="match_parent"
	android:layout_height="match_parent">

	<com.commonsware.cwac.layouts.AspectLockedFrameLayout
		android:id="@+id/source"
		android:layout_width="match_parent"
		android:layout_height="match_parent"
		android:layout_gravity="center">

		<!-- children go here -->
	</com.commonsware.cwac.layouts.AspectLockedFrameLayout>
</FrameLayout>

Note that the resizing only takes place when the AspectLockedFrameLayout is measured. If you change the aspect ratio, call requestLayout() on the AspectLockedFrameLayout (or any parent container) to get it to resize.

NOTE: ConstraintLayout also offers aspect ratio control, so you might consider using it if it better fits your needs.

Usage: Mirroing

The mirror classes are specifically designed for use with Android's Presentation class, specifically for actual presentations. In a presentation, the presenter needs to be able to see and control some widgets, but the audience simply needs to see the widgets via a projector or other external display. MirroringFrameLayout, used as a container around the control widgets, will clone its output onto the Mirror View, which in turn can be hosted by a Presentation.

To mirror a widget or widget hierarchy, wrap it in a com.commonsware.cwac.layouts.MirroringFrameLayout:

<com.commonsware.cwac.layouts.MirroringFrameLayout
	android:id="@+id/source"
	android:layout_width="1000px"
	android:layout_height="0dp"
	android:layout_weight="1"
	android:background="#88FF0000">

	<WebView
	android:id="@+id/webkit"
	android:layout_width="match_parent"
	android:layout_height="match_parent"/>

</com.commonsware.cwac.layouts.MirroringFrameLayout>

Also add a com.commonsware.cwac.layouts.Mirror widget where you want the duplicate contents to be rendered.

Then, in your Java code, attach the Mirror to the MirroringFrameLayout:

MirroringFrameLayout source=
    (MirroringFrameLayout)findViewById(R.id.source);
Mirror target=(Mirror)findViewById(R.id.target);

source.setMirror(target);

And that's it.

This should work for all widgets except SurfaceView and TextureView, plus things derived from them (e.g., VideoView, Maps V2 MapView).

Note that MirroringFrameLayout inherits from AspectLockedFrameLayout and sets its aspect ratio to match that of the Mirror. This ensures that the Mirror will be filled without some type of anamorphic stretching.

You are welcome to implement the MirrorSink interface on something and use that as the destination for the mirroring, rather than use a Mirror.

JavaDocs

An API reference, in the form of JavaDocs, is available online.

Dependencies

This project has no dependencies and should work on most versions of Android, though it is only being tested on API Level 8+.

Version

This is version v0.4.5 of this module, meaning it is coming along nicely.

Demo

In the demo/ sub-project you will find a SimpleMirrorActivity activity and a WebMirrorActivity that each demonstrates the use of MirroringFrameLayout and Mirror.

Additional Documentation

The Busy Coder's Guide to Android Development contains a chapter on custom views that covers the classes from this library, how to use them, and how they work.

License

The code in this project is licensed under the Apache Software License 2.0, per the terms of the included LICENSE file.

Questions

If you have questions regarding the use of this code, please post a question on StackOverflow tagged with commonsware-cwac and android after searching to see if there already is an answer. Be sure to indicate what CWAC module you are having issues with, and be sure to include source code and stack traces if you are encountering crashes.

If you have encountered what is clearly a bug, or if you have a feature request, please post an issue. The contribution guidelines provide some suggestions for how to create a bug report that will get the problem fixed the fastest.

You are also welcome to join the CommonsWare Community and post questions and ideas to the CWAC category.

Do not ask for help via social media.

Also, if you plan on hacking on the code with an eye for contributing something back, please read the contribution guidelines.

Release Notes

• v0.4.5: updated build instructions, added null check for bitmap in MirroringFrameLayout
• v0.4.4: updated build instructions, removed some unnecessary casts
• v0.4.3: reorganized code into Android Studio standard structured, added JavaDocs
• v0.4.2: updated for Android Studio 1.0 and new AAR publishing system
• v0.4.1: updated Gradle, fixed manifest for merging, added cwac- prefix to JAR
• v0.4.0: switched to ViewTreeObserver for more reliable updating; added MirrorSink
• v0.3.0: migrated to support Gradle and publish an AAR artifact
• v0.2.2: improved efficiency and resiliency to source/mirror issues
• v0.2.1: fixed AspectLockedFrameLayout to handle zero height/width better
• v0.2.0: added AspectLockedFrameLayout and used for MirroringFrameLayout
• v0.1.0: initial release

Who Made This?