wm.wit

// Copyright 2023 i509VCB
//
// Permission to use, copy, modify, and/or distribute this software for any
// purpose with or without fee is hereby granted, provided that the above
// copyright notice and this permission notice appear in all copies.
//
// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
// WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
// MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
// ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
// WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
// ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
// OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package aerugo:wm

// TODO: popups, layer shell, pointer, wm surfaces, graphics

/// The Aerugo WM API
///
/// At a high level the the WM API takes a list of toplevels, popups and layer surfaces, configures each surface
/// and then describes a tree to present the output.
world aerugo-wm {
    export wm-types
}

interface wm-types {
    use types.{key-filter, key-modifiers, key-status, snapshot, output, output-id, server, toplevel, toplevel-id, toplevel-updates}

    /// Description of a wm module.
    record wm-info {
        /// Major version of the ABI this wm module was linked to.
        abi-major: u32,

        /// Minor version of the ABI this wm module was linked to.
        abi-minor: u32,

        /// Name of this wm module.
        name: string,

        /// Version of this wm module.
        version: string,
    }

    /// The window manager.
    resource wm {
        /// A new toplevel has been created and is waiting to be mapped.
        ///
        /// At this point the wm may configure the toplevel and prepare the toplevel to be presented.
        new-toplevel: func(toplevel: own<toplevel>)

        /// The toplevel has been unmapped and therefore closed.
        ///
        /// The display server will cache the contents of the toplevel as long as the toplevel handle is valid
        /// to allow for wms to implement animations when the toplevel is closed.
        closed-toplevel: func(toplevel: toplevel-id)

        /// The state of the toplevel has changed.
        ///
        /// The provided update flags indicate what properties have changed.
        update-toplevel: func(toplevel: toplevel-id, updates: toplevel-updates)

        /// The toplevel has acked a pending state.
        ///
        /// The wm can assume when the toplevel will be committed by the client soon.
        ack-toplevel: func(toplevel: toplevel-id, serial: u32)

        /// The toplevel has been committed.
        ///
        /// At this point the toplevel can be presented. If the size of the toplevel has changed, a new snapshot
        /// will be provided.
        committed-toplevel: func(toplevel: toplevel-id, snapshot: option<own<snapshot>>)

        /// A key has been pressed or released.
        ///
        /// The keycode is an X11 keysym.
        key: func(time: u32, sym: u32, compose: option<string>, status: key-status) -> key-filter

        /// The keyboard modifiers have been updated.
        key-modifiers: func(modifiers: key-modifiers)

        /// A new output has been created.
        new-output: func(output: own<output>)

        /// An output has been disconnected.
        disconnect-output: func(output: output-id)
    }

    /// Query information about the wm.
    get-info: func() -> result<wm-info, string>

    create-wm: func(server: own<server>) -> result<own<wm>, string>
}

interface types {
    /// A handle to the display server.
    ///
    /// This is the mechanism through which the wm can describe a scene graph and present.
    resource server {
        set-keyboard-focus: func(focus: focus)

        set-pointer-focus: func(focus: focus)
    }

    resource view-builder {
        /// Create a node builder for a toplevel using the specified snapshot. 
        with-toplevel: static func(toplevel: borrow<toplevel>, snapshot: borrow<snapshot>) -> own<view-builder>

        build: func() -> own<view>
    }

    resource view {}

    /// A physical or virtual output.
    resource output {
        id: func() -> output-id

        /// A human readable name for the output.
        name: func() -> option<string>

        /// Query the geometry of the output.
        ///
        /// The geometry describes the location and size of the output.
        geometry: func() -> geometry

        /// Query the refresh rate of the output in millihertz.
        refresh-rate: func() -> u32
    }

    /// A handle to a toplevel.
    ///
    /// This object can be used to query the state of a toplevel.
    resource toplevel {
        /// Query the id of the toplevel.
        id: func() -> toplevel-id

        /// Query the features supported by the toplevel.
        features: func() -> features

        /// Query whether the toplevel has been mapped.
        ///
        /// If this is true, this toplevel has already been mapped by a past WM due to handoff.
        mapped: func() -> bool

        /// Query the app id of the toplevel
        ///
        /// If the toplevel is an XWayland surface, this will will return the window class.
        app-id: func() -> option<string>

        /// Query the title of the toplevel.
        title: func() -> option<string>

        /// Query the suggested minimum size of the toplevel.
        min-size: func() -> option<size>

        /// Query the suggested maximum size of the toplevel.
        max-size: func() -> option<size>

        /// Query the geometry of the toplevel.
        geometry: func() -> option<geometry>

        /// Query the parent of the toplevel
        parent: func() -> option<toplevel-id>

        /// Query the current states of the toplevel.
        state: func() -> toplevel-state

        /// Query the current decoration mode of the toplevel.
        decorations: func() -> decoration-mode

        /// Query the edge of the toplevel being grabbed during a user driven resize.
        resize-edge: func() -> option<resize-edge>

        /// Request the toplevel be closed.
        ///
        /// This is immediately sent to the toplevel.
        request-close: func()
    }

