# Copyright (c) 2024-2026 Karana Dynamics Pty Ltd. All rights reserved.
#
# NOTICE TO USER:
#
# This source code and/or documentation (the "Licensed Materials") is
# the confidential and proprietary information of Karana Dynamics Inc.
# Use of these Licensed Materials is governed by the terms and conditions
# of a separate software license agreement between Karana Dynamics and the
# Licensee ("License Agreement"). Unless expressly permitted under that
# agreement, any reproduction, modification, distribution, or disclosure
# of the Licensed Materials, in whole or in part, to any third party
# without the prior written consent of Karana Dynamics is strictly prohibited.
#
# THE LICENSED MATERIALS ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND.
# KARANA DYNAMICS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
# BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, AND
# FITNESS FOR A PARTICULAR PURPOSE.
#
# IN NO EVENT SHALL KARANA DYNAMICS BE LIABLE FOR ANY DAMAGES WHATSOEVER,
# INCLUDING BUT NOT LIMITED TO LOSS OF PROFITS, DATA, OR USE, EVEN IF
# ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, WHETHER IN CONTRACT, TORT,
# OR OTHERWISE ARISING OUT OF OR IN CONNECTION WITH THE LICENSED MATERIALS.
#
# U.S. Government End Users: The Licensed Materials are a "commercial item"
# as defined at 48 C.F.R. 2.101, and are provided to the U.S. Government
# only as a commercial end item under the terms of this license.
#
# Any use of the Licensed Materials in individual or commercial software must
# include, in the user documentation and internal source code comments,
# this Notice, Disclaimer, and U.S. Government Use Provision.
from pathlib import Path
import os
from typing import Literal
from Karana.WebUI import HttpWsServer, Router, IFrame, Dock
__all__ = ["EasyDock"]
def findSharePath() -> Path:
yam_install = os.getenv("YAM_INSTALL")
karana_share_dir = os.getenv("KARANA_SHARE_DIR")
if yam_install:
return Path(yam_install) / "share" / "Karana" / "WebUI"
if karana_share_dir:
return Path(karana_share_dir) / "WebUI"
test_path = Path("/opt/homebrew/share/Karana/WebUI")
if test_path.exists():
return test_path
return Path("/usr/share/Karana/WebUI")
[docs]
class EasyDock:
def __init__(self, port: int = 0):
"""EasyDock constructor
Parameters
----------
port: int
The port to listen on. Defaults to 0.
"""
self.server = HttpWsServer(port)
frontend_path = findSharePath() / "frontend"
self.server.serveFile("/", frontend_path / "index.html")
self.server.serveFile("/index.html", frontend_path / "index.html")
self.server.serveFile("/main.js", frontend_path / "router-main-bundle.js")
self.server.serveFile("/main.css", frontend_path / "dock-bundle.css")
self.router = Router(self.server)
self.dock = Dock(self.router)
self.iframes = []
self.server.printConnectionInfo()
@property
def port(self) -> int:
"""The server's port
Returns
-------
int
The port
"""
return self.server.getPort()
@property
def url(self) -> str:
"""The server's base url
Returns
-------
str
The base url
"""
return self.server.getUrl()
[docs]
def addFrame(
self,
url: str,
title: str = "untitled",
*,
relative_to: str | None = None,
direction: Literal["left", "right", "above", "below", "within"] | None = None
) -> str:
"""Add an IFrame panel to the dock
Parameters
----------
url: str
The url to open in the iframe
title: str
Title of the panel containing the iframe
relative_to: str | None
Id returned from a previous call from a frame to position relative to
direction: Literal["left", "right", "above", "below", "within"] | None
If relative_to was given, how to position the new frame
Returns
-------
str
Id to refer to the added frame
"""
if direction and not relative_to:
raise ValueError("direction requires relative_to to be specified")
iframe = IFrame(self.router, url)
self.dock.addChild(
title=title, dom_id=iframe.domId(), relative_to=relative_to, direction=direction
)
self.iframes.append(iframe)
return iframe.domId()
