Difference between revisions of "Os.pullEventRaw"

From ComputerCraft Wiki
Jump to: navigation, search
(Added os,pullEventRaw page, mainly information about how to prevent termination)
 
(Fleshed out a bit. Notably, the filter will not prevent it from returning terminate events.)
 
Line 6: Line 6:
 
  |returns={{type|string}} event, variable parameters(see table below)
 
  |returns={{type|string}} event, variable parameters(see table below)
 
  |addon=ComputerCraft
 
  |addon=ComputerCraft
−
  |desc=Waits (yields) until any event occurs (including 'terminate')
+
  |desc=Near identical to [[os.pullEvent|os.pullEvent()]]; however, it is capable of returning [[terminate (event)|terminate events]] (rather than halting your script when encountering them).<br><br>
 +
 
 +
Note that if a terminate event ''is'' encountered, os.pullEventRaw() will return it ''even if'' a filter specifying a different type of event is used.
 
  |examples=
 
  |examples=
 
{{Example
 
{{Example
−
|desc=The program detects when the user attempted to terminate the program, informs them when they did so then quits.
+
|desc=The program detects when the user attempted to terminate the program, informs them when they did so, then quits.
−
|code=
+
|code= local running = true
−
local running = true
+
 
  while running do
 
  while running do
 
     [[print]] ("Hello. Hold Ctrl + T to terminate (quit) this program.")
 
     [[print]] ("Hello. Hold Ctrl + T to terminate (quit) this program.")
Line 24: Line 25:
  
 
== Special Uses ==
 
== Special Uses ==
−
Apart from the ability to detect when the user tries to terminate the program, os.pullEventRaw is identical to [[os.pullEvent]]. The main use is to prevent the user from quitting your program. This can be useful in programs such as door locks when you don't want the user interfering with the computer.
+
Apart from the returning terminate events instead of actually terminating scripts when encountering them, os.pullEventRaw is identical to [[os.pullEvent]] - as such it is generally used to prevent users attempting to exit your code unless it's under your terms. This can be useful in programs such as door locks when you don't want the user interfering with the computer, or when you want to ensure certain "shutdown" operations are performed before your script exits.
 +
 
 +
The quickest and easiest way to prevent people from terminating (especially pre-made) programs is to add the following to the top of your code:
 +
os.pullEvent = os.pullEventRaw
 +
 
 +
All references to os.pullEvent from that point on will then point to THIS function, and as such, Ctrl+T (the terminate key combo) won't kill scripts unless they're specifically coded to respond to it. Note that Ctrl+R (the reboot key combo) cannot be "disabled" in such a manner.
 +
 
 +
If you're intending for the program to eventually exit, it is strongly recommended to re-instate the original function pointer (as it'll otherwise be lost until the computer reboots!). This can be done by storing a copy of it before redirecting os.pullEvent, eg:
  
−
The quickest and easiest way (especially in pre-made programs) to prevent people from terminating your program is to add the following to the top of your code:
+
local oldPullEvent = os.pullEvent
 
  os.pullEvent = os.pullEventRaw
 
  os.pullEvent = os.pullEventRaw
  
−
This replaces [[os.pullEvent]] with os.pullEventRaw and as such it will catch the 'terminate' event. If you do this, however, it is important to add a method for the user to quit the program (if it is appropriate for the program). If you are using a while loop, add a variable which remains true until you are ready to quit the program. Then, when you want to quit the program simply change the variable to false (as in the above example).
+
Then, when your script is ready to exit, simply:
  
−
For further reference, see the [[os.pullEvent]] page, as almost all their functionality is identical.
+
os.pullEvent = oldPullEvent
  
 
[[Category:Lua_Core_Functions]]
 
[[Category:Lua_Core_Functions]]

Latest revision as of 12:36, 30 March 2014


Grid Redstone.png  Function os.pullEventRaw
Near identical to os.pullEvent(); however, it is capable of returning terminate events (rather than halting your script when encountering them).

Note that if a terminate event is encountered, os.pullEventRaw() will return it even if a filter specifying a different type of event is used.
Syntax os.pullEventRaw([string filter])
Returns string event, variable parameters(see table below)
Part of ComputerCraft
API OS

Examples

Grid paper.png  Example
The program detects when the user attempted to terminate the program, informs them when they did so, then quits.
Code 
local running = true
while running do
   print ("Hello. Hold Ctrl + T to terminate (quit) this program.")
   local event = os.pullEventRaw () -- wait for the next event, you could use "terminate" as the filter in this case instead of the if statement
   if event == "terminate" then -- the event is the terminate event, tell the user and stop the loop (let the program end)
       print ("You terminated the program, good bye!")
       running = false
   end
end


Special Uses

Apart from the returning terminate events instead of actually terminating scripts when encountering them, os.pullEventRaw is identical to os.pullEvent - as such it is generally used to prevent users attempting to exit your code unless it's under your terms. This can be useful in programs such as door locks when you don't want the user interfering with the computer, or when you want to ensure certain "shutdown" operations are performed before your script exits.

The quickest and easiest way to prevent people from terminating (especially pre-made) programs is to add the following to the top of your code: 

os.pullEvent = os.pullEventRaw

All references to os.pullEvent from that point on will then point to THIS function, and as such, Ctrl+T (the terminate key combo) won't kill scripts unless they're specifically coded to respond to it. Note that Ctrl+R (the reboot key combo) cannot be "disabled" in such a manner.

If you're intending for the program to eventually exit, it is strongly recommended to re-instate the original function pointer (as it'll otherwise be lost until the computer reboots!). This can be done by storing a copy of it before redirecting os.pullEvent, eg: 

local oldPullEvent = os.pullEvent
os.pullEvent = os.pullEventRaw

Then, when your script is ready to exit, simply: 

os.pullEvent = oldPullEvent
Retrieved from "https://www.computercraft.info/wiki/index.php?title=Os.pullEventRaw&oldid=6301"