dosktop

package module
v0.0.0-...-622b233 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 4, 2021 License: MIT Imports: 28 Imported by: 0

README

Build codecov Go Reference

Dosktop

Dosktop is a package which allow users to easily create rich text-based terminal applications and games. Dosktop differs from other terminal packages by providing an extremely simple API that abstracts out all low-level terminal operations, while avoiding complicated event-driven TUI designs.

Features

  • Straight forward BASIC-like API and syntax!
  • Access to an unlimited number of independent text layers, allowing for modal dialogs, windows, parallax scrolling, forgrounds, backgrounds, and more!
  • Automatic calculation of shadows and colored transparencies effects!
  • High level support for buttons, selection menus, lines, frames, and other TUI controls!
  • Full manual and automatic mouse support with TUI integration!
  • Dialog text printing with automatic word wrapping, typewriter effects, and dynamic style markup!
  • Virtual File System (ZIP & RAR) support, with password protection to ensure resource integrity!
  • Automatic conversion and rendering of bitmap images directly to text layers in ansi graphics!

Screenshots

Create windows and menus with full mouse support!

alt text

Ability to scale and draw bitmapped images directly to terminal with dialog printing!

alt text

Support for dynamic text layer transparencies!

alt text

Fully manipulable and independent text layers!

alt text

Project status

While Dosktop is currently being actively developed, it is at a point where practical use will determine further areas of usability, existing gaps, and deficiency improvements. If you like what this package has to offer, have ideas on how to improve it, or just want to experiment, consider giving Dosktop a try!

Future Roadmap

  • More examples and documentation. (see tests for basic examples)
  • More TUI controls (Progress bars, loading icons, etc).
  • Bulk addition of images and selections.
  • Saving and loading of terminal screenshots.
  • Fully text-based sprite system.
  • Digital audio and sound integration.

Documentation

Overview

Dosktop is a package which allow users to easily create rich text-based terminal applications and games. Dosktop differs from other terminal packages by providing an extremely simple API that abstracts out all low-level terminal operations, while avoiding complicated event-driven TUI designs.

The BASICs

If your familiar with programming on classical computers and OS environments like the Commodore 64 or MS-DOS, you will find that Dosktop behaves similar to these systems. Dosktop is a procedural package that gives users control over the terminal with simple BASIC-like commands. It maintains this simplicity by managing much of it's functionality and resources internally. While users do not need to keep track of these resources themselves, there are still a few concepts they need to be familiar with.

Aliases

Aliases are a way for a user to reference a resource in Dosktop without actually needing to manage and store it themselves. Things like creating a text layer, a button, or a timer, all use aliases to identify what the user creates and how they can reference that resource at a later time. For example: 

// Create a new text layer with the layer alias "Foreground", placed at
// screen location (0, 0), with a width and height of 20x20 characters,
// a zOrder drawing priority of 0, with no parent layer associated with it.
dosktop.AddLayer("Foreground", 0, 0, 20, 20, 0, "")

Once created, the user no longer needs to manage the resource. If they wish to manipulate it, they simply need to reference the Alias they want to access. For example: 

// Move the text layer with the alias "Foreground" to screen X and Y
// location (2, 2).
dosktop.MoveLayerByAbsoluteValue("Foreground", 2, 2)

Furthermore, an alias is always unique and distinct for any given resource. That means, while it is not recommended, it is possible to give two different types of resources the same alias name. For example: 

// Create a timer with the timer alias "MyAliasName", with a duration of
// 1000 milliseconds, with it's enabled status as being "true".
dosktop.AddTimer("Foreground", 1000, true)

Now we have a layer that has an alias called "Foreground" and a timer that has an alias called "Foreground".

Attribute Entries

Often when working with software, flexibility comes at the expense of simplicity. Having methods with dozens of options and parameters makes functionality more flexible, but also much more difficult to manage and understand. That's why to keep things simple, Dosktop uses Attribute Entries for configuring most customizable features. Attribute Entries are simply structures that hold all kinds of information about how the user would like for something to operate. By simply generating an entry, configuring it, and passing it in as a parameter, functionality will automatically know how to behave if one should want to do something outside the default. In addition, if you want a feature to behave differently under specific cases, you can configure multiple attribute entries and simply provide which one you need at any given time. For example: 

// Create a style entry which lets you configure most TUI related features.
styleEntry := dosktop.NewTuiStyleEntry()

// Configure the foreground color to use when rendering TUI buttons.
styleEntry.ButtonForegroundColor = dosktop.GetRGBColor(0, 255, 0)

// Add a button to a layer with the alias called "Foreground", with a
// button alias called "OkButton", with a button label of "OK", with
// our created style entry, with a layer location of (2,2), with
// a button width and height of 10x3 characters.
dosktop.AddButton("Foreground", "OkButton", "OK", styleEntry, 2, 2, 10, 3)

You will note that not all style attributes need to be set. Any attributes which are not modified will be left at their default settings. In addition, if you wish to quickly create multiple attribute entries based off a single one, you can simply do the following: 

// Create a new text style entry for printing text dialog messages.
defaultTextStyle := dosktop.NewTextStyleEntry()

// Configure some attributes for our new entry.
defaultTextStyle.ForegroundColor = dosktop.GetRGBColor(255, 0, 0)

// Create a new text style entry by cloning an existing style entry.
boldTextStyle := dosktop.NewTuiStyleEntry(defaultTextStyle)

// Set our new style to include the bold attribute
defaultTextStyle.isBold = true

As you can see, cloning attribute entries is a speedy way to configure multiple items with similar base settings.

Failing Fast

Almost all functionality in Dosktop is designed to perform consistently. That is, it will perform most tasks predictably without external runtime conditions changing its behaviour. As a result, when a problem occurs Dosktop will usually prefer to throw a Panic rather than choose an alternative solution or throw an error. This is because any problems encountered will generally be a developer issue and it should be addressed rather than covered up or hidden by default behaviour. For example: 

