Methods of the workshop and the pulpit

What the window of the workshop takes from the platform and what it calls it with, the methods of the function ui and of the function of the pulpit canvas: the document of the pulpit, the surface for the window, pictures, looks, pieces.

Introduction

The document is a part of the contract Exchange with the kernel: the sources of the data of the workshop, the methods of the window program and the description of the pulpit. How it is shown to the person — The workshop. The refusal codes — Error codes.

1 The data of the workshop

The functions do not describe drawing: the workshop draws its views itself, and takes its data with ordinary requests to the functions (The workshop, section 8).

Table 1 — The data of the workshop

An action of the person is an ordinary command to the owner (process.run.start, process.event.fire, canvas.save, settings.set, module.install …); the list of commands is in the contract of the owner. At introduction a function names its surfaces in the field surfaces — this is needed to see the make-up of the platform; the kernel does not parse the meaning of these names.

2 The window

The window of the workshop is a Windows program; it connects to the function ui at the address 127.0.0.1 (the port and the session token come on the command line of the start, The workshop, section 2). How messages are passed and what the wrapper looks like — Exchange with the kernel, sections 2, 3. The id of a request of the window is window-<number>.

Table 2 — The window

The other core.* and function.handshake are closed to the window — method_not_allowed. A wrong token or a first message other than ui.window.hello — ui_window_unauthorized and the connection closed. The events of the kernel the function ui passes to the window as the notification event in the same event wrapper (Exchange with the kernel, section 7). Neither the function ui nor the window program sets a term of its own for an answer: both only pass the call on, and how long to wait the page decides (The make-up of the platform, 3.7.1). The page waits as long as the owner of the method needs and sets no term of its own: a term of the window would break off long work of the owner — checking a module, installing an environment. A call without an answer does not hang: it ends with the refusal function_lost when the owner disconnected or did not pass the health check, and ui_window_disconnected when the link of the window with the platform broke.

The face of a program is opened by a start (The workshop, 6.6). The name of the program is carried by the function ui:

• ui.face.open — { "process_id" } (a command): remember for the window the process whose face is to be shown, and publish ui.face.asked (Exchange with the kernel, section 7). The answer is { process_id }. An empty or missing name — invalid_request. Whether there is such a process and whether its program switches on, the function ui does not check: the owner of the process tells the window that. The command is called by the register verb program (Building, installing and maintenance, 5.2); of two requests in a row the window takes the last.

At its start the window asks ui.window.face and, having got a name, shows the face at once, before the process is read; then it opens the process and switches its program on with a command to the owner (process.program.on). An already open window learns of a request from the event ui.face.asked.

3 The pulpit

The owner of workspace.json is the function canvas. The document of the pulpit is ogas.workspace/3, the graph of the interface: containers and elements (File formats, section 7). The meaning of shared objects is the graph's: they are set by the nodes and variables of process.json (The program: graph and runs, section 16). An empty pulpit is allowed: objects are not laid out by themselves. A refusal for the form of the document is canvas_invalid, the message names the element or container and the field.

