A SchematicControl item is used to place a flow-chart control on the rollout. The user can create and connect different nodes and respond via maxscript.
The syntax is:
SchematicControl <name> [ <caption> ] [ width :<integer>] [ height :<integer>]
Example:
SchematicControl s "View " width:150 height:200
Notes:
1. It is important to know that functions in the SchematicControl are to be run without brackets. Example:
s.addNode
Versus:
s.addNode() <- incorrect
2. Most functions in the SchematicControl work on an Active Node and/or Active Socket.
Since a flow chart can contain many nodes, it is important for the Helium SchematicControl to know which node you wish to work on. This is done by setting the Active Node index. (The Active Node does not have to be the selected node).
Example:
The below example shows how to change the name of a node by setting the Active Node to the correct node first:
heliumOps.targetControl.activeNode = 5 -- set node with index 5 to active
heliumOps.targetControl.nodeName = "New Name" -- change the name
heliumOps.targetControl.redrawNode -- redraw the active node
3. A Schematic Node can have any number of in and output sockets.
Each socket has a unique ID per node.
Connections between sockets are always considered to be made from an Output Socket to an Input Socket.
The UI will allow you to make connections in either direction, but it is still returned to maxscript from output socket to input socket.
(See 'connectionChanged' event)
Events
LButtonDblclk:
Left mouse button double clicked.
LButtonDown:
Left mouse button down/pressed.
LButtonUp:
Left mouse button up/released.
MButtonDown:
Middle mouse button down/pressed.
MButtonUp:
Middle mouse button up/released.
mouseScroll:
Middle mouse button is scrolled.
mouseMoved:
Mouse is moved within rollout.
rButtonDown:
Right mouse button down/pressed.
rButtonUp:
Right mouse button up/released.
killFocus:
Mouse was clicked somewhere outside of the schematic and the schematic has lost mouse and keyboard control.
nodeClicked index :
A Node was clicked in the view. The index is the index of the node that was clicked on.
connectionChanged fromNodeIndex toNodeIndex toSocketID fromSocketID status toSocketCount :
A connection was created or broken:
fromNodeIndex: the node with the output socket.
toNodeIndex: the node with the input socket.
toSocketID: the ID of the input socket.
fromSocketID: the ID of the output socket.
status: 0 if the connection was broken, 1 if the connection was created.
toSocketCount: New number of connections going into the input socket.
socketValueChanged nodeIndex socketID :
The value of a socket was changed:
nodeIndex: the node with the socket.
socketID: the ID of the socket.
preNodesDeleted:
Node(s) are about to be deleted via the UI. You should not delete/add nodes in this event.
You could get the selected nodes during this event to know what nodes were deleted in 'nodesDeleted' event.
nodesDeleted:
Node(s) were deleted via the UI.
If you do not want nodes to be deletable via the UI but only via MXS (i.e. an RCMenu) then use the property: .allowUIDelete = false.
connectionSelectionChanged fromNodeIndex toNodeIndex toSocketID fromSocketID :
A connection was selected.
This functions will return the information for the newly selected connection.
Only one connection can be selected in the graph.
(If you want to know when a connection is unselected, use LButtonUp and getSelectedConnectionIndex)
fromNodeIndex: the node with the output socket.
toNodeIndex: the node with the input socket.
toSocketID: the ID of the input socket.
fromSocketID: the ID of the output socket.
keyboardDown keyCode :
A key on the keyboard was pressed, keyCode stands for the key that was pressed. Print the keyCode to figure out what key is what code.
keyboardUp keyCode :
A key on the keyboard was released, keyCode stands for the key that was pressed. Print the keyCode to figure out what key is what code.
connectToEmpty nodeIndex socketIndex socketType:
This event is send when a connection was initiated, but released in an empty area of the view.
nodeIndex: the node from which the connection was made.
socketIndex: the socket from which the connection was made.
socketType: the type of socket (input:0, or output:1)
connectionStarted nodeIndex socketIndex socketType:
This event is send when a new connection was initiated (and not yet finished). Use the 'mouseMoved' event to do things during 'connection-dragging' and use 'LButtonUp' to know when a connection ended.
nodeIndex: the node from which the connection was made.
socketIndex: the socket from which the connection was made.
socketType: the type of socket (input:0, or output:1)
Functions
Please see the notes at the top of this page for instructions on how to use the functions (no brackets).
The difference between functions and properties are a bit vague in this control, so be sure to check both areas.
Generally, functions only return values or perform some task (read only), while properties can get and set values (read and write).
<SchematicControl>. redrawView:
Redraws the entire SchematicControl view.
<SchematicControl>. redrawNode:
Redraws the Active Node.
<SchematicControl>. getNodeCount:
Returns the total number of nodes in the view (integer).
<SchematicControl>. findNodeByPos = Point2:
Pass it a Point2 (usually mouse position) and the schematic will return the node index at that position. -1 is no node was found (integer). This is used to do hitchecking to see what node is at the current mouse position.
<SchematicControl>. addNode:
Add a new node to the schematic. Returns the index of the newly added node (integer).
<SchematicControl>. deleteActiveNode:
Delete the active node from the schematic (via maxscript). Returns true of false (boolean).
<SchematicControl>. getSelectionCount:
Returns the number of nodes selected in the view (integer).
<SchematicControl>. deleteActiveSocket:
Deletes the Active Socket of the Active Node. Returns true of false (boolean).
<SchematicControl>. getSocketCount:
Returns the socket count of the Active Node (integer).
<SchematicControl>. toggleConnection = Point2 :
Creates a new connection from the Active Node and its Active Socket to the node and socket specified in the Point2.
Example:
s.toggleConnection = [targetNodeIndex,targetInputSocketID]
Note:
The Active Node must always be the Node with the OUTPUT socket.
The Active Socket must be an Output Socket.
If a connection already exists, toggleConnection will remove the existing connection.
Please note that the schematic makes no attempt to prevent cyclic problems (child is wired into parent and parent into child).
It is up to you to prevent this, if that is a concern for your tool.
<SchematicControl>. getActiveSocketType:
Returns the type of the active socket. 0 if the socket is an input socket, 1 if its an output socket, -1 if there was no active socket (integer).
<SchematicControl>. getActiveSocketConnectingNodeIndices:
Returns an array of node indices to which the active socket is connected (integers). Please note that a node index might be returned more then once in this array, since there might be multiple connections between the active socket and the connecting node.
<SchematicControl>. getActiveSocketConnectingSocketIndices:
Returns an array of socket IDs to which the active socket is connected (integers).
Note:
Socket IDs are unique per node, but two different nodes may have a socket with the same index.
<SchematicControl>. addInSocket:
Creates a new in socket to the Active Node.
<SchematicControl>. addOutSocket:
Creates a new out socket to the Active Node.
<SchematicControl>. getSelectedConnectionIndex:
Returns the index of the selected connection of the active socket on the active Node. Returns 0 if no connection was selected.
The active Node is the Node with the Outsocket of the connection, the active socket is the outSocket.
<SchematicControl>. getChildCount:
Returns the number of children the activeNode has.
<SchematicControl>. childIndex = Integer :
Returns the schematic node index of the provided child (index)
Example:
s.childIndex = 1
Note:
The above example will return the node index of the activeNode's first child.
<SchematicControl>. getConnectionWeight = Integer :
Returns the connection weight of the provided connection index. The weight is an integer.
Example:
s.getConnectionWeight = 1
Note:
The above example will return the connectionWeight of the activeSocket's first connection.
Do not forget to set the activeNode and activeSocket.
<SchematicControl>. setConnectionWeight = Point2 :
Set a new weight value for the provided connection. The weight must be an integer.
Example:
s.setConnectionWeight = [2, 75]
Note:
The above example will set the connectionWeight of the activeSocket's second connection to 75.
Do not forget to set the activeNode and activeSocket.
<SchematicControl>. getSelectedConnectionNodeAndSocket:
Returns a point2 that holds the node index and socket index of the selected connection. (There can only be one selected connection per graph). Returns false if no connections were selected.
<SchematicControl>. getDeletedNodeCount:
Returns the number of nodes deleted since the last time the 'nodesDeleted' event was sent to maxscript. Use this incombination with 'getDeletedNodeIndex'.
<SchematicControl>. getDeletedNodeIndex: = Integer :
Returns the index of the delete node. The Integer you provide is in order the nodes were deleted. So you can for loop through 'getDeletedNodeCount' to get all indices that were deleted.
<SchematicControl>. setRenderBall Material
Set the bitmap of the active node to display the 'renderball' of the provided material. This is a 'one time' grab. If the material updates, you must call this again. Size of renderball bitmap is 88x88, use bitmapSize to adjust nodeBitmap to this size. You MUST have called 'nodeBitmap' before using setRenderBall or no bitmap will be displayed. Simply provide a new (empty) bitmap to nodeBitmap before calling this function.
Properties
<SchematicControl>. width Integer
Set the width of the schematic control
<SchematicControl>. height Integer
Set the height of the schematic control
<SchematicControl>. pos Point2
Set the position of the schematic control
<SchematicControl>. allowUIDelete Boolean
Whether to allow nodes/connections being deleted via the UI (delete button) or not (in which case they can only be deleted via Maxscript)
<SchematicControl>. allowZoom Boolean
Whether to allow the view to be zoomed
<SchematicControl>. allowPan Boolean
Whether to allow the view to be panned
<SchematicControl>. activeNode Integer
Get/set the index of the Active Node. This is the node most functions use to operate on.
<SchematicControl>. selectedNodeIndex Integer
Get/Set the index of the selected node. Returns -1 if no node is selected. If multiple nodes are selected, the last created node that is selected will be returned.
<SchematicControl>. nodeName String
Get/set the name of the Active Node. Node labels can be multi-line by adding '\r\n' at the end of each line.
<SchematicControl>. nodeBitmap Bitmap
Set a bitmap for the Active Node. Note that bitmaps are not saved with the max scene. There is currently no GET method.
<SchematicControl>. activeNodePos Point2
Get/set the position of the Active Node. The position is relative to the position of the SchematicControl. So a position of [0,0] means the node will be in the top left of the schematic.
<SchematicControl>. activeNodePosRelative Point2
Get/set the position of the Active Node, but relative to the view's zoom and pan. The position is relative to the position of the SchematicControl. So a position of [0,0] means the node will be in the top left of the schematic.
<SchematicControl>. activeNodeCollapsed Boolean
Get/set collapsed state of Active Node. A collapse Node hides the sockets and bitmap.
<SchematicControl>. nodeColor Color
Get/set the color of the Active Node. A completely black color (color 0 0 0) makes the inside of the node transparent. Other nodes may still be drawn on top, so usually transparent nodes should be added last to the schematic so that they are drawn on top.
<SchematicControl>. nodeSize Point2
Get/set the size of the Active Node.
<SchematicControl>. isHidden Boolean
Get/set hidden state for the Active Node. A hidden node is not drawn and cannot be selected in the UI.
<SchematicControl>. bitmapPath String
Get/set a path for the bitmap for the Active Node. This path is NOT used by the Schematic Control to automatically load images from disk (you control loading bitmaps on the maxscript side). You can use it to re-find your bitmaps on a reLoad or rollout open for example (optional).
<SchematicControl>. sceneNode Node
Get/set a max scene Node for the Active Schematic Node. The max scene node is not used by the Schematic Control, but this option could aid you in making schematic scripts that represent max scene nodes (Optional).
<SchematicControl>. activeSocket Integer
Get/set the active socket for the Active Node.
<SchematicControl>. socketName String
Get/set the name of the active socket on the Active Node.
<SchematicControl>. activeSocketFlipped Boolean
Get/set the flipped state of the active socket on the Active Node. A flipped socket will drawn on the opesite side (left vs right).
<SchematicControl>. activeSocketValue Float
Get/set the value of the active socket on the Active Node. If you assign a .sceneController to the socket the scene controller value is displayed in the view instead (if controller superclass is float), HOWEVER 'activeSocketValue' still returns the value previously stored and not the controller's value. If you want to get the value of the controller instead, you would use .sceneController to get the controller, then use .controller.value to use it's value.
<SchematicControl>. activeSocketShowValue Boolean
Get/set whether to display the value of the active socket on the Active Node or not.
<SchematicControl>. sceneController Controller
Get/set a scene controller for the active socket on the Active Node. The Schematic Control does not use this controller, but it might aid you in writting controller related scripts. If you assign a controller to an output socket, the controllers value will be shown in the schematic view if the controller is of superclass float.
<SchematicControl>. nodeInfo String
Store custom information on active node. You may use this to store anything, for example a sub-class you made up or perhaps a function you want to run when the node is selected.
<SchematicControl>. pan Point2
Get/set pan of view.
<SchematicControl>. zoom Float
Get/set zoom of view.
<SchematicControl>. socketPosition Point2
Get/set position of active Socket. Normally the socket position is controlled by helium, but if you wish, you can override it.
<SchematicControl>. posLocked Boolean
Get/set wheter the active node is position locked. When true, the node cannot be moved. Useful for simulating nodes as buttons.
<SchematicControl>. nodeNameOffset Point2
Get/set position OFFSET for node name label. An offset of [0,0] will draw the node at the top-center of the node. This can be used when you start setting custom positions for sockets and you wish to move the node label. Setting any value higher then [x,5] will stop drawing the node's menubar.
<SchematicControl>. connectionColor Color
Get/set connection (line) color for active output socket. Note setting this property for in-sockets is useless as the outsocket determines the color of the connection line.
<SchematicControl>. isSelected Boolean
Get/set wheter the active node is selected.
<SchematicControl>. selectable Boolean
Get/set wheter the active node can be selected via the UI. This can be useful to make a node act as a groupbox for custom UIs. Set the color of the node the same as the max background and make it not selectable.
<SchematicControl>. socketLabelOffset Point2
Get/set position offset for active socket label. If this is [0,0] the label is drawn on the right or left side of the socket.
<SchematicControl>. nodeCollapsedSize Point2
Get/set size for active node when it is collapsed.
<SchematicControl>. edgeSize Float
Get/set size for active node rounded edges. A smaller value makes the edges more square. Note if you set the node width and height the same as the edgeSize, you will get a circle.
<SchematicControl>. socketDataClass String
Get/set socket data class for active Socket. This is not used internally in helium, but it allows you to check what type of data (class) the input and output sockets can handle. This class string is also shown when you try to make a new connection.
<SchematicControl>. showBitmapOnly Boolean
Get/set show bitmap only state of active node. If true, only the bitmap of the node is shown, this allows you to fully customize the look of your nodes. Please note that also the in and out sockets are not drawn although the node can still have sockets. You can visualize the sockets in your bitmap and place the helium sockets (now hidden) in the same location as where the sockets are in your bitmap (use socketPosition to move your sockets around).
<SchematicControl>. isCollapsible Boolean
Get/set collapsible state of active node. If you do not want a node to be collapsible (for example if you used showBitmapOnly) you can set this to false and double clicking on the ndoe will be ignored.
<SchematicControl>. backgroundBitmap Bitmap
Set background image for view. There is currently no GET method.
<SchematicControl>. backgroundPath String
Get/set path string for background image. The background image is NOT automatically reloaded when the max file is re-opened. You can use this path to reload the background image automatically on for example a 'rollout open' event using openBitmap().
<SchematicControl>. tileBackground Boolean
Get/set tiling of the background image.
<SchematicControl>. parentNode Integer
Set the parent (index) for the activeNode. The activeNode will move relative to its parent node. The parent is simply another node in the schematic. You could use 'isHidden' on the children to simulate grouping of nodes. Use a value of 0 to unlink from the parent. Please note that the schematic makes no attempt to prevent cyclic problems (child is parent of its parent). It is up to you to prevent this, if that is a concern for your tool.
<SchematicControl>. showInfo Boolean
Hide / unHide copyright information at the bottom right of the view.
<SchematicControl>. drawConnectionsFromParent Boolean
If a node is hidden but it has a parent node, this settings controls wheter to draw the connections of the hidden node from the parent. This is useful when you simulate grouping by parenting and hidding the children, however you still want to see the connections.
<SchematicControl>. socketInfo String
Store custom information on active socket. You may use this to store anything, for example connection data.
<SchematicControl>. drawWeights Boolean
Get/Set wheter to draw weights for connections. Defaults to false.
<SchematicControl>. allowRegionSelect Boolean
Get/Set wheter Region Selects can be made in the UI.
<SchematicControl>. textAlign Integer
Get/Set alignment of the active node label. 1=left, 2=center, 3=right.
<SchematicControl>. bitmapSize Point2
Get/set size for active node bitmap. The default size is 80x80.
<SchematicControl>. socketIsHidden Boolean
Get/set active socket hidden state. When a socket is hidden, no node size adjustment is made. If you want to change the node size when hidding a socket, you must call nodeSize. The default height of a socket is 16, so you can subtract 16 from nodeSize.y for each hidden socket.
<SchematicControl>. drawShadows Boolean
Get/Set drawing of node shadows. Default to false, so no shadows are drawn by default to be compatible with older versions of helium.
<SchematicControl>. drawLastIndex Integer
Get/Set the index of the node that should be drawn last. This is useful if you want to make sure that for example the selected node is always drawn on top.
<SchematicControl>. drawMenuBars Boolean
Get/Set wheter menubars are drawn at the top of each node. This defaults to false to stay compatible with older scripts. Menubars are not drawn for transparent nodes or nodes that have their node label moved down by more then 5 units.
<SchematicControl>. drawSeperator Boolean
Get/Set wheter a seperator line is drawn above the active socket. This allows you to visually group sockets together by placing seperator lines between sockets that do not belong together.
<SchematicControl>. zoomAboutMouse Boolean
Get/Set wheter zooming happens around the mouse cursor. This defaults to true, so zooming may have a different behaviour then in older versions
<SchematicControl>. nodeTransparency Float
If set to 0.0 or higher, nodes will be drawn with that amount of transparency. Set to -1.0 when not using transparency (default).
<SchematicControl>. setInfo String
This allows you to set the text that is displayed at the bottom right of the screen. (ShowInfo must be set to true for this text to show up)
<SchematicControl>. viewAlign Integer
By providing a value of -1, the node will be locked to the top-left side of the view. +1 will lock the node on the top right. 0 is the default and does not lock a node, so it can be moved.
<SchematicControl>. viewAlignOffset Point2
Allows for additional offset to be added to the View Aligned node (so it can be moved around and still be locked to the view)
<SchematicControl>. showMiniBitmap Boolean
Set/Get if the active node should show a mini-bitmap when collapsed or not. Defaults to true, so all nodes show a mini-bitmap when collapsed.
<SchematicControl>. drawLayer Integer
Set/Get the layer this node will be drawn on. You must set 'useDrawLayers' to TRUE for the schematic for this to be used. There are 3 layers, background=1, middle=2 (default) and foreground=3.
<SchematicControl>. useDrawLayers Boolean
By default nodes are drawn in the order they are created. Setting this to TRUE will allow you to specify a layer for each node to control the draw order. See 'drawLayer'.
How To Use the UI:
Hold down the middle mouse to pan.
Scroll the middle mouse to zoom.
Click on a node to select it, use ALT and CTRL to remove or add to your selection.
Click and drag to make a selection rectangle.
Double Click on a node to collapse it (unless 'collapsible' is set to false for that node)
If .AllowUIDelete is true, you may use the DEL button to delete nodes directly via the UI.
SHIFT click on a socket to flip it to the other side.
ALT-click on an input-socket to hide all it's inputs, CTRL-click to unhide.
Middle-click and drag on an output-socket to change it's value (hold CTRL to change it faster).
Generally a scripted right-click menu (RCMenu) is used to allow you to add new nodes and change their properties.
You must script this RCMenu yourself.
See Helium_Menu.ms for details on how to set one up for your scripts.
Information
Copyright, © Kees Rijnen, support@lumonix.net, www.lumonix.net
Special Thanks go to Larry Minton, Rejean Poirier, www.maxplugins.de, Bobo, plus all beta testers.