BGABanner-Android: An AndroidX ViewPager Banner and Guide Library

What BGABanner-Android Solves, and Who It Is For

The library targets two screens that Android developers rebuild constantly: the first-run guide carousel and the promotional banner strip. Both are ViewPager jobs, and both need the same extras: an indicator, optional auto-play, and a click callback that does not fire twice. BGABanner-Android packages those extras into one custom view so a project does not hand-roll them.

The README lists the feature set: guide-screen navigation, dynamic page counts from server data, infinite looping auto-play that pauses while a finger is down and resumes on release, custom indicator and caption positions, image and numeric indicators, ViewPager transition animations, selecting a specific page, item click listeners, a placeholder drawable for network loading, and multiple ViewPagers that scroll together.

The audience is narrow on purpose. This is a Java library for classic View-based Android apps, and the README states it has migrated to AndroidX with minSdk 21. If your UI is Jetpack Compose, or your carousel must react to scroll position rather than page position, the view is the wrong shape for the job. It is for teams that want a guide page or banner finished today without writing a pager adapter and an indicator from scratch.

How the Pager, Indicator and Adapter Fit Together

BGABanner is a custom view that owns a ViewPager plus an indicator container and a caption area. You never touch the pager directly. You hand the banner a data source, and it builds the adapter internally and drives the indicator from the current page.

The README documents three ways to supply that data. The first takes a list of models plus a BGABanner.Adapter, which the README says suits network images and infinite looping with fewer than three pages. The second takes a List<View> for fully custom guide layouts. The third takes a BGALocalImageSize plus drawable resource ids for image-only guide pages.

Auto-play, the transition effect, indicator placement and caption styling are all XML attributes on the view, not Java calls. The declare-styleable block in the README lists them: banner_pointAutoPlayAble, banner_pointAutoPlayInterval, banner_pageChangeDuration, banner_indicatorGravity, banner_transitionEffect, banner_isNumberIndicator, banner_isNeedShowIndicatorOnOnlyOnePage, banner_contentBottomMargin and banner_aspectRatio. That split is deliberate. Layout-time concerns stay in XML, and only the data and the click delegate go through code.

The design has one consequence worth naming: because the adapter is built for you, per-item view recycling is fixed. The fillBannerItem callback in the Adapter interface is where your image loader does its work, and the README's example calls Glide there with placeholder and error drawables. If you need conditional view types inside the pager, this abstraction is in the way.

Installing BGABanner-Android from Maven Central

The README gives one dependency line. It uses the literal placeholder latestVersion, so the README does not pin a version and you have to choose one from Maven Central yourself.

implementation 'cn.bingoogolapple:bga-banner:latestVersion'

The README states the library has migrated to AndroidX with minSdk 21, and that the consuming project must enable AndroidX:

android.useAndroidX=true

With the dependency in place, add the view to a layout. This snippet is the README's example, with the hollow point drawable and the alpha transition:

<cn.bingoogolapple.bgabanner.BGABanner
    android:id="@+id/banner_guide_content"
    style="@style/MatchMatch"
    app:banner_pageChangeDuration="1000"
    app:banner_pointAutoPlayAble="false"
    app:banner_pointContainerBackground="@android:color/transparent"
    app:banner_pointDrawable="@drawable/bga_banner_selector_point_hollow"
    app:banner_pointTopBottomMargin="15dp"
    app:banner_transitionEffect="alpha" />

Now give it data. The README's first pattern pairs an Adapter with a model list, and that is the one to copy for network images:

mContentBanner.setAdapter(new BGABanner.Adapter<ImageView, String>() {
    @Override
    public void fillBannerItem(BGABanner banner, ImageView itemView, String model, int position) {
        Glide.with(MainActivity.this)
                .load(model)
                .placeholder(R.drawable.holder)
                .error(R.drawable.holder)
                .centerCrop()
                .dontAnimate()
                .into(itemView);
    }
});

mContentBanner.setData(Arrays.asList("网络图片路径1", "网络图片路径2", "网络图片路径3"), Arrays.asList("提示文字1", "提示文字2", "提示文字3"));

After that call the banner shows three pages and three captions. For a guide screen, wire the enter and skip buttons. The README notes that if one of the two ids does not exist you pass 0, and that the library handles both the double-click guard and the show/hide logic for those buttons:

mContentBanner.setEnterSkipViewIdAndDelegate(R.id.btn_guide_enter, R.id.tv_guide_skip, new BGABanner.GuideDelegate() {
    @Override
    public void onClickEnterOrSkip() {
        startActivity(new Intent(GuideActivity.this, MainActivity.class));
        finish();
    }
});

One practical note from the README: the demo module carries working examples, including FrescoDemoActivity for Fresco image loading and for a custom item layout. When the snippet above does not match your image stack, that file is the reference, not the README prose.

Where BGABanner-Android Stops Being the Right Tool

