Jump to content

Celestia/Celx Scripting/CELX Lua Methods/Callback

Add links
From Wikibooks, open books for an open world

Keyboard

[edit | edit source]

boolean celestia_keyboard_callback(string:char)

The callback for keyboard input must have the name "celestia_keyboard_callback". After a script activates the handling keyboard-input by calling celestia:requestkeyboard(true) (see celestia:requestkeyboard()), any keypress will result in a call to a method with this name.

The callback can return either true or false, indicating that it either has handled the keypress or that Celestia should continue normal processing for this key. Not returning any value is the same as returning true.

Arguments:

char
The method should accept one parameter, a string, which holds the character of the key which has been pressed.
  • Accented characters like ä or é will be passed as UTF-8 sequences, i.e. as a multibyte sequence - if you only want to handle ASCII you can safely ignore this.
  • Keys like CTRL-A are passed as strings containing a char with ASCII-codes < 32, as are Enter (13) or Backspace (8).

Notes:

  1. Some special keys like the cursor-keys or [Esc] key won't activate the callback.
  2. If an error occurs while processing the callback, the error message will be written to the console log (made visible with the tilde [~] key on the keyboard, or [~] + [Spacebar] on some systems) and an implicit false is returned, i.e. Celestia will continue processing for this key.

Example:
The following example code can be used to run some specific CELX code when the user presses the [1] or [2] key on the keyboard. 

-- Initialize variable to have no content:
last_pressed_key = nil

-- Define functions section:
function celestia_keyboard_callback(key)
   last_pressed_key = key
   return true
end

function get_pressed_key()
   last_pressed_key = nil
   celestia:requestkeyboard(true)
   while true do
      if last_pressed_key ~= nil then
         key = last_pressed_key
         last_pressed_key = nil
         celestia:requestkeyboard(false)
         return key
      end
      wait(0.1)
   end
end

-- Main CELX script section:

-- Section within your script, where you want to handle keyboard input:
key = get_pressed_key()
if key == "1" then
   valid_key = true
   celestia:print("Pressed the [1] key", 5.0, -1, -1, 2, 4)
   wait(5.0)
   -- You can add more CELX code here, specific to the [1] key
elseif key == "2" then
   valid_key = true
   celestia:print("Pressed the [2] key", 5.0, -1, -1, 2, 4)
   wait(5.0)
   -- You can add more CELX code here, specific to the [2] key
else
   valid_key = false
   celestia:print("Pressed invalid key", 5.0, -1, -1, 2, 4)
   wait(0.1)
end

if valid_key then
   celestia:print("The [1] and [2] keys are valid keys", 5.0, -1, -1, 2, 4)
   wait(5.0)
   -- You can add more CELX code here, specific to both the [1] and [2] keys
end

Cleanup

[edit | edit source]

function celestia_cleanup_callback()

Whenever a Lua script terminates (because it ended, the user terminated it by pressing the [Esc] key or an error occurred), Celestia will try to execute a function with the name "celestia_cleanup_callback".

This function can be used to perform any cleanup actions, notably restoring settings to the values in use before the script started. Within a CELX script, many Celestia options can be set that differ from the standard settings of a user. By using this Cleanup callback function, settings can be reset to the way they were before running the script.

The use of this Cleanup function is essential to program your CELX scripts user friendly !

Notes:

  1. Errors will only be reported in the console log (made visible with the tilde [~] key on the keyboard, or [~] + [Spacebar] on some systems).

Example:
The following example code can standard be inserted at the beginning of any CELX script (using Celestia version 1.6.1 or later), to restore the Celestia settings to the way they were before running the script and to initialize those setting to the way you like them within your CELX script.

Note: When using older Celestia versions, watch the comments in the example to remove some code, so the example also works with Celestia version 1.5.0, version 1.5.1 and version 1.6.0. 

-- Define Cleanup function to restore the settings
-- to the way they before running the script.

function celestia_cleanup_callback()
   celestia:setrenderflags(orig_renderflags)
   celestia:setlabelflags(orig_labelflags)
   celestia:setorbitflags(orig_orbitflags)
   celestia:setambient(orig_amb)
   celestia:setfaintestvisible(orig_faintest)
   celestia:setminorbitsize(orig_minorbit)
   celestia:setstardistancelimit(orig_stardistance)
   celestia:setminfeaturesize(orig_minfeature)
   celestia:setstarstyle(orig_starstyle)
   celestia:settime(orig_time + (celestia:getscripttime() / 24 / 3600) )
   celestia:settimescale(orig_timescale)
   celestia:setgalaxylightgain(orig_galaxylight)
   celestia:getobserver():setfov(orig_fov)
   celestia:getobserver():setlocationflags(orig_locationflags)
   celestia:getobserver():singleview()
   celestia:setoverlayelements(orig_overlay)
   celestia:setaltazimuthmode(orig_altazimuthmode)
   -- Comment next line if NOT using Celestia v1.6.0 or later
   celestia:settextureresolution(orig_textres)
   -- Comment next line if NOT using Celestia v1.6.1 or later
   celestia:settextcolor(orig_txt_r,orig_txt_g,orig_txt_b)
