Widgets

From Tombstone Engine Wiki
Jump to: navigation, search

A widget is an individual component of a window, panel, or any kind of interface displayed to the user. There are many different types of widgets defined by the Tombstone Engine, and these are described in the table below. Applications can also define their own custom widget types.

Widget

Description

Widget border.png

Border. This widget displays a one-pixel-wide rectangular border. The border is rendered around the outside of the actual boundary of the widget so that it precisely frames any other widget with the same size. (See also the BorderWidget class.)

The widget color controls the color of the border.

  • The Line style setting determines whether the border is rendered as solid, dotted (with either one-pixel dots or two-pixel dots), or dashed.

Widget camera.png

Camera. This widget displays a remote camera view in the world being played. It is only available for in-game panel effects. (See also the CameraWidget class.)

The widget color applies a tint to the entire camera view.

  • The Camera connector setting identifies a connector belonging to the panel effect node that is connected to a camera node through which the camera view is rendered.
  • The Minimum detail level setting specifies the minimum detail level for both geometry and shaders at which objects are rendered through the camera. Higher numbers correspond to lower detail levels.
  • The Detail level bias setting specifies a bias that is added to the normal detail level for objects rendered through the camera.

Widget check.png

Check Box. This widget displays a check box that can be in the checked state or unchecked state. (See also the CheckWidget class.)

The widget color controls the color of the text.

  • The Initially checked setting determines whether the check box is initially in the checked state.
  • The Use highlight when selected setting specifies that the check box changes to the highlight color when it is in the checked state.
  • The Text is not clickable setting specifies that clicking on the text has no effect and that the state of the check box can be changed only by clicking directly on the box.
  • The Button color setting specifies the color of the check box when it is not highlighted.
  • The Highlight color setting, if checked, specifies the color of the check box when it's in the selected state if the Use highlight when selected setting is checked, overriding the default highlight color specified by the $hiliteColor system variable.

Widget color.png

Color Box. This widget displays a color selection box that displays a color picker dialog when clicked. (See also the ColorWidget class.)

The widget color controls the color of the color box's border.

  • The Initial color value setting specifies the color value to which the color box is initially set (the color rendered in the interior).
  • The Color picker title setting specifies the title of the color picker window displayed when the user clicks inside the color box.
  • The Include alpha channel setting specifies whether the user is able to modify the alpha channel in the color picker.
  • The Focus glow color setting, if checked, specifies the color of the glow rendered when the color box is clicked, overriding the default glow color given by the $buttonColor system variable multiplied by 5/8.

Widget config.png

Configuration Table. This widget displays a configuration table that is used to show property settings to the user. (See also the ConfigurationWidget class.)

The widget color controls the color of the configuration table's border.

  • The Title column fraction setting determines what fraction of the full width of the table is used for the setting titles. A vertical line is rendered in between the title column and value column in the table.
  • The Show script variable column setting is used by the Script Editor to indicate that a third column be shown for variable name entry.
  • The Line color setting, if checked, specifies the color of the border lines inside the configuration table, overriding the default color given by the average of 50% gray and the window frame color given by the $windowFrameColor system variable.
  • The Background color setting specifies the background color for the configuration table.

Widget edittext.png

Editable Text Box. This widget displays an editable text box that allows a single line or multiple lines of text entry. (See also the EditTextWidget class.)

The widget color controls the color of the text.

  • The Maximum length setting specifies the maximum number of characters that can be entered into the text box.
  • The Character filter setting specifies a filter that determines what types of characters can be entered into the text box:
    • The value None means that any characters can be entered.
    • The value Numbers means that only the digits 0 through 9 can be entered.
    • The value Signed numbers means that only the digits 0 through 9 and a minus sign can be entered.
    • The value Floating-point means that any floating-point number can be entered, including an exponent.
    • The value Alphanumeric means that only uppercase letters, lowercase letters, and the digits 0 through 9 can be entered.
    • The value Identifier means that only uppercase letters, lowercase letters, the digits 0 through 9, and the underscore character can be entered.
  • The Allow text to overflow setting specifies whether the width of the text can exceed the width of the text box (with scrolling).
  • The Use multiple lines setting specifies whether the text box renders multiple lines or just a single line of text.
  • The Text is read-only setting specifies that the user cannot change the text in the text box, but can still select and copy parts of it.
  • The Select all when changed setting causes the text box to automatically select all when its text is changed through a method other than user input.
  • The Select all on double-click setting causes a double-click in the text box to select all, whereas a double-click would normally select only the word that was clicked on.
  • The Render plain (text only) setting causes the border, background, and keyboard focus glow to not be rendered.
  • The Render focus plain (no glow) setting causes the keyboard focus glow to not be rendered (but the border and background are still shown).
  • The Background color setting specifies the color of the text box's background.
  • The Border color setting specifies the color of the text box's border.
  • The Highlight color setting, if checked, specifies the highlight color for selected text, overriding the default highlight color given by the $hiliteColor system variable.
  • The Focus glow color setting, if checked, specifies the color of the glow rendered when the editable text box has the keyboard focus, overriding the default glow color given by the $hiliteColor system variable multiplied by 5/8.
  • The Insertion caret color setting specifies the color of the insertion caret.

