Functions and classes for generating and controlling user interfaces within Strata 3D CX.
This table contains some useful characters which may be used in strings returned to the Strata 3D CX scripting dialogs for cursor positioning and shift state control, useful for shift-selecting a sequence of just entered text for example. cursor_keys.key_home -- move the cursor to the start of the current line.
cursor_keys.key_end -- move the cursor to the end of the current line.
cursor_keys.arrow_left -- move the cursor left.
cursor_keys.arrow_right -- move the cursor right.
cursor_keys.arrow_up -- move the cursor up.
cursor_keys.arrow_down -- move the cursor down.
cursor_keys.shift_down -- set the shift key down to begin a selection range.
This table contains key codes for the most common keyboard keys. These may be useful as arguments to other functions which take key codes, but probably not for normal string processing. These values are platform specific and subject to change, so don't expect them to remain constant between program runs.
--
-- key codes
--
keys.noKey -- The not-a-keycode key code
keys.homeKey -- Key code for Home key
keys.endKey -- Key code for End key
keys.pageUpKey -- Key code for Page Up key
keys.pageDownKey -- Key code for Page Down key
keys.escapeKey -- Key code for Escape key
keys.clearKey -- Key code for Clear key
keys.helpKey -- Key code for Help key
keys.fwdDeleteKey -- Key code for Forward Delete
keys.backDeleteKey -- Key code for Delete
keys.leftCursorKey -- Key code for cursor left
keys.rightCursorKey -- Key code for cursor right
keys.upCursorKey -- Key code for cursor up
keys.downCursorKey -- Key code for cursor down
keys.backspaceKey -- Key code for Backspace key
keys.enterKey -- Key code for Enter key
keys.returnKey -- Key code for Return key
keys.tabKey -- Key code for Tab key
keys.spaceBarKey -- Key code for SpaceBar key
keys.plusKey -- Key code for Plus key
keys.minusKey -- Key code for Minus key
keys.equalKey -- Key code for Equal key
keys.dashKey -- Key code for Dash key
keys.slashKey -- Key code for the forward slash key
keys.backSlashKey -- Key code for the backward slash key
keys.f1Key -- Key code for F1
keys.f2Key -- Key code for F2
keys.f3Key -- Key code for F3
keys.f4Key -- Key code for F4
keys.f5Key -- Key code for F5
keys.f6Key -- Key code for F6
keys.f7Key -- Key code for F7
keys.f8Key -- Key code for F8
keys.f9Key -- Key code for F9
keys.f10Key -- Key code for F10
keys.f11Key -- Key code for F11
keys.f12Key -- Key code for F12
keys.f13Key -- Key code for F13
keys.f14Key -- Key code for F14
keys.f15Key -- Key code for F15
--
-- scan codes
--
keys.noCharacter -- The not-a-scancode scan code
keys.char1 -- Scan code for 1 key
keys.char2 -- Scan code for 2 key
keys.char3 -- Scan code for 3 key
keys.char4 -- Scan code for 4 key
keys.char5 -- Scan code for 5 key
keys.char6 -- Scan code for 6 key
keys.char7 -- Scan code for 7 key
keys.char8 -- Scan code for 8 key
keys.char9 -- Scan code for 9 key
keys.char0 -- Scan code for 0 key
keys.charA -- Scan code for a key
keys.charB -- Scan code for b key
keys.charC -- Scan code for c key
keys.charD -- Scan code for d key
keys.charE -- Scan code for e key
keys.charF -- Scan code for f key
keys.charG -- Scan code for g key
keys.charH -- Scan code for h key
keys.charI -- Scan code for i key
keys.charJ -- Scan code for j key
keys.charK -- Scan code for k key
keys.charL -- Scan code for l key
keys.charM -- Scan code for m key
keys.charN -- Scan code for n key
keys.charO -- Scan code for o key
keys.charP -- Scan code for p key
keys.charQ -- Scan code for q key
keys.charR -- Scan code for r key
keys.charS -- Scan code for s key
keys.charT -- Scan code for t key
keys.charU -- Scan code for u key
keys.charV -- Scan code for v key
keys.charW -- Scan code for w key
keys.charX -- Scan code for x key
keys.charY -- Scan code for y key
keys.charZ -- Scan code for z key
This table holds values representing bit masks which may be combined via addition.
(the control key on the Mac is unrepresented)
modifiers.none = 0
modifiers.shift = 1
modifiers.alt = 2 -- The option key on Mac, and alt key on Windows.
modifiers.command = 4 -- The command key on Mac, and control key on Windows.
modifiers.capsLock = 8
This table determines the content of the 'Elements' menu within many of the script editing dialogs in Strata 3D CX.
It is a table of sub-tables with the following structure:
Currently supported scripting dialog result names are:
When a menu item with a string value is selected it will be evaluated by the Lua interpreter, so make sure it represents good Lua syntax.
This table determines the content of the 'Scripting' menu in the main menu of Strata 3D CX.
It is a table of sub-tables with the following structure:
Any items beyond these first three are optional and are uninterpreted by the runtime, but they provide an opportunity to store and pass data to any menu item functions you may have declared.
This is a table of functions you may call to give feedback in the button bar of Strata 3D CX.
status.Text (message)
message -> string
status.Distance (distance, isDeltaDistance)
distance -> number
isDeltaDistance -> boolean
status.Rotation (angle, isDeltaRotation)
angle -> number
isDeltaDistance -> boolean
status.Scale (scale, isDeltaScale)
scale -> number
isDeltaDistance -> boolean
status.ViewAngle (angle)
angle -> number
status.Magnification (zoomFactor)
zoomFactor -> number
status.FreeRotation ()
status.Position3d (x, y, z, isDeltaPosition)
x -> number
y -> number
z -> number
isDeltaPosition -> boolean
status.Distance3d (x, y, z, isDeltaDistance)
x -> number
y -> number
z -> number
isDeltaDistance -> boolean
status.Rotation3d (x, y, z, isDeltaRotation)
x -> number
y -> number
z -> number
isDeltaRotation -> boolean
status.Quaternion (angle, axis_x, axis_y, axis_z, isDeltaRotation)
x -> number
y -> number
z -> number
isDeltaRotation -> boolean
status.Scale3d (x, y, z, isDeltaScale)
x -> number
y -> number
z -> number
isDeltaScale -> boolean
status.ViewLookAt (x, y, z, isDeltaMove)
x -> number
y -> number
z -> number
isDeltaMove -> boolean
status.ViewSize (width, height)
width -> number
height -> number
Alert (message)
message -> string
Puts up a simple alert with the given message and a single "OK" button.
DoCommand (cmd)
cmd -> integer
The list of possible command numbers is found in the s3d.command_numbers table.
GetLocalizationLanguage () -> string
Current possible return values include "en" and "jp" for English and Japanese localizations.
GetScriptingFontID () -> integer
Returns the id of the current font used in the scripting dialog. The font id is a transient value across program runs. It's better to deal with the font name.
GetScriptingFontName () -> string
Returns the name of the current font used in the scripting dialog.
GetScriptingFontSize () -> integer
Returns the size of the current font used in the scripting dialog.
IsCommandEnabled (cmd) -> boolean
cmd -> integer
The list of possible command numbers is found in the s3d.command_numbers table.
IsKeyDown (keyCode) -> boolean
keyCode -> integer
Returns true if the given key is down. Pass one of the key code constants from the keys table.
IsModifierKeyDown (modifier) -> boolean
modifier -> integer
Returns true if the given modifier key is down. Pass one of the constants from the modifiers table.
PresentNodeScriptEditor (resultClass, resultName, init, body) -> boolean, string, string, string, string
resultClass -> string
resultName -> string
init -> string
body -> string
This call is for use by custom node script editors to allow opening up the default text based editor.
SetScriptingFontID (id) -> boolean
id -> integer
Makes a persistent change of the font used in the scripting console, specified by an integer identifier. Returns true if the console is showing and therefore updated with the change.
SetScriptingFontName (name) -> boolean
name -> string
Makes a persistent change of the font used in the scripting console, specified by name. Returns true if the console is showing and therefore updated with the change.
SetScriptingFontSize (size) -> boolean
size -> integer
Makes a persistent change of the font size used in the scripting console. Returns true if the console is showing and therefore updated with the change.
Dialogs are constructed of clusters of columns of controls, with each control identified by a unique integer identifier. Using the Add...() methods you fill up a column with new control definitions and are returned the new integer identifiers.
Using the BeginCluster()/EndCluster() methods you start and finish a sub-cluster of additional control columns. In this way you can build up an arbitrary user interface consisting of nested clusters of columns. The overall dialog will size itself to fit all of the defined controls.
Every dialog is given an okay and cancel button by default. Their integer identifiers are given by the class constants kOkay and kCancel. Using the SetShown() method you can hide the cancel button if you don't want to use it.
This class has the following constant data:
kCancel -> integer
kOkay -> integer
These are the predefined identifiers for the standard cancel and okay buttons. These two buttons always exist, although you may hide them if you like, and they will always have these identifiers.
This class has the following construction methods:
Dialog (title)
title -> string
Constructs a dialog window with the given title. Pass the empty string if you don't want a title.
Every instance of this class has the following member methods:
Present ( [ callback ] ) -> integer
callback -> optional function (integer) -> integer
Opens the dialog and begins interacting with the user. The callback function is optional and if provided will be called with the integer id of every control hit while the dialog is presented. Return a different integer id or zero if you don't want to take the default handling for that control.
Typically you might do this to validate the dialog content when the okay button is hit, and optionally present an alert using s3d.ui.Alert() to let the user know about a problem.
Member methods for building an interface:
AddButton (label [, minWidth ] ) -> integer
label -> string
minWidth -> optional integer
Adds a button to the bottom of the dialog near the standard okay and cancel buttons, returning the integer id for the new control. Pass a non-zero minWidth to impose a minimum button width.
AddCheckbox (label [, minWidth ] ) -> integer
label -> string
minWidth -> optional integer
Adds a checkbox to the current column, returning the integer id for the new control. Pass a non-zero minWidth to impose a minimum checkbox width.
AddEditText (text [, minWidth ] ) -> integer
text -> string
minWidth -> optional integer
Adds an editable text control to the current column, returning the integer id for the new control. Pass a non-zero minWidth to impose a minimum control width.
AddNumberText (value [, precision [, minWidth ] ] ) -> integer
value -> number
precision -> optional integer
minWidth -> optional integer
Adds an editable number text control to the current column with a default range over all real numbers, returning the integer id for the new control. Pass a non-zero precision to enable fractional values with the given number of digits. Pass a non-zero minWidth to impose a minimum control width.
The default precision is zero, meaning this control will handle only whole integer values. Call the SetValueLimits method to restrict the range of allowable values.
AddPasswordText (text [, minWidth ] ) -> integer
text -> string
minWidth -> optional integer
Adds a control that behaves like the standard editable text control except that it will only display dots for each character, returning the integer id for the new control.
AddRadio (label [, minWidth ] ) -> integer
label -> string
minWidth -> optional integer
Adds a radio button to the current column, returning the integer id for the new control. Pass a non-zero minWidth to impose a minimum radio button width.
AddStaticText (label [, minWidth ] ) -> integer
label -> string
minWidth -> optional integer
Adds a non-editable static text control to the current column, returning the integer id for the new control. These are useful for informative text and for labeling. Pass a non-zero minWidth to impose a minimum text width.
AddColumn ( [ minWidth ] )
minWidth -> optional integer
Call this method to start a new column in the current cluster. Pass a non-zero minWidth to impose a minimum column width.
BeginCluster (label [, noBorder [, subCluster ], minWidth ] ) -> integer
label -> string
noBorder -> optional boolean
subCluster -> optional boolean
minWidth -> optional integer
Starts a new cluster and column, returning the integer id for the new cluster. All subsequent calls on the dialog methods to add controls will add them to the new cluster column until another column is added or the cluster is closed with EndCluster.
Pass noBorder true to eliminate the label area and the default border around the cluster. Pass subCluster true to get a different secondary look for the cluster, typically used for nested clusters with a border inside of another cluster with a border. Pass a non-zero minWidth to impose a minimum cluster width.
EndCluster ()
Call this method to end the most recent cluster definition and return to adding controls to the parent column and cluster.
Member methods for getting values:
GetAlignment (controlID) -> integer
controlID -> integer
Returns the alignment for a labeled control or one of the editable text controls. Pass the identifier received when the control was added.
GetDesktop ( [ containing ] ) -> s3d.vec.Rectangle
containing -> optional boolean
Returns the rectangle for the system desktop area, optionally restricting the result to the one display containing the largest portion of this dialog.
GetEnabled (controlID) -> boolean
controlID -> integer
Returns the enabled state for the given control. Controls that are not enabled will not accept user input. Pass the identifier received when the control was added.
GetLabel (controlID) -> string
controlID -> integer
Returns the label for the given control. Pass the identifier received when the control was added.
GetLocation () -> s3d.vec.Point
Returns the location of the dialog window on the desktop.
GetSelected (controlID) -> boolean
controlID -> integer
Returns true if the checkbox or radio button is selected. Pass the identifier received when the control was added.
GetShown (controlID) -> boolean
controlID -> integer
Returns true if the control is shown. Pass the identifier received when the control was added.
GetSize () -> s3d.vec.Point
Returns the size of the dialog window on the desktop.
GetText (controlID) -> string
controlID -> integer
Returns the text contained in an editable text, number text, or password text control. Pass the identifier received when the control was added.
GetTextStyle (controlID) -> string, integer
controlID -> integer
Returns the text style as a font name string and integer size for a labeled control or one of the editable text controls. Pass the identifier received when the control was added.
GetValue (controlID) -> number
controlID -> integer
Returns the value of a number text control, or 0 and 1 for any checkbox or radio button controls depending on whether they are selected or not. Pass the identifier received when the control was added.
GetValueLimits (controlID) -> number, number
controlID -> integer
Returns the minimum and maximum numeric value limits for a number text control. Pass the identifier received when the control was added.
Member methods for setting values:
SetAlignment (controlID, leftCenterRight)
controlID -> integer
leftCenterRight -> integer
Pass a value of -1, 0, or +1 in leftCenterRight to align things to the left, center, or right respectively.
SetEnabled (controlID, enabled)
controlID -> integer
enabled -> boolean
Enable or disable a control based on the enabled argument.
SetLabel (controlID, label)
controlID -> integer
label -> string
Set the label for a control to the given string.
SetLocation (h, v)
h -> integer
v -> integer
Sets the dialog window location on the desktop to the given horizontal and vertical coordinates.
SetLocation (location)
location -> s3d.vec.Point
Sets the dialog window location on the desktop using a Point object for the coordinates.
SetSelected (controlID, selected)
controlID -> integer
selected -> boolean
Select or deselect a control based on the selected argument.
SetShown (controlID, shown)
controlID -> integer
shown -> boolean
Show or hide a control based on the shown argument.
SetText (controlID, text)
controlID -> integer
text -> string
Set the text for one of the editable text control types.
SetTextStyle (controlID, fontName, fontSize)
controlID -> integer
fontName -> string
fontSize -> integer
Set the text style given a font name string and integer size.
SetTitle (title)
title -> string
Set the title for the dialog window to the given string.
SetValue (controlID, value)
controlID -> integer
value -> number
Set the value of a number text control to the given number.
SetValueLimits (controlID, minimum, maximum)
controlID -> integer
minimum -> number
maximum -> number
Set the minimum and maximum allowable numeric values for a number text control.
The KeyObject class is typically used for querying the keyboard state. Using these objects you can detect changes in modifier keys and all other keys. There is no mechanism for absorbing a keystroke so as to keep it from the host application.
This class has the following construction methods:
KeyObject ()
Constructs a new object containing the current keyboard state.
Returns the new object.
Every instance of this class has the following member methods:
KeyObject:GetCharacter () -> integer
Returns the ascii character for the key pressed at the time this object was constructed
or the last snapshot was taken.
KeyObject:GetExtended () -> integer
Returns the extended key code for the key pressed at the time this object was constructed
or the last snapshot was taken.
KeyObject:GetModifiers () -> integer
Returns the modifier keys which were pressed at the time this object was constructed
or the last snapshot was taken.
KeyObject:GetMouseState () -> integer
Returns the mouse button state at the time this object was constructed
or the last snapshot was taken.
KeyObject:Snapshot ()
Peeks at the keyboard again and fills this object with the current key state.