servo/
lib.rs

1/* This Source Code Form is subject to the terms of the Mozilla Public
2 * License, v. 2.0. If a copy of the MPL was not distributed with this
3 * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
4
5//! Servo, the mighty web browser engine from the future.
6//!
7//! This crate wires all of Servo's components together as type [`Servo`], along with
8//! a Webview implementation, [`WebView`], to create a working web engine.
9//!
10//! To embed Servo in your application, you need to:
11//! 1) Create an instance of a type that implements the [`EventLoopWaker`] trait.
12//!    This trait allows Servo to integrate with your application's event loop. Your
13//!    [`EventLoopWaker::wake`] implementation needs to ensure that
14//!    [`Servo::spin_event_loop`] is eventually called to let Servo process user input,
15//!    network events etc.
16//! 2) Create a [`Servo`] instance using the [`ServoBuilder`] type. You can optionally
17//!    register a [`ServoDelegate`] implementation to subscribe to notifications about
18//!    events and customize certain behaviours.
19//! 3) Create an instance of a type that implements the [`RenderingContext`] trait.
20//!    Note: You can either use one of the existing types in this crate (such as
21//!    [`WindowRenderingContext`], [`OffscreenRenderingContext`] or [`SoftwareRenderingContext`])
22//!    or provide a custom implementation.
23//! 4) For each [`WebView`] in your application, create a [`WebViewBuilder`] by passing
24//!    it the [`RenderingContext`] and [`Servo`] instance, and then configure the
25//!    builder and use it to create a [`WebView`] instance. The builder must be provided
26//!    with a [`WebViewDelegate`] implementation which, at a minimum, should handle
27//!    [`WebViewDelegate::notify_new_frame_ready`] by calling [`WebView::paint`]
28//!    and presenting the rendered page using [`RenderingContext::present`]. Refer to the
29//!    documentation of the [`WebView`] type to learn more about the relation
30//!    between a [`WebView`] and its [`RenderingContext`].
31//! 5) Run the application's event loop. Your application's event handlers need to
32//!    forward input events for a particular [`WebView`] using one of the `notify_*` methods
33//!    on that [`WebView`] instance. For example, to forward a mouse event to a [`WebView`],
34//!    call the [`WebView::notify_input_event`]. You can also invoke methods on a [`WebView`]
35//!    to request certain actions. For instance, the [`WebView::load`] method requests that
36//!    Servo navigate to a new page. In both cases, the calls to the [`WebView`] methods
37//!    must be followed by calls to [`Servo::spin_event_loop`] to allow Servo to process
38//!    those requests.
39//!
40//! For a minimal working example, refer to the [`winit_minimal`] code.
41//!
42//! [`winit_minimal`]: https://github.com/servo/servo/blob/main/components/servo/examples/winit_minimal.rs
43
44mod clipboard_delegate;
45#[cfg(feature = "gamepad")]
46mod gamepad_delegate;
47mod geolocation_delegate;
48#[cfg(all(
49    feature = "media-gstreamer",
50    not(any(target_os = "android", target_env = "ohos"))
51))]
52mod gstreamer_plugins;
53mod javascript_evaluator;
54mod network_manager;
55mod proxies;
56mod responders;
57mod servo;
58mod servo_delegate;
59mod site_data_manager;
60mod user_content_manager;
61mod webview;
62mod webview_delegate;
63
64// These are Servo's public exports. Everything (apart from a couple exceptions below)
65// should be exported at the root. See <https://github.com/servo/servo/issues/18475>.
66pub use accesskit;
67pub use embedder_traits::user_contents::UserScript;
68pub use embedder_traits::{submit_resource_reader, *};
69pub use image::RgbaImage;
70pub use keyboard_types::{
71    Code, CompositionEvent, CompositionState, Key, KeyState, Location, Modifiers, NamedKey,
72};
73pub use media::{
74    GlApi as MediaGlApi, GlContext as MediaGlContext, NativeDisplay as MediaNativeDisplay,
75};
76pub use net::image_cache::should_panic_hook_suppress_termination;
77pub use net_traits::CookieSource;
78// This API should probably not be exposed in this way. Instead there should be a fully
79// fleshed out public domains API if we want to expose it.
80pub use net_traits::pub_domains::is_reg_domain;
81pub use paint::WebRenderDebugOption;
82pub use paint_api::rendering_context::{
83    OffscreenRenderingContext, RenderingContext, SoftwareRenderingContext, WindowRenderingContext,
84};
85// Expose our profile traits for servoshell, so we can instrument code there, but don't
86// add it as an official API.
87#[doc(hidden)]
88pub use profile_traits;
89// This should be replaced with an API on ServoBuilder.
90// See <https://github.com/servo/servo/issues/40950>.
91pub use resources;
92pub use servo_base::generic_channel::GenericSender;
93pub use servo_base::id::WebViewId;
94pub use servo_config::opts::{DiagnosticsLogging, DiagnosticsLoggingOption, Opts, OutputOptions};
95pub use servo_config::prefs::{PrefValue, Preferences, UserAgentPlatform};
96pub use servo_config::{opts, pref, prefs};
97pub use servo_geometry::{
98    DeviceIndependentIntRect, DeviceIndependentPixel, convert_rect_to_css_pixel,
99};
100#[doc(hidden)]
101pub use servo_tracing;
102pub use servo_url::ServoUrl;
103pub use style::Zero;
104pub use style_traits::CSSPixel;
105pub use webrender_api::units::{
106    DeviceIntPoint, DeviceIntRect, DeviceIntSize, DevicePixel, DevicePoint, DeviceVector2D,
107};
108
109pub use crate::clipboard_delegate::{ClipboardDelegate, StringRequest};
110#[cfg(feature = "gamepad")]
111pub use crate::gamepad_delegate::{
112    GamepadDelegate, GamepadHapticEffectRequest, GamepadHapticEffectRequestType,
113};
114pub use crate::geolocation_delegate::{GeolocationDelegate, PositionRequest, PositionWatch};
115pub use crate::network_manager::{CacheEntry, NetworkManager};
116#[cfg(feature = "multiprocess")]
117pub use crate::servo::run_content_process;
118pub use crate::servo::{Servo, ServoBuilder};
119pub use crate::servo_delegate::{ServoDelegate, ServoError};
120pub use crate::site_data_manager::{SiteData, SiteDataManager, StorageType};
121pub use crate::user_content_manager::UserContentManager;
122pub use crate::webview::{WebView, WebViewBuilder};
123pub use crate::webview_delegate::{
124    AlertDialog, AllowOrDenyRequest, AuthenticationRequest, BluetoothDeviceSelectionRequest,
125    ColorPicker, ConfirmDialog, ContextMenu, CreateNewWebViewRequest, EmbedderControl, FilePicker,
126    InputMethodControl, NavigationRequest, PermissionRequest, PromptDialog, SelectElement,
127    SimpleDialog, WebResourceLoad, WebViewDelegate,
128};
129
130#[cfg(feature = "webxr")]
131pub mod webxr {
132    #[cfg(not(any(target_os = "android", target_env = "ohos")))]
133    pub use webxr::glwindow::{GlWindow, GlWindowDiscovery, GlWindowMode, GlWindowRenderTarget};
134    #[cfg(not(any(target_os = "android", target_env = "ohos")))]
135    pub use webxr::headless::HeadlessMockDiscovery;
136    #[cfg(target_os = "windows")]
137    pub use webxr::openxr::{AppInfo as OpenXrAppInfo, OpenXrDiscovery};
138    pub use webxr::{Discovery, MainThreadRegistry, WebXrRegistry};
139}
140
141// TODO: The protocol handler interface needs to be cleaned and simplified.
142pub mod protocol_handler {
143    pub use net::fetch::methods::{DoneChannel, FetchContext};
144    pub use net::filemanager_thread::FILE_CHUNK_SIZE;
145    pub use net::protocols::{ProtocolHandler, ProtocolRegistry};
146    pub use net_traits::filemanager_thread::RelativePos;
147    pub use net_traits::http_status::HttpStatus;
148    pub use net_traits::request::Request;
149    pub use net_traits::response::{Response, ResponseBody};
150    pub use net_traits::{NetworkError, ResourceFetchTiming};
151
152    pub use crate::webview_delegate::ProtocolHandlerRegistration;
153}
154
155// We need to reference this crate, in order for the linker not to remove it.
156#[cfg(all(feature = "baked-in-resources", not(target_env = "ohos")))]
157use servo_default_resources as _;
servo/lib.rs

servo/
lib.rs
