Expand description
The .dof file format is a json compatible format with specified fields describing any keyboard layout, including some defaults.
It has a set amount of (sometimes optional) fields:
-
name
: name of the layout -
[author]
: author of the layout -
board
: keyboard type the layout is made for. Any value is allowed, but a few values have special properties (explained further below):ansi
iso
ortho
colstag
-
[date]
: date the layout was created. -
[description]
: string containing some of the author’s thoughts. -
[link]
: url to a page with more information about the layout. -
layers
: specifies all layers on the layout. They’re of the form ofname: <layer>
, and each layer has rows specified by a string consisting of keys delimited by any amount of whitespace (but typically a space). They work like the following:- if the string length is 1, output:
- An empty key when it’s equal to
~
- A transparent key when it’s equal to
*
, which refers to the value on the main layer. This is equivalent to~
when on the main layer. - Enter when it’s equal to
\n
, - Tab when it’s equal to
\t
, - A character key otherwise.
- An empty key when it’s equal to
- if the string length is more than 1, output:
~
and*
characters if it contains\\~
and\\*
respectively,- A special key like shift or space when provided with specific identifiers which can be found at the bottom of the document,
- A layer key if it leads with an
@
, for example@altgr
- A word key with its first character removed if it leads with
#
,\\#
or\\@
, for example\\@altgr
would output@altgr
rather than become an altgr layer key, - A word key, which outputs multiple characters at the same time, otherwise.
All layer names are allowed though two are reserved, being:
main
(mandatory)shift
While main is mandatory to be filled, shift can be elided and will follow qwerty’s capitalization scheme. Any shape is allowed, but if you use a standard 3x10 shape, you may be able to elide a fingermap (more on this below).
- if the string length is 1, output:
-
fingering
: specifies which finger presses which key. It’s formatted the same as the layers object, and it should have the exact same shape (it will error otherwise):LP
or0
: left pinkyLR
or1
: left ringLM
or2
: left middleLI
or3
: left indexLT
or4
: left thumbRT
or5
: right thumbRI
or6
: right indexRM
or7
: right middleRR
or8
: right ringRP
or9
: right pinky
As alluded to above you can forego defining this completely and instead provide just a string instead in the following scenarios:
- board = ansi, main layer shape starts at qwerty
q
, allowed fingerings: traditional, standard, angle - board = iso, main layer shape starts at qwerty
q
with 11 keys on the bottom row, allowed fingerings: traditional, standard, angle - board = ortho, main layer shape = 3x10, allod fingerings: traditional, standard
- board = colstag, main layer shap = 3x10, allowed fingerings: traditional, standard
If any other value is provided, it should error.
§Special modifier values:
esc
=>Esc
,repeat
,rpt
=>Repeat
,space
,spc
=>Space
,tab
,tb
=>Tab
,enter
,return
,ret
,ent
,rt
=>Enter
,shift
,shft
,sft
,st
=>Shift
,caps
,cps
,cp
=>Caps
,ctrl
,ctl
,ct
=>Ctrl
,alt
,lalt
,ralt
,lt
=>Alt
,meta
,mta
,met
,mt
,super
,sup
,sp
=>Meta
,fn
=>Fn
,backspace
,bksp
,bcsp
,bsp
=>Backspace
,del
=>Del
,
Modules§
- Contains most types to represent elements of a keyboard layout with
- Contains some structs and functions that are used when interacting with the layout, like swapping two keys.
- Just exports everything the library offers
Macros§
- Macro for implementing functionality for
Fingering
andLayer
Structs§
- An anchor represents where the top left key on a
Dof
is compared to where it would be on a physical keyboard. For example, if you were to provide a 3x10 raster of letters but would like this applied to an ANSI keyboard, theAnchor
would be (1, 1), as the top left corner of theDof
(being where qwertyq
is) would need to be shifted one left and one up to be in the top left corner of the physical keyboard. Therefore, the default value of an anchor is dependent on the physical keyboard it is applied to. - A Key with metadata attached. These are produced by calling
Dof::keys()
. - A struct to represent the dof keyboard layout spec. This struct is useful for interacting with dofs and parsing to/from .dof using
serde_json
. For converting other formats into dofs, consider taking a look atDofIntermediate
. - The main error struct of the library. Internally it uses a Box containing
DofErrorInner
to save space. The other error types of this crate, beingDofinitonError
andDofInteractionError
, can be seamlessly converted intoDofError
with the?
operator. - Main struct to use for parsing, and a more or less literal interpretation of what a .dof file can contain. As its fields are public, this can also be useful for implementing
TryFrom<Type> for Dof
because at the end of that function you can callintermediate.try_into()
to handle all validation for you. - Struct that represents the fingering of each layout. It is an abstraction over
Vec<Vec<Finger>>
. - Used to represent the language(s) a layout is optimized for, containing the name of a language as well as a weight, the latter being useful for layouts that are made for a combination of languages with some amount of % split.
- An abstraction of
Vec<Vec<Key>>
to represent a layer on a layout.
Enums§
- Abstraction over the way an actual .dof file is allowed to represent the fingering of a layout, being either explicit through providing a list of fingerings for each key, or implicit, by providing a name.