<feed xmlns='http://www.w3.org/2005/Atom'>
<title>puzzles/devel.but, branch master</title>
<subtitle>My sgt-puzzles tree</subtitle>
<link rel='alternate' type='text/html' href='https://www.franklinwei.com/cgit/puzzles/'/>
<entry>
<title>Fix typo in developer docs for request_keys().</title>
<updated>2024-07-31T22:29:00+00:00</updated>
<author>
<name>Franklin Wei</name>
<email>franklin@rockbox.org</email>
</author>
<published>2020-06-29T02:41:29+00:00</published>
<link rel='alternate' type='text/html' href='https://www.franklinwei.com/cgit/puzzles/commit/?id=c70878c4adde680fc569ff9ab75e49581c907fa5'/>
<id>c70878c4adde680fc569ff9ab75e49581c907fa5</id>
<content type='text'>
"point"-&gt;"pointer".
</content>
<content type='xhtml'>
<div xmlns='http://www.w3.org/1999/xhtml'>
<pre>
"point"-&gt;"pointer".
</pre>
</div>
</content>
</entry>
<entry>
<title>Rename memswap() to swap_regions(). Consolidate duplicate implementations.</title>
<updated>2024-07-31T22:29:00+00:00</updated>
<author>
<name>Franklin Wei</name>
<email>franklin@rockbox.org</email>
</author>
<published>2024-07-21T22:33:01+00:00</published>
<link rel='alternate' type='text/html' href='https://www.franklinwei.com/cgit/puzzles/commit/?id=a2f7f962ced158dbceebbfc0c3dfbbc58b119e55'/>
<id>a2f7f962ced158dbceebbfc0c3dfbbc58b119e55</id>
<content type='text'>
C99 reserves the mem* namespace for future expansion. Some Rockbox
targets had issues with memswap() conflicting with another definition,
so fix that.
</content>
<content type='xhtml'>
<div xmlns='http://www.w3.org/1999/xhtml'>
<pre>
C99 reserves the mem* namespace for future expansion. Some Rockbox
targets had issues with memswap() conflicting with another definition,
so fix that.
</pre>
</div>
</content>
</entry>
<entry>
<title>Refactor `button &amp; ~MOD_MASK' as `STRIP_BUTTON_MODIFIERS(button)'.</title>
<updated>2024-07-31T22:29:00+00:00</updated>
<author>
<name>Franklin Wei</name>
<email>franklin@rockbox.org</email>
</author>
<published>2024-07-21T22:06:37+00:00</published>
<link rel='alternate' type='text/html' href='https://www.franklinwei.com/cgit/puzzles/commit/?id=5de69c22b0ff037f648a740a7c01869e78587df2'/>
<id>5de69c22b0ff037f648a740a7c01869e78587df2</id>
<content type='text'>
This refactors all instances of bitwise-ANDs with `~MOD_MASK'. There is
a handful of more complex instances I left unchanged (in cube.c, midend.c,
and twiddle.c), since those AND with `~MOD_MASK | MOD_NUM_KEYPAD' or
similar. I don't think it's worth writing a macro for those cases.

Also document this new macro's usage in devel.but.
</content>
<content type='xhtml'>
<div xmlns='http://www.w3.org/1999/xhtml'>
<pre>
This refactors all instances of bitwise-ANDs with `~MOD_MASK'. There is
a handful of more complex instances I left unchanged (in cube.c, midend.c,
and twiddle.c), since those AND with `~MOD_MASK | MOD_NUM_KEYPAD' or
similar. I don't think it's worth writing a macro for those cases.

