16562Sphk------------------------------------------------------------------------------- 237421Scharnier-- Copyright (c) 2002,2006 Free Software Foundation, Inc. -- 36562Sphk-- -- 46562Sphk-- Permission is hereby granted, free of charge, to any person obtaining a -- 53995Spst-- copy of this software and associated documentation files (the -- 63995Spst-- "Software"), to deal in the Software without restriction, including -- 76562Sphk-- without limitation the rights to use, copy, modify, merge, publish, -- 86562Sphk-- distribute, distribute with modifications, sublicense, and/or sell copies -- 96562Sphk-- of the Software, and to permit persons to whom the Software is furnished -- 106562Sphk-- to do so, subject to the following conditions: -- 116562Sphk-- -- 126562Sphk-- The above copyright notice and this permission notice shall be included -- 136562Sphk-- in all copies or substantial portions of the Software. -- 146562Sphk-- -- 156562Sphk-- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS -- 166562Sphk-- OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -- 176562Sphk-- MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN -- 183995Spst-- NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, -- 193995Spst-- DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR -- 20114589Sobrien-- OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE -- 21114589Sobrien-- USE OR OTHER DEALINGS IN THE SOFTWARE. -- 2237421Scharnier-- -- 2319168Sbde-- Except as contained in this notice, the name(s) of the above copyright -- 24110840Ssilby-- holders shall not be used in advertising or otherwise to promote the -- 25110840Ssilby-- sale, use or other dealings in this Software without prior written -- 2637421Scharnier-- authorization. -- 2719168Sbde------------------------------------------------------------------------------- 283995Spst-- $Id: README.IZ,v 1.2 2006/04/22 23:13:05 tom Exp $ 2978949Sdes--------------------------------------------------------------------- 3078949Sdes 313995SpstHere is the patch. I did no testing whatsoever with event watching 3232074Ssteverequests present (I need some applications which exersize this before 3319168Sbdethis, probably lynx ;-), but the code looks working "the normal way". 346562Sphk 356562SphkI had no way to test that the poll() branch compiles/works... 363995Spst 3746226SkrisHere is the API: 3846226Skris 393995Spst*) two new functions wgetch_events() wgetstrn_event() are introduced, 4054109Sobrien which allow an event-watch specification given as the last argument; 4152949Sobrien 4288226Sphk*) if the last argument is NULL, they behave as wgetch() and 4352949Sobrien wgetstrn() (TESTED!); 4476988Sru 4576988Sru*) the event specification is a pointer to _nc_eventlist, which 4676988Sru contains bookkeeping elements (count and the summary of results), 4776988Sru and an array of pointers to _nc_event; 4876988Sru 493995Spst*) each _nc_event is a typed union, with two types supported "as 503995Spst shipped": _NC_EVENT_TIMEOUT_MSEC, _NC_EVENT_FILE. For 513995Spst _NC_EVENT_FILE the fields are fd, flag, and the output field. 523995Spst 533995Spst*) The only supported flag "as shipped" is _NC_EVENT_FILE_READABLE. 543995Spst If the file was found readable, the return field is set to this, 553995Spst otherwise to 0; 563995Spst 573995Spst*) If these functions return KEY_EVENT, this means that the return 583995Spst fields in both the _nc_eventlist and _nc_event structures make 596562Sphk sense. The field result_flags of _nc_eventlist may have a 6076988Sru combination of bits _NC_EVENT_TIMEOUT_MSEC and _NC_EVENT_FILE_READABLE 613995Spst set; 6232086Ssteve 636562Sphk*) The timeout_msec field of _NC_EVENT_TIMEOUT_MSEC _nc_event's is 649489Sphk updated on return, even if the return is not KEY_EVENT. However, 65121914Sse the change in the value represents only the amount of time spent in 663995Spst waiting for events, not the amount of time spent bookkeeping; 67121914Sse 6878756Sru*) the return KEY_EVENT of wgetstrn_event() means that the output 6976988Sru string includes the user input typed so far, but the user did not have 7076988Sru a chance to press ENTER (or whatever). This call should be 7176988Sru repeated (with "shifted" pointer to a buffer, of course) to 7276988Sru complete the input; 7376988Sru 7476988Sru*) The presence of this extension can be checked via inspecting 7576988Sru #ifdef NCURSES_EVENT_VERSION. This symbol is not defined on BeOS, 7676988Sru since there is no support for this on BeOS. 7776988Sru 7876988SruKnown issues: calls interrupted by KEY_EVENT reset the ESCDELAY 7976988Srutimer. This is not entirely new, since other synthetic events behave 8088226Sphkthe same (see "if (ch >= KEY_MIN)" branch of kgetch()). However, 8176988SruKEY_EVENT may be generated in a continuous stream (say, when 8276988Srudownloading a file), thus this may be more important than with other 8376988Srusynthetic keys. An additional field in window structure which keeps 8476988Srutimestamp of the first raw key in the queue may be needed to 8576988Srucircumvent this. 8676988Sru 8776988SruAnother possible issue: KEY_EVENT has a preference over a user input, 8876988Sruso a stream of KEY_EVENT's can make input hard. Maybe use 8976988Sruresult_flags as in input parameter too, which specifies whether the 9076988Sruuser input should have higher precedence? 9132074Ssteve 9276988SruAlso: I took an opportunity to document kgetch() better. 9376988Sru 9476988SruEnjoy, 9576988SruIlya 9676988Sru