package tcelllivepage

Import Path
	github.com/pancsta/cview/tcell-livepage (on go.dev)

Dependency Relation
	imports 24 packages, and imported by 2 packages

Involved Source Files assets.go compo.go events.go html.go pty.go pty_common.go pty_keys.go Package tcelllivepage provides a tcell screen which renders to a browser as HTML streamed by livepage. DOM input events are mapped back to tcell cell coordinates. screen_mux.go
Package-Level Type Names (total 7)
/* sort by: | */
AttachOpts configures a single UI projection of a [ScreenMux]. Clients reports the number of connected clients of this UI, if any. A deferred UI with no clients is kept at the core size. DeferredSize excludes the UI from size negotiation until it reports its first resize. Used for browsers, before a client connects. DetachOnCtrlQ detaches only this UI on Ctrl+Q instead of forwarding the event to the app. func (*ScreenMux).Attach(screen tcell.Screen, closeFn func(), opts AttachOpts) *MuxClient
CmdOpts configures [RunCmd]. Addr is the HTTP listen address. Printf logs the livepage URL and server errors. Optional. Title is the title of the default HTML page. Optional. func RunCmd(ctx context.Context, cmd *exec.Cmd, opts CmdOpts) error
MuxClient is a single UI projection of the core screen. Done is closed when the UI gets detached. func (*ScreenMux).Attach(screen tcell.Screen, closeFn func(), opts AttachOpts) *MuxClient func (*ScreenMux).Detach(c *MuxClient) func (*ScreenMux).SetDeferred(c *MuxClient, deferred bool)
Opts configures a [Screen]. Cols and Rows are the initial grid dimensions before the browser reports the viewport. Defaults to [DefaultCols] and [DefaultRows]. FontFamily is the CSS font family. Defaults to a monospace stack. FontSize is the CSS font size in pixels. Defaults to [DefaultFontSize]. Live holds the livepage options. HtmlPage is wrapped to inject the screen's CSS and JS. Debounce defaults to 20ms. RefreshInterval coalesces [Screen.Show] refreshes to at most this rate, using a trailing refresh. Zero means no throttling. Use it for applications which draw frequently, e.g. 100ms for ~10fps. Cols and Rows are the initial grid dimensions before the browser reports the viewport. Defaults to [DefaultCols] and [DefaultRows]. Theme defines the default colors. Defaults to [DefaultTheme]. Title is the title of the default HTML page. Optional. func NewScreen(ctx context.Context, opts Opts) (*Screen, error)
Screen is a tcell screen which streams its grid to the browser as HTML using livepage. It embeds a [tcell.SimulationScreen], so it can be passed to [cview.Application.SetScreen] or used by any tcell application. The screen is initialized by [NewScreen]; [tcell.Screen.Init] is a no-op. SimulationScreen tcell.SimulationScreen Beep attempts to sound an OS-dependent audible alert and returns an error when unsuccessful. CanDisplay returns true if the given rune can be displayed on this screen. Note that this is a best-guess effort -- whether your fonts support the character or not may be questionable. Mostly this is for folks who work outside of Unicode. If checkFallbacks is true, then if any (possibly imperfect) fallbacks are registered, this will return true. This will also return true if the terminal can replace the glyph with one that is visually indistinguishable from the one requested. Deprecated: This is not a particularly useful or reliable function, due to limitations in fonts, etc. It will be removed in the future. ChannelEvents is an infinite loop that waits for an event and channels it into the user provided channel ch. Closing the quit channel and calling the Fini method are cancellation signals. When a cancellation signal is received the method returns after closing ch. This method should be used as a goroutine. NOTE: PollEvent should not be called while this method is running. CharacterSet returns information about the character set. This isn't the full locale, but it does give us the input/output character set. Note that this is just for diagnostic purposes, we normally translate input/output to/from UTF-8, regardless of what the user's environment is. Clear logically erases the screen. This is effectively a short-cut for Fill(' ', StyleDefault). Colors returns the number of colors. All colors are assumed to use the ANSI color map. If a terminal is monochrome, it will return 0. DisableFocus disables reporting of focus events. DisableMouse disables the mouse. DisablePaste disables bracketed paste mode. EnableFocus enables reporting of focus events, if your terminal supports it. EnableMouse enables the mouse. (If your terminal supports it.) If no flags are specified, then all events are reported, if the terminal supports them. EnablePaste enables bracketed paste mode, if supported. Fill fills the screen with the given character and style. The effect of filling the screen is not visible until Show is called (or Sync). Fini stops the screen and disposes the page. Get the contents at the given location. If the coordinates are out of range, then the values will be 0, nil, StyleDefault. Note that the contents returned are logical contents and may not actually be what is displayed, but rather are what will be displayed if Show() or Sync() is called. The width is the width in screen cells; most often this will be 1, but some East Asian characters and emoji require two cells. GetClipboard is used to request the clipboard contents. It may be ignored. If the terminal is willing, it will be post the clipboard contents using an EventPaste with the clipboard content as the Data() field. Terminals may prevent this for security reasons. GetClipboardData gets the actual data for the clipboard. GetContent is the old way to get cell contents. Deprecated: Use Get() instead. GetContents returns screen contents as an array of cells, along with the physical width & height. Note that the physical contents will be used until the next time SetSize() is called. GetCursor returns the cursor details. GetTitle gets the previously set title. Handler serves the page, the livepage scripts and the WebSocket. HasKey always returns true. Deprecated: This function always returns true. Applications cannot reliably detect whether a key is supported or not with modern terminal emulators. (The intended use here was to help applications determine whether a given key stroke was supported by the terminal, but it was never reliable.) HasMouse returns true if the terminal (apparently) supports a mouse. Note that the return value of true doesn't guarantee that a mouse/pointing device is present; a false return definitely indicates no mouse support is available. HasPendingEvent returns true if PollEvent would return an event without blocking. If the screen is stopped and PollEvent would return nil, then the return value from this function is unspecified. The purpose of this function is to allow multiple events to be collected at once, to minimize screen redraws. HideCursor is used to hide the cursor. It's an alias for ShowCursor(-1, -1).sim Init is a no-op, the screen is initialized by [NewScreen]. InjectKey injects a key event. The rune is a UTF-8 rune, post any translation. InjectKeyBytes injects a stream of bytes corresponding to the native encoding (see charset). It turns true if the entire set of bytes were processed and delivered as KeyEvents, false if any bytes were not fully understood. Any bytes that are not fully converted are discarded. InjectMouse injects a mouse event. LockRegion sets or unsets a lock on a region of cells. A lock on a cell prevents the cell from being redrawn. Machine returns the machine used to serialize rendering and DOM events. PollEvent waits for events to arrive. Main application loops must spin on this to prevent the application from stalling. Furthermore, this will return nil if the Screen is finalized. PostEvent tries to post an event into the event stream. This can fail if the event queue is full. In that case, the event is dropped, and ErrEventQFull is returned. Deprecated: PostEventWait is unsafe, and will be removed in the future. PostEventWait is like PostEvent, but if the queue is full, it blocks until there is space in the queue, making delivery reliable. However, it is VERY important that this function never be called from within whatever event loop is polling with PollEvent(), otherwise a deadlock may arise. For this reason, when using this function, the use of a Goroutine is recommended to ensure no deadlock can occur. Put writes the first graphme of the given string with th given style at the given coordinates. (Only the first grapheme occupying either one or two cells is stored.) It returns the remainder of the string, and the width displayed. PutStr writes a string starting at the given position, using the default style. The content is clipped to the screen dimensions. PutStrStyled writes a string starting at the given position, using the given style. The cont4ent is clipped to the screen dimensions. RegisterRuneFallback adds a fallback for runes that are not part of the character set -- for example one could register o as a fallback for ø. This should be done cautiously for characters that might be displayed ordinarily in language specific text -- characters that could change the meaning of written text would be dangerous. The intention here is to facilitate fallback characters in pseudo-graphical applications. If the terminal has fallbacks already in place via an alternate character set, those are used in preference. Also, standard fallbacks for graphical characters in the alternate character set terminfo string are registered implicitly. The display string should be the same width as original rune. This makes it possible to register two character replacements for full width East Asian characters, for example. It is recommended that replacement strings consist only of 7-bit ASCII, since other characters may not display everywhere. Resize does nothing, since it's generally not possible to ask a screen to resize, but it allows the Screen to implement the View interface. ResizeGrid resizes the grid, typically from the browser viewport. It posts a [tcell.EventResize] to the application and reports whether the size changed. Resume resumes after Suspend(). SetCell is an older API, and will be removed. jj Deprecated: Please use Put instead. SetClipboard is used to post arbitrary data to the system clipboard. This need not be UTF-8 string data. It's up to the recipient to decode the data meaningfully. Terminals may prevent this for security reasons. SetContent sets the contents of the given cell location. If the coordinates are out of range, then the operation is ignored. The first rune is the primary non-zero width rune. The array that follows is a possible list of combining characters to append, and will usually be nil (no combining characters.) The results are not displayed until Show() or Sync() is called. Note that wide (East Asian full width and emoji) runes occupy two cells, and attempts to place character at next cell to the right will have undefined effects. Wide runes that are printed in the last column will be replaced with a single width space on output. SetCursorStyle is used to set the cursor style. If the style is not supported (or cursor styles are not supported at all), then this will have no effect. Color will be changed if supplied, and the terminal supports doing so. SetSize attempts to resize the window. It also invalidates the cells and calls the resize function. Note that if the window size is changed, it will not be restored upon application exit. Many terminals cannot support this. Perversely, the "modern" Windows Terminal does not support application-initiated resizing, whereas the legacy terminal does. Also, some emulators can support this but may have it disabled by default. SetStyle sets the default style to use when clearing the screen or when StyleDefault is specified. If it is also StyleDefault, then whatever system/terminal default is relevant will be used. SetTitle sets a window title on the screen. Terminals may be configured to ignore this, or unable to. Tcell may attempt to save and restore the window title on entry and exit, but the results may vary. Use of unicode characters may not be supported. Show marks the screen as dirty and renders/pushes the HTML. Rendering is skipped while no browser is connected, and coalesced according to [Opts.RefreshInterval]. ShowCursor is used to display the cursor at a given location. If the coordinates -1, -1 are given or are otherwise outside the dimensions of the screen, the cursor will be hidden. Size returns the screen size as width, height. This changes in response to a call to Clear or Flush. Suspend pauses input and output processing. It also restores the terminal settings to what they were when the application started. This can be used to, for example, run a sub-shell. Sync renders and pushes the current state immediately. Tty returns the underlying Tty. If the screen is not a terminal, the returned bool will be false UnregisterRuneFallback unmaps a replacement. It will unmap the implicit ASCII replacements for alternate characters as well. When an unmapped char needs to be displayed, but no suitable glyph is available, '?' is emitted instead. It is not possible to "disable" the use of alternate characters that are supported by your terminal except by changing the terminal database. *Screen : github.com/gdamore/tcell/v2.Screen *Screen : github.com/gdamore/tcell/v2.SimulationScreen func NewScreen(ctx context.Context, opts Opts) (*Screen, error)
ScreenMux multiplexes one core simulation screen to multiple UIs. It implements [tcell.Screen] and can be passed to cview's Application.SetScreen. SimulationScreen tcell.SimulationScreen Attach registers a UI screen and starts forwarding its events and cells. Beep attempts to sound an OS-dependent audible alert and returns an error when unsuccessful. CanDisplay returns true if the given rune can be displayed on this screen. Note that this is a best-guess effort -- whether your fonts support the character or not may be questionable. Mostly this is for folks who work outside of Unicode. If checkFallbacks is true, then if any (possibly imperfect) fallbacks are registered, this will return true. This will also return true if the terminal can replace the glyph with one that is visually indistinguishable from the one requested. Deprecated: This is not a particularly useful or reliable function, due to limitations in fonts, etc. It will be removed in the future. ChannelEvents is an infinite loop that waits for an event and channels it into the user provided channel ch. Closing the quit channel and calling the Fini method are cancellation signals. When a cancellation signal is received the method returns after closing ch. This method should be used as a goroutine. NOTE: PollEvent should not be called while this method is running. CharacterSet returns information about the character set. This isn't the full locale, but it does give us the input/output character set. Note that this is just for diagnostic purposes, we normally translate input/output to/from UTF-8, regardless of what the user's environment is. (*ScreenMux) Clear() Colors returns the number of colors. All colors are assumed to use the ANSI color map. If a terminal is monochrome, it will return 0. Detach removes a UI and releases its screen. DisableFocus disables reporting of focus events. (*ScreenMux) DisableMouse() (*ScreenMux) DisablePaste() EnableFocus enables reporting of focus events, if your terminal supports it. (*ScreenMux) EnableMouse(flags ...tcell.MouseFlags) (*ScreenMux) EnablePaste() (*ScreenMux) Fill(r rune, style tcell.Style) Fini detaches all UIs and the core screen. Get the contents at the given location. If the coordinates are out of range, then the values will be 0, nil, StyleDefault. Note that the contents returned are logical contents and may not actually be what is displayed, but rather are what will be displayed if Show() or Sync() is called. The width is the width in screen cells; most often this will be 1, but some East Asian characters and emoji require two cells. GetClipboard is used to request the clipboard contents. It may be ignored. If the terminal is willing, it will be post the clipboard contents using an EventPaste with the clipboard content as the Data() field. Terminals may prevent this for security reasons. GetClipboardData gets the actual data for the clipboard. GetContent is the old way to get cell contents. Deprecated: Use Get() instead. GetContents returns screen contents as an array of cells, along with the physical width & height. Note that the physical contents will be used until the next time SetSize() is called. GetCursor returns the cursor details. GetTitle gets the previously set title. HasKey always returns true. Deprecated: This function always returns true. Applications cannot reliably detect whether a key is supported or not with modern terminal emulators. (The intended use here was to help applications determine whether a given key stroke was supported by the terminal, but it was never reliable.) HasMouse returns true if the terminal (apparently) supports a mouse. Note that the return value of true doesn't guarantee that a mouse/pointing device is present; a false return definitely indicates no mouse support is available. HasPendingEvent returns true if PollEvent would return an event without blocking. If the screen is stopped and PollEvent would return nil, then the return value from this function is unspecified. The purpose of this function is to allow multiple events to be collected at once, to minimize screen redraws. HideCursor is used to hide the cursor. It's an alias for ShowCursor(-1, -1).sim Init is a no-op, the screen is initialized by [NewScreenMux]. InjectKey injects a key event. The rune is a UTF-8 rune, post any translation. InjectKeyBytes injects a stream of bytes corresponding to the native encoding (see charset). It turns true if the entire set of bytes were processed and delivered as KeyEvents, false if any bytes were not fully understood. Any bytes that are not fully converted are discarded. InjectMouse injects a mouse event. LockRegion sets or unsets a lock on a region of cells. A lock on a cell prevents the cell from being redrawn. PollEvent returns the next event from any UI. PostEvent queues an event for the app, eg an injected keystroke. Deprecated: PostEventWait is unsafe, and will be removed in the future. PostEventWait is like PostEvent, but if the queue is full, it blocks until there is space in the queue, making delivery reliable. However, it is VERY important that this function never be called from within whatever event loop is polling with PollEvent(), otherwise a deadlock may arise. For this reason, when using this function, the use of a Goroutine is recommended to ensure no deadlock can occur. Put writes the first graphme of the given string with th given style at the given coordinates. (Only the first grapheme occupying either one or two cells is stored.) It returns the remainder of the string, and the width displayed. PutStr writes a string starting at the given position, using the default style. The content is clipped to the screen dimensions. PutStrStyled writes a string starting at the given position, using the given style. The cont4ent is clipped to the screen dimensions. RegisterRuneFallback adds a fallback for runes that are not part of the character set -- for example one could register o as a fallback for ø. This should be done cautiously for characters that might be displayed ordinarily in language specific text -- characters that could change the meaning of written text would be dangerous. The intention here is to facilitate fallback characters in pseudo-graphical applications. If the terminal has fallbacks already in place via an alternate character set, those are used in preference. Also, standard fallbacks for graphical characters in the alternate character set terminfo string are registered implicitly. The display string should be the same width as original rune. This makes it possible to register two character replacements for full width East Asian characters, for example. It is recommended that replacement strings consist only of 7-bit ASCII, since other characters may not display everywhere. Resize does nothing, since it's generally not possible to ask a screen to resize, but it allows the Screen to implement the View interface. Resume resumes after Suspend(). SetCell is an older API, and will be removed. jj Deprecated: Please use Put instead. SetClipboard is used to post arbitrary data to the system clipboard. This need not be UTF-8 string data. It's up to the recipient to decode the data meaningfully. Terminals may prevent this for security reasons. SetContent writes a cell to the core and marks it for projection. SetCursorStyle is used to set the cursor style. If the style is not supported (or cursor styles are not supported at all), then this will have no effect. Color will be changed if supplied, and the terminal supports doing so. SetDeferred excludes a UI from size negotiation and keeps its grid at the core size. Used when the last client of a deferred UI disconnects. SetSize attempts to resize the window. It also invalidates the cells and calls the resize function. Note that if the window size is changed, it will not be restored upon application exit. Many terminals cannot support this. Perversely, the "modern" Windows Terminal does not support application-initiated resizing, whereas the legacy terminal does. Also, some emulators can support this but may have it disabled by default. (*ScreenMux) SetStyle(style tcell.Style) SetTitle sets a window title on the screen. Terminals may be configured to ignore this, or unable to. Tcell may attempt to save and restore the window title on entry and exit, but the results may vary. Use of unicode characters may not be supported. Show snapshots the changed cells and queues them for projection. The snapshot is taken on the app goroutine, right after the frame has been drawn, so UIs never see a partially drawn frame. (*ScreenMux) ShowCursor(x, y int) Size returns the screen size as width, height. This changes in response to a call to Clear or Flush. Suspend pauses input and output processing. It also restores the terminal settings to what they were when the application started. This can be used to, for example, run a sub-shell. Sync projects the current grid immediately. Tty returns the underlying Tty. If the screen is not a terminal, the returned bool will be false UnregisterRuneFallback unmaps a replacement. It will unmap the implicit ASCII replacements for alternate characters as well. When an unmapped char needs to be displayed, but no suitable glyph is available, '?' is emitted instead. It is not possible to "disable" the use of alternate characters that are supported by your terminal except by changing the terminal database. *ScreenMux : github.com/gdamore/tcell/v2.Screen *ScreenMux : github.com/gdamore/tcell/v2.SimulationScreen func NewScreenMux(ctx context.Context) (*ScreenMux, error)
Theme defines the default colors of the screen. Bg tcell.Color Cursor tcell.Color Fg tcell.Color func DefaultTheme() Theme
Package-Level Functions (total 4)
DefaultTheme is a dark theme.
NewScreen creates an initialized screen. The page lives as long as ctx; the returned screen disposes it on [Screen.Fini].
NewScreenMux creates an initialized multiplexer with a [DefaultCols] x [DefaultRows] core screen. It lives as long as ctx.
RunCmd serves cmd over HTTP using livepage. The command runs on a Unix PTY, so programs see a real terminal; its output is mirrored into a [Screen]. It blocks until the command exits or ctx is canceled.
Package-Level Constants (total 4)
DefaultCols and DefaultRows are the initial grid dimensions, used until the browser reports its viewport.
DefaultFontSize is the cell font size in CSS pixels.
const DefaultRows = 25
EnvLivepageChild marks the child process of the livepage bridge, which runs the regular TTY command on a PTY.