Difference between revisions of "Os.pullEvent"

From ComputerCraft Wiki
Jump to: navigation, search
m (→‎Event types)
(less -> fewer, tidy up)
Line 4: Line 4:
 
  |args=([[string]]) filter
 
  |args=([[string]]) filter
 
  |api=OS
 
  |api=OS
−
  |returns=(string)event, variable parameters(see table below)
+
  |returns={{type|string}} event, variable parameters(see table below)
 
  |addon=ComputerCraft
 
  |addon=ComputerCraft
 
  |desc=Waits (yields) until an event occurs
 
  |desc=Waits (yields) until an event occurs
Line 35: Line 35:
 
=== Common syntax ===
 
=== Common syntax ===
  
−
  event, param1, param2, param3 = os.pullEvent()
+
event, param1, param2, param3 = os.pullEvent()
  
 
Note: This is one of the most commonly used functions that can return multiple values.
 
Note: This is one of the most commonly used functions that can return multiple values.
Line 54: Line 54:
 
When an event occurs, the event type, followed by the parameters, will be returned. If you have:
 
When an event occurs, the event type, followed by the parameters, will be returned. If you have:
  
−
  event, button, x, y = os.pullEvent()
+
event, button, x, y = os.pullEvent()
  
 
and the user clicks the mouse at coordinates 5,4 then:
 
and the user clicks the mouse at coordinates 5,4 then:
Line 72: Line 72:
  
 
If you assign more variables than necessary, the extra ones will be set to nil.
 
If you assign more variables than necessary, the extra ones will be set to nil.
−
If you assign less variables than necessary, the extra parameters will be discarded.
+
If you assign fewer variables than necessary, the extra parameters will be discarded.
  
 
==Event types==
 
==Event types==
Line 80: Line 80:
 
! colspan="3" | Parameters
 
! colspan="3" | Parameters
 
|-
 
|-
−
! 1
+
! 1 !! 2 !! 3
−
! 2
+
−
! 3
+
 
|-
 
|-
−
![[char (event)|char]]
+
! scope="row" | [[char (event)|char]]
 
|Fired when text is typed on the keyboard
 
|Fired when text is typed on the keyboard
−
|(string)the letter typed
+
| {{type|string}} the letter typed
 
|
 
|
 
|
 
|
 
|-
 
|-
−
![[key (event)|key]]
+
! scope="row" | [[key (event)|key]]
 
|Fired when a key is pressed on the keyboard
 
|Fired when a key is pressed on the keyboard
−
|(number)numerical keycode
+
|{{type|number}} numerical keycode
 
|
 
|
 
|
 
|
 
|-
 
|-
−
![[timer (event)|timer]]
+
! scope="row" | [[timer (event)|timer]]
 
|Fired when a timeout started by [[os.startTimer]]() completes
 
|Fired when a timeout started by [[os.startTimer]]() completes
−
|(number)Value of the timer as returned by os.startTimer()
+
|{{type|number}} Value of the timer as returned by os.startTimer()
 
|
 
|
 
|
 
|
 
|-
 
|-
−
![[alarm (event)|alarm]]
+
! scope="row" | [[alarm (event)|alarm]]
 
|Fired when a time passed to [[os.setAlarm]]() is reached
 
|Fired when a time passed to [[os.setAlarm]]() is reached
−
|(number)Value of the alarm as returned by os.setAlarm()
+
|{{type|number}} Value of the alarm as returned by os.setAlarm()
 
|
 
|
 
|
 
|
 
|-
 
|-
−
![[redstone (event)|redstone]]
+
! scope="row" | [[redstone (event)|redstone]]
 
|Fired when the state of any of the redstone inputs change
 
|Fired when the state of any of the redstone inputs change
 
|
 
|
Line 114: Line 112:
 
|
 
|
 
|-
 
|-
−
![[terminate (event)|terminate]]
+
! scope="row" | [[terminate (event)|terminate]]
 
|Fired when a combination of keys CTRL and T is pressed and held for three seconds.
 
|Fired when a combination of keys CTRL and T is pressed and held for three seconds.
 
You will not normally see this event, as it is handled inside os.pullEvent.
 
You will not normally see this event, as it is handled inside os.pullEvent.
Line 121: Line 119:
 
|
 
|
 
|-
 
|-
−
![[disk (event)|disk]]
+
! scope="row" | [[disk (event)|disk]]
 
|Fired when a disk is inserted into an adjacent disk drive
 
|Fired when a disk is inserted into an adjacent disk drive
−
|(string)side
+
|{{type|string}} side
 
