Os.pullEvent - Revision history

MKlegoman357: /* Event types */ Updated to ComputerCraft 1.74

2015-06-28T11:53:41Z

‎Event types: Updated to ComputerCraft 1.74

Bomb Bloke: /* Event types */ Network messages can be of variable type.

2015-06-14T13:55:10Z

‎Event types: Network messages can be of variable type.

MKlegoman357: Expanded description about "task_complete" event

2015-02-16T19:35:15Z

Expanded description about "task_complete" event

MKlegoman357: Added task_complete event. Fixed example.

2015-02-16T17:51:47Z

Added task_complete event. Fixed example.

Turkey: /* Guides */ Adding raw key events page

2014-08-30T16:38:28Z

‎Guides: Adding raw key events page

Turkey: /* How it works */ Correcting this since modem events are built-in events

2014-08-30T16:17:43Z

‎How it works: Correcting this since modem events are built-in events

Bomb Bloke: /* Event types */ paste added by CC 1.6

2014-06-20T11:47:13Z

‎Event types: paste added by CC 1.6

MKlegoman357: Added a note about key and char events

2014-06-11T16:15:33Z

Added a note about key and char events

Bomb Bloke: Fleshed out description a bit.

2014-03-30T12:38:15Z

Fleshed out description a bit.

Bomb Bloke: /* Event types */ Addition of term_resize by CC 1.6.

2014-03-29T09:12:01Z

‎Event types: Addition of term_resize by CC 1.6.

@@ Line 92: / Line 92: @@
 ! scope="row" | [[key (event)|key]]
 |Fired when a key is pressed on the keyboard
 |{{type|number}} numerical keycode
+|
@@ Line 215: / Line 223: @@
 ! scope="row" | [[mouse_click (event)|mouse_click]]
 |Fired when a mouse button is pressed
 |{{type|number}} mouse button
 |{{type|number}} x coordinate

@@ Line 182: / Line 182: @@
 |Fired when a rednet message is received from the [[Rednet_(API)|rednet API]]
 |{{type|number}} senderID
-|{{type|string}} message
+|{{type|any}} message
-|{{type|number}} distance travelled
+|{{type|string}} protocol / {{type|number}} distance travelled
+|
+|
@@ Line 192: / Line 192: @@
 |{{type|number}} frequency
 |{{type|number}} replyFrequency
-|{{type|string}} message
+|{{type|any}} message
 |{{type|number}} distance travelled
 |-

@@ Line 123: / Line 123: @@
 |-
 ! scope="row" | [[task_complete_(event)|task_complete]]
-|Fired when an asynchronous task completes. Used by every [[commands_(API)|commands API]] method which yields, including [[commands.execAsync]](), but excluding [[commands.getBlockPosition]]().
+|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

@@ Line 4: / Line 4: @@
   |args=[<nowiki></nowiki>{{type|string}} filter]
   |api=OS
-  |returns={{type|string}} event, variable parameters(see table below)
+  |returns={{type|string}} event, {{type|any}} param1, param2, ... (see table below)
   |addon=ComputerCraft
   |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>
@@ Line 18: / Line 18: @@
 |code=
   while true do
-    [[print]]("Press E to do something.")
+    [[print]]( "Press E to do something." )
-    local event, key = '''os.pullEvent("char")''' -- limit os.pullEvent to the [[Key_(event)|'key']] event
+    local event, key = '''os.pullEvent( "key" )''' -- limit os.pullEvent to the [[Key_(event)|'key']] event
     if key == [[Keys_(API)|keys]].e then -- if the key pressed was 'e'
-      [[print]]("You pressed E. Exiting program...")
+      [[print]]( "You pressed [E]. Exiting program..." )
       break
     end
@@ Line 120: / Line 120: @@
+|
+|
+|
 |-
@@ Line 253: / Line 261: @@
+|
 |-
-! scope="row" | [[turtle_inventory (event)|turtle_inventory]]
+! scope="row" | [[turtle_inventory_(event)|turtle_inventory]]
 |Fired when the inventory on a [[Turtle]] is changed.
+|

@@ Line 263: / Line 263: @@
 == 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()'']
 [[Category:Lua_Core_Functions]]

@@ Line 50: / Line 50: @@
 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.
+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:

@@ Line 12: / Line 12: @@
 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.
+[[#How it works|See below]] for more detailed information on the command.<br><br>See also: [[os.pullEventRaw|os.pullEventRaw()]]
   |examples=
 {{Example
 |desc=The program requires to wait for a keypress to do something:
-|code=[[Function (type)|function]] clear()
+|code=
-    [[term.clear]]()
-    [[term.setCursorPos]] (1,1)
- end
   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("char")''' -- 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!")
-        [[os.sleep|sleep]] (1.5) -- I don't like a whole 2 seconds but 1 second is too short
-    end
   end
 }}
 }}
-=== Common syntax ===
+__TOC__
-  event, param1, param2, param3 = os.pullEvent()
+  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 "input = read()") except that you can get more than one piece of information back.
+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 ==
@@ Line 60: / Line 54: @@
 When an event occurs, the event type, followed by the parameters, will be returned. If you have:
-  event, button, x, y = os.pullEvent()
+  local event, button, x, y = '''os.pullEvent()'''
 and the user clicks the mouse at coordinates 5,4 then:
@@ Line 73: / Line 67: @@
 If we wanted to only wait for mouse clicks we could use:
-   event, button, x, y = os.pullEvent("mouse_click")
+   local event, button, x, y = '''os.pullEvent("mouse_click")'''
 which will ignore any events that are not mouse clicks.

@@ Line 222: / Line 222: @@
 |-
 ! scope="row" | [[monitor_touch (event)|monitor_touch]]
-|Fired when a player right click on an advanced monitor connected.
+|Fired when a player right clicks on a connected advanced monitor.
 |{{type|string}} side
 |{{type|number}} x coordinate(in screen chars)
@@ Line 230: / Line 230: @@
 |-
 ! scope="row" | [[monitor_resize (event)|monitor_resize]]
-|Fired when a monitor resizes
+|Fired when a connected monitor resizes.
 |{{type|string}} side
+|
+|