mirror of
https://bitbucket.org/chromiumembedded/cef
synced 2025-06-05 21:39:12 +02:00
Update include/ comments to Doxygen formatting (see issue #3384)
See related guidelines in the issue.
This commit is contained in:
Marshall Greenblatt
@ -43,98 +43,100 @@
|
||||
#include "include/cef_frame.h"
|
||||
|
||||
///
|
||||
// Implement this interface to handle events related to CefFrame life span. The
|
||||
// order of callbacks is:
|
||||
//
|
||||
// (1) During initial CefBrowserHost creation and navigation of the main frame:
|
||||
// - CefFrameHandler::OnFrameCreated => The initial main frame object has been
|
||||
// created. Any commands will be queued until the frame is attached.
|
||||
// - CefFrameHandler::OnMainFrameChanged => The initial main frame object has
|
||||
// been assigned to the browser.
|
||||
// - CefLifeSpanHandler::OnAfterCreated => The browser is now valid and can be
|
||||
// used.
|
||||
// - CefFrameHandler::OnFrameAttached => The initial main frame object is now
|
||||
// connected to its peer in the renderer process. Commands can be routed.
|
||||
//
|
||||
// (2) During further CefBrowserHost navigation/loading of the main frame and/or
|
||||
// sub-frames:
|
||||
// - CefFrameHandler::OnFrameCreated => A new main frame or sub-frame object has
|
||||
// been created. Any commands will be queued until the frame is attached.
|
||||
// - CefFrameHandler::OnFrameAttached => A new main frame or sub-frame object is
|
||||
// now connected to its peer in the renderer process. Commands can be routed.
|
||||
// - CefFrameHandler::OnFrameDetached => An existing main frame or sub-frame
|
||||
// object has lost its connection to the renderer process. If multiple objects
|
||||
// are detached at the same time then notifications will be sent for any
|
||||
// sub-frame objects before the main frame object. Commands can no longer be
|
||||
// routed and will be discarded.
|
||||
// - CefFrameHandler::OnMainFrameChanged => A new main frame object has been
|
||||
// assigned to the browser. This will only occur with cross-origin navigation
|
||||
// or re-navigation after renderer process termination (due to crashes, etc).
|
||||
//
|
||||
// (3) During final CefBrowserHost destruction of the main frame:
|
||||
// - CefFrameHandler::OnFrameDetached => Any sub-frame objects have lost their
|
||||
// connection to the renderer process. Commands can no longer be routed and
|
||||
// will be discarded.
|
||||
// - CefLifeSpanHandler::OnBeforeClose => The browser has been destroyed.
|
||||
// - CefFrameHandler::OnFrameDetached => The main frame object have lost its
|
||||
// connection to the renderer process. Notifications will be sent for any
|
||||
// sub-frame objects before the main frame object. Commands can no longer be
|
||||
// routed and will be discarded.
|
||||
// - CefFrameHandler::OnMainFrameChanged => The final main frame object has been
|
||||
// removed from the browser.
|
||||
//
|
||||
// Cross-origin navigation and/or loading receives special handling.
|
||||
//
|
||||
// When the main frame navigates to a different origin the OnMainFrameChanged
|
||||
// callback (2) will be executed with the old and new main frame objects.
|
||||
//
|
||||
// When a new sub-frame is loaded in, or an existing sub-frame is navigated to,
|
||||
// a different origin from the parent frame, a temporary sub-frame object will
|
||||
// first be created in the parent's renderer process. That temporary sub-frame
|
||||
// will then be discarded after the real cross-origin sub-frame is created in
|
||||
// the new/target renderer process. The client will receive cross-origin
|
||||
// navigation callbacks (2) for the transition from the temporary sub-frame to
|
||||
// the real sub-frame. The temporary sub-frame will not recieve or execute
|
||||
// commands during this transitional period (any sent commands will be
|
||||
// discarded).
|
||||
//
|
||||
// When a new popup browser is created in a different origin from the parent
|
||||
// browser, a temporary main frame object for the popup will first be created in
|
||||
// the parent's renderer process. That temporary main frame will then be
|
||||
// discarded after the real cross-origin main frame is created in the new/target
|
||||
// renderer process. The client will recieve creation and initial navigation
|
||||
// callbacks (1) for the temporary main frame, followed by cross-origin
|
||||
// navigation callbacks (2) for the transition from the temporary main frame to
|
||||
// the real main frame. The temporary main frame may receive and execute
|
||||
// commands during this transitional period (any sent commands may be executed,
|
||||
// but the behavior is potentially undesirable since they execute in the parent
|
||||
// browser's renderer process and not the new/target renderer process).
|
||||
//
|
||||
// Callbacks will not be executed for placeholders that may be created during
|
||||
// pre-commit navigation for sub-frames that do not yet exist in the renderer
|
||||
// process. Placeholders will have CefFrame::GetIdentifier() == -4.
|
||||
//
|
||||
// The methods of this class will be called on the UI thread unless otherwise
|
||||
// indicated.
|
||||
/// Implement this interface to handle events related to CefFrame life span. The
|
||||
/// order of callbacks is:
|
||||
///
|
||||
/// (1) During initial CefBrowserHost creation and navigation of the main frame:
|
||||
/// - CefFrameHandler::OnFrameCreated => The initial main frame object has been
|
||||
/// created. Any commands will be queued until the frame is attached.
|
||||
/// - CefFrameHandler::OnMainFrameChanged => The initial main frame object has
|
||||
/// been assigned to the browser.
|
||||
/// - CefLifeSpanHandler::OnAfterCreated => The browser is now valid and can be
|
||||
/// used.
|
||||
/// - CefFrameHandler::OnFrameAttached => The initial main frame object is now
|
||||
/// connected to its peer in the renderer process. Commands can be routed.
|
||||
///
|
||||
/// (2) During further CefBrowserHost navigation/loading of the main frame
|
||||
/// and/or sub-frames:
|
||||
/// - CefFrameHandler::OnFrameCreated => A new main frame or sub-frame object
|
||||
/// has been created. Any commands will be queued until the frame is attached.
|
||||
/// - CefFrameHandler::OnFrameAttached => A new main frame or sub-frame object
|
||||
/// is now connected to its peer in the renderer process. Commands can be
|
||||
/// routed.
|
||||
/// - CefFrameHandler::OnFrameDetached => An existing main frame or sub-frame
|
||||
/// object has lost its connection to the renderer process. If multiple
|
||||
/// objects are detached at the same time then notifications will be sent for
|
||||
/// any sub-frame objects before the main frame object. Commands can no longer
|
||||
/// be routed and will be discarded.
|
||||
/// - CefFrameHandler::OnMainFrameChanged => A new main frame object has been
|
||||
/// assigned to the browser. This will only occur with cross-origin navigation
|
||||
/// or re-navigation after renderer process termination (due to crashes, etc).
|
||||
///
|
||||
/// (3) During final CefBrowserHost destruction of the main frame:
|
||||
/// - CefFrameHandler::OnFrameDetached => Any sub-frame objects have lost their
|
||||
/// connection to the renderer process. Commands can no longer be routed and
|
||||
/// will be discarded.
|
||||
/// - CefLifeSpanHandler::OnBeforeClose => The browser has been destroyed.
|
||||
/// - CefFrameHandler::OnFrameDetached => The main frame object have lost its
|
||||
/// connection to the renderer process. Notifications will be sent for any
|
||||
/// sub-frame objects before the main frame object. Commands can no longer be
|
||||
/// routed and will be discarded.
|
||||
/// - CefFrameHandler::OnMainFrameChanged => The final main frame object has
|
||||
/// been removed from the browser.
|
||||
///
|
||||
/// Cross-origin navigation and/or loading receives special handling.
|
||||
///
|
||||
/// When the main frame navigates to a different origin the OnMainFrameChanged
|
||||
/// callback (2) will be executed with the old and new main frame objects.
|
||||
///
|
||||
/// When a new sub-frame is loaded in, or an existing sub-frame is navigated to,
|
||||
/// a different origin from the parent frame, a temporary sub-frame object will
|
||||
/// first be created in the parent's renderer process. That temporary sub-frame
|
||||
/// will then be discarded after the real cross-origin sub-frame is created in
|
||||
/// the new/target renderer process. The client will receive cross-origin
|
||||
/// navigation callbacks (2) for the transition from the temporary sub-frame to
|
||||
/// the real sub-frame. The temporary sub-frame will not recieve or execute
|
||||
/// commands during this transitional period (any sent commands will be
|
||||
/// discarded).
|
||||
///
|
||||
/// When a new popup browser is created in a different origin from the parent
|
||||
/// browser, a temporary main frame object for the popup will first be created
|
||||
/// in the parent's renderer process. That temporary main frame will then be
|
||||
/// discarded after the real cross-origin main frame is created in the
|
||||
/// new/target renderer process. The client will recieve creation and initial
|
||||
/// navigation callbacks (1) for the temporary main frame, followed by
|
||||
/// cross-origin navigation callbacks (2) for the transition from the temporary
|
||||
/// main frame to the real main frame. The temporary main frame may receive and
|
||||
/// execute commands during this transitional period (any sent commands may be
|
||||
/// executed, but the behavior is potentially undesirable since they execute in
|
||||
/// the parent browser's renderer process and not the new/target renderer
|
||||
/// process).
|
||||
///
|
||||
/// Callbacks will not be executed for placeholders that may be created during
|
||||
/// pre-commit navigation for sub-frames that do not yet exist in the renderer
|
||||
/// process. Placeholders will have CefFrame::GetIdentifier() == -4.
|
||||
///
|
||||
/// The methods of this class will be called on the UI thread unless otherwise
|
||||
/// indicated.
|
||||
///
|
||||
/*--cef(source=client)--*/
|
||||
class CefFrameHandler : public virtual CefBaseRefCounted {
|
||||
public:
|
||||
///
|
||||
// Called when a new frame is created. This will be the first notification
|
||||
// that references |frame|. Any commands that require transport to the
|
||||
// associated renderer process (LoadRequest, SendProcessMessage, GetSource,
|
||||
// etc.) will be queued until OnFrameAttached is called for |frame|.
|
||||
/// Called when a new frame is created. This will be the first notification
|
||||
/// that references |frame|. Any commands that require transport to the
|
||||
/// associated renderer process (LoadRequest, SendProcessMessage, GetSource,
|
||||
/// etc.) will be queued until OnFrameAttached is called for |frame|.
|
||||
///
|
||||
/*--cef()--*/
|
||||
virtual void OnFrameCreated(CefRefPtr<CefBrowser> browser,
|
||||
CefRefPtr<CefFrame> frame) {}
|
||||
|
||||
///
|
||||
// Called when a frame can begin routing commands to/from the associated
|
||||
// renderer process. |reattached| will be true if the frame was re-attached
|
||||
// after exiting the BackForwardCache. Any commands that were queued have now
|
||||
// been dispatched.
|
||||
/// Called when a frame can begin routing commands to/from the associated
|
||||
/// renderer process. |reattached| will be true if the frame was re-attached
|
||||
/// after exiting the BackForwardCache. Any commands that were queued have now
|
||||
/// been dispatched.
|
||||
///
|
||||
/*--cef()--*/
|
||||
virtual void OnFrameAttached(CefRefPtr<CefBrowser> browser,
|
||||
@ -142,29 +144,29 @@ class CefFrameHandler : public virtual CefBaseRefCounted {
|
||||
bool reattached) {}
|
||||
|
||||
///
|
||||
// Called when a frame loses its connection to the renderer process and will
|
||||
// be destroyed. Any pending or future commands will be discarded and
|
||||
// CefFrame::IsValid() will now return false for |frame|. If called after
|
||||
// CefLifeSpanHandler::OnBeforeClose() during browser destruction then
|
||||
// CefBrowser::IsValid() will return false for |browser|.
|
||||
/// Called when a frame loses its connection to the renderer process and will
|
||||
/// be destroyed. Any pending or future commands will be discarded and
|
||||
/// CefFrame::IsValid() will now return false for |frame|. If called after
|
||||
/// CefLifeSpanHandler::OnBeforeClose() during browser destruction then
|
||||
/// CefBrowser::IsValid() will return false for |browser|.
|
||||
///
|
||||
/*--cef()--*/
|
||||
virtual void OnFrameDetached(CefRefPtr<CefBrowser> browser,
|
||||
CefRefPtr<CefFrame> frame) {}
|
||||
|
||||
///
|
||||
// Called when the main frame changes due to (a) initial browser creation, (b)
|
||||
// final browser destruction, (c) cross-origin navigation or (d) re-navigation
|
||||
// after renderer process termination (due to crashes, etc). |old_frame| will
|
||||
// be NULL and |new_frame| will be non-NULL when a main frame is assigned to
|
||||
// |browser| for the first time. |old_frame| will be non-NULL and |new_frame|
|
||||
// will be NULL and when a main frame is removed from |browser| for the last
|
||||
// time. Both |old_frame| and |new_frame| will be non-NULL for cross-origin
|
||||
// navigations or re-navigation after renderer process termination. This
|
||||
// method will be called after OnFrameCreated() for |new_frame| and/or after
|
||||
// OnFrameDetached() for |old_frame|. If called after
|
||||
// CefLifeSpanHandler::OnBeforeClose() during browser destruction then
|
||||
// CefBrowser::IsValid() will return false for |browser|.
|
||||
/// Called when the main frame changes due to (a) initial browser creation,
|
||||
/// (b) final browser destruction, (c) cross-origin navigation or (d)
|
||||
/// re-navigation after renderer process termination (due to crashes, etc).
|
||||
/// |old_frame| will be NULL and |new_frame| will be non-NULL when a main
|
||||
/// frame is assigned to |browser| for the first time. |old_frame| will be
|
||||
/// non-NULL and |new_frame| will be NULL and when a main frame is removed
|
||||
/// from |browser| for the last time. Both |old_frame| and |new_frame| will be
|
||||
/// non-NULL for cross-origin navigations or re-navigation after renderer
|
||||
/// process termination. This method will be called after OnFrameCreated() for
|
||||
/// |new_frame| and/or after OnFrameDetached() for |old_frame|. If called
|
||||
/// after CefLifeSpanHandler::OnBeforeClose() during browser destruction then
|
||||
/// CefBrowser::IsValid() will return false for |browser|.
|
||||
///
|
||||
/*--cef(optional_param=old_frame,optional_param=new_frame)--*/
|
||||
virtual void OnMainFrameChanged(CefRefPtr<CefBrowser> browser,
|
||||
|
||||
Reference in New Issue
Block a user