Document layout XML format

[JapanYoshi]

I think there should be a formal documentation of how to write a custom layout file for Unexpected Keyboard, including a list of special key values, how to modify what characters appear when Shift is pressed, and other pain points or little-known features. If there is already, it should be linked in the Readme.

The Wiki for this repo is empty, so that could be used for that purpose.

[Julow]

If anyone wants to contribute on this, the resources I'm aware of are the comment in Qwerty (US), the implementation and @Lixquid's online editor.

[JapanYoshi]

https://github.com/JapanYoshi/DocumentXML/wiki/Custom-layouts Opened my own branch here to be merged later.

[Spike-from-NH]

This is very helpful! May I collaborate, or must I wait until you are done and fork a copy to make edits?

[JapanYoshi]

This is very helpful! May I collaborate, or must I wait until you are done and fork a copy to make edits?

Please do contribute in place!

[Spike-from-NH]

Thank you! but I don't seem to be able to. Pressing the link logo appends ?action=edit to the URL, but the effect is to return to viewing the whole page.

[Spike-from-NH]

Future additional sections: ① Under Structure, a brief overview of writing XML; some tags are paired to surround content, like <row>...</row>; some are auto terminating, like <key.../> ② Where to find the stock QWERTY layout, to use as a starting point. ③ What to do with the XML once you've produced it: The "Add layout" in Settings; the copypaste method. ④ A pointer to the online tool for producing layouts by gestures.

[Spike-from-NH]

Additional info for the "Keyboard metadata" section: ① name= is optional. It is commentary to describe the layout or distinguish it from others you've done—so it could include the date or your revision number. If present, the text will appear in the Layout section of Settings. If omitted, Settings will identify your layout only as "Custom layout". ② Optional bottom_row= defaults to "false", in which case Unexpected provides a bottom row with space bar and other useful keys. It's recommended to use the default bottom row, to benefit from future enhancements. If a layout specifies "true", then the layout must define any bottom row itself.

[Spike-from-NH]

Additional info for the "Row" section:

The total height of the keyboard is defined in Settings as a percentage of the total height of the screen. This can be different for Portrait and Landscape. The default height of a row is the keyboard's height divided by the number of rows the layout defines (plus the default bottom row provided by Unexpected, whose height is always 1). <row height="1"... selects this default row height. A larger number makes the row taller—but makes other rows narrower, because the total keyboard height is still constrained by Settings.

[Spike-from-NH]

Finally, remember Julow's recent work that Unexpected remembers which layout is active in each of Portrait and Landscape, so a user can have two custom layouts to make the effective layout vary on this basis.

Thanks again!

[JapanYoshi]

All added.

[Spike-from-NH]

Thank you! As for What does indication do? It produces a "keycap legend"; see my #613.

[Spike-from-NH]

Error in Crash course; you say a closing tag ends with / —In fact, it begins with /. I suggest you also enhance the nearby examples, <row> and <keyboard>, to include the closing tag.

[JapanYoshi]

Thank you! As for What does indication do? It produces a "keycap legend"; see my #613.

Can swipe legends be changed like that too?

[Spike-from-NH]

I've been asking for that, but it seems indication creates a single legend for the key (at the bottom; it was originally used to add mnemonics like ABC on the telephone keypad). This is confirmed by the syntax; indication is not captive to a single swipe specification such as key1=.

[JapanYoshi]

Added a description for slider

[alotbsol555]

this is already really good and I learned some new things!

one suggestion: the function of the "slider" key seems to be more genaral and is not limited to the left/right movement, when used on different keys other than the default space bar.

the description in the linked GUI based editor on lixquid.com is more more accurate in my opinion:

"Slider" keys are keys that will activate their Left Key and Right Key inputs by sliding your finger across the key.

I'm not sure if it is ok to copy this exactly…

maybe add: This is most commonly used on the default space bar for left and right cursor movements.

[alotbsol555]

another suggestion for the "action" key:

Perform the action in the current context, such as Go, Done, Search, Next, Previous, Send. The title of the key is automatically set depending on the current context.

[JapanYoshi]

another suggestion for the "action" key:

Perform the action in the current context, such as Go, Done, Search, Next, Previous, Send. The title of the key is automatically set depending on the current context.

Isn’t that just enter? I have my keyboard using enter, and the text is automatically set to Go, Search, etc.

[alotbsol555]

another suggestion for the "action" key:

Perform the action in the current context, such as Go, Done, Search, Next, Previous, Send. The title of the key is automatically set depending on the current context.