Widget viewport.png

Frustum Viewport. This widget displays a viewport with a frustum camera. (See also the FrustumViewportWidget class.)

The widget color is not used.

Widget hyperlink.png

Hyperlink. This widget displays a text button with a hyperlink. Clicking on the button opens the default web browser installed on the user's computer and navigates to the address stored in the widget. (See also the HyperlinkWidget class.)

The widget color controls the color of the text.

  • The Hyperlink URL specifies the link sent to the user's browser when the text button is activated.

Widget iconbutton.png

Icon Button. This widget displays a button with a texture image. (See also the IconButtonWidget class.)

The widget color applies to the texture image displayed in the button.

  • The Stays selected when clicked setting causes the button to remain in the selected state when it is clicked.
  • The Render plain (icon only) setting specifies that the button background is not rendered.
  • The Initially selected setting specifies that the button is initially in the selected state.
  • The Button color setting specifies the color of the button itself (without affecting the icon image).

Widget image.png

Image. This widget displays a plain texture image. (See also the ImageWidget class.)

The widget color applies a tint to the texture image.

  • The Texture map setting specifies the texture resource that is displayed by the widget.
  • The X scale setting applies a horizontal scale to the texture image.
  • The Y scale setting applies a vertical scale to the texture image.
  • The X offset setting applies a horizontal offset to the texture image.
  • The Y offset setting applies a vertical offset to the texture image.
  • The Blend mode setting specifies the blending mode for the texture image:
    • The value Add causes the image to be added to the background.
    • The value Alpha add causes the image to be multiplied by its alpha channel and then added to the background.
    • The value Alpha blend causes the image to be multiplied by its alpha channel and then added to the background multiplied by the inverse of the image's alpha channel.
    • The value Alpha preblend causes the image to be added to the background multiplied by the inverse of the image's alpha channel.
    • The value Replace causes the image to replace the background with no blending.
  • The Layer/depth coordinate setting applies only to 2D array textures are 3D textures, and it specifies the layer or depth coordinate used to display the image.
  • The Cube map face index setting applies only to cube map textures, and it specifies which face is displayed by the image widget.

Widget line.png

Line. This widget displays a one-pixel-wide line that can be solid, dotted, or dashed. (See also the LineWidget class.)

The widget color controls the color of the line.

  • The Line style setting determines whether the line is rendered as solid, dotted (with either one-pixel dots or two-pixel dots), or dashed.

Widget list.png

List. This widget displays a list box with a scroll bar. (See also the ListWidget class.)

The widget color controls the color of the list's border.

  • The Item spacing setting specifies the vertical distance from one list item to the next. The height of the list box should be a multiple of this value to avoid extra space at the bottom of the list.
  • The Item offset X setting specifies a horizontal offset for items displayed in the list.
  • The Item offset Y setting specifies a vertical offset for items displayed in the list.
  • The Allow multiple selection setting enables multiple items to be selected in the list at the same time.
  • The Render focus plain (no glow) setting causes the keyboard focus glow to not be rendered.
  • The Leave list items enabled setting causes items in the list to be left in an enabled state to allow user interaction directly with each item.
  • The Background color setting specifies the color of the list background.
  • The Highlight color setting, if checked, specifies the color of the highlight used to indicate selected items, overriding the default highlight color specified by the $hiliteColor system variable.
  • The Focus glow color setting, if checked, specifies the color of the glow drawn around the list box when it has the keyboard focus, overriding the default glow color given by the $hiliteColor system variable multiplied by 5/8.
  • The Text item font setting determines what font is used to display plain text list items.

