slope/guiStatic.go

//+build gui all

package main

const guiIsOn = true

var guiUsageStrings = map[string]string{
	"dialog-error":          "(dialog-error [gui-root] [window-name: string] [error: string]) => ()\n\nShows an error message. The dialog that is opened is not a system native dialog and will be constrained by the window size",
	"dialog-info":           "(dialog-info [gui-root] [window-name: string] [title: string] [message: string]) => ()\n\nShows an information window with the given title and message. The dialog that is opened is not a system native dialog and will be constrained by the window size",
	"dialog-open-file":      "(dialog-open-file [app: gui-root] [window-name: string] [callback: lambda]) => ()\n\nCreates an 'open file' dialog. The given lambda should take one argument, a string representing the selected file path. The dialog that is opened is not a system native dialog and will be constrained by the window size",
	"dialog-save-file":      "(dialog-save-file [app: gui-root] [window-name: string] [callback: lambda]) => ()\n\nCreates an 'save file' dialog. The given lambda should take one argument, a string representing the selected file path. The dialog that is opened is not a system native dialog and will be constrained by the window size",
	"container":             "(container [layout: string] [[columns: number]] [contents: gui-widget|container...])\n\n`container` is the basic layout unit of the slope gui system. It can hold any number of other widgets or containers. The columns value is shown as optional, despite having a mandatory value after it, because it is only available for the `grid` layout. Do not pass `columns` for any other layout. The available layout strings are:\n\n\tnone - No layout\n\n\thbox - arranges items in a horizontal row. Every element will have the same height (the height of the tallest item in the container) and objects will be left-aligned at their minimum width\n\n\tvbox - arranges items in a vertical column. Every element will have the same width (the width of the widest item in the container) and objects will be top-aligned at their minimum height\n\n\tform - arranges items in pairs where the first column is at minimum width. This is normally useful for labelling elements in a form, where the label is in the first column and the item it describes is in the second. You should always add an even number of elements to a form layout\n\n\tgrid - positions elements into the given number of columns from left to right top to bottom. All grid elements will be evenly sized\n\n\tcenter - positions all container elements in the center of the container. Every object will be set to it’s minimum size\n\n\tmax - positions all container elements to fill the available space. The objects will all be full-sized and drawn in the order they were added to the container (last-most is on top)\n\n\tpadded - positions all container elements to fill the available space but with a small padding around the outside. The size of the padding is theme specific. The objects will all be drawn in the order they were added to the container (last-most is on top)\n\n\tborder - must have at least four objects passed to it to fulfill the following: top, bottom, left, right (in that order). Any further objects will fill the center space and will stretch to fit. If you do not wish to have a top, bottom, left, or right you may pass `#f` for one of these values. The border container padds the bordered sections from the center content\n\n\tvsplit - creates a resizable vertical split between two widgets/containers\n\n\thsplit - creates a resizable horizontal split between two widgets/containers",
	"container-add-to":      "(container-add-to [parent: gui-container] [child: gui-widget|gui-container]) => #t\n\nAdds the given child widget/container to the given parent container",
	"container-scroll":      "(container-scroll [gui-container]) => gui-container\n\nTakes a single, unlike the other containers, container (which can in turn contain widgets or other containers). The minimum size of the container it is passed will be ignored and scroll bars will be added as needed. Note that since `container-scroll` does not accept more than one `gui-container` a call to `container-add-to` targeting a container generated by `container-scroll` will result in a runtime panic",
	"container-size":        "(container-size [gui-container]) => list\n\nReturns a two item list containing the given gui-container's width and height (in that order)",
	"gui-add-shortcut":      "(gui-add-shortcut [gui-root] [window-name: string] [callback: lambda] [key: string] [modifier: string]) => #t\n\nAdds a shortcut to the window. Any time the two given keys are pressed the lambda will be called with no arguments. The valid modifiers are (not case sensitive and various alternate abbreviations/spellings):\n\n\t- `ctrl`\n\t- `shift`\n\t- `alt`\n\t- `super`\n\nThe available key strings are given in CamelCase with the first character always capitalized. A set of examples are: `F1`, `Left`, `Down`, `Tab`, `Q`, `C`, `BackSpace`, `Home`. Note that single characters are always uppercase for purposes of providing a key to this procedure.",
	"gui-add-window":        "(gui-add-window [app: gui-root] [name: string])\n\nAdds a window to the given gui-root as returned by `gui-create`. Name will be used to refer to the newly created window in other procedures. A string is prefered and called for in the procedure signature, but any other value can be used and will be stringified",
	"gui-create":            "(gui-create) => gui-root\n\nCreates the application root for a gui application. See: `gui-add-window` for information about adding content to a gui-root. In general you will always want to use `define` when creating a GUI-Root as everything is done by passing it as a reference later on in the development process for GUI applications",
	"gui-list-windows":      "(gui-list-windows [app: gui-root]) => list\n\nReturns a list containing the name of each window associated with the given gui-root",
	"gui-set-char-handlers": "(gui-set-char-handlers [gui-root] [window-name: string] [callback: lambda]) => #t\n\nSets up all single key keypress handlers. This is distinct from shortcuts, which are made by a key chord (Ctrl/Shift/Alt/Mod+Something). The lambda should accept a string. The string will always be a single character representing the key that was pressed. This only functions for printable keys. You should make one call to this procedure, at most, per window of your application. All kepresses that are not used by a widget (for example, an entry widget accepts text and will not further pass on the keypresses) will have the callback called with the character that was pressed as the input to the procedure. It is suggested that you use an if or cond statement to sort them into the effects you want to achieve for any given character",
	"gui-use-light-theme":   "(gui-use-light-theme [[bool]]) => bool\n\nIf no arguments are given `gui-use-light-theme` will check is a light theme is being used and return #t if so, #f if not. Any value passed to `gui-use-light-theme` will be coerced to a bool. If the given value is #t then the gui will be set to use the light them, otherwise the dark theme will be used",
	"widget-add-to-size":    "(widget-add-to-size [gui-widget] [width-change: number] [height-change: number]) => gui-widget\n\nUpdates the width and height of the given widget by adding the width-change value to the current width and the height-change value to the current height. Returns the updated widget",
	"widget-disable":        "(widget-disable [gui-widget] [[set-disabled: bool]]) => bool\n\nWhen called with only a valid gui-widget the current disabled state will be returned (`#t` means it is disabled). When called with a bool for `set-disabled` the widget will be disabled, if possible, if `#t` is given and will be enabled if `#f` is given. Any gui-widget passed to `widget-disable` that cannot be disabled will return `#f` for any call to the procedure",
	"widget-get-text":       "(widget-get-text [gui-widget]) => string\n\nRetrieves the text of the given widget",
	"widget-hide":           "(widget-hide [gui-widget]) => #t\n\nHides the given gui-widget. Calling on an already hidden widget will have no effect",
	"widget-make-button":    "(widget-make-button [text: string] [callback: lambda] [[alignment: number]] [[importance: number]]) => gui-widget\n\nCreates a button widget with the given text. The callback should accept no arguments and should only create side effects (the return value will be discarded). If alignment is given it should be one of:\n\n\t-1: Align Leading\n\t 0: Align Center\n\t 1: Align Trailing\n\nIf an importance value is given it will emphasise or de-emphasise the button. A value less than 1 will be the least emphasis, a value greater than 1 will be the most emphasis, 1 is the default medium emphasis",
	"widget-make-checkbox":  "(widget-make-checkbox [text: string] [callback: lambda]) => gui-widget\n\nCreates a button widget with the given text. The callback should accept one argument representing the boolean state of the checkbox and should only create side effects (the return value will be discarded)",
	"widget-make-entry":     "(widget-make-entry [placeholder-text: string] [[wrap-text: bool]] [[validation-callback: lambda]]) => gui-widget\n\nCreates an entry widget with the given placeholder value. For accessibility purposes it is always advised to also have a label widget describing this widget. If a validation lambda is given it should take a string value as its argument and should validate based on that string. If it successfully validates `#t` or any non-string value should be returned, otherwise a string explaining the error should be returned",
	"widget-make-hyperlink": "(widget-make-hyperlink [text: string] [url: string]) => gui-widget\n\nCreates a hyperlink widget with the given text linking to the given URL. If the URL cannot be parsed as a valid URL an exception will be returned",
	"widget-make-image":     "(widget-make-image [source: string] [location: string] [[mode: string]] [[min-width: number]] [[min-height: number]]) => gui-widget\n\nCreates an image widget from the given source. Available sources are: \"path\" and \"url\", the later of which will actually load any available URI. The `location` string represents the address or path of the image. The optional `mode` argument defaults to \"fit\" which will keep the original aspect ratio of the image but size it to fit the container (latching to the smallest container dimension). \"original\" may be passed to over-ride the default behavior and use the original image size, expanding the container if need be. Passing a min-width or min-height will cause the resulting image widget to size to this dimension as a minimum value. The way the size minimums work may be surprising as they interact with attempts to keep the aspect ratio and size to the container, so a 50x10 image set to 10x100 will not work, since aspect ratio is being kept. One value will be chosen as the one to use in sizing, this may depend on the type of container",
	"widget-make-label":     "(widget-make-label [text: string] [[alignment: number]] [[wrap-text: bool]]) => gui-widget\n\nCreates a label widget with the given text. If alignment is given it should be one of:\n\n\t-1: Align Leading\n\t 0: Align Center\n\t 1: Align Trailing",
	"widget-make-markdown":  "(widget-make-markdown [markdown-text: string] [[wrap-text: bool]]) => gui-widget\n\nCreates a markdown text block. The markdown-text string should be markdown, which will be parsed and rendered. wrap-text defaults to #f. If set to #t the text will be wrapped at word boundaries using the minimum size of the container",
	"widget-make-multiline": "(widget-make-multiline [placeholder-text: string] [[wrap-text: bool]] [[use-monospace-font: bool]] [[validation-callback: lambda]]) => gui-widget\n\nCreates a multiline text entry widget with the given placeholder value. For accessibility purposes it is always advised to also have a label widget describing this widget. If `#t` is passed to `use-monospace-font` the system's monospace font will be for text within the widget. If a validation lambda is given it should take a string value as its argument and should validate based on that string. If it successfully validates `#t` or any non-string value should be returned, otherwise a string explaining the error should be returned",
	"widget-make-password":  "(widget-make-password [placeholder-text: string] [[wrap-text: bool]] [[validation-callback: lambda]]) => gui-widget\n\nCreates an password widget with the given placeholder value. For accessibility purposes it is always advised to also have a label widget describing this widget. If a validation lambda is given it should take a string value as its argument and should validate based on that string. If it successfully validates `#t` or any non-string value should be returned, otherwise a string explaining the error should be returned",
	"widget-make-select":    "(widget-make-select [options: list] [callback: lambda] [[alignment: number]]) => gui-widget\n\nCreates a select widget with the given options. Any non-string options will be converted to string. The callback should accept a string argument representing the selected element and should only create side effects (the return value will be discarded). If alignment is given it should be one of:\n\n\t-1: Align Leading\n\t 0: Align Center\n\t 1: Align Trailing",
	"widget-make-separator": "(widget-make-separator) => gui-widget\n\nReturns a separator widget, which takes the form of a separator line that will go horizontal or vertical automatically depending on the container/layout",
	"widget-make-spacer":    "(widget-make-spacer) => gui-widget\n\nReturns a spacer widget which will fill up the available space in the container, pushing other widgets away from it in a direction decided based on the container/layou",
	"widget-set-text":       "(widget-set-text [gui-widget] [string]) => string\n\nSets the text of the given widget to the given string and returns the string",
	"widget-resize":         "(widget-resize [gui-widget] [width: number] [height: number]) => gui-widget\n\nIn general the size of widgets is defined by the container/layout. However, in cases where it is not, `widget-resize` can be used. If used in a situation where it cannot be used, there will be no effect. Returns the widget with the new size",
	"widget-show":           "(widget-show [gui-widget]) => #t\n\nShows the given gui-widget. The widget will only become visible if it is in a visible grouping (window, container, layout, etc). Calling on an already visible widget will have no effect",
	"widget-size":           "(widget-size [gui-widget]) => list\n\nReturns the given widget's current width and height, in that order, in a two item list",
	"window-allow-resize":   "(window-allow-resize [app: gui-root] [window-name: string] [bool]) => #t\n\nSets whether or not to allow the user to resize the given window",
	"window-center":         "(window-center [app: gui-root] [window-name: string]) => #t\n\nCenters the given window on the screen",
	"window-close":          "(window-close [app: gui-root] [window-name: string]) => #t\n\nCloses the given window. When called on an already closed window the behavior is undefined",
	"window-hide":           "(window-hide [app: gui-root] [window-name: string]) => #t\n\nHides the given window. There is no effect when called on an already hidden window",
	"window-resize":         "(window-resize [app: gui-root] [window-name: string] [width: number] [height: number]) => #t\n\nResizes the given app's given window to the width and height that were given, if possible. This is a finicky function in the underlying library and seems to behave unexpectedly or not at all",
	"window-set-content":    "(window-set-content [app: gui-root] [window-name: string] [content: gui-widget|gui-container]) => #t\n\nSets the content for the given window. This is usually a `container`, but could be a `widget`. #t or an exception will be returned",
	"window-set-fullscreen": "(window-set-fullscreen [app: gui-root] [window-name: string] [set-to-full-screen: bool]) => #t\n\nSets the given window to full screen if #t is given and removes it from full screen if #f is given",
	"window-set-title":      "(window-set-title [app: gui-root] [window-name: string] [title: string]) => #t\n\nSets the title of the window to the given title string. If a non-string value is passed as title a stringified version of the value will be used",
	"window-show":           "(window-show [app: gui-root] [window-name: string]) => #t\n\nShows the given window. There is no effect when called on an already visible window",
	"window-show-and-run":   "(window-show-and-run [app: gui-root] [window-name: string]) => #t\n\nRuns the gui with the given window visible. This is the main procedure for starting the gui and will block once evaluated until the window is closed",
}