Key event

General

The Key event informs us of the fact that the user pressed a key on the keyboard and allows us to suppress it, add something to it or give it an own interpretation. The key event is the most useful of the celx event types but it's use is still very limited. You can use it to create a menu or other type of question, that requires a one-letter answer.

Celestia reports [Key], [Shift]+[Key] and [Control]+[Key] combinations. None of the [Alt]+[Key] combinations however and [Ctrl]+[Shift]+[Key] combinations are not supported either but are reported as [Ctrl]+[key] combinations, so pressing [Ctrl]+[Shift]+[A] has the same result as pressing [Ctrl]+[A].

In other object oriented type environments "key state" info like [Shift] would be part of the event data packet (message); somewhat like this:

message{
   char     = string: the character pressed,
   shift    = boolean: the shift key was or was not pressed,
   control  = boolean: the control key was or was not pressed,
   alt      = boolean: the alt key was or was not pressed
   }

Something like a Capital A would in this method be represented like this:

message{
   char     = "a",
   shift    = true,
   control  = false,
   alt      = false
   }

Not in Celestia.celx however; there the event message exists of only one field: "char" that combines both character ánd state information. For the keyboard key [A] for example this would result in one of the following:

Key pressed         Value of message.char
-----------         ----------------------
[A]                = "a"
[Shift]+[A]        = "A"
[Ctrl]+[A]         = "C-a"
[Ctrl]+[Shift]+[A] = "C-a"
[Alt]+[A]          = no event

Not all key's yield a key event; the ones that don't comprise keys like the function and cursor keys and the Escape key. Manufacturer specific keys, like the Windows key don't have a meaning in Celestia.

Example

The general page on Celx Events already shows an example for a key event handler; the example below is not as much a demo as it is a tool that comes in handy when you want to test which keys do and which don't generate a key event. It is also available as a download at the bottom of this page.

--[[ Function: keyEvent()
------------------------------------------------------------------------
   the keyboard event handler
------------------------------------------------------------------------]]
function keyEvent(eventInfo)
   if intercept == false then                                                   -- if not intercepting
      if eventInfo.char == "i" or eventInfo.char == "I" then                    -- and if it is an "i"

intercept = true -- then start intercepting

         celestia:print("Started key interception\npress i again to stop", 2)   -- inform the user
         return true                                                            -- celestia ingnore event
      else                                                                      -- but if it is not an "i"
         return false                                                           -- celestia handle event => don't intercept
      end
   else                                                                         -- we are intercepting
      if eventInfo.char == "i" or eventInfo.char == "I" then                    -- if it is an "i"
         intercept = false                                                      -- then stop intercepting
         celestia:print("Stopped key interception\npress i again to start", 2)  -- inform the user
         return true                                                            -- celestia ignore event
      else                                                                      -- but if it is not an "i"
         celestia:print("keyEvent.char = " ..eventInfo.char)                    -- print the character

return true -- celestia ignore event => intercept

      end
   end
end
--[[ Function: Main()
------------------------------------------------------------------------
   the function Main
------------------------------------------------------------------------]]
function Main()

intercept = false -- preset intercept to false

celestia:registereventhandler("key", keyEvent) -- register the event handler

celestia:print("Key test is active\npress i to start intercepting keys", 4)-- inform the user

end
--[[ Script
------------------------------------------------------------------------
   start
------------------------------------------------------------------------]]
Main()                                                                         -- start the main function

Pressing the [i] key toggles the variabel "intercept" between true and false. If intercept == true then the event handler intercepts all key presses execpt for the [i]. If intercept == false all key presses are processed by Celestia the default way.

Celestia inconsistencies:

Not all key presses result in an event and not all result in what you would expect. Pressing the [Enter] key for instance results in "C-m" and pressing [Ctrl]+[Enter] in "C-j". So before you start using certain key combinations, you'd better write a little test script to see what happens. Or download the tool in the example.

The keys:

    • a = increase velocity
    • z = decrease velocity

ignore the return value of the custom keyboard event handler. If that value is true Celestia shoud ignore the key press and not change the velocity. It does however change the velocity no matter whát the return value is. The keys should therefore not be used as menu keys. It is possible that there are more keys for which Celestia shows this behaviour. I have not tested all keyboard keys for this symptom.

According to a post on the Celestia scripting forum

    • http://www.shatters.net/forum/viewtopic.php?f=9&t=12702&p=106526&hilit=keyboard+event+a#p106526)

the following Ctrl+letter combinations can not be used wit the key event and therefore their corresponding standard commands can't be overriden:

    • Ctrl+A : Toggle atmospheres
    • Ctrl+E : Toggle eclipse shadow rendering
    • Ctrl+Y : Toggle autoMag
    • Ctrl+Q : Quit
    • Ctrl+L : Toggle night side planet maps
    • Ctrl+C : Copy location URL to clipboard

Downloads