• canvas.get — { "process_id" }: the document ogas.workspace/3, laid out: each page has a sheet, what is on it has a place. Nothing changes on disk;
• canvas.save — { "process_id", "document" }: adds to the document — the name of the pulpit; the identifier of a container and how it shows its content; the identifier and container of an element; the size and place of what stands on a sheet and is written without them — checks its form and writes it. A place written in the document the owner does not change and does not move to the step of the sheet: what does not lie on its sheet whole or is smaller than the smallest size of its kind is refused. An object that is not in the graph or does not fit the element is not a refusal — the snapshot will mark it. The generation of the pulpit is kept by the owner: a written document gets the next generation after the one written on disk (the first is 1), the field generation of the sent document is not counted. The answer is { process_id, generation }. A pulpit on disk the function cannot read or that is of another format is not overwritten: the refusal document_invalid;
• canvas.ensure — { "process_id" }: make an empty pulpit — one window without a name and without elements; it gets a sheet with the first thing put into it — if there is no pulpit (a command). Having written the pulpit, canvas.save and canvas.ensure publish canvas.changed (Exchange with the kernel, section 7). The function of the pulpit listens to process.changed: if the graph is written with renamed_objects, and the pulpit still names objects by their former ids, it rewrites the bindings of elements, containers and the pulpit itself to the new ids by itself and publishes canvas.changed; a failure — function.work_failed (File formats, section 15);
• canvas.snapshot — { "process_id" }: a surface for the window, not the document; makes no file. The answer is { surface_id: "canvas.editor", revision, process_id, bindings, open_why, groups, elements, objects, grid, scale_min, theme, images, looks }:
• revision — the generation of the document of the pulpit; without a document — an empty pulpit;
• bindings — the bindings of the pulpit itself (open) with the present ids; open_why — object_gone or object_unfit, when the variable of the open window is gone or is not a text one, otherwise null;
• a container — id, name or null, parent or null, holds, bindings with the present ids, screen or null, box — the frame inside a page { place, size } counted around what lies in it, or null, look or null, look_why, layer or null, collapsed, placed — whether it was not taken off the sheet itself, out — whether it does not stand on the sheet — taken off itself or lying in what was (then box is null), why — object_gone or object_unfit for a binding to a variable that is not there or is of the wrong type (such a container is shown as without the binding), image_gone, when the underlay picture is not in the folder, otherwise null;
• an element — element_id, kind, family, group — the container, bindings with the present ids of the objects (the binding opens names a container of the pulpit and is not marked), label or null, screen — { place, size } for what stands on a sheet, otherwise null, placed and out — as for a container: an element that does not stand on the sheet is not drawn, layer or null, look or null, look_why — why the element is drawn not with the look it named: look_gone, look_unfit or look_broken (this does not hinder the work of the element), parameters — those set by the person and the defaults of the kind, invalid and why: object_gone — the object is not in the graph, object_unfit — the object does not fit the element, image_gone — the picture the element names is not in the folder, otherwise null. A decoration has family — decoration, and its bindings are empty;
• a reflection — id, objects — the rows with the present ids of the objects, source or null, group or null, layer or null, gone — those of the rows whose objects are not in the graph;
• an object — what the graph gave (process.objects), and fits — the kinds of elements the object is put on the pulpit as, in the order of the set; the first is the one the object gets when the person named no kind;
• grid — { step, margin, sheet, head }: the step of the sheet and the margin from the edge in units of the sheet, the size of the sheet for a page without one and the height of the head of a frame; scale_min — the limit of making the sheet smaller on the screen in percent. These are settings of the function of the pulpit for the process (Settings, section 8): the window keeps no numbers of the sheet of its own;
• theme — all keys of the theme with values: those set by the pulpit, the rest from the settings;
• images — the pictures of the folder of the pulpit: [ { name, media_type, bytes, stamp } ], stamp changes when the file is written anew;
• looks — the looks that can be given to elements: [ { look_id, kind, name, size, own, sound, why, stamp } ] — first the process's own looks (own: true; a look that does not pass the check has sound: false and the cause in words in why), then the built-in ones, whose name is null, and the name lies in the dictionary of the element;
• canvas.preview — { "process_id", "document" } and an optional process (a query): what the sent document will become when written, without writing. With process — the graph the person is editing — the pulpit is checked against it, not against the written graph: an object made a minute ago fits, a removed one is marked. The answer is { document, surface }: the document, added to as at canvas.save, and its surface, as at canvas.snapshot. Refusals — as at canvas.save. The window asks so after each edit of the pulpit and shows the answer: it keeps no rules of its own about the pulpit — what goes where, what fits, what is not allowed;
• canvas.elements — {} (a query): the set of elements — { elements: [ { kind, family, bindings, parameters, one_of, size, min_size } ], theme, image_types } in the order of the set:
• one_of — the bindings of which an element names at least one, each optional by itself: a button presses an event, opens a container, or both;
• states — the states for which a look may have a picture, the first is required; an empty list — the element has no looks; quantity — whether the element shows a quantity a look can draw (File formats, 7.2);
• a binding — name, objects — the kinds of objects, types — the types of a variable (empty — any), many, optional, with — beside which binding and which object it is allowed;
• a parameter — name, how (number | choice | list | text | image — the name of a picture of the pulpit), choices, default, optional, range — the smallest and largest integer for a number, or null;
• theme — the keys of the theme: [ { key, type, choices, min, max } ], type — color, string or integer; the names of the keys are the texts of settings setting.canvas.theme_<key>.title; image_types — the endings of file names the pulpit takes as pictures;
• names and hints are in the dictionaries of the elements: canvas.element.<kind>.name, .description, .binding.<name>.title and .help, .param.<name>.title and .help, .param.<name>.choice.<value>.
• canvas.images — { "process_id" } (a query): the pictures of the folder of the pulpit — { images: [ { name, media_type, bytes, stamp } ] } by name; no folder — the list is empty;
• canvas.image — { "process_id", "name" } (a query): one picture for showing — { name, media_type, bytes, stamp, data }, data is the content of the file in base64. Refusals: canvas_image_invalid — the name is not the name of a picture, the file is larger than the setting canvas.image_max_bytes or does not begin the way a file of its kind does; canvas_image_not_found — there is no such file;
• canvas.image.put — { "process_id", "name", "data" } (a command): put a picture into the folder of the pulpit under this name; data is the content of the file in base64, in one message. The name, the kind by the ending of the name, the beginning of the file and the size are checked (File formats, 7.2); a refusal — canvas_image_invalid. A picture with the same name is replaced. The answer is { name, media_type, bytes, stamp }; canvas.images.changed is published;
• canvas.image.remove — { "process_id", "name" } (a command): remove a picture from the folder. Whether it is named on the pulpit the function does not check: this is an edit the person has not written yet, and the window knows of it — it does not remove a picture while it stands on the sheet. The answer is { name }; canvas.images.changed is published;
• canvas.look — { "process_id", "look_id", "kind" } (a query): a look for showing — { look_id, kind, own, stamp, look, images }: look — the document ogas.look/1, images — the pictures it names { "<file>": { media_type, data } } in base64. kind — the kind of element that asks: an own look of the process with this name is given as it is, a built-in one only as a look of this element. Refusals: canvas_look_not_found, canvas_look_invalid;
• canvas.look.put — { "process_id", "files": [ { name, data } ] } (a command): take an own look whole — look.json and the pictures it names in one message, data in base64; a painted look (paint) — one look.json. The name of the look is taken from the look_id of the document. The look is checked before writing (File formats, 7.2): the document, the pictures, extra files, the whole size; a refusal — canvas_look_invalid with the cause in the message. A look with the same name is replaced whole. The answer is { look_id, kind, files, bytes }; canvas.images.changed is published;
• canvas.look.remove — { "process_id", "look_id" } (a command): remove an own look of the process; whether an element is drawn with it, the window knows, and it does not remove such a look. The answer is { look_id }; canvas.images.changed is published;
• canvas.files.export — { "process_id", "target" } (a command): copy the folder pulpit/ of the process into the folder target inside the data folder — so the pack of a process gets the pictures and looks of the pulpit (File formats, 10.1). Links and half-written files are not copied; a folder without files is not made. The answer is { files, bytes }. A path outside the data folder — path_outside_root;
• canvas.files.import — { "process_id", "source" } (a command): make the files of the folder source the files of the pulpit of this process; with no source nothing is done. The answer is { files, bytes }; when files came, canvas.images.changed is published.
• canvas.piece.save — { "process_id", "group_id" } and an optional name (a command): save a container of the written pulpit with everything in it as a piece of interface in the library (File formats, 7.4). What is taken off links and looks — there too. The name of the piece is given by the function from the title; a taken name is not overwritten but gets a number. The answer is { piece_id, name }. No such container in the pulpit — canvas_invalid;
• canvas.piece.list — {} (a query): the pieces of the library by name — { pieces: [ { piece_id, name, holders, elements } ] }, holders and elements — how many containers and elements it holds. A file of another format is not in the list;
• canvas.piece.get — { "piece_id" } (a query): the whole piece, the document ogas.piece/1. The window puts it, as an edit of the pulpit written by canvas.save. No such piece — canvas_piece_not_found;
• canvas.piece.import — { "path" } (a command): take into the library a piece brought from outside — the document ogas.piece/1 at a path from the data folder, for example downloaded from a showcase into downloads/. Its containers and elements are checked by the rules of the pulpit, as if they were a pulpit; the name of the piece is given by the function from its title, a taken one gets a number. The answer is { piece_id, name }. A document of another format or one breaking the rules of the pulpit — canvas_invalid, no document — document_not_found. A piece is data, not code: no question of trust is asked.
• canvas.piece.delete — { "piece_id" } (a command): remove a piece from the library; the programs it was put into keep what was put. The answer is { piece_id, deleted: true }. No such piece — canvas_piece_not_found.