// Attempt to initialize Dosktop with a terminal size of (-1, 0)
dosktop.InitializeTerminal(-1, 0)

In this case, the user is attempting to create a terminal session with invalid dimensions. Rather than choose a sane default or return a recoverable error, Dosktop will panic since clearly the developer made an error and should correct it. For functionality that could vary depending on runtime conditions, errors will be returned as expected.

Double buffering

When updating the screen with with rapid changes or changes that may take a long time, it is desirable to wait until all drawing is completed before performing a refresh. This allows you to eliminate flickering, screen tearing, or other artifacts that may appear when display data is being updated at the same time as a screen refresh. In Dosktop, all changes to the terminal remain in memory until the user calls 'UpdateDisplay' to refresh the screen. This allows the user to make as many changes as they want before writing their changes to screen in a single pass.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AddButton 

func AddButton(layerAlias string, buttonAlias string, buttonLabel string, styleEntry memory.TuiStyleEntryType, xLocation int, yLocation int, width int, height int)

AddButton allows you to add a button to a text layer. The Style of the button will be determined by the style entry passed in. If you wish to remove a button from a text layer, simply call 'DeleteButton'. In addition, the following information should be noted:

- Buttons are not drawn physically to the text layer provided. Instead they are rendered to the terminal at the same time when the text layer is rendered. This allows you to create buttons without actually overwriting the text layer data under it.

- If the button to be drawn falls outside the range of the provided layer, then only the visible portion of the button will be drawn.

- If the width of your button is less than the length of your button label, then the width will automatically default to the width of your button label.

- If the height of your button is less than 3 characters high, then the height will automatically default to the minimum of 3 characters.

func AddLayer 

func AddLayer(layerAlias string, xLocation int, yLocation int, width int, height int, zOrderPriority int, parentAlias string)

AddLayer allows you to add a text layer to the current terminal display. You can add as many layers as you wish to suite your applications needs. Text layers are useful for setting up windows, modal dialogs, viewports, game foregrounds and backgrounds, and even effects like parallax scrolling. In addition, the following information should be noted:

- If you specify location for your layer that is outside the visible terminal display, then only the visible portion of your text layer will be rendered. Likewise, if your text layer is larger than the visible area of your terminal display, then only the visible portion of it will be displayed.

- If you pass in a zero or negative value for ether width or height a panic will be generated to fail as fast as possible.

- The z order priority controls which text layer should be drawn first and which text layer should be drawn last. Layers that have a higher priority will be drawn on top of layers that have a lower priority. In the event that two layers have the same priority, they will be drawn in random order. This is to ensure that programmers do not attempt to rely on any specific behavior that might be a coincidental side effect.

- The parent alias specifies which text layer is the parent of the one being created. Having a parent layer means that the child layer will only render on the parent and not the main terminal. This allows you to have text layers within text layers that can be moved or manipulated relative to the parent. If you pass in a value of "" for the parent alias, then no parent is used and the layer is rendered directly to the terminal display. This feature is useful for creating 'Window' effects where content is contained within something else.

- When adding a new text layer, it will become the default working text layer automatically. If you wish to set another text layer as your default, use 'Layer' to explicitly set it.

func AddTextStyle 

func AddTextStyle(textStyleAlias string, textStyleEntry memory.TextStyleEntryType)

AddTextStyle allows you to add a new printing style which can be used for writing dialog text with. Dialog text printing differs from regular printing, since it allows for "typewriter" drawing effects as well as changing text attributes on the fly (color, isBold, etc). In addition, the following information should be noted:

- This method expects you to pass in a 'textStyleEntry' type obtained by calling 'dosktop.NewTextStyle()'. This entry type contains all the options available for your text style and can be configured easily by setting each attribute accordingly.

func Clear 

func Clear()

Clear allows you to empty the default text layer of all its contents. If you wish to clear a text layer that is not currently set as the default, use 'ClearLayer' instead.

func ClearLayer 

func ClearLayer(layerAlias string)

Clear allows you to empty the specified text layer of all its contents. If you do not wish to specify a text layer, you can use the method 'Clear' which will simply clear the default text layer previously set.

func Color 

func Color(foregroundColorIndex int, backgroundColorIndex int)

Color allows you to set default colors on your text layer for printing with. The color index specified corresponds to the 16 color ANSI standard, where color 0 is Black and 15 is Bright White. If you wish to change colors settings for a text layer that is not currently set as your default, use 'ColorLayer' instead.

func ColorLayer 

func ColorLayer(layerAlias string, foregroundColorIndex int, backgroundColorIndex int)

ColorLayer allows you to set default colors on your specified text layer for printing with. The color index specified corresponds to the 16 color ANSI standard, where color 0 is Black and 15 is Bright White. If you do not wish to specify a text layer, you can use the method 'Color' which will simply change the color for the default text layer previously set.

func ColorLayerRGB 

func ColorLayerRGB(layerAlias string, foregroundRed int32, foregroundGreen int32, foregroundBlue int32, backgroundRed int32, backgroundGreen int32, backgroundBlue int32)

ColorLayerRGB allows you to set default colors on your specified text layer for printing with. This method allows you to specify colors using RGB color index values within the range of 0 to 255. If you do not wish to specify a text layer, you can use the method 'ColorRGB' which will simply change the color for the default text layer previously set.

func ColorRGB 

func ColorRGB(foregroundRedIndex int32, foregroundGreenIndex int32, foregroundBlueIndex int32, backgroundRedIndex int32, backgroundGreenIndex int32, backgroundBlueIndex int32)

ColorRGB allows you to set default colors on your text layer for printing with. This method allows you to specify colors using RGB color index values within the range of 0 to 255. If you wish to change colors settings for a text layer that is not currently set as your default, use 'ColorLayerRGB' instead.

func DeleteButton 

func DeleteButton(layerAlias string, buttonAlias string)

DeleteButton allows you to remove a button from a text layer. In addition, the following information should be noted:

- If you attempt to delete a button which does not exist, then the request will simply be ignored.

func DeleteLayer 