end

-- immidiatily followed by the following code to obtain the
-- current user settings and save them during the script.

orig_renderflags                 = celestia:getrenderflags()
orig_labelflags                  = celestia:getlabelflags()
orig_orbitflags                  = celestia:getorbitflags()
orig_amb                         = celestia:getambient()
orig_faintest                    = celestia:getfaintestvisible()
orig_minorbit                    = celestia:getminorbitsize()
orig_stardistance                = celestia:getstardistancelimit()
orig_minfeature                  = celestia:getminfeaturesize()
orig_starstyle                   = celestia:getstarstyle()
orig_time                        = celestia:gettime()
orig_timescale                   = celestia:gettimescale()
orig_galaxylight                 = celestia:getgalaxylightgain()
orig_fov                         = celestia:getobserver():getfov() 
orig_locationflags               = celestia:getobserver():getlocationflags()
orig_overlay                     = celestia:getoverlayelements()
orig_altazimuthmode              = celestia:getaltazimuthmode()
-- Comment next line if NOT using Celestia v1.6.0 or later
orig_textres                     = celestia:gettextureresolution()
-- Comment next line if NOT using Celestia v1.6.1 or later
orig_txt_r,orig_txt_g,orig_txt_b = celestia:gettextcolor()

-- The following initialization part can be customized
-- by the wishes of the CELX writer to the way he/she
-- wants the settings to be during the script.

celestia:setorbitflags{Planet = true,
                       Moon = false,
                       Asteroid = false,
                       Comet = false,
                       Spacecraft = false,
                       Invisible = false,
                       Unknown = false,
                       DwarfPlanet = false,     -- Comment line if NOT using Celestia v1.6.0 or later
                       MinorMoon = false,       -- Comment line if NOT using Celestia v1.6.0 or later
                       Star = false             -- Comment line if NOT using Celestia v1.6.0 or later
                      }

celestia:setrenderflags{atmospheres = true,
                        automag = true,
                        boundaries = false,
                        cloudmaps = true,
                        cloudshadows = true,
                        comettails = true,
                        constellations = false,
                        eclipseshadows = true,
                        galaxies = true,
                        grid = false,
                        markers = false,
                        nebulae = false,
                        nightmaps = true,
                        orbits = false,
                        planets = true,
                        ringshadows = true,
                        stars = true,
                        smoothlines = true,
                        lightdelay = false,
                        partialtrajectories = false,
                        ecliptic = false,       -- Comment line if NOT using Celestia v1.6.0 or later
                        equatorialgrid = false, -- Comment line if NOT using Celestia v1.6.0 or later
                        galacticgrid = false,   -- Comment line if NOT using Celestia v1.6.0 or later
                        eclipticgrid = false,   -- Comment line if NOT using Celestia v1.6.0 or later
                        horizontalgrid = false  -- Comment line if NOT using Celestia v1.6.0 or later
                       }

celestia:setlabelflags{planets = false,
                       moons = false,
                       spacecraft = false,
                       asteroids = false,
                       comets = false,
                       stars = false,
                       galaxies = false,
                       locations = false,
                       constellations = false,
                       i18nconstellations = false,
                       openclusters = false,
                       nebulae = false,
                       dwarfplanets = false,    -- Comment line if NOT using Celestia v1.6.0 or later
                       minormoons = false,      -- Comment line if NOT using Celestia v1.6.0 or later
                       globulars = false        -- Comment line if NOT using Celestia v1.6.0 or later
                      }

celestia:setambient(0.05)
celestia:setfaintestvisible(7)

-- Make your standard Star Style choice below by 
-- commenting/uncommenting one of the following lines:
celestia:setstarstyle("point")
-- celestia:setstarstyle("fuzzy")
-- celestia:setstarstyle("disc")

-- End of initialization part of the script
Retrieved from "https://en.wikibooks.org/w/index.php?title=Celestia/Celx_Scripting/CELX_Lua_Methods/Callback&oldid=3451854"