WaveText

WaveText 개념 및 사용 방법.

WaveText는 LabelLayer에 속하는 타입으로, 일명 흐르는 글씨를 표시하고자 할 때 사용합니다. Poi는 하나의 point 정보를 표시할 수 있고, WaveText는 여러개의 점, 즉 선형의 정보를 표시할 수 있습니다.

waveText

WaveText를 생성하기 위해서는 LabelLayer를 먼저 생성해야 합니다. LabelLayer를 통해 WaveText생성 옵션인 WaveTextOptions 클래스를 이용해서 WaveText를 생성할 수 있습니다.

WaveTextStyle

WaveText가 어떻게 표시될지는 WaveTextStyle로 정의합니다. WaveTextStyle은 LabelManager를 통해 생성할 수 있으며, 같은 styleID로는 overwrite할 수 없습니다. WaveTextStyle은 한 개 이상의 레벨별 스타일(PerLevelWaveTextStyle)로 구성됩니다. 각 레벨별 스타일을 통해서 레벨마다 WaveText가 어떻게 그려질것인지를 지정합니다. 레벨별 스타일은 PerLevelStyle에 지정한 레벨부터 그려지기 시작합니다.

PerLevelPoiStyle

위 그림의 경우, 하나의 WaveTextStyle에 각각 0레벨, 5레벨, 15레벨로 PerLevelStyle이 지정되어 있으므로 0-4레벨까지는 PerLevelStyle1, 5-14까지는 PerLevlStyle2, 15부터는 PerLevelStyle3으로 그려집니다.

WaveTextStyle의 단위레벨 구성 요소는 아래와 같습니다.

Property Description
fontSize WaveText 폰트 사이즈
fontColor WaveText 폰트 컬러
strokeThickness WaveText 외곽선 두께
strokeColor WaveText 외곽선 컬러
0~17 18~21
waveText1 waveText

아래 예제는 위 표와 같은 레벨별 스타일을 갖는 WaveTextStyle을 생성하는 예제입니다.

    func createLabelLayer() {
        let view = mapController?.getView("mapview") as! KakaoMap
        let manager = view.getLabelManager()
        let layerOption = LabelLayerOptions(layerID: "WaveTextLayer", competitionType: .none, competitionUnit: .poi, orderType: .rank, zOrder: 0)
        let _ = manager.addLabelLayer(option: layerOption)
    }
    
    func createWaveTextStyle() {
        let view = mapController?.getView("mapview") as! KakaoMap
        let manager = view.getLabelManager()
        let perLevelStyle1 = PerLevelWaveTextStyle(textStyle: TextStyle(fontSize: 15, fontColor: UIColor.white, strokeThickness: 2, strokeColor: UIColor.red), level: 10)
        let perLevelStyle2 = PerLevelWaveTextStyle(textStyle: TextStyle(fontSize: 20, fontColor: UIColor.white, strokeThickness:4, strokeColor: UIColor.blue), level: 15)
        
        let waveTextStyle = WaveTextStyle(styleID: "perLevelWaveTextStyle", styles: [perLevelStyle1, perLevelStyle2])
        
        manager.addWaveTextStyle(waveTextStyle)
    }
    
    func createWaveText() {
        let view = mapController?.getView("mapview") as! KakaoMap
        let manager = view.getLabelManager()
        let layer = manager.getLabelLayer(layerID: "WaveTextLayer")
        
        let options = WaveTextOptions(styleID: "perLevelWaveTextStyle")
        options.rank = 0
        options.text = "흐르는 글씨"
        // 그려질 경로의 point들을 지정.
        options.points = [MapPoint(longitude: 127.027401, latitude: 37.498469),
                          MapPoint(longitude: 127.027511, latitude: 37.498367),
                          MapPoint(longitude: 127.02768, latitude: 37.498254),
                          MapPoint(longitude: 127.027882, latitude: 37.498195),
                          MapPoint(longitude: 127.028052, latitude: 37.498165)]
        
        let waveText = layer?.addWaveText(options)
        waveText?.show()
    }

changeStyle

새로운 스타일을 생성해서 기존에 표시되고 있던 WaveText를 다른 스타일로 바꿀 수 있습니다. 위에서 설명한 예제와 같이 새로운 스타일을 생성하고, WaveText의 changeStyle()함수를 호출하면 새로운 style로 update 됩니다.

아래 예제는 WaveText의 Style을 바꾸는 예제입니다.

    func createWaveTextStyle() {
        let view = mapController?.getView("mapview") as! KakaoMap
        let manager = view.getLabelManager()
        let perLevelStyle1 = PerLevelWaveTextStyle(textStyle: TextStyle(fontSize: 15, fontColor: UIColor.white, strokeThickness: 2, strokeColor: UIColor.red), level: 0)
        let perLevelStyle2 = PerLevelWaveTextStyle(textStyle: TextStyle(fontSize: 20, fontColor: UIColor.white, strokeThickness: 4, strokeColor: UIColor.blue), level: 0)
        
        let waveTextStyle1 = WaveTextStyle(styleID: WaveTextStyle1", styles: [perLevelStyle1])
        let waveTextStyle2 = WaveTextStyle(styleID: "WaveTextStyle2", styles: [perLevelStyle2])

        manager.addWaveTextStyle(waveTextStyle1)
        manager.addWaveTextStyle(waveTextStyle2)
    }
    
    func createWaveText() {
        let view = mapController?.getView("mapview") as! KakaoMap
        let manager = view.getLabelManager()
        let layer = manager.getLabelLayer(layerID: "WaveTextLayer")
        
        let options = WaveTextOptions(styleID: "WaveTextStyle1", waveTextID: "waveText")
         options.
        options.rank = 0
        options.text = "흐르는 글씨"
        // 그려질 경로의 point들을 지정.
        options.points = [MapPoint(longitude: 127.027401, latitude: 37.498469),
                          MapPoint(longitude: 127.027511, latitude: 37.498367),
                          MapPoint(longitude: 127.02768, latitude: 37.498254),
                          MapPoint(longitude: 127.027882, latitude: 37.498195),
                          MapPoint(longitude: 127.028052, latitude: 37.498165)]
        
        let waveText = layer?.addWaveText(options)
        waveText?.show()
    }
    
    @IBAction func changeButtonClicked(_ sender: Any) {
    	let view = mapController?.getView("mapview") as! KakaoMap
   	let manager = view.getLabelManager()
    	let layer = manager.getLabelLayer(layerID: "WaveTextLayer")
        
    	// WaveText를 가져와서 WaveText의 style을 바꾼다. 별도의 show 함수 필요없이 changeStyle()을 호출하면 바로 적용된다.
    	let waveText = layer?.getWaveText(waveTextID: "waveText")
        waveText?.changeStyle(styleID: "WaveTextStyle2")
    }

changeStyleAndText

changeStyleAndText()메소드를 이용하여 생성된 WaveText의 스타일과 함께 WaveText의 text를 바꿀 수 있습니다. 아래 예제는 추가한 WaveText의 text와 style을 함께 업데이트하는 예제입니다.

	// WaveText 생성을 위해 LabelLayer를 생성한다.
    func createLabelLayer() {
        let view = mapController?.getView("mapview") as! KakaoMap
        let manager = view.getLabelManager()
        let layerOption = LabelLayerOptions(layerID: "WaveTextLayer", competitionType: .none, competitionUnit: .poi, orderType: .rank, zOrder: 0)
        let _ = manager.addLabelLayer(option: layerOption)
    }
    
	// WaveText가 처음 표시될 때 사용할 style 생성
    func createWaveTextStyle() {
        let view = mapController?.getView("mapview") as! KakaoMap
        let manager = view.getLabelManager()
        let perLevelStyle1 = PerLevelWaveTextStyle(textStyle: TextStyle(fontSize: 15, fontColor: UIColor.white, strokeThickness: 2, strokeColor: UIColor.red), level: 10)
        let perLevelStyle2 = PerLevelWaveTextStyle(textStyle: TextStyle(fontSize: 20, fontColor: UIColor.white, strokeThickness: 4, strokeColor: UIColor.blue), level: 15)

        let waveTextStyle = WaveTextStyle(styleID: "perLevelWaveTextStyle", styles:[perLevelStyle1, perLevelStyle2])

        manager.addWaveTextStyle(waveTextStyle)
    }
    
    // 버튼이 클릭되면 변경할 WaveTextStyle 생성
    func createChangedWaveTextStyle() {
        let view = mapController?.getView("mapview") as! KakaoMap
        let manager = view.getLabelManager()
        let perLevelStyle1 = PerLevelWaveTextStyle(textStyle: TextStyle(fontSize: 15, fontColor: UIColor.white, strokeThickness: 2, strokeColor: UIColor.blue), level: 10)
        let perLevelStyle2 = PerLevelWaveTextStyle(textStyle: TextStyle(fontSize: 20, fontColor: UIColor.white, strokeThickness: 4, strokeColor: UIColor.red), level: 15)
        
        let waveTextStyle = WaveTextStyle(styleID: "perLevelWaveTextStyle2", styles: [perLevelStyle1, perLevelStyle2])

        manager.addWaveTextStyle(waveTextStyle)
    }
    
    // WaveText 생성
    func createWaveText() {
        let view = mapController?.getView("mapview") as! KakaoMap
        let manager = view.getLabelManager()
        let layer = manager.getLabelLayer(layerID: "WaveTextLayer")
        
        let options = WaveTextOptions(styleID: "perLevelWaveTextStyle", waveTextID: "waveText1")
        options.rank = 0
        options.text = "흐르는 글씨"
        // 그려질 경로의 point들을 지정.
        options.points = [MapPoint(longitude: 127.027401, latitude: 37.498469),
                          MapPoint(longitude: 127.027511, latitude: 37.498367),
                          MapPoint(longitude: 127.02768, latitude: 37.498254),
                          MapPoint(longitude: 127.027882, latitude: 37.498195),
                          MapPoint(longitude: 127.028052, latitude: 37.498165)]
        
        let waveText = layer?.addWaveText(options)
        waveText?.show()
    }
    
    @IBAction func onButtonClicked(_ sender: Any) {
        let view = mapController?.getView("mapview") as! KakaoMap
        let manager = view.getLabelManager()
        let layer = manager.getLabelLayer(layerID: "WaveTextLayer")
        let waveText = layer?.getWaveText(waveTextID: "waveText1")
        
        // 바꿀 WaveTextStyle을 생성한다.
        createChangedWaveTextStyle()
        
        // 바꾸고자 하는 text와 styleID로 waveText의 텍스트 내용과 스타일을 함께 업데이트 한다.
        waveText?.changeTextAndStyle(text: "흐르는 글씨 업데이트", styleID: "perLevelWaveTextStyle2")
    }

WaveTextOptions

WaveText는 사용자가 직접적으로 생성할 수 없습니다. LabelManager를 통해 생성한 LabelLayer에 아래와 같은 addWaveText를 호출할 때 WaveTextOptions 생성 옵션을 넘기면 API 내부적으로 WaveText 객체를 생성하여 리턴합니다.

        let options = WaveTextOptions(styleID: "perLevelWaveTextStyle")
        options.rank = 0
        options.text = "흐르는 글씨"
        // 그려질 경로의 point들을 지정.
        options.points = [MapPoint(longitude: 127.027401, latitude: 37.498469),
                          MapPoint(longitude: 127.027511, latitude: 37.498367),
                          MapPoint(longitude: 127.02768, latitude: 37.498254),
                          MapPoint(longitude: 127.027882, latitude: 37.498195),
                          MapPoint(longitude: 127.028052, latitude: 37.498165)]
        
        let waveText = layer?.addWaveText(options)

WaveText를 생성하기 위한 WaveTextOptions의 속성은 아래와 같습니다.

Property Description
ID WaveText 고유 ID. 같은 Layer안에서 중복으로 추가할 수 없습니다. ID는 Layer내에서 유니크합니다.
styleID WaveText를 표시할 때 사용할 WaveTextStyle의 ID. 생성하는 시점에서 Style은 미리 추가되어 있어야 합니다.
rank WaveText의 렌더링 우선순위
text WaveText에 표시할 text
points WaveText를 구성하는 2개 이상의 point배열. text가 이 points의 path를 따라서 그려진다.

WaveTextOptions에 따라 다양한 WaveText를 생성할 수 있습니다.

WaveText Properties

LabelLayer를 통해 생성된 WaveText의 Property는 아래와 같습니다.

Property Description
layerID WaveText가 속한 LabelLayer의 ID
itemID WaveText의 ID
isShow WaveText가 현재 뷰에 표시되고 있는지 여부
userObject WaveText의 UserObject