func DeleteLayer(layerAlias string)

DeleteLayer allows you to remove a text layer. If you wish to reuse a text layer for a future purpose, you may also consider making the layer invisible instead of deleting it. In addition, the following information should be noted:

- When a text layer is deleted, all child text layers are recursively deleted as well.

- If any dynamically drawn TUI controls reference the deleted layer, they will still be present. However, because the layer they were created for no longer exists, they will never be rendered. Consider removing any TUI controls before deleting the layer they reference. If you delete a layer that is referenced by dynamic TUI controls, creating a new layer with the same layer alias will allow them to be rendered again.

- If you attempt to delete a text layer which is currently set as your default text layer, then a panic will be generated in order to fail as fast as possible.

- If you attempt to delete a text layer that does not exist, then the operation will be ignored.

func DeleteTextStyle 

func DeleteTextStyle(textStyleAlias string)

DeleteTextStyle allows you to remove a text style that was added previously. In addition, the following information should be noted:

- If you attempt to delete an entry that does not exist, then no operation will be performed.

func DrawBar 

func DrawBar(layerAlias string, xLocation int, yLocation int, barLength int, fillCharacters string)

DrawBar allows you to draw a horizontal bar on a given text layer row. This is useful for drawing application headers or status bar footers.

func DrawBorder 

func DrawBorder(layerAlias string, styleEntry memory.TuiStyleEntryType, xLocation int, yLocation int, width int, height int)

DrawBorder allows you to draw a border on a given text layer. Borders differ from frames since they are flat shaded and do not have a raised or sunken look to them. In addition, the following information should be noted:

- If the border to be drawn falls outside the range of the specified layer, then only the visible portion of the border will be drawn.

func DrawFrame 

func DrawFrame(layerAlias string, styleEntry memory.TuiStyleEntryType, isRaised bool, xLocation int, yLocation int, width int, height int)

DrawFrame allows you to draw a frame on a given text layer. Frames differ from borders since borders are flat shaded and do not have a raised or sunken look to them. In addition, the following information should be noted:

- If the frame to be drawn falls outside the range of the specified layer, then only the visible portion of the frame will be drawn.

func DrawFrameLabel 

func DrawFrameLabel(layerAlias string, styleEntry memory.TuiStyleEntryType, label string, xLocation int, yLocation int)

DrawFrameLabel allows you to draw a label for a frame. The label will be automatically enclosed by the characters "[" and "]" to blend in with a border of a frame.

- If the frame label to be drawn falls outside the range of the specified layer, then only the visible portion of the border will be drawn.

func DrawHorizontalLine 

func DrawHorizontalLine(layerAlias string, styleEntry memory.TuiStyleEntryType, xLocation int, yLocation int, width int, isConnectorsDrawn bool)

DrawHorizontalLine allows you to draw a horizontal line on a text layer. This method also has the ability to draw connectors in case the line intersects with other lines that have already been drawn. In addition, the following information should be noted:

- If the the line to be drawn falls outside the area of the text layer specified, then only the visible portion of the line will be drawn.

func DrawImageToLayer 

func DrawImageToLayer(layerAlias string, imageAlias string, xLocation int, yLocation int, widthInCharacters int, heightInCharacters int, blurSigma float64)

DrawImageToLayer allows you to draw a loaded image to the specified layer. In addition, the following information should be noted:

- If the location specified falls outside the range for the layer, then only the visible portion of the image will be drawn.

- If you are drawing an image which has already been pre-rendered, then your width, height, and blur factor will be ignored.

- If you specify a value of 0 for ether the width or height, then that dimension will be automatically calculated to a value that best maintain the images aspect ratio. This is useful since it removes the need to calculate this manually.

- If you specify a value less than or equal to 0 for both the width and height, a panic will be generated to fail as fast as possible.

- When pre-rendering an image, it should be noted that each text cell assigned contains a top and bottom pixel. This is done to provide as much resolution as possible for your image. That means for a pre-rendered image with a size of 10x10 characters, the actual image being rendered would be 10x20 pixels tall. If the user wishes to maintain proper aspect ratios, they must manually select a height that appropriately compensates for this effect, or leave the height value as 0 to have it done automatically.

- The blur sigma controls how much blurring occurs after your image has been resized. This allows you to soften your image before it is rendered in ansi so that hard edges are removed. A value of 0.0 means no blurring will occur, with higher values increasing the blur factor.

func DrawLayerToScreen 

func DrawLayerToScreen(layerEntry *memory.LayerEntryType, isForcedRefreshRequired bool)

DrawLayerToScreen allows you to render a text layer to the visible terminal screen. If debug is enabled, this method does nothing since the terminal is virtual.

func DrawShadow 

func DrawShadow(layerAlias string, xLocation int, yLocation int, width int, height int, alphaValue float32)

DrawShadow allows you to draw shadows on a given text layer. Shadows are simply transparent areas which darken whatever text layers are underneath it by a specified degree. In addition, the following information should be noted:

- The alpha value can range from 0.0 (no shadow) to 1.0 (totally black).

func DrawVerticalLine 

func DrawVerticalLine(layerAlias string, styleEntry memory.TuiStyleEntryType, xLocation int, yLocation int, height int, isConnectorsDrawn bool)

DrawVerticalLine allows you to draw a vertical line on a text layer. This method also has the ability to draw connectors in case the line intersects with other lines that have already been drawn. In addition, the following information should be noted:

- If the the line to be drawn falls outside the area of the text layer specified, then only the visible portion of the line will be drawn.

func DrawVerticalMenu 

func DrawVerticalMenu(layerAlias string, styleEntry memory.TuiStyleEntryType, selectionEntry memory.SelectionEntryType, xLocation int, yLocation int, menuWidth int, menuHeight int, viewportPosition int, itemSelected int)

DrawVerticalMenu allows you to obtain a user selection from a horizontal menu. In addition, the following information should be noted:

- If the location to draw a menu item falls outside of the range of the text layer, then only the visible portion of your menu item will be drawn.

