Object
RubyEdit is the class on which the RubyEdit primitives themselves are based. As such, it is not a class of object that you would ever create your own instance of - the editor you see on screen is the instance.
A RubyEdit instance acts as a 'sandbox' for the variables and methods that you define within it - allowing multiple RubyEdits to be used in a schematic without any crosstalk between them. The only time that this is not true is when declaring a new Class or Module, as new classes and modules are always created in the 'global namespace' and so are visible to all RubyEdit instances.
Many of the methods documented below are what are known as 'call-backs'. These methods do not exist as part of a newly created RubyEdit instance. Rather, they are methods that you define yourself, which FlowStone will look for and call when certain events take place. The documented method definitions simply set out what arguments each method should take so that they can be called successfully by FlowStone. 'Callback' methods will be indicated in the documentation for each one.
It is not necessary to define any of these methods at all. A RubyEdit with no methods defined will have all of its code executed every time there is a trigger at any of the primitive's inputs. For simple 'one-liner' codes (e.g. a simple maths equation), this may be sufficient. But if you need different behaviour depending on the input that was triggered, or the primitive defines a GUI, you will need to define these methods in order to take control.
To make referencing inputs, outputs, and the RubyEdit instance itself easier, each RubyEdit is created with several instance variables already defined...
@in Accesses the data at the first (uppermost) input connector of the primitive. This variable should be considered read-only, and should not have new value assigned within the instance's code. The class of the returned value will depend on what data type the input has been set to.
@ins Accesses an Array of all input connector values for the primitive. This variable should be considered read-only, and not have new values set from within the code. As with all Ruby arrays, the data is zero-indexed. i.e. index zero returns the value of the first input connector, index one, the second, etc... The Ruby class of each value will depend on the data type to which each connector is set.
@outs Accesses an Array of all of the primitive's output connector values (zero-indexed as for @ins. New values can be set by writing them to the appropriate Array index - however this will not send a trigger to the output; the data would have to be explicitly read by, for example, triggering a 'sample and hold' primitive connected to the output. To send a value complete with trigger, the output method should be called.
@this Contains a reference to the RubyEdit instance itself. This could be sent via a 'Ruby value' output to another RubyEdit instance to enable another instance to call methods within this one. However, this is not advisable, as unique instance IDs are randomly chosen each time FlowStone is started; rendering the reference invalid when stored input and output values are loaded at startup.
Connector labels If you give the connectors on your RubyEdit names, an instance variable with the same name will be created for each one. This can make the code much easier to read than referencing @ins or @outs by index. Take care that the labels you choose will generate valid Ruby instance variable names - they cannot include spaces (use underscores instead) or punctuation characters. 'Standard' Ruby practice is that instance variable names are all lower-case, and use 'snake_case' - though this is not enforced by the interpreter's parser. You do not need to include the '@' character in the label (though you must in the code itself!).
As there is not a direct correspondence between the 'green' FlowStone data types and classes of Ruby object, some care is needed when reading inputs and setting outputs. However, FlowStone will do its best to translate values to make them compatible. For example, if you send an Array of float values to an output connector that is set to be a 'green' integer array, the values will all be rounded to integers. If translation cannot be done, a default 'empty' value will be used - i.e. zero for numeric values, or empty Strings and Arrays.
Note however, that there will be some CPU overhead for doing this translation, so if you are only ever sending the value to another RubyEdit, using a Ruby Value connector may make your schematic a little more efficient.
Take care with this though - Ruby Value connectors do not send a copy of the object, they send a reference to the object itself. For example, if you send an Array via a Ruby Value connector, and change the Array contents in one of the connected RubyEdit instances, it will change the Array in all of them!
Here is a list of the allowed FlowStone data types and how they translate into Ruby objects...
Integer -> Fixnum Fixnum is a type of Integer; simply one that is limited to 32bit values, as are the green integers. The method call is_a?(Integer) would return true.
Float -> Float Floats simply become floats. However, bear in mind that 'green' floats are only 32bit (single) precision, whereas Ruby Floats are 64bit (double) precision. This can be useful if you need to do some calculations where extra precision in 'intermediate' values would yield a more precise or reliable result. The 64bit values are rounded automatically when sent to an output connector.
String -> String Strings are passed unchanged. The only thing to be careful of is line breaks in multi-line strings. For best reliability line breaks should use carriage-return followed by new-line ("\r\n").
Boolean -> TrueClass/FalseClass In Ruby, boolean true and false are two entirely separate classes of object, so the appropriate one will be chosen depending on the current state of the input. When sending a value to a boolean output, the special Ruby values 'false' and 'nil' will output false, any other value/Object is taken to represent 'true'.
Integer Array -> Array Ruby arrays are not choosy about what they contain, so an integer array simply becomes an Array object that just happens to be full of Fixnum objects. When sending a Ruby Array to an integer array output connector, FlowStone will attempt to convert every array item into a 'green' integer, or to zero if this is not possible.
Float Array -> Array Ruby arrays are not choosy about what they contain, so a float array simply becomes an Array object that just happens to be full of Float objects. When sending a Ruby Array to a float array output connector, FlowStone will attempt to convert every array item into a 'green' float, or to zero if this is not possible.
String Array -> Array Ruby arrays are not choosy about what they contain, so a string array simply becomes an Array object that just happens to be full of Strings. When sending a Ruby Array to a string array output connector, FlowStone will attempt to convert every array item into a 'green' strings, or an empty string if this is not possible.
Trigger -> nil Trigger inputs have no inherent value, so are converted to a Ruby 'nil'. However they do generate Ruby events which can execute code from an 'event' method.
View -> View View inputs also act as a kind of output. Whenever a Ruby defined GUI needs re-drawing, an empty 'View' object (a special FlowStone Ruby class) is delivered to the input, which the Ruby 'draw' method will fill with graphics (assuming that 'draw' has been defined).
Area -> Array In Ruby, a view area is nothing more than an Array containing four float values, in the order x-position, y-position, width, height. Sending an invalid value to an Area output will output a 'null' area [0.0, 0.0, 0.0, 0.0].
Color -> Color Direct translation to a FlowStone Ruby Color object (NB - watch the spelling if you are used to UK English!).
Pen -> Pen Direct translation to a FlowStone Ruby Pen object.
Font -> Font Fonts are turned into the special FlowStone Ruby Font class of objects.
String Format -> StringFormat String format connectors become the FlowStone special StringFormat class. However, note that 'green' formats do not include all of the features available to a Ruby format (most of the special 'flags').
Bitmap -> Bitmap Direct translation to a FlowStone Ruby Bitmap object. (see the Connector Storage section below for some special notes).
MIDI -> Midi Direct translation to a FlowStone Ruby Midi object. A Midi object can contain either a 'standard' three byte MIDI message (e.g. notes, controllers) or a SysEx message.
Ruby Value -> Object A Ruby value connector can take almost any kind of Ruby object and pass it between RubyEdit instances. There are a handful of exceptions to this, however. For more details, see the 'Connector Storage' section below.
Editors Note: A couple of connector types still to document, as I have yet to use them!
By default, FlowStone will store the current values of each connector when you save your schematic, and will restore them the next time it is loaded. This is safe for all 'green' data types. However, it can fail for 'Ruby Value' connectors. Storing a Ruby object depends on a feature called 'Marshalling' - a way to take the data about the object and turn it into a String that perfectly describes the object. However, this feature is not written into every Ruby class, and there are some kinds of Object that inherently just can't be stored. For user-defined classes, you would have to write this ability into the class yourself - but there is not room here to show how (hint: you need to look into the standard Ruby 'Marshal' module). These rules also apply to any objects that you might want to store between sessions using the saveState and loadState methods of the RubyEdit.
Here is a list of the most common exceptions to the rule.
Bitmaps Because bitmaps can take up so much memory, Bitmap connectors are cleared of all their data when you close a schematic. However, bitmap primitives do retain their data. Connect an 'after load' primitive to the same RubyEdit input as the bitmap to 'push' the bitmap data into the RubyEdit primitive at load time. Note that this means that the bitmap data will not be available to your code after a loadState method, and you may need to watch that 'pushing' the data does not execute unwanted code from your event method if you have one.
RubyEdit While you can send a reference to the RubyEdit instance to other RubyEdits so that they can call each other's methods, this is not advised, as their unique identities are re-defined every time you load the schematic, rendering the old references invalid.
Proc A 'Proc' object is a way to store a block of code as an object that you can treat like a variable. However, any object containing such a block of code can never be stored between sessions, as the addresses in memory of the code and the variables that it contains are determined by Windows when the application is started, and Ruby does not get to choose!
Brushes, Gradient brushes, GraphicsPaths These classes do not have Marshalling defined, so they cannot be stored between sessions.
Views A new view is created and filled with GUI objects each time there is a screen re-draw. In fact, you should not attempt to store a View object in a persistent (global, class or instance) variable at all, as it is only valid when FlowStone passes it as an argument to a 'draw' method - though you may forward the value as an argument to other methods which are called from 'draw'.
Returns a String containing the caption for the RubyEdit - this is the title label that you can set at the top of the primitive (or from the 'N' icon on the bottom context menu).
# File Flowstone API.rb, line 584 def caption #DUMMY end
Instructs the RubyEdit to take possession of the mouse - the mouse will no longer send events to other RubyEdits or other application windows.
This is intended for mouse dragging operations using the mouseMoveCaptured method, so that dragging can be done without interference from other GUI objects and areas.
It is crucial to remember to call the releaseMouse method once the drag operation is done, otherwise the mouse may become unresponsive.
Also see releaseMouse, mouseMoveCaptured and mouseLUpCaptured.
# File Flowstone API.rb, line 838 def captureMouse #DUMMY end
If you have used input or output to schedule future events, this method will clear all of the ones that are still pending. Note that this applies only to the RubyEdit that makes the call, events for other RubyEdits are not affected in any way.
# File Flowstone API.rb, line 609 def clearEvents #DUMMY end
When this method is called, a drop list will be drawn on the screen with customisable items of which the user can select only one by clicking on it.
As the argument list is rather long, the optional arguments are not shown in the call signature - but all arguments are listed below in the order that they should be given. The list may be terminated at any position within the optional arguments, but the required ones must be given.
connector The RubyEdit connector containing the GUI on which the drop list should be drawn. (required)
id An integer identifier to help tell this drop list apart from any others which may already be open. (required)
position An Array giving the top-left corner from which the drop list should be drawn. The first two array items only are used, to give the x and y positions respectively. (required)
items A comma separated String giving the list of items from which the user may select - more details below. (required)
checked The integer index of an item in the list which will have a small tick drawn beside it to represent the currently selected item. (optional)
style A String or Integer specifying how the list items should be formatted.
"scroll" - long lists will be shown in a small area with a scroll bar.
"autocol" - long lists will be automatically divided into columns.
Integer - long list will be divided into columns with this number of items.
disabled - Integer index of an item that should be 'greyed out' as unavailable. This does not prevent the user from clicking on it!
If the items list is a simple list of words or phrases separated by commas, they will be shown as a single long list of items. It is also possible to have nested lists of items which 'fly out' whenever the user hovers the mouse over a 'parent' item. This is done using two special strings; "<<" and ">>". This works as follows...
"One, Two, Three, Four" builds this list... One Two Three Four "One, Two, <<, Two A, Two B, >>, Three, Four" builds this nested list... One Two -----> Two A Three Two B Four In the second version "Two" is taken as the 'parent' of the items between the "<<" and ">>". The items between those 'brackets' won't be visible until the mouse is hovered over the "Two" entry - then a 'sub-menu' will fly-out containng just those two items, and the user is able to select them. When the user selects an item, an index is returned. Parent items and the 'brackets' do not count towards this index. So, in this case there would be five selectable items, indexed like this... One -> 0 Two A -> 1 Two B -> 2 Three -> 3 Four -> 4
There is no limit to the number of nested lists allowed within the main list, It is even possible to nest lists within other nested lists, just as you might with parenthesis in a mathematical expression.
See also dropListFinished
# File Flowstone API.rb, line 1076 def createDropList #DUMMY end
Creates a text editor window into which the user can type. The editor will close when the user presses 'enter' or clicks the mouse outside of the editor.
The above call-signature is abbreviated as there are rather a lot of optional arguments. The complete list is shown below in the order that they must be given. As long as the first three required arguments are given, you may end the argument list at any point, but you cannot omit an optional argument from part way through the list and then continue.
connector The integer index of the view connector containing the GUI that you want to draw the edit box on. (required).
id An integer number used to identify this specific edit box in cases where another RubyEdit might have one open. (required)
area An array containing four floats giving the x position, y position, width and height of the edit box. (required)
start_text The text that should appear in the edit box when it is first opened. An empty edit box is created if this is not given. (optional)
font A Font object giving the text font and style for the edit box. Normal Arial text is assumed if not given. (optional)
text_color A Color object giving the colour of the text characters. (optional)
back_color A Color object giving the colour of the box background. (optional)
multiline May be true or false. If true, the user may edit across multiple lines, otherwise only a single line is allowed. (optional)
Note that, when an edit box closes, it disappears and its screen area is cleared. If the entered text needs to remain visible, this must be done explicitly in the draw method.
See also editChanged and editFinished
# File Flowstone API.rb, line 963 def createEdit #DUMMY end
Called whenever a view connector to the RubyEdit requests a redraw, or when you call the redraw method from within your code. The view connector should be linked to the view output of an MGUI primitive.
If only a View parameter is given, it assumes that you have a single view connector at the top-most input. If you have multiple View connectors, use the second form - the input parameter will then tell you which input requested the redraw (always an integer index). Your draw routine can then switch between different drawing routines depending which input needs a redraw.
Example:
# Normal usage - a single View connector. def draw(view) # Fill the view with black area = [0.0, 0.0, view.width, view.height] brush = Brush.new(Color.new(0)) view.drawRectangle(brush, area) end # Multiple views (assume view connectors on the top two inputs) def draw(in_id, view) area = [0.0, 0.0, view.width, view.height] if in_id == 0 # Fill the view with black brush = Brush.new(Color.new(0)) view.drawRectangle(brush, area) elsif in_id == 1 # Draw a white ellipse in the other view brush = Brush.new(Color.new(255)) view.drawEllipse(brush, view) end end
# File Flowstone API.rb, line 517 def draw() #DUMMY end
This method is called when the user selects an item from a drop list. The integer id is used to identify the particular list, and will be the value given when the list was created using the createDropList method.
The Integer index denotes which item in the list was selected - a description of how items are indexed can be found in the createDropList notes.
The String text contains the text of the item that was selected.
See also createDropList
# File Flowstone API.rb, line 1097 def dropListFinished #DUMMY end
This method is called whenever the users types a new character or deletes one from a text edit box.
The id is an integer to identify the specific edit box - the one given when the edit box was created by the createEdit method. Use this to ensure that you are responding to the correct editor.
The String text will be the current content of the edit box.
See also createEdit and editFinished
# File Flowstone API.rb, line 983 def editChanged #DUMMY end
Called when the user finished editing within an edit box by pressing 'enter' or clicking the mouse outside the edit box.
The id is an integer to identify the specific edit box - the one given when the edit box was created by the createEdit method. Use this to ensure that you are responding to the correct editor.
The String text will be the current content of the edit box.
See also createEdit and editChanged
# File Flowstone API.rb, line 1003 def editFinished #DUMMY end
If you define a method event, it will be called each time an input connector receives a trigger, or a Ruby event from an input method call. You can include up to three parameters (which do not have to have the same names as shown here)...
connector A RubyEditConnector object that identifies which connector received a trigger. Connectors can be identified either by their index, or by their label.
value The new value that just got sent to the input.
event_time The time, in seconds since startup, that the event was received. Do not use time for the name of this argument, as it will be confused with the time method.
You can only include parameters (or not) in the four styles listed above, chosen according to which ones your event handler needs to use.
Example:
# Simple demo that shows all possible data about the most recent # input event. def event(in_id, value, event_time) watch "Input index", in_id.index watch "Input name", in_id.name watch "New value", value watch "Time (s)", event_time end # Filtering data so that you can choose the action can be done either # using 'if' statements... def event(in_id, value) if in_id == 0 watch "Input zero just got new data" elsif in_id == "reset" watch "I've just been triggered by the 'reset' input" elsif in_id == "set_value" @my_value = value else watch "What input is this?" end end # ...or you could use a 'case' statement (which I always think looks # prettier! def event(in_id, value) case in_id when 0 watch "Input zero just got new data" when "reset" watch "I've just been triggered by the 'reset' input" when "set_value" @my_value = value else watch "What input is this?" end end
# File Flowstone API.rb, line 386 def event() # DUMMY end
Returns an array containing two floats that give the size of a view directly from its input connector. The format is always...
[width, height]
If no argument is given, the top input connector is assumed - otherwise you may give the integer index of any input that is of the view type.
This method allows you to find out the size of a view even if you are not inside a draw method where a View object is available directly.
The size is always given in 'grid' units (8 pixels by default - as per the FlowStone editor's 'graph-paper' background).
# File Flowstone API.rb, line 573 def getViewSize #DUMMY end
If an init method is defined it will be called...
When a schematic, VST or EXE is first loaded.
Each time you edit the code in the RubyEdit.
If you explicitly call init in your code.
Upon loading, init is always called before anything else happens in your schematic - that is...
Before any loadState method
Before stored input and output connector values are loaded
Before the Ruby event scheduler starts
Before the green trigger system starts
Before audio streams are started.
This means that you must take care not to refer to any variables that will not have been defined yet (e.g. the value of an input connector).
Init is very useful for defining any values which must have a definite start state, or are unlikely to change while the code is running. For example, it is a good place to define Colors, Brushes, Fonts etc. for a GUI draw method if you do not need them to be customisable from user input.
Remember however, that for values in init to be usable by other methods in your code, you must define them as @instance variables, and not as local ones (without the '@')!!
# File Flowstone API.rb, line 418 def init #DUMMY end
Send a value to an input connector of the same RubyEdit instance at some point in the future. The RubyEdit behaves exactly as if the input had been triggered by a trigger at an input connector. This can be used to define timers and tickers that will generate accurately timed events at a chosen rate. In this case the connector does not actually have to exist, so long as the event will execute some code within the event method of the RubyEdit. Extreme care should be taken when setting the time - it is an absolute time counted in seconds from when the RubyEdit was started. To schedule a future event, an offset must be added to the current time given by the time method. If this is not done, the event is sent immediately, and the Ruby event queue will rapidly overflow - leading to the dreaded "Ruby lock-up".
For example...
input 100, "Hello", time + 0.5 #=> Sends "Hello" to input 100, half a second from now. Input 100 is #=> unlikely to be a real connector - but so long as the 'event' method #=> defines an action for input 100, something will still be executed.
# File Flowstone API.rb, line 262 def input() # DUMMY end
If the RubyEdit has a View input that is linked to an MGUI, this method gets called whenever the mouse is moved over the view. The two arguments give the position of the mouse relative to the top-left corner of the view, measured in grid units.
The method should return true or false to indicate whether the given x, y position contains an active element which the user should be able to click or drag with the mouse.
If the method replies false, then no other mouse call-back methods will be called for the given position and the standard cursor icon will always be displayed.
# File Flowstone API.rb, line 631 def isInMousePoint #DUMMY end
Returns whether or not a specific key on the keyboard is currently pressed.
The String argument defines which key to test - note that for most keys, you should give the single character that the key would produce if it were pressed without any modifier keys.
The common 'non-character' keys can be tested by giving one of the following multi-character strings...
"Shift"
"Control" or "CTRL"
"Alt"
"Space"
"Up" or "Arrow Up"
"Down" or "Arrow Down"
"Left" or "Arrow Left"
"Right" or "Arrow Right"
Note that there is currently no way to get an automatic call-back when the user presses a key - this can only be done by using a timer or ticker to repeatedly poll the key to see if it is pressed.
# File Flowstone API.rb, line 924 def isKeyPressed #DUMMY end
Defining loadState allows data that was stored by saveState at the last saving of the file to be recovered automatically at load time. Only a single object can be recovered, however, this is easily worked around by storing an Array containing all of the desired data.
LoadState is called after any init method, but before the 'green' trigger system or audio streams come on line. This means that you can use init to set default values that will be overwritten if there is any saveState data, but will be used if there is no valid data.
Example:
def loadState(array) @my_data1, @my_data2, @my_data3 = array end # NB) Example assumes that 'array' is a Ruby Array that contains three # items of data (i.e. as stored in the 'saveState' code example.
# File Flowstone API.rb, line 473 def loadState(obj) #DUMMY end
This method will be called when the following conditions are met...
There is a view connector to the RubyEdit linked to an MGUI primitive.
There is an isInMousePoint method, and it returns true for the current mouse position.
The two arguments give the x and y location of the current mouse position relative to the top-left of the view, measured in 'grid' units.
The code should be written to return an integer corresponding to the mouse icon that you wish to display, or you may use a String describing the icon that is required. The following are recognised (see p.198 of the official User Guide for images of the resulting cursors).
0 or 'default' -> Diagonal 'hand' icon
1 or 'ibeam' -> Text insertion cursor ('I' beam)
2 or 'pointer' -> A normal 'arrow' pointer.
3 or 'handpointer' -> Hand with pointing finger.
4 or 'move' -> A 'cross' of direction arrows.
5 or 'pointeradd' -> Arrow pointer with a '+' icon.
6 or 'pointerdel' -> Arrow pointer with a '-' icon.
7 or 'smallpointer' -> A small arrow icon.
8 or 'resizeew" -> Double arrow east to west.
9 or 'resizens' -> Double pointer north to south.
10 or 'handopen' -> A hand with fingers splayed.
11 or 'handclosed' -> A hand with grasping fingers.
12 or 'crosshair' -> Small cross shaped pointer.
13 or 'deny' -> a 'no access' road sign.
# File Flowstone API.rb, line 666 def mouseCursor #DUMMY end
This is called when the following conditions are met...
There is a view connector linked to an MGUI primitive.
There is an isInMousePoint method, and it returns true
The user double clicked the left mouse button within the view.
The two parameters give the x and y position of the mouse relative to the top left of the view, measured in 'grid' units.
No return value is expected, you simply define what action should be taken when the user double clicks at the given position.
Note that mouseLUp and mouseLDown events may also be generated when the user double clicks, as the system cannot know that it is a double click until it has examined the timing of the button actions!
# File Flowstone API.rb, line 733 def mouseLDouble #DUMMY end
This is called when the following conditions are met...
There is a view connector linked to an MGUI primitive.
There is an isInMousePoint method, and it returns true
The user pressed the left mouse button within the view.
The two parameters give the x and y position of the mouse relative to the top left of the view, measured in 'grid' units.
No return value is expected, you simply define what action should be taken when the user clicks at the given position.
# File Flowstone API.rb, line 685 def mouseLDown #DUMMY end
This is called when the following conditions are met...
There is a view connector linked to an MGUI primitive.
There is an isInMousePoint method, and it returns true
The user released the left mouse button within the view.
The two parameters give the x and y position of the mouse relative to the top left of the view, measured in 'grid' units.
No return value is expected, you simply define what action should be taken when the user releases the mouse button at the given position.
Note that mouseLUp should not be used to end a mouse dragging operation, as it will not 'fire' if the drag has gone outside of the RubyEdit's view area. The method mouseLUpCaptured should always be used for this purpose (NB - this rather important point is not given in the User Guide!)
# File Flowstone API.rb, line 710 def mouseLUp #DUMMY end
This method is called only when the user releases the left mouse button to end a dragging operation.
This should always be used in preference to mouseLUp to end as drag, as it will be called no matter where the mouse is on the screen (mouseLUp would not be called if the drag were ended outside of the RubyEdits view area).
At some point in the method definition releaseMouse should be called to inform Windows that the drag has ended, otherwise the mouse may become unresponsive.
Also see captureMouse, releaseMouse and mouseMoveCaptured
# File Flowstone API.rb, line 896 def mouseLUpCaptured # DUMMY end
This method is called when the following conditions are met...
There is a view connector linked to an MGUI primitive
The MGUI primitive has its 'Mouse' input set to true
There is an isInMousePoint method, and it returns true
The mouse moves by at least one pixel while over the view.
The two parameters give the x and y position of the mouse relative to the top left of the view, measured in 'grid' units.
No return value is expected, you simply define what action should be taken when the mouse moves over the the given position.
Note that using this feature can use a lot of CPU, especially if you have multiple MGUI's with mouse moves enabled - hence the MGUI 'mouse' input is false by default.
# File Flowstone API.rb, line 819 def mouseMove #DUMMY end
This method is called only when the mouse has been 'captured' using the captureMouse method - i.e. the user is performing a drag with the mouse.
The two arguments give the x and y position of the mouse relative to the top left of the view, measured in 'grid' units. The mouse does not, however have to be over the screen area covered by the view - a captured mouse is 'possessed' by the RubyEdit until releaseMouse is called no matter where it is on the screen.
Also see captureMouse, releaseMouse and mouseLUpCaptured
# File Flowstone API.rb, line 874 def mouseMoveCaptured #DUMMY end
This is called when the following conditions are met...
There is a view connector linked to an MGUI primitive.
There is an isInMousePoint method, and it returns true
The user double clicked the right mouse button within the view.
The two parameters give the x and y position of the mouse relative to the top left of the view, measured in 'grid' units.
No return value is expected, you simply define what action should be taken when the user double clicks at the given position.
Note that mouseRUp and mouseRDown events may also be generated when the user double clicks, as the system cannot know that it is a double click until it has examined the timing of the button actions!
# File Flowstone API.rb, line 794 def mouseRDouble #DUMMY end
This is called when the following conditions are met...
There is a view connector linked to an MGUI primitive.
There is an isInMousePoint method, and it returns true
The user pressed the right mouse button within the view.
The two parameters give the x and y position of the mouse relative to the top left of the view, measured in 'grid' units.
No return value is expected, you simply define what action should be taken when the user clicks at the given position.
# File Flowstone API.rb, line 752 def mouseRDown #DUMMY end
This is called when the following conditions are met...
There is a view connector linked to an MGUI primitive.
There is an isInMousePoint method, and it returns true
The user released the right mouse button within the view.
The two parameters give the x and y position of the mouse relative to the top left of the view, measured in 'grid' units.
No return value is expected, you simply define what action should be taken when the user releases the mouse button at the given position.
# File Flowstone API.rb, line 771 def mouseRUp #DUMMY end
Sends a value to a RubyEdit output connector. If only a value is given, it is sent to the first (uppermost) output. If a connector is given, this should be either an Integer (zero being the top output), or a String that matches the output's label.
When no time is given, the output is sent immediately. If a time is given the output is added to a queue, and will be output at the allotted time. Be careful when setting the time - it is an absolute time, counted in seconds, since the RubyEdit was created. So to schedule the event for a future time, you must add an offset to the current time given by the time method. You cannot give a time unless the connector is also specified. The event will be sent immediately if the given time is at or before the current time.
For example...
output "Hello" #=> Sends "Hello" to the first output output 1, "Hello" #=> Sends "Hello" to the second output. output "greeting", "Hello" #=> Sends "Hello" to an output labelled "greeting" - no action if this #=> label does not exist. output 1, "Hello", time + 0.5 #=> Sends "Hello" to the second output half a second from now.
# File Flowstone API.rb, line 234 def output() # DUMMY end
Undocumented in the offical User Guide. If the RubyEdit is within a FlowStone module, it returns the name of that module as a String. It is included only for completeness, as it is not always reliable, and can even cause crashes!
# File Flowstone API.rb, line 597 def parent # DUMMY end
Requests that a GUI associated with this RubyEdit gets redrawn - this will call the draw method if it has been defined.
Without arguments, it assumes that the top input connector is the view to be redrawn. If a connector is given (Integer index), and that connector is of View type, that is the view that will be redrawn (see the example for draw for how this is passed to the drawing method). If an area is specified, this should be an array containing four floats...
[x-position, y-position, width, height]
...in this case, only the given area of the view gets redrawn, and it is assumed that the rest of the view is unchanged. Note that drawing is usually anti-aliased, which means that the actual area re-drawn will extend slightly beyond that given (typically by 1 to 2 pixels in each dimension). The area is always given in 'grid' units (8 pixels by default - as per the FlowStone editor's 'graph-paper' background).
Typically, you would call redraw only when you know that the graphics of the GUI have changed (e.g. moving a control). However, when inside the FlowStone editing environment, there will be other redraws generated when you navigate around your schematic; so don't rely on your coded redraws being the only ones!
Also note that redraws are one of the most expensive operations, CPU wise, that FlowStone has to handle - so consider carefully how you might keep the number of redraws to a minimum. For example, did your control actually move, or did the user just click on it without ever dragging?
# File Flowstone API.rb, line 553 def redraw #DUMMY end
If the mouse is currently 'captured' by the RubyEdit for a mouse dragging operation, calling releaseMouse will hand control back to the usual Windows' handlers.
If releaseMouse is not called at the end of a drag operation, the mouse may become unresponsive!!
Also see captureMouse, mouseMoveCaptured and mouseLUpCaptured.
# File Flowstone API.rb, line 854 def releaseMouse #DUMMY end
Defining saveState allows you to store the values of instance variables within the RubyEdit whenever you save your schematic. These can then be automatically loaded by the loadState method when you re-open the project, or an exported VST/EXE starts up. To work correctly, you must ensure that saveState returns a single Ruby object containing all of the data that you want to store. If you need to store multiple values, the simplest way is by placing them inside an array.
NOTE see the 'Connector Storage' section at the top of this page - the same rules for what can and cannot be stored are the same as for connectors.
Example:
def saveState [@my_data1, @my_data2, @my_data3] end # See the 'loadState' example to see how this data would be recovered.
# File Flowstone API.rb, line 446 def saveState #DUMMY end
Return the elapsed time in seconds since this RubyEdit was first started. The return value is a 64-bit float, meaning that calculations that use this time can be accurate to the level of a single sample (so long as the CPU has the capacity to execute the event at the scheduled time!).
# File Flowstone API.rb, line 273 def time() #DUMMY end
Writes a string of text to the data view at the bottom of the RubyEdit's GUI. This allows you to put 'debugging' messages into your code, and see some of the internal state of the RubyEdit while it is running. The (possibly confusing!) call signature simply means that watch will accept absolutely any values that you throw at it - necessary, as a debugging tool is useless if it generates errors of its own! The rules are actually quite simple.
Giving a single value will display that value in the data display with the label "Quick Watch". Note that 'quick watches' will over-write each other on the display.
If there are two values, the first is taken as a label, and the second as the value. Labelled 'watches' will only over-write others with the exact same label.
Any argument beyond two (or code blocks) are simply discarded.
For Example...
watch "Hello" #=> Quick Watch = "Hello" @message = "Hello" watch "My message", @message #=> My message = "Hello"
Discarding any extra arguments means that only one object at a time can have its value shown. To show multiple values, wrap them in an Array or construct a String from them...
@message = "Hello" @caller = "Trog" watch [@message, @caller] #=> Quick Watch = ["Hello", "Trog"] watch "Message", "#{@caller} said '#{@message}'" #=> Message = "Trog said 'Hello'"
Note that turning Objects into Strings can be quite CPU intensive, so it is wise to delete or comment out any watch calls once you have squished all the bugs you were looking for!
# File Flowstone API.rb, line 321 def watch() #DUMMY end
Generated with the Darkfish Rdoc Generator 2.