Difference between revisions of "Os.pullEvent"

From ComputerCraft Wiki
Jump to: navigation, search
(→‎Event Types)
(→‎Event types: Updated to ComputerCraft 1.74)
 
(44 intermediate revisions by 18 users not shown)
Line 2: Line 2:
 
{{Function
 
{{Function
 
  |name=os.pullEvent
 
  |name=os.pullEvent
−
  |args=[[string]] only-event-to-accept
+
  |args=[<nowiki></nowiki>{{type|string}} filter]
−
  |api=os
+
  |api=OS
−
  |returns=event, parameters
+
  |returns={{type|string}} event, {{type|any}} param1, param2, ... (see table below)
 
  |addon=ComputerCraft
 
  |addon=ComputerCraft
−
  |desc=Yields computer until event occurs
+
  |desc=Waits (yields) until an event occurs, and returns details about that event before removing it from the event queue. If a "filter" is specified, it will wait until an event matching that type is found in the queue - any events that enter the queue ''before'' that one are also removed, so take care not to "discard" ones you don't need!<br><br>
 +
 
 +
Be aware that many other functions (most any that "pause" or "wait" for any amount of time) make use of os.pullEvent(). For example, calling [[Os.sleep|sleep()]] will [[os.startTimer|start a timer]], then wait for a [[timer_(event)|timer event]] to occur. If any other events happen before that timer event enters the queue (notably, those generated by [[Rednet (API)|rednet messages]] sent to the computer), they'll be discarded. In many cases use of the [[Parallel (API)|Parallel API functions]] offers a simple way around this, but if you need to listen for multiple event types at once it's generally best to forgo the filter and use if/then statements to respond according to what event type you get.<br><br>
 +
 
 +
If Ctrl+T is held, a [[terminate (event)|terminate event]] will be generated - if os.pullEvent() (or by extension, any function that uses it) spots this in the queue it will exit your script. This is not the case with the near-identical [[os.pullEventRaw|os.pullEventRaw()]].<br><br>
 +
 
 +
[[#How it works|See below]] for more detailed information on the command.<br><br>See also: [[os.pullEventRaw|os.pullEventRaw()]]
 
  |examples=
 
  |examples=
 
{{Example
 
{{Example
 
|desc=The program requires to wait for a keypress to do something:
 
|desc=The program requires to wait for a keypress to do something:
−
|code=[[function]] clear()
+
|code=
−
    [[term.clear]]()
+
−
    [[term.setCursorPos]] (1,1)
+
−
end
+
 
  while true do
 
  while true do
−
    clear()
+
  [[print]]( "Press E to do something." )
−
    [[print]] ("Press E to do something.")
+
 
−
    local event, param1 = os.pullEvent ("char") -- limit os.pullEvent to the char event
+
  local event, key = '''os.pullEvent( "key" )''' -- limit os.pullEvent to the [[Key_(event)|'key']] event
−
    if param1 == "e" then -- if the returned value was 'e'
+
 
−
        clear()
+
  if key == [[Keys_(API)|keys]].e then -- if the key pressed was 'e'
−
        [[write]] ("Name: ")
+
    [[print]]( "You pressed [E]. Exiting program..." )
−
        local name = [[read]]()
+
    break
−
        [[print]] (name)
+
  end
−
        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
 
  end
 
}}
 
}}
 +
|notes=* When you press a key on the keyboard that is a printable character ("''A''", "'']''", etc...) [[char_(event)|"char"]] and [[key_(event)|"key"]] events are both fired, commonly the "key" event is first fired and after it "char" event is fired.
 
}}
 
}}
  
−
== How it Works ==
+
__TOC__
−
When os.pullEvent() is called, regardless of whether it has variables to set, the computer is yielded until an event occurs. An event is anything the computer can use as input, such as a button being pushed on the keyboard or a redstone input.
+
 
−
When said event occurs, the event's name is placed in the first variable (the variable 'event' in the section below). With the event comes returned values, and, depending on the event type, there can be different amounts and different data types of returned values.
+
== Common syntax ==
 +
 
 +
local 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 "local 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 any one single 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 5 parameters.
 +
 
 +
When an event occurs, the event type, followed by the parameters, will be returned. If you have:
 +
 
 +
local 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:
  
−
For example, the event "char" returns "char" as the event and (let's say E was pressed) the first parameter will be set to "e", although whether or not Shift was pressed can change that "e" to an "E" as well.
+
  local event, button, x, y = '''os.pullEvent("mouse_click")'''
  
−
The event "redstone" only returns the event type since any other information needed can be retrieved with [[redstone.getInput]].
+
which will ignore any events that are not mouse clicks.
  
−
=== Common Syntax ===
+
If you assign more variables than necessary, the extra ones will be set to nil.
−
<pre>
+
If you assign fewer variables than necessary, the extra parameters will be discarded.
−
event, param1, param2, param3 = os.pullEvent()
+
−
</pre>
+
  
−
==Event Types==
+
==Event types==
 
{| class="wikitable" width="100%"
 
{| class="wikitable" width="100%"
 
! rowspan="2" | Name
 
! rowspan="2" | Name
 
! rowspan="2" | Description
 
! rowspan="2" | Description
−
! colspan="6" | Parameters
+
! colspan="5" | Parameters
 
|-
 
|-
−
! 1
+
! 1 !! 2 !! 3 !! 4 !! 5
−
! 2
+
−
! 3
+
−
! 4
+
−
! 5
+
−
! 6
+
 
|-
 
|-
−
![[char]] (Event)
+
! scope="row" | [[char (event)|char]]
 
|Fired when text is typed on the keyboard
 
|Fired when text is typed on the keyboard
−
|the letter typed
+
| {{type|string}} the letter typed
−
|
+
 
|
 
|
 
|
 
|
Line 68: Line 90:
 
|
 
|
 
|-
 
|-
−
![[key]]
+
! scope="row" | [[key (event)|key]]
 
|Fired when a key is pressed on the keyboard
 
|Fired when a key is pressed on the keyboard
−
|numerical keycode
+
|{{type|number}} numerical keycode
 +
|{{type|boolean}} is being held
 
|
 
|
 +
|
 +
|
 +
|-
 +
! scope="row" | [[key_up (event)|key_up]]
 +
|Fired when a key is released
 +
|{{type|number}} numerical keycode
 
|
 
|
 
|
 
|
Line 77: Line 106:
 
|
 
|
 
|-
 
|-
−
![[timer]]
+
! scope="row" | [[paste (event)|paste]]
−
|Fired when a timeout started by os.startTimer() completes
+
|Fired when Ctrl + V is pressed on the keyboard
−
|Value of the timer as returned by os.startTimer()
+
|{{type|string}} system clipboard text
 
|
 
|
 +
|
 +
|
 +
|
 +
|-
 +
! scope="row" | [[timer (event)|timer]]
 +
|Fired when a timeout started by [[os.startTimer]]() completes
 +
|{{type|number}} Value of the timer as returned by os.startTimer()
 
|
 
|
 
|
 
|
Line 86: Line 122:
 
|
 
|
 
|-
 
|-
−
![[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
−
|Value of the alarm as returned by os.setAlarm()
+
|{{type|number}} Value of the alarm as returned by os.setAlarm()
 
|
 
|
 
|
 
|
 
|
 
|
 
|
 
|
 +
|-
 +
! scope="row" | [[task_complete_(event)|task_complete]]
 +
|Fired when an asynchronous task completes. Used by every [[commands_(API)|commands API]] method internally which yields, including [[commands.execAsync]](), but excluding [[commands.getBlockPosition]](). Also used internally by every [[Command_Block_(API)|command block's method]].
 +
|{{type|number}} taskID
 +
|{{type|boolean}} success
 +
|[<nowiki/>{{type|string}} error]
 +
|{{type|any}} param1, param2, ...
 
|
 
|
 
|-
 
|-
−
![[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
 
|
 
|
 +
|
 +
|
 +
|
 +
|
 +
|-
 +
! scope="row" | [[terminate (event)|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.
 
|
 
|
 
|
 
|
Line 104: Line 155:
 
|
 
|
 
|-
 
|-
−
![[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
−
|side
+
|{{type|string}} side
−
|
+
 
|
 
|
 
|
 
|
Line 113: Line 163:
 
|
 
|
 
|-
 
|-
−
![[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
−
|side
+
|{{type|string}} side
−
|
+
 
|
 
|
 
|
 
|
Line 122: Line 171:
 
|
 
|
 
|-
 
|-
−
![[peripheral]]
+
! scope="row" | [[peripheral (event)|peripheral]]
 
|Fired when peripheral is attached
 
|Fired when peripheral is attached
−
|side
+
|{{type|string}} side
−
|
+
 
|
 
|
 
|
 
|
Line 131: Line 179:
 
|
 
|
 
|-
 
|-
−
![[peripheral_detach]]
+
! scope="row" | [[peripheral_detach (event)| peripheral_detach]]
 
|Fired when peripheral is removed
 
|Fired when peripheral is removed
−
|side
+
|{{type|string}} side
−
|
+
 
|
 
|
 
|
 
|
Line 140: Line 187:
 
|
 
|
 
|-
 
|-
−
![[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]]
−
|senderID
+
|{{type|number}} senderID
−
|message
+
|{{type|any}} message
−
|distanceTravelled
+
|{{type|string}} protocol / {{type|number}} distance travelled
−
|
+
 
|
 
|
 
|
 
|
 
|-
 
|-
−
![[http_success]]
+
! scope="row" | [[modem_message (event)|modem_message]]
−
|Fired when an attempt to recieve text from / post text on a website is successful
+
|Fired when a modem message is received from the [[modem]]
−
|url of the site
+
|{{type|string}} side
−
|text on the site
+
|{{type|number}} frequency
−
|
+
|{{type|number}} replyFrequency
 +
|{{type|any}} message
 +
|{{type|number}} distance travelled
 +
|-
 +
! scope="row" | [[http_success (event)|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.
 +
|{{type|string}} url of the site
 +
|{{type|table}} text on the site
 
|
 
|
 
|
 
|
 
|
 
|
 
|-
 
|-
−
![[http_failure]]
+
! scope="row" | [[http_failure (event)|http_failure]]
−
|Fired when an attempt to recieve text from / post text on a website is unsuccessful
+
|Fired when an attempt to receive text from / post text on a website is unsuccessful
−
|url of the site
+
You will not normally see this event as it is handled inside http.get.
−
|
+
|{{type|string}} url of the site
 
|
 
|
 
|
 
|
Line 167: Line 221:
 
|
 
|
 
|-
 
|-
−
![[mouse_click]]
+
! scope="row" | [[mouse_click (event)|mouse_click]]
 
|Fired when a mouse button is pressed
 
|Fired when a mouse button is pressed
−
|mouse button
+
|{{type|number}} mouse button
−
|x coordinate
+
|{{type|number}} x coordinate
−
|y coordinate
+
|{{type|number}} y coordinate
 
|
 
|
 +
|
 +
|-
 +
! scope="row" | [[mouse_up (event)|mouse_up]]
 +
|Fired when a mouse button is released
 +
|{{type|number}} mouse button
 +
|{{type|number}} x coordinate
 +
|{{type|number}} y coordinate
 
|
 
|
 
|
 
|
 
|-
 
|-
−
![[mouse_scroll]]
+
! scope="row" | [[mouse_scroll (event)|mouse_scroll]]
 
|Fired when a mousewheel is scrolled.
 
|Fired when a mousewheel is scrolled.
−
|scroll direction (-1 for up, 1 for down)
+
|{{type|number}} scroll direction (-1 for up, 1 for down)
−
|x coordinate
+
|{{type|number}} x coordinate(in screen chars)
−
|y coordinate
+
|{{type|number}} y coordinate(in screen chars)
 
|
 
|
 
|
 
|
 
|-
 
|-
−
![[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.
−
|x coordinate
+
|{{type|number}} mouse button
−
|y coordinate
+
|{{type|number}} x coordinate(in screen chars)
 +
|{{type|number}} y coordinate(in screen chars)
 +
|
 +
|
 +
|-
 +
! scope="row" | [[monitor_touch (event)|monitor_touch]]
 +
|Fired when a player right clicks on a connected advanced monitor.
 +
|{{type|string}} side
 +
|{{type|number}} x coordinate(in screen chars)
 +
|{{type|number}} y coordinate(in screen chars)
 +
|
 +
|
 +
|-
 +
! scope="row" | [[monitor_resize (event)|monitor_resize]]
 +
|Fired when a connected monitor resizes.
 +
|{{type|string}} side
 +
|
 +
|
 +
|
 +
|
 +
|-
 +
! scope="row" | [[Term_resize_(event)|term_resize]]
 +
|Fired when the terminal resizes.
 +
|
 +
|
 +
|
 +
|
 +
|
 +
|-
 +
! scope="row" | [[turtle_inventory_(event)|turtle_inventory]]
 +
|Fired when the inventory on a [[Turtle]] is changed.
 +
|
 +
|
 
|
 
|
 
|
 
|
Line 194: Line 287:
  
 
== Guides ==
 
== Guides ==
−
[http://www.computercraft.info/forums2/index.php?/topic/1516-ospullevent-what-is-it-and-how-is-it-useful/page__view__findpost__p__11156 ''Onionnion's Guide on os.pullEvent()'']
+
* [http://www.computercraft.info/forums2/index.php?/topic/1516-ospullevent-what-is-it-and-how-is-it-useful/page__view__findpost__p__11156 ''Onionnion's Guide on os.pullEvent()'']
 +
* [[Raw key events]]
 +
 
 +
[[Category:Lua_Core_Functions]]

Latest revision as of 11:53, 28 June 2015


Grid Redstone.png  Function os.pullEvent
Waits (yields) until an event occurs, and returns details about that event before removing it from the event queue. If a "filter" is specified, it will wait until an event matching that type is found in the queue - any events that enter the queue before that one are also removed, so take care not to "discard" ones you don't need!

Be aware that many other functions (most any that "pause" or "wait" for any amount of time) make use of os.pullEvent(). For example, calling sleep() will start a timer, then wait for a timer event to occur. If any other events happen before that timer event enters the queue (notably, those generated by rednet messages sent to the computer), they'll be discarded. In many cases use of the Parallel API functions offers a simple way around this, but if you need to listen for multiple event types at once it's generally best to forgo the filter and use if/then statements to respond according to what event type you get.

If Ctrl+T is held, a terminate event will be generated - if os.pullEvent() (or by extension, any function that uses it) spots this in the queue it will exit your script. This is not the case with the near-identical os.pullEventRaw().

See below for more detailed information on the command.

See also: os.pullEventRaw()
Syntax os.pullEvent([string filter])
Returns string event, any param1, param2, ... (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 
while true do
  print( "Press E to do something." )
  
  local event, key = os.pullEvent( "key" ) -- limit os.pullEvent to the 'key' event
  
  if key == keys.e then -- if the key pressed was 'e'
    print( "You pressed [E]. Exiting program..." )
    break
  end
end

Additional Notes

  • When you press a key on the keyboard that is a printable character ("A", "]", etc...) "char" and "key" events are both fired, commonly the "key" event is first fired and after it "char" event is fired.


Common syntax

local 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 "local 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 any one single 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 5 parameters.

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

local 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: 

 local 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 4 5
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 boolean is being held
key_up Fired when a key is released number numerical keycode
paste Fired when Ctrl + V is pressed on the keyboard string system clipboard text
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()
task_complete Fired when an asynchronous task completes. Used by every commands API method internally which yields, including commands.execAsync(), but excluding commands.getBlockPosition(). Also used internally by every command block's method. number taskID boolean success [string error] any param1, param2, ...
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 any message string protocol / number distance travelled
modem_message Fired when a modem message is received from the modem string side number frequency number replyFrequency any 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_up Fired when a mouse button is released 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 clicks on a connected advanced monitor. string side number x coordinate(in screen chars) number y coordinate(in screen chars)
monitor_resize Fired when a connected monitor resizes. string side
term_resize Fired when the terminal resizes.
turtle_inventory Fired when the inventory on a Turtle is changed.

Guides

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