- The viewport position represents the first menu item that needs to be drawn. This is useful for menus sizes which are significantly larger than the visible display area allocated for the menu.

func DrawWindow 

func DrawWindow(layerAlias string, styleEntry memory.TuiStyleEntryType, xLocation int, yLocation int, width int, height int)

DrawWindow allows you to draw a window on a given text layer. Windows differ from borders since the entire area the window surrounds gets filled with a solid background color. In addition, the following information should be noted:

- If the window to be drawn falls outside the range of the specified layer, then only the visible portion of the window will be drawn.

func FillArea 

func FillArea(layerAlias string, fillCharacters string, xLocation int, yLocation int, width int, height int)

FillArea allows you to fill an area of a given text layer with characters of your choice. If you wish to fill the area with repeating text, simply provide the string you wish to repeat. In addition, the following information should be noted:

- If the area to fill falls outside the range of the specified layer, then only the visible portion of the fill will be drawn.

func FillLayer 

func FillLayer(layerAlias string, fillCharacters string)

FillLayer allows you to fill an entire layer with characters of your choice. If you wish to fill the layer with repeating text, simply provide the string you wish to repeat.

func GetCellIdUnderMouseLocation 

func GetCellIdUnderMouseLocation(layerAlias string) int

GetCellIdUnderMouseLocation allows you to obtain the cell ID for the text directly under your mouse cursor. This is useful for tracking elements on a screen, creating "hot spots", or interactive zones which you want the user to interact with. In addition, the following information should be noted:

- If multiple text layers are being displayed, the cell ID returned will be from the top-most visible text cell.

- The cell ID returned will only reflect what is currently being displayed on the terminal display. If you wish for any new changes to take effect, call 'UpdateDisplay' to refresh the visible display area first.

func GetColor 

func GetColor(colorIndex int) int32

GetColor allows you to obtain an RGB color from a predefined color palette list. This list corresponds to the 16 color ANSI standard, where color 0 is Black and 15 is Bright White. In addition, the following information should be noted:

- If you specify a color index less than 0 or greater than 15 a panic will be generated to fail as fast as possible.

func GetCurrentTimeInMilliseconds 

func GetCurrentTimeInMilliseconds() int64

GetCurrentTimeInMilliseconds allows you to get the current epoch time in milliseconds.

func GetDarkenedCharacterEntry 

func GetDarkenedCharacterEntry(characterEntry *memory.CharacterEntryType, alphaValue float32) memory.CharacterEntryType

fillLayer allows you to fill an entire layer with characters of your choice. If you wish to fill the layer with repeating text, simply provide the string you wish to repeat.

func GetDarkenedColor 

func GetDarkenedColor(color int32, percentChange float32) int32

GetDarkenedColor allows you to obtain a color that has been darkened uniformly by a specific amount. In addition, the following information should be noted:

- The percent change can range from 0.0 (totally dark) to 1.0 (no difference).

- If you pass in a percent change of less than 0.0 or greater than 1.0, a panic will be generated to fail as fast as possible.

func GetInput 

func GetInput(layerAlias string, styleEntry memory.TuiStyleEntryType, xLocation int, yLocation int, width int, maxLengthAllowed int, IsPasswordProtected bool, defaultValue string) string

GetInput allows you to obtain keyboard input from the user. This is useful for letting applications accept configurations, settings, or other options in an interactive way at runtime. In addition, the following information should be noted:

- If the location specified for the input field falls outside of the range of the text layer, then only the visible portion of your input field will be drawn.

- If the max length of your input field is less than or equal to 0, a panic will be generated to fail as fast as possible.

- Password protection will echo back '*' characters to the terminal instead of the actual characters entered.

- Specifying a default value will simply pre-populate the input field with the value specified.

- If the cursor position moves outside of the visible display area of the field, then the entire input field will shift to ensure the cursor is always visible.

func GetRGBColor 

func GetRGBColor(redColorIndex int32, greenColorIndex int32, blueColorIndex int32) int32

GetRGBColor allows you to obtain a specific RGB color based on the red, green, and blue index values provided. In addition, the following information should be noted:

- If you specify a color channel index less than 0 or greater than 255 a panic will be generated to fail as fast as possible.

func GetRGBColorComponents 

func GetRGBColorComponents(color int32) (int32, int32, int32)

GetRGBColorComponents allows you to obtain RGB color component indexes for red, green, an blue color channels.

func GetScrambledPassword 

func GetScrambledPassword(password string, scrambleKey string) string

GetScrambledPassword allows you to scramble a password with a simple XOR algorithm. This allows a user to provide a password for a virtual file system without having to store it in their own program as plaintext. To use this feature, simply pass in your desired password and scramble key to obtain your encoded password. This password can then be used to mount a virtual file system provided you use the same scramble key to decode it. In addition, the following information should be noted:

- This method is not designed for cryptographic security. It is simply a method of transposing a password so that it is not viewable in plaintext. While this can prevent casual users from extracting a password hardcoded into a binary executable, it will not prevent a determined user from obtaining it.

- The length and randomness of your 'password' will directly influence the usefulness of your chosen 'scrambleKey'. Consider using a long and random password if you want maximum effectiveness.

func GetSelectionFromHorizontalMenu 

func GetSelectionFromHorizontalMenu(layerAlias string, styleEntry memory.TuiStyleEntryType, selectionEntry memory.SelectionEntryType, xLocation int, yLocation int, defaultItemSelected int) string

GetSelectionFromHorizontalMenu allows you to obtain a user selection from a horizontal menu. This is different from a proportional menu since all menu items are drawn to the size of the current selection. If you want each menu item to be of equal width, consider using 'GetSelectionFromProportionalHorizontalMenu' instead. In addition, the following information should be noted:

- If the location to draw a menu item falls outside of the range of the text layer, then only the visible portion of your menu item will be drawn.

- The returned value is the selection alias for the item that was chosen.

func GetSelectionFromHorizontalMenuByIndex 

