1166124Srafan------------------------------------------------------------------------------- 2166124Srafan-- Copyright (c) 2002,2006 Free Software Foundation, Inc. -- 3166124Srafan-- -- 4166124Srafan-- Permission is hereby granted, free of charge, to any person obtaining a -- 5166124Srafan-- copy of this software and associated documentation files (the -- 6166124Srafan-- "Software"), to deal in the Software without restriction, including -- 7166124Srafan-- without limitation the rights to use, copy, modify, merge, publish, -- 8166124Srafan-- distribute, distribute with modifications, sublicense, and/or sell copies -- 9166124Srafan-- of the Software, and to permit persons to whom the Software is furnished -- 10166124Srafan-- to do so, subject to the following conditions: -- 11166124Srafan-- -- 12166124Srafan-- The above copyright notice and this permission notice shall be included -- 13166124Srafan-- in all copies or substantial portions of the Software. -- 14166124Srafan-- -- 15166124Srafan-- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS -- 16166124Srafan-- OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -- 17166124Srafan-- MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN -- 18166124Srafan-- NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, -- 19166124Srafan-- DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR -- 20166124Srafan-- OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE -- 21166124Srafan-- USE OR OTHER DEALINGS IN THE SOFTWARE. -- 22166124Srafan-- -- 23166124Srafan-- Except as contained in this notice, the name(s) of the above copyright -- 24166124Srafan-- holders shall not be used in advertising or otherwise to promote the -- 25166124Srafan-- sale, use or other dealings in this Software without prior written -- 26166124Srafan-- authorization. -- 27166124Srafan------------------------------------------------------------------------------- 28166124Srafan-- $Id: README.IZ,v 1.2 2006/04/22 23:13:05 tom Exp $ 29166124Srafan--------------------------------------------------------------------- 30166124Srafan 31166124SrafanHere is the patch. I did no testing whatsoever with event watching 32166124Srafanrequests present (I need some applications which exersize this before 33166124Srafanthis, probably lynx ;-), but the code looks working "the normal way". 34166124Srafan 35166124SrafanI had no way to test that the poll() branch compiles/works... 36166124Srafan 37166124SrafanHere is the API: 38166124Srafan 39166124Srafan*) two new functions wgetch_events() wgetstrn_event() are introduced, 40166124Srafan which allow an event-watch specification given as the last argument; 41166124Srafan 42166124Srafan*) if the last argument is NULL, they behave as wgetch() and 43166124Srafan wgetstrn() (TESTED!); 44166124Srafan 45166124Srafan*) the event specification is a pointer to _nc_eventlist, which 46166124Srafan contains bookkeeping elements (count and the summary of results), 47166124Srafan and an array of pointers to _nc_event; 48166124Srafan 49166124Srafan*) each _nc_event is a typed union, with two types supported "as 50166124Srafan shipped": _NC_EVENT_TIMEOUT_MSEC, _NC_EVENT_FILE. For 51166124Srafan _NC_EVENT_FILE the fields are fd, flag, and the output field. 52166124Srafan 53166124Srafan*) The only supported flag "as shipped" is _NC_EVENT_FILE_READABLE. 54166124Srafan If the file was found readable, the return field is set to this, 55166124Srafan otherwise to 0; 56166124Srafan 57166124Srafan*) If these functions return KEY_EVENT, this means that the return 58166124Srafan fields in both the _nc_eventlist and _nc_event structures make 59166124Srafan sense. The field result_flags of _nc_eventlist may have a 60166124Srafan combination of bits _NC_EVENT_TIMEOUT_MSEC and _NC_EVENT_FILE_READABLE 61166124Srafan set; 62166124Srafan 63166124Srafan*) The timeout_msec field of _NC_EVENT_TIMEOUT_MSEC _nc_event's is 64166124Srafan updated on return, even if the return is not KEY_EVENT. However, 65166124Srafan the change in the value represents only the amount of time spent in 66166124Srafan waiting for events, not the amount of time spent bookkeeping; 67166124Srafan 68166124Srafan*) the return KEY_EVENT of wgetstrn_event() means that the output 69166124Srafan string includes the user input typed so far, but the user did not have 70166124Srafan a chance to press ENTER (or whatever). This call should be 71166124Srafan repeated (with "shifted" pointer to a buffer, of course) to 72166124Srafan complete the input; 73166124Srafan 74166124Srafan*) The presence of this extension can be checked via inspecting 75166124Srafan #ifdef NCURSES_EVENT_VERSION. This symbol is not defined on BeOS, 76166124Srafan since there is no support for this on BeOS. 77166124Srafan 78166124SrafanKnown issues: calls interrupted by KEY_EVENT reset the ESCDELAY 79166124Srafantimer. This is not entirely new, since other synthetic events behave 80166124Srafanthe same (see "if (ch >= KEY_MIN)" branch of kgetch()). However, 81166124SrafanKEY_EVENT may be generated in a continuous stream (say, when 82166124Srafandownloading a file), thus this may be more important than with other 83166124Srafansynthetic keys. An additional field in window structure which keeps 84166124Srafantimestamp of the first raw key in the queue may be needed to 85166124Srafancircumvent this. 86166124Srafan 87166124SrafanAnother possible issue: KEY_EVENT has a preference over a user input, 88166124Srafanso a stream of KEY_EVENT's can make input hard. Maybe use 89166124Srafanresult_flags as in input parameter too, which specifies whether the 90166124Srafanuser input should have higher precedence? 91166124Srafan 92166124SrafanAlso: I took an opportunity to document kgetch() better. 93166124Srafan 94166124SrafanEnjoy, 95166124SrafanIlya 96