Widget menubar.png

Menu Bar. This widget displays a menu bar that allows the user to choose commands from pull-down menus. (See also the MenuBarWidget class.)

The widget color applies a tint to the menu bar.

  • The Menu title spacing setting specifies how much horizontal space is inserted between menu titles.
  • The Menu title offset Y setting specifies the vertical offset for menu titles.
  • The Menu title font setting determines what font is used to display menu titles.
  • The Highlight color setting, if checked, specifies the highlight color for the selected menu name, overriding the default highlight color given by the $hiliteColor system variable.

Widget movie.png

Movie. This widget plays a movie resource. (See also the MovieWidget class.)

The widget color applies a tint to the entire movie image.

  • The Movie name setting specifies the resource name of the movie.
  • The Movie is initially playing setting causes the movie to start playing when the panel is loaded.
  • The Movie is looping setting causes the movie to loop.
  • The Movie blend mode setting specifies the blending mode for the movie image. This setting pertains only to movies that contain an alpha channel. See the image widget for the meaning of the blending modes.
  • The Source connector key setting identifies a connector belonging to the panel effect node that is connected to a source node through which the movie audio is played. This setting pertains only to movie widgets belonging to in-game panel effects.

Widget multipane.png

Multipane Box. This widget displays a multipane box. The border and selection tabs are displayed outside the actual boundary of the widget. (See also the MultipaneWidget class.)

The widget color controls the color of the border.

  • The Line style setting determines whether the border is rendered as solid, dotted (with either one-pixel dots or two-pixel dots), or dashed.
  • The Pane title font setting determines what font is used to display pane titles.
  • The Pane list setting specifies the list of pane titles, where each title is separated from the next by a semicolon.
  • The Initial selection setting determines which pane is initially selected. A value of −1 indicates that no pane is selected.
  • The Button color setting controls the color of the pane tabs.
  • The Highlight color setting, if checked, controls the color of the selected pane tab, overriding the default highlight color specified by the $hiliteColor system variable.

Widget viewport.png

Ortho Viewport. This widget displays a viewport with an orthographic camera. (See also the OrthoViewportWidget class.)

The widget color is not used.

Widget paint.png

Paint. This widget displays an interactive painting canvas. The brush radius, fuzziness, opacity, and color can be set from a script using controller functions. (See also the PaintWidget class.)

The widget color applies a tint to the contents of the painting canvas.

  • The Resolution X and Resolution Y settings determine the internal resolution of the painting canvas, in pixels.
  • The Background color setting determines what color the painting canvas is initially filled with.
  • The Initial brush radius setting specifies the initial radius of the paint brush, in pixels.
  • The Initial brush fuzziness setting specifies the initial fuzziness of the paint brush in the range 0.0 (no fuzziness) to 1.0 (very fuzzy).
  • The Initial brush opacity setting specifies the initial opacity of the paint brush in the range 1% (almost completely transparent) to 100% (completely opaque).
  • The Initial brush color setting specifies the initial color of the paint brush.

Widget password.png

Password. This widget displays a password entry box that obscures the text entered into it. (See also the PasswordWidget class.)

The widget color controls the color of the text.

  • The Enable security features setting specifies that extra steps be taken to ensure the security of the password text. In particular, when this box is checked, the memory used to hold the password is locked in physical RAM and cannot be written to the system page file, and the password is erased before the widget is destroyed.

Widget popupmenu.png

Popup Menu. This widget displays a popup menu. (See also the PopupMenuWidget class.)

The widget color controls the color of the text.

  • The Render plain (text only) setting causes the background button not to be rendered.
  • The Item spacing setting specifies the vertical distance from one menu item to the next.
  • The Menu item list setting specifies the list of menu items, where each item is separated from the next by a semicolon.
  • The Initial selection setting determines which menu item is initially selected. A value of −1 indicates that no item is selected, in which case the text string is displayed, if specified.
  • The Button color setting specifies the color of the background button.

Widget progress.png

Progress Bar. This widget displays a progress bar. (See also the ProgressWidget class.)

