원형 진행 바 라이브러리, dinuscxj님의 CircleProgressBar 사용하기

---

오늘은 dinuscxj님이 제작하신 CircleProgressBar라는 라이브러리에 대해서 알아보는 시간을 가지도록 하겠습니다. 이 라이브러리는 라이브러리가 올려진 GitHub에 자세히 설명이 되어 있지 않아 직접 제가 사용해보면서 안 내용 등을 적어서 올려야 할 것 같습니다. 코드는 대부분 Kotlin을 기준으로 작성되었으나, Java로 프로그래밍하시는 분들도 볼 때 큰 무리가 없을 것이라고 판단됩니다. 질문은 댓글로 부탁드립니다. 공감도 부탁드려요!

---

사용 준비하기

이 라이브러리는 어디에다 사용하나요?

저는 역시 현재 개발 중인 블로그 플래너에서 목표 대비 현재 진행 상황을 원형 진행 바 (프로그래스 바)로 나타내기 위해서 사용하고 있습니다. 이와 같이 전체 기준 대비 어떤 것의 비율을 원형의 모양으로 나타낼 때 이 라이브러리를 사용하면 좋습니다. 또한 둥근 모서리나, 처음과 끝의 색깔도 다르게 할 수 있으니 심미적으로도 괜찮은 라이브러리라고 생각합니다. 

---

라이브러리에서 제공하는 컴포넌트

라이브러리에서 제공하는 컴포넌트는 오직 하나, CircleProgressBar입니다. 대신 여기 속성값들이 정말 많습니다. 레이아웃 xml 파일에서 이 객체를 삽입하는 방법은 간단합니다. 

---

본격적으로 사용하기에 앞서

프로젝트에 라이브러리 불러오기

build.gradle (app) 파일에 다음과 같은 구문을 추가합니다.

dependencies {
    implementation 'com.dinuscxj:circleprogressbar:1.3.0'
}

---

레이아웃에 추가하기

<com.dinuscxj.progressbar.CircleProgressBar
        android:id="@+id/days_graph"
        android:layout_width="400dp"
        android:layout_height="400dp"/>

삽입은 간단하게 하고, 이제 이 그래프에 대한 속성을 알아보도록 하겠습니다.

---

CircleProgressBar의 속성들 (Attributes)

속성들에 대한 이미지들은 여러분의 편의를 위해 배경을 검정색으로 설정하였고, 처음 색은 빨강색, 마지막 색은 파랑색으로 설정하였습니다.

app:style

line, solid, solid_line 순

 

"line"은 말 그대로 선들이 표시도는 퍼센트만큼 둘러싸고 있습니다. 

"solid"는 하나의 원이, 표시해야 하는 퍼센트만큼 갈라져 있습니다. 중심 기준으로이죠.

"solid_line"은 원의 테두리가 그 퍼센트만큼 둘러싸고 있습니다.

---

app:progress_text_

progress_text 관련 속성은 그래프 중간의 "70%"를 꾸미는 속성입니다.

progress_text_size는 "70%"의 글자 크기로, sp 단위의 크기를 입력하면 됩니다.

progress_text_color는 "70%"의 글자 색상입니다. 현재는 파란색을 지정해 두었습니다.

---

app:progress_

이 문단에서는 전체적으로 프로그래스 그래프에 관해서 속성을 지정하는 것들의 모임입니다.

이 속성은 progress_stroke_width로, line_width랑 헷갈릴 수 있는데, style이 "solid_line"일 때 모습입니다. 프로그래스 선의 두께를 결정하는 속성으로, 현재는 20dp로 지정해 두었습니다.

이 속성은 progress_start_degree로, 왼쪽 위부터 순서대로 0, 90, 180, 270순입니다. 이 속성을 표기하지 않으면 기본값이 270 = -90으로 들어가는 것 같습니다. 보통 통상적으로 -90도가 가장 안정적인 각도로 보이네요. 

이 속성은 progress_start_color, progress_end_color입니다. 현재는 start_color는 빨간색, end_color는 파란색입니다. 자연스러운 그라데이션을 보여주고 있는데, Java와 Kotlin 코드에서 설정할 수도 있으나 그건 후설하겠습니다. 어쨌거나 attrs 속성에서 위와 같은 설정을 바로 할 수 있다는 것입니다.

이 속성은 progress_background_color입니다. 전체 원에서 퍼센트를 표시하고 남은 영역의 색을 결정하는 속성인데, 현재는 브라운 (갈색)으로 설정된 부분이 바로 background입니다.

---

app:progress_shader

이 속성에는 3가지의 타입이 존재하는데, 그 중 두번째는 지정할 때마다 튕겨서 나중에 안 튕길때 추가해두겠습니다.

1번째 사진 : linear, 2, 3번째 사진 : sweep

start_color와 end_color의 그라데이션 방식을 설정합니다. 원래는 "linear", "radial", "sweep"의 세 가지 타입이 있고 그 중 두번째는 방사형으로 추측이 되는데, 어떤 인자가 빠졌는지 계속 튕겨서 2가지만 기술합니다.

"linear"은 말 그대로 선형입니다. 그렇기 때문에 미적으로는 몰라도, 원형 프로그래스바와 적합하다고 보기에는 무리가 있습니다. 왜냐하면 그라데이션이 원형이 아니기 때문에 퍼센티지와 색의 직접적인 연관은 없기 때문입니다.

거기에 반해 "sweep"은 어떤 점을 중심으로 그 주위로 원형을 그리면서 그라데이션이 나타납니다. 때문에 퍼센티지와 색이 직접적인 연관이 생깁니다.

