237 lines
14 KiB
Markdown
237 lines
14 KiB
Markdown
# Laptop Mod API
|
|
|
|
## Add new hardware nodes
|
|
`laptop.register_hardware(name, hwdef)`
|
|
- `name` - Item name (prefix) The created node names are name_variant
|
|
- `hwdef.description` - Computer item name
|
|
- `hwdef.infotext` - Text shown if node is pointed
|
|
- `hwdef.sequence` = { "variant_1_name", "variant_2_name", "variant_3_name" } On punch swaps sequence. the first variant is in creative inventory
|
|
- `hwdef.custom_launcher` - optional - custom launcher name
|
|
- `hwdef.os_version` - optional - Set OS version. ('1.10', '3.31' or '6.33') By default the latest version is used
|
|
- `hwdef.tty_style` - optional - override CS-BOS console textcolor
|
|
- `hwdef.tty_monochrome` - Old computer with monochrome CRT screen
|
|
- `hwdef.custom_theme` - optional - custom initial theme name
|
|
- `hwdef.hw_capabilities` = { "hdd", "floppy", "usb", "net", "liveboot" } Table with hardware capabilities. Default is all, if nothing set
|
|
- `hwdef.node_defs` - A list for node definitions for each variant. with hw_state parameter for OS-initialization
|
|
```
|
|
hwdef.node_defs = {
|
|
variant_1_name = {
|
|
hw_state = "resume", "power_on" or "power_off", -- Hardware state
|
|
--node 1 definiton
|
|
},
|
|
variant_2_name = {
|
|
hw_state = "resume", "power_on" or "power_off", -- Hardware state
|
|
--node 2 definiton
|
|
},
|
|
}
|
|
```
|
|
|
|
- `laptop.os_get(pos)` - Get an OS object. Usefull in on_construct or on_punch to initialize or do anything with OS
|
|
Needed in on_receive_fields to be able to call mtos:receive_fields(fields, sender) for interactive apps
|
|
- `laptop.after_place_node` / `laptop.after_dig_node` - (optional) can be used directly for node definition. Move laptop apps data to ItemStack if digged and restored back if placed again. So you can take along your laptop. Note: you need to set `stack_max = 1` because the data can be stored per stack only, not per item.
|
|
|
|
|
|
## Operating system object
|
|
`local mtos = laptop.os_get(pos)` - Get the Operating system object. Used internally, but usable for remote operations. mtos is passed to app methods as parameter
|
|
|
|
### Operating system methods
|
|
- `mtos:power_on(new_node_name)` - Free RAM, activate the launcher and if given swap node to new_node_name
|
|
- `mtos:resume(new_node_name)` - Restore the last running app after power_off. Means no free ram and no switch to launcher. Update formspec and if given swap node to new_node_name
|
|
- `mtos:power_off(new_node_name)` - Remove the formspec and if given swap node to new_node_name
|
|
- `mtos:swap_node(new_node_name)`- Swap the node only without any changes on OS
|
|
- `mtos:set_infotext(infotext)` - Set the mouseover infotext for laptop node
|
|
- `mtos:get_app(appname)`- Get the app instance
|
|
- `mtos:set_app(appname)` - Start/Enable/navigate to appname. If no appname given the launcher is called
|
|
- `mtos:get_theme(theme)`- Get theme data current or requested (theme parameter is optional)
|
|
- `mtos:set_theme(theme)`- Activate theme
|
|
- `mtos:get_os_attr()`- Get OS-version attributes (see mtos.os_attr)
|
|
- `mtos:save()` - Store all app-data to nodemeta. Called mostly internally so no explicit call necessary
|
|
- `mtos:pass_to_app(method, reshow, sender, ...)` - call custom "method" on app object. Used internally. Reshow means update formspec after update
|
|
- `mtos:select_file_dialog(param)` - call the select file dialog ('os:select_file')
|
|
```
|
|
if fields.load then
|
|
mtos:select_file_dialog({
|
|
mode = 'open', -- open/select or save mode
|
|
allowed_disks = {'hdd', 'removable'}, -- disks shown in disk overview ('ram', 'hdd', 'removable', 'cloud' or 'system')
|
|
selected_disk_name = data.selected_disk_name, -- Start selection on disk
|
|
selected_file_name = data.selected_file_name, -- Start selection with file
|
|
store_name = store_area, -- The storage_name used for fliles (Sample 'stickynote:files')
|
|
prefix = 'open_', -- Prefix for return files
|
|
})
|
|
elseif fields.open_selected_disk and fields.open_selected_file then
|
|
data.selected_disk_name = fields.open_selected_disk -- Selected disk (prefix 'open_' is used)
|
|
data.selected_file_name = fields.open_selected_file -- Selected file (prefix 'open_' is used)
|
|
```
|
|
- `mtos:print_file_dialog({ label= , text= })` - call the print file dialog ('printer:app')
|
|
|
|
### Operating system attributes
|
|
`mtos.pos` - Computers position vector
|
|
`mtos.node` = minetest.get_node(pos)
|
|
`mtos.hwdef` = Merged hardware definition (Hardware + Hardware node attributes merged to 1 object)
|
|
`mtos.meta` = Nade meta - mostly managed by block device framework
|
|
`mtos.bdev` = Block device framework object
|
|
`mtos.sysram` = System/OS ram partition, mtos.bdev:get_app_storage('ram', 'os')
|
|
`mtos.sysdata` = System/OS data partition, mtos.bdev:get_app_storage('system', 'os')
|
|
`mtos.theme` = Selected theme object
|
|
`mtos.os_attr` = Hard-coded attributes for OS version
|
|
`releaseyear`
|
|
`version_string`
|
|
`blacklist_commands` CS-BOS interpreter
|
|
`tty_style` CS-BOS Console color. Supported GREEN, AMBER, WHITE
|
|
`tty_monochrome` CS-BOS Console is monochrome, no color change supported
|
|
`min_scrollback_size` CS-BOS Buffer
|
|
`max_scrollback_size` CS-BOS Buffer
|
|
`custom_launcher` Custom launcher for OS (can be overriden on node level)
|
|
`custom_theme` Custom theme for OS (can be overriden on node level)
|
|
|
|
## Apps
|
|
### Definition attributes
|
|
`laptop.register_app(internal_shortname, { definitiontable })` - add a new app or view
|
|
- `app_name` - App name shown in launcher. If not defined the app is just a view, not visible in launcher but can be activated. This way multi-screen apps are possible
|
|
- `app_icon` - Icon to be shown in launcher. If nothing given the default icon is used
|
|
- `app_info` - Short app info visible in launcher tooltip
|
|
- `os_min_version` - minimum version to be used (CS-BOS, optional)
|
|
- `os_max_version` - maximum version to be used (CS-BOS, optional)
|
|
- `fullscreen` - (boolean) Do not add app-background and window buttons
|
|
- `view` - (boolean) The definition is a view. That means the app/view is not visible in launcher
|
|
- `formspec_func(app, mtos)` - Function, should return the app formspec (mandatory) During definition the "app" and the "mtos" are available
|
|
- `appwindow_formspec_func(launcher_app, app, mtos)`- Only custom launcher app: App background / Window decorations and buttons
|
|
- `receive_fields_func(app, mtos, sender, fields)` Function for input processing. The "app" and the "mtos" are available inside the call
|
|
- `allow_metadata_inventory_put(app, mtos, player, listname, index, stack)` - Optional: custom actions on item put
|
|
- `allow_metadata_inventory_take(app, mtos, player, listname, index, stack)` - Optional: custom actions on item take
|
|
- `allow_metadata_inventory_move(app, mtos, player, from_list, from_index, to_list, to_index, count)` - Optional: custom actions on item move
|
|
- `on_metadata_inventory_put(app, mtos, player, listname, index, stack)` - Optional: custom check on items put
|
|
- `on_metadata_inventory_take(app, mtos, player, listname, index, stack)` - Optional: custom check on items put
|
|
- `on_metadata_inventory_move(app, mtos, player, from_list, from_index, to_list, to_index, count)` - Optional: custom check on items put
|
|
- `on_timer(app, mtos, nil, elapsed) - Optional. The on-timer callback (no sender)
|
|
|
|
`laptop.register_view(internal_shortname, { definitiontable })` - add a new app or view
|
|
same as register_app, but the view flag is set. app_name and app_icon not necessary
|
|
|
|
### App Object
|
|
`local app = mtos:get_app(appname)` - Give the app object internal_shortname, connected to given mtos. Not necessary in formspec_func or receive_fields_func because given trough interface
|
|
- `app:back_app(fields, sender)` - Go back to previous app/view. Trough fields/sender additional data can be sent to the previous app trough receive_fields_func
|
|
- `app:exit_app()` - Delete call stack and return to launcher
|
|
- `app:get_timer()` - Get timer for this app (based on nodetimer)
|
|
|
|
|
|
## Themes
|
|
### Theme definition
|
|
`laptop.register_theme(name, definitiontable)` - add a new theme. All parameters optional, if missed, the default is used
|
|
The most colors are grouped by "prefixes". Each prefix means a specific content to be themed.
|
|
#### Theme suffixes
|
|
- background - A background texture
|
|
- button - A foreground texture, used on buttons
|
|
- bgcolor - Background RGB color, should be the same color as background texture
|
|
- textcolor - Foreground RGB color used for label text or button texts
|
|
|
|
#### Theme prefixes
|
|
- desktop - Main launcher
|
|
- `desktop_background` Desktop background image
|
|
- desktop_icon - The App icon in main launcher
|
|
- `desktop_icon_button` App button background in launcher
|
|
- desktop_icon_label The label under the app icon in main launcher (technically a button too)
|
|
- `desktop_icon_label_button` Background texture for icon label text
|
|
- `desktop_icon_label_textcolor` Icon label text color
|
|
|
|
- app - App decorations
|
|
- `app_background` Apps background image, adds titlebar
|
|
- titlebar - The titlebar on app decorations
|
|
- `titlebar_textcolor` Sets the color of text on app titlebar
|
|
- back - The back button on app decoration
|
|
- `back_button` Back Button image
|
|
- `back_textcolor` Back Button textclolor (for '<' character)
|
|
- exit - The exit button on app decoration
|
|
- `exit_button` Exit button image
|
|
- `exit_textcolor` Exit button textcolor (for 'X' character)
|
|
- `exit_character` Sets the character that shows up in the close box, X is default
|
|
|
|
- major - Highlighted Button
|
|
- `major_button` Major (highlighted) button image
|
|
- `major_textcolor` Major (highlighted) button text color
|
|
|
|
- minor - not highlighted button
|
|
- `minor_button` Minor button image
|
|
- `minor_textcolor` Minor button text color
|
|
|
|
- contrast - dark background in contrast for not themeable elements
|
|
- `contrast_background` dark background to place under white text elements that does not support textcolor
|
|
- `contrast_bgcolor` dark background as RGB
|
|
- `contrast_textcolor` some labels are placed on contrast background. This color is used to colorize them
|
|
|
|
- status_online - Used to show status information "online / green"
|
|
- `status_online_textcolor` - Sets "online" text color for peripherals
|
|
- status_disabled - Used to show status information "disabled / yellow"
|
|
- `status_disabled_textcolor` - Sets "disabled" text color for peripherals
|
|
- status_off - Used to show status information "off / red"
|
|
- `status_off_textcolor =` - Sets "offline" text color for peripherals
|
|
|
|
- table - Colorize the table-like output
|
|
- `table_bgcolor` - Table background color
|
|
- `table_textcolor` - Table text color
|
|
- table_highlight - Colorize the selection in tables
|
|
- `table_highlight_bgcolor` - Table highlighted background
|
|
- `table_highlight_textcolor` - Table highlighted textcolor
|
|
- muted - muted color
|
|
- `muted_textcolor` - Table textcolor muted
|
|
|
|
- monochrome - Optimized for monochrome output (old computers). Some elements will be colorized using this color
|
|
- `monochrome_textcolor` - default is nil. if set to RGB, colorization is applied on some textures (like tetris shapes)
|
|
|
|
- fallback - without prefix (obsolete)
|
|
- `textcolor` Default text color for buttons and labels. Each "prefix" can have own textcolor, like major_textcolor and minor_textcolor for major/minor buttons or labels
|
|
|
|
- Other settings / without prefix
|
|
- `taskbar_clock_position_and_size` Set where the clock is positioned and its size on the taskbar
|
|
- `node_color` Palette number to set if the node is paramtype2 = "colorfacedir" (inactive)
|
|
- `os_min_version` - minimum version to be used (CS-BOS, optional)
|
|
- `os_max_version` - maximum version to be used (CS-BOS, optional)
|
|
- `table_border` - draw tables border (true or false)
|
|
- `texture_replacements` - A table with texture replacements, defined as { ['orig_texture_name.png'] = 'themed_texture_name.png', }
|
|
|
|
### Theme methods
|
|
`function laptop.get_theme(theme_name)`
|
|
- `theme:get_button(area, prefix, code, text)` get a themed [prefix]_button in area 'x,y;w,h' with code and text
|
|
- `theme:get_image_button(area, prefix, code, image, text)` get a themed [prefix]_button in area 'x,y;w,h' with code an image and text. Text is colorized by [prefix]_textcolor or textcolor
|
|
- `theme:get_label(pos, text, color_prefix)` get a themed label text starting at pos 'x,y', colorize theme by color prefix (usually the button text colors)
|
|
- `theme:get_texture(image)` get replacement for texture image if set in theme or the image. Called internally from get_image_button()
|
|
- `theme:get_tableoptions(show_select_bar)` get themed tableoptions string before table[]. If show_select_bar is set to false, the highlight values are the same as non-highlight so no selection is visible
|
|
- `theme:get_bgcolor_box(area, prefix)` get plain box colorized by [prefix]_bgcolor or bgcolor
|
|
|
|
## Block devices / Data objects
|
|
`mtos.bdev = laptop.get_bdev_handler(mtos)`
|
|
|
|
### Low-Level methods
|
|
Can be used for non-data and/or system tasks. For usual data store please use the storage methods
|
|
- `bdev:get_ram_disk()` ram store - a table with all app-related storage partitions
|
|
- `bdev:get_hard_disk()` hdd store - a table with all app-related storage partitions, if hard disk capatibility exists
|
|
- `bdev:get_removable_disk()` removable data object (drive)
|
|
- `bdev:get_cloud_disk(storage_name)` - Get named cloud storage
|
|
- `bdev:sync()` - Write/store all opened and maybe changed data (cached)
|
|
- `bdev:sync_cloud()` - Write/store all opened and maybe changed data in cloud
|
|
|
|
### Storage methods
|
|
- `get_boot_disk()` - Check which device can be booted. possible return value is "hdd" or "removable"
|
|
- `get_app_storage(disk_type, storage_name)` - Get data storage table to be used in apps.
|
|
- disk_type can be 'ram', 'hdd', 'removable', 'cloud' or 'system'. System is eather hdd or removable storage depending on booted device
|
|
- store_name is usually the app name. 'os' is reserved for System related saves
|
|
|
|
### Low-level Removable data
|
|
`data = bdev:get_removable_disk()`
|
|
- `bdev.inv` - node inventory (the slot)
|
|
- `bdev.label` - Meda label. Item name by default
|
|
- `bdev.def` - Registered item definition (read-only)
|
|
- `bdev.stack` - The item stack
|
|
- `bdev.meta` - Stack metadata
|
|
- `bdev.os_format`- The format type: "none", "boot", "backup", "filesystem" (read-only)
|
|
- `bdev.rtype` - Removable type. "usb" or "floppy"
|
|
- `bdev.storage` - Data table used for app storage, if format is data compatible
|
|
- `bdev:reload(stack)` - Reload all data from node inventory. If stack is given, the stack will be inserted to slot
|
|
- `bdev:eject()` - Remove item from slot and drop them to the world nearly computer
|
|
- `bdev:format_disk(ftype, label)` - Format the disk. ftype can be "" or nil, "data" "backup" or "boot"
|
|
|
|
## Compatible Items
|
|
There is no own compatible items registrator. The item needs to match the item group to be usable with the laptops
|
|
- `laptop_removable_floppy = 1` - The item is a floppy
|
|
- `laptop_removable_usb = 1` - The item is usb storage disk
|