CircleImageView README

The project's README from github.com/hdodenhof/CircleImageView. As one markdown file: README.md.

CircleImageView

A fast circular ImageView perfect for profile images. This is based on RoundedImageView from Vince Mi which itself is based on techniques recommended by Romain Guy.

CircleImageView

It uses a BitmapShader and does not:

create a copy of the original bitmap
use a clipPath (which is neither hardware accelerated nor anti-aliased)
use setXfermode to clip the bitmap (which means drawing twice to the canvas)

As this is just a custom ImageView and not a custom Drawable or a combination of both, it can be used with all kinds of drawables, i.e. a PicassoDrawable from Picasso or other non-standard drawables (needs some testing though).

Gradle

dependencies {
    ...
    implementation 'de.hdodenhof:circleimageview:3.1.0'
}

Usage

<de.hdodenhof.circleimageview.CircleImageView
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:id="@+id/profile_image"
    android:layout_width="96dp"
    android:layout_height="96dp"
    android:src="@drawable/profile"
    app:civ_border_width="2dp"
    app:civ_border_color="#FF000000"/>

Limitations

The ScaleType is always CENTER_CROP and you'll get an exception if you try to change it. This is (currently) by design as it's perfectly fine for profile images.
Enabling adjustViewBounds is not supported as this requires an unsupported ScaleType
If you use an image loading library like Picasso or Glide, you need to disable their fade animations to avoid messed up images. For Picasso use the noFade() option, for Glide use dontAnimate(). If you want to keep the fadeIn animation, you have to fetch the image into a Target and apply a custom animation yourself when receiving the Bitmap.
Using a TransitionDrawable with CircleImageView doesn't work properly and leads to messed up images.

FAQ

How can I use a VectorDrawable with CircleImageView?

Short answer: you shouldn't. Using a VectorDrawable with CircleImageView is very inefficient. You should modify your vectors to be in a circular shape and use them with a regular ImageView instead.

Why doesn't CircleImageView extend AppCompatImageView?

Extending AppCompatImageView would require adding a runtime dependency for the support library without any real benefit.

How can I add a selector (e.g. ripple effect) bound to a circle?

There's currently no direct support for a circle bound selector but you can follow these steps to implement it yourself.

How can I add a gap between image and border?

Adding a gap is also not supported directly but there's a workaround.

Changelog

3.1.0
- Align bitmap paint flags with BitmapDrawable (improves scaling)
3.0.2
- Fix NPE during initialization on API level <= 19
- Fix wrong outline being provided if circular transformation is disabled
3.0.1
- Fix touch event not fired if view is empty
- Fix touchable area limited to a circle even if transformation is disabled
3.0.0
- Limit touch event handling to circle area
- Migrate to AndroidX
- Remove deprecated properties and methods
2.2.0
- Add support for elevation
- Add circle background color attribute to replace fill color
2.1.0
- Add support for padding
- Add option to disable circular transformation
- Fix hairline gap being drawn between image and border under some conditions
- Fix NPE when using tint attribute (which is not supported)
- Deprecate fill color as it seems to cause quite some confusion
2.0.0
- BREAKING: Custom xml attributes are now prefixed with "civ_"
- Graceful handling of incompatible drawables
- Add support for a fill color shown behind images with transparent areas
- Fix dimension calculation issues with small images
- Fix bitmap not being cleared when set to null
1.3.0
- Add setBorderColorResource(int resId)
- Add resource type annotations
- Add border_overlay attribute to allow drawing border on top of the base image
1.2.2
- Add ColorFilter support
1.2.1
- Fix ColorDrawables not being rendered properly on Lollipop
1.2.0
- Add support for setImageURI(Uri uri)
- Fix view not being initialized when using CircleImageView(Context context)
1.1.1
- Fix border being shown although border width is set to 0
1.1.0
- Add support for ColorDrawables
- Add getters and setters for border color and border width
1.0.1
- Prevent crash due to OutOfMemoryError
1.0.0
- Initial release

License

Copyright 2014 - 2020 Henning Dodenhof

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Searching Database…

14.5K ·GitHub

CircleImageView

What is this?

CircleImageView is a fast circular ImageView for Android, made for profile images. It's a custom View you drop into your layouts in place of the standard ImageView.

How is it different from a regular ImageView?

It renders the image as a circle with a BitmapShader — no bitmap copy, no clipPath, no double-drawing via setXfermode — so it stays fast. Being a custom ImageView, it accepts any drawable, including Picasso's.

How do I add it to my project?

Add the Gradle dependency from the README's Gradle section to your app's build.gradle. Version 3.x is based on AndroidX, so use it in an AndroidX project.

Does it pull in any extra libraries?

No — the author intentionally doesn't extend AppCompatImageView, which would add a runtime dependency on the support library for no real benefit.

Can I change the ScaleType or use adjustViewBounds?

No. The ScaleType is always CENTER_CROP and changing it throws an exception, and adjustViewBounds isn't supported — by design, since it's aimed at profile images.

What can I customize on the circle?

Border color and width, a circle background color, padding, and elevation. Its XML attributes are all prefixed with 'civ', like civ_border_width.

Does it respond to taps outside the circle?

No — since 3.0.0, touch event handling is limited to the circle area, so touches outside the round image don't hit the view.

Can I use VectorDrawables with it?

You shouldn't — rendering vectors through it is very inefficient. The README recommends reshaping your vectors into a circular form and showing them in a regular ImageView.

Is upgrading from 2.x to 3.x painless?

Mostly, but 3.0.0 migrated the library to AndroidX and removed all deprecated properties and methods, so update your imports and any deprecated calls when you switch.

What are similar projects?

SlidingMenu, flexbox-layout, material-components-android, QMUI_Android, AndroidSwipeLayout, ViewPagerIndicator, SmartRefreshLayout, Android-Universal-Image-Loader

Which topics is it in?

xml, widget, android-library, image, mobile-development, ui-components, java, mobile, ui, performance, android, gui

Creator: hdodenhof
Size: 1 MB
Stars: 14.5K
Updated: CommitJan 10
Age: 12y
Commits · 90 Days