diff --git a/CHANGELOG.md b/CHANGELOG.md index 069fc97..0cee7a0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,8 @@ ## Next version ### Added - (html5) Added `characterSpacingHack` in `Settings` to replace the magic cookie used for fixing character spacing. +### Changed +- Readme cleaned. ### Fixed - Compilation failure when targetting html5 - Demo sample's cursor would jump on html5 due to spaces having no height. diff --git a/README.md b/README.md index 0d707a7..c95154f 100644 --- a/README.md +++ b/README.md @@ -3,14 +3,12 @@ ![Demo](readme_files/demo.gif) - ## Features - "Character-per-character"-style textbox for [Haxeflixel](https://haxeflixel.com/). - Correct word-wrapping : a being written word won't jump from a line to another if it's too big for the current line - Per-character effects : allows you to have dynamic text. - Extendable and customizable : There is a way to add new effects to your textbox, change the font, color, size, etc... - ## Usage ### Known issues or quirks @@ -23,6 +21,7 @@ Include the library's root folder as classpath in your project node. Something l + ``` Now you should be ready and able to require classes such as `textbox.Textbox`. @@ -40,33 +39,63 @@ Now you should be ready and able to require classes such as `textbox.Textbox`. #### Why callbacks? Callbacks are useful as they allow you to extend the textbox without touching its logic. It allowed me to extract the textbox's logic from my now-dead project and make it easy to add features over it, features like effects, triggering a sound per character added to the box or change how it deals with the siutation when the textbox is full. -A few callback ideas (chaining boxes, sound-per-character, text character) are shown in the given sample project. +A few callback ideas (chaining boxes, sound-per-character, text character) are shown in the given sample project, in the form of simple callbacks or *plugin* classes. +### List of available callbacks - `statusChangeCallbacks (Status)` : if the textbox's state changes, this callback is called. Here a list of the expected behavior to be notifed of: + `FULL` : the textbox is full. Coupled with `continueWriting` you can make stuff like waiting a button press to resume writing. + `DONE` : the textbox finished writing its content. You can `dismiss` it or set it with new text. - `characterDisplayCallbacks (textbox.Text)` : This callback is added each time a character is added to the box. Use this if you need features like an audio sample played for every character, a text cursor following the input, etc etc... -Those textbox callback facilities are just callback arrays, to add or remove your own callback, just use `push` or `pop` on those members. +Those textbox callback facilities are just callback arrays, to add or remove your own callback, just use `push`, `pop`, `remove`, etc... on those members. There is no control from the textbox's part, so take care of which callbacks you're manipulating. ### Settings object (Check for textbox/Settings.hx to see what kind of parametters you can override.) ```haxe - font:String // Font location, default = HXFlixel's default font - fontSize:Int // default = 12 - textFieldWidth:Float // default = 240px - color:FlxColor // default = White - numLines:Int // How many lines the textbox will display, default = 3 - charactersPerSecond:Int // default = 24 +font:String // Font location, default = HXFlixel's default font +fontSize:Int // default = 12 +textFieldWidth:Float // default = 240px +color:FlxColor // default = White +numLines:Int // How many lines the textbox will display, default = 3 +charactersPerSecond:Int // default = 24 ``` ## Text effects This textbox allows for per-character effects such as (but not limited to) rotating characters or making them wave, coloring text or making an animated rainbow. Those effects are enabled and disabled by in-text code sequences that are small and human-writable. The system that links effects and the textbox is also user-editable to add new effects for your own projects. ## Code sequences and effects. +Having a textbox is fine. Having a textbox that can make letters change their color or move easily is better. To apply effects easily, this library looks for code sequences while parsing to determine which effect and how to trigger it. A code sequence is composed of an arobas (`@`) and 3 or 7 hexadecimal numbers determining which effect to enable or disable and its parameters. It looks like `@00105DEFF` or `@050`. The first sequence turns on the effect n° 00 with as arguments the values (5, 222, 255) while the second disables the effect n°05. -### Usage example +### Enabling an effect +``` + ┌ Enable this effect + ▼ +@MM1AABBCC +▲│ ┃ ┃ ┃ +└┼ Sequence start () + │ ┃ ┃ ┃ + └ Effect n° 0xMM + ┃ ┃ ┃ + ┃ ┃ ┃ + ┗ Argument 1 : 0xAA + ┃ ┃ + ┗ Argument 2 : 0xBB + ┃ + ┗ Argument 3 : 0xCC +``` +### Disabling an effect +``` + ┌ Disable this effect + ▼ +@MM0 +▲│ +└┼ Sequence start () + │ + └ Effect n° 0xMM +``` + +### Usage example ```haxe var textbox:Textbox = new Textbox(...); textbox`.setText(" @@ -77,34 +106,6 @@ It even works inside wo@001000000rds, even if it's a bit unreadable... "); ``` -### Enabling an effect -``` - @MM1AABBCC - ▲│ │ │ │ - └┼Sequence start () - │ │ │ │ - └ Effect n° 0xMM - │ │ │ - │ │ │ - └ Argument 1 : 0xAA - │ │ - └ Argument 2 : 0xAA - │ - └ Argument 3 : 0xAA -``` - -### Disabling an effect - -``` - @MM0 - ▲│ - └┼Sequence start () - │ - └ Effect n° 0xMM -``` - -Note : The `0` or `1` between the effect index and the first argument indicates the textbox parser to disable or enable said effect - ### Create new effects **NOTE** : This is under WIP as it might change between versions. @@ -120,8 +121,9 @@ To add an effect to the effect list, you have to create a class implementing `IE The library's pretty much functionnal and gives the barebones features as now (the current effects comes from my dead project as freebies). Here's a non-exhaustive list of what could be added or changed to make the users' life easier : - [X] Change the callback types into arrays or a class that acts a bit like C#'s delegates. - [X] On JS, there is a quirk on how to calculate a space's width and a magic cookie is used instead. Maybe make this variable part of the settings class. -- [ ] Implement helper classes such as a status icon or a "Press a button to continue" helper class. -- [ ] Add more effects +- [X] Implement ~~helper~~ example classes such as a status icon or a "Press a button to continue" helper class. + Note : Due to various kind of interactions with a textbox, I prefer making small examples as there is no canonical way to make them, only ways that works with your own projects. +- Add more effects - [ ] Add more examples + [ ] For tween-based character, factorize tween selection code? - [ ] Document the code as well as this file?