---

app:progress_stroke_cap

이 속성은 프로그래스바의 처음과 끝의 모양을 결정하는 속성입니다. 이미지로 직접 보시면 다음과 같습니다.

이 속성도 세 가지가 있는데, 하나하나 소개를 하겠습니다.

"butt"은 그냥 기본값입니다. 그리고 "round"는 끝부분이 뭉툭합니다. 사실상 제가 이 라이브러리를 사용하게 된 이유이기도 하죠. 미적으로 깔끔해 보입니다. 그리고 "square"는 "butt"와 뭐가 다른지 잘 모르겠습니다. 그냥 네모 모양의 처음과 끝 모양이라고 생각합시다.

---

app:line_

기본, line_width, line_count

현재 style은 "line"모드로 했습니다. 이 속성은 "line"모드에서만 작동하는 것 같습니다. 세 사진 모두 전체 프로그래스바의 두께는 다르지만, 모양으로 봐 주시기 바랍니다.

두번째 사진은 line_width입니다. 결과물로 추측컨데, 기본 "line"들의 선에서 그 너비? 길이를 늘려놨다고 생각할 수 있습니다. 그리고 세번째 사진은 line_count이고 정수를 받는 속성입니다. 때문에 제가 30을 넣었는데 30개의 선으로 나누어져 보여지는 것을 알 수 있습니다.

---

기타 잘 알기 힘들거나 작동하지 않는 속성은 일단 제외하였으며, 나중에라도 알게 되면 글에 추가해두겠습니다.

---

CircleProgressBar의 메소드들

CircleProgressBar에 대한 값들을 Kotlin이나 Java 언어를 이용해서 Activity나 Fragment 등에서 지정할 수 있도록, 여러 메소드들을 제공하고 있습니다. 그것들에 대해 알아보도록 합시다.

앞과 같은 속성 (attributes)과 같은 기능을 하는 메소드들

.setProgressStartColor(색상) 
.setProgressEndColor(색상)
.setProgressBackgroundColor(색상)
.setProgressStrokeWidth(길이) 
.setProgressTextColor(색상)
.setProgressTextSize(글자크기)
.startDegree(각도)
.setLineCount(정수)
.setLineWidth(길이)
.setStyle(프로그래스바타입) // LINE 0, SOLID 1, SOLID_LINE 2
.setShader(그라데이션타입) // LINEAR 0, RADIAL 1, SWEEP 2
.setCap(프로그래스바끝모양) // Paint.Cap.BUTT, Paint.Cap.ROUND, Paint.Cap.SQUARE 중 택일

이들은 앞과 같은 역할을 하기 때문에 손 아프게 다시 칠 필요가 없습니다. 이들은 그냥 앞에서 한 것처럼 하면 되고, 동적으로 변환시킬 필요가 있기 때문에 메소드로 제공하는 것일 겁니다. 따라서 웬만해서는 사용할 일이 없을 것입니다. 우리가 정말 알아야 할 메소드는 이게 아니라 다음과 같은 메소드들이죠. 주의할 점은 LINE, LINEAR 등의 값이 제가 못 찾는건지 따로 나와 있지 않아서, 주석으로 표기해 둡니다. 이렇게 하시면 됩니다.

---

.max (setMax / getMax)

// Language : Kotlin
graph.max = 100
var graph_max = graph.max

// Language : Java
graph.setMax(100)
int graph_max = graph.getMax()

Kotlin은 프로퍼티 접근 문법 지원을 하기 때문에 .max라는 간단한 키워드로 최댓값 설정과 받아오기가 가능합니다. 이 최댓값이란 프로그래스바의 100%에 해당하는 값을 말합니다.

---

.progress (setProgress / getProgress)

// Language : Kotlin
graph.progress = 70
var graph_progress = graph.progress

// Language : Java
graph.setProgress(70)
int graph_progress = graph.getProgress()

위의 설명과 같습니다. 여기서 progress값은 현재의 값이라고 말하면 될까요? 그리고 프로그래스바는 progress / max * 100%만큼 표시를 해 주게 됩니다. 

---

.setProgressFormatter

// Language : Kotlin
graph.setProgressFormatter { progress, max ->
            val DEFAULT_PATTERN = "%d퍼센트"
            String.format(DEFAULT_PATTERN, (progress.toFloat() / max.toFloat() * 100).toInt())
        }

// Language : Java
graph.setProgressFormatter((progress, max) -> {
            final String DEFAULT_PATTERN = "%d퍼센트";
            return String.format(DEFAULT_PATTERN, (int) ((float) progress / (float) max * 100));
        });

DEFAULT_PATTERN 자리에는 우리가 아는 그 String Format 하듯이 하면 됩니다. return 이후의 문장이나 String.format 이후의 문장은 건드리지 않는 게 좋습니다. 

---

이렇게 원형 프로그래스 바 라이브러리에 대해서 알아보았습니다. 상세한 예시와 코드로 설명을 해 두었으니, 유용하게 사용하시면 좋을 것 같습니다. 공감 눌러주시면 감사하겠습니다. 질문은 댓글에 남겨 주세요. 다음은 원래의 라이브러리 링크입니다. 혹시나 모르니 참고하시면 좋을 것 같습니다만 README.md 파일이 상세하지 않아 도움이 될지는 모르겠네요. 그럼 이상으로 글을 마치도록 하겠습니다. 다음에는 무슨 라이브러리를 소개할까요?

dinuscxj/CircleProgressBar