| Amit Daniel Kachhap | e6a01f5 | 2011-07-20 11:45:59 +0530 | [diff] [blame] | 1 | ------------------------------------------------------------------------------- |
| micky387 | 9b9f5e7 | 2025-07-08 18:04:53 -0400 | [diff] [blame] | 2 | -- Copyright 2020,2021 Thomas E. Dickey -- |
| 3 | -- Copyright 2002,2006 Free Software Foundation, Inc. -- |
| Amit Daniel Kachhap | e6a01f5 | 2011-07-20 11:45:59 +0530 | [diff] [blame] | 4 | -- -- |
| 5 | -- Permission is hereby granted, free of charge, to any person obtaining a -- |
| 6 | -- copy of this software and associated documentation files (the -- |
| 7 | -- "Software"), to deal in the Software without restriction, including -- |
| 8 | -- without limitation the rights to use, copy, modify, merge, publish, -- |
| 9 | -- distribute, distribute with modifications, sublicense, and/or sell copies -- |
| 10 | -- of the Software, and to permit persons to whom the Software is furnished -- |
| 11 | -- to do so, subject to the following conditions: -- |
| 12 | -- -- |
| 13 | -- The above copyright notice and this permission notice shall be included -- |
| 14 | -- in all copies or substantial portions of the Software. -- |
| 15 | -- -- |
| 16 | -- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS -- |
| 17 | -- OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -- |
| 18 | -- MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN -- |
| 19 | -- NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, -- |
| 20 | -- DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR -- |
| 21 | -- OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE -- |
| 22 | -- USE OR OTHER DEALINGS IN THE SOFTWARE. -- |
| 23 | -- -- |
| 24 | -- Except as contained in this notice, the name(s) of the above copyright -- |
| 25 | -- holders shall not be used in advertising or otherwise to promote the -- |
| 26 | -- sale, use or other dealings in this Software without prior written -- |
| 27 | -- authorization. -- |
| 28 | ------------------------------------------------------------------------------- |
| micky387 | 9b9f5e7 | 2025-07-08 18:04:53 -0400 | [diff] [blame] | 29 | -- $Id: README.IZ,v 1.5 2021/06/17 21:20:30 tom Exp $ |
| Amit Daniel Kachhap | e6a01f5 | 2011-07-20 11:45:59 +0530 | [diff] [blame] | 30 | --------------------------------------------------------------------- |
| 31 | |
| 32 | Here is the patch. I did no testing whatsoever with event watching |
| micky387 | 9b9f5e7 | 2025-07-08 18:04:53 -0400 | [diff] [blame] | 33 | requests present (I need some applications which exercise this before |
| Amit Daniel Kachhap | e6a01f5 | 2011-07-20 11:45:59 +0530 | [diff] [blame] | 34 | this, probably lynx ;-), but the code looks working "the normal way". |
| 35 | |
| 36 | I had no way to test that the poll() branch compiles/works... |
| 37 | |
| micky387 | 9b9f5e7 | 2025-07-08 18:04:53 -0400 | [diff] [blame] | 38 | Here is the API: |
| Amit Daniel Kachhap | e6a01f5 | 2011-07-20 11:45:59 +0530 | [diff] [blame] | 39 | |
| 40 | *) two new functions wgetch_events() wgetstrn_event() are introduced, |
| 41 | which allow an event-watch specification given as the last argument; |
| 42 | |
| 43 | *) if the last argument is NULL, they behave as wgetch() and |
| 44 | wgetstrn() (TESTED!); |
| 45 | |
| 46 | *) the event specification is a pointer to _nc_eventlist, which |
| 47 | contains bookkeeping elements (count and the summary of results), |
| 48 | and an array of pointers to _nc_event; |
| 49 | |
| 50 | *) each _nc_event is a typed union, with two types supported "as |
| 51 | shipped": _NC_EVENT_TIMEOUT_MSEC, _NC_EVENT_FILE. For |
| 52 | _NC_EVENT_FILE the fields are fd, flag, and the output field. |
| 53 | |
| 54 | *) The only supported flag "as shipped" is _NC_EVENT_FILE_READABLE. |
| 55 | If the file was found readable, the return field is set to this, |
| 56 | otherwise to 0; |
| 57 | |
| 58 | *) If these functions return KEY_EVENT, this means that the return |
| 59 | fields in both the _nc_eventlist and _nc_event structures make |
| 60 | sense. The field result_flags of _nc_eventlist may have a |
| 61 | combination of bits _NC_EVENT_TIMEOUT_MSEC and _NC_EVENT_FILE_READABLE |
| 62 | set; |
| 63 | |
| 64 | *) The timeout_msec field of _NC_EVENT_TIMEOUT_MSEC _nc_event's is |
| 65 | updated on return, even if the return is not KEY_EVENT. However, |
| 66 | the change in the value represents only the amount of time spent in |
| 67 | waiting for events, not the amount of time spent bookkeeping; |
| 68 | |
| 69 | *) the return KEY_EVENT of wgetstrn_event() means that the output |
| 70 | string includes the user input typed so far, but the user did not have |
| 71 | a chance to press ENTER (or whatever). This call should be |
| 72 | repeated (with "shifted" pointer to a buffer, of course) to |
| 73 | complete the input; |
| 74 | |
| 75 | *) The presence of this extension can be checked via inspecting |
| 76 | #ifdef NCURSES_EVENT_VERSION. This symbol is not defined on BeOS, |
| 77 | since there is no support for this on BeOS. |
| 78 | |
| 79 | Known issues: calls interrupted by KEY_EVENT reset the ESCDELAY |
| 80 | timer. This is not entirely new, since other synthetic events behave |
| 81 | the same (see "if (ch >= KEY_MIN)" branch of kgetch()). However, |
| 82 | KEY_EVENT may be generated in a continuous stream (say, when |
| 83 | downloading a file), thus this may be more important than with other |
| 84 | synthetic keys. An additional field in window structure which keeps |
| 85 | timestamp of the first raw key in the queue may be needed to |
| 86 | circumvent this. |
| 87 | |
| 88 | Another possible issue: KEY_EVENT has a preference over a user input, |
| 89 | so a stream of KEY_EVENT's can make input hard. Maybe use |
| 90 | result_flags as in input parameter too, which specifies whether the |
| 91 | user input should have higher precedence? |
| 92 | |
| 93 | Also: I took an opportunity to document kgetch() better. |
| 94 | |
| 95 | Enjoy, |
| 96 | Ilya |