|
 
|
 
|
 
|
 
|-
 
|-
−
![[disk_eject (event)|disk_eject]]
+
! scope="row" | [[disk_eject (event)|disk_eject]]
 
|Fired when a disk is removed from an adjacent disk drive
 
|Fired when a disk is removed from an adjacent disk drive
−
|(string)side
+
|{{type|string}} side
 
|
 
|
 
|
 
|
 
|-
 
|-
−
![[peripheral (event)|peripheral]]
+
! scope="row" | [[peripheral (event)|peripheral]]
 
|Fired when peripheral is attached
 
|Fired when peripheral is attached
−
|(string)side
+
|{{type|string}} side
 
|
 
|
 
|
 
|
 
|-
 
|-
−
![[peripheral_detach (event)| peripheral_detach]]
+
! scope="row" | [[peripheral_detach (event)| peripheral_detach]]
 
|Fired when peripheral is removed
 
|Fired when peripheral is removed
−
|(string)side
+
|{{type|string}} side
 
|
 
|
 
|
 
|
 
|-
 
|-
−
![[rednet_message (event)|rednet_message]]
+
! scope="row" | [[rednet_message (event)|rednet_message]]
 
|Fired when a rednet message is received from the [[Rednet_(API)|rednet API]]
 
|Fired when a rednet message is received from the [[Rednet_(API)|rednet API]]
−
|(number)senderID
+
|{{type|number}} senderID
−
|(string)message
+
|{{type|string}} message
−
|(number)distance travelled
+
|{{type|number}} distance travelled
 
|-
 
|-
−
![[http_success (event)|http_success]]
+
! scope="row" | [[http_success (event)|http_success]]
 
|Fired when an attempt to receive text from / post text on a website is successful.
 
|Fired when an attempt to receive text from / post text on a website is successful.
 
You will not normally see this event as it is handled inside http.get.
 
You will not normally see this event as it is handled inside http.get.
−
|(string)url of the site
+
|{{type|string}} url of the site
−
|(table)text on the site
+
|{{type|table}} text on the site
 
|
 
|
 
|-
 
|-
−
![[http_failure (event)|http_failure]]
+
! scope="row" | [[http_failure (event)|http_failure]]
 
|Fired when an attempt to receive text from / post text on a website is unsuccessful
 
|Fired when an attempt to receive text from / post text on a website is unsuccessful
 
You will not normally see this event as it is handled inside http.get.
 
You will not normally see this event as it is handled inside http.get.
−
|(string)url of the site
+
|{{type|string}} url of the site
 
|
 
|
 
|
 
|
 
|-
 
|-
−
![[mouse_click (event)|mouse_click]]
+
! scope="row" | [[mouse_click (event)|mouse_click]]
 
|Fired when a mouse button is pressed
 
|Fired when a mouse button is pressed
−
|(number)mouse button
+
|{{type|number}} mouse button
−
|(number)x coordinate
+
|{{type|number}} x coordinate
−
|(number)y coordinate
+
|{{type|number}} y coordinate
 
|-
 
|-
−
![[mouse_scroll (event)|mouse_scroll]]
+
! scope="row" | [[mouse_scroll (event)|mouse_scroll]]
 
|Fired when a mousewheel is scrolled.
 
|Fired when a mousewheel is scrolled.
−
|(number)scroll direction (-1 for up, 1 for down)
+
|{{type|number}} scroll direction (-1 for up, 1 for down)
−
|(number)x coordinate(in screen chars)
+
|{{type|number}} x coordinate(in screen chars)
−
|(number)y coordinate(in screen chars)
+
|{{type|number}} y coordinate(in screen chars)
 
|-
 
|-
−
![[mouse_drag (event)|mouse_drag]]
+
! scope="row" | [[mouse_drag (event)|mouse_drag]]
 
|Fired when the mouse is moved after clicking.
 
|Fired when the mouse is moved after clicking.
−
|(number)mouse button
+
|{{type|number}} mouse button
−
|(number)x coordinate(in screen chars)
+
|{{type|number}} x coordinate(in screen chars)
−
|(number)y coordinate(in screen chars)
+
|{{type|number}} y coordinate(in screen chars)
 
|-
 
|-
−
![[monitor_touch (event)|monitor_touch]]
+
! scope="row" | [[monitor_touch (event)|monitor_touch]]
 
|Fired when a player right click on an advanced monitor connected.
 
