API Reference
Fire★ Apps are built using the Lua programming language. Fire★ provides a custom object oriented API for building Apps. The main object you interact with is the app object
app object
The app
object is a global object and provides functions for creating all other objects in an app.
It also provides other functions such as sending messages and handling them. This is the
entry point to the Fire★ API.
There is only one app
object.
app:print
print(message:string) : nil
Prints a string to the app editor log and Fire★ log. Newline is added automatically.
app:print("this is a debug message")
app:alert
alert() : nil
If the user does not have focus in Fire★ or they are in another conversation, then the conversation label turns red and the user is alerted through their operating system that there is something they need to pay attention to.
app:button
button(label:string) : button
Creates a button with text specified. The button must be placed on the canvas using the place function.
b = app:button("hello world")
app:place(b, 0, 0)
app:label
label(text:string) : label
Creates a label with text specified. The label must be placed on the canvas using the place function.
lb = app:label("cool app")
app:place(lb, 0, 0)
app:edit
edit(text:string) : edit
Creates a single line edit object with text specified. The edit object must be placed on the canvas using the place function.
e = app:edit("type here")
app:place(e, 0, 0)
app:text_edit
text_edit(text:string) : text_edit
Creates a multi-line text_edit object with text specified. The text_edit object must be placed on the canvas using the place function.
t = app:text_edit("type many things here")
app:place(t, 0, 0)
app:dropdown
dropdown() : dropdown
Creates a dropdown. The dropdown must be placed on the canvas using the place function.
d = app:dropdown()
d:add("option 1")
d:add("option 2")
app:place(d, 0, 0)
app:list
list() : list
Creates an empty list which you can use to add other widgets to. The list must be placed on the canvas using the place function.
lst = app:list()
app:place(lst, 0, 0)
app:grid
grid() : grid
Creates an empty grid which you can use to add other widgets to. The grid must be placed on the canvas using the place function.
The grid is similar to the canvas and allows you nest grids for laying out widgets.
g = app:grid()
app:place(g, 0, 0)
app:draw
draw() : draw
Creates a draw object which can be used to draw shapes to. The draw object must be placed on the canvas using the place function.
d = app:draw()
app:place(d, 0, 0)
app:pen
pen(color:string, width:int) : pen
Creates a pen which is used by the [draw](reference.md#draw-object] object. The first parameter is a color. This can either be a color name or a hex rgb value. The second parameter is the width of the pen in pixels.
d = app:draw()
r = app:pen("red", 3)
d:set_pen(r)
app:timer
timer(msec:int, callback:string) : timer
Creates a timer which can be used to call a function every x milliseconds. The timer starts right away.
t = app:timer(500, "foo()")
function foo()
app:print("foo")
end
app:image
image(data:bin_data) : image
Creates an image which can be used by various widgets to display pictures. An image takes binary image data as bin_data. This can be JPEG, PNG, BMP, and many other formats.
file = app:open_bin_file()
img = app:image(file:data())
app:place(img, 0,0)
app:mic
mic(callback:string, codec:string) : mic
Creates a mic object which can be used to get sound from a microphone. The callback must be a function of type
callback(bin_data)
Where the sound data is passed in as a bin_data object. The codec currently can either be "pcm" or "opus". "pcm" provides the callback raw audio data as single channel with a sample rate of 12k and a sample size of 16 bytes. "opus" provides compressed audio data using the opus codec.
The mic and speaker object must match codecs if you want to hear sound. Otherwise you can use the audio encoder and decoder to convert from/to pcm and opus.
m = app:mic("got_sound", "opus")
m:start()
function got_sound(data)
end
app:speaker
speaker(codec:string) : speaker
Creates a speaker object which can be used to play sound.
The codec currently can either be "pcm" or "opus". "pcm" provides the callback raw audio data as single channel with a sample rate of 12k and a sample size of 16 bytes. "opus" provides compressed audio data using the opus codec.
The mic and speaker object must match codecs if you want to hear sound. Otherwise you can use the audio encoder and decoder to convert from/to pcm and opus. speaker
s = app:speaker("opus")
app:audio_encoder
audio_encoder() : audio_encoder
Creates an audio_encoder which can be used to convert pcm audio to opus.
enc = app:audio_encoder()
app:audio_decoder
audio_decoder() : audio_decoder
Creates an audio_decorder which can be used to convert opus audio to pcm.
enc = app:audio_decoder()
app:vclock
vclock()
Creates a vclock object which is a vector clock. A vector clock can be used to determine if any messages were sent concurrently.
v = app:vclock()
app:place
place(widget, row:int, column:int) : nil
Places a widget on the canvas. The canvas is an invisible grid which you can place your widgets on. A widget is not displayed until it is placed on the canvas.
a = app:button("one")
b = app:button("two")
app:place(a, 0, 0)
app:place(b, 1, 0)
app:place_across
place_across(widget, row:int, column:int, rows:int, columns:int) : nil
Places a widget on the canvas that can span across rows and columns. The canvas is an invisible grid which you can place your widgets on. A widget is not displayed until it is placed on the canvas.
a = app:button("one")
b = app:button("two")
c = app:button("three")
app:place_across(a, 0, 0, 1, 2)
app:place(b, 1, 0)
app:place(c, 1, 1)
app:height
height(pixels:int) : nil
Changes the height of the app in pixels. The app cannot get smaller than the height specified. Use this if you want more vertical room.
app:width
width(pixels:int) : nil
Changes the width of the app in pixels. The app cannot get smaller than the width specified. Use this if you want more horizontal room.
app:total_contacts
total_contacts() : int
Returns the count of contacts in the conversation.
app:contact
contact(index:int) : contact
Returns the contact at the index specified in the conversation.
app:last_contact
last_contact() : int
Returns the index of the last contact in the conversation.
app:who_started
who_started() : contact
Returns the contact that added the App in the conversation.
app:self
self() : contact
Returns the contact information of user using the app.
app:total_apps
total_apps() : int
Returns the count of all the apps int the conversation.
app:app
app(index:int) : app
Returns the app at the index specified in the conversation.
app:message
message() : message
Creates a message which can be sent via the send function.
m = app:message()
m:set_type('a')
app:send(m)
app:when_message_received
when_message_received(callback:string) : nil
Sets the callback called when a message is received. The callback must be of the following form.
function callback(message)
end
The callback receives a message which was sent from another instance of the same App from a different contact
app:when_message_received("foo")
function foo(m)
end
app:when_local_message_received
when_local_message_received(callback:string) : nil
Sets the callback called when a local message is received. A local message is one that is sent by another app from within the conversation from the same instance.
The callback must be of the following form.
function callback(message)
end
The callback receives a message which was sent from another instance of the same App from a different contact
app:when_local_message_received("foo")
function foo(m)
end
app:when_message
when_message(type:string, callback:string) : nil
Sets the callback called when a message is received of a specific type.
Messages can have a type
which can be any string. You can capture messages of a specific
type with this callback
The callback must be of the following form.
function callback(message)
end
The callback receives a message which was sent from another instance of the same App from a different contact
app:when_message("foo", "bar")
function bar(m)
end
app:when_local_message
when_local_message(type:string, callback:string) : nil
Sets the callback called when a message is received of a specific type.
Messages can have a type
which can be any string. You can capture messages of a specific
type with this callback
A local message is one that is sent by another app from within the conversation from the same instance.
The callback must be of the following form.
function callback(message)
end
The callback receives a message which was sent from another instance of the same App from a different contact
app:when_local_message("foo", "bar")
function bar(m)
end
app:when_joined
when_joined(callback:string) : nil
Sets the callback called when a contact joins the conversation after the app runs. The callback must be of the following form.
function callback(contact)
end
The callback receives a contact who joined the conversation
app:when_joined("joined")
function joined(c)
local name = c:name()
end
app:when_quit
when_quit(callback:string) : nil
Sets the callback called when a contact quits the conversation. The callback must be of the following form.
function callback(contact)
end
The callback receives a contact who quit the conversation
app:when_quit("quit")
function quit(c)
local name = c:name()
end
app:send
send(msg:message) : nil
Sends a message to the same app to all contacts in the conversation. Once the message arrives to the other contacts, their respective message callbacks are called.
m = app:message()
m:set_type("foo")
app:send(m)
app:send_to
send_to(to:contact, msg:message) : nil
Sends a message to the same app to a specific contact in the conversation. Once the message arrives to the contact, their respective message callback is called.
m = app:message()
m:set_type("foo")
c = app:contact(0)
app:send_to(c, m)
app:send_local
send_local(msg:message) : nil
Sends a message to the all apps in the conversation locally. The message does not go over the network. Once the message arrives to the other apps, their respective local message callbacks are called.
This is useful for having different apps communicate with each other.
m = app:message()
m:set_type("foo")
app:send(m)
app:save_file
save_file(name:string, data:string) : nil
This opens up the file save dialog to allow a user to save some data to a file. You cannot specify the file location for safety reasons. This always brings up the file save dialog to allow the user to select the location of the file saved.
The name you give to this function is a suggested name and the user is free to change it.
app:save("hello.txt", "Hello World")
app:save_bin_file
save_bin_file(name:string, data:bin_data) : nil
This opens up the file save dialog to allow a user to save some binary data to a file. You cannot specify the file location for safety reasons. This always brings up the file save dialog to allow the user to select the location of the file saved.
The name you give to this function is a suggested name and the user is free to change it.
app:save_bin_file("hello.bin", bin_dat)
app:open_file
open_file() : file_data
This opens up the file open dialog to allow a user to load some data from a file. You cannot specify the file location for safety reasons. This always brings up the file open dialog to allow the user to select the file they want to open.
The function returns a file_data object which contains the contents of the file the user selected.
The name you give to this function is a suggested name and the user is free to change it.
data = app:open_file()
app:open_bin_file
open_bin_file() : bin_file_data
This opens up the file open dialog to allow a user to load some data from a file. You cannot specify the file location for safety reasons. This always brings up the file open dialog to allow the user to select the file they want to open.
The function returns a bin_file_data object which contains the contents of the binary file the user selected.
The name you give to this function is a suggested name and the user is free to change it.
data = app:open_bin_file()
app:bin_data
bin_data() : bin_data
Creates an empty binary data bin_data object. You can use this to manipulate binary data.
data = app:bin_data()
data:set(0, 'i')
app:i_started
i_started() : bool
Returns true if the user of the instance started the app in the conversation. If the app started from a remoted user, then this will return false.
button object
A button can be clicked. When it is clicked things can happen. Use app:button to create a button.
button:text
text() : string
Returns the text that the button is displaying.
t = my_button:text()
button:set_text
set_text(text:string) : nil
Sets the text the button will display.
my_button:set_text("Press me now")
button:set_image
set_image(img:image) : nil
Sets an image instead of text to the button. You have to use an image
my_button:set_image(my_image)
button:callback
callback() : string
Returns the code that will run when the button is clicked. Use when_clicked to set the code that will be executed.
code = my_button:callback()
button:when_clicked
when_clicked(code:string) : nil
Sets the code that will execute when the button is clicked.
my_button:when_clicked("foo()")
function foo()
end
button:set_name
set_name(name:string) : nil
When you give a name to a widget, it has a life that is shared across all instances. All events in one instance are propagated automatically to the others.
For the case of a button, if the button is clicked on one instance, it will be clicked on all instances.
my_button:set_name("some unique name")
my_button:when_clicked("foo()")
function foo()
end
So if one user clicked on the button, then the "foo" function will be called for each user in a conversation.
button:set_style
set_style(style:string) : nil
Sets the style of the widget. You can use Qt Style Sheets.
my_button:set_style("background-color: 'green'")
button:enabled
enabled() : bool
Returns true if the button is enabled.
en = my_button:enabled()
button:enable
enable() : nil
Enables the button.
my_button:enable()
button:disable
disable() : nil
Disables the button.
my_button:disable()
button:visible
visible() : bool
Returns true if the button is visible
en = my_button:visible()
button:show
show() : nil
Makes the button visible.
my_button:show()
button:hide
hide() : nil
Hides the button.
my_button:hide()
label object
A label can show text. Use labels to label things. Create a label the app:label. function.
label:text
text() : string
Returns the text that the label is displaying.
t = my_label:text()
label:set_text
set_text(text:string) : nil
Sets the text the label will display.
my_label:set_text("Showing stuff, things")
label:set_style
set_style(style:string) : nil
Sets the style of the widget. You can use Qt Style Sheets.
my_label:set_style("background-color: 'green'")
label:enabled
enabled() : bool
Returns true if the label is enabled.
en = my_label:enabled()
label:enable
enable() : nil
Enables the label.
my_label:enable()
label:disable
disable() : nil
Disables the label.
my_label:disable()
label:visible
visible() : bool
Returns true if the label is visible.
en = my_label:visible()
label:show
show() : nil
Makes the label visible.
my_label:show()
label:hide
hide() : nil
Hides the label.
my_label:hide()
edit object
An edit object provides a single line for a user to type text in. Create one using the app:edit function.
edit:text
text() : string
Returns the text that the edit box is displaying.
t = my_edit:text()
edit:set_text
set_text(text:string) : nil
Sets the text the edit box will display.
my_edit:set_text("Press me now")
edit:edited_callback
edited_callback() : string
Returns the function that will run when the edit box text changes. Use when_edited to set the function that will be executed.
code = my_edit:edited_callback()
edit:when_edited
when_edited(func:string) : nil
Sets the function that will execute when the edit box text changes. The callback must be of the form
callback(text:string)
Where the text is the new text of the edit box
my_edit:when_edited("foo")
function foo(text)
end
edit:finished_callback
finished_callback() : string
Returns the function that will run when the user leaves or presses enter in the edit box. Use when_finished to set the function that will be executed.
code = my_edit:finished_callback()
edit:when_finished
when_finished(func:string) : nil
Sets the function that will execute when the edit box text changes. The callback must be of the form
callback(text:string)
Where the text is the new text of the edit box.
my_edit:when_finished("foo")
function foo(text)
end
edit:set_name
set_name(name:string) : nil
When you give a name to a widget, it has a life that is shared across all instances. All events in one instance are propagated automatically to the others.
For the case of an edit box, when the edit box text changes on one instance, it will change on all instances.
my_edit:set_name("some unique name")
my_edit:when_edited("foo")
function foo(text)
end
So if one user chnages the text int the edit box, then the "foo" function will be called for each user in a conversation.
edit:set_style
set_style(style:string) : nil
Sets the style of the widget. You can use Qt Style Sheets.
my_edit:set_style("background-color: 'green'")
edit:enabled
enabled() : bool
Returns true if the edit is enabled.
en = my_edit:enabled()
edit:enable
enable() : nil
Enables the edit.
my_edit:enable()
edit:disable
disable() : nil
Disables the edit.
my_edit:disable()
edit:visible
visible() : bool
Returns true if the edit is visible
en = my_edit:visible()
edit:show
show() : nil
Makes the edit visible.
my_edit:show()
edit:hide
hide() : nil
Hides the edit.
my_edit:hide()
text_edit object
A text_edit object provides a multi line text editor for a user to type text in. Use app:text_edit to create a text_edit object.
text_edit:text
text() : string
Returns the text that the text_edit box is displaying.
t = my_text_edit:text()
text_edit:set_text
set_text(text:string) : nil
Sets the text the text_edit box will display.
my_text_edit:set_text("Press me now")
text_edit:edited_callback
edited_callback() : string
Returns the function that will run when the text_edit box text changes. Use when_edited to set the function that will be executed.
code = my_text_edit:edited_callback()
text_edit:when_edited
when_edited(func:string) : nil
Sets the function that will execute when the text_edit box text changes. The callback must be of the form
callback(text:string)
Where the text is the new text of the text_edit box
my_text_edit:when_edited("foo")
function foo(text)
end
text_edit:set_name
set_name(name:string) : nil
When you give a name to a widget, it has a life that is shared across all instances. All events in one instance are propagated automatically to the others.
For the case of an text_edit box, when the text_edit box text changes on one instance, it will change on all instances.
my_text_edit:set_name("some unique name")
my_text_edit:when_text_edited("foo")
function foo(text)
end
So if one user chnages the text int the text_edit box, then the "foo" function will be called for each user in a conversation.
text_edit:set_style
set_style(style:string) : nil
Sets the style of the widget. You can use Qt Style Sheets.
my_text_edit:set_style("background-color: 'green'")
text_edit:enabled
enabled() : bool
Returns true if the text_edit is enabled.
en = my_text_edit:enabled()
text_edit:enable
enable() : nil
Enables the text_edit.
my_text_edit:enable()
text_edit:disable
disable() : nil
Disables the text_edit.
my_text_edit:disable()
text_edit:visible
visible() : bool
Returns true if the text_edit is visible
en = my_text_edit:visible()
text_edit:show
show() : nil
Makes the text_edit visible.
my_text_edit:show()
text_edit:hide
hide() : nil
Hides the text_edit.
my_text_edit:hide()
list object
You can put widgets in a list which are displayed vertically. Use app:list to create a list.
list:add
add(object:widget) : nil
Adds a widget to the list.
b = app:button("me me me")
my_list:add(b)
list:remove
remove(object:widget) : nil
Removes a widget from the list.
b = app:button("me me me")
my_list:add(b)
my_list:remove(b)
list:size
size() : int
Returns count of all widgets in the list.
s = my_list:size()
list:clear
clear() : nil
Removes all widgets from the list.
my_list:clear()
list:set_style
set_style(style:string) : nil
Sets the style of the widget. You can use Qt Style Sheets.
my_list:set_style("background-color: 'green'")
list:enabled
enabled() : bool
Returns true if the list is enabled.
en = my_list:enabled()
list:enable
enable() : nil
Enables the list.
my_list:enable()
list:disable
disable() : nil
Disables the list.
my_list:disable()
list:visible
visible() : bool
Returns true if the list is visible
en = my_list:visible()
list:show
show() : nil
Makes the list visible.
my_list:show()
list:hide
hide() : nil
Hides the list.
my_list:hide()
dropdown object
You can put options in a dropdown which can be selected. Use app:dropdown to create a dropdown.
dropdown:add
add(option:string) : nil
Adds an options to the dropdown.
my_dropdown:add("option 1")
my_dropdown:add("option 2")
dropdown:get
get(index:int) : string
Returns the option at the index specified, or an empty string.
text = my_dropdown:get(0)
dropdown:selected
selected() : int
Returns the index of the option that is selected
index = my_dropdown:selected()
dropdown:size
size() : int
Returns count of all options in the dropdown.
s = my_dropdown:size()
dropdown:clear
clear() : nil
Removes all the options from the dropdown.
my_dropdown:clear()
dropdown:callback
callback() : string
Returns the callback that will run when an option is selected from the dropdown. Use when_clicked to set the callback that will be executed.
callback = my_dropdown:callback()
dropdown:when_selected
when_clicked(code:string) : nil
Sets the callback that will execute when an item from the dropdown is selected.
The callback must be of the form:
callback(item_index:int)
An example is:
my_dropdown:when_selected("foo")
function foo(index)
local text = my_dropdown:selected(index)
app:print("selected: "..text)
end
dropdown:set_name
set_name(name:string) : nil
When you give a name to a widget, it has a life that is shared across all instances. All events in one instance are propagated automatically to the others.
For the case of a dropdown, if a dropdown option is selected on one instance, it will be selected on all instances.
my_dropdown:set_name("some unique name")
my_dropdown:when_selected("foo")
function foo(index)
--called on all instances
end
So if one user selects an option in the dropdown, then the "foo" function will be called for each user in a conversation.
dropdown:set_style
set_style(style:string) : nil
Sets the style of the widget. You can use Qt Style Sheets.
my_dropdown:set_style("background-color: 'green'")
dropdown:enabled
enabled() : bool
Returns true if the dropdown is enabled.
en = my_dropdown:enabled()
dropdown:enable
enable() : nil
Enables the dropdown.
my_dropdown:enable()
dropdown:disable
disable() : nil
Disables the dropdown.
my_dropdown:disable()
dropdown:visible
visible() : bool
Returns true if the dropdown is visible
en = my_dropdown:visible()
dropdown:show
show() : nil
Makes the dropdown visible.
my_dropdown:show()
dropdown:hide
hide() : nil
Hides the dropdown.
my_dropdown:hide()
grid object
A grid object provides a way to layout widgets in a flexible way. You can nest grids within grids if you like. Use app:grid to create a grid.
grid:place
place(object:widget, row:int, column:int) : nil
Places a widget on the grid at the row and column specified. You can also nest grids as a grid is also a widget.
b = app:button("moo cow")
my_grid:place(b, 0, 0)
grid:place_across
place(object:widget, row:int, column:int, row_span:int, column_span:int) : nil
Places a widget on the grid at the row and column specified. You also must specify how many rows and columns the widget can span. This provides finer control over size and placements of widgets. You can also nest grids as a grid is also a widget.
a = app:button("moo cow")
b = app:button("chicken")
c = app:button("cat")
my_grid:place_across(a, 0, 0, 2, 2)
my_grid:place_across(b, 1, 0, 1, 1)
my_grid:place_across(b, 1, 1, 1, 1)
grid:enabled
enabled() : bool
Returns true if the grid is enabled.
en = my_grid:enabled()
grid:enable
enable() : nil
Enables the grid.
my_grid:enable()
grid:disable
disable() : nil
Disables the grid.
my_grid:disable()
grid:visible
visible() : bool
Returns true if the grid is visible
en = my_grid:visible()
grid:show
show() : nil
Makes the grid visible.
my_grid:show()
grid:hide
hide() : nil
Hides the grid.
my_grid:hide()
draw object
You can use a draw object to display graphics such as lines, circles, and images. Use app:draw to create one.
draw:mouse_moved_callback
mouse_moved_callback() : string
Returns the function called when the mouse is moved on the draw surface. Use when_mouse_moved to set the callback.
cb = my_draw:mouse_moved_callback()
draw:mouse_pressed_callback
mouse_pressed_callback() : string
Returns the function called when a mouse button is pressed on the draw surface. Use when_mouse_pressed to set the callback.
cb = my_draw:mouse_pressed_callback()
draw:mouse_released_callback
mouse_released_callback() : string
Returns the function called when the mouse button is released on the draw surface. Use when_mouse_released to set the callback.
cb = my_draw:mouse_released_callback()
draw:mouse_dragged_callback
mouse_dragged_callback() : string
Returns the function called when the mouse is dragged on the draw surface. Dragged means a mouse button was down when the mouse was moving. Use when_mouse_dragged to set the callback.
cb = my_draw:mouse_dragged_callback()
draw:when_mouse_mmoved
when_mouse_mmoved(func:string) : nil
Sets the function to be called when the mouse is moved on the draw surface.
The callback must be of the form:
callback(x: int, y: int)
Where x
and y
are the pixel coordinates of the mouse.
my_draw:when_mouse_mmoved("foo")
function foo(x, y)
end
draw:when_mouse_pressed
when_mouse_pressed(func:string) : nil
Sets the function to be called when a mouse button is pressed on the draw surface.
The callback must be of the form:
callback(button: int, x: int, y: int)
Where button
is the mouse button number and x
and y
are the pixel coordinates of the mouse.
my_draw:when_mouse_pressed("foo")
function foo(b, x, y)
end
draw:when_mouse_released
when_mouse_released(func:string) : nil
Sets the function to be called when a mouse button is released on the draw surface.
The callback must be of the form:
callback(button: int, x: int, y: int)
Where button
is the mouse button number and x
and y
are the pixel coordinates of the mouse.
my_draw:when_mouse_released("foo")
function foo(b, x, y)
end
draw:when_mouse_dragged
when_mouse_dragged(func:string) : nil
Sets the function to be called when a mouse is dragged on the draw surface. Dragged means a mouse button was down when the mouse was moving.
The callback must be of the form:
callback(button: int, x: int, y: int)
Where button
is the mouse button number and x
and y
are the pixel coordinates of the mouse.
my_draw:when_mouse_dragged("foo")
function foo(b, x, y)
end
draw:set_name
set_name(name:string) : nil
When you give a name to a widget, it has a life that is shared across all instances. All events in one instance are propagated automatically to the others.
For the case of a draw surface, if the draw is clicked or the mouse is moved, it will be clicked or moved on all instances.
my_draw:set_name("some unique name")
my_draw:when_mouse_moved("foo")
function foo(x, y)
end
So if one user moves the mouse, then the "foo" function will be called for each user
in a conversation with the x
and y
coordinates.
draw:clear
clear() : nil
Clears all graphics from the draw surface.
my_draw:clear()
draw:line
line(x1:int, y1:int, x2:int, y2:int) : line
Draws a line from x1
, y1
to x2
, y2
. Returns a reference
line object which can be used to manipulate the line.
line_ref = my_draw:line(0, 0, 500, 500)
draw:circle
circle(x:int, y:int, radius:int) : circle
Draws a circle at x
, y
with the radius
specified. Returns a reference
circle object which can be used to manipulate the circle.
circle_ref = my_draw:circle(50, 50, 20)
draw:image
image(img:image, x:int, y:int, width:int, height:int) : draw_image
Draws an image at x
, y
with the width
and height
specified. Returns a reference
draw_image which can be used to manipulate the image.
img_ref = my_draw:image(my_img, 50, 60, 120, 120)
draw:pen
pen(object:pen) : nil
Sets the pen used by the draw functions.
my_draw:pen(my_pen)
draw:get_pen
get_pen() : pen
Returns the pen used by the draw functions.
p = my_draw:get_pen()
draw:set_style
set_style(style:string) : nil
Sets the style of the widget. You can use Qt Style Sheets.
my_draw:set_style("background-color: 'green'")
draw:enabled
enabled() : bool
Returns true if the draw is enabled.
en = my_draw:enabled()
draw:enable
enable() : nil
Enables the draw.
my_draw:enable()
draw:disable
disable() : nil
Disables the draw.
my_draw:disable()
draw:visible
visible() : bool
Returns true if the draw is visible
en = my_draw:visible()
draw:show
show() : nil
Makes the draw visible.
my_draw:show()
draw:hide
hide() : nil
Hides the draw.
my_draw:hide()
line object
The line object is a reference to a line in a draw canvas Use draw:line to create one.
line:set
set(x1: double, y1: double, x2: double, y2: double ) : nil
Sets the location of a line in the draw object.
ln = my_draw:line(0, 0, 500, 500)
ln:set(500, 500, 345, 699)
line:set_pen
set_pen(pen: pen) : nil
Sets the pen of a line in the draw object.
ln = my_draw:line(0, 0, 500, 500)
ln:set_pen(app:pen("red", 3))
circle object
The circle object is a reference to a circle in a draw canvas Use draw:circle to create one.
circle:set
set(x: double, y: double, r: double) : nil
Sets the location of a circle in the draw object with the radius specified.
cr = my_draw:circle(0, 0, 40)
cr:set(500, 500, 50)
circle:set_pen
set_pen(pen: pen) : nil
Sets the pen of a circle in the draw object.
cr = my_draw:circle(0, 0, 40)
cr:set_pen(app:pen("red", 3))
draw_image object
The draw_image object is a reference to an image in a draw canvas Use draw:image to create one.
draw_image:set
set(x: int, y: int, w: int, h: int) : nil
Sets the location of an image in the draw object with the width and height specified.
image_ref = my_draw:image(my_img, 0, 0, 50, 50)
image_ref:set(500, 500, 50,50) --translates the image
image object
An image object can display a raster image of various formats. Use app:image to create one.
image:width
width() : int
Returns the width of the image in pixels.
w = my_image:width()
image:height
height() : int
Returns the height of the image in pixels.
h = my_image:height()
image:good
good() : bool
Returns true if the data used to create the was actual image data. Only good images are displayed.
g = my_image:good()
image:enabled
enabled() : bool
Returns true if the image is enabled.
en = my_image:enabled()
image:enable
enable() : nil
Enables the image.
my_image:enable()
image:disable
disable() : nil
Disables the image.
my_image:disable()
image:visible
visible() : bool
Returns true if the image is visible
en = my_image:visible()
image:show
show() : nil
Makes the image visible.
my_image:show()
image:hide
hide() : nil
Hides the image.
my_image:hide()
bin_data object
A bin_data object stores binary data. It is created from various functions such as app:open_bin_file.
bin_data:size
size() : int
Returns the size of the data in bytes.
s = my_data:size()
bin_data:get
get(index:int) : char
Returns the byte at the specified index.
s = my_data:get(5)
bin_data:set
set(index:int, byte:char) : nil
Sets the byte at the specified index.
my_data:set(5, 44)
bin_data:overlay
overlay(index:int, data:bin_data) : nil
Overlays the binary data at the position specified. Will resize if the original bin_data is too small
my_data:overlay(10, other_data)
bin_data:sub
sub(index:int, size:int) : bin_data
Returns a subsection of data at the specified index with the specified size.
s = my_data:sub(10, 25)
bin_data:append
append(data:bin_data) : nil
Appends data to the end.
my_data:append(more_ata)
bin_data:from_str
from_str(str:string) : nil
Converts a string to binary data.
my_data:from_str("hello")
bin_data:str
str() : string
Converts the data to a string.
app:print(my_data:str())
mic object
A mic object provides access to the microphone available to the computer. Create one using app:mic to create a mic.
mic:when_sound
when_sound(func:string) : nil
Sets the callback to be used when sound data is ready from the mic.
The callback must be of the following form:
callback(sound:bin_data)
The callback will be called repeated when more sound data is available.
my_mic:when_sound("foo")
spkr = app:speaker("opus")
function foo(sound)
spkr:play(sound)
end
mic:start
start() : nil
Start recording from the microphone.
my_mic:start()
mic:stop
stop() : nil
Stop recording from the microphone. This will cause the sound callback to stop being called.
my_mic:stop()
speaker object
A speaker object provides access to the speaker available to the computer. You can use this to play sounds. Use app:speaker to create a speaker.
speaker:play
play(sound:bin_data) : nil
Plays the sound given to it. The sound data must match the codec that the speaker was created with.
my_spkr:play(fun_sound)
speaker:mute
mute() : nil
Mutes the speaker.
my_spkr:mute()
audio_encoder object
An audio_encoder is used to encode pcm
audio data to opus
.
Use app:audio_encoder to create an audio_encoder.
audio_encoder:encode
encode(pcm:bin_data) : bin_data
Takes pcm
audio data and encodes it to opus
.
some_opus = my_encoder:encode(some_pcm)
audio_decoder object
An audio_decoder is used to decode opus
audio data to pcm
.
Use app:audio_decoder to create an audio_decorder.
audio_decoder:decode
decode(opus:bin_data) : bin_data
Takes opus
audio data and decodes it to pcm
.
some_pcm = my_decoder:decode(some_opus)
contact object
A contact object provides information about a contact. Use app:contact to access which contacts are connected to the conversation.
contact:id
id() : string
Returns the id
of the contact. Each contact has a unique id
.
id = my_friend:id()
contact:name
name() : string
Returns the name
of the contact. The name
is not unique.
name = my_friend:name()
contact:online
online() : bool
Returns the true if the contact is still online. If a contact will not be in the conversation anymore if the are offline.
on = my_friend:online()
app object
An app object provides information about an app in the conversation. Use app:app to access which apps are used in the current conversation.
app:id
id() : string
Returns the id
of the app. Each app has a unique id
.
id = some_app:id()
app:send
send(msg:message) : nil
Sends a local message to the app.
some_app:send(cool_msg)
message object
A message object is used to store data for a message. Create one using the app:message function. Send a message using the app:send function.
message:from
from() : contact
Returns the contact that the message came from.
c = cool_msg:from()
message:not_robust
not_robust() : nil
If a message is robust, then it will be resent automatically if it did not make it for a fixed amount of times. You can turn this off by calling this method.
cool_msg:not_robust()
message:get_bin
get_bin(key:string) : bin_data
Returns bin_data with the key specified.
dat = cool_msg:get_bin("sound")
message:set_bin
set_bin(key:string, val:bin_data) : nil
Sets bin_data with to key specified.
cool_msg:set_bin("sound", dat)
message:get_vclock
get_vclock(key:string) : bin_data
Returns a vclock with the key specified.
clock = cool_msg:get_vclock("clock")
message:set_vclock
set_vclock(key:string, val:bin_data) : nil
Sets vclock with to key specified.
cool_msg:set_vclock("clock", clk)
message:get
get(key:string) : lua object
Returns a lua object with the key specified.
stuf = cool_msg:get("stuff")
message:set
set(key:string, val:lua table) : nil
Sets a lua object with to key specified. This can be any lua type including tables. You can use this to send lua data structures. And use get to retrieve the data.
cool_msg:set("stuff", {name="hey", stuff="hi"})
message:is_local
is_local() : bool
Returns a true if the message is local.
loc = cool_msg:is_local()
message:set_type
set_type(type:string) : nil
Sets the type
of the message. The type can be used to call different functions
to respond to a message. You can use when_message method
in app to call a specific function based on the type.
cool_msg:set_type("pic")
message:type
type() : string
Returns the type
of the message.The type can be used to call different functions
to respond to a message. You can use when_message method
in app to call a specific function based on the type.
type = cool_msg:type()
message:app
app() : app
Returns the app that sent the message if it was sent locally. You can determine if a message is local by using is_local.
app = cool_msg:app()
file_data object
A file data object stores the file data returned from app:open_file.
file_data:good
good() : bool
Returns a true the file_data object is storing any file data.
good = my_file:good()
file_data:name
name() : string
Name of the file the user choose when using open_file.
name = my_file:name()
file_data:size
size() : int
Returns the size of the file picked in bytes.
sz = my_file:size()
file_data:data
data() : string
Returns the file data as a string.
dat = my_file:data()
bin_file_data object
A bin_file data object stores the binary file data returned from app:open_bin_file.
bin_file_data:good
good() : bool
Returns a true the bin_file_data object is storing any file data.
good = my_file:good()
bin_file_data:name
name() : string
Name of the file the user choose when using open_bin_file.
name = my_file:name()
bin_file_data:size
size() : int
Returns the size of the file picked in bytes.
sz = my_file:size()
bin_file_data:data
data() : bin_data
Returns the binary file data as a bin_file.
dat = my_file:data()
timer object
A timer object can be used to execute call at a regular interval. Use app:timer to a timer.
timer:running
running() : bool
Returns true if the timer is running.
is_running = my_timer:running()
timer:start
start() : nil
Starts the timer. Whatever function is set using when_triggered will be called.
my_timer:start()
timer:stop
stop() : nil
Stops the timer.
my_timer:stop()
timer:interval
interval(msec:int) : nil
Sets the timer interval in milliseconds.
my_timer:interval(1500) --second and a half
timer:when_triggered
when_triggered(code:string) : nil
Sets the code called when the timer is triggered.
my_timer:when_triggered("foo()")
function foo()
end
pen object
A pen is used by the draw object to determine color and width of the lines and circles that are drawn. Use app:pen to create a pen.
pen:set_width
set_width(pixels:int) : nil
Sets the width of the pen.
my_pen:set_width(4)
vclock object
A vclock object is a vector clock. A vector clock can be used to determine if messages are sent concurrently. You can send clocks with messages and use them to partially order messages and determine when concurrent messages are sent.
Vector clocks are useful if you want need to have some understanding of order of events.
vclock:good
good() : bool
Returns true if it is a valid vector clock.
yay = my_clock:good()
vclock:inc
inc() : bool
Increments the element for the current user by one in the vector clock.
my_clock:inc()
vclock:merge
merge(other:vclock) : nil
Merges two vector clocks together. The clock is modified in place.
my_clock:merge(other_clock)
vclock:conflict
conflict(other:vclock) : bool
Returns true if the two vector clocks are in conflict. This means the clocks have concurrent changes and are not equal.
c = my_clock:conflict(other_clock)
vclock:concurrent
concurrent(other:vclock) : bool
Returns true if the two vector clocks are concurrent. This means that neither clock is newer. The clocks may be identical.
c = my_clock:concurrent(other_clock)
vclock:comp
comp(other:vclock) : int
Compares two vector clocks.
- Returns -1 if the other clock is greater.
- Returns 1 if the other clock is less.
- Returns 0 if the clocks are not less or greater.
This can be used to create a partial ordering of events.
c = my_clock:comp(other_clock)
vclock:equals
equals(other:vclock) : bool
Returns true if the two vector clocks are identical.
identical = my_clock:equals(other_clock)
store object
A store object is a global object that can be used to store permanent data. This data
will be available to all apps and survives restarts. There is only one store
object.
store:get_bin
get_bin(key:string) : bin_data
Returns bin_data with the key specified.
dat = store:get_bin("sound")
store:set_bin
set_bin(key:string, val:bin_data) : nil
Sets bin_data with to key specified.
store:set_bin("sound", dat)
store:get_vclock
get_vclock(key:string) : bin_data
Returns a vclock with the key specified.
clock = store:get_vclock("clock")
store:set_vclock
set_vclock(key:string, val:bin_data) : nil
Sets vclock with to key specified.
store:set_vclock("clock", clk)
store:get
get(key:string) : lua object
Returns a lua object with the key specified.
stuf = store:get("stuff")
store:set
set(key:string, val:lua table) : nil
Sets a lua object with to key specified. This can be any lua type including tables. You can use this to save lua data structures. And use get to retrieve the data.
store:set("stuff", {name="hey", stuff="hi"})
store:has
has(key:string) : bool
Returns true if the key exists.
has_stuff = store:has("stuff")
store:remove
remove(key:string) : bool
Removes the value with the key from the store. Returns true if the value was removed.
removed = store:remove("stuff")
data object
A data object is a global object that can be used to store app data permanently. This data is stored with the app and is sent to all contacts along with the app. Use this to store any data the app needs like graphics and sounds. Do not store a lot of data because it is sent to all contacts in a conversation each time the app starts.
You can also populate the data using the data
tab in the App Editor.
data:get_bin
get_bin(key:string) : bin_data
Returns bin_data with the key specified.
dat = data:get_bin("sound")
data:set_bin
set_bin(key:string, val:bin_data) : nil
Sets bin_data with to key specified.
data:set_bin("sound", dat)
data:get_vclock
get_vclock(key:string) : bin_data
Returns a vclock with the key specified.
clock = data:get_vclock("clock")
data:set_vclock
set_vclock(key:string, val:bin_data) : nil
Sets vclock with to key specified.
data:set_vclock("clock", clk)
data:get
get(key:string) : lua object
Returns a lua object with the key specified.
stuf = data:get("stuff")
data:set
set(key:string, val:lua table) : nil
Sets a lua object with to key specified. This can be any lua type including tables. You can use this to save lua data structures. And use get to retrieve the data.
data:set("stuff", {name="hey", stuff="hi"})
data:has
has(key:string) : bool
Returns true if the key exists.
has_stuff = data:has("stuff")
data:remove
remove(key:string) : bool
Removes the value with the key from the data. Returns true if the value was removed.
removed = data:remove("stuff")