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
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.SimulationScreentcell.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.SimulationScreentcell.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)
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.
EnvLivepageChild marks the child process of the livepage bridge, which runs
the regular TTY command on a PTY.
The pages are generated with Goldsv0.8.7. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @zigo_101 (reachable from the left QR code) to get the latest news of Golds.