Class CSS

  • public class CSS
extends java.lang.Object

    This class was built using the Chrome Remote Dev-Tools A.P.I., which is specified by two JSON-RPC Files. These files were obtained from the Chrome Dev Tools Protocol Git Hub Page, which has a "Tip of Tree" (the latest) API-Specification Page Here: JSON-RPC Protocol Specification.

    These files were converted into this Java-Browser (CDP) Library. The intention is to have them function in a similar fasion to the Node.js Tool known as 'Puppeteer', Microsoft's 'Playwright' and of course the Main-Stay 'Selenium.' The Java-HTML JAR Library merely implements the Java Types & Commands defined by Google's DevTools Protocol.

    🧠 View the Google CDP API:

    This domain exposes CSS read/write operations. All CSS objects (stylesheets, rules, and styles) have an associated id used in subsequent operations on the related object. Each object type has a specific id structure, and those are not interchangeable between objects of different kinds. CSS objects can be loaded using the get*ForNode() calls (which accept a DOM node id). A client can also keep track of stylesheets via the styleSheetAdded/styleSheetRemoved events and subsequently load the required stylesheet contents using the getStyleSheet[Text]() methods.

    The top-level description and explanation for this class (this comment, at the top this Java-Doc Page) is repeated, verbatim, across all of the domain classes which comprise Google's CDP API.

    This class is intended to be used with a Browser Instance

    These methods have been tested, to some degree, using Google Chrome. In order to use this class you must start a web-browser instance and make a connection to the browser using a Remote Debugging Port. Google-Corporation is the developer of this API, but any browser which accepts a Remote Debug Port Connection over Web-Sockets.

    Google-Chrome was used during the development process of the classes in this particular package. Lately, it has been asserted Microsoft has switched to using the Chrome Browser-Engine for its Microsoft Edge Internal Code-Base. Therefore, there may some functionality available when running the methods in this class with Microsoft-Edge.

    Check whether the your Web-Browser will allow itself to be driven by the Web-Socket RDP-Port 9223. See the examples available in package Torello.Browser to undertand how to build a PageConn and BrowserConn Web-Socket Connection, and how to build a WebSocketSender instance in order to execute the methods in this class.

    Web-Socket & JSON API:   
    Every one of the methods that reside in this class are designed to do nothing more than:

    1. Accept Parameters from the User, and "Marshall Them" into a Valid JSON-Request
    2. Transmit the Marshalled Request-JSON to a Headless Web-Browser over a Web-Socket Connection
    3. Receive BOTH that Command-Results AND any Browser Event-Firings from the Web-Socket
    4. Parse JSON Method-Results and Browser-Event Firings, and Subsequently Convert them to Standard Java-Types
    5. Report these Method-Results and Browser-Events to the User via a User-Registered, Event-Listener (Events) or a Promise Object (Command Responses / Results)

    Unlike the bulk of the Java HTML JAR Library, there is very little native Java-Code, and very little testing that may be done on any of the classes & methods in this package. The code inside these classes does nothing more than marshall-and-unmarshall Java-Types into Json-Requests (and vice-versa). The Java-Script & Browser modules inside of a Google-Chrome instance are, theoretically, handling these requests, and returning their results (or events) over the Web-Socket Connection.

    It has been asserted (by Google Chrome Developers) that some of these methods are only "partially working" or "experimental".


    Asking Chat-GPT for Help:   
    The LLM otherwise known as "Chat-GPT" does, indeed, have an expert level of knowledge about the "Remote DevTools Protocol". The API that the Chrome DevTools Protocl (CDP) exports is extremely well understood by the LLM, and generally I have found that Chat-GPT understands (by 2 or 3 orders of magnitude) better what my Auto-Generated JSON-Wrappers can do in controlling a Web-Browser than I could ever possibly hope to understand.

    Though not available today, there will soon be an automatically downloadable Token-Stream (AI Embeddings) BUTTON available on my Java-Doc Pages that should hopefully make it extremely easy to post my code-base, RAG Style, to Chat-GPT and other LLM's when 'interogating' them. Presently, because my "Get Token Stream Button" does not exist yet on any of my pages, what you can do is copy-and-paste any Method-Signature from any one of these pages and then ask Chat-GPT to explain what that Browser or Java-Script Function is actually doing. It is very likely to give you some pretty neat answers.

    I have found that every single one of the Domains, Types & Events which are offered by the CDP Protocol (though not documented very well by Google), are perfectly understood by the A.I. LLM - literally to the point where it does know (much better than I ever could) what my own code base actually does!

    Try it out, it's a lot of fun. Note that this package and these classes were originally developed solely to be able to execute the Java-Script that a browser executes when visiting a Web-Site. Complete HTML-Page Content can be scraped (using the HTML Data-Scraping Tools in Java-HTML) off of Web-Sites that have dynamic / Java-Script Generated Content.


    Conspicuous Boxed-Types Usage:
    You may notice that there are many methods that have parameters which accept, for instance, an Integer, instead of a primitive int. Just to remind the readiner, in Java Programs a Boxed Type is a standard Java-Primitive which has been converted into an Object-Reference. The use of Boxed-Types in this code base is an easy-and-fast-way to allow for the concept of "Optional Parameters" or "Optional Field Value."

    Whenever you see a method that accepts an Integer, the reason for this Parameter-Type choice is actually to allow a user to pass 'null' to it. This is a simple way to ELIDE passing any value at all to parameters which Google-Chrome would otherwise assert are "Optional." Whenever you pass 'null' to a Boxed-Types in this class, the Json-Processor will simply eliminate that Object-Property from the command altogether; and the browser will simply not receive any value for that parameter when that command is invoked.

    The Java Language Specification does not have an easy or well defined means of accepting optional method parameters; so Boxed-Types and 'null' are utilized here. Note that 'null' may be passed to any Command Method-Parameter that is listed as Optional on the Java-Doc Page description for that parameter.



    Stateless Class:
    This class neither contains any program-state, nor can it be instantiated. The @StaticFunctional Annotation may also be called 'The Spaghetti Report'. Static-Functional classes are, essentially, C-Styled Files, without any constructors or non-static member fields. It is a concept very similar to the Java-Bean's @Stateless Annotation.

    • 1 Constructor(s), 1 declared private, zero-argument constructor
    • 38 Method(s), 38 declared static
    • 4 Field(s), 4 declared static, 4 declared final


    • Field Detail

      • StyleSheetId

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final java.lang.String StyleSheetId
        [No Description Provided by Google]

        The Type StyleSheetId has been eliminated, because it is a direct mapping to a basic Java-Type; it has no additional fields, or other distinguishing properties. Instead, this CDP defined type has been relegated to a simple String Constant, for documentation & reference purposes only.

        The code which is generated which employs this type replaces its use with the Standard Java-Type: String

        Eliminated Type
        See Also:
        Constant Field Values

      • mediaQueryResultChanged

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final java.lang.String mediaQueryResultChanged
        Fires whenever a MediaQuery result changes (for example, after a browser window has been resized.) The current implementation considers only viewport-dependent media features.

        This is Marker-Event. Marker-Event's are events that do not possess any data or fields at all. When such events are fired by the browser, the Web-Socket sends nothing more than the name of the event in the packet. The Java-HTML CDP Implementation (this library) has not actually created a dedicated Java Event-Type for this Browser Event.

        This specific static field is actually just declared a String.
        mediaQueryResultChanged has not been 'reified' into an actual nested / inner class of its own, at all.

        Eliminated Event Type
        See Also:
        Constant Field Values

      • CSSRuleType

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final ReadOnlyList<java.lang.String> CSSRuleType
        Enum indicating the type of a CSS rule, used to represent the order of a style rule's ancestors. This list only contains rule types that are collected during the ancestor rule collection.
        EXPERIMENTAL

        String-Enumeration Type

      • StyleSheetOrigin

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final ReadOnlyList<java.lang.String> StyleSheetOrigin
        Stylesheet type: "injected" for stylesheets injected via extension, "user-agent" for user-agent stylesheets, "inspector" for stylesheets created by the inspector (i.e. those holding the "via inspector" rules), "regular" for regular stylesheets.

        String-Enumeration Type

    • Method Detail

      • addRule

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<CSS.CSSRule> addRule​
            (java.lang.String styleSheetId,
             java.lang.String ruleText,
             CSS.SourceRange location,
             java.lang.Integer nodeForPropertySyntaxValidation)
        Inserts a new rule with the given ruleText in a stylesheet with given styleSheetId, at the position specified by location.
        Parameters:
        styleSheetId - The css style sheet identifier where a new rule should be inserted.
        ruleText - The text of a new rule.
        location - Text position of a new rule in the target style sheet.
        nodeForPropertySyntaxValidation - NodeId for the DOM node in whose context custom property declarations for registered properties should be validated. If omitted, declarations in the new rule text can only be validated statically, which may produce incorrect results if the declaration contains a var() for example.
        OPTIONALEXPERIMENTAL
        Returns:
        An instance of Script<CSS.CSSRule>

        This script may be executed, using Script.exec, and afterwards, a Promise <CSS.CSSRule> will be returned

        Finally, the Promise may be awaited, using Promise.await(), and the returned result of this Browser Function may be retrieved.

        This Browser Function's Promise returns: CSS.CSSRule (rule)
        The newly created rule.

      • collectClassNames

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.String[]> collectClassNames​
            (java.lang.String styleSheetId)
        Returns all class names from specified stylesheet.
        Parameters:
        styleSheetId - -
        Returns:
        An instance of Script<String[]>

        This script may be executed, using Script.exec, and afterwards, a Promise <String[]> will be returned

        Finally, the Promise may be awaited, using Promise.await(), and the returned result of this Browser Function may be retrieved.

        This Browser Function's Promise returns: String[] (classNames)
        Class name list.

      • createStyleSheet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.String> createStyleSheet​
            (java.lang.String frameId,
             java.lang.Boolean force)
        Creates a new special "via-inspector" stylesheet in the frame with given frameId.
        Parameters:
        frameId - Identifier of the frame where "via-inspector" stylesheet should be created.
        force - If true, creates a new stylesheet for every call. If false, returns a stylesheet previously created by a call with force=false for the frame's document if it exists or creates a new stylesheet (default: false).
        OPTIONAL
        Returns:
        An instance of Script<String>

        This script may be executed, using Script.exec, and afterwards, a Promise <String> will be returned

        Finally, the Promise may be awaited, using Promise.await(), and the returned result of this Browser Function may be retrieved.

        This Browser Function's Promise returns: String (styleSheetId)
        Identifier of the created "via-inspector" stylesheet.

      • disable

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.Void> disable()
        Disables the CSS agent for the given page.
        Returns:
        An instance of Script<Void>

        This Script instance must be executed before the browser receives the invocation-request.

        This Browser-Function does not have a return-value. You may choose to await the Promise<Void> to ensure that the Browser Function has run to completion.

      • enable

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.Void> enable()
        Enables the CSS agent for the given page. Clients should not assume that the CSS agent has been enabled until the result of this command is received.
        Returns:
        An instance of Script<Void>

        This Script instance must be executed before the browser receives the invocation-request.

        This Browser-Function does not have a return-value. You may choose to await the Promise<Void> to ensure that the Browser Function has run to completion.

      • forcePseudoState

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.Void> forcePseudoState​
            (int nodeId,
             java.lang.String[] forcedPseudoClasses)
        Ensures that the given node will have specified pseudo-classes whenever its style is computed by the browser.
        Parameters:
        nodeId - The element id for which to force the pseudo state.
        forcedPseudoClasses - Element pseudo classes to force when computing the element's style.
        Returns:
        An instance of Script<Void>

        This Script instance must be executed before the browser receives the invocation-request.

        This Browser-Function does not have a return-value. You may choose to await the Promise<Void> to ensure that the Browser Function has run to completion.

      • forceStartingStyle

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.Void> forceStartingStyle​(int nodeId,
                                                        boolean forced)
        Ensures that the given node is in its starting-style state.
        Parameters:
        nodeId - The element id for which to force the starting-style state.
        forced - Boolean indicating if this is on or off.
        Returns:
        An instance of Script<Void>

        This Script instance must be executed before the browser receives the invocation-request.

        This Browser-Function does not have a return-value. You may choose to await the Promise<Void> to ensure that the Browser Function has run to completion.

      • getEnvironmentVariables

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<JsonValue> getEnvironmentVariables()
        Returns the values of the default UA-defined environment variables used in env()
        EXPERIMENTAL
        Returns:
        An instance of Script<JsonValue>

        This script may be executed, using Script.exec, and afterwards, a Promise <JsonValue> will be returned

        Finally, the Promise may be awaited, using Promise.await(), and the returned result of this Browser Function may be retrieved.

        This Browser Function's Promise returns: JsonValue (environmentVariables)

      • getLayersForNode

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<CSS.CSSLayerData> getLayersForNode​(int nodeId)
        Returns all layers parsed by the rendering engine for the tree scope of a node. Given a DOM element identified by nodeId, getLayersForNode returns the root layer for the nearest ancestor document or shadow root. The layer root contains the full layer tree for the tree scope and their ordering.
        EXPERIMENTAL
        Parameters:
        nodeId - -
        Returns:
        An instance of Script<CSS.CSSLayerData>

        This script may be executed, using Script.exec, and afterwards, a Promise <CSS.CSSLayerData> will be returned

        Finally, the Promise may be awaited, using Promise.await(), and the returned result of this Browser Function may be retrieved.

        This Browser Function's Promise returns: CSS.CSSLayerData (rootLayer)

      • getStyleSheetText

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.String> getStyleSheetText​
            (java.lang.String styleSheetId)
        Returns the current textual content for a stylesheet.
        Parameters:
        styleSheetId - -
        Returns:
        An instance of Script<String>

        This script may be executed, using Script.exec, and afterwards, a Promise <String> will be returned

        Finally, the Promise may be awaited, using Promise.await(), and the returned result of this Browser Function may be retrieved.

        This Browser Function's Promise returns: String (text)
        The stylesheet text.

      • resolveValues

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.String[]> resolveValues​
            (java.lang.String[] values,
             int nodeId,
             java.lang.String propertyName,
             java.lang.String pseudoType,
             java.lang.String pseudoIdentifier)
        Resolve the specified values in the context of the provided element. For example, a value of '1em' is evaluated according to the computed 'font-size' of the element and a value 'calc(1px + 2px)' will be resolved to '3px'. If the propertyName was specified the values are resolved as if they were property's declaration. If a value cannot be parsed according to the provided property syntax, the value is parsed using combined syntax as if null propertyName was provided. If the value cannot be resolved even then, return the provided value without any changes.
        EXPERIMENTAL

        👍 Because of the sheer number of input parameters to this method, there is a a CommandBuilder variant to this method which may be invoked instead.

        Please View: resolveValues()
        Parameters:
        values - Substitution functions (var()/env()/attr()) and cascade-dependent keywords (revert/revert-layer) do not work.
        nodeId - Id of the node in whose context the expression is evaluated
        propertyName - Only longhands and custom property names are accepted.
        OPTIONAL
        pseudoType - Pseudo element type, only works for pseudo elements that generate elements in the tree, such as ::before and ::after.
        OPTIONAL
        pseudoIdentifier - Pseudo element custom ident.
        OPTIONAL
        Returns:
        An instance of Script<String[]>

        This script may be executed, using Script.exec, and afterwards, a Promise <String[]> will be returned

        Finally, the Promise may be awaited, using Promise.await(), and the returned result of this Browser Function may be retrieved.

        This Browser Function's Promise returns: String[] (results)

      • setEffectivePropertyValueForNode

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.Void> setEffectivePropertyValueForNode​
            (int nodeId,
             java.lang.String propertyName,
             java.lang.String value)
        Find a rule with the given active property for the given node and set the new value for this property
        Parameters:
        nodeId - The element id for which to set property.
        propertyName - -
        value - -
        Returns:
        An instance of Script<Void>

        This Script instance must be executed before the browser receives the invocation-request.

        This Browser-Function does not have a return-value. You may choose to await the Promise<Void> to ensure that the Browser Function has run to completion.

      • setLocalFontsEnabled

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.Void> setLocalFontsEnabled​(boolean enabled)
        Enables/disables rendering of local CSS fonts (enabled by default).
        EXPERIMENTAL
        Parameters:
        enabled - Whether rendering of local fonts is enabled.
        Returns:
        An instance of Script<Void>

        This Script instance must be executed before the browser receives the invocation-request.

        This Browser-Function does not have a return-value. You may choose to await the Promise<Void> to ensure that the Browser Function has run to completion.

      • setStyleSheetText

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.String> setStyleSheetText​
            (java.lang.String styleSheetId,
             java.lang.String text)
        Sets the new stylesheet text.
        Parameters:
        styleSheetId - -
        text - -
        Returns:
        An instance of Script<String>

        This script may be executed, using Script.exec, and afterwards, a Promise <String> will be returned

        Finally, the Promise may be awaited, using Promise.await(), and the returned result of this Browser Function may be retrieved.

        This Browser Function's Promise returns: String (sourceMapURL)
        URL of source map associated with script (if any).

      • setStyleTexts

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<CSS.CSSStyle[]> setStyleTexts​
            (CSS.StyleDeclarationEdit[] edits,
             java.lang.Integer nodeForPropertySyntaxValidation)
        Applies specified style edits one after another in the given order.
        Parameters:
        edits - -
        nodeForPropertySyntaxValidation - NodeId for the DOM node in whose context custom property declarations for registered properties should be validated. If omitted, declarations in the new rule text can only be validated statically, which may produce incorrect results if the declaration contains a var() for example.
        OPTIONALEXPERIMENTAL
        Returns:
        An instance of Script<CSS.CSSStyle[]>

        This script may be executed, using Script.exec, and afterwards, a Promise <CSS.CSSStyle[]> will be returned

        Finally, the Promise may be awaited, using Promise.await(), and the returned result of this Browser Function may be retrieved.

        This Browser Function's Promise returns: CSS.CSSStyle[] (styles)
        The resulting styles after modification.

      • startRuleUsageTracking

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.Void> startRuleUsageTracking()
        Enables the selector recording.
        Returns:
        An instance of Script<Void>

        This Script instance must be executed before the browser receives the invocation-request.

        This Browser-Function does not have a return-value. You may choose to await the Promise<Void> to ensure that the Browser Function has run to completion.

      • takeComputedStyleUpdates

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<int[]> takeComputedStyleUpdates()
        Polls the next batch of computed style updates.
        EXPERIMENTAL
        Returns:
        An instance of Script<int[]>

        This script may be executed, using Script.exec, and afterwards, a Promise <int[]> will be returned

        Finally, the Promise may be awaited, using Promise.await(), and the returned result of this Browser Function may be retrieved.

        This Browser Function's Promise returns: int[] (nodeIds)
        The list of node Ids that have their tracked computed styles updated.

      • trackComputedStyleUpdates

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.Void> trackComputedStyleUpdates​
            (CSS.CSSComputedStyleProperty[] propertiesToTrack)
        Starts tracking the given computed styles for updates. The specified array of properties replaces the one previously specified. Pass empty array to disable tracking. Use takeComputedStyleUpdates to retrieve the list of nodes that had properties modified. The changes to computed style properties are only tracked for nodes pushed to the front-end by the DOM agent. If no changes to the tracked properties occur after the node has been pushed to the front-end, no updates will be issued for the node.
        EXPERIMENTAL
        Parameters:
        propertiesToTrack - -
        Returns:
        An instance of Script<Void>

        This Script instance must be executed before the browser receives the invocation-request.

        This Browser-Function does not have a return-value. You may choose to await the Promise<Void> to ensure that the Browser Function has run to completion.

      • trackComputedStyleUpdatesForNode

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Script<java.lang.Void> trackComputedStyleUpdatesForNode​
            (java.lang.Integer nodeId)
        Starts tracking the given node for the computed style updates and whenever the computed style is updated for node, it queues a computedStyleUpdated event with throttling. There can only be 1 node tracked for computed style updates so passing a new node id removes tracking from the previous node. Pass undefined to disable tracking.
        EXPERIMENTAL
        Parameters:
        nodeId - -
        OPTIONAL
        Returns:
        An instance of Script<Void>

        This Script instance must be executed before the browser receives the invocation-request.

        This Browser-Function does not have a return-value. You may choose to await the Promise<Void> to ensure that the Browser Function has run to completion.