Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

initial import

  • Loading branch information...
commit 59f4a504a19fb3ae1e1669244f474c0885129271 1 parent 333d44a
Mark Murphy authored

Showing 1 changed file with 165 additions and 0 deletions. Show diff stats Hide diff stats

  1. +165 0 README.markdown
165 README.markdown
Source Rendered
... ... @@ -0,0 +1,165 @@
  1 +CWAC RichEditText: Letting Users Make Text Pretty
  2 +=================================================
  3 +
  4 +Android's `EditText` widget supports formatted (a.k.a.,
  5 +"rich text") editing. It just lacks any way for the user
  6 +to supply formatting, and it does not provide much in the
  7 +way of convenience methods for a developer to, say, tie
  8 +in some sort of toolbar to allow users to format selections.
  9 +
  10 +That's where `RichEditText` comes in.
  11 +
  12 +`RichEditText` is a drop-in replacement for `EditText` that:
  13 +
  14 +- Provides an action mode on Android 3.0+ that allows
  15 +users to format selected pieces of text
  16 +- Provides convenience methods to allow developers to
  17 +trigger formatting for selected text via other means
  18 +
  19 +This widget is packaged as an Android library project, with
  20 +a `demo/` subdirectory containing a regular Android project
  21 +with a couple of activities demonstrating the use of
  22 +`RichEditText`.
  23 +
  24 +**NOTE: THIS IS A HIGHLY EXPERIMENTAL RELEASE.** While some
  25 +rudimentary stuff works, there are many limitations and
  26 +probably more than its fair share of bugs. Mostly, this was
  27 +released to serve as a reference point for some bugs to be
  28 +filed against Android itself (related to action modes).
  29 +Expect significant revisions of this component, including
  30 +API changes, in the coming weeks and months. That being said,
  31 +you are welcome to try it out and supply feedback.
  32 +
  33 +Usage
  34 +-----
  35 +Add the project as a library project to your main project.
  36 +Then, simply add `com.commonsware.cwac.richedit.RichEditText`
  37 +widgets to your layout as needed:
  38 +
  39 +```xml
  40 +<?xml version="1.0" encoding="utf-8"?>
  41 +<com.commonsware.cwac.richedit.RichEditText xmlns:android="http://schemas.android.com/apk/res/android"
  42 + android:id="@+id/editor"
  43 + android:layout_width="fill_parent"
  44 + android:layout_height="fill_parent"
  45 + android:gravity="top|left"
  46 + android:inputType="textMultiLine">
  47 +
  48 + <requestFocus/>
  49 +
  50 +</com.commonsware.cwac.richedit.RichEditText>
  51 +```
  52 +At this time, there are no custom attributes used by
  53 +`RichEditText`.
  54 +
  55 +### Action Mode
  56 +
  57 +If you want to enable the extended action mode, where users
  58 +can format selected alongside their existing cut/copy/paste
  59 +options, call `enableActionMode()`. By default this is disabled,
  60 +and it will be up to your activity or fragment to arrange
  61 +to allow the user to format selected text.
  62 +
  63 +Note that it is safe to call `enableActionMode()` on all
  64 +versions of Android &mdash; it is this component's responsibility
  65 +to do the right thing.
  66 +
  67 +The action mode support, at present, is limited to bold
  68 +and italic. There is an underline option, but it will not
  69 +work, due to a bug/design limitation in Android. The fervent
  70 +hope is that the action mode will support all formatting options
  71 +in the coming weeks and months.
  72 +
  73 +Also note that action modes do not appear to work on Android 4.0
  74 +in landscape, at least on phones. They do work on Android 3.x
  75 +tablets and on Android 4.0 phones in portrait mode, but the
  76 +action mode does not even show up on Android 4.0 in landscape.
  77 +The hope is that this is a bug or misunderstanding in the
  78 +use of action modes, as having action modes not be available
  79 +in **THE MOST COMMON EXTENDED TYPING POSITION ON PHONES** would just
  80 +be scary.
  81 +
  82 +### Rolling Your Own Controls
  83 +
  84 +If you want to have your own toolbar or gesture interface or
  85 +whatever to allow users to format text, here are the two key
  86 +methods to call on `RichEditText`:
  87 +
  88 +- `applyEffect()` changes the current selection, applying
  89 +or removing an effect (e.g., making the selection bold). The
  90 +first parameter is the effect to apply (e.g., `RichEditText.BOLD`).
  91 +The second parameter is the new value for the effect. Many
  92 +effects take boolean values, so `applyEffect(RichEditText.BOLD, true)`
  93 +would format the current selection as bold.
  94 +
  95 +- `setOnSelectionChangedListener()` is where you register a
  96 +RichEditText.OnSelectionChangedListener object, which will
  97 +be called with `onSelectionChanged()` whenever the user changes
  98 +the selection in the widget (i.e., highlights text or taps
  99 +to un-select the highlight). You are provided the start and
  100 +end positions of the selection (as were supplied to `onSelectionChanged()`
  101 +to `RichEditText` itself by Android), plus a list of effects
  102 +that are active on that selection. This will allow you to
  103 +update your toolbar to indicate what is and is not in use,
  104 +and so you know what to do when the user taps on one of
  105 +those toolbar buttons again.
  106 +
  107 +### Supported Effects
  108 +
  109 +At the time of this writing, here are the `RichEditText`
  110 +static data members for each supported effect:
  111 +
  112 +- `BOLD`
  113 +- `ITALIC`
  114 +- `UNDERLINE`
  115 +- `STRIKETHROUGH`
  116 +- `SANS`
  117 +- `SUPERSCRIPT`
  118 +- `SUBSCRIPT`
  119 +
  120 +There are other effects presently implemented, but they
  121 +will be revised shortly, including name and data type
  122 +changes, so don't mess with them yet.
  123 +
  124 +Dependencies
  125 +------------
  126 +This project has no dependencies.
  127 +
  128 +Version
  129 +-------
  130 +This is version v0.0.1 of this module, meaning it has all
  131 +the stability of a sand castle. You have been warned.
  132 +
  133 +Demo
  134 +----
  135 +In the `demo/` sub-project you will find
  136 +a sample activity that demonstrates the use of `RichEditText`.
  137 +
  138 +License
  139 +-------
  140 +The code in this project is licensed under the Apache
  141 +Software License 2.0, per the terms of the included LICENSE
  142 +file.
  143 +
  144 +Questions
  145 +---------
  146 +If you have questions regarding the use of this code, please post a question
  147 +on [StackOverflow](http://stackoverflow.com/questions/ask) tagged with `commonsware` and `android`. Be sure to indicate
  148 +what CWAC module you are having issues with, and be sure to include source code
  149 +and stack traces if you are encountering crashes.
  150 +
  151 +If you have encountered what is clearly a bug, or a feature request,
  152 +please post an [issue](https://github.com/commonsguy/cwac-endless/issues).
  153 +Be certain to include complete steps for reproducing the issue.
  154 +
  155 +Do not ask for help via Twitter.
  156 +
  157 +Also, if you plan on hacking
  158 +on the code with an eye for contributing something back,
  159 +please open an issue that we can use for discussing
  160 +implementation details. Just lobbing a pull request over
  161 +the fence may work, but it may not.
  162 +
  163 +Release Notes
  164 +-------------
  165 +* v0.0.1: initial release

0 comments on commit 59f4a50

Please sign in to comment.
Something went wrong with that request. Please try again.