func GetSelectionFromHorizontalMenuByIndex(layerAlias string, styleEntry memory.TuiStyleEntryType, selectionEntry memory.SelectionEntryType, xLocation int, yLocation int, defaultItemSelected int) int

GetSelectionFromHorizontalMenuByIndex allows you to obtain a user selection from a horizontal menu. This is different from a proportional menu since all menu items are drawn to the size of the current selection. If you want each menu item to be of equal width, consider using 'GetSelectionFromProportionalHorizontalMenuByIndex' instead. In addition, the following information should be noted:

- If the location to draw a menu item falls outside of the range of the text layer, then only the visible portion of your menu item will be drawn.

- The returned value is the index number of your selection, where 0 is the first item on your selection list.

func GetSelectionFromProportionalHorizontalMenu 

func GetSelectionFromProportionalHorizontalMenu(layerAlias string, styleEntry memory.TuiStyleEntryType, selectionEntry memory.SelectionEntryType, xLocation int, yLocation int, menuWidth int, numberOfItemsOnRow int, defaultItemSelected int) string

GetSelectionFromProportionalHorizontalMenu allows you to obtain a user selection from a proportional horizontal menu. This differs from a regular menu since all menu selections are evenly spaced out. If you would like to have menu items match the size of the selection, use 'GetSelectionFromHorizontalMenu' instead. In addition, the following information should be noted:

- If the location to draw a menu item falls outside of the range of the text layer, then only the visible portion of your menu item will be drawn.

- The returned value is the selection alias for the item that was chosen.

func GetSelectionFromProportionalHorizontalMenuByIndex 

func GetSelectionFromProportionalHorizontalMenuByIndex(layerAlias string, styleEntry memory.TuiStyleEntryType, selectionEntry memory.SelectionEntryType, xLocation int, yLocation int, menuWidth int, numberOfItemsOnRow int, defaultItemSelected int) int

GetSelectionFromProportionalHorizontalMenuByIndex allows you to obtain a user selection from a proportional horizontal menu. If you would like to have menu items match the size of the selection, use 'GetSelectionFromHorizontalMenuByIndex' instead. In addition, the following information should be noted:

- If the location to draw a menu item falls outside of the range of the text layer, then only the visible portion of your menu item will be drawn.

- The returned value is the index number of your selection, where 0 is the first item on your selection list.

func GetSelectionFromVerticalMenu 

func GetSelectionFromVerticalMenu(layerAlias string, styleEntry memory.TuiStyleEntryType, selectionEntry memory.SelectionEntryType, xLocation int, yLocation int, menuWidth int, menuHeight int, defaultItemSelected int) string

GetSelectionFromVerticalMenu allows you to obtain a user selection from a vertical menu. In addition, the following information should be noted:

- If the location to draw a menu item falls outside of the range of the text layer, then only the visible portion of your menu item will be drawn.

- The returned value is the selection alias for the item that was chosen.

func GetSelectionFromVerticalMenuByIndex 

func GetSelectionFromVerticalMenuByIndex(layerAlias string, styleEntry memory.TuiStyleEntryType, selectionEntry memory.SelectionEntryType, xLocation int, yLocation int, menuWidth int, menuHeight int, defaultItemSelected int) int

GetSelectionFromVerticalMenuByIndex allows you to obtain a user selection from a vertical menu. In addition, the following information should be noted:

- If the location to draw a menu item falls outside of the range of the text layer, then only the visible portion of your menu item will be drawn.

- The returned value is the index number of your selection, where 0 is the first item on your selection list.

func GetTransitionedColor 

func GetTransitionedColor(sourceColor int32, targetColor int32, percentChange float32) int32

GetTransitionedColor allows you to obtain a color that has been transitioned to another color by a specific percent. For example, if your source color is red (255, 0, 0) and your target color is green (0, 255, 0), transitioning by 0.5 (fifty percent) will yield the color (128, 128, 0). In addition, the following information should be noted:

- If your percent change yields color indexes which are not evenly divisible, then the color index will be rounded up or down to the nearest whole number. For example: 50% of color index 255 would yield the color index 128.

- If you pass in a percent change of less than 0.0 or greater than 1.0, you are simply specifying that you want to transition the color greater than 100%. For example, a value of 1.2 would mean you want to transition to 120% of the target color, and a value of -0.2 would mean you want to transition to -20% of the target color.

- If the resultant transitioned color falls outside of the RGB range of Black (0, 0, 0) or White (255, 255, 255), it will be defaulted to closest valid color.

func InitializeTerminal 

func InitializeTerminal(width int, height int)

InitializeTerminal allows you to initialize Dosktop for the first time. This method must be called first before any operations take place. The parameters 'width' and 'height' represent the display size of the terminal instance you wish to create. In addition, the following information should be noted:

- If you pass in a zero or negative value for ether width or height a panic will be generated to fail as fast as possible.

func Inkey 

func Inkey() string

Inkey allows you to read keyboard input from the user's terminal. This method returns the character pressed or a keyword representing the special key pressed (For example: 'a', 'A', 'escape', 'f10', etc.). In addition, the following information should be noted:

- If more than one keystroke is recorded, it is stored sequentially in the input buffer and this method needs to be called repeatedly in order to read them.

func IsTimerExpired 

func IsTimerExpired(timerAlias string) bool

IsTimerExpired allows you to check if a created timer has expired or not. If the specified timer has expired, then it will automatically be disabled. In order to activate the timer again, simply call 'StartTimer'.

func Layer 

func Layer(layerAlias string)

Layer allows you to specify a default layer alias that you wish to use when interacting with methods which have a non-layer alias method signature. Non-layer alias method signatures can be identified by finding methods which have both a layer and non-layer version. This makes interacting with methods faster, as the user does not need to provide the layer alias context in which he is working on. For example: 

// On the layer with a layer alias of "MyForegreoundLayer" print a string.
dosktop.PrintLayer("MyForegroundLayer", "Hello World")

// Set the default layer alias to be "MyForegroundLayer".
dosktop.Layer("MyForegroundLayer")

