OpenGl-based custom UI dialog

The OpenGl-based custom UI dialog is located at [Menu bar --> Tools --> OpenGl-based Custom UIs]. Alternatively, it can also be accessed through its toolbar button:

[OpenGl-based custom UI toolbar button]


[OpenGl-based custom UI dialog - part 1]


The OpenGl-based custom UI edit mode is automatically activated/deactivated when its related dialog is shown/hidden. The OpenGl-based custom UI dialog is context sensitive, and displays a different content according to a UI cell's selection state: when no cells of a UI are selected, then the custom UI dialog displays above's part 1, otherwise below's part 2.

A non-empty UI cell is called a button. Following briefly describes the various items in the custom UI dialog part 1:

  • Add new user interface: allows adding a default OpenGl-based custom UI to the scene. Clicking the button opens a dialog where the main properties of the new custom UI can be set:

    [OpenGl-based custom UI creation dialog]


    The dialog allows specifying how big in terms of cells the client size should be (Client x-size and Client y-size). Additionally, a title bar with minimize/maximize button or/and a close button can be added. In any case, the new custom UI can be further edited in next step.

  • Horizontal / vertical cell count: number of horizontal/vertical cells (i.e. columns and rows of the custom UI)
  • Horizontal / vertical cell size: horizontal/vertical size of a single cell. This has to be a multiple of 2 and is set to 14 by default.
  • Horizontal / vertical UI position: horizontal/vertical position of the custom UI, indicated in pixels. The position can be specified relative to the top-, bottom-, left- or right-border of the rendering window (see hereafter).
  • UI is relative to left / top border: if enabled, then the custom UI's horizontal/vertical position is specified relative to the left/top border of the rendering window. Otherwise it is specified relative to the right/bottom border of the rendering window.
  • UI is visible: allows turning the display of the custom UI on and off. When the custom UI edit mode is activated however, all custom UIs are visible.
  • UI is visible only during simulation: if enabled, then the custom UI will only be visible when a simulation is running. When the custom UI edit mode is activated however, all custom UIs are visible.
  • UI is visible if associated object is selected: if enabled, then the custom UI will only be visible when its associated object is selected. When the custom UI edit mode is activated however, all custom UIs are visible.
  • UI is moveable: if enabled, then the custom UI can be dragged with the mouse when clicking a label-type button. This however only works when not in custom UI edit mode.
  • Use fixed-width font: allows specifying whether a variable-width font or a fixed-width font should be used for this custom UI.
  • Select associated object if UI is clicked: custom UIs can be associated (or attached) with an object. If this item is checked, then if the user clicks the custom UI, its associated object will be selected.
  • Display UI in: allows specifying on which page the custom UI should be displayed. By default a custom UI appears on all pages.
  • UI is associated with: allows associating (attaching) a custom UI with an object. Copying the object will also copy all custom UIs that are associated to that object.
  • Set UI background texture: opens the texture dialog for the custom UI background texture. The background texture for a custom UI stretches over the whole custom UI and is only visible where buttons have the Transparent / show background texture item selected (see further below).
  • Adjust rolled-up sizes: a custom UI can be displayed in 2 different modes: the normal mode and the rolled-up mode. When the custom UI is rolled-up, the rolled-up size specifies a rectangular area of cells that stay visible. This feature can be used to obtain custom UIs that can be minimized and maximized for instance. Use this feature together with a button that has the roll-up action property activated.

  • When one or more UI cells are selected, then the OpenGl-based custom UI dialog will display following part 2:

    [OpenGl-based custom UI dialog - part 2]


  • Insert button(s): inserts single buttons in the selected non-empty cells.
  • Insert merged button: inserts a merged button. A merged button is a button that stretches over several cells. The selection needs to be rectangular for this command to have an effect.
  • Button handle: handle or ID of the last selected button. Custom UI events report actions by using this handle (e.g. button "buttonHandle" of custom UI "uiID" was clicked/changed). Also, some API functions that target buttons will need this ID to uniquely identify the button within a custom UI.
  • Type: 4 basic button types are available: a button can be of type button, label, edit box or slider.
  • Enabled: allows toggling the enabled state of a button.
  • Checkable: a checkable button, when clicked a first time will stay pressed until it is clicked a second time. Only checkable buttons can have a roll-up action.
  • Roll-up action: if selected, then the associated button will allow minimizing/maximizing the custom UI. (see the Adjust rolled-up sizes-item here above). Only checkable buttons can have a roll-up action.
  • Horizontally / vertically centered: indicates whether a button, label or edit box text should be horizontally/vertically centered.
  • Up/down event: when selected, then the button will generate an event when pressed, and another event when released. This allows implementing buttons with "continuous" effect rather than "punctual" effect. Refer to the simGetUIEventButton function for more details.
  • Close action: if selected, then the associated button will allow making the custom UI invisible.
  • Borderless: indicates whether the button should have a border.
  • Ignore mouse: indicates whether the button should ignore any mouse action. If selected, the button will still be visible, but all mouse actions will be applied to what lies under that button.
  • Button label (up /down state): text to display on a button of type button in up-state (not pressed), on a label or on an edit box. Checkable buttons can display a different label when pressed (down state). Button labels accept special codes to display shapes or change the text color (the decoding is case-sensitive):
  • &&fg###: allows changing the text color for the following text. Each # represents a digit (0-9) indicating the value for the red-, green- and blue-component of the color respectively.
  • &&fg@@@: resets the original text color (can be used sometime after &&fg### (see here above))
  • &&Box: displays a filled square.
  • &&Pause: displays a pause icon (two vertical rectangles)
  • &&Start: displays a "rewind" icon (vertical rectangle followed by an arrow pointing to the left)
  • &&End: displays a "wind forward" icon (arrow pointing to the right followed by a vertical rectangle)
  • &&ArrowLeft: displays an arrow pointing to the left.
  • &&ArrowRight: displays an arrow pointing to the right.
  • &&ArrowUp: displays an arrow pointing up.
  • &&ArrowDown: displays an arrow pointing down.
  • &&Check: displays a cross (big X).
  • &&Square: displays an empty square.
  • &&Minimize: display a "minimize" icon.
  • &&n: indicates a line-break for multiline text for button or label-type buttons.

  • Edit background color (up / down): allows editing the background colors of a button.
  • Edit label color: allows editing the default label color of a button.
  • Transparent / show background texture: the button will appear semi-transparent if selected. If a background texture was specified for the custom UI (see the Set UI background texture item above), then having this item selected will display the background texture fragment for the button's location.
  • Set button texture: opens the texture dialog for the button texture. The button texture stretches over the whole button. A button texture is different from a background texture.
  • No background color: the button won't have any background color if selected.

  • Recommended topics

  • OpenGl-based custom UI edit mode
  • Texture dialog