|Fired when a player right click on an advanced monitor connected.
−
|(string)side
+
|{{type|string}} side
−
|(number)x coordinate(in screen chars)
+
|{{type|number}} x coordinate(in screen chars)
−
|(number)y coordinate(in screen chars)
+
|{{type|number}} y coordinate(in screen chars)
 
|}
 
|}
  

Revision as of 04:22, 20 January 2013


Grid Redstone.png  Function os.pullEvent
Waits (yields) until an event occurs
Syntax os.pullEvent((string) filter)
Returns string event, variable parameters(see table below)
Part of ComputerCraft
API OS

Examples

Grid paper.png  Example
The program requires to wait for a keypress to do something:
Code 
function clear()
   term.clear()
   term.setCursorPos (1,1)
end
while true do
   clear()
   print ("Press E to do something.")
   local event, param1 = os.pullEvent ("char") -- limit os.pullEvent to the char event
   if param1 == "e" then -- if the returned value was 'e'
       clear()
       write ("Name: ")
       local name = read()
       print (name)
       break
   else
       clear()
       print ("Wrong button!")
       sleep (1.5) -- I don't like a whole 2 seconds but 1 second is too short
   end
end


Common syntax

event, param1, param2, param3 = os.pullEvent()

Note: This is one of the most commonly used functions that can return multiple values. It works like any other function call (such as "input = read()") except that you can get more than one piece of information back.

How it works

When os.pullEvent() is called, the computer waits until an event occurs. Events can be triggered by several different things, such as a key being pressed or a redstone input changing. They are usually triggered by ComputerCraft itself, when it needs to notify the computer that something happened. They can also be triggered by peripherals, or by your program calling os.queueEvent.

More complicated input, such as "the user typing a line of text," does not correspond to an event. read handles this inside itself by waiting for the user to press a key, then updating the screen, moving the cursor, etc.

Events have a type (which is a string) and 0-5 parameters (which are often but not always strings). No built-in events use more than 3 parameters.

When an event occurs, the event type, followed by the parameters, will be returned. If you have: 

event, button, x, y = os.pullEvent()

and the user clicks the mouse at coordinates 5,4 then:

  • event will be set to "mouse_click" (the event type)
  • button will be set to 0 (the first parameter)
  • x will be set to 5 (the second parameter)
  • y will be set to 4 (the third parameter)

Note that in this example, we didn't specify a filter. If you specify a filter, then all events of different types will be ignored. If the user inserts a disk, instead of clicking the mouse, then event will be "disk", button will be the side the disk drive is on, and x and y will be nil.

If we wanted to only wait for mouse clicks we could use: 

 event, button, x, y = os.pullEvent("mouse_click")

which will ignore any events that are not mouse clicks.

If you assign more variables than necessary, the extra ones will be set to nil. If you assign fewer variables than necessary, the extra parameters will be discarded.

Event types

Name Description Parameters
1 2 3
char Fired when text is typed on the keyboard string the letter typed
key Fired when a key is pressed on the keyboard number numerical keycode
timer Fired when a timeout started by os.startTimer() completes number Value of the timer as returned by os.startTimer()
alarm Fired when a time passed to os.setAlarm() is reached number Value of the alarm as returned by os.setAlarm()
redstone Fired when the state of any of the redstone inputs change
terminate Fired when a combination of keys CTRL and T is pressed and held for three seconds.

You will not normally see this event, as it is handled inside os.pullEvent.

disk Fired when a disk is inserted into an adjacent disk drive string side
disk_eject Fired when a disk is removed from an adjacent disk drive string side
peripheral Fired when peripheral is attached string side
peripheral_detach Fired when peripheral is removed string side
rednet_message Fired when a rednet message is received from the rednet API number senderID string message number distance travelled
http_success Fired when an attempt to receive text from / post text on a website is successful.

You will not normally see this event as it is handled inside http.get.

string url of the site table text on the site
http_failure Fired when an attempt to receive text from / post text on a website is unsuccessful

You will not normally see this event as it is handled inside http.get.

string url of the site
mouse_click Fired when a mouse button is pressed number mouse button number x coordinate number y coordinate
mouse_scroll Fired when a mousewheel is scrolled. number scroll direction (-1 for up, 1 for down) number x coordinate(in screen chars) number y coordinate(in screen chars)
mouse_drag Fired when the mouse is moved after clicking. number mouse button number x coordinate(in screen chars) number y coordinate(in screen chars)
monitor_touch Fired when a player right click on an advanced monitor connected. string side number x coordinate(in screen chars) number y coordinate(in screen chars)

Guides

Onionnion's Guide on os.pullEvent()

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