Conversation
added Keyboard Input to menu as discussed
stevesims
left a comment
stevesims
left a comment
There was a problem hiding this comment.
looking great!
I've made some suggestions for some improvements. if you'd like to address them that'd be great, but I'd be happy to merge this in as-is...
we should probably also think about adding links into this document from other parts of the documentation, where appropriate - but that can be done as a later exercise
docs/mos/Keyboard.md
Outdated
| You can also do a simple test to see if any of the _keys_ are pressed. | ||
|
|
||
| The byte at offset $18 (sysvar_vkeydown) after IXU provides an indication if there are any keys pressed. |
There was a problem hiding this comment.
this is not actually true...
this sysvar actually just reflects the "keydown" byte of the last vdp protocol keycode packet that was received. so if the user has pressed down multiple keys and then releases one of them this value would be a zero, even tho there are other keys still pressed
if this value is true then you know that at least one key is being held down, but if it's false you don't actually know whether any keys are being held, just that a key was released
docs/mos/Keyboard.md
Outdated
|
|
||
| There are several different methods of reading the keyboard from within your code, each with advantages and disadvantages, so the method selected will depend on your specific need at that point in your code. You don't have to stick with one method, you can choose the best for a particular task. | ||
|
|
||
| ## Method 1 - mos_getkey |
There was a problem hiding this comment.
it'd probably be nice/sensible to add in links to the API documentation that corresponds to commands
I had written something here about how sometimes this can be complex, owing to how markdown auto-generates APIs, and how it can help to add in explicit IDs instead which has been done in several places in the docs... there's quite a lot of them inside the VDU-Commands.md file, for example...
but I think that for linking to explicit individual MOS APIs we probably don't need to worry about that, so this could just do:
| ## Method 1 - mos_getkey | |
| ## Method 1 - [`mos_getkey`](./API.md#0x00-mos_getkey) |
NB in general our MOS API documentation shows API names using a "code" style, hence the back-ticks
docs/mos/Keyboard.md
Outdated
| ld a, $00 ; put $00 into A | ||
| rst.lil $08 ; make a MOS call with command $00 (mos_getkey). | ||
| ; system will wait until a key is pressed, then... | ||
| ; A now contains the ascii code of the pressed key |
There was a problem hiding this comment.
stylistically this doesn't match examples we currently have inside the MOS API.md file... that generally has opcodes in all caps, hex numbers with an h suffix, and generally zeros haven't been given any suffix.
the documentation for MOS APIs themselves use 0x00 style for the API number
I was going to say that the use of "command" in the comment here also feels wrong, since it makes me think of the CLI and star-commands, but actually this is the terminology currently used in the API.md file... I kinda think that we should probably be referring to them as APIs to help maintain a clearer separation, but that's not something we need to address right now
|
|
||
| ## Method 2 - Single Key Checks | ||
|
|
||
| The MOS API command `mos_sysvars` returns a pointer to the base of the MOS SysVars (system state variables/information) area in IXU as a 24-bit pointer. |
There was a problem hiding this comment.
we should really be linking to the mos_sysvars API docs here (at ./API.md#0x08-mos_sysvars), and the docs on the sysvar values (at ./API.md#sysvars)
in general our API docs use code-style for register names, like IXU
docs/mos/Keyboard.md
Outdated
| ld a, $09 ; put $09 into A | ||
| ld hl, myBuffer ; HL is where the string data will be stored once entered | ||
| ld bc, 32 ; BC is the max length of string to be captured | ||
| ld e, 1 ; E contains flags. 1 = buffer will be cleared before use |
There was a problem hiding this comment.
It'd probably be sensible to add some text above about these flags, and what the default behaviour of the line editor is.
by default, hotkey support is enabled, as is the input history, which in many cases may not be desirable/appropriate behaviour
|
|
||
| There may be times when you want a user to enter some text, or even just a number. The MOS API provides a useful method of allowing the user to type in as string of text without the programmer having to deal with every key press. | ||
| The programmer needs to define a buffer of bytes where the typed in string will be stored and then invoke the `mos_editline` command. Note that the buffer needs to allow an extra byte for a $00 terminator. So, a 32 byte buffer will be 31 string characters, plus the $00 terminator. | ||
|
|
There was a problem hiding this comment.
might be worth documenting a bit more about the features of the line editor. for instance, it supports cursor movement within the input via arrow keys, which includes the up/down arrows moving the cursor up or down a row within the input - this respects the currently set text viewport on the VDP. there's a global "input history" which keeps track of up to the last 10 inputs which is enabled by default. the OS-provided "hotkey" system is also supported, also enabled by default... there's also optional tab-completion for MOS commands and filenames that can be turned on
(I should probably add in an extra flag to allow for tab-completion to work only for filenames...)
typo Co-authored-by: Steve Sims <steve_sims7@yahoo.co.uk>
typo Co-authored-by: Steve Sims <steve_sims7@yahoo.co.uk>
better sentence.
2 participants
First draft at some notes on different keyboard input methods.
Also, index page to provide link.