hans/racket-webview
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

initialization and cleanup

Browse Source
This commit is contained in:
Hans Dijkema
2026-03-17 15:42:03 +01:00
parent 7c3b780ae9
commit c50267120a
9 changed files with 209 additions and 216 deletions
Download Patch File Download Diff File Expand all files Collapse all files

151
scrbl/rktwebview-api.scrbl
View File

@@ -12,36 +12,24 @@ Qt-based webviews from Racket through the FFI.
The public interface is declared in @tt{rktwebview.h}. Its implementation in
@tt{rktwebview.cpp} mainly forwards requests to the internal Qt runtime.
The API consists of:
@itemlist[#:style 'compact
@item{initialization and event processing}
@item{version and memory-management helpers}
@item{browser-context management}
@item{window creation and lifecycle control}
@item{navigation and content loading}
@item{JavaScript execution}
@item{window-state manipulation}
@item{native dialogs}
]
The API consists of initialization and event processing, version and memory-management utility
functions, http(s)-context management, window management, navigation and content loading,
JavaScript execution and native dialogs.
@section{Basic Types}
@subsection{Window and Context Handles}
The API uses integer handles for windows and browser contexts.
The API uses integer handles for windows and contexts.A value of type @tt{rktwebview_t} identifies
a single webview window and of type @tt{rkt_wv_context_t} identifies a http(s) context. Both
are typedefs of @tt{int}.
@verbatim|{
typedef int rktwebview_t;
typedef int rkt_wv_context_t;
}|
@subsection{Returned data, data for events and resultcodes}
A value of type @tt{rktwebview_t} identifies a single webview window.
A value of type @tt{rkt_wv_context_t} identifies a browser context.
@subsection{Returned Data Objects}
Some API calls return a pointer to a heap-allocated @tt{rkt_data_t} value.
The following type is used for communication of data, version information and events.
All possible data that is communicated is assembled in this one type that will be
allocated by the API and must be released by the API user, using a call to
@tt{rkt_webview_free_data()}.
@verbatim|{
typedef enum {
@@ -60,9 +48,8 @@ typedef struct {
} rkt_data_t;
}|
The @tt{kind} field determines which member of the union is valid.
@subsubsection{Version Data}
The @tt{kind} field determines which member of the union is valid. A version field
is a struct of integer numbers:
@verbatim|{
typedef struct {
@@ -75,9 +62,9 @@ typedef struct {
} rkt_version_t;
}|
Version data is returned by @tt{rkt_webview_version}.
@subsubsection{Event Data}
Events are always for webview windows and consist of the webview handle along with
an event. This event is always a Utf-8 JSON string. In this JSON string, the @tt{"event"}}
item holds the name of the event that is triggered.
@verbatim|{
typedef struct {
@@ -86,12 +73,8 @@ typedef struct {
} rkt_event_t;
}|
Event data is delivered to the registered callback when the backend emits an
event for a window.
The @tt{event} field is a UTF-8 JSON string allocated by the native side.
@subsubsection{JavaScript Result Data}
Returned data (mostly as a result of Javascript calls) consists of a result code and
a JSON encoded value. See following struct.
@verbatim|{
typedef struct {
@@ -100,84 +83,27 @@ typedef struct {
} rkt_js_result_t;
}|
JavaScript result data is returned by @tt{rkt_webview_call_js}.
Many functions return a value of type @tt{result_t}. The possible enumeration values
can be found in @tt{rktwebview.h}. Most important are the values @tt{no_result_yet}, which
is for internal use and equals @tt{-1}; @tt{oke = 0}, which tells that everything went alright,
and all values @tt{>0} indicate some kind of failure.
The @tt{value} field contains a UTF-8 JSON string describing the result of the
JavaScript evaluation.
@subsection{Window state}
@subsection{Result Codes}
Window state is represented by @tt{window_state_t}. The following values are used:
@tt{invalid = -1}, represents an invalid window state, @tt{normal = 0x00} and @tt{normal_active = 0x10},
window shown in normal state (0x00). All windows that are active, i.e. have focus for user input, will
have bit 5 set to 1. Other states: @tt{minimized = 0x01}, @tt{maximized = 0x02} or @tt{0x12},
@tt{hidden = 0x03}.
Many functions return a value of type @tt{result_t}.
@subsection{Messagebox types}
@verbatim|{
typedef enum {
no_result_yet = -1,
oke = 0,
set_html_failed = 1,
set_navigate_failed = 2,
eval_js_failed = 3,
no_devtools_on_platform = 4,
no_delegate_for_context = 5,
webview_missing_dependency = 6,
webview_canceled = 7,
webview_invalid_state = 8,
webview_invalid_argument = 9,
webview_unspecified = 10,
webview_dispatch_failed = 11,
move_failed = 12,
resize_failed = 13,
choose_dir_failed = 14,
open_file_failed = 15,
save_file_failed = 16,
failed = 17
} result_t;
}|
Message boxes use the type @tt{rkt_messagetype_t} to indicate the type of message to present:
@tt{info = 1} for information, @tt{error = 2} for error messages, @tt{warning = 3} for warnings,
@tt{yes_no = 4} for questions that can be answered by 'yes' or 'no' and @tt{oke_cancel} for messages
that can be answered by 'oke' or 'cancel'.
In the current implementation, the most commonly returned values are:
@itemlist[#:style 'compact
@item{@tt{oke} for success}
@item{@tt{set_html_failed} for @tt{rkt_webview_set_html}}
@item{@tt{set_navigate_failed} for @tt{rkt_webview_set_url}}
@item{@tt{eval_js_failed} for JavaScript execution failure}
@item{@tt{move_failed} for failed move requests}
@item{@tt{resize_failed} for failed resize requests}
@item{@tt{failed} for general window-operation failure}
]
@subsection{Window States}
Window state is represented by @tt{window_state_t}.
@verbatim|{
typedef enum {
invalid = -1,
normal = 0,
minimized = 1,
maximized = 2,
hidden = 3,
normal_active = 16,
maximized_active = 18
} window_state_t;
}|
This type is returned by @tt{rkt_webview_window_state}.
@subsection{Message Box Types}
Message boxes use the type @tt{rkt_messagetype_t}.
@verbatim|{
typedef enum {
info = 1,
error = 2,
warning = 3,
yes_no = 4,
oke_cancel = 5
} rkt_messagetype_t;
}|
@subsection{Event Callback Type}
@subsection{Callback functions for events}
A window is created with an event callback of the following type:
@@ -185,13 +111,10 @@ A window is created with an event callback of the following type:
typedef void (*event_cb_t)(rkt_data_t *);
}|
The callback receives a pointer to a @tt{rkt_data_t} whose @tt{kind} is
@tt{event}.
The callback receives a pointer to a @tt{rkt_data_t} whose @tt{kind} is @tt{event}. The callback
argument must eventually be released by calling @tt{rkt_webview_free_data}.
The callback argument must eventually be released by calling
@tt{rkt_webview_free_data}.
@subsection{Memory Ownership}
@subsection{Memory management}
The following functions return heap-allocated @tt{rkt_data_t *} values: