Documentation
¶
Overview ¶
Package text provides text rendering helper functions and an abstraction to create input text windows.
The DrawText rendering function included takes a window, font information and text and creates an image with the text written on it. The image is then painted to the window provided, and the window is resized to "snugly" fit the text. (Note that DrawText has a subtle bug that will manifest itself with large font sizes. Please see the bugs section.)
The other useful part of this package is the Input window type. It is an abstraction over xwindow.Window that provides an input box like window. The Input type's methods can then be used to easily add and remove text from the input box in response to KeyPress events. (You must write the KeyPress event handler.)
Here's a minimal example for creating an input window and allowing the user to type into it:
input := text.NewInput(XUtilValue, RootId, 500, 0, font, 20.0,
textColor, bgColor)
input.Listen(xproto.EventMaskKeyPress)
xevent.KeyPressFun(
func(X *xgbutil.XUtil, ev xevent.KeyPressEvent) {
if keybind.KeyMatch(X, "BackSpace", ev.State, ev.Detail) {
input.Remove()
} else {
input.Add(ev.State, ev.Detail)
}
}).Connect(X, input.Id)
Since the Input type embeds an xwindow.Window, it can be thought of as a regular window with special methods for handling text display.
Note that a slightly more involved and working example can be found in text/examples/input/main.go.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DrawText ¶
func DrawText(win *xwindow.Window, font *truetype.Font, size float64, fontClr, bgClr render.Color, text string) error
DrawText is a convenience function that will create a new image, render the provided text to it, paint the image to the provided window, and resize the window to fit the text snugly.
An error can occur when rendering the text to an image.
Types ¶
type Input ¶
Input encapsulates the information needed to construct and maintain an input window. The only exposed information is the Text field, in case you need to inspect it. Input values should *only* be made with the NewInput constructor.
func NewInput ¶
func NewInput(X *xgbutil.XUtil, parent xproto.Window, width int, padding int, font *truetype.Font, fontSize float64, fontColor, bgColor render.Color) *Input
NewInput constructs Input values. It needs an X connection, a parent window, the width of the input box, and theme information related for the font and background. Padding separating the text and the edges of the window may also be specified.
While NewInput returns an *Input, a Input value also has an xwindow.Window value embedded into it. Thus, an Input can also be treated as a normal window on which you can assign callbacks, close, destroy, etc.
As with all windows, the Input window should be destroyed when it is no longer in used.
func (*Input) Add ¶
Add will convert a (modifiers, keycode) tuple taken directly from a Key{Press,Release}Event to a single character string. Note that sometimes this conversion will fail. When it fails, a message will be logged and no text will be added.
Note that sometimes the conversion should fail (like when the Shift key is pressed), and other times it will fail because the xgbutil/keybind package provides inadequate support for keyboard encodings.
I suspect that languages other than English will completely fail here.
If a work-around is desperately needed, use AddLetter.
func (*Input) AddLetter ¶
AddLetter will add a single character to the input and re-render the input box. Note that the Add method is quite convenient and should be used when reading Key{Press,Release} events. If input is coming from somewhere else, or if Add is not working, resort to AddLetter.
func (*Input) Remove ¶
func (ti *Input) Remove()
Remove will remove the last character in the input box and re-render. If there are no characters in the input, Remove has no effect.
func (*Input) Render ¶
func (ti *Input) Render()
Render will redraw the background image, and write whatever text is in (*Input).Text to the image. No clean-up by the caller is necessary.
Render probably should not be called, unless you are manipulating (*Input).Text manually. Otherwise, it is preferrable to use the Add, Remove and Reset methods.
Notes ¶
Bugs ¶
I don't think freetype-go has a way to compute text extents before rendering text to an image. To work-around this, DrawText will over estimate the extents by assuming each character has a width equal to 1 em, and draw the text on an image with width = len(text) * pixels-per-em and a height = pixels-per-em. freetype-go then returns the point advanced by the drawn text, and this function uses it to take a sub-image of the image which is then drawn to the window. Unfortunately, this point doesn't reflect the true bounding box of the text (it cuts off the part of the text that dips below the base line). So to work-around this, the height of the extents is padded by a fixed pixel amount. This is wrong and will break if the font size is too large.
If `text` is zero-length, very bad things happen.
Source Files
Directories