// Since we set the default layer, we don't need to call the method
// PrintLayer anymore. Instead, we can use the shorter method Print.
dosktop.Print("Hello World")

func LoadBase64Image 

func LoadBase64Image(imageDataAsBase64 string, imageAlias string) error

LoadBase64Image allows you to load a base64 encoded image into memory without performing any ansi conversions ahead of time. This takes up more memory for larger images but allows you to render those images at arbitrary resolutions. For example, loading a large image to retain detail and dynamically rendering that image later depending on the available terminal resolution detected. Since base64 encoded images can be stored in strings, they are ideal for directly embedding them into applications.

func LoadImage 

func LoadImage(imageFile string, imageAlias string) error

LoadImage allows you to load an image into memory without performing any ansi conversions ahead of time. This takes up more memory for larger images but allows you to render those images at arbitrary resolutions. For example, loading a large image to retain detail and dynamically rendering that image later depending on the available terminal resolution detected.

func LoadImagesInBulk 

func LoadImagesInBulk(assetList memory.AssetListType) error

LoadImagesInBulk allows you to load multiple images into memory at once. This is useful since it eliminates the need for error checking over each image as they are loaded. An example use of this method is as follows: 

// Create a new asset list.
assetList := dosktop.NewAssetList()
// Add an image file to our asset list, with a filename of 'MyImageFile'
// and an image alias of 'MyImageAlias'.
assetList.AddImage("MyImageFile", "MyImageAlias")
// Load the list of images into memory.
err := dosktop.LoadImagesInBulk(assetList)

In addition, the following information should be noted:

- This method works by reading in the provided asset list and then calling 'LoadImage' accordingly each time. For more information about the loading of images, please see 'LoadImage' for more details.

- In the event an error occurs, it will be returned to the user immediately and further loading will stop.

func LoadPreRenderedBase64Image 

func LoadPreRenderedBase64Image(imageDataAsBase64 string, imageAlias string, widthInCharacters int, heightInCharacters int, blurSigma float64) error

LoadPreRenderedBase64Image allows you to pre-render an image before loading it into memory. This enables you to save memory by rendering larger images ahead of time instead of storing the image data for later use. For example, you can take a large image and pre-render it at a much lower resolution suitable for the terminal. Since base64 encoded images can be stored in strings, they are ideal for directly embedding them into applications. In addition, the following information should be noted:

- If you load a pre-rendered image, you are not able to draw them dynamically at various resolutions. The image can only be drawn with the settings specified at load time.

- If you specify a value of 0 for ether the width or height, then that dimension will be automatically calculated to a value that best maintain the images aspect ratio. This is useful since it removes the need to calculate this manually.

- If you specify a value less than or equal to 0 for both the width and height, a panic will be generated to fail as fast as possible.

- When pre-rendering an image, it should be noted that each text cell assigned contains a top and bottom pixel. This is done to provide as much resolution as possible for your image. That means for a pre-rendered image with a size of 10x10 characters, the actual image being rendered would be 10x20 pixels tall. If the user wishes to maintain proper aspect ratios, they must manually select a height that appropriately compensates for this effect, or leave the height value as 0 to have it done automatically.

- The blur sigma controls how much blurring occurs after your image has been resized. This allows you to soften your image before it is rendered in ansi so that hard edges are removed. A value of 0.0 means no blurring will occur, with higher values increasing the blur factor.

func LoadPreRenderedImage 

func LoadPreRenderedImage(imageFile string, imageAlias string, widthInCharacters int, heightInCharacters int, blurSigma float64) error

LoadPreRenderedImage allows you to pre-render an image before loading it into memory. This enables you to save memory by rendering larger images ahead of time instead of storing the image data for later use. For example, you can take a large image and pre-render it at a much lower resolution suitable for the terminal. In addition, the following information should be noted:

- If you load a pre-rendered image, you are not able to draw them dynamically at various resolutions. The image can only be drawn with the settings specified at load time.

- If you specify a value of 0 for ether the width or height, then that dimension will be automatically calculated to a value that best maintain the images aspect ratio.

- If you specify a value less than or equal to 0 for both the width and height, a panic will be generated to fail as fast as possible.

- When pre-rendering an image, it should be noted that each text cell assigned contains a top and bottom pixel. This is done to provide as much resolution as possible for your image. That means for a pre-rendered image with a size of 10x10 characters, the actual image being rendered would be 10x20 pixels tall. If the user wishes to maintain proper aspect ratios, they must manually select a height that appropriately compensates for this effect, or leave the height value as 0 to have it done automatically.

- The blur sigma controls how much blurring occurs after your image has been resized. This allows you to soften your image before it is rendered in ansi so that hard edges are removed. A value of 0.0 means no blurring will occur, with higher values increasing the blur factor.

func Locate 

func Locate(xLocation int, yLocation int)

Locate allows you to set the default cursor location on your specified text layer for printing with. This is useful for when you wish to print text at different locations of your text layer at any given time. If you wish to change the cursor location for a text layer that is not currently set as your default, use 'LocateLayer' instead. In addition, the following information should be noted:

- If you pass in a location value that falls outside the dimensions of the default text layer, a panic will be generated to fail as fast as possible.

- Valid text layer locations start at position (0,0) for the upper left corner. Since location values do not start at (1,1), valid end positions for the bottom right corner will be one less than the text layer width and height. For example: 

// Create a new text layer with the alias "ForegroundLayer", at location
// (0,0), with a width and height of 15x15, a z order priority of 1,
// and no parent layer associated with it.
dosktop.AddLayer("ForegroundLayer", 0, 0, 15, 15, 1, "")
// Set the text layer with the alias "ForegroundLayer" as our default.
dosktop.Layer("ForegroundLayer")
// Move our cursor location to the bottom right corner of our text layer.
dosktop.Locate(14, 14)

func LocateLayer 

func LocateLayer(layerAlias string, xLocation int, yLocation int)