Also document this new macro's usage in devel.but.
</pre>
</div>
</content>
</entry>
<entry>
<title>midend_process_key: allow Shift+Tab to pass through to the backend.</title>
<updated>2024-07-31T22:29:00+00:00</updated>
<author>
<name>Franklin Wei</name>
<email>franklin@rockbox.org</email>
</author>
<published>2024-07-21T08:49:06+00:00</published>
<link rel='alternate' type='text/html' href='https://www.franklinwei.com/cgit/puzzles/commit/?id=3f8ef290786fbaf7b9ec200a2fd598eb324c6b0c'/>
<id>3f8ef290786fbaf7b9ec200a2fd598eb324c6b0c</id>
<content type='text'>
Previously, a button code of ('\t' | MOD_SHFT) from a frontend would have
the MOD_SHFT flag stripped by midend_process_key, resulting in a bare '\t'
passed to the backend. Now, this combination is allowed to pass through to
the backend. This will be used in the keyboard interface to Untangle, which
I'm about to add.
</content>
<content type='xhtml'>
<div xmlns='http://www.w3.org/1999/xhtml'>
<pre>
Previously, a button code of ('\t' | MOD_SHFT) from a frontend would have
the MOD_SHFT flag stripped by midend_process_key, resulting in a bare '\t'
passed to the backend. Now, this combination is allowed to pass through to
the backend. This will be used in the keyboard interface to Untangle, which
I'm about to add.
</pre>
</div>
</content>
</entry>
<entry>
<title>move_cursor(): handle visible flag; return useful value</title>
<updated>2023-08-09T10:44:25+00:00</updated>
<author>
<name>Ben Harris</name>
<email>bjh21@bjh21.me.uk</email>
</author>
<published>2023-08-09T08:43:04+00:00</published>
<link rel='alternate' type='text/html' href='https://www.franklinwei.com/cgit/puzzles/commit/?id=5ec86c03a8bc911bb3dbd77fb7c827eeca975594'/>
<id>5ec86c03a8bc911bb3dbd77fb7c827eeca975594</id>
<content type='text'>
This adds an extra parameter to move_cursor() that's an optional pointer
to a bool indicating whether the cursor is visible.  This allows for
centralising the common idiom of having the keyboard cursor become
visible when a cursor key is pressed.  Consistently with the vast
majority of existing puzzles, the cursor moves even if it was invisible
before, and becomes visible even if it can't move.

The function now also returns one of the special constants that can be
returned by interpret_move(), so that the caller can correctly return
MOVE_UI_UPDATE or MOVE_NO_EFFECT without needing to carefully check for
changes itself.

Callers are updated only to the extent that they all pass NULL as the
new argument.  Most of them could now be substantially simplified.
</content>
<content type='xhtml'>
<div xmlns='http://www.w3.org/1999/xhtml'>
<pre>
This adds an extra parameter to move_cursor() that's an optional pointer
to a bool indicating whether the cursor is visible.  This allows for
centralising the common idiom of having the keyboard cursor become
visible when a cursor key is pressed.  Consistently with the vast
majority of existing puzzles, the cursor moves even if it was invisible
before, and becomes visible even if it can't move.

The function now also returns one of the special constants that can be
returned by interpret_move(), so that the caller can correctly return
MOVE_UI_UPDATE or MOVE_NO_EFFECT without needing to carefully check for
changes itself.