Isn’t that just enter? I have my keyboard using enter, and the text is automatically set to Go, Search, etc.

they are related but not identical. just put both of them on the same button and see what happens in different fields. as long as you are in a simple text input field, the enter key is just the new line arrow. when you're in a search field the "enter" key becomes the action "search" (like you described) and the action key becomes the new line arrow.

only with both keys present in your layout you are always able to insert a new line.

so, the enter key "primarily" inserts a new line and switches to an action when needed. the action key "primarily" performs an action and switches to the new line when needed.

[alotbsol555]

according to the documentation, this should work, or am I doing something wrong?

<modmap>
    <fn a="i" b="İ" />
</modmap>

there is an error shown in the editor ("expecting tag <shift> and got <fn>") and the layout becomes unusable (be sure to have another working layout before testing this).

using shift instead of fn works fine as described. is this a bug or does the documentation needs to be changed/improved with a working example?

[JapanYoshi]

You’re right, I read somewhere that fn works, but it evidently doesn’t. func doesn’t either. I’m unsure what’s supposed to happen there.

[Julow]

That's fantastic, thanks you all! And thanks @JapanYoshi for starting this!

I'd suggest that the list of all the keys are in a different page to make the page less intimidating.

The tag encloses custom mappings for the Shift and Fn key’s behavior. It supports two tags: and .

Fn is not supported by this, only Shift is.

Keyboard metadata

Other scripts currently used by layouts are: arabic, armenian, bengali, cyrillic, devanagari, gujarati, hangul, hebrew, persian, shavian, urdu

An other optional property: numpad_script. It specifies the script to use for the numpad. If it's absent, the same value as the script property is used.

offset: How much empty space to add to the left of this key. Defaults to 0 and accepts a non-negative floating point value. TODO: Find out if negative values are actually ignored

key0 through key8 take arbitrary strings of characters, and if they don't match any of the special values, it is printed verbatim. TODO: Is this intentional behavior?

That's intended. If the specified key is not a key with a special meaning defined in KeyValue.java, then it's a "string" key that outputs the specified string.

Literal tab character. TODO: Is this actually different from tab?

Yes, the two might be different on some text-editor apps or on some websites.

No-break space. TODO: Is there a way to send Narrow NBSP recommended in French?

No, please add it :)

Select all. Equivalent to Ctrl+A. Oddity: This is in CamelCase.

The camel casing is a mistake. We could have a snake case alias for this key, code welcome :)

cursor_left TODO: What's the difference between this and left?

The left key just sends a "arrow left" key event while the cursor_left changes the cursor position directly. It's used for the spacebar slider. When the cursor is at the beginning of a text field, the former might jump into a previous text field while the later won't do anything.

accent_arrow_right TODO: What does this do?

This types a right arrow on top of an other character using this combining character: https://unicode-table.com/en/20D7/

All the combinations are implemented in KeyModifier.java.

voice_typing_chooser TODO: What does this do?

This starts voice typing but first let you choose the voice typing app.

Placeholders

These key are not rendered and do nothing when typed. They are intended to be replaced to other keys when some modifiers are used.

Keys prefixed with loc do not appear by default, and are only visible when they are enabled through the "Add keys to keyboard" option in the settings menu.

They are also added to the keyboard depending on the languages installed on the device, according to res/xml/method.xml.

[JapanYoshi]

Updated.

[Spike-from-NH]

I'd suggest that the list of all the keys are in a different page to make the page less intimidating.

That's a good design goal. If Github wikis are real wikis, there are several techniques to avoid overwhelming the reader: ① Subpages. The main page can give an overview and guide the reader to a subpage for details. ② Index. Some people like the classic Unix alphabetical presentation, but you can have an index page with an alphabetical list, where each element is a wikilink to the location in the page that gives details. Like my Statement Index at https://rfobasic.miraheze.org

[Spike-from-NH]

@JapanYoshi, the compass-point alternatives proposed in #495 are now merged. Instead of key1=, you can write nw= as in "northwest". The old way still works—but you can't specify both old+new! Would you please mention this in the wiki?

[JapanYoshi]

Is key0 unchanged?

[Spike-from-NH]

That's right; it has no synonym, only the swipes, which can now (1.28?) be referenced as nw, ne, sw, se, w, e, n, and s.

[JapanYoshi]

Added.

I think the documentation is ready to be copied over to the Wiki of the main project. If that's done, I'll close this issue.