Locate allows you to set the default cursor location on your specified text layer for printing with. This is useful for when you wish to print text at different locations of your text layer at any given time. If you do not wish to specify a text layer, you can use the method 'Locate' which will simply change the cursor location for the default text layer previously set. In addition, the following information should be noted:

- If you pass in a location value that falls outside the dimensions of the specified text layer, a panic will be generated to fail as fast as possible.

- Valid text layer locations start at position (0,0) for the upper left corner. Since location values do not start at (1,1), valid end positions for the bottom right corner will be one less than the text layer width and height. For example: 

// Create a new text layer with the alias "ForegroundLayer", at location
// (0,0), with a width and height of 15x15, a z order priority of 1,
// and no parent layer associated with it.
dosktop.AddLayer("ForegroundLayer", 0, 0, 15, 15, 1, "")
// Move our cursor location to the bottom right corner of our text layer.
dosktop.LocateLayer(14, 14)

func MoveLayerByAbsoluteValue 

func MoveLayerByAbsoluteValue(layerAlias string, xLocation int, yLocation int)

MoveLayerByAbsoluteValue allows you to move a text layer by an absolute value. This is useful if you know exactly what position you wish to move your text layer to. In addition, the following information should be noted:

- If you move your layer outside the visible terminal display, only the visible display area will be rendered. Likewise, if your text layer is a child of a parent layer, then only the visible display area will be rendered on the parent.

func MoveLayerByRelativeValue 

func MoveLayerByRelativeValue(layerAlias string, xLocation int, yLocation int)

MoveLayerByRelativeValue allows you to move a text layer by a relative value. This is useful for windows, foregrounds, backgrounds, or any kind of animations or movement you may wish to do in increments. For example: 

// Move the text layer with the alias "ForegroundLayer" one character to
// the left and two characters down from its current location.
dosktop.MoveLayerByRelativeValue("ForegroundLayer", -1, 2)

In addition, the following information should be noted:

- If you move your layer outside the visible terminal display, only the visible display area will be rendered. Likewise, if your text layer is a child of a parent layer, then only the visible display area will be rendered on the parent.

func NewAssetList 

func NewAssetList() memory.AssetListType

NewAssetList allows you to obtain a list for storing asset information with. This is useful for loading assets in bulk since you can specify asset information as a collection instead of each one individually. An example use of this method is as follows: 

// Create a new asset list.
assetList := dosktop.NewAssetList()
// Add an image file with the image filename 'MyImageFile', and image
// alias of 'MyImageAlias'.
assetList.AddImage("MyImageFile", "MyImageAlias")
// Load the list of images into memory.
err := loadImagesInBulk(assetList)

In addition, the following information should be noted:

- An asset list can contain multiple asset types. This allows the same asset list to be shared by multiple methods that load different kinds of assets.

func NewSelectionEntry 

func NewSelectionEntry() memory.SelectionEntryType

NewSelectionEntry allows you to obtain an entry used for specifying what options you want to make available for a given menu prompt. For example: 

// Create a new TUI style entry with default settings.
tuiStyleEntry := dosktop.NewTuiStyleEntry()
// Create a new selection entry to populate our menu entries with.
selectionEntry := dosktop.NewSelectionEntry()
// Add a selection with the alias "Opt1" and a display value of "OK".
selectionEntry.Add("Opt1", "OK")
// Add a selection with the alias "Opt2" with the display value of "CANCEL".
selectionEntry.Add("Opt2", "CANCEL")
// Prompt the user with a vertical selection menu, on the text layer
// with the alias "ForegroundLayer", using a default TUI style entry,
// a selection entry with two options, at the layer location (0, 0),
// with a menu width and height of 15x15 characters.
selectionMade := dosktop.GetSelectionFromVerticalMenu ("ForegroundLayer", tuiStyleEntry, selectionEntry, 0, 0, 15, 15)

func NewTextStyle 

func NewTextStyle() memory.TextStyleEntryType

NewTextStyle allows you to obtain a new text style entry which can be used when printing dialog text. By configuring attributes for your text style entry and adding your entry to Dosktop, simple markup commands can be used to switch between dialog printing styles automatically. For example: 

// Create a new text style entry to configure.
myTextStyleEntry := dosktop.NewTextStyle()
// Configure your text style so that the foreground color is red.
myTextStyleEntry.ForegroundColor = dosktop.GetRGBColor(255, 0, 0)
// Add a new text style called "RedColor".
dosktop.AddTextStyle("RedColor", myTextStyleEntry)

func NewTuiStyleEntry 

func NewTuiStyleEntry() memory.TuiStyleEntryType

NewTuiStyleEntry allows you to obtain a new style entry which can be used for specifying how TUI controls and other TUI drawing operations should occur. For example: 

// Create a new TUI style entry to configure.
myTuiStyleEntry := dosktop.NewTuiStyleEntry()
// Configure the style entry so that the upper left corner character
// for drawing a window is the '╔' character. Here we use '\u' to
// denote the specific byte value in our code since not all editors may
// know how to display the actual character.
myTuiStyleEntry.UpperLeftCorner = '\u2554'
// Draw a window on the text layer with the alias of "ForegroundLayer",
// using the TUI style entry "myTuiStyleEntry", at layer location (0, 0),
// with a width and height of 10x10 characters.
dosktop.DrawWindow("ForegroundLayer", myTuiStyleEntry, 0, 0, 10, 10)

func Print 

func Print(textToPrint string)

Print allows you to write text to the default text layer. If you wish to print to a text layer that is not currently set as the default, use 'PrintLayer' instead. In addition, the following information should be noted:

- When text is written to the text layer, the cursor position is also updated to reflect its new location. Like a typewriter, the cursor position moves to the start of the next line after each print statement.

- If the string to print ends up being too long to fit at its current location, then only the visible portion of your string will be printed.

- If printing has not yet finished and there are no available lines left, then all remaining characters will be discarded and printing will stop.

func PrintDialog 

func PrintDialog(layerAlias string, xLocation int, yLocation int, widthOfLineInCharacters int, printDelayInMilliseconds int, isSkipable bool, stringToPrint string)

