progrium / topframe Goto Github PK

View Code? Open in Web Editor NEW

351.0 14.0 7.0 8.63 MB

Local webpage screen overlay for customizing your computing experience

License: MIT License

Makefile 1.02% HTML 15.65% Go 16.76% JavaScript 63.56% Shell 3.01%

html5 html-css-javascript javascript macos webview golang overlay-window always-on-top overlay

topframe's Introduction

Topframe

Local webpage screen overlay

Customize your computing experience with webdev
Display information and always-on-top widgets
Edit source, hit save, screen will update
Extensible with shell scripts in any language
Less than 400 lines of Go code, minimal deps
Currently alpha, macOS only ...

Getting Started

You can download from Releases or with Homebrew you can:

$ brew install progrium/taps/topframe

If you download a release zip make sure to unzip and put the binary in your PATH (like /usr/local/bin).

$ topframe -h
Usage: topframe <flags>
Topframe is a fullscreen webview overlay agent

Flags:
  -docs       open documentation in browser
  -help       show help
  -plist      generate launch agent plist
  -version    show version

To start it and show the demo webpage overlay, simply run topframe. This will also:

create a ~/.topframe directory with a demo index.html used for the overlay
watch for file changes in ~/.topframe to trigger a page reload
add a menu bar extra (🔲) to control the overlay

If you edit ~/.topframe/index.html and hit save, changes will reflect immediately. If you hate the demo content of the default index.html, change it! Use Show Source from the menu extra to quickly open your topframe directory.

Launching on Startup

Topframe works with launchd to run as a background agent on startup. You can generate an agent plist file with topframe -plist, which you can write to a file in ~/Library/LaunchAgents:

$ topframe -plist > ~/Library/LaunchAgents/com.progrium.Topframe.plist

It's a good idea to view the output before writing to the file, just to make sure paths are correct. If you don't know what is correct, it's probably fine!

Documentation

There is not a whole lot to Topframe! I recommend reading the source as its only a few hundred lines, but otherwise there is a wiki ready to document anything else.

Getting Help

If you're having trouble, be sure to check issues to see if its a known issue. Otherwise, feel free to drop a question into the discussion forum.

Contributing

Ideally, Topframe is kept small. Bug fixes and other small PRs are welcome and should be merged quickly. If you happen to have a large PR that we haven't discussed, you should talk about it in the forum first. In order to keep the project small, some features suggestions may be held back in favor of determining a good extension point to expose instead.

About

Topframe started as a 130 line example for progrium/macdriver.

MIT Licensed

topframe's People

Contributors

Stargazers

Watchers

Forkers

jpf isgasho productinfo ngfine alphat7 visionarylab strogo

topframe's Issues

manage LaunchAgent plist file in app via menu item

I'm not sure why I avoided it, but instead of generating a plist file for the user to place at ~/Library/LaunchAgents/com.progrium.Topframe.plist via command line, there should just be a menu item for "Start at login". We'd check if that plist file exists to "checkmark" that menu item. On click, if not checked, it would write that file. If checked, it would delete the file. I know that would remove any edits made to the file, but I don't know of another simple way to do this. Maybe that's why I wanted the user to manage it in the first place. However, I think the convenience for the common case is worth it.

Does this work with websocket?

Cant seem to get it working with advanced combat tracker .

cross-platform support

This is an issue for people interested in tracking cross-platform support. Topframe currently uses progrium/macdriver for its UI. Once that project is on its way to 1.0, I will start equivalent tuxdriver and windriver projects, but let me know which is higher priority.

setup homebrew tap for `brew install progrium/tap/topframe`

Once we have release builds (signed and notarized [#6]), I can set up a Homebrew tap and formulae for topframe to make installation with Homebrew as easy as:

$ brew tap progrium/tap
$ brew install progrium/tap/topframe

sign and notarize using gon

Right now installation is done via go get because it circumvents the security of new binaries by building from source. However, we want to make it easier to install, so we must sign and notarize binaries before we can even build and release them usefully here. Luckily, we have gon to provide a workflow for this. It just needs to be set up.

minimise or dont show terminal window when the program is opened

Good idea?

global shortcut to enable/disable

It would be nice to have a keyboard shortcut to enable/disable topframe. Since the app doesn't let you switch focus to it (and that would be annoying anyway), it would have to be a global shortcut. Open to suggestions on what it should be. I'd rather hardcode it than make it configurable, though I'd be open to environment variable configuration.

resize window?

Possible to resize the overlay?

not able to launch on startup

i cant seem to run the launch on startup plist command
it says that 'topframe' isnt a command

do i need to install launchd or something? i tried searching for a way to download launchd but i only found a python version. help pls