TextArea — Gideros library for multiline text editing

n1cke

TextArea
TextArea is Gideros library to show and edit multiline and oneline texts. TextArea supports hardware and virtual (built-in) keyboard input. Text can be scrolled via mouse/touch and selected via mouse or virtual keyboard. All standard text operations are supported: Select All, Duplicate, Cut, Copy, Paste, Undo, Redo. If text can't fit into width and height vertical and horizontal sliders will appear to help with the navigation. Each text can have it's own colors and alphas of text, sliders, selection and cursor. Various alignment modes are available: left, right, center and justified with ability to suppress word breaks ('wholewords' setting). When text editing is finished TextArea will run callback if defined.

Virtual keyboard
Virtual keyboard is fully customizable from within itself: you can set each color, change font and sound, modify height, set cursor delays etc. More than 150 layouts is available for it in included keyboard layouts file (kblayouts.lua). Keyboard settings are automatically saved in a file ('keyboard.json' by default). It also automatically resizes when screen resolution changes and fits editable text. If you need to popup it without touch, for example for cursor settings, you can press "Menu" key on hardware keyboard.

API

◘ TextArea.new(t) creates TextArea instance accepts a table (t) where all parameters are optional: 'font': [Font] font for the text 'text': [string] text to display 'sample': [string] text to get top and height for lines 'align': ["L"|"C"|"R"|"J" or 0..1 or -1] left/center/right/justified 'valign': [number in 0..1 range] relative vertical positioning 'width': [number] to clip text width 'height': [number] to clip text height 'letterspace': [number] a space between characters 'linespace': [number] line height modifier 'color': [number in 0x000000..0xFFFFFF range] text color 'colors': [table] paragraph colors, can have a fraction for alpha 'wholewords': [boolean] only whole words in lines if enabled 'oneline': [boolean] fits all text into one line if enabled 'linechars': [number] maximum line length restriction (in characters) 'maxchars': [number] maximum text length restriction (in characters) 'undolevels': [number in 0.. range] levels for undo/redo operations 'curwidth': [number] cursor width in pixels 'curcolor': [number in 0x000000..0xFFFFFF range] cursor color 'curalpha': [number in 0..1 range] cursor alpha 'selcolor': [number in 0x000000..0xFFFFFF range] selection color 'selalpha': [number in 0..1 range] selection alpha 'sldwidth': [number] slider width in pixels 'sldcolor': [number in 0x000000..0xFFFFFF range] slider color 'sldalpha': [number in 0..1 range] slider alpha 'edit': [boolean] adds mouse/touch listener to focus and edit if enabled 'scroll': [boolean] adds mouse/touch listener to scroll if enabled 'callback': [function] (textfield, esc) to be called when editing is done 'native': [boolean] enables native onscreen keyboard if available NOTE: any missing parameter will be defaulted to TextArea.default one ◘ TextArea:update(t) updates TextArea with new values from table (t) accepts a table with same parameters as for TextArea.new ◘ TextArea.property gets property value 'property' is any parameter accepted by TextArea.new ◘ TextArea:setFocus(showkeyboard) to manually set focus on TextArea 'showkeyboard': [boolean] shows virtual keyboard if enabled NOTE: you cannot set focus on text without text width and height set ◘ TextArea:removeFocus(hidekeyboard) to manually set focus from TextArea 'hidekeyboard': [boolean] hides virtual keyboard if enabled NOTE: you cannot remove focus from text if you are not focused on it ◘ TextArea.setKeyboardFonts(fonts) sets fonts for virtual keyboard 'fonts': [table] list of fonts ◘ TextArea.setKeyboardSounds(sounds) sets sounds for virtual keyboard 'sounds': [table] list of sounds ◘ TextArea.setKeyboardLayouts(layouts, [langsPerRow], [lang], [lang2]) sets layouts for virtual keyboard 'layouts': [table] list of languages where language is list of layouts 'langsPerRow': [number greater than 0] langs menu columns number 'lang': [string, optional] sets main language 'lang2': [string, optional] sets extra language ◘ TextArea.setKeyboardOptions(options) sets options and/or colors for virtual keyboard 'options': [table] accepts same keys as Keyboard.default table

Keyboard Layouts
Can be set via `TextArea.setKeyboardLayouts(layouts)`.
All layouts are grouped into languages:
{lang1 = {...}, lang2 = {...}, ...}
Each language group can contain up to 8 main layouts at 1..8 indexes:
{l1, l2, l3, l4, l5, l6, l7, l8}
1: lowercase letters (shift: off, alt: off)
2: uppercase letters (shift: on, alt: off)
3: main symbols (shift: off, alt: on)
4: extra symbols (shift: on, alt: on)
5: bottom bar
6: colors menu
7: options menu
8: cursor menu
Each missing layout will be loaded from default layouts.
Each language group also supports extra layouts. Extra layout is an layout you can go to when you hold a key with this extra layout name.

