Nhraykey.dll - Revision history

Ray Chason: Note merger of nh*key.dll to main binary in 3.7

2022-06-05T23:05:25Z

Note merger of nh*key.dll to main binary in 3.7

Ray Chason: Bug W343-4 is fixed in 3.6.1

2018-05-13T15:41:50Z

Bug W343-4 is fixed in 3.6.1

Ray Chason: W343-4 fixed in Git

2016-03-06T22:21:29Z

W343-4 fixed in Git

Tjr: link to individual bug

2013-03-09T07:21:50Z

link to individual bug

Paxed: Text replace - "bilious.homelinux.org" to "bilious.alt.org"

2011-05-08T17:30:12Z

Text replace - "bilious.homelinux.org" to "bilious.alt.org"

Rogerb-on-NAO: use Template:main; tag for 343.

2008-06-10T16:09:27Z

use Template:main; tag for 343.

Ray Chason: Bilious has a patch to fix W343-3 and W343-4

2008-01-18T04:23:57Z

Bilious has a patch to fix W343-3 and W343-4

Jayt: category:annotations

2006-08-25T21:44:00Z

category:annotations

Ray Chason: Slight unhosing

2006-08-24T02:58:26Z

Slight unhosing

Ray Chason: Initial revision

2006-08-24T02:55:43Z

Initial revision

New page

'''Nhraykey.dll''' is a keyboard handler for the [[Microsoft Windows]] text-mode version of [[NetHack 3.4.3]]. Its purpose is to improve handling of keyboards with non-USA layouts.

Unfortunately it suffers from a minor but annoying [[Bugs in NetHack 3.4.3|bug]], [[W343-4]].

== How it works ==

NetHack wants both keyboard and mouse input, but the Win32 console APIs provide no easy way of getting mouse input and also translating keystrokes according to the user's locale. The ReadConsole API retrieves keystrokes and translates them properly, but discards mouse events. The ReadConsoleInput API retrieves key and mouse events but does not translate the keys.

[[NetHack 3.4.1]] attempted to solve this problem by reading all input with ReadConsoleInput and passing it to the ToAscii API. The default keyboard handler, [[nhdefkey.dll]], still works this way. This approach, however, only seems to work with USA keyboards. With others, it ends up using the USA layout, and the user is likely to find this confusing.

Nhraykey.dll takes a different approach. First, it notes that commands have different needs from prompts:
* When NetHack is waiting for a command, such as (d)rop or one of the hjklyubn keys, it wants any of three kinds of input: an [[ASCII]] character, a character with the eighth bit set to indicate an
Alt sequence, or a mouse event. We do not want to send a non-ASCII character except in response to an Alt sequence, else the game might give surprising behavior, even accidentally invoking the #[[quit]] command.
* When NetHack has prompted for text, the mouse is unimportant, and we don't want Alt sequences; but we do want any character that the user can type, ASCII or not.

So it separates these two functions, which had previously been one, and solves the problem according to the needs of each mode. For a command, it first uses PeekConsoleInput to determine what type of input is available. For a key event, it goes to ReadConsole to retrieve the key properly translated. For a mouse event, it goes to ReadConsoleInput to fetch the event.

The idea is never to call ReadConsole when a mouse event is important, unless we can be sure that it will not block; if that happened, the mouse would cease to function until it returned. ReadConsole is prevented from blocking by pushing a bogus key event on the queue; if there's nothing else for ReadConsole to fetch, it will fetch the bogus key. The bogus key is constructed so that it does not match any real key event, and can be filtered out.

For prompts, ReadConsole is used directly, because mouse events are not needed.

== Bug W343-4 ==

''Main article: [[W343-4]]''

There is one point at which the unmodified nhraykey.dll needs to filter the bogus key, but fails to do so. This can result in ReadConsole being called and blocking because there is no real key for it to read. A [[patch]] is available for this bug, and it is listed as fixed in the next release.

== Further reading ==

[http://groups.google.com/group/rec.games.roguelike.nethack/browse_frm/thread/76c79f23e56a210f The patch] against [[NetHack 3.4.1]] that became nhraykey.dll.

[http://groups.google.com/group/rec.games.roguelike.nethack/browse_frm/thread/5218c0df964795f7 Description] of the patch.

[http://groups.google.com/group/rec.games.roguelike.nethack/browse_frm/thread/e92013db64618fe3 Fix] for bug W343-4.

← Older revision		Revision as of 23:05, 5 June 2022
Line 1:		Line 1:
	'''Nhraykey.dll''' is a keyboard handler for the [[Microsoft Windows]] text-mode version of [[NetHack 3.4.3]]. Its purpose is to improve handling of keyboards with non-USA layouts.		'''Nhraykey.dll''' is a keyboard handler for the [[Microsoft Windows]] text-mode version of [[NetHack 3.4.3]]. Its purpose is to improve handling of keyboards with non-USA layouts.
		+
		+	This is a separate DLL in NetHack 3.4.2 through 3.6.6. In the current development version, it is merged into the main binary, along with its alternatives, nhdefkey.dll and nh340key.dll.

	== How it works ==		== How it works ==

@@ Line 1: / Line 1: @@
 '''Nhraykey.dll''' is a keyboard handler for the [[Microsoft Windows]] text-mode version of [[NetHack 3.4.3]].  Its purpose is to improve handling of keyboards with non-USA layouts.
 == How it works ==
@@ Line 23: / Line 21: @@
 {{main|W343-4}}
-There is one point at which the unmodified nhraykey.dll needs to filter the bogus key, but fails to do so.  This can result in ReadConsole being called and blocking because there is no real key for it to read.  A [[patch]] is available for this bug, and it is listed as fixed in the next release.
+There is one point at which the unmodified nhraykey.dll needs to filter the bogus key, but fails to do so.  This can result in ReadConsole being called and blocking because there is no real key for it to read.  A [[patch]] is available to fix this bug in 3.4.3, and it is fixed in 3.6.1.<ref>[https://github.com/NetHack/NetHack/commit/78857961d2b40f01516ec3ecdafd348c79142bbc#diff-fa02d0cc210b095a04eaed9c7fbbd331 DevTeam GitHub repository, commit 7885796.]</ref>
 == Further reading ==
@@ Line 37: / Line 35: @@
 [[Category:Annotations]]
-{{nethack-360}}
+{{nethack-361}}

@@ Line 1: / Line 1: @@
 '''Nhraykey.dll''' is a keyboard handler for the [[Microsoft Windows]] text-mode version of [[NetHack 3.4.3]].  Its purpose is to improve handling of keyboards with non-USA layouts.
-Unfortunately it suffers from a minor but annoying [[Bugs in NetHack 3.4.3#W343-4|bug]], [[W343-4]].  [http://bilious.alt.org/?313 This patch] from the [[Bilious Patch Database]] fixes this bug and also [[W343-3]].
+Unfortunately it suffers from a minor but annoying [[Bugs in NetHack 3.4.3#W343-4|bug]], [[W343-4]].  [http://bilious.alt.org/?313 This patch] from the [[Bilious Patch Database]] fixes this bug and also [[W343-3]]. It is not fixed in [[NetHack 3.6.0]], despite being listed as fixed, but it is fixed in Git.<ref>[https://github.com/NetHack/NetHack/commit/78857961d2b40f01516ec3ecdafd348c79142bbc#diff-fa02d0cc210b095a04eaed9c7fbbd331 DevTeam GitHub repository, commit 7885796.]</ref>
 == How it works ==
@@ Line 32: / Line 32: @@
 [http://groups.google.com/group/rec.games.roguelike.nethack/browse_frm/thread/e92013db64618fe3 Fix] for bug W343-4.
 [[Category:Annotations]]
-{{nethack-343}}
+{{nethack-360}}

@@ Line 1: / Line 1: @@
 '''Nhraykey.dll''' is a keyboard handler for the [[Microsoft Windows]] text-mode version of [[NetHack 3.4.3]].  Its purpose is to improve handling of keyboards with non-USA layouts.
-Unfortunately it suffers from a minor but annoying [[Bugs in NetHack 3.4.3|bug]], [[W343-4]].  [http://bilious.alt.org/?313 This patch] from the [[Bilious Patch Database]] fixes this bug and also [[W343-3]].
+Unfortunately it suffers from a minor but annoying [[Bugs in NetHack 3.4.3#W343-4|bug]], [[W343-4]].  [http://bilious.alt.org/?313 This patch] from the [[Bilious Patch Database]] fixes this bug and also [[W343-3]].
 == How it works ==

@@ Line 1: / Line 1: @@
 '''Nhraykey.dll''' is a keyboard handler for the [[Microsoft Windows]] text-mode version of [[NetHack 3.4.3]].  Its purpose is to improve handling of keyboards with non-USA layouts.
-Unfortunately it suffers from a minor but annoying [[Bugs in NetHack 3.4.3|bug]], [[W343-4]].  [http://bilious.homelinux.org/?313 This patch] from the [[Bilious Patch Database]] fixes this bug and also [[W343-3]].
+Unfortunately it suffers from a minor but annoying [[Bugs in NetHack 3.4.3|bug]], [[W343-4]].  [http://bilious.alt.org/?313 This patch] from the [[Bilious Patch Database]] fixes this bug and also [[W343-3]].
 == How it works ==

@@ Line 21: / Line 21: @@
 == Bug W343-4 ==
-''Main article:  [[W343-4]]''
+{{main|W343-4}}
 There is one point at which the unmodified nhraykey.dll needs to filter the bogus key, but fails to do so.  This can result in ReadConsole being called and blocking because there is no real key for it to read.  A [[patch]] is available for this bug, and it is listed as fixed in the next release.
@@ Line 34: / Line 34: @@
 [[Category:Annotations]]

← Older revision		Revision as of 21:44, 25 August 2006
Line 32:		Line 32:

	[http://groups.google.com/group/rec.games.roguelike.nethack/browse_frm/thread/e92013db64618fe3 Fix] for bug W343-4.		[http://groups.google.com/group/rec.games.roguelike.nethack/browse_frm/thread/e92013db64618fe3 Fix] for bug W343-4.
		+
		+	[[Category:Annotations]]

@@ Line 10: / Line 10: @@
 Nhraykey.dll takes a different approach.  First, it notes that commands have different needs from prompts:
-* When NetHack is waiting for a command, such as (d)rop or one of the hjklyubn keys, it wants any of three kinds of input:  an [[ASCII]] character, a character with the eighth bit set to indicate an
+* When NetHack is waiting for a command, such as (d)rop or one of the hjklyubn keys, it wants any of three kinds of input:  an [[ASCII]] character, a character with the eighth bit set to indicate an Alt sequence, or a mouse event.  We do not want to send a non-ASCII character except in response to an Alt sequence, else the game might give surprising behavior, even accidentally invoking the #[[quit]] command.
 * When NetHack has prompted for text, the mouse is unimportant, and we don't want Alt sequences; but we do want any character that the user can type, ASCII or not.