Label

1. Label 종류

라벨은 지도의 특정 위치에 점, 혹은 선형으로 이미지나 텍스트를 표시할 수 있습니다. 사용하는 방법에 따라 Label, LodLabel, PolylineLabel 3가지 종류의 라벨이 있습니다.

다양한 스타일과 기능을 활용한 Label 예제들

Icon 만 있는	Text 만 있는	Icon 과 Text 가 같이 있는

Badge 가 있는	움직임이 있는	구부러진 텍스트

2. Label 관련 주요 클래스들

Label 을 표시하기 위해서는 라벨과 관련 된 클래스들의 역할과 관계를 이해해야 합니다.

• LabelManager - Label 과 관련 된 모든 진입점. LabelLayer, LodLabelLayer, LabelStyles, PolylineLabelStyles, LabelAnimator 를 추가 및 삭제 할 수 있는 컨테이터 클래스.

• LabelLayer, LodLabelLayer - Label 과 LodLabel 을 그룹 별로 관리. 레이어마다 렌더링 우선순위를 다르게 지정 할 수 있고 Label, LodLabel 을 추가 및 삭제 할 수 있는 컨테이너 클래스.

• LabelStyles, PolylineLabelStyles - Label, LodLabel, PolylineLabel 의 이미지 또는 텍스트 색깔, 크기 등을 설정하는 클래스. 라벨 객체 하나 당 하나의 스타일을 갖고 있다.

• LabelAnimator - Label 에 애니메이션 효과를 주고 제어하는 클래스. 여러 개의 라벨을 동시에 효과 줄 수 있다.

LabelManager

LabelManager 는 Label 과 관련 된 최상위 클래스이며 LabelLayer, LodLabelLayer 생성 및 삭제, Label 과 관련 된 객체관리를 하는 컨테이너 역할을 합니다. 아래의 예제코드는 LabelManager 를 가져오는 방법입니다.

// LabelManager 를 가져오는 방법
kakaoMap.getLabelManager();

LabelLayer, LodLabelLayer

LabelLayer 는 Label 과 PolylineLabel 의 생성 및 삭제와 같은 객체관리를 하는 컨테이너 역할을 합니다. 뿐만 아니라, zOrder 값을 이용해 LabelLayer 간에 Label 들이 겹칠 때 어떤 것이 우선적으로 보여지게 할 지 렌더링 우선순위를 설정할 수 있습니다. 그리고, CompetitionType, CompetitionUnit, OrderingType 옵션을 이용해 Label 이 다른 Label 들과 겹쳐질 때 어떤 식으로 보여지게 할지 세부적으로 설정 할 수 있습니다.

LodLabelLayer 는 LodLabel 만 관리 합니다.

Layer 생성하기

LabelLayer 와 LodLabelLayer 는 LabelLayerOptions 을 통해 초기값을 설정하고 생성할 수 있습니다. 아래 표는 LabelLayerOptions 의 주요 속성값 입니다.

LabelLayer 는 LabelManager 에 미리 생성 된 디폴트 LabelLayer 를 사용하는 방법과 사용자가 직접 LabelLayer 를 생성해서 사용하는 2가지 방법이 있습니다.

// 1. LabelManager 에 미리 생성 된 디폴트 LabelLayer 가져오는 방법 
labelManager.getLayer();
labelManager.getLodLayer();

// 2. 사용자 커스텀으로 LabelLayer 생성 및 가져오는 방법
LabelLayer layer = labelManager.addLayer(LabelLayerOptions.from("myLayerId")
        .setOrderingType(OrderingType.Rank)
        .setCompetitionUnit(CompetitionUnit.IconAndText)
        .setCompetitionType(CompetitionType.All));

// 2-1. 사용자 커스텀으로 LodLabelLayer 생성 및 가져오는 방법
LodLabelLayer lodLayer = labelManager.addLodLayer(LabelLayerOptions.from("myLayerId")
        .setOrderingType(OrderingType.Rank)
        .setCompetitionUnit(CompetitionUnit.IconAndText)
        .setCompetitionType(CompetitionType.All));        

3. LabelLayer 의 렌더링 우선순위

LabelLayer 의 zOrder 값은 LabelLayer 가 여러 개일 때, zOrder 값의 크기비교로 LabelLayer 간에 라벨들의 보여지는 우선순위를 조절 할 수 있습니다. LabelLayer의 zOrder 값은 아래와 같이 미리 정의된 사용 가능한 범위 내에서 사용해야 합니다. 예약된 범위의 값을 사용하게 되면 의도와 다르게 그려지거나 별도의 공지 없이 렌더링 결과가 달라질 수 있습니다.

경쟁 옵션 설정하기

Layer 의 경쟁 옵션 값들을 이용해 Label 이 다른 Label 들과 겹쳐질 때 어떤 라벨을 어떻게 보여질지 세부적으로 설정 할 수 있습니다.

Label 이 겹쳐질 때 렌더링 처리 순서

• zOrder의 값이 클수록 일반적으로 위에 그려집니다(우선 순위가 높음).
• CompetitionType이 none 혹은 background인 경우 다른 라벨과 겹치더라도 관계없이 그려집니다. (위 아래 겹치는 순서는 zOrder 순서에 따름.)
• CompetitionType의 upper속성을 가지는 label은 자신이 속한 layer보다 zOrder가 높은 layer에 속한 label 중에 lower속성을 가지는 label과 겹칠 경우 그려지지 않습니다.
• CompetitionType의 same속성을 가지는 label끼리는 겹칠 경우 orderType에 따라 우선 순위가 높은 label이 그려집니다.