The widget color controls the color of the background of the progress bar that is shown for the uncompleted portion of progress.

  • The Render plain (no border) setting specifies that the progress bar is rendered without a border and at the full height of the widget bounds.
  • The Initial value setting specifies the initial value of the progress bar.
  • The Maximum value setting specifies the maximum value of the progress bar.
  • The Highlight color setting, if checked, specifies the highlight color for the progress bar that is shown for the completed portion of progress, overriding the default highlight color specified by the $hiliteColor system variable.

Widget pushbutton.png

Push Button. This widget displays a button with a text string. (See also the PushButtonWidget class.)

The widget color controls the color of the text.

  • The Primary button setting indicates that the button should be rendered with the appearance of a primary button, which causes the color of the button be that specified by the $buttonColor system variable.
  • The Activation key setting specifies whether the Enter or Escape key acts as a shortcut for the push button.
  • The Button color setting specifies the color of the push button if it is not a primary button.

Widget quad.png

Quad. This widget displays a plain colored quad. (See also the QuadWidget class.)

The widget color controls the color of the quad.

Widget radio.png

Radio Button. This widget displays a radio button that can be in the selected or unselected state. When a radio button is selected, all other radio buttons in the same group (or in the entire window if the radio button is not in a group) are automatically unselected. (See also the RadioWidget class.)

The widget color controls the color of the text.

  • The Initially selected setting determines whether the radio button is initially in the selected state.
  • The Use highlight when selected setting specifies that the radio button changes to the highlight color when it is in the selected state.
  • The Text is not clickable setting specifies that clicking on the text has no effect and that the state of the radio button can be changed only by clicking directly on the button.
  • The Button color setting specifies the color of the radio button when it is not highlighted.
  • The Highlight color setting, if checked, specifies the color of the radio button when it's in the selected state if the Use highlight when selected setting is checked, overriding the default highlight color specified by the $hiliteColor system variable.

Widget scroll.png

Scroll Bar. This widget displays a scroll bar. (See also the ScrollWidget class.)

The widget color controls the color of the scroll bar's background.

  • The Horizontal appearance setting causes the widget to be rendered with the appearance adjusted for a horizontally-oriented scroll bar.
  • The Initial value setting specifies the initial value for the scroll bar.
  • The Maximum value setting specifies the maximum value for the scroll bar.
  • The Page up/down distance setting specifies by how much the value changes when the user clicks in the scroll bar above or below the indicator button.
  • The Button color setting specifies the color of the up, down, and indicator buttons.

Widget slider.png

Slider. This widget displays a slider. (See also the SliderWidget class.)

The widget color controls the color of the slider bar.

  • The Slider style setting determines the style of the indicator button, and it can be circular or square.
  • The Initial value setting specifies the initial value for the slider.
  • The Maximum value setting specifies the maximum value for the slider.
  • The Button color setting, if checked, specifies the color of the indicator button, overriding the default buttoncolor specified by the $buttonColor system variable.

Widget list.png

Table. This widget displays a table with a fixed number of columns in a box with a scroll bar. (See also the TableWidget class.)

The widget color controls the color of the table's border.

  • The Number of columns setting specifies the number of columns in the table.
  • The Cell size X setting specifies the horizontal size of each cell in the table. The width of the widget should be a multiple of this value plus 16 pixels for the scroll bar.
  • The Cell size Y setting specifies the vertical size of each cell in the table. The height of the widget should be a multiple of this value to avoid extra space at the bottom of the table.
  • The Item offset X setting specifies a horizontal offset for items displayed in the table.
  • The Item offset Y setting specifies a vertical offset for items displayed in the table.
  • The Highlight inset X setting specifies the left and right inset for the highlight box rendered behind selected items in the table.
  • The Highlight inset Y setting specifies the top and bottom inset for the highlight box rendered behind selected items in the table.
  • The Allow multiple selection setting enables multiple items to be selected in the table at the same time.
  • The Render focus plain (no glow) setting causes the keyboard focus glow to not be rendered.
  • The Leave table items enabled setting causes items in the table to be left in an enabled state to allow user interaction directly with each item.
  • The Background color setting specifies the color of the table background.
  • The Highlight color setting, if checked, specifies the color of the highlight used to indicate selected items, overriding the default highlight color specified by the $hiliteColor system variable.
  • The Focus glow color setting, if checked, specifies the color of the glow drawn around the table when it has the keyboard focus, overriding the default glow color given by the $hiliteColor system variable multiplied by 5/8.

