From d26c3ab11074c81c4a7108347ea879320a447a09 Mon Sep 17 00:00:00 2001 From: Sam Clegg Date: Fri, 14 Aug 2026 17:10:41 -0700 Subject: [PATCH] [headers] Add deprecation attributes to deprecated struct fields Mark deprecated fields in `EmscriptenKeyboardEvent`, `EmscriptenMouseEvent`, and `EmscriptenTouchPoint` with `__attribute__((deprecated(...)))` attributes in `html5.h`, and add corresponding warnings in `html5.h.rst`. Also add deprecation message to `emscripten_fetch_wait` in `fetch.h`, and add `-Wno-deprecated-declarations` to existing tests that inspect deprecated fields. --- site/source/docs/api_reference/html5.h.rst | 6 +++++ system/include/emscripten/fetch.h | 2 +- system/include/emscripten/html5.h | 26 +++++++++++++--------- test/test_browser.py | 2 +- test/test_interactive.py | 12 +++++----- 5 files changed, 30 insertions(+), 18 deletions(-) diff --git a/site/source/docs/api_reference/html5.h.rst b/site/source/docs/api_reference/html5.h.rst index bd2d6f7c46f2d..7b153d215a523 100644 --- a/site/source/docs/api_reference/html5.h.rst +++ b/site/source/docs/api_reference/html5.h.rst @@ -570,6 +570,9 @@ Struct client area (Emscripten-specific extension; coordinates are rounded down to the nearest integer). + .. warning:: These attributes are deprecated. Register a listener on the + canvas directly to get canvas coordinates, or translate manually. + .. c:member:: int padding @@ -1696,6 +1699,9 @@ Struct The touch coordinates mapped to the Emscripten canvas client area, in pixels (Emscripten-specific extension). + .. warning:: These attributes are deprecated. Register a listener on the + canvas directly to get canvas coordinates, or translate manually. + .. c:type:: EmscriptenTouchEvent diff --git a/system/include/emscripten/fetch.h b/system/include/emscripten/fetch.h index b39d05120e4c0..536e34014df67 100644 --- a/system/include/emscripten/fetch.h +++ b/system/include/emscripten/fetch.h @@ -207,7 +207,7 @@ void emscripten_fetch_attr_init(emscripten_fetch_attr_t * _Nonnull fetch_attr); // given URL or from IndexedDB database. emscripten_fetch_t *emscripten_fetch(emscripten_fetch_attr_t * _Nonnull fetch_attr, const char * _Nonnull url); -EMSCRIPTEN_RESULT emscripten_fetch_wait(emscripten_fetch_t * _Nonnull fetch, double timeoutMSecs) __attribute__((deprecated)); +EMSCRIPTEN_RESULT emscripten_fetch_wait(emscripten_fetch_t * _Nonnull fetch, double timeoutMSecs) __attribute__((deprecated("waitable fetch requests are no longer implemented"))); // Closes a finished or an executing fetch operation and frees up all memory. If // the fetch operation was still executing, the onerror() handler will be called diff --git a/system/include/emscripten/html5.h b/system/include/emscripten/html5.h index 15dd52ac8604c..4e3df3ec7d800 100644 --- a/system/include/emscripten/html5.h +++ b/system/include/emscripten/html5.h @@ -95,12 +95,12 @@ typedef struct EmscriptenKeyboardEvent { bool altKey; bool metaKey; bool repeat; - unsigned int charCode; - unsigned int keyCode; - unsigned int which; + unsigned int charCode __attribute__((deprecated("use key instead"))); + unsigned int keyCode __attribute__((deprecated("use key or code instead"))); + unsigned int which __attribute__((deprecated("use key or code instead"))); EM_UTF8 key[EM_HTML5_SHORT_STRING_LEN_BYTES]; EM_UTF8 code[EM_HTML5_SHORT_STRING_LEN_BYTES]; - EM_UTF8 charValue[EM_HTML5_SHORT_STRING_LEN_BYTES]; + EM_UTF8 charValue[EM_HTML5_SHORT_STRING_LEN_BYTES] __attribute__((deprecated("use key instead"))); EM_UTF8 locale[EM_HTML5_SHORT_STRING_LEN_BYTES]; } EmscriptenKeyboardEvent; @@ -126,9 +126,12 @@ typedef struct EmscriptenMouseEvent { int movementY; int targetX; int targetY; - // canvasX and canvasY are deprecated - there no longer exists a Module['canvas'] object, so canvasX/Y are no longer reported (register a listener on canvas directly to get canvas coordinates, or translate manually) - int canvasX; - int canvasY; + // canvasX and canvasY are deprecated - there no longer exists a + // Module['canvas'] object, so canvasX/Y are no longer reported (register a + // listener on canvas directly to get canvas coordinates, or translate + // manually) + int canvasX __attribute__((deprecated("register a listener on canvas directly to get canvas coordinates, or translate manually"))); + int canvasY __attribute__((deprecated("register a listener on canvas directly to get canvas coordinates, or translate manually"))); int padding; } EmscriptenMouseEvent; @@ -346,9 +349,12 @@ typedef struct EmscriptenTouchPoint { bool onTarget; int targetX; int targetY; - // canvasX and canvasY are deprecated - there no longer exists a Module['canvas'] object, so canvasX/Y are no longer reported (register a listener on canvas directly to get canvas coordinates, or translate manually) - int canvasX; - int canvasY; + // canvasX and canvasY are deprecated - there no longer exists a + // Module['canvas'] object, so canvasX/Y are no longer reported (register a + // listener on canvas directly to get canvas coordinates, or translate + // manually) + int canvasX __attribute__((deprecated("register a listener on canvas directly to get canvas coordinates, or translate manually"))); + int canvasY __attribute__((deprecated("register a listener on canvas directly to get canvas coordinates, or translate manually"))); } EmscriptenTouchPoint; typedef struct EmscriptenTouchEvent { diff --git a/test/test_browser.py b/test/test_browser.py index 598992b75a31c..8ddfa4ca7f014 100644 --- a/test/test_browser.py +++ b/test/test_browser.py @@ -2523,7 +2523,7 @@ def test_html5_core(self, opts): }); ''') self.cflags.append('--pre-js=pre.js') - self.btest_exit('test_html5_core.c', cflags=opts) + self.btest_exit('test_html5_core.c', cflags=opts + ['-Wno-deprecated-declarations']) def test_html5_remove_event_listener(self): self.btest_exit('test_html5_remove_event_listener.c') diff --git a/test/test_interactive.py b/test/test_interactive.py index 4677df2e607ea..dd2b1495512b9 100644 --- a/test/test_interactive.py +++ b/test/test_interactive.py @@ -27,22 +27,22 @@ def setUpClass(cls): print() def test_html5_core(self): - self.btest_exit('test_html5_core.c', cflags=['-DKEEP_ALIVE']) + self.btest_exit('test_html5_core.c', cflags=['-DKEEP_ALIVE', '-Wno-deprecated-declarations']) def test_html5_fullscreen(self): self.btest('test_html5_fullscreen.c', expected='0', cflags=['-sDISABLE_DEPRECATED_FIND_EVENT_TARGET_BEHAVIOR', '-sEXPORTED_FUNCTIONS=_requestFullscreen,_enterSoftFullscreen,_main', '--shell-file', test_file('browser/test_html5_fullscreen.html')]) def test_html5_emscripten_exit_with_escape(self): - self.btest('test_html5_emscripten_exit_fullscreen.c', expected='1', cflags=['-DEXIT_WITH_F']) + self.btest('test_html5_emscripten_exit_fullscreen.c', expected='1', cflags=['-DEXIT_WITH_F', '-Wno-deprecated-declarations']) def test_html5_emscripten_exit_fullscreen(self): - self.btest('test_html5_emscripten_exit_fullscreen.c', expected='1') + self.btest('test_html5_emscripten_exit_fullscreen.c', expected='1', cflags=['-Wno-deprecated-declarations']) def test_html5_mouse(self): self.btest_exit('test_html5_mouse.c', cflags=['-sDISABLE_DEPRECATED_FIND_EVENT_TARGET_BEHAVIOR']) def test_html5_pointerlockerror(self): - self.btest('test_html5_pointerlockerror.c', expected='0', cflags=['-sDISABLE_DEPRECATED_FIND_EVENT_TARGET_BEHAVIOR']) + self.btest('test_html5_pointerlockerror.c', expected='0', cflags=['-sDISABLE_DEPRECATED_FIND_EVENT_TARGET_BEHAVIOR', '-Wno-deprecated-declarations']) def test_sdl_mousewheel(self): self.btest_exit('test_sdl_mousewheel.c') @@ -250,7 +250,7 @@ def test_threadprofiler(self): def test_html5_callbacks_on_calling_thread(self): # TODO: Make this automatic by injecting mouse event in e.g. shell html file. for args in ([], ['-DTEST_SYNC_BLOCKING_LOOP=1']): - self.btest('html5_callbacks_on_calling_thread.c', expected='1', cflags=args + ['-sDISABLE_DEPRECATED_FIND_EVENT_TARGET_BEHAVIOR', '-pthread', '-sPROXY_TO_PTHREAD']) + self.btest('html5_callbacks_on_calling_thread.c', expected='1', cflags=args + ['-sDISABLE_DEPRECATED_FIND_EVENT_TARGET_BEHAVIOR', '-pthread', '-sPROXY_TO_PTHREAD', '-Wno-deprecated-declarations']) # Test that it is possible to register HTML5 event callbacks on either main browser thread, or # application main thread, and that the application can manually proxy the event from main browser @@ -350,7 +350,7 @@ def test_audio_worklet_memory_growth(self): os.mkdir('audio_files') copy_asset('webaudio/audio_files/emscripten-beat.mp3', 'audio_files/') copy_asset('webaudio/audio_files/emscripten-bass.mp3', 'audio_files/') - self.btest_exit('webaudio/audioworklet_memory_growth.c', cflags=['-sAUDIO_WORKLET', '-sWASM_WORKERS', '-sALLOW_MEMORY_GROWTH']) + self.btest_exit('webaudio/audioworklet_memory_growth.c', cflags=['-sAUDIO_WORKLET', '-sWASM_WORKERS', '-sALLOW_MEMORY_GROWTH', '-Wno-deprecated-declarations']) def test_html_source_map(self): # browsers will try to 'guess' the corresponding original line if a