The library is bound to ViewPager. Every feature in the README, including the thirteen transition effects, is a ViewPager page transformer or an equivalent. Anything that needs a RecyclerView-backed carousel with diffing, or a Compose pager, is outside what this view can do, and no adapter hook in the README changes that.

Documentation is the second limit. The README is the manual: a feature list, three data-source patterns, one attribute reference and a pointer to the demo. There is no API reference beyond that, no changelog in the README, and no published releases. The README also does not document rollback or version pinning, so if a version you pick misbehaves you are reading the source in library/ rather than a migration guide. There is a 实现原理.md file at the repository root, but it is not linked from the README's table of contents and its contents are not reproduced there.

Licensing is the third thing to check. The README's badge points at Apache 2.0, but the repository metadata does not carry a licence field, and the README's License section was truncated before its text. Treat the badge as a claim to verify against the LICENSE file in the repository before you ship.

Finally, the maintenance signal is mixed. The last push was on 2026-07-27, which is recent, and the repository is not archived. But the repository has no published releases, and the README still says latestVersion rather than a number. Recent commits are not the same as a release cadence, and nothing here shows one.

BGABanner-Android Versus a Plain ViewPager with a Page Transformer

The honest alternative is not another library. It is a ViewPager2 or ViewPager plus a page transformer and a hand-written indicator, which is what BGABanner-Android itself is. The difference is where the work sits.

With a plain pager you write the adapter, the indicator drawable selector, the auto-play handler with its pause-on-touch logic, and the double-click guard on item clicks. That is a few hundred lines you own and can debug. With BGABanner-Android those pieces arrive configured through XML attributes such as banner_pointAutoPlayAble, banner_pointAutoPlayInterval and banner_indicatorGravity, and the README states the double-click guard is handled inside the view.

The trade is control against surface area. A hand-rolled pager takes any adapter you like, including multiple view types and DiffUtil. BGABanner-Android takes the three data-source shapes in the README and no others. On the other side, the thirteen transition effects, the numeric indicator mode and the placeholder drawable are already written and named; replicating that set by hand is real work for a screen you will look at once.

There is a middle option the README itself implies: use BGABanner for the guide screen, where the enter and skip wiring and the indicator are the annoying parts, and keep a plain pager anywhere the adapter needs to be yours.

Maintenance, Upgrade Cost and Licence

Upgrade cost is low in code and higher in verification. The public surface is small: setAdapter, setData in three overloads, setDelegate, setEnterSkipViewIdAndDelegate, and the XML attributes. A version bump therefore rarely breaks call sites. What it can break is layout, because indicator spacing and caption placement are attribute-driven and the README does not promise that defaults stay put across versions.

The absence of retrieved releases matters here. Without release notes you cannot diff behaviour between versions, so the safe upgrade path is to pin an explicit version instead of following the README's latestVersion placeholder, then run the demo module against your own image loader. The demo is part of the repository, and the README points at FrescoDemoActivity for both Fresco and custom item layouts, which makes it the closest thing to a compatibility test that ships with the project.

On licence, the README badge links to the Apache 2.0 text, but the repository metadata has no licence field and the README's License section is truncated. Apache 2.0 is permissive and generally safe for closed-source apps, but that is a statement about the licence text, not about this repository's actual file. Check the LICENSE file before you rely on it; I am not giving legal advice, and the repository does not confirm the file exists.

One more cost: the library is Java and predates Kotlin-first tooling. There is no Kotlin API in the README, so Kotlin callers use the same Java interfaces, including the anonymous Adapter and Delegate classes.

Reading the Demo Before You Read the README Again

The README's "使用" section lists three data-source patterns and says more initialization approaches are in the demo. That sentence is the most useful line in the document, because the three patterns do not cover every case. The View-collection pattern covers custom guide layouts, the local-image-size pattern covers image-only guides, and the adapter pattern covers network images and loops with fewer than three pages. Custom item layouts are explicitly deferred to FrescoDemoActivity.

If your banner needs a layout the three patterns do not describe, the demo module under demo/src/main/java/cn/bingoogolapple/bgabanner/demo is where the answer lives. The README's FAQ section makes the same two referrals: Fresco loading and custom item layout both point at FrescoDemoActivity. That is a thin FAQ, but it is honest about where the working code is.

The repository root also holds 实现原理.md, which the README does not link. If you want to understand why infinite looping behaves as it does, that file is the place to look before filing anything as a bug. Nothing in the README explains the looping mechanism, so the source and that file are your only references.

Editorial conclusion

Adopt BGABanner-Android when the screen really is a ViewPager: a splash guide with enter and skip buttons, or an ad strip that loops. Skip it for scroll-linked carousels, Compose screens, or any project that needs maintained API documentation, because the README is the whole manual and the repository has no published releases. Before you commit, open the demo module, check the banner_transitionEffect value you want against the declare-styleable list, and confirm the library's ViewPager dependency resolves against your AndroidX setup.

Frequently asked questions

Official sources

1. bingoogolapple/BGABanner-Android on GitHub
2. Issues
3. README