    /// Description of a toplevel configure
    ///
    /// If a property is not set in the configure, then it is assumed the previous value will be used.
    resource toplevel-configure {
        /// Build a toplevel configure
        constructor(toplevel: borrow<toplevel>)

        /// Submit the configure and wait for the toplevel to ack the configure.
        ///
        /// This function returns a serial which can be used to ensure the toplevel was acked.
        submit: func() -> u32

        /// Set the new decoration mode of the toplevel.
        ///
        /// This is ignored if the toplevel does not support server side decorations.
        decorations: func(decorations: decoration-mode)

        /// Set the new parent of the toplevel.
        parent: func(parent: option<borrow<toplevel>>)

        /// Set the new state of the toplevel.
        state: func(states: toplevel-state)

        /// Set the new suggested size of the toplevel.
        ///
        /// If the size is none, the toplevel may pick it's own size. The default size is 0x0.
        ///
        /// Whether or not the size must be used is dependent on the toplevel states.
        size: func(size: option<size>)

        /// Set the new suggested bounds of the toplevel.
        ///
        /// If the bounds are none, the toplevel will behave as if no bounds are set. Similarly if the toplevel
        /// does not support bounds, the bounds are ignored.
        bounds: func(bounds: option<size>)
    }

    /// A handle to a contents of a surface.
    ///
    /// When dropped, the backing storage of the snapshot is destroyed.
    resource snapshot {
        /// Query the size of the snapshot.
        size: func() -> size

        /// Query the scale of the snapshot.
        scale: func() -> float32
    }

    /// Id to reference a toplevel.
    type toplevel-id = u32

    /// Id to reference an output.
    type output-id = u32

    /// Size of a surface.
    record size {
        /// width of surface
        width: u32,

        /// height of surface
        height: u32,
    }

    /// Describes the geometry of a toplevel.
    record geometry {
        /// x position of top left corner of the window
        x: s32,

        /// y position of top left corner of the toplevel
        y: s32,

        /// width of the toplevel
        width: u32,

        /// height of the toplevel.
        height: u32
    }

    /// Features supported by the toplevel.
    flags features {
        /// The toplevel supports server side decorations.
        ///
        /// If this feature is not supported, the decoration mode will be ignored during a configure and
        /// querying the decoration mode will always return client_side.
        server-side-decorations,

        /// The toplevel can understand tiled states.
        ///
        /// If this feature is not supported the tiled states will be ignored in configures.
        tiled-states,

        /// The toplevel understands the suspended state.
        ///
        /// If this feature is not supported the suspended state will be ignored in configures.
        suspended,
    }

    /// States a toplevel may have
    flags toplevel-state {
        maximized,
        fullscreen,
        resizing,
        activated,
        tiled-left,
        tiled-right,
        tiled-top,
        tiled-bottom,
        suspended,
    }

    /// Decoration mode of a toplevel.
    enum decoration-mode {
        /// The client decorates the toplevel 
        client-side,

        /// The server decorates the toplevel.
        server-side,
    }

    /// The edge of a toplevel which is being resized.
    enum resize-edge {
        top,
        bottom,
        left,
        right,
        top-left,
        top-right,
        bottom-left,
        bottom-right,
    }

    flags toplevel-updates {
        /// The app id has changed.
        app-id,

        /// The title of the toplevel has changed.
        title,

        /// The parent of the toplevel has changed.
        parent,

        /// The minimum suggested size of the toplevel has changed.
        min-size,

        /// The maximum suggested size of the toplevel has changed.
        max-size,
        
        /// The geometry of the toplevel has changed.
        geometry,

        /// The toplevel has requested to be made maximized.
        request-set-maximized,

        /// The toplevel has requested to be un-maximized.
        request-unset-maximized,

        /// The toplevel has requested to be made fullscreen.
        request-set-fullscreen,

        /// The toplevel has requested to leave fullscreen.
        request-unset-fullscreen,

        /// The toplevel has requested to be minimized.
        request-set-minimized,

        /// The toplevel has requested a user driven move.
        ///
        /// The wm is free to ignore the move, such as if the surface is fullscreened or maximized.
        request-move,

        /// The toplevel has requested a user driven resize.
        ///
        /// The wm is free to ignore the move, such as if the surface is fullscreened or maximized. To
        /// determine what edge is being grabbed during the resize, use the resize_edge function on toplevel.
        request-resize,
    }

    enum key-status {
        press,
        release,
    }

    flags key-modifiers {
        ctrl,
        alt,
        shift,
        caps-lock,
        logo,
        num-lock,
    }

    enum key-filter {
        /// The key input should be dropped and not propagated to the target.
        drop,

        /// The key input should be forwarded to the target.
        forward,
    }

    /// The current focused object.
    variant focus {
        none,
        toplevel(toplevel-id),
    }
}