From 261f2893296d1db99e74ab0c0edc92d1b0a11c11 Mon Sep 17 00:00:00 2001 From: Dimitry Ivanov Date: Fri, 26 May 2017 17:42:17 +0300 Subject: [PATCH] Working with readmes --- README.md | 8 +- library/README.md | 156 +++++++++++++++++- .../markwon/SpannableConfiguration.java | 2 +- .../renderer/html/SpannableHtmlParser.java | 2 +- .../noties/markwon/spans/SpannableTheme.java | 88 +++++----- 5 files changed, 208 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index d4501926..25518070 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,10 @@ compile 'ru.noties:markwon-image-loader:1.0.0' // optional --- +**Please note, that this file is created for demonstration purposes. Please refer to `library` module [README][library] instead** + +--- + ## Supported markdown features: * Emphasis (`*`, `_`) * Strong emphasis (`**`, `__`) @@ -167,4 +171,6 @@ long long long skjfs fgjsdfhj sf `dfk df` | sdsd,fklsdfklsdfklsdfkl sdfkl dsfjks [1]: https://github.com [github]: https://github.com -[commonmark-java]: https://github.com/atlassian/commonmark-java \ No newline at end of file + +[commonmark-java]: https://github.com/atlassian/commonmark-java/blob/master/README.md +[library]: https://github.com/noties/Markwon/blob/master/README.md \ No newline at end of file diff --git a/library/README.md b/library/README.md index b5c0e430..ae394b0e 100644 --- a/library/README.md +++ b/library/README.md @@ -17,6 +17,142 @@ The most basic example would be: Markwon.setMarkdown(textView, "**Hello *there*!!**") ``` +Please note, that this library depends on [commonmark-java][commonmark-java] (and some extensions): +```groovy +compile 'com.atlassian.commonmark:commonmark:0.9.0' +compile 'com.atlassian.commonmark:commonmark-ext-gfm-strikethrough:0.9.0' +compile 'com.atlassian.commonmark:commonmark-ext-gfm-tables:0.9.0' +``` + +## Configuration +In order to render correctly markdown, this library need a `SpannableConfiguration` instance. It has 2 factory methods: +```java +// creates default instance +SpannableConfiguration.create(Context); + +// returns configurable Builder +SpannableConfiguration.builder(Context); +``` + +`SpannableConfiguration.Builder` class has these configurable properties (which are described in more detail further): +```java +public Builder theme(SpannableTheme theme); +public Builder asyncDrawableLoader(AsyncDrawable.Loader asyncDrawableLoader); +public Builder syntaxHighlight(SyntaxHighlight syntaxHighlight); +public Builder linkResolver(LinkSpan.Resolver linkResolver); +public Builder urlProcessor(UrlProcessor urlProcessor); +public Builder htmlParser(SpannableHtmlParser htmlParser); + +// and obviously: +public SpannableConfiguration build(); +``` + +## Theme +`SpannableTheme` controlls the appearance of rendered markdown. It has pretty reasonable defaults, which are established based on style of a TextView to which it is applied. It has some factory methods: +```java +// creates ready-to-use SpannableThemeObject +SpannableTheme.create(Context); + +// can be used to tweak default appearance +SpannableTheme.builderWithDefaults(Context); + +// returns empty builder (no default values are set) +SpannableTheme.builder(); + +// returns a builder that is instantiated with all values from specified SpannableTheme +SpannableTheme.builder(SpannableTheme copyFrom); +``` + +`SpannableTheme.Builder` have these configurations: +#### Link +```java +public Builder linkColor(@ColorInt int linkColor); +``` + +#### Block +```java +// left margin for: lists & quotes (text is shifted) +public Builder blockMargin(@Dimension int blockMargin); +``` + +#### Quote +```java +// width of quote indication (the `|`) +public Builder blockQuoteWidth(@Dimension int blockQuoteWidth); + +// color of `|` quote indication +public Builder blockQuoteColor(@ColorInt int blockQuoteColor); +``` + +#### Lists +```java +// color of list item bullets(●, ○, ■)/numbers +public Builder listItemColor(@ColorInt int listItemColor); + +// stroke width for list bullet (2nd level - `○`) +public Builder bulletListItemStrokeWidth(@Dimension int bulletListItemStrokeWidth); + +// width of list bullet (●, ○, ■) +public Builder bulletWidth(@Dimension int bulletWidth); +``` + +#### Code +```java +// text color for `code` blocks +public Builder codeTextColor(@ColorInt int codeTextColor); + +// background color for `code` blocks +public Builder codeBackgroundColor(@ColorInt int codeBackgroundColor); + +// left margin for multiline `code` blocks +public Builder codeMultilineMargin(@Dimension int codeMultilineMargin); + +// typeface of `code` block +public Builder codeTypeface(@NonNull Typeface codeTypeface); + +// text size for `code` block +public Builder codeTextSize(@Dimension int codeTextSize); +``` + +#### Headings +```java +// height of the `break` line under h1 & h2 +public Builder headingBreakHeight(@Dimension int headingBreakHeight); + +// color of the `break` line under h1 & h2 +public Builder headingBreakColor(@ColorInt int headingBreakColor); +``` + +#### SuperScript & SupScript +```java +// ratio for & text size (calculated based on TextView text size) +public Builder scriptTextSizeRatio(@FloatRange(from = .0F, to = Float.MAX_VALUE) float scriptTextSizeRatio); +``` + +#### Thematic break +```java +// the `---` thematic break color +public Builder thematicBreakColor(@ColorInt int thematicBreakColor); + +// the `---` thematic break height +public Builder thematicBreakHeight(@Dimension int thematicBreakHeight); +``` + +#### Tables +```java +// padding inside a table cell +public Builder tableCellPadding(@Dimension int tableCellPadding); + +// color of table borders +public Builder tableBorderColor(@ColorInt int tableBorderColor); + +// the `stroke` width of table border +public Builder tableBorderWidth(@Dimension int tableBorderWidth); + +// the background of odd table rows +public Builder tableOddRowBackgroundColor(@ColorInt int tableOddRowBackgroundColor); +``` + ## Images By default this library does not render any of the images. It's done to simplify rendering of text-based markdown. But if images must be supported, then the `AsyncDrawable.Loader` can be specified whilst building a `SpannableConfiguration` instance: @@ -29,6 +165,8 @@ final AsyncDrawable.Loader loader = new AsyncDrawable.Loader() { download(destination, new Callback() { @Override public void onDownloaded(Drawable d) { + // additionally we can call `drawable.isAttached()` + // to ensure if AsyncDrawable is in layout drawable.setResult(d); } }); @@ -55,7 +193,7 @@ Tables are supported but with some limitations. First of all: table will always ## Syntax highlight -This library does not provide ready-to-be-used implementation of syntax highlight, but it can be easily added via `SyntaxHighlight` interface whilst building `SpannableConfiguration`: +This library does not provide ready-to-be-used implementation of syntax highlight, but it can be added via `SyntaxHighlight` interface whilst building `SpannableConfiguration`: ```java final SyntaxHighlight syntaxHighlight = new SyntaxHighlight() { @@ -93,5 +231,21 @@ The primary goal of additing this abstraction is to give ability to convert rela final UrlProcessor urlProcessor = new UrlProcessorRelativeToAbsolute("https://this-is-base.org"); ``` +## Link resolver +Link resolver is used to navigate to clicked link. By default `LinkResolverDef` is used and it just constructs an `Intent` and launches activity that can handle it, or silently fails if activity cannot be resolved. The main interface: +```java +public interface Resolver { + void resolve(View view, @NonNull String link); +} +``` +## HTML parser +As markdown supports HTML to be inlined, we need to introduce another entity that does (limited) parsing. Obtain an instance of `SpannableHtmlParser` via one of these factory methods: + +```java +SpannableHtmlParser.create(SpannableTheme, AsyncDrawable.Loader) +SpannableHtmlParser.create(SpannableTheme, AsyncDrawable.Loader, UrlProcessor, LinkSpan.Resolver) +``` + +[commonmark-java]: https://github.com/atlassian/commonmark-java [mil-README]: https://github.com/noties/Markwon/blob/master/library-image-loader/README.md diff --git a/library/src/main/java/ru/noties/markwon/SpannableConfiguration.java b/library/src/main/java/ru/noties/markwon/SpannableConfiguration.java index 4952b599..aa9b6f15 100644 --- a/library/src/main/java/ru/noties/markwon/SpannableConfiguration.java +++ b/library/src/main/java/ru/noties/markwon/SpannableConfiguration.java @@ -70,7 +70,7 @@ public class SpannableConfiguration { private UrlProcessor urlProcessor; private SpannableHtmlParser htmlParser; - public Builder(Context context) { + Builder(Context context) { this.context = context; } diff --git a/library/src/main/java/ru/noties/markwon/renderer/html/SpannableHtmlParser.java b/library/src/main/java/ru/noties/markwon/renderer/html/SpannableHtmlParser.java index 74df59a1..af616330 100644 --- a/library/src/main/java/ru/noties/markwon/renderer/html/SpannableHtmlParser.java +++ b/library/src/main/java/ru/noties/markwon/renderer/html/SpannableHtmlParser.java @@ -163,7 +163,7 @@ public class SpannableHtmlParser { private ImageProvider imageProvider; private HtmlParser parser; - public Builder simpleTag(@NonNull String tag, @NonNull SpanProvider provider) { + Builder simpleTag(@NonNull String tag, @NonNull SpanProvider provider) { simpleTags.put(tag, provider); return this; } diff --git a/library/src/main/java/ru/noties/markwon/spans/SpannableTheme.java b/library/src/main/java/ru/noties/markwon/spans/SpannableTheme.java index d1ae16bc..8eed1c0f 100644 --- a/library/src/main/java/ru/noties/markwon/spans/SpannableTheme.java +++ b/library/src/main/java/ru/noties/markwon/spans/SpannableTheme.java @@ -5,23 +5,25 @@ import android.content.res.TypedArray; import android.graphics.Paint; import android.graphics.Typeface; import android.support.annotation.AttrRes; +import android.support.annotation.ColorInt; +import android.support.annotation.Dimension; +import android.support.annotation.FloatRange; import android.support.annotation.IntRange; import android.support.annotation.NonNull; import android.text.TextPaint; import android.util.TypedValue; -import android.widget.TextView; @SuppressWarnings("WeakerAccess") public class SpannableTheme { - - // this method should be used if TextView is known beforehand - // it will correctly measure the `space` char and set it as `codeMultilineMargin` - // otherwise this value must be set explicitly - public static SpannableTheme create(@NonNull TextView textView) { - return builderWithDefaults(textView.getContext()) - .codeMultilineMargin((int) (textView.getPaint().measureText("\u00a0") + .5F)) - .build(); - } +// +// // this method should be used if TextView is known beforehand +// // it will correctly measure the `space` char and set it as `codeMultilineMargin` +// // otherwise this value must be set explicitly +// public static SpannableTheme create(@NonNull TextView textView) { +// return builderWithDefaults(textView.getContext()) +// .codeMultilineMargin((int) (textView.getPaint().measureText("\u00a0") + .5F)) +// .build(); +// } // this create default theme (except for `codeMultilineMargin` property) public static SpannableTheme create(@NonNull Context context) { @@ -37,16 +39,16 @@ public class SpannableTheme { } public static Builder builderWithDefaults(@NonNull Context context) { - final Px px = new Px(context); + final Dip dip = new Dip(context); return new Builder() .linkColor(resolve(context, android.R.attr.textColorLink)) - .codeMultilineMargin(px.px(8)) - .blockMargin(px.px(24)) - .bulletListItemStrokeWidth(px.px(1)) - .headingBreakHeight(px.px(1)) - .thematicBreakHeight(px.px(2)) - .tableCellPadding(px.px(4)) - .tableBorderWidth(px.px(1)); + .codeMultilineMargin(dip.toPx(8)) + .blockMargin(dip.toPx(24)) + .bulletListItemStrokeWidth(dip.toPx(1)) + .headingBreakHeight(dip.toPx(1)) + .thematicBreakHeight(dip.toPx(2)) + .tableCellPadding(dip.toPx(4)) + .tableBorderWidth(dip.toPx(1)); } private static int resolve(Context context, @AttrRes int attr) { @@ -385,11 +387,9 @@ public class SpannableTheme { private int tableOddRowBackgroundColor; Builder() { - } Builder(@NonNull SpannableTheme theme) { - this.linkColor = theme.linkColor; this.blockMargin = theme.blockMargin; this.blockQuoteWidth = theme.blockQuoteWidth; @@ -413,107 +413,107 @@ public class SpannableTheme { this.tableOddRowBackgroundColor = theme.tableOddRowBackgroundColor; } - public Builder linkColor(int linkColor) { + public Builder linkColor(@ColorInt int linkColor) { this.linkColor = linkColor; return this; } - public Builder blockMargin(int blockMargin) { + public Builder blockMargin(@Dimension int blockMargin) { this.blockMargin = blockMargin; return this; } - public Builder blockQuoteWidth(int blockQuoteWidth) { + public Builder blockQuoteWidth(@Dimension int blockQuoteWidth) { this.blockQuoteWidth = blockQuoteWidth; return this; } - public Builder blockQuoteColor(int blockQuoteColor) { + public Builder blockQuoteColor(@ColorInt int blockQuoteColor) { this.blockQuoteColor = blockQuoteColor; return this; } - public Builder listItemColor(int listItemColor) { + public Builder listItemColor(@ColorInt int listItemColor) { this.listItemColor = listItemColor; return this; } - public Builder bulletListItemStrokeWidth(int bulletListItemStrokeWidth) { + public Builder bulletListItemStrokeWidth(@Dimension int bulletListItemStrokeWidth) { this.bulletListItemStrokeWidth = bulletListItemStrokeWidth; return this; } - public Builder bulletWidth(int bulletWidth) { + public Builder bulletWidth(@Dimension int bulletWidth) { this.bulletWidth = bulletWidth; return this; } - public Builder codeTextColor(int codeTextColor) { + public Builder codeTextColor(@ColorInt int codeTextColor) { this.codeTextColor = codeTextColor; return this; } - public Builder codeBackgroundColor(int codeBackgroundColor) { + public Builder codeBackgroundColor(@ColorInt int codeBackgroundColor) { this.codeBackgroundColor = codeBackgroundColor; return this; } - public Builder codeMultilineMargin(int codeMultilineMargin) { + public Builder codeMultilineMargin(@Dimension int codeMultilineMargin) { this.codeMultilineMargin = codeMultilineMargin; return this; } - public Builder codeTypeface(Typeface codeTypeface) { + public Builder codeTypeface(@NonNull Typeface codeTypeface) { this.codeTypeface = codeTypeface; return this; } - public Builder codeTextSize(int codeTextSize) { + public Builder codeTextSize(@Dimension int codeTextSize) { this.codeTextSize = codeTextSize; return this; } - public Builder headingBreakHeight(int headingBreakHeight) { + public Builder headingBreakHeight(@Dimension int headingBreakHeight) { this.headingBreakHeight = headingBreakHeight; return this; } - public Builder headingBreakColor(int headingBreakColor) { + public Builder headingBreakColor(@ColorInt int headingBreakColor) { this.headingBreakColor = headingBreakColor; return this; } - public Builder scriptTextSizeRatio(float scriptTextSizeRatio) { + public Builder scriptTextSizeRatio(@FloatRange(from = .0F, to = Float.MAX_VALUE) float scriptTextSizeRatio) { this.scriptTextSizeRatio = scriptTextSizeRatio; return this; } - public Builder thematicBreakColor(int thematicBreakColor) { + public Builder thematicBreakColor(@ColorInt int thematicBreakColor) { this.thematicBreakColor = thematicBreakColor; return this; } - public Builder thematicBreakHeight(int thematicBreakHeight) { + public Builder thematicBreakHeight(@Dimension int thematicBreakHeight) { this.thematicBreakHeight = thematicBreakHeight; return this; } - public Builder tableCellPadding(int tableCellPadding) { + public Builder tableCellPadding(@Dimension int tableCellPadding) { this.tableCellPadding = tableCellPadding; return this; } - public Builder tableBorderColor(int tableBorderColor) { + public Builder tableBorderColor(@ColorInt int tableBorderColor) { this.tableBorderColor = tableBorderColor; return this; } - public Builder tableBorderWidth(int tableBorderWidth) { + public Builder tableBorderWidth(@Dimension int tableBorderWidth) { this.tableBorderWidth = tableBorderWidth; return this; } - public Builder tableOddRowBackgroundColor(int tableOddRowBackgroundColor) { + public Builder tableOddRowBackgroundColor(@ColorInt int tableOddRowBackgroundColor) { this.tableOddRowBackgroundColor = tableOddRowBackgroundColor; return this; } @@ -523,14 +523,14 @@ public class SpannableTheme { } } - private static class Px { + private static class Dip { private final float density; - Px(@NonNull Context context) { + Dip(@NonNull Context context) { this.density = context.getResources().getDisplayMetrics().density; } - int px(int dp) { + int toPx(int dp) { return (int) (dp * density + .5F); } }