[Spike-from-NH]

@JapanYoshi, I think @Julow must do this.

I remain confused on whether GitHub wikis are real wikis (group-editable but also open to vandalism) or like other pieces of the project, changed only by commit and merge by the owner.

Ultimately, this should not be the main wiki's home page, as editing custom layouts is only one piece of learning about Unexpected.

And the incomplete tutorial at the start of QWERTY.xml et al. should be replaced by a link to this wiki page.

[Julow]

I've made a full review and I think this is almost ready to be included. Thanks for this ! I have a few remarks below.

Wikis on Github are not collaborative wikis but instead a separate git repository containing markdown files. There's no pull request system for wikis and I find them not ideal in this case.

I suggest having the documentation in a doc folder in the same repository as the code. This way, the documentation is in a more discoverable place, can be updated at the same time as the code, and can eventually be embedded into the app. If you agree with this idea, please make a PR.

• Note: No backward compatibility is guaranteed. The layout schema might change if that's needed to improve the app.

• The second sentence should be dropped in

  The tag encloses custom mappings for the Shift and Fn key’s behavior. It supports one tag: .

• The tables for the edge symbols in the Key section don't look great due to the first row being turned into a header row. Perhaps ASCII art into code block would look better ?

• This attribute is called shift, not offset. A negative value will make the keyboard render incorrectly. If anyone has some time to implement bound checks :)

  offset: How much empty space to add to the left of this key. Defaults to 0 and accepts a non-negative floating point value. TODO: Find out if negative values are actually ignored

• slider: It affects key5 and key6 only. Note: It will change in the future.

• The "Virtual keys" contains a lot of duplicated text and takes a lot of space. What do you think of turning it into a non-structured list ? Also, the modifiers could be denominated as such.

• F13 to F24 are not supported by the Android SDK.

  F13 throught F24 are not supported, because no Android apps actually use those.

• It should be added to the app!

  No-break space. Note: To input the narrow no-break space recommended for French, use \u202F.

• cursor_left and cursor_right do not belong in the "Virtual shortcuts" section. They are "Keyboard editing keys" (the keyboard takes care of the editing) while the other "Virtual shortcuts" are "Android editing commands" (sent to text boxes that support them).

• compose is not dedicated to diacritics and can do much more. For example <Compose> = e outputs €.

• I think these don't need a description and can be a list, just like the "Virtual keys".

  TODO: I don't know Hebrew, so I can't describe these.

• switch_back_emoji is useless in a layout.

• change_method opens the keyboard picker dialog while change_method_prev immediately switches to the previously used keyboard.

• f11_ and f12_placeholder are used to place the F11 and F12 on the layout. These keys are removed from the keyboard unless the Fn modifier is activated. removed is for internal use and shouldn't be mentionned.

[Spike-from-NH]

Thanks for the explanation! If these wikis are not true collaborative wikis, I agree that a /doc folder of the code base is a better location—especially if the markdown lets you link to subpages to minimize intimidation.

[sdrapha]

Maybe a better approach to not spam the code base with documentation commits and PRs, and also to take advantage of some github features, it would be better to do a separate repo, and use github.io pages. That would properly organize dev environments too, code languages, and github actions and integrations. Documentation CI actions are different than the apk builds, so different repos would properly enable that in an organized way.

[Julow]

I want to review changes to the doc as carefully as in the code and I want them updated both at the same time. A separate repository is a blocker for that.

The better looking github.io URL is from this repository too, and it can be updated automatically using a Github Action (if anyone is interested in looking at that). The wiki can also be updated using a Github Action but I found out that I can remove the wiki tab, so I did. Let's discuss that after the doc is in the doc folder.

Let's discuss dev environments in an other issue, could you open an issue ? I would like to make contributing easier.

[Spike-from-NH]

Concur; it doesn't "spam the code base" to have change history for documentation. Those who don't want the history will read the current version, as they do of the code.

If anyone has some time to implement bound checks :)

I could do it, @Julow, but this particular bound check seems like a single line of Java and you could do it faster. If you will raise a new issue enumerating all the additional checking you would like, I'll take it.

[Julow]

@JapanYoshi Could you copy all the doc into .md files in a new doc/ folder in this repository ?

[JapanYoshi]

https://github.com/Julow/Unexpected-Keyboard/pull/643

[Julow]

Thanks you all for this awesome document! https://github.com/Julow/Unexpected-Keyboard/pull/643 is merged and will possibly be kept uptodate as the app evolves.