stagexl_richtextfield 0.3.0

  • README.md
  • CHANGELOG.md
  • Installing
  • Versions
  • 73

StageXL RichTextField

Rich Text Field add-on package for StageXL - allows for multiple format ranges within a given text field.

NOTE: as of version 0.10.0-dev, StageXL_RichTextField requires a Dart 2 SDK.

Build Status

Usage

To use StageXL RichTextFields, simply import the package after importing stagexl itself...

import 'package:stagexl/stagexl.dart';
import 'package:stagexl_richtextfield/stagexl_richtextfield.dart';

void main() {

  CanvasElement canvas = querySelector("#richtext");
  Stage stage = new Stage('richtext', canvas)
    ..scaleMode = StageScaleMode.SHOW_ALL;
  RenderLoop render = new RenderLoop();
  RichTextFormat format = new RichTextFormat('Calibri, sans-serif', 25, 0x000000, align: TextFormatAlign.LEFT);
  RichTextField rtf = new RichTextField()
    ..defaultTextFormat = format
    ..text = 'Here is some sample {b}bold{/b} text.'
    ..width = stage.sourceWidth
    ..height = stage.sourceHeight
    ..wordWrap = true
    ..y = 0;

  render.addStage(stage);
  stage.addChild(rtf);

}

Doing it by hand

RichTextField adds startIndex and endIndex fields to the RichTextFormat class. A -1 in endIndex will anchor the format through the end of the string. These are commonly specified in the RichTextField.setFormat method, as follows:

RichTextFormat format = new RichTextFormat('Calibri, sans-serif', 25, 0x000000, align: TextFormatAlign.LEFT);
RichTextField rtf = new RichTextField('Manually setting some bold text', format, false)
    ..width = 400;

//the word "bold" above is at character positions 22 through 25
rtf.setFormat(format..bold=true, 22, 25);

As you add "ranged formats" to your RichTextField it applies logic to maintain mutually exclusive format ranges. This means that if you added italic=true from 5 through 25, and then bold=true from 10 through 15, the range from 10 to 15 will not be italicized, only bold - the original 5 to 25 italic is automatically split into two ranges, one from 5 to 9, the other from 16 to 25.

The easy way

As you can imagine, having to count character ranges simply to apply some formatting is not ideal. To address this, a simple parser is included which understand the set of "text tags" (wrapped in {}) defined below:

TagMeaningExample
{b}BoldSome {b}bold{/b} text
{i}ItalicNow {i}italic{/i} text
{u}UnderlineCan do {u}underlines{/u}
{o}OverlineAnd {o}overlines{/o}
{s}StrikethroughEven {s}strikethrough{/s} text
{color=}Set colorSome {color=0xFF0000}red text{/color}
{font=}Set font{font=Georgia}Georgia{/font} on my mind
{size=[+-*/]}Set size{size=*2}Double{/size} and {size=-5}smaller{/size}
{[preset]}Apply presetI'm so {excited}excited, I just can't hide it!{/excited}

The {[preset]} tag bears some explanation. RichTextField also has a public Map<String, RichTextFormat> field named presets. If you have some combination of styles that you use regularly, instead of wrapping multiple tags every time, you can simply add the preset to your field and call it with a tag:

RichTextField rtf = new RichTextField()
    ..presets['excited'] = format.clone()..bold=true..italic=true..size=30..color=0xFF00FF;

Try out the sandbox example to get better acquainted.

Roll your own parser

The default included parser may not meet all of your needs. Beyond wrapping the low-level functions, the parser method itself is publically settable, so you can override with your own. (Note: this approach could use a code review to make pluggable parsers more robust).

changelog

This file contains highlights of what changes on each version of the StageXL_RichTextField package. This file is normally updated whenever we push a new version to pub.

Pub version 0.3.0

  • Raised dependency to StageXL 1.4.0
  • Ready for Dart 2.0

Pub version 0.2.0

  • No Changelog available

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  stagexl_richtextfield: ^0.3.0

2. Install it

You can install packages from the command line:

with pub:


$ pub get

Alternatively, your editor might support pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:stagexl_richtextfield/stagexl_richtextfield.dart';
  
Version Uploaded Documentation Archive
0.3.0 Aug 11, 2018 Go to the documentation of stagexl_richtextfield 0.3.0 Download stagexl_richtextfield 0.3.0 archive
0.2.0+1 Sep 4, 2017 Go to the documentation of stagexl_richtextfield 0.2.0+1 Download stagexl_richtextfield 0.2.0+1 archive
0.2.0 Aug 26, 2017 Go to the documentation of stagexl_richtextfield 0.2.0 Download stagexl_richtextfield 0.2.0 archive
0.1.5 Dec 3, 2016 Go to the documentation of stagexl_richtextfield 0.1.5 Download stagexl_richtextfield 0.1.5 archive
0.1.4 Aug 8, 2016 Go to the documentation of stagexl_richtextfield 0.1.4 Download stagexl_richtextfield 0.1.4 archive
0.1.3+3 Jan 24, 2016 Go to the documentation of stagexl_richtextfield 0.1.3+3 Download stagexl_richtextfield 0.1.3+3 archive
0.1.3+2 Nov 21, 2015 Go to the documentation of stagexl_richtextfield 0.1.3+2 Download stagexl_richtextfield 0.1.3+2 archive
0.1.3+1 Nov 21, 2015 Go to the documentation of stagexl_richtextfield 0.1.3+1 Download stagexl_richtextfield 0.1.3+1 archive
0.1.3 Nov 21, 2015 Go to the documentation of stagexl_richtextfield 0.1.3 Download stagexl_richtextfield 0.1.3 archive
0.1.2 Mar 23, 2014 Go to the documentation of stagexl_richtextfield 0.1.2 Download stagexl_richtextfield 0.1.2 archive

All 12 versions...

Popularity:
Describes how popular the package is relative to other packages. [more]
60
Health:
Code health derived from static analysis. [more]
91
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
80
Overall:
Weighted score of the above. [more]
73
Learn more about scoring.

We analyzed this package on Dec 5, 2018, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.1.0
  • pana: 0.12.7

Platforms

Detected platforms: web

Primary library: package:stagexl_richtextfield/stagexl_richtextfield.dart with components: html.

Health issues and suggestions

Document public APIs (-9.35 points)

100 out of 107 API elements (library, class, field or method) have no adequate dartdoc content. Good documentation improves code readability and discoverability through search.

Format lib/src/rich_font_style_metrics.dart.

Run dartfmt to format lib/src/rich_font_style_metrics.dart.

Format lib/src/rich_text_field.dart.

Run dartfmt to format lib/src/rich_text_field.dart.

Format lib/src/rich_text_format.dart.

Run dartfmt to format lib/src/rich_text_format.dart.

Fix additional 3 files with analysis or formatting issues.

Additional issues in the following files:

  • lib/src/rich_text_line_metrics.dart (Run dartfmt to format lib/src/rich_text_line_metrics.dart.)
  • lib/src/rich_text_parser.dart (Run dartfmt to format lib/src/rich_text_parser.dart.)
  • lib/src/tools.dart (Run dartfmt to format lib/src/tools.dart.)

Maintenance suggestions

The description is too short. (-20 points)

Add more detail about the package, what it does and what is its target use case. Try to write at least 60 characters.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0 <3.0.0
stagexl >=1.4.0 <2.0.0 1.4.0+2
Transitive dependencies
collection 1.14.11
petitparser 2.0.2
xml 3.2.3
Dev dependencies
build_runner ^0.10.1
build_test ^0.10.3+1
build_web_compilers ^0.4.2+1