Callers are updated only to the extent that they all pass NULL as the
new argument.  Most of them could now be substantially simplified.
</pre>
</div>
</content>
</entry>
<entry>
<title>Expose the NO_EFFECT/UNUSED distinction through midend_process_key()</title>
<updated>2023-06-10T23:33:28+00:00</updated>
<author>
<name>Ben Harris</name>
<email>bjh21@bjh21.me.uk</email>
</author>
<published>2023-06-07T22:03:30+00:00</published>
<link rel='alternate' type='text/html' href='https://www.franklinwei.com/cgit/puzzles/commit/?id=1547154efbfcf0bd8f6fc4f91fe99c26371fe0ee'/>
<id>1547154efbfcf0bd8f6fc4f91fe99c26371fe0ee</id>
<content type='text'>
This removed the "handled" pointer and instead extends the existing
boolean return value (quit or don't quit) into an enumeration.  One of
the values still quits the program, but now there are different values
for keys that had an effect, had no effect, and are not used by the
puzzle at all.  The mapping from interpret_move results to process_key
results is roughly:

move string    -&gt; PKR_SOME_EFFECT
MOVE_UI_UPDATE -&gt; PKR_SOME_EFFECT
MOVE_NO_EFFECT -&gt; PKR_NO_EFFECT
MOVE_UNUSED    -&gt; PKR_UNUSED

The mid-end can also generate results internally, and is the only place
that PKR_QUIT can arise.

For compatibility, PKR_QUIT is zero, so anything expecting a false
return value to mean quit will be unsurprised.  The other values are
ordered so that lower values indicate a greater amount of handling of
the key.
</content>
<content type='xhtml'>
<div xmlns='http://www.w3.org/1999/xhtml'>
<pre>
This removed the "handled" pointer and instead extends the existing
boolean return value (quit or don't quit) into an enumeration.  One of
the values still quits the program, but now there are different values
for keys that had an effect, had no effect, and are not used by the
puzzle at all.  The mapping from interpret_move results to process_key
results is roughly:

move string    -&gt; PKR_SOME_EFFECT
MOVE_UI_UPDATE -&gt; PKR_SOME_EFFECT
MOVE_NO_EFFECT -&gt; PKR_NO_EFFECT
MOVE_UNUSED    -&gt; PKR_UNUSED

The mid-end can also generate results internally, and is the only place
that PKR_QUIT can arise.

For compatibility, PKR_QUIT is zero, so anything expecting a false
return value to mean quit will be unsurprised.  The other values are
ordered so that lower values indicate a greater amount of handling of
the key.
</pre>
</div>
</content>
</entry>
<entry>
<title>Add MOVE_NO_EFFECT and MOVE_UNUSED return values from interpret_move()</title>
<updated>2023-06-10T23:33:27+00:00</updated>
<author>
<name>Ben Harris</name>
<email>bjh21@bjh21.me.uk</email>
</author>
<published>2023-06-04T18:02:21+00:00</published>
<link rel='alternate' type='text/html' href='https://www.franklinwei.com/cgit/puzzles/commit/?id=a943f3177f4adc591a282bdc62eef80675dc2a67'/>
<id>a943f3177f4adc591a282bdc62eef80675dc2a67</id>
<content type='text'>
These allow for distinguishing the case where a puzzle doesn't have a
use for a key from the case where it just happens to have no effect in
the current state of the puzzle.  These were both represented by NULL,
but that now represents the case where a puzzle hasn't been updated to
make the distinction yet.
</content>
<content type='xhtml'>
<div xmlns='http://www.w3.org/1999/xhtml'>
<pre>
These allow for distinguishing the case where a puzzle doesn't have a
use for a key from the case where it just happens to have no effect in
the current state of the puzzle.  These were both represented by NULL,
but that now represents the case where a puzzle hasn't been updated to
make the distinction yet.
</pre>
</div>
</content>
</entry>
<entry>
<title>Rename UI_UPDATE as MOVE_UI_UPDATE</title>
<updated>2023-06-10T23:33:27+00:00</updated>
<author>
<name>Ben Harris</name>
<email>bjh21@bjh21.me.uk</email>
</author>
<published>2023-06-04T17:42:58+00:00</published>
<link rel='alternate' type='text/html' href='https://www.franklinwei.com/cgit/puzzles/commit/?id=a9af3fda1d784c42d486a019a0a4e947f762af70'/>
<id>a9af3fda1d784c42d486a019a0a4e947f762af70</id>
<content type='text'>
All the other constants named UI_* are special key names that can be
passed to midend_process_key(), but UI_UPDATE is a special return value
from the back-end interpret_move() function instead.  This renaming
makes the distinction clear and provides a naming convention for future
special return values from interpret_move().
</content>
<content type='xhtml'>
<div xmlns='http://www.w3.org/1999/xhtml'>
<pre>
All the other constants named UI_* are special key names that can be
passed to midend_process_key(), but UI_UPDATE is a special return value
from the back-end interpret_move() function instead.  This renaming
makes the distinction clear and provides a naming convention for future
special return values from interpret_move().
</pre>
</div>
</content>
</entry>
<entry>
<title>Keep a set of preferences in the midend.</title>
<updated>2023-04-23T12:25:57+00:00</updated>
<author>
<name>Simon Tatham</name>
<email>anakin@pobox.com</email>
</author>
<published>2023-04-22T11:54:11+00:00</published>
<link rel='alternate' type='text/html' href='https://www.franklinwei.com/cgit/puzzles/commit/?id=bb1ab36108942ed9b0c84bf68e22869994467a2a'/>
<id>bb1ab36108942ed9b0c84bf68e22869994467a2a</id>
<content type='text'>
This commit introduces a serialisation format for the user preferences
stored in game_ui, using the keyword identifiers that get_prefs is
required to write into its list of config_item. As a result, the
serialisation format looks enough like an ordinary config file that a
user could write one by hand.

The preferences for the game backend are kept in serialised form in
me-&gt;be_prefs. The typical use of this is to apply it to a just-created
game_ui by calling midend_apply_prefs(), which deserialises the prefs
buffer into a list of config_item and passes it to the backend's
set_prefs function, overwriting the preference fields (but no others)
of the game_ui.

This is duly done when creating a new game, when loading a game from a
save file, and also when printing a puzzle. To make the latter work,
document_add_puzzle now takes a game_ui (and keeps ownership of it
afterwards), and passes that to the backend's compute_size and print
functions.

The backend's own get_prefs and set_prefs functions are wrapped by
midend_get_prefs and midend_set_prefs. This is partly as a convenience
(it deals with optionally constructing a game_ui specially to call the
backend with), but mostly so that there will be a convenient place in
the midend to add standard preferences applying across all puzzles.
No cross-puzzle preferences are provided yet.

There are two external interfaces to all this, and in this commit,
neither one is yet called by any frontend:

A new pair of midend functions is exposed to the front end, called
midend_load_prefs and midend_save_prefs. These have a similar API to
midend_serialise and midend_deserialise, taking a read/write function
pointer and a context. So front ends that can already load/save a game
to a file on disk should find it easy to add a similar set of
functions loading/saving user preferences.

Secondly, a new value CFG_PREFS is added to the enumeration of
configuration dialog types, alongside the ones for the Custom game
type, entering a game description and entering a random seed. This
should make it easy for frontends to offer a Preferences dialog,
because it will operate almost exactly like three dialogs they already
handle.
</content>
<content type='xhtml'>
<div xmlns='http://www.w3.org/1999/xhtml'>
<pre>
This commit introduces a serialisation format for the user preferences
stored in game_ui, using the keyword identifiers that get_prefs is
required to write into its list of config_item. As a result, the
serialisation format looks enough like an ordinary config file that a
user could write one by hand.

The preferences for the game backend are kept in serialised form in
me-&gt;be_prefs. The typical use of this is to apply it to a just-created
game_ui by calling midend_apply_prefs(), which deserialises the prefs
buffer into a list of config_item and passes it to the backend's
set_prefs function, overwriting the preference fields (but no others)
of the game_ui.

This is duly done when creating a new game, when loading a game from a
save file, and also when printing a puzzle. To make the latter work,
document_add_puzzle now takes a game_ui (and keeps ownership of it
afterwards), and passes that to the backend's compute_size and print
functions.

The backend's own get_prefs and set_prefs functions are wrapped by
midend_get_prefs and midend_set_prefs. This is partly as a convenience
(it deals with optionally constructing a game_ui specially to call the
backend with), but mostly so that there will be a convenient place in
the midend to add standard preferences applying across all puzzles.
No cross-puzzle preferences are provided yet.

There are two external interfaces to all this, and in this commit,
neither one is yet called by any frontend:

A new pair of midend functions is exposed to the front end, called
midend_load_prefs and midend_save_prefs. These have a similar API to
midend_serialise and midend_deserialise, taking a read/write function
pointer and a context. So front ends that can already load/save a game
to a file on disk should find it easy to add a similar set of
functions loading/saving user preferences.

Secondly, a new value CFG_PREFS is added to the enumeration of
configuration dialog types, alongside the ones for the Custom game
type, entering a game description and entering a random seed. This
should make it easy for frontends to offer a Preferences dialog,
because it will operate almost exactly like three dialogs they already
handle.
</pre>
</div>
</content>
</entry>
<entry>
<title>Require games to accept new_ui(NULL) if they have preferences.</title>
<updated>2023-04-23T12:25:06+00:00</updated>
<author>
<name>Simon Tatham</name>
<email>anakin@pobox.com</email>
</author>
<published>2023-04-22T09:51:37+00:00</published>
<link rel='alternate' type='text/html' href='https://www.franklinwei.com/cgit/puzzles/commit/?id=ea6be8f0af766ed15b19260ae17fa793d3d6d4d8'/>
<id>ea6be8f0af766ed15b19260ae17fa793d3d6d4d8</id>
<content type='text'>
This will be necessary in the next commit, so that the midend can make
a game_ui out of nothing in order to store preferences in it.

The only game actually affected by this requirement is Pearl, which
has a preference (GUI style) and also allocates space based on the
game_state's grid size to store the coordinates of a path being
dragged, so if there is no game_state, it can't do the latter - which
is OK, because it also won't be expected to.
</content>
<content type='xhtml'>
<div xmlns='http://www.w3.org/1999/xhtml'>
<pre>
This will be necessary in the next commit, so that the midend can make
a game_ui out of nothing in order to store preferences in it.

The only game actually affected by this requirement is Pearl, which
has a preference (GUI style) and also allocates space based on the
game_state's grid size to store the coordinates of a path being
dragged, so if there is no game_state, it can't do the latter - which
is OK, because it also won't be expected to.
</pre>
</div>
</content>
</entry>
</feed>
