CefFrame
Header: cef_frame.h
Category: Core APIs
Overview
Foundational interfaces: process bootstrap, browser lifecycle, frames, DOM, requests, and data objects.
CefFrame
Source File: include/cef_frame.h
Process / Thread Context: "Class used to represent a frame in the browser window. When used in the browser process the methods of this class may be called on any thread unless otherwise indicated in the comments. When used in the render process the methods of this class may only be called on the main thread."
Purpose: Per-frame handle. A CefBrowser owns a tree of CefFrames: one main frame and zero or more sub-frames (e.g. iframes). Provides editing commands (cut/copy/paste/etc.), source/text retrieval, navigation (LoadRequest/LoadURL), JavaScript execution, frame metadata queries, render-process-only DOM and V8 context access, URL request creation scoped to the frame, and inter-process messaging.
Methods
virtual bool IsValid() = 0
Return Value: "True if this object is currently attached to a valid frame."
Threading Constraint: Threading constraint not specified in source.
virtual void Undo() = 0
Return Value: "Execute undo in this frame."
Threading Constraint: Threading constraint not specified in source.
virtual void Redo() = 0
Return Value: "Execute redo in this frame."
Threading Constraint: Threading constraint not specified in source.
virtual void Cut() = 0
Return Value: "Execute cut in this frame."
Threading Constraint: Threading constraint not specified in source.
virtual void Copy() = 0
Return Value: "Execute copy in this frame."
Threading Constraint: Threading constraint not specified in source.
virtual void Paste() = 0
Return Value: "Execute paste in this frame."
Threading Constraint: Threading constraint not specified in source.
virtual void PasteAndMatchStyle() = 0
Return Value: "Execute paste and match style in this frame."
Threading Constraint: Threading constraint not specified in source.
virtual void Delete() = 0
Return Value: "Execute delete in this frame." (translator name del.)
Threading Constraint: Threading constraint not specified in source.
virtual void SelectAll() = 0
Return Value: "Execute select all in this frame."
Threading Constraint: Threading constraint not specified in source.
virtual void ViewSource() = 0
Return Value: "Save this frame's HTML source to a temporary file and open it in the default text viewing application. This method can only be called from the browser process."
Threading Constraint: Threading constraint not specified in source.
virtual void GetSource(CefRefPtr<CefStringVisitor> visitor) = 0
Return Value: "Retrieve this frame's HTML source as a string sent to the specified visitor."
Threading Constraint: Threading constraint not specified in source.
virtual void GetText(CefRefPtr<CefStringVisitor> visitor) = 0
Return Value: "Retrieve this frame's display text as a string sent to the specified visitor."
Threading Constraint: Threading constraint not specified in source.
virtual void LoadRequest(CefRefPtr<CefRequest> request) = 0
Return Value: "Load the request represented by the |request| object." WARNING: "This method will fail with 'bad IPC message' reason INVALID_INITIATOR_ORIGIN (213) unless you first navigate to the request origin using some other mechanism (LoadURL, link click, etc)."
Threading Constraint: Threading constraint not specified in source.
virtual void LoadURL(const CefString& url) = 0
Return Value: "Load the specified |url|."
Threading Constraint: Threading constraint not specified in source.
virtual void ExecuteJavaScript(const CefString& code, const CefString& script_url, int start_line) = 0
Return Value: "Execute a string of JavaScript code in this frame. The |script_url| parameter is the URL where the script in question can be found, if any. The renderer may request this URL to show the developer the source of the error. The |start_line| parameter is the base line number to use for error reporting." script_url is an optional parameter.
Threading Constraint: Threading constraint not specified in source.
virtual bool IsMain() = 0
Return Value: "Returns true if this is the main (top-level) frame."
Threading Constraint: Threading constraint not specified in source.
virtual bool IsFocused() = 0
Return Value: "Returns true if this is the focused frame."
Threading Constraint: Threading constraint not specified in source.
virtual CefString GetName() = 0
Return Value: "Returns the name for this frame. If the frame has an assigned name (for example, set via the iframe 'name' attribute) then that value will be returned. Otherwise a unique name will be constructed based on the frame parent hierarchy. The main (top-level) frame will always have an empty name value."
Threading Constraint: Threading constraint not specified in source.
virtual CefString GetIdentifier() = 0
Return Value: "Returns the globally unique identifier for this frame or empty if the underlying frame does not yet exist."
Threading Constraint: Threading constraint not specified in source.
virtual CefRefPtr<CefFrame> GetParent() = 0
Return Value: "Returns the parent of this frame or NULL if this is the main (top-level) frame."
Threading Constraint: Threading constraint not specified in source.
virtual CefString GetURL() = 0
Return Value: "Returns the URL currently loaded in this frame."
Threading Constraint: Threading constraint not specified in source.
virtual CefRefPtr<CefBrowser> GetBrowser() = 0
Return Value: "Returns the browser that this frame belongs to."
Threading Constraint: Threading constraint not specified in source.
virtual CefRefPtr<CefV8Context> GetV8Context() = 0
Return Value: "Get the V8 context associated with the frame. This method can only be called from the render process."
Threading Constraint: Threading constraint not specified in source.
virtual void VisitDOM(CefRefPtr<CefDOMVisitor> visitor) = 0
Return Value: "Visit the DOM document. This method can only be called from the render process."
Threading Constraint: Threading constraint not specified in source.
virtual CefRefPtr<CefURLRequest> CreateURLRequest(CefRefPtr<CefRequest> request, CefRefPtr<CefURLRequestClient> client) = 0
Return Value: "Create a new URL request that will be treated as originating from this frame and the associated browser. Use CefURLRequest::Create instead if you do not want the request to have this association, in which case it may be handled differently." Notes from header: (a) may be intercepted via CefResourceRequestHandler or CefSchemeHandlerFactory; (b) POST data may only contain a single element of type PDE_TYPE_FILE or PDE_TYPE_BYTES. "The |request| object will be marked as read-only after calling this method." Browser-process only.
Threading Constraint: Threading constraint not specified in source.
virtual void SendProcessMessage(CefProcessId target_process, CefRefPtr<CefProcessMessage> message) = 0
Return Value: "Send a message to the specified |target_process|. Ownership of the message contents will be transferred and the |message| reference will be invalidated. Message delivery is not guaranteed in all cases (for example, if the browser is closing, navigating, or if the target process crashes). Send an ACK message back from the target process if confirmation is required."
Threading Constraint: Threading constraint not specified in source.
Usage Example
// Browser-process: navigate and execute JS on the main frame:
CefRefPtr<CefFrame> main = browser->GetMainFrame();
main->LoadURL("https://example.com");
// After the load completes (see CefLoadHandler::OnLoadEnd), run JS:
main->ExecuteJavaScript("window.scrollTo(0, document.body.scrollHeight);",
"my-app://scroll", 1);
// Renderer-process: visit the DOM:
class MyDomVisitor : public CefDOMVisitor {
void Visit(CefRefPtr<CefDOMDocument> doc) override {
CefRefPtr<CefDOMNode> body = doc->GetBody();
// ... read-only snapshot ...
}
IMPLEMENT_REFCOUNTING(MyDomVisitor);
};
frame->VisitDOM(new MyDomVisitor());
// Inter-process messaging (browser → renderer):
CefRefPtr<CefProcessMessage> msg = CefProcessMessage::Create("ping");
msg->GetArgumentList()->SetString(0, "hello from browser");
main->SendProcessMessage(PID_RENDERER, msg);
// Receiver: CefRenderProcessHandler::OnProcessMessageReceived(...)