Bubbl Help File
Revision 0.0.9Alpha
Index
Glossary
Alert Instruction
Ask user instruction
Choice instruction
Create instruction
Data types
Delete instruction
Destroy instruction
The Display
DISPLAY table
Edit instruction
Events
Expressions
File format
Filename instruction
For/Next instructions
Formulas
How to ...
How to add 'help' info to programs
How to contact the author
How to display data
How to edit a program
How to play sound
How to search tables
How to store data
How to write a program
How to deploy a program
Common Programming Pitfalls
If (then else) instruction
Input instruction
Insert instruction
Instruction Index
Introduction
Let instruction
Looping and iteration
Menu instruction
Notes and comments
Operators
Output mark-ups
Output instruction
Page instruction
PAGE table
Present instruction
Select instruction
Sort instruction
Start and End instructions
Switch instruction
System variables
Update instruction
Wait instruction
Instruction Index
Alert InstructionAsk user instruction
Choice instruction
Create instruction
Delete instruction
Destroy instruction
Edit instruction
Filename instruction
For/Next instructions
If (then else) instruction
Input instruction
Insert instruction
Let instruction
Menu instruction
Output instruction
Page instruction
Present instruction
Select instruction
Sort instruction
Start and End instructions
Switch instruction
Update instruction
Wait instruction
Glossary
Indexuser | The person at the keyboard/mouse while the program is running |
program | A network of one or more instructions which tell the computer what to do if they are 'executed' ('run'). They are essentially state transition diagrams, with flow-charts, representing actions to take, forming a network of links (arcs). The diagram simply specifies how the computer should behave according to it's internal 'state' (c.f. human 'state of mind'). It is a system of behaviour modelling. This is the fundamental concept to apply when programming with BUBBL. Specify the computer's behaviour. |
execute | 'Run' or 'enact' a program or instruction. |
mark-ups | information passed to Output instructions to affect screen position, font, colours etc. |
page | A 'window' in which a program's 'output' may be displayed. |
output | Information produced by a program for the 'user' to see, read or hear. Examples include writing text or rendering a jpeg or png file, playing a sound clip. |
database | One or more 'tables' designed to map onto a particular domain, and used to refer to that domain. For example a telephone directory. |
event | A real time occurrence of something relevant, such as a key press or mouse movement. In BUBBL there are built in events for keyboard and mouse input, timing and other uses |
table |
A data structure consisting of rows and columns of variables to
allow very large amounts of data to be expressed or manipulated. In BUBBL
columns (also known as fields) are named and rows are numbered.
Column values can also be accessed by number: Eg: table[row].col refers to the 'col'th column of the 'row'th row of the table 'table' table[3].2 refers to the second column of the third row of the table 'table' |
record | Another name for a row of a table, or single data item with many named 'fields' |
variable |
A named part of memory used to store data. It can be referred to by its name. The data its stores is called its 'value' |
expression |
A combination of one or more constants or variable names and operators as a sequence of characters. Expressions can be 'evaluated', meaning that all operators are applied in order of precedence until a constant value remains – the 'returned value' |
row |
Part of the contents of a table, consisting of a set of associated single values for each column (field) of the table. A whole row of a table is read as a series of comma-separated values, with embedded commas being transposed into '|' characters. |
column |
Part of the contents of a table, consisting of the set of all row values for a particular field (column) of the table. |
data | |
field |
Refers to a column of a table, or part of a 'tuple' variable or table row. In tables, fields are referred to by name, or by number (1 refers to leftmost). In simple tuple variables they are referred to by number, e.g. “one,two,three”.1 is “one” |
instruction |
Explicitly codified action or set of actions to be performed by the computer. Instructions are represented as shapes on the screen, with arrowed lines joining them to form a network. The network represents a combination of state and flow control information, yielding an explicit specification of behaviour. Instructions which have characteristically different possible outcomes (e.g. success or failure) have more then one exit link, each link corresponding to a different outcome. |
instruction-block |
An instruction made up a network of other instructions |
parameter |
A parameter is an important mechanism used to pass information to or from
instructions and instruction blocks. |
iterate | This means to repeat an operation for a number of different objects. To 'iterate over a set' means to take each element of the set (in some arbitrary order) in turn and perform some action with/on it. The For/Next instruction is used to iterate over a set of integers in BUBBL. |
link | The connection between two instructions. It is unidirectional (except when going backwards), and when there is more than one link from an instruction they will normally be individually labelled, representing different outcomes from running the instruction. |
set |
In BUBBL the concept of a set is limited to a set of integers. However this data type is used to hold a set of table row indices, representing a selection or query on a table. This allows many common data manipulation tasks to be undertaken with ease. Sets are expressed as comma-separated ranges of integers inside a pair of curly brackets(braces)
E.g. {1..5,14,34} has 7 elements, 1,2,3,4,5,14 and 34 |
exit link | When programming instruction blocks, it is possible to create multiple links from the instruction block (by editing the start instruction). Within the instruction block each 'end' instruction may be connected to any one of the links. The links are called 'exit links'. They can (and should!) be labelled. |
relation |
In mathematics this is a formal way of representing the relationships between items of information or data. A relation can be thought of as a table with named columns and numbered rows. The name of the table is the name of the relation, and the column titles are the 'fields' of the relation. Each column, in principle, has some sort of relationship to other columns, and all have a relationship to the 'name' of the relation. E.g. A simple relation used to express personnel details: person(forname,surname,date_of_birth,home_phone) and some members of the relation (or 'tuples'): person(John,Smith,1-12-1990,123456) person(Julie,Snobbit,23-4-1984,102032) |
tuple | A tuple is a single member, or row, of a relation. |
looping | Looping is a term derived from flow-charts, where a closed loop of linked items is expressed. It is represented in 'structured programming' languages such C and its derivatives by the 'while', 'do-while' and 'for' constructs. The flow chart is not typically encouraged as a design tool within the 'structured' and 'object oriented' programming paradigms, but it is a key conceptual component of BUBBL programming. Its power for expressing algorithms, particularly those with iteration (or 'looping'), is available directly to the BUBBL programmer. |
Alert Instruction
IndexThis instruction allows the program to
give a message to the user.
The user must either press 'Esc',
click the 'Ok' button or close the alert pop-up window.
The font,
colours etc. used to present the message may be specified in the
'mark-ups' (see 'Output mark-ups ' below).
E.g. The following pops up a box with large (50point) red writing
showing the message
'Wake up!' in the middle of the desktop.
Adding mark-ups is straightforward and menu-driven (see below).
pops up the following:
See also:
Ask user instruction
Output mark-ups
Ask user instruction
IndexThis instruction prompts the user for a
simple Yes/No answer.
The user may also press `Esc`.
Each
response results in a different link being followed.
The
`mark-ups` allow the user prompt to be placed anywhere on the screen
and
different fonts, colours etc. to be used.
E.g. The following instruction will prompt the user with the
question 'Should I go on ?”
in large 40-pt text in a pop-up box
in the centre of the screen.
See also:
Output mark-ups
Bugs
IndexIt has been said that all programs contain bugs. Bugs are errors in the program. They can be described as either errors in specification ('logical' errors), or errors in implementation (the program does not behave as it is supposed to).
In BUBBL bugs can usually be thought of as errors in
specification. A BUBBL diagram is both specification and
implementation.
These are some useful strategies for fixing
bugs, they can be easily used individually or in combination to
'home-in' on a problem
Stepping through the program one instruction at a time, checking that it does what is expected
Using Formula, Table and Variable blocks to 'watch' the value of variables and expressions as the program is stepped through or run.
Stepping backwards through a program until the error 'disappears'
Disconnecting one or more links to 'trap' unexpected program behaviour and then stepping backwards to find the problem.
Call instruction
IndexThis is a way of referring to a set of instructions as one thing.
It can make programs readable by simplifying the visual image of the program in meaninful ways. For example, the built-in instructions 'Alert','Edit','Present',and 'File' are each BUBBL programs in their own right (of wideley varying complexity)! These 'programs' are referred to as 'instruction-blocks' or just 'blocks', and are the main way of building BUBBL programs that are easy for humans to read.
User-defined blocks appear in the instruction factory and can be dragged and dropped into a BUBBL diagram like any of the built-in instructions.
Running an instruction-block as a single instruction is known as 'calling' the block.
When a block is 'called' (from another block ) the 'caller' can give
it information at the time of calling. This information is organised
into named 'parameters'. As the instruction block is entered, the
value of a parameter is put into a new variable with the parameter's
name, so that it is available within the instruction block.
Parameters may be marked as 'output', so that if a variable is 'passed' as the parameter it's value is updated to whatever the new variable's value is when the block exits (or 'returns control') to the caller.
See also:
Choice instruction
IndexThis instruction allows the user to be presented with a set of choices from a table column (one field of all records). The instruction operates in one of two modes, the default allows only one item to be selected and assigns the variable with a value equal to the choice's index.. If the user does not make a selection, the 'Esc' link is followed. If the mark-up parameter 'm' is included, multiple selections are allowed, and a set containing the indices of the selected is returned.
The text presented for the user to choose from defaults to values from the first column of the table. Another column may be chosen simply with the '.<column>' table column operator.
Other marks-ups specific to Choice instructions (in addition to the font, colours, positioning etc. mark-ups) are:
fil={set of records to include in the menu presented}
r=<No. of rows to display in menu>
d=<default choice(s)>
E.g. given the table: person(forename,surname), a menu of surnames all the entries with forename 'John' could be presented with the following instructions (note the 'm' mark-up allows zero or more selections to be made).
Note: The index number assigned to the variable ('ch' in the above
example) indexes the original table, not the (possibly reduced) menu
presented.
See also:
Sort instruction
Delete instruction
Insert instruction
Update instruction
Destroy instruction
Create instruction
Create instruction
IndexThis instruction is
used to create one or more new tables, replacing any existing tables with the
same name(s). The instruction works in one of three ways:-
1. A single empty table, with specified fields is created
2. A single table with the contents of a text file is created
3. One or more tables are imported from a '.ken' (BUBBL database) file. The name(s) of the created (imported) table(s) do not have to be the same as the source table(s), but the field names will be the same.
If any create operation fails, any existing table of the same name will be unchanged.Note:
Tables may be manually created by dragging a 'new table' Table instruction from the instruction factory into a program and right clicking on it.
To search tables use the `Select` instruction, and to update records use the `Let` instruction to assign directly to indexed records and fields thereof.
See also:
Choice instruction
Insert instruction
Update instruction
Delete instruction
Destroy instruction
Sort instruction
Data Types
Data Types
IndexData can be one of :
Numeric: E.g. 1, 47, -23.54
Boolean: E.g. 1 or 0 (for TRUE or FALSE)
Set: E.g. {4..16}, {1,3,5,8,9}, {-1..3,6..7} (only integers allowed)
String: E.g. “Hello”, “3 and a half”
Tuple: E.g. “one,two,3,the end” - Not really a data type, but comma separated values of other types
Table: E.g. name[row].column or name[record].field
Additionally the following file-based data types are implicitly supported, but the BUBBL programmer only has to deal with the filenames, directories etc.:
Image files: .PNG, .JPEG, and .GIF
Sound files: .WAV, .MID, .OGG
All expressions are represented as strings. The type of a string expression is determined according to its content, and, in the case of expressions, the context: whether from the result of an operation, or from the write destination.
Variables are named pieces of data. They can hold a value of any data type for later use.
Any syntax errors in expressions result in the expression being interpreted as a literal string. This 'feature' allows the programmer to omit the double quotes around some strings!
Tuple Not really a type, but a way of storing multiple types in the same value. It is comma- separated values of any other type(s) such as in a whole table row. Eg. person[1] might be "John,Smith,27" Individual fields are referenced using '.<field number>' Eg. "one,two,four".3 gives "four" or person[1].2 (see above) would be "Smith"
See also:
OperatorsExpressions
Delete instruction
IndexThis instruction allows a program to delete one
or more records from a table. The records are specified by a set of
the indices (record or 'row' numbers) of the record(s).
See also:
Insert instruction
Update instruction
Data types
Choice instruction
Sort instruction
Select instruction
Create instruction
Destroy instruction
Destroy instruction
IndexThis instruction
allows tables to be completely deleted.
See also:
Sort instruction
Choice instruction
Delete instruction
Insert instruction
Update instruction
Create instruction
DISPLAY table
IndexDISPLAY(thing,x,y,width,height,colour,fill,border,data1,data2,tag)
This table variable gives access to each item being shown in the current page. The
table index represents the painting order, with the topmost items having the highest indices.
Deleting records from the table removes them from the display, and some fields are similarly mapped through to the displayed objects so that, for example, changing the 'x' field in a DISPLAY record changes the x-position of the corresponding object (displayed item). However, the only way to create new items for display is to use the 'Output' instruction.
The fields are interpreted as follows:-
thing | x | y | width | height | colour | fill | border | data1 | data2 | tag |
---|---|---|---|---|---|---|---|---|---|---|
LINE | x | y | width | height | r,g,b | - | - | - | matrix:m00,m10,m01,m11,m02,m12 | |
EXPR | x | y | width | height | r,g,b | r,g,b | border | expression | font parameters | |
RECT | x | y | width | height | r,g,b | r,g,b | border | corner-radius | matrix:m00,m10,m01,m11,m02,m12 | |
CIRC | x | y | width | height | r,g,b | r,g,b | border | - | matrix:m00,m10,m01,m11,m02,m12 | |
POLY | x | y | width | height | r,g,b | r,g,b | border | x1,y1,x2,y2...etc | matrix:m00,m10,m01,m11,m02,m12 | |
SECT | x | y | width | height | r,g,b | r,g,b | border | start-angle,turn-angle | matrix:m00,m10,m01,m11,m02,m12 | |
PICT | x | y | width | height | - | - | border | filename | matrix:m00,m10,m01,m11,m02,m12 | |
SCB | x | y | width | height | r,g,b | r,g,b | ver/hor | value | min,max,step | |
BUT | x | y | width | height | r,g,b | r,g,b | border | text | font parameters | |
TRANS | x | y | 0 | 0 | 0,0,0 | - | - | params | matrix:m00,m10,m01,m11,m02,m12 |
Most of the fields beyond 'thing' may be assigned to, however the fields 'width' and 'height' are not writeable for POLY or PIC items. Changing the value of an item field causes a corresponding change in the display when it is next updated. Note that a 'refresh page' or other instruction needs to be executed to cause the display to update. This allows several sequential updates made to the table to change the displayed output simultaneously,
The field 'border' is set to one of 'raise','lower', 'frame' or 'none', determining the style of the graphic. This field is maintained automatically for BUT items. For polygon items it can also be set to 'clip' or 'blank' which have an effect on the following image to be displayed.
Records may only inserted by `Output` instructions
Deletes may be performed as in normal tables (i.e. any except for record 0, the field names)
See Also:
The DisplayOutput mark-ups
System variables
Page instruction
Edit instruction
IndexThis instruction allows a user to edit a table in one of four modes:
Graphical Image, where the table fields match those of DISPLAY
Text file, where rows represent free-form simple text
Grid, where rows and columns are laid out like a spreadsheet, or a database in 'list' view
Database, where individual rows (records) are presented with field names (column names)
The mode is inferred from the table field-names, but can be overridden
with a 'v=<mode>' mark-up where <mode> is one of:
gr | Graphical |
tx | Text |
db | Database |
dbr | Database records |
The editor always uses a page (window) called 'editor', which may be
pre-initialised with fonts, colours etc. and/or 'frozen' graphics.
In the graphical mode, text and graphics can be edited by direct
manipulation of items on the screen. (e.g. font, size,
colours etc). If your program needs to change these during editing,
you can put your own formatting instructions on the 'Esc' or 'Event'
links. The 'Event' link is used for extending the instruction. Any
events (such as 'OFF_PAGE' which you want to use for special actions
should be included in the 'Exit events' set. When the specified event
occurs, the 'Event' link will be followed. Any items already on the
page (including buttons and scrollbars) are ignored by the editor.
Buttons and scrollbars will generate USER events which can cause the
'Event' link to be followed. The contents of the table (page) can be
displayed as graphics/text, but without editing facilities, with the
'Present' instruction.
See also:
Present instructionOutput mark-ups
Events
IndexEvents are the bread and butter of real time programming. They are how the computer tells a program that something happened in the physical world, for example that a key has been pressed by the user.
In BUBBL each possible event has a unique number. Events are processed using a 'wait' instruction. Any irrelevant events are ignored by the 'wait' instruction. But when an event in one of its 'action sets' happens, event processing is suspended (events will be queued until the next 'wait' instruction), and the appropriate link is followed.
The 'wait' instruction allows the programmer to use one or more events to trigger one or more actions. Events are coded as follows:
If the the `zero` key is pressed, event number 0 is sent to the program. The `one` key sends event number 1 and so on.
The `a` key sends event number 10, `b` sends number 11 etc.
Mouse events have their own numbers, as do timer `ticks` (every 1/10th second).
For key events the character corresponding to the key pressed can be accessed by using the variable `CASED_KEY` whose value is the character, taking account of whether the `shift` key was held down at the time the key was pressed.
Key and mouse button 'releases' and an
'un-tick' give -1 minus the event numbers of the corresponding
'press' or 'tick' event (for computer science buffs this is a bitwise complement or 'not'
operation). These event numbers can be specified in sets for the `Wait`
instruction by preceding the event name with a backslash.
e.g.: {\TICK,TICK} or {\a..\z,a..z}
The Keyboard and Mouse
To specify key
events in 'wait' instructions, either the event number is used, or a
symbolic representation of the event (e.g. MOUSE_LEFT). Key events
may be referred to either by their numbers (starting from 10 for 'a')
or by simply quoting the character associated with the key in lower
case. Keys with no printable character associated with them are
referred to either by the appropriate event number or one of the
symbols in the following table:
Keyboard: F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12,
UP, DOWN, LEFT, RIGHT, PGUP, PGDN, HOME, END,
INS, DEL, BACKSPACE, ENTER, TAB, ESC, SPACE,
Mouse: MOUSE_LEFT, MOUSE_MOVE, MOUSE_RIGHT,MOUSE_WHEEL,DRAG,DROP
These events are generated to give the program more information:
FRAME -Generated when the user changes the frame size or position
OFF_PAGE -Generated when the user clicks on a page other than the current output page (CP). This event is always generated before the MOUSE_LEFT or MOUSE_RIGHT event that triggered it.
USER - Generated when the user presses a button or moves a scroll-bar
CLOSE -The user has clicked the 'Close'
button on the current page.
Note: convention dictates that the
program should close the window when it receives this event. Windows which are not the current
window will be closed by the system, but the program is given the responsibility for doing this
if it is the currently selected output window. (CP)
TICK and \TICK Timing events, TICK occurs every 100ms, with each \TICK event following 50ms second later
Code/Event | Source | CHR EVENT(=KEY) | Shifted(CASED_KEY) | Un-event |
---|---|---|---|---|
0..9 | 0-key to 9 key | 0..9 | Us: )!@#$%^&*( Uk: )!ӣ$%^&*( | Y |
10..36 | A-key to Z-key | a to z | A to Z | Y |
37 | - key | - | _ (underscore) | Y |
38 | =key | = | + | Y |
39 | [ -key | [ | } | Y |
40 | ] -key | [ | { | Y |
41 | ; -key | ; | : | Y |
42 | ' -key | ' | Us: “ Uk:@ | Y |
43 | \ -key | \ | | | Y |
44 | , -key | , | < | Y |
45 | . -key | . | > | Y |
46 | / -key | / | ? | Y |
47 | # | # | # | |
48 | * | * | * | Y |
49 | SPACE | SPACE | Y | |
50 | Unrecognised key | Y | ||
51..62 | Function keys F1..F12 | F1 to F12 | F1 to F12 | Y |
63 | Enter-key | ENTER | ENTER | N |
64 | Esc-key | ESC | ESC | Y |
65 | Tab-key | TAB | TAB | Y |
66 | Backspace-key | BACKSPACE | BACKSPACE | Y |
67 | up-arrow | UP | UP | Y |
68 | down-arrow | DOWN | DOWN | Y |
69 | left-arrow | LEFT | LEFT | Y |
70 | right-arrow | RIGHT | RIGHT | Y |
71 | Home-key | HOME | HOME | Y |
72 | End-key | END | END | Y |
73 | PgUp-key | PGUP | PGUP | Y |
74 | PgDn-key | PGDN | PGDN | Y |
75 | Ins-key | INS | INS | Y |
76 | Del-key | DEL | DEL | Y |
77 | Left mouse button | MOUSE_LEFT | MOUSE_LEFT | Y |
78 | Right mouse button | MOUSE_RIGHT | MOUSE_RIGHT | Y |
79 | Mouse moved | MOUSE_MOVE | MOUSE_MOVE | N |
80 | 1/10th second tick | TICK | TICK | Y |
81 | User resized window | FRAME | FRAME | N |
82 | Mouse pressed off-page | OFF_PAGE | OFF_PAGE | N |
83 | User closed window | CLOSE | CLOSE | N |
84 | User operated UI item | USER | USER | N |
85 | Program has started running | START | START | N |
86 | External D/B changed | DB_WRITE | DB_WRITE | N |
87 | Program Ended | PROG_END | PROG_END | N |
88 | Top-line menu | MENU | MENU | N |
89 | Sound clip ended | CLIP_END | CLIP_END | N |
90 | Key typed | KEY_TYPED | KEY_TYPED | N |
91 | Drag started/continuing | DRAG | DRAG | N |
92 | Dragged data dropped | DROP | DROP | N |
93 | Mouse wheel moved | MOUSE_WHEEL | MOUSE_WHEEL | N |
98 | unrecognised event | UNKNOWN | UNKNOWN | N |
87..96 and 99 | Reserved for future use |
Expressions
IndexWhenever a variable `assignment` is made (e.g. with a `Let` instruction), the variable is given a `value`. In BUBBL the value is always a 'string' (a sequence of characters), and it is usually the 'result' (or 'evaluation') of an `expression`. An expression is also a string, but it usually contains special characters or sequences of characters called 'operators' (Eg '+' or '>='). Although the computed value of an expression is a string, it may also be interpreted as either a number, a boolean value (1/0 for true/false), a set of integers (e.g. {1..27}) or a variable name, according to its value.
Expressions can be as simple as a single value, with no operators, or complex, with many operators, values and variables. Its evaluation involves applying a corresponding transformation for each operator present in the expression, in order of priority,
The operators transform the expression into the result. Eg.
The expression `4+5` evaluates to `9`
The expression `"This"+"that"` evaluates to "Thisthat.
The expression `"This"+5' evaluates to "This5"
To avoid confusing parts of strings which are intended to be quoted (or used literally) with operators or variable names, strings may be surrounded with double quotes. Any operators or variable names within the quotes will not be interpreted as operators or variables. They remain part of the string. ALL operators in BUBBL are either a) `prefix` operators with one `argument` Eg. `NOT x` - where NOT is the operator and x is the argument) or b) `infix` operators with two arguments Eg `a>b` - where > is the operator and a and b are the arguments. Each operator produces a single result which may be of one or more different 'types' . All operators fall into a single `precedence hierarchy`. This means that in an expression, some will be evaluated before others -much as in formal algebra. Eg `1+3/4` evaluates to `1.75` because the / operator is evaluated before the + operator (it has a higher precedence).
See also
Data types
System variables
Operators
Events
Filename instruction
This instruction pops up a file dialogue for
the user to select a file, enter a filename or select a directory, and navigate
the directory tree. Multiple selections can be enabled by including 'm' in the mark-ups*. The result for multiple selections is a set of indices into the FILE table.
Other mark-ups allow font, colours etc. to be overridden. After
successful file selection, in all cases, the path to the directory selected by the user is in the variable "FILE_PATH".
In addition to normal font, colour etc mark-ups, the following may be used:
Mark-ups | Description |
---|---|
d= | Set default file-name |
fil=x | Set filter expression to x |
m | Allow multiple selection* |
path=x | Set initial file path to x |
a=x | Set 'action' text to x (e.g. "Save", default="Open") |
cw=x | Set column width to x |
ch=x | Set column height to x |
* | Note multiple selection still under development:For now use fil="dir" to navigate to directory, then follow with Choice from FILE |
File format
A program, along with its data is stored in a simple text file. Each line of the file is formatted as a named relation. The first tuple (relation) for any named relation is interpreted as the field names. Although usually desirable, tuples do not need to have the same arity (number of fields) as the field- names, allowing for variable length records.
Eg. A data-table: MyData(FieldName1,FieldName2)
MyData(Value1,value2)
MyData(34,goose)
Each file has a table: `program(name)`. Entries in this table are interpreted as instruction-block names which are the names of tables which contain instruction-blocks. These tables may not be accessed by the program as normal data tables, and must be in the appropriate form.
Note that, in general, programs may not be self modifying.
Instruction-block tables have the following form:
<program-name>(No,Type,x,y)
where: No = Instruction number -an integer greater than or equal to zero used to reference the instruction by others.
Type = Instruction type (see below)
x = X co-ordinate for drawing instruction in the editor
y = Y co-ordinate for drawing instruction in the editor
Any additional fields are interpreted according to the instruction type (see below). Some instructions are extended with additional 'data' lines which have the same instruction number and the value 'DATA' in the `Type` field.
Summary of BUBBL instruction record formats
<prog>(No,START,x,y,Next instr)
<prog>(No,DATA,I/O/L,input-parameter/output-parameter/Link name)
<prog>(No,LINK,x,y,next instr)
<prog>(No,EXIT,x,y,exit code)
<prog>(No,FOR,x,y,Done instr,Do instr,variable,in-set)
<prog>(No,NEXT,x,y,For instruction)
<prog>(No,IF,x,y,If instr,Else instr,boolean expression)
<prog>(No,WAIT,x,y,name)
<prog>(No,DATA,Event-set,Instr)
<prog>(No,MENU,x,y,Esc instr,params)
<prog>(No,DATA,text,Instr);
<prog>(No,INPUT,x,y,Next instr,Esc instr,variable(s),parameters)
<prog>(No,CHOICE,x,y,Next instr,Esc instr,result variable,table name,params)
<prog>(No,ASKUSER,x,y,No instr,Yes instr,Question,params,Esc instr)
<prog>(No,ASSIGN,x,y,Next instr)
<prog>(No,DATA,variable,expression)
<prog>(No,SWITCH,x,y,Default instr,expression)
<prog>(No,DATA,case set/comma-separated string-list,instr)
<prog>(No,MESSAGE,x,y,message text)
<prog>(No,CALL,x,y,Next instr )
<prog>(No,DATA,P/L,param/Link instr)
<prog>(No,WRITE,x,y,Next instr,<display-item>,parameters...) Note: see below for display items
<prog>(No,PAGE,x,y,Next instr,<page-command>[,parameters]) Note: see below for page commands
<prog>(No,SELECT,x,y,Next instr,result var,table name,selection filter=true/false expression)
<prog>(No,CREATE,x,y,Next instr,table name,field names)
<prog>(No,DELETE,x,y,Next instr,delete set,table name)
<prog>(No,DESTROY,x,y,Next instr,table/variable name)
<prog>(No,INSERT,x,y,Next instr,table name)
<prog>(No,DATA,field,expression)
<prog>(No,FILESYS,x,y,Success instr,Fail inst,<command>,[param 1],[param 2]))
Note:<command> is one of "SAVE","MAKE","DELETE","RENAME","COPY","EXEC","DUMP","APPEND","IMAGE"
<prog>(No,FORMULA,x,y,ID)
<prog>(No,DATA,expression)
<prog>(No,VIEW,x,y,Table,<mark-ups>,<column offsets>,<No. of rows>,Index offset)
<prog>(No,VARS,x,y,<mark-ups>,<column offsets>,<No. of rows>,Index offset)
<prog>(No,EDIT,x,y,<table-name>,Close instr,Esc instr,Event instr)
<prog>(No,PAGE,x,y,Next instr, SELECT,<page>,<params>) Set current page to <page>, <params> specify colours, font etc.
<prog>(No,PAGE,x,y,Next instr,DESTROY) Removes current page, restoring most recent, existing current page (does not remove 'Output').
<prog>(No,PAGE,x,y,Next instr,CLS) Clears the screen. Items written before a FREEZE<true> instruction are not removed.
<prog>(No,PAGE,x,y,Next instr,FREEZE,<true/false>) Switches 'freeze' mode on/off (1=on). When activated, freezes current display items,
preventing their removal or scrolling until de-activated.
<prog>(No,PAGE,x,y,Next instr,DIR,<true/false>) Switches 'direct-write' mode on/off (1=on). When on, nothing is added to display list, instead it is just written to the display.
<prog>(No,PAGE,x,y,Next instr,UPDATE) Causes the page to be refreshed (re-drawn)
<prog>(No,PAGE,x,y,Next instr, FORMAT,<params>) Used to specify size and position and colour of page, and default values for ink, font etc.
Mark-ups are separated by spaces in <params> and are executed in sequence when the instruction is executed. Mark-ups are as follows:
Mark-up Description
x=<int> set x co-ordinate, use x=max for rhs anchor
y=<int> set y co-ordinate, use y=max for bottom screen anchor
c=r,g,b set default drawing colour (INK).
f=<font name> set the default font. Font is one of (at least) Serif, SansSerif, Dialog or MonoSpaced and is plain in style.
s=<Point size> set the default font point size (1 point is 1/72 of an inch)
b make the default font bold
i make the default font font italic
b=r,g,b set the background colour (PAPER).
st=min/norm/max set the 'window' state as minimised/normal/maximised'
fr=scr/fix/res set the 'window' frame as scrollable/fixed-size/resizable
w=width set the 'window' width in points (pixels)
h=height set the 'window' height in points (pixels)
<prog>(No,WRITE,x,y,Next instr,@,cx,cy) Initialise CX and CY
<prog>(No,WRITE,x,y,Next instr,EXPR,<expr>,<params>) Outputs the value of <expr>, updating CX (and CY if new line output).
<prog>(No,WRITE,x,y,Next instr, LINE,dx,dy,<params>) Draws a line from (CX,CY) to (CX+dx,CY+dy). CX and CY are offset by dx and dy.
<prog>(No,WRITE,x,y,Next instr,RECT,w,h,<params>) Draws a rectangle w pixels by h pixels
<prog>(No,WRITE,x,y,Next instr,CIRC,w,h,<params>) Draws an ellipse in a w by h rectangle
<prog>(No,WRITE,x,y,Next instr,POLY,xOffs,yOffs,<params>) Draws a polygon starting at (CX,CY), using vectors (xOffs1,yOffs1), (xOffs2,yOffs2) etc. vector components are separated with vertical bar characters.
<prog>(No,WRITE,x,y,Next instr,SECTOR,w,h,st,an,<params>) Fills the sector of ellipse in rectangle w by h from st deg. anticlockwise to st+an deg. (0 = East)
<prog>(No,WRITE,x,y,Next instr,PIC,<filename>,<params>) Displays the (jpeg or png or GIF) image file
<prog>(No,WRITE,x,y,Next instr,SCB,<horiz>,len,init-val,upp,lwr,step,<params>) Displays a scroll-bar which sources USER events
<prog>(No,WRITE,x,y,Next instr,BUT,<expr>,<params>) Displays a button which sources USER events
<prog>(No,WRITE,x,y,Next instr,CLIP,<audio-file name>) Plays an audio clip
Note: Where <params> contain commas (e.g. 'c=255,200,100') the commas are stored as vertical bar characters to distinguish them from field separators.
For/Next instructions
Sometimes a program needs to repeat the same operation or calculation over and over, either on a number of objects (data records), or on the same object(s). This is variously known as iterating or looping, and BUBBL provides the `For/Next` pair of instructions for this purpose. The `For` instruction takes a set of ordered integers, and assigns the value of each member to the same variable sequentially. For each assigned value the `Do` link of the `For` instruction is followed once -as long as the loop is `closed` by linking to the `Next` instruction. When all values have been used, the `Done` link of the `For instruction is followed. Each `Next` instruction is permanently linked to a `For` instruction, and cannot be changed. For the looping to work properly, the `Do` link must be linked (via one or more useful instructions) to the `Next` instruction. The set of integers might be from a user `Choice` or from a table search (`Select` instruction), or from a set calculation. The set is `frozen` when the `For` instruction is first executed so that changes to the value of the set do not affect the instruction`s iterations. Only the `For` instruction`s `Next` instruction causes iteration. All other links to the `For` instruction cause the iteration to be re-started from the beginning. Some structured programming purists may feel uncomfortable about this, but it is safe for the program to `break out` of the loop by simply not following a link to the `Next` instruction. To allow for one level of nesting, the 'frozen' set is stored locally when the iteration begins, and restored when it is completed.
See also:
Looping and iteration
Formulas
A formula block is a stand-alone entity which allows the programmer or user to see what the value of various variables, expressions or calculations are. It is not intended to be a program instruction, but a tool for use in program development. Each formula block can be thought of as a single-column spreadsheet. Multiple formula blocks can be used in combination for more complex computations. Although formula values may be used in other formula blocks, they may not be used in expressions within ordinary program instructions. To use in expressions the formula block must be given a name. Its formulas can then be referred to using table record notation: <formula-name>[<row>] Rows are numbered from 1. If you do not want the formula itself to show, only its value, the formula should start with an equals sign. Eg. "This"+"that" displays as '"This"+"that" = ThisThat whereas ="This"+"that" displays as ThisThat
See also:
Expressions
Operators
How to ...
IndexHow to add 'help' info to programs
Each user interface instruction has an optional 'Info' button that can be enabled by including the string 'info' in the mark-ups (see UI mark-ups ). When the button is pressed, a URI (Usually an HTML anchor inside an HTML file) is made up from the system variables INFO_KEY and INFO_FILE and passed to the browser (the system variable BROWSER should have the command line invocation for the browser). Help file(s) are then produced using any appropriate HTML editing tools
How to deploy a programs
A program which has been finished and debugged may be made available to others without the 'development' environment (i.e. the 'RUN', "STEP' etc buttons and the desktop). This can be done by assigning a variable on the desktop called 'AUTO_RUN' with the value 1. This value is only picked up from the program file, so changing it while running the program is not straightforward. Also, when this option is active, a program which ends causes the user to be prompted on whether to 'run the program again' or 'exit the system', rather than be presented with the usual desktop.
How to contact the author
You can contact the author at oldbarney@hotmail.com This version of BUBBL is released under the terms of the GPL.
Please play with it!
The author is grateful for any suggestions or bug-reports. BUBBL is the result of over 10 years of thinking and 6 years of coding. It is still a bit `rough around the edges` although the documentation is pretty much accurate. Please do not supply it to a third party without the author`s consent.
Happy BUBBLing !
Barney McCabe 24thSeptember 2010 (author)
Credits: Thanks to: Nesia, Mya, Tafari and Zauditu and Valerie -my long-suffering family, Kev Buckley - making me define it, Irwin Abraham, Jim & Moira Sarsfield for critical feedback ... and for teaching me useful stuff: Andrew James, Chris Scaife, Yogesh Sharma, Ayad Abdullah, Finbar Dineen, Alex Gray et al-University of Wales College Cardiff, Open University, Jan Winter & John Hayter et al-University of Bristol School of Education, Borland International, Sun Microsystems, BBC micro, Sinclair Spectrum
How to display data
Output to the screen is
performed via 'pages' (or 'windows'). Page instructions can be used to create, destroy and manipulate pages in a variety of ways.
Only one page at a time can be output to, and this can be selected with the Page instruction.
Note that the default page (named "Desktop") cannot be destroyed, so there is always at least one page available for output.
However, as the desktop is the main working area when working on a program, the program's
output to the desktop is only shown while the program is running, otherwise the
desktop shows what is in the currently load program's 'Desktop' instruction block.
It is therefore suggested to use other named pages for output while developing programs.
The name of the current page is stored in the system variable 'CP'.
To put things on a page an 'Output' instruction is used as follows:
1. Click on the `Output` instruction
in the instruction factory and choose an item from the menu presented. This creates a new instruction in the factory.
2. Drag the new instruction from the factory into your program.
3. Right-click on the new instruction and fill in any data fields
necessary to make sense (Eg. if you chose 'Output rectangle', give it
a width and a height). You can directly manipulate the object, colours etc.
by pressing the 'Interact' button in the editor. Finish editing by clicking on Ok or pressing
<Enter>.
4. Left-click on the instruction. This should cause it to be highlighted with a flashing
rectangle.
5. Now click the Step or Run button at the lower right of the screen. You should see the effect of your output instruction on the 'current page' (=the last page selected with a 'Page-select' instruction).
See also:
Output instruction
System variables
The Display
Page instruction
How to edit a program
To edit an individual instruction, right-click on it and fill in the form appropriately. This cannot be done in the factory, the instruction must first be dragged into an editor or onto the desktop. To edit instruction blocks, right-click on the instruction in the factory. To copy instructions, do the same `copy` action as you would to an icon, but to an instruction or `boxed group` (see below) selected with the mouse. In Windows(TM) this is holding the `Ctrl' key down whilst dragging the item(s). The copied instruction(s) can then be dragged to a new position in the editor window, or to another edtor window, and `dropped` by releasing the mouse. To move an instruction (or boxed group), left-press the mouse on the instruction and drag it to its new location.
Undoing mistakes
If you accidentally break a link or delete an instruction, you can fix the problem by selecting 'undo' from the 'Edit' menu.
Boxed group
To select a group of instructions, press the right mouse button to drag out a blue box until it surrounds the instructions (for most instructions the centre of the instruction must be inside the box for it to be selected, but non-executing instructions such as a formula tool use the top left corner) Right-clicking inside this box gives a menu of actions, and left- clicking allows the whole group to be moved as one.
Linking instructions
Links are made by left-clicking on the link and dragging the mouse over the instruction to be linked to. If the link is already connected it is automatically disconnected when clicked on. If the link is dropped over a blank area, a new `LINK' instruction is created and left where the mouse was released. This allows the path of the link to have corners. An un-connected link shows as a red circle just outside the edge of an instruction. One or more links which connect to their own instruction appear as a black circle over the centre of the bottom outline of the instruction. When an instruction has more than one link they are labelled appropriately. Although links are drawn according to a precise algorithm, it is usually possible to get pleasing visual results by varying the positions of instructions. This can improve program readability.
Cut and paste
The Edit menu and boxed-group local menu provide copy, cut, delete and paste operations. These are applied to instructions 'selected' in the box (see ' Boxed group' above).
Summary
In BUBBL you are trying to
describe the behaviour of the program- this is done with a diagram, rather
than carefully indented text. Eg: A program to write the
times table (here in pseudo-code):
Input which table (t)
For n=1 to 10 do
BEGIN FOR LOOP
WriteLn n+" x "+t+" = "+ n * t
END FOR LOOP
in BUBBL could be:
How to play sound
Click on the `Output` instruction in the factory and choose `Audio-clip` from the menu given.
Drag the new instruction into your program and right-click on it to give it the filename of the `clip` (Eg '.WAV' or '.FLAC' file) you want to play.
-
Note: When the program is 'stopped' (i.e. 'activated', but not 'running'), all sound clips are automatically stopped. This can make it seem like there is a problem with the clip when you step through the program. To debug sound playing BUBBL programs, it can be helpful to put a 'Wait' instruction after each sound clip playing instruction, and press 'Run' instead of 'Step' to make sure the clip will play appropriately.
Each time a new clip is played, an entry is inserted in the system table 'CLIP'. Clips can be paused, resumed, stopped and restarted by updating the 'paused' and 'ended' fields with TRUE or FALSE (1 or 0). Records can also be deleted, but other than this, values in the table are read-only.
When a clip finishes playing normally a 'CLIP_END' event is generated. This allows a program (for example) to loop a clip repetitively, or play a sequence of clips in a controlled manner.
How to search tables
There are three built-in ways to search tables in BUBBL:
Using the 'Select' instruction:
The 'Select' instruction returns a set of the indices of all records in a table (or subset of a table) which match its selection criteria. For each record the value of a boolean expression (true/false) is tested, and those record numbers for which the expression returns 'true' (=1) are included in the result. This allows you to find all the records which match your search criteria. A set of all the matching record indices is returned
Using the 'LOOKUP' operator:
The LOOKUP operator is used inside expressions and returns the index of the first record whose first field matches the 'key'. It should be noted that other fields can be searched with LOOKUP by using '<table>.<field>' syntax which gives a 'table view' of a single column of a table. If no match is found, a value of 0 (zero) is returned.
Indexing the table with a string
This is similar to LOOKUP (the first field of the table is searched for a match of the string), however, the subsequent fields of the matching record are returned instead of the index. This is a useful syntactic convenience over using the “LOOKUP” operator, if a little less clear. If no match is found, an empty string is returned. This method of indexing also allows new key-value pairs to be inserted in the table just by assigning to (e.g.) 'table[<key string>]'.
Tables can also, of course, be searched in many different ways by iterating through records one at a time in a program loop.
See also:
Looping and iteration
Data types
Select instruction
Operators
How to store data
Data is stored or used in BUBBL by giving it a name. A named piece of data is called a variable. The data itself is said to be the variable`s `value`. The value of a variable can be output to the screen, for example. Variables may be separate things or they may be inside a table. A table is an organised form of data with zero or more numbered rows and 1 or more named columns. Whereas a variable is referred to by it`s name, each row of a table is referred to by the table name followed by its number in square brackets.
E.g: MyTable[1]
Individual fields are referred to by following the row name with a dot and then either the field name or field number.
E.g: MyTable[1].type or MyTable[3].6
Additionally a single column of a table can be referenced as if it
was a whole table by using the syntax: <table>.<field>
This can be useful when looking up values with the LOOKUP operator if
the field is not the first in the table.
E.g. MyTable.surname LOOKUP "Johnson"
Rows may be added to a table using the `Insert` instruction, or by editing the table manually (while the program is not running). The following BUBBL instructions may be used to make separate variables or to change any variable`s value:
Let, Select, For, Input, File, Edit and Choice
And these instructions may be used to make and remove rows and tables respectively:
Insert, Delete, Create, Destroy
Notes:
Rows are numbered from 1 upwards, although an imaginary row 0 gives the field names.
Fields can be referred to either by their name, or by their number (numbered from left to right starting with 1)
When a new row is created with the `Insert` instruction it is added to the end of the table.
When rows are removed with the `Delete` instruction, rows with higher numbers are moved down so that there are never any `empty` rows.
When a whole row is referenced, the fields are separated in the value with commas. If the fields contain commas, these are first converted to vertical bar characters to distinguish them from the field separators.
Separate variables may also have multiple fields, by simply including commas in the values assigned to them. The fields are referred to by their number only (1=first). The fields may be assigned to individually.
Eg. The following sequence of assignments:
produces the following output:
Assignments to fields which do not exist -either in table records or separate variables- have no effect
See also:
Data types
Expressions
Let instruction
How to write a program
A BUBBL program is a diagram made up of interlinked instructions. The language itself has about 20 such instructions which cover all the things a programmer may tell the computer to do. To build on built-in instructions, a programmer may make his/her own instructions (called 'instruction-blocks') which may be used in programs in just the same way as the built-in ones. All available instructions are shown in the `factory`, and can be dragged into a program. Most instructions require `editing` to give additional information. To edit an instruction, right-click on it after dragging it into the program. The computer runs a program by `executing` (i.e. doing) an instruction, then following one of the instruction`s `links` to another instruction. It keeps doing this until either it gets to an `End`instruction, the user clicks on the STOP button, or it gets to an unconnected link. To start a program click on the instruction you want to start with, and then click the `RUN` button.
To make testing programs easy you can use these three buttons: The `STOP` button stops any running program immediately. The `STEP` button `executes' just one instruction or block and the `BACK` instruction `undoes` the previous instruction or block, running the program backwards. Instruction-blocks are usually treated as a single instruction when stepping or stepping back. However, if an editor window is open, it is 'stepped into', with its own instructions stepped (back) through individually. To further aid program development and testing, formulas, tables and variables may be used to give 'live' information, simply drag the appropriate item from the instruction factory. You can annotate your program by dragging a 'note' into it.
More Debugging tools
The system variable DEBUG when written to, causes the value written to be echoed to standard output (e.g. in the terminal window if that is where Java was run from). This may be useful for debugging real-time program segments.Assigning a file path and name to the variable "UNDO_DUMP_FILE" will cause the 'undo script' of the last few thousand instructions executed to be output to the specified file. Interpreting this file is beyond the scope of this document, however, the reader is encouraged to discover this for his/herself by careful experimentation!
See also:
Common Programming Pitfalls
Common Programming Pitfalls
Deleting rows/records from tables
A common problem arises when incrementally removing records from tables.
When a record is deleted, all higher-numbered records 'move down one', so that
their index numbers change. If you delete records in a 'FOR' loop this can be
disasterous as the wrong records end up being deleted unless care is taken to
adjust the indices as lower numbered records disappear. If a single set of records
is deleted in one instruction this problem does not arise however, so if you have
multiple records or sets of records to delete, first of all combine them with
the 'UNION' operator.
E.g.
See also:
Operators
If (then else) instruction
This instruction is used to choose between two paths of execution based on some condition or test. An expression is evaluated (calculated) and the result is interpreted as a 'boolean' (true/false) value. If it is 1 (true) the link labelled with the expression is followed. If it is 0 or anything else (false), The unlabelled link is followed. Note: the words 'if, then and else' do not appear in the instruction, as the question mark is used to suggest a 'decision'.
See also
Expressions
Operators
Switch instruction
Wait nstruction
Input instruction
This instruction allows the program to get typed information directly from the user. The user may also press `Esc`, but his function may be disabled. The program may also provide `info` (like this page) when the user presses the added `info` button. This is done by setting the `mark-up` `info'. The `mark-ups` also allow the user prompt to be placed anywhere on the screen and different fonts, colours etc. to be used.
See also:
Output mark-ups
Update instruction
This instruction is used to modify one or more fields of a set of records (rows) of a table in one go. The records to be updated are selected with a set of their index numbers. Fields to be modified are each assigned an expression. When evaluating the expressions for each record, field names are interpreted as referring to the field values of the current record, as in the 'Select' instruction. Fields not explicitly initialised with the `Update` instruction are left unchanged. For very large sets of records this instruction may be noticeably slow in execution!
See also:
Select instruction
Delete instruction
Create instruction
Destroy instruction
Sort instruction
Insert instruction
Choice instruction
Insert instruction
This instruction is used to add a new record (row) to a table. The record is added to the end of the table, i.e. Its index after `Inserting` into <table> will be `COUNT <table>`. Each field of the new record may be assigned to in the instruction. Fields not explicitly initialised with the `Insert` instruction are set to a blank (zero length string).
See also:
Select instruction
Delete instruction
Create instruction
Destroy instruction
Sort instruction
Update instruction
Choice instruction
Introduction
Do it yourself knowledge engineering.
Build your own Artificial Brain!
Behavioural / Beginners'
Universal / User-oriented
Building-
Block
Language
Knowledge ENactment Files
What is it?
1. A simple programming
package for Windows/Linux etc..
2. A definition of a literacy for
human/computer interaction using relations and 2-dimensional
behaviour specification diagrams.
3. A tool for learning the core
concepts of computer programming
4. A knowledge engineering tool
What isn't it ?
1.Visual Basic
2.A cross-compiler
3.A
distributed business-wide application generator
4.Unnecessarily
complicated
What could it be?
A 'toy' for anyone to 'free-play' with
images/control/ behaviour etc
A tool for teachers to build
interactive knowledge environments
A universal operating system
(just fix an interpreter to any database)
A cookie-using
web-resident knowledge-base automaton network.
BUBBL embodies the
following ideas:
database: named relations, queries, sorting,
insert/delete/update
mathematics: formulas and
expressions
graphics: pictures geometrical shapes fonts
cartesian co-ordinates in 2
dimensions
variables(types): numeric, string, set, tuple, array,
table
Philosophy
The cornerstone of the BUBBL philosophy is that all data
(including 'source code') can be represented with named
relations.
This philosophy is applied to programs and program
components ('instruction blocks') which are stored as relations
representing a network of instructions. Each instruction or part of
instruction is identified with a numeric field. The value of this
field is used by(in) other instructions to link to it.
The BUBBL diagram works at the level of behaviour description as
well as process definition.
How the program should respond to
events, what transformations it should perform on its data are all
made explicit in a 'self-documenting' diagram.
From an object-oriented perspective, classes and objects are
database entities - simple named relations and tuples
respectively.
Methods are operations deriving from and/or on
tuples and sets of tuples (relations).
In the case of (e.g) the
DISPLAY table, the database entities are mapped onto the 'objects'
displayed through reading and writing table values.
See also:
Data types
Operators
System variables
Events
DISPLAY table
Let instruction
This instruction is used to give a value to one or more variables. A variable may be one of the following:
a simple named variable
a field of a multi-field (comma-separated) named variable
an indexed row of a table
a single field of an indexed row of a table
Values are similar to mathematical expressions, but with more non-mathematical operators available. Some operators, notably the plus (+) operator, have different interpretations depending on their arguments. Invalid expressions are interpreted simply as strings, allowing for easy debugging.
Examples of valid variable assignments:
See also:
Operators
Expressions
Bugs
Data types
Looping and iteration
Sometimes a program needs to repeat the same operation or calculation over and over, either on a number of objects (data records), or on the same object(s). This is variously known as iterating or looping, and BUBBL provides several ways of doing this:
For iterating through a predetermined set of objects the 'For/Next' instructions may be used. The For instruction takes a set of integers and assigns them sequentially to a variable. The set would typically be the result of a database 'Select' instruction, or a user interface 'Selection' instruction or other set value (e.g. ALL <table> for all the indices of <table> records).
Where the iteration depends on intermediate calculations or external events, a loop can be realised as a physically looped group of instructions. Normally such a loop would have a 'test' in it - typically an 'If' instruction, which is used to determine when to 'exit' the loop (i.e. when the iteration should end). Such a loop in BUBBL has the advantage over so-called 'structured programming constructs' that more than one exit is possible, allowing the programmer to construct the program in the most appropriate, or elegant way.
See also:
For/Next instructionsIf (then else) instruction
Menu instruction
This instruction allows program flow to be chosen by the user. Each menu item is associated with a different link which is followed it the item is selected. The link labelled `Esc` is followed if the `Esc` key is pressed, or nothing is selected. The `mark-ups` may be used to position the menu anywhere on the user`s screen and to specify colours and font, size and style. Also the menu may include icons if the markups contain the string 'icons', in which case the first comma-separated substring of each menu line's text should be the icon's filename.
See Also:
Output mark-ups
UI mark-ups
Choice instruction
Selection instruction
Ask user instruction
Notes and comments
A well written program will include some `comments` to guide the reader. The `Note' instruction is not `executed` in the normal way, but allows comments or notes to be included with the `code` -allowing the programmer to annotate the program.
The text can be any colour, size or font and should be used to help increase the readability of the program. To change the style (font, size etc), right click on the text and edit `mark-ups` in the same way as for Output Expression instructions. The 'Interact button' allows direct manipulation of the font and colour.
See also:
Output mark-ups
Operators
Note: Operators are listed in descending order of precedence
Operator | Description | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
x.y | If x is a table, gives a 1-column table 'view' of column y of x. | ||||||||||||||
ENV x | Gives the value of the envrionment variable x, or empty string if x doesn't exist
| ||||||||||||||
ALL x | Set of table x indices, equivalent to 1 TO (CARD x) | ||||||||||||||
NFIELDS x | Gives the number of named fields of the table or tuple x. If x is neither of these it is interpreted as comma-separated values, and the number of commas+1 is returned. | ||||||||||||||
NRECS x | Gives the same as 'CARD x' if x is a table | ||||||||||||||
x LOOKUP y | <
P>If x is a table, gives the record number of the first record in x whose first field equals y. If x is a string, gives the index of the first comma-separated sub-string of x that equals y. If x is a set containing y (an integer), gives the ordinal number of y in x. Otherwise gives 0 | ||||||||||||||
x TRANSPOSE y |
x should be a table column. | ||||||||||||||
EXISTS x | Gives 1(true) if x is a table, 0 otherwise | ||||||||||||||
CARD x |
Gives the cardinality of x: | ||||||||||||||
COUNT x |
Identical to CARD x -gives the
cardinality of x: | ||||||||||||||
NSUBSTR x |
Gives the number of space-separated sub-strings of x | ||||||||||||||
SGN x | Gives the signum of x (-1 if x is negative, 1 if x is positive,0 if x is 0). | ||||||||||||||
ABS x | Gives the absolute value of x | ||||||||||||||
LOG x | Base 10 logarithm of x if x is a number >0 | ||||||||||||||
SQRT x | Floating point or integer square-root | ||||||||||||||
RAD x | Degrees to radians: equivalant to pi/180*x | ||||||||||||||
SIN x | Trigonometric sine of x (x in radians). | ||||||||||||||
COS x | Trigonometric cosine of x (x in radians). | ||||||||||||||
TAN x | Trigonometric tangent of x (x in radians) | ||||||||||||||
ASIN x | Trigonometric arcsine of x (in radians). | ||||||||||||||
ACOS x | Trigonometric arccosine of x (in radians). | ||||||||||||||
ATAN x | Trigonometric arctangent of x (in radians). | ||||||||||||||
ATAN y,x | Trigonometric arctangent of the position vector specified by x and y | ||||||||||||||
DEG x | Radians to degrees: equivalant to 180/pi*x | ||||||||||||||
RANDOM x | Random integer in the range 0 to x-1 | ||||||||||||||
+x | Unary plus, gives x | ||||||||||||||
-x | Unary minus, gives 0-x | ||||||||||||||
\x | Binary not. Gives -1-x if x is a number. | ||||||||||||||
x^y | x raised to the power y | ||||||||||||||
x/y | Division, gives x/y. | ||||||||||||||
x DIV y | Integer division | ||||||||||||||
x MOD y | x Modulo y (remainder of x divided by y) | ||||||||||||||
x*y | Multiplication (type depends on the operands-and result !-) | ||||||||||||||
x-y | Floating point or integer subtraction | ||||||||||||||
x+y | Numeric addition or string concatenation | ||||||||||||||
x SUM y | Sums the values of table column x whose record numbers are elements of the set y | ||||||||||||||
x MEAN y | Computes the average of the values of table column x, with indicies in the set y | ||||||||||||||
x MODE y | Computes the mode of the values of table column x, with indicies in the set y | ||||||||||||||
x MEDIAN y | Computes the median of the values of table column x, with indicies in the set y | ||||||||||||||
x MAX y | Gives the highest of the values of table column x, with indices in the set y | ||||||||||||||
x MIN y | Gives the lowest of the values of table column x, with indices in the set y | ||||||||||||||
x VARIANCE y | Computes the variance of table column x of records whose indices are elements of y | ||||||||||||||
x STDEV y | Computes the standard deviation of table column x of records whose indices are elements of y | ||||||||||||||
x SF y | Gives y correct to x significant figures | ||||||||||||||
x DP y | Gives y correct to x decimal places | ||||||||||||||
SCI y | Gives y in scientific notation (e.g. 'SCI 1000' gives '1.0e3' | ||||||||||||||
ROUND x | Gives x rounded to the nearest whole number | ||||||||||||||
MONEY x | Gives the decimal x as a quantity of dollars (including cents) | ||||||||||||||
DOW x | Gives the day of week, x is seconds since 00:00hrs, 1st January 2000 ignoring leap seconds. | ||||||||||||||
DOM x | Gives the day of month, x is sec. since 00:00hrs, 1st Jan 2000 | ||||||||||||||
DATE x | Gives the date (day month year) x is seconds since 00:00 1-1-2000 | ||||||||||||||
MONTH x | Gives the month, x is seconds since 00:00 1-1-2000 | ||||||||||||||
YEAR x | Gives the year, x is sec. since 00:00 1-1-2000 | ||||||||||||||
TOD x | Gives the time of day, x is sec. since 1-1-2000 | ||||||||||||||
PERCENT x | Gives the decimal x as a percentage | ||||||||||||||
UPPER x | Gives x in upper-case characters | ||||||||||||||
LOWER x | Gives x in lower-case characters | ||||||||||||||
x FROM y | The string x starting from the y'th character | ||||||||||||||
x CHOP y | The string x minus the rightmost y characters | ||||||||||||||
x LEFTMOST y | The y leftmost characters of the string x | ||||||||||||||
x RIGHTMOST y | The y rightmost characters of the string x | ||||||||||||||
LEN x | Identical to LENGTH x, the number of characters in the string x | ||||||||||||||
LENGTH x | The number of characters in the string x | ||||||||||||||
WIDTH x | The width of the string x in graphics units (points or pixels), using current font dimensions | ||||||||||||||
x SUBSTR y | Gives the y'th space separated substring of x | ||||||||||||||
HASHED x | Gives x with spaces replaced with # character | ||||||||||||||
CHR x | Gives character encoded with the number x | ||||||||||||||
UNICHAR x | Gives UNICODE character encoded with the UNICODE x | ||||||||||||||
x ASSOC y | Text following occurrence of y in x up to first space or end. E.g. "x=4" ASSOC "x=" gives "4"'#` characters are transmuted into spaces. Eg. "t=My#Title"ASSOC "t=" gives "My Title" | ||||||||||||||
x HAS y | Gives 1 if x contains y delimited by spaces or end of line, 0 otherwise | ||||||||||||||
x POS y | Gives the index of y in x (1 for 1st, 0 for no match) | ||||||||||||||
x LASTPOS y | Gives the last position of y in x | ||||||||||||||
UNICODE x | The integer UNICODE encoding of the first character of the string x | ||||||||||||||
CODE x | The integer code of the first character of the string x | ||||||||||||||
FILE_EXISTS x | Gives 1 if x is an existing file, 0 otherwise | ||||||||||||||
NOT x | Gives 0 if x=1, 1 otherwise | ||||||||||||||
x TO y | Gives the set {x..y}, gives {} if y<x | ||||||||||||||
x CRC y | Gives a 32-bit CRC calculated from the UNICODE encoding of the charaters of x, and seeded with the value y. | ||||||||||||||
x INTERSECT y | Gives the intersection of the sets x and y | ||||||||||||||
x UNION y | Gives the union of the sets x and y (integers are interpreted as single-element sets). | ||||||||||||||
x EXCLUDE y | Gives the set x intersected with y's complement | ||||||||||||||
x DISTINCT y | Gives the set of row indices of table x which are also in the set y, and whose first field is not duplicated by rows with a lower index. Eg. myTab.fld DISTINCT ALL myTab. It is intended for use in combination with Select instructionin table searches. | ||||||||||||||
x IN y | Gives 1 if the set y contains the integer or set x. | ||||||||||||||
x ORD y | Gives the ordinal number of y in the set x (1=first, 0 if y not an element of x). | ||||||||||||||
REST x | Identical to TAIL x | ||||||||||||||
TAIL x |
If x is a set gives x with first element of x removed | ||||||||||||||
FIRST x | If x is a set gives the first element of x (or empty string if x is empty) | ||||||||||||||
HEAD x | Identical to FIRST x: | ||||||||||||||
LAST x |
If x is a set, gives the highest valued element of the set (or empty string if set is empty). | ||||||||||||||
y NEXT x | Gives the lowest valued element of the set x greater than y or, if y is a set, the lowest valued element of the set y greater than x | ||||||||||||||
y PREV x | Gives the highest valued element of the set x less than y or, if y is a set, the highest valued element of the set y less than x | ||||||||||||||
x=y | Gives 1 if true, 0 otherwise | ||||||||||||||
x>y | Gives 1 if true, 0 otherwise | ||||||||||||||
x>=y | Gives 1 if true, 0 otherwise | ||||||||||||||
x<y | Gives 1 if true, 0 otherwise | ||||||||||||||
x<=y | Gives 1 if true, 0 otherwise | ||||||||||||||
x<>y | Gives 1 if true, 0 otherwise | ||||||||||||||
x AND y | Gives 1 if x is 1 (true) and y is also 1 (true), 0 otherwise | ||||||||||||||
x OR y | Gives 1 if x is 1 (true) or y is 1 or both are. | ||||||||||||||
x?y:z | Gives y if x is true, z otherwise. | ||||||||||||||
x >? y | Gives x if x>y, y otherwise | ||||||||||||||
x <? y | Gives x if x<y, y otherwise | ||||||||||||||
EVAL x | Interprets the string x as an expression and returns its evaluation. This operator is not recursive beyond a depth of 2 | ||||||||||||||
x CHILD_EVAL y | Uses the program-block x from the child program indexed by CHILD_NO to evaluate y as a local expression in that block. It allows (e.g.) child variables to be evaluated. | ||||||||||||||
STACK_EVAL x | Uses the 'calling' program-block to interpret x as a local expression. It is used by system programs to allow variables from a calling program block to be evaluated. | ||||||||||||||
ENCRYPTED x | Gives an encrypted/decrypted copy of x, depending on the initial value of the system variable SEED, and what has been encrypted since SEED was initialised. SEED is initialised to a 'random' number by assigning a 'password' string to it. The encryption algorithm is symmetrical so that encrypting and decrypting use this same operator, as long as SEED is initialised to the same value in each case. | ||||||||||||||
x REENCRYPTED y | Gives an encrypted/decrypted copy of y, initialising "SEED" to x dircetly. This allows repositioning encryption/decryption within an encryption stream, but cannot replace the initialisation of SEED with the password, as this initialises other 'invisible' variables at the same time. | ||||||||||||||
URL_ENCODE&npsp;x | Gives x encoded for the MIME format: "application/x-www-form-urlencoded" | ||||||||||||||
URL_DECODE&npsp;x | Gives x decoded from the MIME format: "application/x-www-form-urlencoded" | ||||||||||||||
HTML_ENCODE&npsp;x | Gives x encoded as legal HTML, with character entities etc." | ||||||||||||||
HTML_DECODE&npsp;x | Gives the HTML string x decoded to plain text." | ||||||||||||||
See also:
Expressions
Output mark-ups
Most output instructions allow their output to be modified as it is put on the screen. For example the position on the screen, or font size can be changed from the default values. These changes are made through parameters which are part of the instruction. They consist of zero or more space-separated parameters as described below. Spaces may be included in parameter values by using a hash character where a space is required. It is often desirable to store parameters in a string variable. The contents of one or more such variables can be invoked by simply embedding '@<variable-name>' within the parameter string (or using the same as the parameter string).
Positioning control
In general items which use 'windows' (or 'frames') will be
positioned relative to the desktop, whereas simple graphical or
textual items will be positioned relative to the current page (CP)
(ie within a window). The following are available
Set the item's x or y co-ordinate directly: x=<int> y=<int>
Align item with right-hand side of page/desktop: x=max
Align item with bottom edge of page/desktop: y=max
Place item in centre horizontally: cx
Place item in centre vertically: cy
Offset item from 'position so far': dx=<int> dy=<int>
Right-align text (relative to bounding rectangle): rr
Change width of window or graphical item: w=<int>
Change height of window or graphical item: h=<int>
Output mark-ups for Framed (UI) items:
(Input, Page, Choice, Menu, Selection, Alert, Ask)
Give frame a title: t=<title>
Make frame closable: cl=1
Make frame not closable: cl=0 (default)
Make frame scrollable: fr=scr
Make frame fixed (not resizable): fr=fix
Make frame resizable: fr=res (default)
Grab keyboard focus for page: foc=1
Don't bother to grab keyboard focus for page: foc=0 (default)
Minimise frame: st=min
Maximise frame: st=max
Make frame normal size: st=norm
Set input prompt text: p=<Prompt(s)>
Set history 'context key' for input instruction: hk=<context>
Show 'Info' button: info
Add 'file' button for Input (e.g. fm="*.WAV"): fm=<mask>
Allow icons in menu instruction: icons
Set initial selection query (e.g. q=RECORD#IN#set) for Choice instruction: q=<query>
Specify field name for choice menu text: tf=<name;>
Specify field name for choice text-colours: cf=<name;>
Specify field name for choice continuation menus: mf=<name;>
Specify number of characters in the input field of input instruction: l=<int>
Number of rows to show: r=<rows>
Allow multiple selection in Choice instruction: m
Specify editing mode for Edit instruction: v=<mode>
where: <mode>=gr,tx,db or dbr for graphical,text,database or database record.
Specify editing parameters for Edit instruction:
row=<row>
col=<column>
po=<page-offset>
cxs=<x-coordinates of columns>
nr=<number of rows>
h=<height of window>
ex=<set of event numbers for 'Event' link>
=<>
=<>
Specify additional lines of text for 'Alert' and 'Ask user' instructions: aux=<table>
where <table> is a table with a row for each line of additional text.
Colours mark-ups
Foreground,'INK',text or outline colour: c=<r,g,b>
Background,'PAPER' or fill colour: b=<r,g,b> (Note: values for r,g and b
should be in the range 0 to 255)
Text (expressions and buttons)
Specify font name: f=<font name>, font is one of (at least) Serif,SansSerif, Dialog or MonoSpaced
Set font point size (1 point=1/72inch): s=<point size>
Make font italic: i
Make font bold: b
Output a new-line (scrolling the page if necessary): n
Tabbed output of tuples: tabs={tab-stops} (Note tab-stops in points = 1/72inch)
Right justify (e.g. for numeric output): rr (Note: Justifies to box defined by
w= parameter)
Text and Graphical items Border styles
raised: bd=raise
lowered: bd=lower
frame: bd=frame
clip region around polygon to transparency: bd=clip
blank region inside polygon to transparency: bd=blank
none: bd=none
Miscellaneous
Append to display without deleting items overwritten or covered from DISPLAY table: a
Add an arrow to a line: ar
Set rounded corner radius for rectangles: cr=<radius>
See also:
Output instruction
Expressions
Output instruction
BUBBL allows simple geometric shapes, text and images to be displayed on a page. It also allows sound-clips to be played. There are 14 sub-functions of the output intstruction:
Sub-function | Description |
---|---|
Output @ | Sets CX and CY for the next output. |
Write expression | Displays text and/or numbers. |
Line | Draws a line |
Polygon | Draws a polygon |
Rectangle | Draws a rectangle |
Circle | Draws a circle or ellipse |
Sector | Draws a sector of a circle or ellipse |
Button | Creates and draws an event-generating button |
Scroll-bar | Creates and draws an event-generating scroll-bar |
Picture | Displays an image file |
Dump | Dumps a table's contents to a file. No field structure is preserved, each row is simply output as text, with commas within fields appearing as '|' characters. If the table was created from a 'text' file, this would reproduce the content of that file. |
Append | Appends a table's contents to a file as in 'Dump' above. |
Audio-clip | Plays a sound file. |
Transform | Introduces an affine transform into the display list. All items following it are accordingly transformed until the next 'Transform' item.
Transforms can be specified by one or more things such as: ro=<angle (in degrees)> m=<magnification factor> mx or my=<horizontal or vertical magnification factor> x or y=<rotation/magnification centre> tx=m00,m10,m01,m11,m02,m12 |
See also:
Page instruction
Output mark-ups
DISPLAY table
Page instruction
This instruction does a single sub-function chosen from a menu when first created. The sub-functions are as follows:-
Sub-function | Description |
---|---|
Select | This selects the 'current' page for output. The variable 'CP' is set to the name of the page. If the page does not exist a new one is created. The page is moved to the front. Output mark-ups are also interpreted to change size etc. |
Destroy | This completely removes the current page. The previous current page is made current, or if it does not exist, the front-most page is made current. |
Clear | This removes the contents of the current page, subject to whether parts of it were `frozen` (see `Freeze` below) |
Freeze | This causes the current contents of the page to be kept intact despite `Clear` instructions or scrolling. It can be used to create a fixed background for other graphical output. |
Direct | Switches `direct-mode` on or off. In direct mode outputs to the page are written directly to the screen, so they will not be refreshed by the operating system in the normal way. It can be useful in animation. |
Format | This allows the page width, height, position, default font,style and size and `PAPER` and `INK` colours to be set. |
Refresh | Normally (when not in direct-mode, see above) the page will be redrawn on the screen when a `Wait` instruction is executed, only if a previous `Output` instruction was executed. This immediately updates the display, and is useful if the page contents was altered via `DISPLAY` table. |
Print(,tables) | Prints the current page, or list of tables containing data in
the same format as 'DISPLAY'. All currently existing pages are contained in the table 'PAGE', with record 1 being the current page. |
Dump | Outputs the contents of the current page as an image file, either '.jpg/jpeg' or '.png', depending on file extention -default is 'jpeg'. |
See also:
Output Mark-ups
Data types
Operators
System variables
Events
DISPLAY table
The Display
PAGE table
File system instruction
There are 9 types (sub-functions) of file system instruction. Each sub-function may succeed or fail, and the corresponding link is followed. If it fails, the system variable 'FILE_MESSAGE' is set to a message describing the reason for the failure, other wise it is set to "OK". The sub-functions are as follows:-
Sub-function | Description |
---|---|
Save | Saves the current program. If no filename is given it is saved under its current name. |
MakeDir | Creates a directory |
Delete | Deletes a file or directory. Directories must be empty before being deleted. |
Rename | Renames a file or directory |
Copy | Copies a file of up to 200MB in length to a given destination |
Execute | Passes a command to the underlying operating system. |
Dump | Creates or overwrites a file with the contents of a table. The table rows are treated as text strings and are output in the default platform encoding (e.g. Unicode UTF-8). |
Append | As 'Dump' above, but any existing file is appended to rather than overwritten |
Dump_Image | Creates or overwrites a file with a compressed image file representation of the current output page. The encoding is determined by the given file extension as follows: filenames ending in '.jpg' or '.JPG' will have the image saved in 'JPEG' format, otherwise the image will be in 'PNG' format) |
See also:
System variables
PAGE table
This table contains information about all the currently
existing pages. It has the following fields:
name: name of page (used in 'Select' instruction)
x: x-coordinate of top left corner within desktop
y: y-coordinate of top left corner within desktop
width: width of paintable area
height: height of paintable area
state: one of 'showing' or 'icon'
fmt: Mark-ups as included in 'Select Page' instruction, (e.g. f=Font etc.)
Note:
When a page is selected for output (i.e. CP=page name), it is moved to record 1 in PAGE.See also:
DISPLAY table
Output mark-ups
Present instruction
This instruction displays a table in one of 3 ways, depending on the
field names and contents: If the field names match the DISPLAY table, the
table is assumed to be 'graphics' from the graphical editor, and is displayed as such.
Otherwise it is displayed as a grid of rows(records) and columns(fields), unless
there is a single columns with the name 'text' in which case the table rows are
displayed a rows of text. When displaying 'graphics', any buttons or scrollbars
contained will be activated by this instruction (as long as the program is designed to use them!).
See also:
Edit instruction
Select instruction
Any table may be searched with this
instruction. The search comprises a 'selection expression` against which
all (or a sub-set of) records in the table are tested for a `match`. The
variable is assigned the value of the set of the indices
of all matching records. The `filter` (or `where` part) may be any
expression which gives a `boolean` (=true or false) result. Eg.
[where] age IN {21..50} AND smoker="No"
[where] MX IN x TO
x+width
Any ordinary variable sharing the same name as a field is
ignored in evaluating the expression, and instead the value of that field
for the record being tested is used. Additionally the system variable
RECORD gives the number of the record being tested, and can be used
to make relative references to other (e.g. adjacent) records.
Another feature is the 'filter' parameter which may be used to limit the number of
records tested to improve efficiency. The filter parameter consists
of a set of record numbers to be tested (instead of the default of all records),
thereby speeding up the instruction. It can be used to 'narrow down' a selection. See also:
Expressions
Sort instruction
Choice instruction
Delete instruction
Insert instruction
Update instruction
Destroy instruction
Create instruction
Sort instruction
This instructions allow tables to be sorted based
on the contents of their data fields. Rows (records) of a table may
be sorted on one or more fields (columns). Whether letters are upper
or lower case is ignored when sorting, and fields of wholly numeric
values are sorted numerically rather than alphabetically. The order
and direction in which fields are used for sorting is specified by a
comma-separated list of field names, starting with the highest
priority field. By default, records are sorted in ascending order,
but any field may be used to sort in descending order by prefixing it
with a minus sign.
E.g. "title,-page" would cause sorting on the field 'title', in ascending order.
Records with the same value of 'title' would be further sorted in
descending order on the field 'page'
It is also possible to specify arbitrary sort orders by following the relevant field name
with a colon and then a series of colon-separated values which, when matched by a data item,
would cause that item to be ordered accordingly. Each pre-defined value may be ended with
".." in which case, instead of an exact match being required, data items starting with the characters preceding the ".." would be matched.
E.g. day:Mo..:Tu..:We..:Th..:Fr..:Sa..:Su.. would sort on the field 'day' into day-of-week order for most variants of spelling in English (however capitalised),
whereas day:Mon:Tue:Wed:Thu:Fri:Sat:Sun would put 'Tue' before "Monday"
See also:
Select instruction
Choice instruction
Delete instruction
Insert instruction
Update instruction
Destroy instruction
Create instruction
Start and End instructions
Each instruction-block has a single `Start` instruction which is the first instruction executed when it is called by another instruction-block. The `Start` instruction is also used to hold information on any `parameters` passed to the instruction-block by the calling instruction-block, and any named links that it has. The instruction-block may have a single unnamed link or as many named links as desired. The `End` instruction is used to choose which link should be followed when the instruction-block finishes (`returns`). The links may be added removed and named by editing the 'Start` instruction and, when more than one link is available, the `End` instructions may be programmed to follow a particular link by right-clicking on the instruction and choosing from the menu.
Wait instruction
A BUBBL program executes a `Wait` instruction
when it has nothing to do for a while. The instruction tells the
computer to do nothing until something happens to trigger it into
action. Such a trigger is known as an `event`, and is caused by one
of the following: A key on the keyboard is pressed or released A
mouse button is pressed or released The mouse is moved A `tick` or
`un-tick` happens (alternate 1/5ths of a second) A display page is
resized or closed by the user A button is pressed by the user A
scroll-bar is moved by the user The wait instruction allows `set`s of
numbered events to trigger particular actions (=follow links). Each
type of event has a unique number. When an event occurs the first
link whose set contains the number of the event is followed. If no
link is tied to the event it is ignored.
Note: To create a new link,
click `Add new line` in the editor.
The set of events for each link must be expressed as a set value,
not an expression giving a set: Eg.
0..z,SPACE is ok, but 2 TO 32 will not work Surrounding {} are
optional.
See also:
Events
Switch instruction
This instruction allows the program to choose
one of several links depending on the value of an expression. When
the instruction is entered, the expression is evaluated and should
give either a number or a string. For a number each link is
associated with a set of integers against which the number is
compared. The first link whose set contains the number is followed.
For a string, each link is associated with a comma-separated set of
strings. The first link whose string-set has the string is followed.
In either case if there is no such match the link labelled `Default`
is followed. To add new links to a switch instruction click the `Add
new line` button in the instruction editor.
See also:
Expressions
System variables
The following symbols have the described interpretation (i.e. as `variables`) when used in expressions.
Event information/Miscellaneous
Variable | Access | Description |
---|---|---|
EVENT | r | This is the event number of the last responded to event |
EVENTS | r | This is a comma-separated list of the pending events (the 'queue'). The first number in the list is the next event |
UI | r | When a button or scroll-bar is activated by the user, a 'USER' event is raised, and this variable is set to the index in DISPLAY of the button or scroll-bar causing it. |
TICKS | r | This gives the count of tick events since one was last acted on |
EXTRN_DB | r/w | This may be set to the path of a read-only 'external' database |
FREE_MEM | r | Gives the available free memory in bytes |
USED_MEM | r | Gives the used memory in bytes |
RECORD | r | This variable is only of use within 'Select' instructions where it gives the index of record being tested against the query |
SYSTEM | r | Gives 1 (true) if the current instruction block is a system program |
TIME | r | Local time in seconds since 00:00 1/1/2000 |
ENCODING | r/w | Text file encoding to use for Create instruction when reading text file. Default value is taken from the platform. Possible values include (e.g.)'ISO-8859-1', 'UTF-8', 'US-ASCII'. |
UTC | r | UTC (or 'GMT') in seconds since 00:00 1/1/2000 |
USER_NAME | r | Gives the log-in name of the current user |
DEBUG | w | Values written to this are echoed to standard output. Useful for real-time debugging. |
DUMP | w | Writing a table name to this causes standard output to be buffered in the table. Useful for real-time debugging. |
CLIPBOARD(text) | r | Table containing contents of system clipboard if it has a MIME text type available |
PAGE(name,x,y...) | r | Table of all the currently active display 'page's ('windows' or 'frames') and various bits of state information |
TABLE(name,fields,system,size) | r/w | A table of all the tables in the system. Inserting a record creates a table with the specified number of blank records and fields. Deleting a record will delete the corresponding table if it is not a built-in system table. It does (of course) contain itself |
INET | r/w | Converts URL to IP address |
HOST | r | Gives the I/D of the network local host |
SEED | r/w | Writing with 'password' string initialises ENCRYPTED operator. Reading gives 31 bit encryption seed value which can be used to authenticate 'passwords' |
SYS_TABLE | r/w | This variable maps onto a table from the system programs (loaded from 'SYS.ken'). Writing to it selects the table, and accessing it as a table (i.e. using [] operators) accesses the selected table. |
USR_TABLE | r/w | This variable maps onto a table from the user programs (loaded from ' |
UNDO_DUMP_FILE | r/w | Writing with file name causes 'undo script' for last few thousand instructions to be written to the file |
'Drag and Drop' system
Variable | Access | Description |
---|---|---|
DRAGGED(text) | r/w | Table containing data from dragged text MIME type |
DSP | r | Gives the page on which a drag operation started. Gives blank if drag originated outside the program. |
DRP | r | Gives the page being dragged over. Gives blank if dragged outside the program. | DROP_OK | r/w | May be set to true (1) to allow dragged data to be dropped on the most recent page dragged over. It is cleared automatically when the drag operation leaves the page, so must be set to true again (if desired) on the next 'DRAG' event. |
MIME | r/w | Gives the MIME type of current or most recently dragged data. A 'MOUSE_LEFT' event resets the drag and drop system, and may be followed by setting this variable to a valid mime type (e.g. "text/uri-list") or empty string to enable a drag from the BUBBL program. The table 'DRAGGED' should contain the data to be dragged prior to enabling the drag operation (usually in response to a MOUSE_LEFT event). |
Key event processing
Variable | Access | Description |
---|---|---|
ALT | r | Gives 1 (true) if the 'Alt' key was pressed for the current event |
CTRL | r | Gives 1 (true) if the 'Ctrl' key was pressed for the current event |
CASED_KEY | r | Gives code of the character typed taking account of 'shift' keys etc according to UK Keyboard layout |
TYPED | r | Gives the character typed as a character |
KEY | r | Gives the event number of the last key pressed |
SHIFT | r | Gives 1 (true) if a 'Shift' key was pressed for the current event |
Mouse event handling
Variable | Access | Description |
---|---|---|
MP | r | Gives the name of the page on which the last mouse event occurred |
MX | r | Gives the x co-ordinate of the mouse pointer at the last mouse event |
MY | r | Gives the y co-ordinate of the mouse pointer at the last mouse event |
MW | r | Gives the number of forward or backward(-ve) mouse wheel clicks from the last 'MOUSE_WHEEL' event |
MOUSE_OVER | r | Gives a set of the indicies in DISPLAY of the items over which the mouse pointer is |
MOUSE_RADIUS | r/w | The distance in pixels used by MOUSE_OVER when testing items |
MOUSE_OVERLAY | r | Gives a set of the indicies in OVERLAY of the items over which the mouse pointer is |
Display-system state
Variable | Access | Description |
---|---|---|
CP | r | Gives the name of the page currently selected for output |
CX | r | Default X-co-ordinate of next screen output (within page) |
CY | r | Default Y-co-ordinate of next screen output (within page) |
CURSOR | r/w | Gives the current mouse cursor type, one of N,S,E,W,NE,SE,SW,NW for respective 'outline-dragging' cursors, or one of the following: DEFAULT - system default CROSS - Cross-hairs HAND - Hand MOVE - Dragging WAIT - Waiting TEXT - Text |
CURSORS | r | Comma-separated possible values for CURSOR |
DISPLAY(thing,x,y...) | r/w | Table of contents of current page (CP) |
FOCUS | r | Gives the name of the page with keyboard focus. |
PH | r | Height of current page (CP) in pixels |
PT | r | Title of current page |
PV | r | Gives 1 (true) if the current page is not minimised |
PW | r | Width of current page (CP) in pixels |
PX | r | Gives the screen x-co-ordinate of the current output page, relative to the BUBBL 'desktop' |
PY | r | Gives the screen y-co-ordinate of the current output page, relative to the BUBBL 'desktop' |
DH | r | Height of the desktop window in pixels |
DW | r | Width of the desktop window in pixels |
SH | r | Height of the screen in pixels |
SW | r | Width of the screen in pixels |
WINDOW | r | Gives the type of of current output page window. Its value is one of res,scr,fix for resizable, scrollable, fixed-sized |
Text formatting
Variable | Access | Description |
---|---|---|
FONT | r | Default font for text output |
BOLD | r | Gives 1 if default font is bold, 0 otherwise |
ITALIC | r | Gives 1 if default font is italic, 0 otherwise |
SIZE | r | Point-size of default font (FONT) |
PAPER | r | Background r,g,b colour of current page |
INK | r | Default drawing r,g,b colour of CP |
FONTNAME(name) | r | Table of available fonts |
Printer control
Variable | Access | Description |
---|---|---|
DIALOGUE | r/w | Set to 1 (true) to pop-up user printer-dialogue before printing |
LANDSCAPE | r/w | Set to 1 (true) to force landscape orientation printing |
LEFT_MARGIN | r/w | Specify the left margin (non-printing area) in 'points' (=1/72 inch) |
RIGHT_MARGIN | r/w | Specify the right margin (non-printing area) in 'points' (=1/72 inch) |
TOP_MARGIN | r/w | Specify the top margin (non-printing area) in 'points' (=1/72 inch) |
BOTTOM_MARGIN | r/w | Specify the bottom margin (non-printing area) in 'points' (=1/72 inch) |
PAPER_WIDTH | r/w | Specify the width of pages for printing (including margins) in 'points' (=1/72 inch) |
PAPER_HEIGHT | r/w | Specify the height of pages for printing (inlcuding margins) in 'points' (=1/72 inch) |
Environment globals
Variable | Access | Description |
---|---|---|
PROG_FILE | r | Filename of program currently being run |
BROWSER | r/w | Command line for HTML browser for help file viewing |
INFO_FILE | r/w | File path of user program info (help) file. Defaults to <working directory>+"BUBBLSys.htm" |
INFO_KEY | r/w | Reference id for next user info button press |
File-system
Variable | Access | Description |
---|---|---|
SEPARATOR | r | Gives '/' for Linux operating system, '\' for others |
ROOT(name,ext,dir) | r | Table of all the available file system roots. Note: There will only be one record for '/' using operating systems, whereas there will be one for each physical drive for '\' using systems. |
FILE_PATH | r/w | File 'path' used to fill FILE table, set initially to user's working directory. When his variable is assigned to, the table 'FILE' is updated to reflect the current contents of the directory indicated by the value assigned. |
FILE(name,ext,dir,size,time,hidden,read,write) | r | Table of files in FILE_PATH ext is file-spec from last dot dir is 1 if the file is a directory, 0 otherwise. size is file size in bytes time is time file last updated in seconds since 1st Jan 2000 read is 1 if file is readable, 0 otherwise write is 1 if file is writable, 0 otherwise |
USER_HOME | r | User's home directory |
WORKING | r | User's working directory |
FILE_MESSAGE | r | Gives 'Ok' if last 'FileSys' instruction was successful. If it failed, gives an explanatory message. |
Child Program
Variable | Access | Description |
---|---|---|
CHILD(File,Libs,Progs,Nodes,Steps,Params,State) | r/w | Each row gives the current state of a child program. Inserting a new row creates a new child program if the 'File' field refers to a valid program file. |
CHILD_CTL | w | Assiging to this variable controls a child program. The following commands are valid: GOTO,<child>,<lib>,<prog>,<node> RUN,<child> RUN_TO,<child>,<lib>,<prog>,<node> STEP,<child> BACK,<child> BACK_TO,<child>,<lib>,<prog>,<node> STOP,<child> RENEW,<child>,<table>,<prog>(Note: no table indicates program should be deleted) |
CHILD_TABLE | r/w | This variable maps onto a table of the child program indexed by 'CHILD_NO'. Writing to it selects the table from the child program. After writing to it, the selected table can be accessed by referring to this variable as a table (e.g. CHILD_TABLE[0]). |
CHILD_NO | r/w | Identifies the particular child program with a table mapped to 'CHILD_TABLE' |
CHILD_MESSAGE | r | Message from child program corresponding to last 'PROG_END' event |
Non-event constants
Variable | Access | Description |
---|---|---|
DAY | r | Number of seconds in a day=86 400 |
FALSE | r | =0 |
TRUE | r | =1 |
PI | r | =3.14159265358979323846 |
See also:
DISPLAY table
Operators
Data types
Events
The Display
The idea of a 'page' is used to organise visual output. Pages can be created and destroyed using `Page-Select` and `Page- Destroy` instructions, and can be printed and dumped to image files.
Some output is subject to 'mark-ups' which can be used to control things like fonts and colours (see Output mark-ups ).
The display management system maintains some variables: CP, CX, CY, INK, PAPER, FONT, ITALIC, BOLD, PX, PY, PW, PH, DW DH, SW, SH. Most of these variables apply to the current page (CP) only. In general they cannot be directly assigned to, but may change as a side effect of some other action such as use of the 'Page-Format' instruction. For example, `CX` and `CY` are modified by the 'Ouput-Expression' and 'Output @' instructions.
Normally the display is maintained using the 'Output' and 'Page` instructions. The standard unit of size is the 'Point' (1/72 of an inch for printing). All screen dimensions and coordinates etc. follow this convention. Additionally everything in the contents of the current page is availble to the program through the table variable `DISPLAY`.
Outputing to pages is affected by the current `mode`: If in `direct-write` mode any program output is displayed immediatley on the page, and anything written in this mode is subject to on-screen corruption by other screen objects (for example other software running on the computer).
Normally however,a list of display items is maintained automatically, and the items persist until expressly overwritten, scrolled or cleared off the screen. A page can also be 'frozen' so that items written to it before the 'Page-Freeze' instruction are not removed or scrolled, creating a static 'background'.
Items added to the display list after any `Page-Freeze on` instruction, or all display items, are subject to the following rules for removal from the display list.
- New items are appended to the end of the table (as in table insert instruction).
- 'Text' items, 'line' items (lines, rectangle, circle and polygon outlines and sectors) and 'area' items (solid rectangles, pictures etc.) are treated differently.
- Subject to the behaviour described above, an
item will be removed if:
- A 'clear screen' instruction is executed
- The list has>2000 items, and the item is number 1
- It's y-coordinate is -Ve after scrolling
- It is completely overlapped by a new 'area' object
- It is a text item and a new text item has the same co-ords
See also:
DISPLAY table
Output instruction
Page instruction
System variables
Output mark-ups