Widget text.png

Text. This widget displays a plain text string. (See also the TextWidget class.)

The widget color controls the color of the text.

  • The Font setting determines in what font the text is displayed.
  • The Font size setting specifies the size of the font. This corresponds to the height of the em square for the font, in pixels. The heights of capital letters in a font are typically about 70% of this size, but this can vary significantly from one font to another.
  • The Text scale setting specifies a scale to be applied to the text. The font size is multiplied by the text scale to calculate the final size at which text is rendered.
  • The Leading (em) setting specifies the vertical distance between two consecutive baselines in multi-line text, in em units. The default value of 1.2 em produces a typical line spacing.
  • The Tracking (em) setting specifies additional horizontal space that is inserted between all characters, in em units.
  • The Enable kerning setting determines whether kerning is applied to the text. When this is enabled, information taken from tables in the original font are used to adjust the spacing between certain pairs of characters to improve visual appearance.
  • The Alignment setting determines the alignment of the text within the widget's bounding box. This can be left, center, or right.
  • The Box mode setting determines what action is taken when the text does not fit within the horizontal bounds of the widget. If this is set to Clip text, then text that flows beyond the left or right edge of the widget's bounding box is clipped. If this is set to Wrap text, then the text is displayed as multiple lines that are broken after spaces or hyphens. If this set to Overflow, then text that flows beyond the left or right edge is rendered outside the bounding box without clipping.
  • The Glyph effect setting determines what special effect is applied to the text, if any. If this is set to None, then no effect is applied, and the following glyph effect parameters are ignored. If this is set to Shadow, then a drop shadow is rendered behind the text with the intensity, size, and offset specified by the following settings. If this is set to Glow, then a glow effect is added to the text with the intensity and size specified by the following settings.
  • The Glyph effect intensity setting specifies the intensity of each glyph effect. This corresponds to the opacity of the shadow effect or the maximum brightness of the glow effect.
  • The Glyph effect size (em) setting specifies the size of each glyph effect, in em units. This value is clamped to the maximum value specified for the font when it was imported.
  • The Glyph effect offset X (em) setting specifies the offset of the shadow effect in the x direction, in em units. This value is clamped to the minimum and maximum values specified for the font when it was imported.
  • The Glyph effect offset Y (em) setting specifies the offset of the shadow effect in the y direction, in em units. This value is clamped to the minimum and maximum values specified for the font when it was imported.

The text string box contains the string that is displayed by the widget. If the text is displayed as multiple lines, then a hard line break can be inserted by entering \n in the text string. Formatting directives may also be embedded inside the text string. See Text Formatting for details.

Widget textbutton.png

Text Button. This widget displays a clickable text string. (See also the TextButtonWidget class.)

The widget color controls the color of the text.

  • The Highlight color setting determines the color in which the text is rendered while the mouse button is pressed inside the text.

Widget list.png

Tree. This widget displays a list box with a scroll bar, and the items can have collapsable subtrees. (See also the TreeWidget class.)

The widget color controls the color of the list's border.

  • The Item spacing setting specifies the vertical distance from one list item to the next. The height of the list box should be a multiple of this value to avoid extra space at the bottom of the list.
  • The Item offset X setting specifies a horizontal offset for items displayed in the list.
  • The Item offset Y setting specifies a vertical offset for items displayed in the list.
  • The Allow multiple selection setting enables multiple items to be selected in the list at the same time.
  • The Render focus plain (no glow) setting causes the keyboard focus glow to not be rendered.
  • The Leave list items enabled setting causes items in the list to be left in an enabled state to allow user interaction directly with the item.
  • The Background color setting specifies the color of the list background.
  • The Highlight color setting, if checked, specifies the color of the highlight used to indicate selected items, overriding the default highlight color specified by the $hiliteColor system variable.
  • The Focus glow color setting, if checked, specifies the color of the glow drawn around the list box when it has the keyboard focus, overriding the default glow color given by the $hiliteColor system variable multiplied by 5/8.
  • The Text item font setting determines what font is used to display plain text list items.
  • The Subitem indent spacing setting specifies by how much subitems are indented relative to their parent item.}}

Widget viewport.png

World Viewport. This widget renders a complete world inside a frustum viewport, and the it provides camera orbit functionality. (See also the WorldViewportWidget class.)

The widget color is not used.

See Also