Download:
https://github.com/Nlcke/TextArea/archive/master.zip

Screenshots

keszegh

thanks for sharing, can you also show some screenshots about these?

keszegh

i had a quick test, it's really something.
i don't know why 'en' keyboard is not some qwerty one, but then i've found 'en-6' which is what i expected from 'en'.
looking forward to the file-chooser built on top of this.

n1cke

@keszegh: I changed "en" layouts (Microsoft ones) to default ones (my own). Please, redownload and switch to another language and then switch back to "en". Soon I will return to Layout library and finish "file-chooser" example.

keszegh

your layout/gui library also looks cool, i checked the examples.

n1cke

@keszegh: thanks! I didn't post it yet because I want to make more examples to fully demonstrate it's power. I also have easy-to-use multiplayer library, but it needs more plugins. I will work on it and post it after Layout library.

antix

@n1cke, wow that's some awesome coding there! Thanks for sharing this

unlying

That's great!

pie

@n1cke Thank you for sharing, it's really cool and useful!

n1cke

UPDATE: added paragraph colors/alphas support. See new screenshot at first post.

n1cke

UPDATE2:
added 'valign' option: [number in 0..1 range] for relative vertical text positioning;
improved `align` option: it also supports numbers in 0..1 range and -1 as alias for justified text for consistency with new `valign` option;
added support of other Gideros scale modes, thanks to @hgy29.
added TextArea.setKeyboardOptions(options) function to set Keyboard defaults.

muro

@n1cke awesome job and many thanks. Is there a way just caching specific language charset instead of all the utf-8 characters? Application:getLocale() function may help for this?

n1cke

@muro: this is good idea so I attached helper library named 'tocache' for that. However it is up to you which charsets to use for concrete language because it is complex theme.
This library creates a string to use in TTFont cache:

-- usage: tocache(...) -- where ... is list of {num1, num2} ranges and/or "charsetnames" -- example: local cache = tocache('Basic Latin', {0x0186,0x0190})

muro

@n1cke , You have an elegant code style, thanks again for this useful helper.

totebo

I'm using Strict.lua which checks for undeclared global variables and crashes if it finds them (attached). TextArea causes a couple of crashes for the undeclared global variables "length" and "colors". I've marked them nil in the code, which solves it, but may be worth adding a more solid fix.

n1cke

UPDATE:
◘ native onscreen keyboard support for iOS and Android, thx to @hgy29. Use `TextArea.setKeyboardOptions{native = true}` to enable it in your app.
◘ new parameter `linechars` to limit width of textarea in characters
NOTE: since Gideros doesn't know native keyboard height TextArea assumes it is half of the screen. Let's hope @hgy29 will add `application:getKeyboardHeight` method

keszegh

thanks for the updates.
application:getKeyboardHeight would be indeed important in this case.

grotly

@n1cke For the native keyboard (Android) the backspace does not seem to work.

unlying

Don't why but it doesn't support cyrillic for me. It's show cyrillic characters and don't type them.

n1cke

MINOR UPDATE: backspace support for native keyboard and font cache changed to 2048 to display cyrillic chars in TextArea example. Please, redownload the project.

Also note: Gideros cannot display noncached chars from cached fonts. In my TextArea example I have just used the following trick to cache a range of characters:

local chars = {} for code = 1, 1024 do chars[#chars+1] = utf8.char(code) end local font = TTFont.new("NotoSans.ttf", 30, table.concat(chars))

Every char from #1 to #1024 have been cached. To add cyrillic chars (they are somewhere after #1000 char) I have just increased max value to 2048 in updated example.

unlying

Yeah! It works!

totebo

I get a crash without an error message when I try to up it to 2048 with my font. Is there a way to catch an error and stop when it happens?

totebo

Amazing idea though, this will save me a lot of time when using translations because I don't have to go through all the text to figure out which chars are needed.

n1cke

Yep, Gideros crashes when it tries to cache missing characters. This should be fixed in Gideros source code.

totebo

Added to Github:
https://github.com/gideros/gideros/issues/319

pie

Hi, is it possible to show a default text in an editable text area that clears itself when the user clicks to edit?

SinisterSoft

This should be updated to have the predefined chrs set to "" - that way Gideros will use multiple textures (so it won't crash if the space for the characters outsizes the texture size) and also just add characters that are actually used.

pie

The 2017.9 font caching addition is a blessing to textarea speed thanks

hgy29

If you knew what we are preparing for 2017.10 ...

pie

I already like it, on trust..

Unknown

I like this too