PrintDialog allows you to write text immediately to the terminal screen via a typewriter effect. This is useful for video games or other applications that may require printing text in a dialog box. In addition, the following information should be noted:

- If you specify a print location outside the range of your specified text layer, a panic will be generated to fail as fast as possible.

- If printing has reached the last line of your text layer, printing will not advance to the next line. Instead, it will resume and overwrite what was already printed on the same line.

- Specifying the width of your text line allows you to control when text wrapping occurs. For example, if printing starts at location (2, 2) and you set a line width of 10 characters, text wrapping will occur when the printing exceeds the text layer location (12, 2). When this happens, text will continue to print underneath the previous line at (2, 3).

- When a word is too long to be printed on a text layer line, or the width of your line has already exceed its allowed maximum, the word will be pushed to the line directly under it. This prevents words from being split across two lines.

- When specifying a printing delay, the amount of time to wait is inserted between each character printed and does not reflect the overall time to print your specified text.

- If the dialog being printed is flagged as skipable, the user can speed up printing by pressing the 'enter' key or right mouse button. Otherwise, they must wait for the animation to completely finish before execution continues.

- This method supports the use of text styles during printing to add color or styles to specific words in your string. All text styles must be enclosed around the "{" and "}" characters. If you wish to use the default text style, simply omit specifying any text style between your enclosing braces. For example: 

// Add a text layer with the alias "ForegroundLayer", at location (0, 0),
// with a width and height of 80x20 characters, z order priority of 1,
// with no parent layer.
dosktop.AddLayer("ForegroundLayer", 0, 0, 80, 20, 1, "")
// Obtain a new text style entry.
redTextStyle := dosktop.GetTextStyle()
// Change the default foreground color of our text style to be red.
redTextStyle.ForegroundColor = dosktop.GetRGBColor(255,0,0)
// Register our new text style so Dosktop can use it.
dosktop.AddTextStyle("red", redTextStyle)
// Print some dialog text on the text layer "ForegroundLayer", at location
// (0, 0), with a text wrapping location at 30 characters, a 10 millisecond
// delay between each character printed, and mark the dialog as skipable.
// Inside our string to print, we add the "{red}" tag to switch printing
// styles on the fly to "red" and change back to the default style using
// "{}".
dosktop.PrintDialog("ForegroundLayer", 0, 0, 30, 10, true, "This is some dialog text in {red}red color{}. Only the words 'red color' should be colored.")

func PrintLayer 

func PrintLayer(layerAlias string, textToPrint string)

PrintLayer allows you to write text to a specified text layer. If you do not wish to specify a text layer, you can use the method 'Print' which will simply print to the default text layer previously set. In addition, the following information should be noted:

- When text is written to the text layer, the cursor position is also updated to reflect its new location. Like a typewriter, the cursor position moves to the start of the next line after each print statement.

- If the string to print ends up being too long to fit at its current location, then only the visible portion of your string will be printed.

- If printing has not yet finished and there are no available lines left, then all remaining characters will be discarded and printing will stop.

func RestoreTerminalSettings 

func RestoreTerminalSettings()

RestoreTerminalSettings allows the user to gracefully return the terminal back to its normal settings. This should be called once your application is finished using Dosktop so that the users terminal environment is not left in a bad state.

func SetAlpha 

func SetAlpha(layerAlias string, alphaValue float32)

SetAlpha allows you to set the alpha value for a given text layer. This lets you perform pseudo transparencies by making the layer foreground and background colors blend with the layers underneath it to the degree specified. In addition, the following information should be noted:

- An alpha value of 1.0 is equal to 100% visible, while an alpha value of 0.0 is 0% visible. Specifying a value outside this range indicates that you want to over amplify or under amplify the color transparency effect.

- If the percent change specified is outside of the RGB color range (for example, if you specified 200%), then the color will simply bottom or max out at RGB(0, 0, 0) or RGB(255, 255, 255) respectively.

func SetTimer 

func SetTimer(timerAlias string, durationInMilliseconds int64, isEnabled bool)

SetTimer allows you to create a new timer to measure time with. If the timer is not enabled by default, you must call 'StartTimer' when you wish for it to begin.

func Sleep 

func Sleep(timeInMilliseconds uint)

Sleep allows you to pause execution for a given amount of milliseconds. This method is simply a convenient wrapper for the method 'SleepInMilliseconds'.

func SleepInMilliseconds 

func SleepInMilliseconds(timeInMilliseconds uint)

SleepInMilliseconds allows you to pause execution for a given amount of milliseconds.

func SleepInSeconds 

func SleepInSeconds(timeInSeconds uint)

SleepInSeconds allows you to pause execution for a given amount of seconds.

func StartTimer 

func StartTimer(timerAlias string)

StartTimer allows you to start a timer that has already been previously created. In addition, the following information should be noted:

- If you specify a timer that does not exist, then a panic will be generated to fail as fast as possible.

func UnloadImage 

func UnloadImage(imageAlias string)

UnloadImage allows you to remove an image from memory. Since images can take up a large amount of space, it is recommended to unload images any time you are done working with them. However, you may consider retaining images if they are frequently used and repeatedly loading them would be less effective. In addition, the following information should be noted:

- If you pass in an image alias that does not exist, then the delete operation will be ignored.

func UnmountVirtualFileSystem 

func UnmountVirtualFileSystem()

UnmountVirtualFileSystem allows you to reset the virtual file system to an unmounted state. This is useful for when you want to access the physical file system directly.

func UpdateDisplay 

func UpdateDisplay()

UpdateDisplay allows you to synchronize the terminals visible display area with your current changes. In addition, the following information should be noted:

- All text layers are sorted from lowest to highest z order priority level.

- Layers with the same z order priority will appear in random display order. This is to ensure that programmers do not attempt to rely on any specific behavior that might be a coincidental side effect.

Types

This section is empty.

Source Files

View all Source files

Directories

Path Synopsis
constant module
internal
math
memory
recast
stringformat

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.