Class CefHost
Namespace: ReadyM.Cef
Assembly: ReadyM.Cef.dll
The one place that knows every viewport and every browser this reload cycle created.
public sealed class CefHost : IDisposable, IPageMessageTransport
Inheritance
Implements
IDisposable, IPageMessageTransport
Inherited Members
object.GetType(), object.ToString(), object.Equals(object?), object.Equals(object?, object?), object.ReferenceEquals(object?, object?), object.GetHashCode()
Remarks
It exists so everything can be torn down at the end of a cycle without depending on mods to clean up after themselves. There is deliberately no ownership or permission model: a handle can be passed to anyone.
Properties
Browsers
Browsers that currently exist, in creation order.
public IReadOnlyCollection<BrowserHandle> Browsers { get; }
Property Value
IReadOnlyCollection<BrowserHandle>
Viewports
Viewports that currently exist, in creation order.
public IReadOnlyCollection<ViewportHandle> Viewports { get; }
Property Value
IReadOnlyCollection<ViewportHandle>
Methods
Assign(ViewportHandle, BrowserHandle?)
Shows browser in viewport, or clears the viewport when
browser is null.
public void Assign(ViewportHandle viewport, BrowserHandle? browser)
Parameters
viewport ViewportHandle
browser BrowserHandle?
Remarks
Assigning a browser that is already shown somewhere else MOVES it: a browser is in at most one viewport, because a client has a single render handler slot and a browser therefore paints one surface. The browser is not recreated and its page is not reloaded, which is the point of the split.
BrowserIn(ViewportHandle)
The browser currently shown in viewport, or null.
public BrowserHandle? BrowserIn(ViewportHandle viewport)
Parameters
viewport ViewportHandle
Returns
CreateBrowser()
Creates a browser. It does not exist yet, and nothing here waits for it.
public CefBrowserInstance CreateBrowser()
Returns
Remarks
The returned instance works immediately: anything asked of it before CEF has finished is queued and run in order once the browser arrives. A session with no CEF gets an instance too, and every operation on it does nothing, so a mod is written once rather than twice.
CreateViewport(int)
Creates a viewport: a place a browser can be shown, with no browser in it yet.
public ViewportHandle CreateViewport(int zOrder)
Parameters
zOrder int
Fixed for the life of the viewport.
Returns
Remarks
A browser is assigned afterwards, which is what lets the same content move between viewports without being recreated.
DestroyBrowser(BrowserHandle)
Destroys a browser and forgets it. Any viewport showing it is left showing nothing.
public void DestroyBrowser(BrowserHandle browser)
Parameters
browser BrowserHandle
Remarks
Expensive and rare, unlike Boolean). A browser takes real time to create and to navigate, so hiding a viewport is how you put UI away; destroying the browser is how you give the resources back when you are done with the content entirely.
DestroyViewport(ViewportHandle)
Destroys a viewport. Any browser shown in it survives, with nothing showing it.
public void DestroyViewport(ViewportHandle viewport)
Parameters
viewport ViewportHandle
Dispose()
Tears down everything this registry created, whether or not anyone disposed it.
public void Dispose()
Remarks
This is the end of a reload cycle. Browsers deliberately do not survive one: the outgoing cycle destroys what it created and the incoming one creates its own, so page state is lost and the UI blinks out and returns. Carrying browsers across would mean carrying every handler and delegate pointer with them, for ever, growing with each browser a mod created.
IsFocusable(ViewportHandle)
Whether the engine may focus this viewport.
public bool IsFocusable(ViewportHandle viewport)
Parameters
viewport ViewportHandle
Returns
IsVisible(ViewportHandle)
Whether a viewport is currently shown.
public bool IsVisible(ViewportHandle viewport)
Parameters
viewport ViewportHandle
Returns
Navigate(BrowserHandle, string)
Points a browser at url, now or as soon as it exists.
public void Navigate(BrowserHandle browser, string url)
Parameters
browser BrowserHandle
url string
PlacementOf(ViewportHandle)
Where this viewport sits and how big it is, as last set.
public ViewportPlacement PlacementOf(ViewportHandle viewport)
Parameters
viewport ViewportHandle
Returns
RegisterFile(string, string, string)
Serves one file at
readym://host/pathpublic void RegisterFile(string host, string path, string file)
Parameters
host string
path string
file string
RegisterFolder(string, string)
Serves everything under directory at
readym://host/public void RegisterFolder(string host, string directory)
Parameters
host string
directory string
Remarks
The host is chosen by the caller. Two mods may pick the same one, share its storage, and replace each other's pages: mods integrating with each other is the point, and keeping them apart is an explicit non-target.
Reload(BrowserHandle)
Reloads whatever a browser is showing, now or as soon as it exists.
public void Reload(BrowserHandle browser)
Parameters
browser BrowserHandle
ReloadAll()
Reloads every browser that exists, ignoring the cache, and returns how many were asked.
public int ReloadAll()
Returns
Remarks
For picking up an edited page without restarting the game. The cache is ignored so a subresource a page already holds is refetched too: a plain reload can keep an old stylesheet while the document is new.
SendRaw(BrowserHandle, long, string, PayloadKind, ReadOnlySpan<byte>)
Sends one named message to a page, filling CEF's own shared region so nothing is buffered on the way.
public void SendRaw(BrowserHandle browser, long requestId, string name, PayloadKind kind, ReadOnlySpan<byte> payload)
Parameters
browser BrowserHandle
requestId long
name string
kind PayloadKind
payload ReadOnlySpan<byte>
Remarks
THE ONLY WAY OUT, whatever the payload means. There is no overload per payload shape here, because each one would be a small decision about meaning taken in the class that should hold none.
SetCursorVisible(bool)
Whether the game draws a mouse cursor. See Boolean): same caveat.
public void SetCursorVisible(bool visible)
Parameters
visible bool
SetFocusable(ViewportHandle, bool)
Whether the engine may give viewport the keyboard at all. True unless set otherwise.
public void SetFocusable(ViewportHandle viewport, bool focusable)
Parameters
viewport ViewportHandle
focusable bool
Remarks
Turning it off while focused gives the keyboard up.
IT IS THE ENGINE'S MEANING OF THE WORD. A widget that refuses focus still takes clicks, and a click on it hands focus to whatever underneath accepts it, which in a game is the viewport, so clicking an unfocusable page takes the keyboard from a page that had it.
SetFocused(ViewportHandle, bool)
Gives the browser in viewport keyboard focus, or takes it away.
public void SetFocused(ViewportHandle viewport, bool focused)
Parameters
viewport ViewportHandle
focused bool
Remarks
AN ASK, NOT A RECORD. The engine decides, and moves focus for its own reasons, a click being the usual one. It is exclusive wherever it lands, which is the engine's to enforce.
SetInputMode(CefInputMode)
Says what should happen to input while any page is on screen.
public void SetInputMode(CefInputMode mode)
Parameters
mode CefInputMode
Remarks
GLOBAL, not per browser. A mode the engine cannot honour is refused and said so rather than accepted and quietly behaving like another one.
SetPageFocused(BrowserHandle, bool)
Tells a browser whether it holds the keyboard.
public void SetPageFocused(BrowserHandle browser, bool focused)
Parameters
browser BrowserHandle
focused bool
Remarks
THE BROWSER'S OWN BELIEF, separate from where the engine's focus is. A document that has just loaded starts unfocused however the engine's focus has not moved, and an unfocused browser dispatches no key events into its page at all: the page can focus an element and still receive nothing.
SetPlacement(ViewportHandle, ViewportPlacement)
Where this viewport sits and how big it is. Settable at any time, including while a page is up.
public void SetPlacement(ViewportHandle viewport, ViewportPlacement placement)
Parameters
viewport ViewportHandle
placement ViewportPlacement
Remarks
The size becomes the browser's layout viewport, so window.innerWidth follows it. Never a scale
factor, and the page is never stretched.
NOTHING IS DRAWN for the frames between asking and receiving, so do not animate by resizing.
SetUiInputMode(bool)
Whether the GAME or its UI owns input, and whether the pointer is drawn.
public void SetUiInputMode(bool uiOnly)
Parameters
uiOnly bool
Remarks
NOT A CEF CONCERN, and here only so a page can be reached at all while this is being built. One answer for the whole game, with nothing per viewport or per browser about it, and it belongs to whatever owns the game's input rather than to this. Said plainly rather than left to look like a design.
SetVisible(ViewportHandle, bool)
Shows or hides a viewport. Cheap and repeatable, unlike creating a browser.
public void SetVisible(ViewportHandle viewport, bool visible)
Parameters
viewport ViewportHandle
visible bool
Unregister(string)
Stops serving a host. Pages already loaded from it stay loaded.
public void Unregister(string host)
Parameters
host string
ZOrderOf(ViewportHandle)
The layer this viewport was created on.
public int ZOrderOf(ViewportHandle viewport)
Parameters
viewport ViewportHandle