Skip to content

Latest commit

 

History

History
207 lines (144 loc) · 7.57 KB

README.md

File metadata and controls

207 lines (144 loc) · 7.57 KB
Raw

Maven metadata URL License Apache 2.0 kotlin

String Annotations

Rich text in your strings.xml.

Table of contents

Problem to solve

image

Take a look at a picture above. Think about how you would implement this design in terms of Android.

Yes, with different colors in the same text. Oh, highlighted parts should perform some action on click as well.

Aren't frightened yet? Well, make it use wildcards and placeholders (e.g. "group by: _, sort by: _"). And don't forget about localization.

B r e a t h e   o u t.

If you're not new in modern Android development, then you've certainly done things alike before. Indeed, it's pretty common business' request — to reinvigorate monotonous Android TextView with some styles in order to provide a better UX.

For my personal surprise, I've never found industry-standard solution, like ones we have for almost everything else in Android. From my experience, every time, when developer needs to do something like this, they either assemble their own solution from related answers, or use copy-pasted piece of code, which they have been using for last few years with minor adjustments each time.

Well, no more :)

StringAnnotations is a library that absorbed all best from old good familiar solutions, and enhanced it with great customization, extendability and convenience of use.

Reasons to use

  • Annotates string resources in your strings.xml, preserving ability for localization.
  • Works with Android Views system and Jetpack Compose UI — choose what you need.
  • Provides neat API to use inside Activity, Fragment and @Composable scopes.
  • Extendable and customizable: add your own annotation types and arguments for them.
  • 100% documented.
  • Covered in unit tests.

Artifacts

Android Views

io.github.mmolosay:string-annotations:views:VERSION

Artifact to be used with Android Views system.

See string-annotations:views README.md for more information.

Jetpack Compose

io.github.mmolosay:string-annotations:compose:VERSION

Artifact to be used with Jetpack Compose UI.

See string-annotations:compose README.md for more information.

Installation

The library has not been published yet.

Arguments

Arguments provide values for your annotations. You should pass Arguments instance, containing all declared values, when obtaining annotated string.

Default Arguments implementation provides values for all out-of-the-box annotation types.

Since default implementations of AnnotationProcessor use DefaultValuesParser to parse arguments, default placeholders' format is $arg${QUALIFIER}${INDEX}, where QUALIFIER should match the qualifier of corresponding annotation type and INDEX specifies index of desired value.

Below you can see simplified example, how Arguments can be used. For more examples, view samples.

In your strings.xml:

<string name="demo">Text with <annotation color="$arg$color$0">multiple</annotation> <annotation color="$arg$color$1">colors</annotation></string>

In your code:

val color1 = ContextCompat.getColor(this, R.color.red)
val color2 = ContextCompat.getColor(this, R.color.green)
val args = Arguments {
    colors(color1, color2)
}
yourTextView.text = getAnnotatedString(R.string.demo, args)

Annotations

There are types of annotations, supported by default. You can extend it and implement your own ones.

Background color

Specifies background color of its body.

image

  • Annotation attribute: background
  • Arguments qualifier: color

<annotation background="$arg$color$0">text with background color</annotation>

Foreground color

Specifies foreground color of its body.

image

  • Annotation attribute: color
  • Arguments qualifier: color

<annotation color="$arg$color$0">colored text</annotation>

Clickable

Specifies ability of its body to intercept click events.

image

  • Annotation attribute: clickable
  • Arguments qualifier: clickable

<annotation clickable="$arg$clickable$0">clcik me</annotation>

Decoration

Specifies trivial graphic, e.g. line.

image image

  • Annotation attribute: decoration
  • Arguments qualifier: decoration
  • <annotation decoration="$arg$decoration$0">decorated text</annotation>

Absolute size

Specifies absolute size of its body.

image

  • Annotation attribute: size
  • Arguments qualifier: size

<annotation size="$arg$size$0">text of some size</annotation>

Typeface style

Specifies typeface style of its body.

image

  • Annotation attribute: style
  • Arguments qualifier: style

<annotation style="$arg$style$0">styled text</annotation>

Samples

Check out Android Views and Jetpack Compose samples.

License

Copyright 2023 Mikhail Malasai

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.