How Hipe Works

There are two sides to a Hipe session. On the server side, you have the Hipe display server (hiped); a single process which starts when the user's session does.

On the client side, you have applications like word processors, web browsers and calculator utilities. They are called clients because they use the services of the Hipe display server. The Hipe server provides each client application with its own frame. Each client app is allowed to display graphical user content only within its own frame.

One Hipe display server instance can have multiple client applications using it at any one time.

A framing manager is a special kind of client application whose job is to manage the placement of other client applications' frames on the screen. It is analogous to the various 'window managers' used in X windowing environments. Framing managers can be nested; for example, a particular suite of related applications can be provided within its own desktop environment. Alternatively, instances of certain remote applications can be sandboxed within a common environment.

Client applications communicate with Hipe by exchanging instructions over a local socket connection. For example, a client might send an instruction to manipulate the contents of a particular tag element, or may receive an event instruction in response to the user clicking a particular tag element.

Connecting to hiped

To connect to the Hipe display server, a client application needs two pieces of information. The location of the Hipe display server's open socket (nominally placed in a standard/reproducible default location unique to each user), and a host key which is a character string that applications use to prove they have permission to be granted a frame at a specific level.

Hipe does not dictate a single mechanism for framing managers to share host keys with client applications (although a default lookup policy for client applications is built into the API), but for top-level applications (which cover the whole screen and are not governed by framing managers), hiped maintains a key-file in a standard location which is updated every time a client claims a top-level key. The key-file can be placed in a different location with restricted permissions to satisfy case requirements where it is not appropriate to allow applications to create frames at the top level. In this case, only the framing manager bundled with the system distribution would be able to access the key-file for creating a single top-level frame which would then contain all the frames of client applications.

Implementation stack

The Hipe display server is implemented as a Qt/Webkit application. Although Hipe (and Hipe applications) doesn't use or depend on X or any other display manager directly, Webkit's implementation does depend on X (or other Qt-compatible display server). This means that at this stage, Hipe runs on top of X.

You can think of Hipe as a 'high level' display server. It does stuff like rendering, layout and frame management, but it doesn't interact with hardware or device drivers directly. For the latter, we use a bare-minimal X session as a 'low-level' base environment.

Hipe can run on top of a bare X session (without requiring any X-based window management or desktop environment), in which case a framing manager can create a top-level frame and manage all other client applications from there. In this form, Hipe has the appearance and functionality of a standalone display environment.

Alternatively, hiped can be started within an existing X-based desktop environment. In this case, client applications can be started as top-level Hipe applications, and they will be managed by the X window manager of the host environment. In this mode, we say that Hipe is running in a rootless mode, since it doesn't take over the whole desktop. Applications will start maximised, because Hipe doesn't allow applications to dictate their own frame sizes.

There are other alternatives to X, such as the leaner Wayland, which may be considered as a preferred base for Hipe in the future. For now, X is used as a base display server for Hipe, since it is stable and has good hardware support.

Installing Hipe

Installing Hipe is easy once you have the required dependencies. However, exactly how you configure Hipe to run on your target system will differ depending on your requirements. (For example, if you are building an embedded device that uses Hipe for its entire user interface, you would configure Hipe to run your entire desktop environment. If you are installing Hipe on an Ubuntu desktop to develop software on, you might prefer to run Hipe within your existing desktop environment.)

The steps are as follows:

1. Install the dependencies.
2. Build and install the display server program, known as hiped.
3. Configure hiped to start automatically.
4. Install the API. This is not required for running applications built for Hipe, but is necessary for developing such applications. You will need the API to build the test applications. These will allow you to make sure that everything is working correctly.
5. Build and install the test applications if desired.

These instructions assume you have downloaded the Hipe distribution into some directory called hipe. You will not need superuser privileges except for certain steps where stated.

A $ prompt in these instructions means you type the command as a normal user, while a # means you type the command with superuser privileges (or by prefixing it with sudo if your OS distribution allows it). Please don't literally type those prompt characters.

---

Install the dependencies

We assume you have a working X installation. You will also need the development files for Qt with either QtWebkit or hipecore (a leaner, modified WebKit engine purpose-built for Hipe, and now the recommended backend for new installations — see the Status page). Qt must be built with STL support as Hipe requires it. On a Debian-based system (e.g. Ubuntu), you can try installing the QtWebKit dependency with the following command:

$ sudo apt install libqt5webkit5-dev

Note: QtWebKit was dropped from some distributions' package repositories some years ago, so this package may not be available depending on your distribution and release version — for example, it's no longer packaged in Debian 13 (Trixie) or its derivatives. If this command fails, see "Building against hipecore instead" below.

Building against hipecore instead

If libqt5webkit5-dev isn't available for your system, or you'd simply prefer the leaner, Hipe-optimised engine, you can build and install hipecore from source instead — it provides the same Qt5WebKit/Qt5WebKitWidgets libraries that hiped links against, so no further changes are needed to the instructions below once it's installed.

hipecore is distributed as its own source archive, alongside Hipe's. Unpack it, then from inside its directory:

$ mkdir build && cd build
$ cmake -G Ninja -DPORT=Qt -DCMAKE_BUILD_TYPE=Release ..
$ ninja
# ninja install

Building hipecore has its own set of dependencies (CMake, Ninja, a C++17-capable compiler, Qt5 development packages, and a handful of image/XML/multimedia libraries), which vary somewhat by distribution — if the cmake step fails, its output will generally tell you which package is missing. See the README.md in the hipecore archive for its build instructions and list of dependencies.

The display server itself needs the Qt 5 development files, including the Qt SVG and Qt OpenGL modules. On a Debian-based system:

$ sudo apt install qtbase5-dev libqt5svg5-dev libqt5opengl5-dev

If a module is missing, qmake stops in the next section with a message such as Unknown module(s) in QT: svg. Hipe requires Qt version 5. On a system that also has another version of Qt installed, qmake may belong to that version; in that case try qmake -qt=5 or qmake-qt5 in its place.

If in doubt, the following command will tell you which version of Qt is set up as the current default version:

$ qmake --version

You may also need to install other Qt development packages if you don't already have them. If the server refuses to compile in the following step, it means you're missing one or more Qt components.

Build hiped

hiped is the display server itself. If you have Qt Creator (a graphical IDE developed by the Qt people), you can open the hiped project file and build hiped in the graphical environment.

The following instructions don't require Qt Creator, and assume you will be building it from the terminal, the old-fashioned way.

First, enter the server subdirectory of the hipe distribution.

$ cd hipe/server/

Now use qmake to configure and build the Makefile for your system:

$ qmake -makefile ./src/hiped.pro

Then run the following command to build the hiped executable from source:

$ make

An executable file, hiped should now be present in the current directory. The Hipe display server can now be run directly using the hiped executable if desired, however it is often more convenient to install it in a permanent location.

Install the compiled display server

Running make will produce the hiped executable but will not install it. The following describes a typical installation. In some cases your requirements may differ, and it is quite OK to modify your deployment accordingly. (Experiment as needed!)

First, it is recommended to copy the hiped executable file into your system's /usr/local/bin/ directory. It is recommended to check the file permissions to ensure that all users have permission to execute hiped.

Now you will need to configure your system to run hiped automatically so that applications that depend on Hipe can find the running display server.

Configure hiped

Running on an existing desktop environment

Unless you're preparing hiped to run in its own standalone display environment, hiped needs to be started within a graphical environment compatible with Qt applications (such as X11 or Wayland).

Configure the following command to run on user login, within the user's graphical desktop environment:

hiped &

For example, the command could be added to the appropriate session startup script (e.g. Xsession or .xprofile). The exact script to modify will differ depending on your OS distribution, or your OS distro may provide another way to configure applications to run on startup.

Now the Hipe display server is available from the moment the user logs in. The hiped background process is lightweight and consumes only minimal CPU and RAM resources until it is actually required.

Deploying in an embedded environment

An easy way to deploy hiped is to start up a bare-bones X11 session (without a window manager or desktop environment), and then start hiped with the --fill option. Although other display backends are provided by Qt, running Hipe on X11 tends to outperform them due to driver availability issues on various devices.

The --fill option causes the first top-level application to take over the entire screen.

$ hiped --fill &

The server/start_hipe_standalone_x11 script (which must be run from a virtual console TTY in Linux) gives a rudimentary example of how to start Hipe as a standalone display environment by piggybacking off a bare-bones X11 session.

Note: If your system allows the user to run more than one application, then your top-level application should carry out framing management for other applications in order to provide a complete desktop shell. The quadrant sample program provides a very rudimentary example of how to do this. (You should also set up the appropriate environment variables to ensure applications run within your shell instead of attempting to spawn top-level frames.)

You can also try running

$ hiped --help

as well as browsing the Running hiped page for various other configuration options. In addition to the options listed, hiped supports standard Qt arguments for running on different graphics backends. You may be able to install additional backends as part of your Qt installation. Refer to the official Qt documentation for details. (Hipe has no affiliation with the Qt project or Qt developers.)

---

Compile and install the client API

So you've installed and configured the Hipe display server. Well, you won't be able to do anything interesting with Hipe without some Hipe client apps to run on it, so read on and install the API.

Leave the server directory and enter the api directory instead.

$ cd ..
$ cd api/

Build the Hipe API library, libhipe, by running make.

$ make

Now it's time to install the libhipe library so that hipe applications can be compiled and linked to it. To see what will happen, have a quick look at the Makefile, under the install: heading.

$ cat Makefile

By default, library files will be installed into your /usr/local/lib/ and /usr/local/include/ directories. This is sensible for most GNU/Linux distributions. For certain other system distributions or installation requirements, you may need to edit the Makefile to change these paths.

Now install libhipe with superuser privileges:

# make install

And now you can build the test applications.

$ make testing

The test applications are now available inside the api/test/ subdirectory.

Try it

Start the display server if it isn't already running. From your desktop environment, run it in the background from the server directory:

$ cd ../server/
$ ./hiped &

Nothing appears yet: hiped shows nothing until an application connects. Now run one of the test applications from the same terminal:

$ ../api/test/hipe-clock

A window with a digital clock should open. The application found the display server by itself, through the socket and key files that hiped creates (see Running hiped). Other test applications worth trying are hipe-calc (a calculator), hipe-slider (range sliders) and hipe-canvas (a small paint program). Their source code, in api/test/, is the quickest way to see how a Hipe application is written, and may be copied freely into your own.

---

Running hiped

hiped is the utility that provides the Hipe display server itself. To be able to run Hipe applications, hiped needs to be running, and the client applications need to be able to locate and access the appropriate files generated by the hiped instance.

hiped is implemented using Qt so needs to be run within an appropriate environment.

• One way to run it is within an existing X desktop environment. Client applications can then be allowed to create top-level frames within Hipe, which means they will appear as ordinary application windows within the desktop environment.
• Another way to run the hipe server is within its own dedicated X environment. Hipe doesn't require an X window manager so the X environment can be kept almost completely empty apart from a Hipe framing manager/ desktop environment that manages the whole screen. The GNU/Linux environment usually reserves two TTYs for graphical purposes (usually accessible using Ctrl+Alt+F7 and Ctrl+Alt+F8). Assuming you already have an X desktop environment running in the first one, the following command would start hiped in the second one:

  xinit hiped -- :1

  At this point the user sees a blank screen, because no framing manager or client applications are running. Hipe is ready to accommodate them, but the actual desktop environment hasn't been launched yet.
• Another way to run hiped is by using the LinuxFb platform provided by the Qt runtime environment. When run in this mode, X is not required, but hardware acceleration is not available. This mode is suitable for embedded systems. The Linux framebuffer is not a protected medium. Care must therefore be taken to set the system to a blank TTY before running hiped in this mode, or the TTY running behind hiped may receive the same keystrokes as the user's Hipe session. For more information about running a hiped, or any other Qt application, in such a mode, refer to the documentation on Qt's website.

Socket file, and host key

hiped generates the following files when running:

• A socket file, hipe.socket, which client applications connect to in order to utilise the Hipe display server.
• A hostkey file, hipe.hostkey. This file contains a unique key string that authorises a client application to create a top-level frame managing the entire screen. Each key can only be claimed once so the file is updated whenever a key is claimed. Multiple top-level frames can be created in which case the least recently created top-level frame will be covered up and hidden from view by more newly-created top-level clients. When hiped is run within an existing desktop environment, top-level frames are created as ordinary windows within the desktop environment.

By default, hiped creates the socket and hostkey files in one of the following directories (shown in order of precedence):

1. If hiped is run by the root user, files are placed in /run/.
2. If the environment variable XDG_RUNTIME_DIR has been set, this path is used. This is usually a subdirectory of /run/user/ which is uniquely assigned to each user of the operating system.
3. As a last resort, hiped places the files in /tmp/.

The file placement scheme is formalised in this way to ensure that Hipe client applications will be able to locate and connect to the Hipe display server on most systems and create top-level frames without needing additional configuration. However, in many cases you will want to configure the file placement so that only trusted applications can create top-level frames, or to place the socket in a different location. The following command line parameters are available for this purpose:

hiped [--socket ⟨file path⟩] [--keyfile ⟨file path⟩]

With the above parameters, you can specify an alternative path (including the desired filename) for either or both files.

Having specified non-default locations, you now need to set up a runtime environment so that client applications can find the required files. Set the following environment variables to the same file paths:

• HIPE_SOCKET
• HIPE_KEYFILE

If set, Hipe client applications will look at these environment variables instead of looking in the default directory (as determined by the order of precedence above).

Hipe client applications do not have to be started from the same TTY as hiped. As long as the client application can locate the hiped runtime files as described above, the application will be granted a frame (window) in Hipe.

---

When you provide your own framing manager, you won't normally want to allow ordinary client applications to create their own top-level frames. Instead of accessing host-keys for creating top-level frames, the user's client applications will need to access host-keys for creating frames that are integrated within your desktop environment. In this case you have two options, and an additional environment variable you can utilise:

1. Your framing manager can create and maintain its own hostkey file, updating it each time a new application creates a frame in the desktop environment. In this case, you would set up the environment variable HIPE_KEYFILE to point to the framing manager's hostkey file, rather than hiped's top-level hostkey file, once the framing manager has started running. You would also place the top-level hostkey file in a location that is inaccessible to ordinary applications.
2. You can create a desktop environment that is responsible for launching applications itself. In this case, there is no need for a hostkey file. Instead, your desktop environment can set the HIPE_HOSTKEY environment variable uniquely for each application it spawns. This approach affords greater control to the desktop environment, and allows particular applications to be framed differently as special cases. However, because each hostkey expires as soon as it is claimed, this approach does not enable multiple client applications to be run directly from a TTY.

The demonstration framing manager, hipe-quadrant, doesn't do either of these things. Instead, it simply displays the newest hostkey on the screen and TTY, and the user then has to feed these into the test applications by hand. This manual approach demonstrates the concept, but would be far less than ideal in a real-world computing environment.

Other hiped command line options

The following invocation will list available command line options to your standard output:

hiped --help

The --fill option causes all top-level hipe clients to attempt to fill the entire screen in an environment where no window manager is running. This is particularly useful for embedded applications.

The --css option allows you to specify one or more CSS files which will be read when hiped starts up. This allows you to specify global default style rules which will be applied to all client applications running within this session. Multiple CSS files should be separated by colons : and use full path rather than the ~ token (which might not be correctly expanded by the shell when multiple CSS files are specified).
When a client application is launched, the first CSS stylesheet (index 1) is used by default, or the environment variable HIPE_THEME may be set to an integer value to make the client use a different stylesheet. HIPE_THEME should be set to the index number (counting from 1) of the stylesheet to be used, or 0 if no default stylesheet should be applied to the client session.

The Hipe API

To write a graphical program for Hipe, you'll need to include the Hipe API in your program. The Hipe API is designed to be used with C and C++ programs. The Hipe API is designed to be compact and general rather than user-friendly. The idea is that if user-friendliness or a particular GUI-development approach is required in future, it will be easy to build the necessary GUI toolkit on top of the Hipe API in future.

You can modify and include the Hipe API freely in your code even if you write proprietary software, subject to the license conditions.

Including libhipe

How to include the Hipe API in your C/C++ program

Assuming the Hipe API is correctly installed on your system, inclusion is simple. Use this compiler directive in your code:

#include <hipe.h>

When building your application, pass the -lhipe argument to your compiler/linker, so that the static library is linked into your program.

libhipe functions

Functions for creating and destroying a Hipe frame

Each application is granted a single frame when it connects to Hipe. A frame is a rectangular window on the screen through which that application is able to interact with the user. Applications are not normally allowed to create multiple frames, although they can create their own sub-frames for embedding other applications inside.

hipe_open_session()

This function connects to the Hipe display server and requests a frame.

hipe_session hipe_open_session(const char* host_key, const char* socket_path,
                               const char* key_path, const char* client_name)

Returns a value of type hipe_session on success. The return value is a session handle which is required by other hipe functions. On failure, the function returns 0, and an error message is printed to stderr.

• host_key (optional) is a unique key-string that may be supplied by a particular Hipe environment (such as a framing manager). In most cases, you should pass 0 (a null value, not the string "0") and let libhipe obtain the key automatically from environment variables and hostkey files.
• socket_path (optional) is the location of the Hipe display server socket file. In most cases you should pass 0 and let libhipe deduce the socket path automatically from environment variables and fallback paths.
• key_path (optional) is the location of a file containing a valid host-key for connection to a Hipe environment. In most cases you should pass 0 and let libhipe deduce this information automatically from environment variables and fallback paths.
• client_name is a short name that identifies the application process. It is quite reasonable to use argv[0] here. This short name also serves as a temporary title placeholder until you set the frame title properly.

hipe_close_session()

This function disconnects from the Hipe server and closes the session. The application's frame is destroyed and server resources associated with it are freed.

short hipe_close_session(hipe_session session)

Returns 0 on success.

• session is the session handle that was obtained when hipe_open_session() was called. After calling hipe_close_session(), the session handle is no longer valid and should not be used again.

Functions for dealing with Hipe instruction structures

libhipe uses data structures of type hipe_instruction for sending and receiving instructions from the display server. The functions for managing these variables all start with the prefix hipe_instruction_.

hipe_instruction_init()

Initialises a hipe_instruction instance by making its internal pointers null, making it safe for use in Hipe API functions.

void hipe_instruction_init(hipe_instruction* obj)

Must be called on any new hipe_instruction instance (excluding shallow copies of an existing instance).

Must also be called on a hipe_instruction object whose values have been populated manually by the user (e.g. by assigning as arguments string pointers that are not owned by the hipe_instruction object itself) and is now going to be re-used by a Hipe API function.

hipe_instruction_clear()

Frees memory allocated within the instruction, and leaves the hipe_instruction structure in a clean state ready for reuse.

void hipe_instruction_clear(hipe_instruction* obj)

Do not use this function to clear a hipe_instruction for which you have allocated values yourself. Instead, de-allocate the argument strings in a way consistent with how you allocated them, then call hipe_instruction_init() to re-initialise the values into a clean state.

hipe_instruction_copy()

Deeply copies values from one hipe_instruction instance to another, allocating memory for storage of values in the destination instance.

void hipe_instruction_copy(hipe_instruction* dest, hipe_instruction* src);

• dest is the hipe_instruction instance into which values will be be copied. dest should be in a clean state, as hipe_instruction_copy() does not do any initialisation or de-allocation of any existing data in dest.
• src is the hipe_instruction instance values are to be copied from.

When done with the instruction values in dest, you should free the memory associated with its internal variables using hipe_instruction_clear().

hipe_instruction_alloc()

Allocates memory for each argument of an instruction, according to the lengths already set in its arg_length[] values. Use it when building an instruction by hand whose arguments you will then fill in.

void hipe_instruction_alloc(hipe_instruction* obj)

Arguments allocated in this way should later be freed with hipe_instruction_clear().

hipe_instruction_move()

Moves the contents of one hipe_instruction instance into another without copying the arguments: the memory belonging to src is handed over to dest, and src is left re-initialised.

void hipe_instruction_move(hipe_instruction* dest, hipe_instruction* src);

As with hipe_instruction_copy(), dest should be in a clean state beforehand. The memory now in dest should later be freed in the way that suits how src was filled: with hipe_instruction_clear() if libhipe allocated it.

Functions for sending and receiving Hipe instructions

All interaction with the Hipe display server is done by sending and receiving Hipe instructions.

hipe_next_instruction()

Gets the next instruction from the display server, with an optional blocking wait.

short hipe_next_instruction(hipe_session session, hipe_instruction* instruction_ret,
                            short blocking)

Returns 1 if an instruction has been received, 0 if no instruction is available at the present moment and blocking was not requested, or -1 if disconnection from the server has occurred.

• session is the session handle that was obtained when hipe_open_session() was called.
• The received instruction is copied into *instruction_ret. The passed instruction variable must have been correctly initialised at the time it was created (using hipe_instruction_init()) but does not need to have been cleared before calling this function. It will be cleared automatically for your convenience, then repopulated with the next received instruction (if available).

Always check for a return value of -1 (or an instruction_ret->opcode of HIPE_OP_SERVER_DENIED) in your event loop, and exit (or otherwise stop calling hipe_next_instruction()) when it occurs. Once a session is disconnected, a blocking call can no longer block on anything, so an application that keeps calling hipe_next_instruction() in a tight loop without checking for disconnection will spin continuously instead of exiting cleanly when the display server goes away.

hipe_await_instruction()

A variation of the hipe_next_instruction function that waits for a specific type of instruction. There is a blocking wait until an instruction with the specified opcode arrives. When this happens, that instruction will jump the queue and be returned first.

short hipe_await_instruction(hipe_session session, hipe_instruction* instruction_ret,
                             short opcode)

Returns 1 if an instruction of type opcode has been received or -1 if disconnection from the server has occurred.

• session is the session handle that was obtained when hipe_open_session() was called.
• The received instruction is copied into *instruction_ret. instruction_ret must have been correctly initialised but does not need to have been cleared before calling this function. It will be cleared automatically for your convenience, then repopulated with the next received instruction.
• opcode is the instruction code to wait for.

Instructions that have already been received and are waiting in the queue are checked first, oldest first, so a reply that arrived while you were awaiting something else is still found. Any other instructions that arrive during the wait are added to the queue, to be retrieved later with hipe_next_instruction().

This function should only be used when you have sent the server a request that is guaranteed a response. Otherwise your application will hang waiting for an instruction that never arrives. That includes the case where the response has already been taken out of the queue by a call to hipe_next_instruction(): once retrieved, it is no longer there to be found.

hipe_session_fd()

Returns the file descriptor of the session's connection to the display server, so that an application can wait for Hipe instructions and its own file descriptors (pipes, FIFOs, sockets) at the same time, using poll(), select() or epoll, instead of checking each one on a timer.

int hipe_session_fd(hipe_session session)

Returns the file descriptor, or -1 if there is no connection to the display server.

• session is the session handle that was obtained when hipe_open_session() was called.

Only wait on this file descriptor for readability. Never read from or write to it directly: use hipe_next_instruction() and the send functions.

Important: libhipe keeps a queue of instructions it has already received. A single read can take in several instructions, and hipe_await_instruction() queues every instruction that isn't the one it's waiting for. Queued instructions are no longer waiting in the connection, so they won't wake poll(). Always empty the queue with non-blocking calls to hipe_next_instruction() before waiting:

for(;;) {
    while(hipe_next_instruction(session, &instruction, 0) > 0)
        handle(&instruction);
    poll(fds, nfds, -1);  /* fds includes hipe_session_fd(session) */
    /* ...handle your own file descriptors... */
}

A readable file descriptor doesn't guarantee that a complete instruction has arrived, so hipe_next_instruction() may still return 0. In that case, just wait again.

hipe_queued_instructions()

Returns the number of instructions that libhipe has received and queued, but that haven't yet been retrieved with hipe_next_instruction().

int hipe_queued_instructions(hipe_session session)

• session is the session handle that was obtained when hipe_open_session() was called.

This function doesn't read from the connection, so it doesn't count data the server has sent that hasn't been read yet. It's mainly useful for checking that the queue is empty before waiting on hipe_session_fd(). Like hipe_next_instruction(), it first sends any instructions waiting in the send buffer (see hipe_set_buffered()).

hipe_set_buffered()

Turns send buffering on or off for a session. Buffering is off by default, and each instruction is transmitted as soon as it is sent. With buffering on, sent instructions are collected and transmitted together, which is much more efficient for an application that sends many instructions at once (for example, building a large document or table). The order of instructions is always preserved.

void hipe_set_buffered(hipe_session session, int buffered)

• session is the session handle that was obtained when hipe_open_session() was called.
• buffered is non-zero to turn buffering on, or 0 to turn it off (which also transmits anything waiting).

Buffered instructions are transmitted when the buffer fills up (at 64 KiB), when the application waits or checks for instructions from the display server (with hipe_next_instruction(), hipe_await_instruction() or hipe_queued_instructions()), when hipe_flush() is called, when buffering is turned off, and when the session is closed. So a request is always transmitted before the application waits for its reply, and an application that drains hipe_next_instruction() before waiting on hipe_session_fd() (as described above) never needs to flush.

An application that sends instructions and then waits for something else without calling any of those functions (a timer, or one of its own file descriptors) must call hipe_flush() first. Otherwise its last instructions stay in the buffer, and the screen isn't updated, until it next does.

hipe_flush()

Transmits any instructions waiting in the session's send buffer.

int hipe_flush(hipe_session session)

Returns 0 on success, or -1 if there is no connection to the display server (or the connection has failed). It does nothing if buffering is off or nothing is waiting.

• session is the session handle that was obtained when hipe_open_session() was called.

hipe_send_instruction()

Transmits an instruction to the display server.

int hipe_send_instruction(hipe_session session, hipe_instruction instruction)

Returns 0 on success or -1 if there is no connection to the display server (or the connection has failed). With send buffering on (see hipe_set_buffered()), the instruction may be held in the buffer and transmitted later.

• session is the session handle that was obtained when hipe_open_session() was called.
• instruction is the Hipe instruction to transmit to the display server.

hipe_send()

A convenience function for transmitting a simple instruction to the display server without having to create a hipe_instruction instance first.

int hipe_send(hipe_session session, char opcode, uint64_t requestor, hipe_loc location,
              int n_args[, const char* arg, ...])

This function calls hipe_send_instruction internally and returns the return value from that call.

• session is the session handle that was obtained when hipe_open_session() was called.
• opcode, requestor, location and arg, ... are parts of the Hipe instruction to transmit. The strings arg[] need to be null-terminated, and their lengths are determined automatically. This convenience function should only be used when the arguments are simple text strings (due to the null-termination requirement).
• nargs is the number of arguments specified in the function call. Zero or more arguments may be specified at the end of the argument list.
• If an argument is explicitly specified but not used at a particular position, pass 0 (a null pointer) instead of a blank string.

hipe_newest_location()

Retrieves the location value of the most recently created tag.

hipe_loc hipe_newest_location()

Returns the location value that was assigned to the most recently created tag. This function is more efficient than sending instructions to the server to obtain location details.

C++ extensions for Hipe

While Hipe is primarily intended as a library for C, Hipe comes with an additional C++ header intended for C++ developers who prefer to deal with Hipe sessions and locations as C++ objects.

You still need to include and use the normal Hipe API for many tasks, but the C++ header adds a convenient alternative interface for dealing with locations. Instead of dealing with hipe_loc variables, Hipe provides the hipe::loc C++ class.

Including it in your program

For C++ developers, the name of the header file to include is slightly different. Use the following include statement at the top of each relevant code file:

#include <hipe>

and compile using the -lhipe linker argument as usual.

You now don't need to include the header as it is included automatically within . Therefore the ordinary C-based API function calls remain available, but you now also get access to the hipe:: namespace containing C++ alternative classes.

Classes for C++

Hipe provides two classes. hipe::session creates and manages a connection to the Hipe server, and hipe::loc represents the location of an on-screen document element within your program's user interface, such as a frame or button.

The hipe::session class inherits functionality from hipe::loc and represents the <body> element in your application's user interface.

The hipe::session class

To use the Hipe API in an object-oriented way, create a session object from the C++ hipe::session class, rather than the C hipe_session variable type.

hipe::session::open()

After instantiating a session object, call open() on it to open a connection to hiped.

bool open(const char* host_key, const char* socket_path, const char* key_path,
          const char* client_name);

(with arguments as per the hipe_open_session() C function)

Returns true on success. The session object now represents the open session.

hipe::session::close()

Call this on your session object to disconnect your application from hiped. Your application's user interface, and associated resources, are removed from the display server.

The hipe::loc class

A hipe::loc object represents a reference to a document element managed by your application. Unlike C-based hipe_loc variables, you never need to send Hipe a HIPE_OP_FREE_LOCATION instruction, since hipe::loc objects manage their own reference counts. The C++ API will automatically send an instruction to free the server resource once all hipe::loc objects referring to a particular location are discarded.

You can derive hipe::loc location references from other existing hipe::loc objects. This includes your session object, which inherits all of hipe::loc's public functions, and represents the top-level body element.

You can also create hipe::loc objects from C-style hipe_loc variables (or cast them back again), but hipe::loc instances created in this way are not resource-managed and must not be used for anything except comparison with other hipe::loc objects.

hipe::loc::loc()

The loc class has multiple constructors to choose from, depending on how you need to create your location object.

Default constructor. This constructs a 'null' instance of a loc object with no pre-assigned meaning. It must be defined by assigning it to a location before it is used.

loc()

Copy constructor. This creates a loc object by copying the location reference from another existing loc object. Note that a loc object represents a reference to an element location, not the element itself, so it's perfectly safe to have multiple loc objects referring to the same user interface element.

loc(const loc& orig)

Construct from hipe_loc variable. This constructor defines a hipe::loc object from a C-style hipe_loc variable. Since hipe_loc variables don't have managed reference counts or Hipe session information, the resulting hipe::loc object may only be used as a comparison object (for comparison with another hipe::loc object; to check if it matches a particular document element).

loc(const hipe_loc& location)   //object can be used for comparisons only.

hipe::loc::operator=

Assignment operator. You can assign either from another hipe::loc object, or from a C-style hipe_loc variable type value. If you assign from a hipe_loc variable, the same rule applies as with the constructor described above: the newly defined loc object can only be used for comparison purposes.

loc& operator= (const loc& orig)
loc& operator= (const hipe_loc& location)   //object can be used for comparisons only.

hipe::loc::~loc()

Destructor. Always ensure hipe::loc objects are discarded correctly when you're done with them, but don't discard all hipe::loc objects that point to a location you wish to reference again. When the last hipe::loc object pointing to a particular location (excepting comparison objects as described above) is destroyed, the location handle is automatically freed by the display server (the element itself still exists but can no longer be referenced and instructions such as HIPE_OP_GET_LAST_CHILD will no longer produce a valid location value for that object). Therefore, do not destroy all the hipe::loc objects that refer to a particular location whilst you still have hipe_loc variables (and/or hipe::loc comparison objects) referring to that location in memory, and/or wish to reference that location in future.

hipe::loc::firstChild()

Returns a new hipe::loc object corresponding to the first child tag inside this one.

hipe::loc::lastChild()

Returns a new hipe::loc object corresponding to the last child tag inside this one.

hipe::loc::nextSibling()

Returns a new hipe::loc object corresponding to the tag that follows this one at the same level.

hipe::loc::prevSibling()

Returns a new hipe::loc object corresponding to the tag that precedes this one at the same level.

hipe::loc::send()

Sends a hipe instruction as a method of the location the instruction relates to. This is the O-O equivalent of the hipe_send() function.

int send(char opcode, uint64_t requestor, const std::vector& args)

hipe::loc::appendAndGetTag()

Appends a new tag inside this one, and returns a hipe::loc object corresponding to the new tag.

hipe::loc appendAndGetTag(std::string type, std::string id="")

hipe::loc::insertAndGetTag()

Inserts a new tag before this one, at the same level, and returns a hipe::loc object corresponding to the new tag.

hipe::loc insertAndGetTag(std::string type, std::string id="")

Comparing and converting locations

Two hipe::loc objects can be compared with == and !=, and a hipe::loc can be compared with a C-style hipe_loc value using == (for example, the location of a received instruction). < is provided so that hipe::loc objects can be used as keys in ordered containers such as std::map.

A hipe::loc converts to hipe_loc, so it can be passed to the C functions, and to bool: it is false for a null location (a default-constructed object that hasn't been assigned to) and true otherwise.

Note that firstChild(), lastChild(), nextSibling() and prevSibling() return location 0 when there is no such tag, and location 0 is also the <body> element. The object returned is therefore not null: it converts to true and compares equal to your session object. To find out whether a tag was found, compare the result with the session object, or test whether its hipe_loc value is 0.

More hipe::session functions

A hipe::session converts to the C hipe_session handle, so it can be passed to the C functions (for example hipe_next_instruction(), to receive instructions). It also has these functions, each equivalent to the C function named:

Function	Equivalent C function
int fd() const	hipe_session_fd()
int queuedInstructions() const	hipe_queued_instructions()
void setBuffered(bool buffered)	hipe_set_buffered()
int flush()	hipe_flush()

Multithreading with the Hipe API

How should you use the Hipe API if your application contains multiple threads?

The safest possible approach is to limit interactions with the Hipe API to a single thread, regardless of how many threads you have. Nonetheless a degree of thread safety exists within Hipe.

As of version 1.03, sending a completed instruction to the Hipe display server is an atomic, thread-safe operation. This means that if multiple threads send instructions to the hiped server at the same time, the Hipe API will ensure that the instructions are serialised.

Receiving (and waiting on) instructions is not thread-safe. Only one thread should receive instructions at a time. Otherwise incoming instructions may be decoded in a garbled way. Hipe also has no Earthly way of knowing which instructions are wanted by which thread—the display server sends all instructions to the process via a single linear queue.

Example

One sensible compromise is to use one thread for handling the bulk of graphical interactions with the user, while using another thread to display information that does not require user interaction; sending only instructions that do not generate (or require) a reply from the display server. As long as the second thread doesn't compete with the main thread for being the first to append an element to a particular location, for instance, the desired result is guaranteed each time the program runs.

Hipe instructions

Anatomy of an instruction

The hipe_instruction data type produces a C struct with the following member variables:

char     opcode,       /* 8 bits  */
uint64_t requestor,    /* 64 bits */
hipe_loc location,     /* 64 bits */
uint64_t arg_length[4],/* 64 bits per length value */
char*    arg[4]        /* size of each element as specified in arg_length[] */

opcode identifies the nature of the instruction request. You should fill this field using only the predefined macro constants provided by the Hipe API, which are all prefixed by HIPE_OP_ (the prefix was HIPE_OPCODE_ in older versions).

requestor is a 64-bit unsigned integer which you can use to identify an instruction request in a meaningful way. When the Hipe server receives an instruction from an application that requires a response, it passes back the same requestor value in the response. The value of requestor is not interpreted by Hipe in any way. You can use requestor in any number of ways. For example, when requesting events from a calculator utility, you might request that when the user clicks numerical buttons, the events are identified with a requestor value equal to the numerical value of the button clicked. In a more general case, for example when developing a complete GUI toolkit, you might pass as requestor a pointer to an object that will handle a particular event, or deal with a particular subset of incoming instructions.

location is a 64-bit unsigned integer which serves as a numerical handle corresponding to a particular element in the Document Object Model (i.e. a particular HTML tag). Location 0 refers to the <body> element which encloses all other elements within the application frame.

arg[] elements are character strings carrying a different meaning depending on the opcode of the instruction being passed.

arg_length[] specifies the corresponding length of each arg[] element, excluding any null-termination character at the end of the argument string. (Hipe does not expect arguments to be null-terminated.)

If an argument is unused (or not required in a particular instruction), its corresponding arg_length[] element should be assigned a value of 0, and the arg[] element itself may be assigned a NULL pointer.

Transmission of an instruction

The first 49 bytes of a transmitted Hipe instruction form the 'instruction preamble.' The preamble specifies the opcode, requestor and location (the subject of the instruction), as well as the remaining instruction length. Any arguments are then concatenated to the preamble. The arguments may be of any length (or no length at all, depending on the instruction). The recipient therefore reads the preamble first in order to know how much memory to allocate to storing the rest of the instruction. An instruction must be entirely received at the other end before it can be used.

Interprocess communication through Hipe

Like many display servers, Hipe provides some capabilities for sending data from one application to another via the display server itself. While the operating system provides its own capabilities for this, transmitting data through the display server is sometimes useful in its own right: for example, where the user must be involved in selecting target application for data to be exported to (e.g. by selecting the target application from a menu in the desktop environment itself), or where the on-screen relationship between two applications is significant.

Basic message passing

The HIPE_OP_MESSAGE instruction is used to send an arbitrary message to a direct child or parent frame within Hipe.Both applications must have a mutual understanding of what these messages mean, so this technique is most useful in cases where the parent application manages child frames that are directly related to it. For example, a suite of utilities that are all written by the same author and are designed to exchange messages with one another.

FIFOs

A FIFO (or named pipe) is a capability of the operating system where a virtual 'file' is written to by one applicaiton and read from by a different application. The resource looks and behaves like a file on the disk, but no data is actually written to the disk. In certain cases, an actual file on the disk may be used.

Examples include sending a file from a word processor application to a printer application, saving a file to a cloud application by writing to a FIFO that is then read by the cloud access utility, and even simply loading a file by requesting the file's contents from a file manager utility.

Hipe does not create or maintain FIFO resources itself but does provide a set of instructions for allowing applications in Hipe to negotiate setting them up and exchange of data.

• HIPE_OP_FIFO_ADD_ABILITY: A client application can issue this instruction to notify the parent frame of a capability that it has. For example, the ability to save a file to a certain hardware device. The parent frame (e.g. a framing manager) can then choose to maintian a menu of capablities for the user to choose from when choosing to export or import data into another child frame. Note: a framing manager that does not support the use of FIFOs can simply ignore such instructions.
• HIPE_OP_FIFO_REMOVE_ABILITY: A client application can issue this instruction to withdraw a capability that is no longer offered. The parent frame receives the instruction and should remove the ability from its own list accordingly. A client is not guaranteed to remove all its abilities before it terminates, so whenever a child frame terminates, a supporting framing manger should also discard related abilities from its own list.
• HIPE_OP_FIFO_GET_PEER: When a client application requires another application to exchange data with, it sends this instruction to the parent frame (framing manager). A supporting framing manager should then prompt the user to select a peer action from a menu (based on abilities that have been advertised by other applications), relay the instruction to the chosen application, and allow the chosen application to prompt the user for further details and then either ACCEPT or REJECT the connection - which will notify the originator of the FIFO to open and read/write to.
• HIPE_OP_FIFO_RESPONSE: After receiving a ...GET_PEER instruction, a chosen application may prompt the user for more details about the required operation (e.g. if the advertised ability was printing, how many pages does the user want to print? If the chosen action was saving a file, the user may be prompted for a filename and location), before either accepting or rejecting the peer application. A HIPE_OP_FIFO_RESPONSE message will be sent by the chosen application to the framing manager, which then relays it to the peer application, to signal that the FIFO has been established.
  If the chosen application cannot fulfil the request, or the user selects a cancel option in the chosen application, the chosen application relays a 'reject' message back to the peer to indicate that the operation has been cancelled and that the user is already aware of it.
• HIPE_OP_FIFO_OPEN: The client application sends an ..._OPEN instruction to notify the host peer that it is opening the FIFO in a particular access mode. Since a FIFO can work in either direction after creation, it is important that both peers know what the other application requires: for example, if the client is opening the resource to read, the host should open the same FIFO for writing, and begin streaming the required data.
• HIPE_OP_FIFO_CLOSE: The client application sends a ..._CLOSE instruction to notify the host peer that it has closed the FIFO resource at its end. This does not mean the FIFO will not be used again, but will be reopened in an appropriate access mode when it is next required (e.g. open for reading to load a file, then later reopen for writing to save changes to that file).
• HIPE_OP_FIFO_DROP_PEER: At the conclusion of a FIFO relationship between two peers, either application issues this instruction, which is relayed to the other application, to signal that the FIFO resource has been (or should be) destroyed.

A typical interaction might go like this:

1. An application (the 'host') uses HIPE_OP_FIFO_ADD_ABILITY to tell the framing manager about an ability it offers (such as open, save, print, scan, edit, etc.)
2. In another application (the 'client'), the user selects an option to import or export data from/to another application, and the application sends a HIPE_OP_FIFO_GET_PEER request to the framing manager with details of the read/write access it requires.
3. The framing manager prompts the user to select a host application and switches focus to the host to allow the user to select options. The framing manager relays the HIPE_OP_FIFO_GET_PEER instruction to the chosen host application and also inserts the name of the ability the user has selected.
4. The host sends a HIPE_OP_FIFO_RESPONSE response to inform the client of the resource path, and access permissions that are available.
5. The client and host exchange HIPE_OP_FIFO_OPEN instructions to coordinate opening the FIFO resource at both ends in the required direction of transfer.
6. The client sends a HIPE_OP_FIFO_CLOSE instruction when it has finished reading or writing the data required. The host repeats this message back to the client to acknowledge that the resource is now closed at both ends.
7. The client may re-open the FIFO any number of times (e.g. to save the latest changes to a file while the user is working on it). The host is informed each time, so that the service can be provided at the other end.
8. When the client is done with the peer connection, it issues a HIPE_OP_FIFO_DROP_PEER instruction to tell the host to discard the FIFO resource.
9. Before the host terminates, it issues a HIPE_OP_FIFO_REMOVE_ABILITY instruction to indicate that it is no longer offering the FIFO service.

Allowed tags, attributes and styles

A Hipe application builds its interface from HTML tags, attributes and CSS styles, but the display server accepts only those that are safe and meaningful for an application's own frame. This page lists what is accepted.

Anything that isn't accepted is ignored, without an error. If a tag doesn't appear, or an attribute or style has no effect, check it against this page first, including its spelling and its letter case: names are matched exactly as written here, so div is accepted and DIV is not.

Tags

These can be created with HIPE_OP_APPEND_TAG and HIPE_OP_INSERT_TAG:

Kind	Tags
Sections and headings	section nav article aside header footer hgroup h1 h2 h3 h4 h5 h6 address div center
Paragraphs and blocks	p pre blockquote hr br wbr figure figcaption details summary
Lists	ol ul li dl dt dd menu command
Inline text	span a abbr b bdo big cite code dfn em i kbd mark q rp rt ruby s samp small spacer strong sub sup time tt u var ins del
Tables	table caption colgroup col thead tbody tfoot tr th td
Forms and controls	form fieldset legend label input button select datalist optgroup option textarea output progress meter
Images, media and drawing	img video audio source track canvas svg map area
Frames and embedding	iframe frame frameset object

With the hipecore display server backend, these SVG tags can also be created inside an svg tag: g path rect circle ellipse line polyline polygon defs linearGradient radialGradient stop text tspan clipPath symbol.

Tags that load or run something are not accepted: for example script, style, link, meta, embed and base. Style rules are added with HIPE_OP_ADD_STYLE_RULE.

A tag that is refused still uses up the location that was allocated for it. Instructions sent to that location do nothing, and the location can be freed as usual.

Attributes

These can be set with HIPE_OP_SET_ATTRIBUTE and removed with HIPE_OP_REMOVE_ATTRIBUTE:

abbr accept-charset accesskey align alt autoplay border cellpadding cellspacing char charoff checked cols colspan contenteditable controls coords dir disabled for frame frameborder headers height hidden id label loop max maxlength min multiple muted name noresize placeholder preload readonly rows rowspan rules scope scrolling selected shape size span step summary tabindex title type usemap valign value width

With the hipecore backend, these attributes of SVG tags are accepted too: d cx cy r rx ry x1 y1 x2 y2 points viewBox preserveAspectRatio fill fill-opacity fill-rule stroke stroke-width stroke-opacity stroke-linecap stroke-linejoin stroke-dasharray opacity transform gradientUnits gradientTransform offset stop-color stop-opacity text-anchor dx dy clip-path.

Some things that are attributes in HTML have their own instruction in Hipe, and can't be set as attributes:

In HTML	In Hipe
class	HIPE_OP_TOGGLE_CLASS, or arg[2] of HIPE_OP_APPEND_TAG and HIPE_OP_INSERT_TAG
style	HIPE_OP_SET_STYLE
src	HIPE_OP_SET_SRC, which takes the file's data and not an address
onclick, onkeydown and other event attributes	HIPE_OP_EVENT_REQUEST
href	Not available: nothing in a Hipe frame navigates. To hand a link to the user's environment, use HIPE_OP_OPEN_LINK.

Any attribute can be read with HIPE_OP_GET_ATTRIBUTE.

Styles

Any CSS property and value can be used with HIPE_OP_SET_STYLE, and any selector and properties with HIPE_OP_ADD_STYLE_RULE, except that the instruction is ignored if the property, value or selector contains:

• any of the characters < > { }. This rules out the child selector a > b: use a descendant selector (a b) or a class.
• url(. Styles can't refer to files or addresses. To use an image or a font in a style, send its data with HIPE_OP_SET_STYLE_SRC, HIPE_OP_ADD_STYLE_RULE_SRC or HIPE_OP_ADD_FONT.

Text

Text given to HIPE_OP_SET_TEXT, HIPE_OP_APPEND_TEXT and the tag instructions is never treated as HTML, so it can't create tags or attributes. See HIPE_OP_SET_TEXT.

Instruction set reference

HIPE_OP_ADD_FONT

Adds a font to the document for use in subsequent styling, by sending font data to the display server.

• location: 0. Not used.
• arg[0]: Specify a name for the font here. The name is then used to specify the font face in subsequent styling.
• arg[1]: The correct mime type for the font data must be specified. (e.g. "application/x-font-woff")
• arg[2]: Pass the raw contents of the font file here.

Notes

For security reasons, the font data added using HIPE_OP_ADD_FONT is local to the client application. It is inaccessible to other applications running within the Hipe session.

Instruction set reference

HIPE_OP_ADD_STYLE_RULE

Sent by a client application to the display server to specify a CSS style rule.

• location: 0. Not used.
• arg[0]: The CSS descriptor of element(s) the rule will apply to (e.g. "div", "#element", etc.).
• arg[1]: A set of style properties, separated by semicolons (e.g. "border:0; width:100%;").

Notes

The instruction is ignored if the selector or the properties contain <, >, {, } or url(. See "Allowed tags, attributes and styles".

For styling individual elements after you have created them, use the HIPE_OP_SET_STYLE instruction instead.

Some combinations of CSS rules can produce undefined behaviour involving race conditions where application layouts may either render correctly or incorrectly each time the application runs. To avoid this, ensure that multiple layout elements are not defined purely relative to one another, particularly when using tables.

Older versions of QtWebKit contained a bug that did not respect style rules added after the first content was displayed. If this is an issue, all style rules should be specified before anything else, after the hipe session has been opened. Hipecore does not have this bug.

Instruction set reference

HIPE_OP_ADD_STYLE_RULE_SRC

Sets background image data for a particular CSS style rule specifier.

• location: 0 - not used.
• arg[0]: The CSS descriptor of element(s) the rule will apply to (e.g. "div", "#element", etc.).
• arg[1]: binary image file data. If the data is not a PNG image, the next argument should specify the mime type for the data.
• arg[2]: (optional) The mime type for the data supplied in arg[1]. If not specified, "image/png" is assumed.

Instruction set reference

HIPE_OP_APPEND_TAG

Appends a new HTML tag element as the last child within the specified tag element.

• location: The parent element inside which the new tag will be appended.
•   arg[0]: The tag type (e.g. span or button).
•   arg[1]: An optional id string to uniquely identify the new element. The tag id can be used in conjunction with CSS style rules or later in conjunction with HIPE_OP_GET_BY_ID.
•   arg[2]: Optional. A space-separated list of CSS classes to give the new element, as if added with HIPE_OP_TOGGLE_CLASS.
•   arg[3]: Optional. Initial text content for the new element, handled as HIPE_OP_SET_TEXT handles its arg[0] in text mode 0: the characters <, >, &, " and ' are shown as typed, and newlines and tabs are not converted. Ignored for void elements such as br, img and input, which can't have content.

Notes

Only tags that Hipe allows are created; any other tag type is ignored. See "Allowed tags, attributes and styles".

When building a table, append a tbody tag to the table first, and append the tr rows to that. HTML doesn't allow a row directly inside a table, so a tr appended straight to a table is wrapped in a tbody of its own, and the location you get back refers to that wrapper and not to the row: cells then appended to it each land in a separate row.

When building up a table (or similar layout-intensive element) by appending td elements to it, keep the table hidden (use the display style property for this purpose) until it is complete. It will display faster overall, since Hipe will not have to keep recalculating and re-rendering the layout as you add your table cells.

Setting the class and text in the same instruction (arg[2] and arg[3]) is much faster than following up with HIPE_OP_TOGGLE_CLASS and HIPE_OP_SET_TEXT, which matters when building many small elements, such as the coloured spans of syntax-highlighted text.

Prior to version 2, Hipe accepted an extra argument in arg[2] where passing "1" would cause the server to reply with a HIPE_OP_LOCATION_RETURN instruction describing the newly appended tag. This was removed in version 2, and arg[2] is now the class list. A more efficient way to obtain the new location is by calling the hipe_newest_location() function (C) or the hipe::loc::appendAndGetTag() method (C++) in the hipe API.

Instruction set reference

HIPE_OP_APPEND_TEXT

Appends a text element as the last child element within the specified tag element.

• location: The proud parent element.
• arg[0]: A string of text to append.
• arg[1]: Text mode: "0" (the default, also used if the argument is empty), "1" or "2". See the table below.

Text modes

In every mode, the characters <, >, " and ' are shown as typed. Text that looks like an HTML tag, such as <b>, is never treated as markup, so there is no need to remove such things from arg[0]. The modes differ in what happens to & and to newlines, carriage returns and tabs.

Mode	&	Newlines, carriage returns and tabs	Text read back with HIPE_OP_GET_CONTENT
"0"	Shown as typed.	Not converted.	The same as arg[0].
"1"	Shown as typed.	Converted: a newline becomes a line break, a carriage return an empty paragraph, a tab a wide space.	Differs from arg[0]: the newlines and carriage returns are now elements, not characters, and each tab is a wide space character.
"2"	Starts a character entity: × shows as ×, & as &.	Not converted.	arg[0] with its entities replaced by the characters they stand for.

Where newlines and tabs are not converted (modes 0 and 2), how they look depends on the element. Most elements show any run of spaces, tabs and newlines as a single space, as HTML normally does. An element that keeps whitespace, such as a pre tag or one styled with white-space: pre, shows them as line breaks and tab stops.

Also in modes 0 and 2, a carriage return is stored as a newline, and a carriage return followed by a newline is stored as one newline.

Which mode to use

• Mode 0 for most text, and for any text that will be read back or edited and must come back the same, such as a source file shown in a pre tag. To show a symbol, put the character itself in the text: arguments are UTF-8.
• Mode 1 for showing text you don't control, such as an error message or a command's output, in an ordinary element with its line breaks and tabs visible and no styling of your own.
• Mode 2 for text you write yourself, where you want symbols by name, such as a calculator button labelled &times;. Don't use it for text that may contain & for any other reason: some older entity names are recognised without their closing semicolon, so &param shows as ¶m and &times, as ×,.

Instruction set reference

HIPE_OP_ATTRIBUTE_RETURN

This instruction is received by the client (sent by the display server) in response to a HIPE_OP_GET_ATTRIBUTE request. It is the server's way of returning the requested data.

• location: the location of the element for which data is being returned.
• arg[0]: the name of the attribute for which data was requested.
• arg[1]: the current value stored in the attribute data.
• requestor: value passed back to client from HIPE_OP_GET_ATTRIBUTE request.

Instruction set reference

HIPE_OP_AUDIOVIDEO_STATE

When sent from the client to the server, modifies the playback state of an <audio> or <video> element. When received from the server, this is sent in response to a HIPE_OP_GET_AUDIOVIDEO_STATE request and reflects the current state of the media element.

• location: The <audio> or <video> element being controlled or queried.
• arg[0]: Setting: the desired playback position, in seconds. Receiving: the current playback position and the total duration, in seconds, separated by a comma (e.g. "12.5,90").
• arg[1]: The playback speed, where 1 is normal speed.
• arg[2]: The playing/paused status: "1" for playing, "0" for paused.
• arg[3]: The playback volume, as a fraction of 1.0.

Notes

When sending this instruction to set the playback state, any argument that isn't being changed may be left empty — only the arguments you provide will be applied.

Instruction set reference

HIPE_OP_CANVAS_ACTION

Calls a drawing method on the canvas that was selected with HIPE_OP_USE_CANVAS. The methods are those of the HTML Canvas 2D Context.

• location: not used. The instruction applies to the selected canvas.
• arg[0]: the name of the method, e.g. "fillRect".
• arg[1]: the method's parameters, separated by commas, in the order the method takes them, e.g. "0,0,150,75" for fillRect's x, y, width and height.

An unknown method name, the wrong number of parameters, or a parameter that can't be used (such as text where a number is expected) causes the instruction to be ignored. No error is reported.

With the hipecore display server backend, the methods are those listed below. With the Qt5WebKit backend, any method of the 2D context can be named, but the methods on this page that aren't part of the HTML specification (those dealing with ids, and setSrcRegion) are not available.

Writing the parameters

• Spaces around a comma are ignored: "0, 0, 150, 75" is the same as "0,0,150,75".
• A comma inside round or square brackets doesn't separate parameters, so rgba(0,0,0,0.5) and [4,2] are each one parameter.
• Put a parameter in double quotes if it contains a comma or spaces that matter, such as the text for fillText: "Score: 1, 2, 3", 10, 20. Inside the quotes, write a double quote as \".

Methods

Method	Arguments
save	—
restore	—
scale	sx, sy
rotate	angle (radians)
translate	tx, ty
transform	m11, m12, m21, m22, dx, dy
setTransform	m11, m12, m21, m22, dx, dy
beginPath	—
closePath	—
moveTo	x, y
lineTo	x, y
quadraticCurveTo	cpx, cpy, x, y
bezierCurveTo	cp1x, cp1y, cp2x, cp2y, x, y
arcTo	x0, y0, x1, y1, radius
arc	x, y, radius, startAngle, endAngle, anticlockwise ("true"/"false")
ellipse	x, y, radiusX, radiusY, rotation, startAngle, endAngle, anticlockwise ("true"/"false")
rect	x, y, width, height
fill	0 args (implicit path, default winding); 1 arg (implicit path, winding rule "nonzero"/"evenodd"); or 2 args (path id, winding rule)
stroke	0 args (implicit path) or 1 arg (path id)
clip	same shape as fill above
clearRect	x, y, width, height
fillRect	x, y, width, height
strokeRect	x, y, width, height
fillText	text, x, y, optional maxWidth
strokeText	text, x, y, optional maxWidth
setLineDash	a single bracketed list of numbers, e.g. [4,2] ([] clears the dash pattern)
drawImage	source element id, then either (dx, dy), (dx, dy, dw, dh), or (sx, sy, sw, sh, dx, dy, dw, dh) (see Notes)
setSrcRegion	dx, dy, width, height (see Notes)
createLinearGradient	id, x0, y0, x1, y1
createRadialGradient	id, x0, y0, r0, x1, y1, r1
addColorStop	gradientId, offset, color
createPattern	id, sourceElementId, repetition ("repeat"/"repeat-x"/"repeat-y"/"no-repeat")
deleteGradient	gradientId
deletePattern	patternId
createPath2D	id
deletePath2D	id
selectPath2D	id (empty string reselects this canvas's own implicit path)

Gradients, patterns and paths

In HTML a gradient, pattern or path is an object that a script keeps hold of. Here each one is given an id by the client when it is created, and is referred to by that id afterwards. Ids belong to the canvas they were created on: the same id on another canvas is a different object.

• Gradients and patterns are created with createLinearGradient, createRadialGradient and createPattern. To draw with one, set fillStyle or strokeStyle to url(#id) with HIPE_OP_CANVAS_SET_PROPERTY.
• A path is created with createPath2D. Call selectPath2D with its id, and the path-building methods (moveTo, lineTo, arc, rect and so on) add to that path instead of the canvas's own, until selectPath2D is called with a different id or an empty one. fill, stroke and clip can be given a path's id directly, without selecting it, and so can the tests of HIPE_OP_CANVAS_QUERY.
• These objects are kept until they are deleted with deleteGradient, deletePattern or deletePath2D. A client that creates many should delete those it no longer needs.

Notes

beginPath always starts the canvas's own path afresh, whichever path is selected. To start a new named path, create one under a new id.

drawImage's first parameter is the id attribute of an img, canvas or video element in the document. The rest are numbers, in one of three forms: the destination position (dx, dy); the destination rectangle (dx, dy, dw, dh); or a source rectangle followed by the destination rectangle (sx, sy, sw, sh, dx, dy, dw, dh).

setSrcRegion is not a method of the HTML canvas. It sets the area of the canvas that raw pixels sent with HIPE_OP_SET_SRC will be written to: the top-left position (dx, dy) and the width and height of the pixel data. The area is in canvas pixels and is not affected by scale, translate or the other transformations. It stays in effect until it is set again. If it is never set, raw pixels fill the whole canvas. See HIPE_OP_SET_SRC.

Only the 2D context is available. To read a canvas back as an image, use HIPE_OP_GET_SRC.

Instruction set reference

HIPE_OP_CANVAS_QUERY

Asks a question of the canvas that was selected with HIPE_OP_USE_CANVAS. It covers the methods of the HTML Canvas 2D Context that return a value. The display server replies with HIPE_OP_CANVAS_QUERY_RETURN.

This instruction needs the hipecore display server backend. With the Qt5WebKit backend the reply is always an error.

• location: not used. The instruction applies to the selected canvas.
• arg[0]: the query: "isPointInPath", "isPointInStroke" or "measureText".
• arg[1]: the query's parameters, separated by commas and written as for HIPE_OP_CANVAS_ACTION.

Query	Parameters	Reply
isPointInPath	pathId, x, y, and optionally the winding rule: "nonzero" (the default) or "evenodd"	true or false
isPointInStroke	pathId, x, y	true or false
measureText	the text	Its width in pixels, in the canvas's current font

Notes

pathId is always given. It is the id of a path made with createPath2D (see HIPE_OP_CANVAS_ACTION), or empty to test the canvas's own current path, as in ",10,20".

measureText measures in the font set on the canvas with HIPE_OP_CANVAS_SET_PROPERTY. To measure text in the font of an element of the document, use HIPE_OP_MEASURE_TEXT.

Instruction set reference

HIPE_OP_CANVAS_QUERY_RETURN

Sent by the server in response to a HIPE_OP_CANVAS_QUERY request.

• location: not applicable.
• arg[0]: on success, the result as a string — "true"/"false" for isPointInPath/isPointInStroke, or a decimal number for measureText's width. Absent/empty on failure.
• arg[1]: on failure, a human-readable error message (no context selected, unrecognised query name, wrong argument count, or an unknown path id). Absent/empty on success.

Instruction set reference

HIPE_OP_CANVAS_SET_PROPERTY

Sets a property on the canvas context currently selected with HIPE_OP_USE_CANVAS (for example, fillStyle or lineWidth).

Note: When Hipe is built against stock Qt5WebKit, arg[0] may be any property name from the HTML Canvas 2D Context specification, since it is executed as JavaScript against the canvas context. When Hipe is built against hipecore, canvas drawing is implemented directly in C++ rather than through JavaScript (which hipecore does not support), so only the specific property names listed below are recognised. An unrecognised property name, or a value that fails to parse for that property's type, is silently ignored — the server does not report an error back to the client.

• location: not applicable — the canvas object was already selected via HIPE_OP_USE_CANVAS.
• arg[0]: the name of the property to set, matching the property names defined in the HTML Canvas 2D Context specification (e.g. "fillStyle", "strokeStyle", "lineWidth", "font").
• arg[1]: the value to assign to that property, as a single string — unlike HIPE_OP_CANVAS_ACTION's arg[1], this is one value, not a comma-separated list.

Properties implemented under hipecore

Property	Value
fillStyle	a CSS colour string (e.g. red, #ff0000, rgba(0,0,0,0.5)), or url(#id) referencing a gradient/pattern id created via HIPE_OP_CANVAS_ACTION's createLinearGradient/createRadialGradient/createPattern — see that instruction's "Named objects" section
strokeStyle	same as fillStyle above
lineWidth	a number
lineCap	butt, round, or square
lineJoin	round, bevel, or miter
miterLimit	a number
lineDashOffset	a number
shadowOffsetX	a number
shadowOffsetY	a number
shadowBlur	a number
shadowColor	a CSS colour string
globalAlpha	a number from 0 to 1
globalCompositeOperation	a composite operation name from the HTML Canvas 2D Context specification, e.g. source-over, multiply
font	a CSS font shorthand string, e.g. 16px sans-serif
textAlign	start, end, left, right, or center
textBaseline	a baseline name from the HTML Canvas 2D Context specification, e.g. alphabetic, middle
imageSmoothingEnabled	"true" or "false"

Note that setLineDash is a method in the Canvas 2D specification, not a property — set it via HIPE_OP_CANVAS_ACTION instead, described on that instruction's reference page.

Instruction set reference

HIPE_OP_CARAT_POSITION

This instruction relates to the current position of the text entry carat (cursor position, or range of selected text) in an input element such as a textarea tag, or in an element with the contenteditable attribute.

The instruction may be sent to the server in order to move the text cursor position or select a range of text. It can also be received from the server in response to a HIPE_OP_GET_CARAT_POSITION instruction, to get the current text entry and/or selection position.

• location: The element for which to set the text entry carat position.
• arg[0]: Character offset of the selection's anchor: the point where the selection starts.
• arg[1]: Character offset of the selection's focus: the point where it ends, which is where the cursor is. If no text should be selected (simple cursor), use the same value as arg[0], or leave this argument empty. If arg[1] is less than arg[0], the selection is made backwards, as if the user had selected from right to left.
• arg[2]: Optional. Pass "1" to scroll the selection into view. Otherwise the view is not scrolled.

Offsets

Offsets count characters, starting from 0 before the first character. A character is a Unicode code point, which may be several bytes long in UTF-8: an offset is never a byte count.

For input and textarea elements, offsets index the element's value. For other elements, they index the element's text as it is laid out: the same text that HIPE_OP_GET_CONTENT returns in mode 2. In this text, line-break tags such as <br> and the boundaries between block elements (such as consecutive div tags) each count as one line-break character, and runs of spaces that are displayed as a single space count once. Elements styled display:none don't count.

Negative offsets count from the end of the text: -1 is the position after the last character, -2 the position before the last character, and so on. This is useful for placing the cursor at (or near) the end of the text without first having to query its length. For example, arg[0] = "0" and arg[1] = "-1" selects all the text. Offsets beyond the text are clamped to it.

Notes

If arg[0] is empty, the instruction is ignored. HIPE_OP_GET_CARAT_POSITION replies with empty arguments when the element contains neither the cursor nor selected text, so sending back what it returned never moves the selection. Arguments that aren't whole numbers are also ignored.

Setting the carat in an element with the contenteditable attribute also gives that element keyboard focus.

Some positions can't hold a cursor, and the display engine moves the cursor to the nearest one that can. For example, in a contenteditable element whose text ends with a line break, the position after that final line break has no line to appear on, so the cursor is placed before it. Similarly, a character that the user sees as one symbol may be made of several code points (such as some flags, or a letter with a separately encoded accent), and the cursor can't be placed between them.

The character offsets, the handling of elements other than input and textarea, backward selections and arg[2] are features of the hipecore display server backend.

Instruction set reference

HIPE_OP_CLEAR

Clears the contents of the tag at the given location, removing all child elements.

• location: The tag whose contents are to be cleared.
• no arguments.

Notes

While the tag content of location is cleared, the tag at location itself, and its attributes, remain.

Clearing location 0 (the body element) clears the frame's contents.

If you need to delete a tag entirely, clear its parent tag, or use HIPE_OP_DELETE.

Instruction set reference

HIPE_OP_CONTAINER_GRANT

You never need to deal with this instruction directly. It is sent by the server to the client application to indicate the validity of a new client session. It is received and processed automatically by hipe_open_session() before that function returns.

• location: 0 — not used.
• arg[0]: "1" if a frame has been granted to the client application, or "0" if the request was denied (invalid or expired host key)

Instruction set reference

HIPE_OP_CONTENT_RETURN

Sent back from the server in response to a HIPE_OP_GET_CONTENT request.

• location: The location on which content was requested
• requestor: Returns back user-defined information that was passed with the original request.
• arg[0]: The contents of the specified element (for mode 4 requests: see below).
• arg[1] to arg[3]: Empty, except in replies to mode 4 requests.

Replies to mode 4 requests

A HIPE_OP_GET_CONTENT request in mode 4 asks for the changes to the element's text since the client's previous mode 4 request for that element, rather than the whole text. The reply describes one replacement, to be applied to the text as returned by the previous mode 4 reply:

• arg[0]: The new text of the part that changed (possibly empty, for a deletion).
• arg[1]: Where the change starts, in characters from the start of the text.
• arg[2]: How many characters of the previous text it replaces (possibly 0, for an insertion).
• arg[3]: delta for such a change. full if arg[0] is instead the whole text (the first mode 4 request for the element, or one made with full in its arg[1]), in which case arg[1] and arg[2] are 0.

For example, if the text was hello world and the user typed X after hello, the reply is X, 5, 0, delta: replace 0 characters at position 5 with X. If nothing has changed, the reply is an empty string, 0, 0, delta, which changes nothing when applied.

Characters are Unicode code points, as in HIPE_OP_CARAT_POSITION: count UTF-8 characters, not bytes. The reported change is the smallest one that turns the previous text into the new one. It always produces the right text, but it isn't necessarily where the user typed: in hello, typing another l after the first l may be reported as an insertion after the second one, since both give the same result.

Only mode 4 fills in arg[1] to arg[3], and a mode 4 reply always has delta or full in arg[3]. A reply with an empty arg[3] is therefore never a list of changes.

Instruction set reference

HIPE_OP_DELETE

Deletes the specified element itself, rather than clearing its contents.

• location: The tag element to be deleted.

Notes

Use HIPE_OP_CLEAR to clear the contents of an element rather than the element itself.

Instruction set reference

HIPE_OP_DIALOG

This instruction is used to request a dialog box prompt to be displayed for collecting user input. If the frame that sends the instruction is a child of another frame (such as a framing manager), the parent frame receives the instruction to act upon. If the frame that requests the dialog is a top-level frame, Hipe itself produces the dialog box.

The dialog box should be implemented modally, which means the user should not be able to continue interacting with the application until the dialog has either been answered or dismissed (cancelled).

• location: Sending a request: A value of 0 (corresponding to the body element of the client frame) means the message should be sent to the direct parent of this client. If the client is at the top level, the request will be handled by the Hipe server directly, otherwise the functionality should be integrated into the framing manager.
  Receiving a request: A location value corresponding to a child frame means the message came from that client.
• arg[0]: Dialog title caption
• arg[1]: Dialog prompt text
• arg[2]: Dialog answer choices, separated by newlines. (e.g. "Yes\nNo\nOther") A separator may be specified by leaving a line blank. Blank lines keep their place in the numbering of choices (see HIPE_OP_DIALOG_RETURN), so they can also be used to keep a choice in the same position whatever other choices are offered. When the display server shows the dialog itself (a top-level client with no framing manager), blank lines before the first choice or after the last are left out, and each run of blank lines between choices is shown as a single separator line that can't be chosen.
• arg[3]: Character symbols (UTF8) for each option, separated by newlines. If no symbol is required or a separator occupies a 'slot', the corresponding line should be left blank. An additional symbol at the end of the list specifies a symbol for the dialog itself. Give each symbol as the character itself, encoded as UTF-8 (for example ⚠). HTML character entities are not decoded: a symbol written as &#9888; is shown as those seven characters.

Notes

Framing managers without dialog support: As there is no mechanism in Hipe that may be used to determine whether a framing manager implements dialogs or not, a framing manager that does not implement dialog functionality must respond to a HIPE_OP_DIALOG or HIPE_OP_DIALOG_INPUT instruction with a HIPE_OP_DIALOG_RETURN instruction and arguments {"","0"} to indicate that the dialog has been cancelled. Otherwise, client applications that request dialogs may be left in an undefined or suspended state.

The framing manager should send a HIPE_OP_DIALOG_RETURN instruction back to the client once the dialog has been answered by the user.

Modality: The framing manager should display the dialog in a modal way, preventing interaction with the client frame until the dialog is answered. There are at least two ways to implement this: (a) prevent the user interacting with the client until the dialog is dismissed, or (b) that the dialog is dismissed automatically if the user removes focus from the dialog, and a 'cancel' is inferred.

Instruction set reference

HIPE_OP_DIALOG_INPUT

This instruction provides an alternative form of HIPE_OP_DIALOG that allows freeform text input by the user, rather than a set of fixed choices. Otherwise, this dialog functions similarly to HIPE_OP_DIALOG and the user's response is received back via a HIPE_OP_DIALOG_RETURN instruction.

• location: Sending a request: A value of 0 (corresponding to the body element of the client frame) means the message should be sent to the direct parent of this client. If the client is at the top level, the request will be handled by the Hipe server directly, otherwise the functionality should be integrated into the framing manager.
  Receiving a request: A location value corresponding to a child frame means the message came from that client.
• arg[0]: Title text for the dialog
• arg[1]: Dialog prompt text. Multiple lines are allowed; in which case the implementor of the framing manager responsible for displaying the dialog might choose to position the last line alongside the input prompt itself, with preceding lines being explanatory text.
• arg[2]: Suggested inputs, separated by newlines. The first line is the suggested default input. If the first line is blank, the input box presented to the user should initially be empty. If the whole argument is blank, no suggestions are provided.
• arg[3]: A unicode character symbol (UTF8) to be displayed alongside the question prompt. Give the symbol as the character itself, encoded as UTF-8. HTML character entities are not decoded.

Notes

Framing managers without dialog support: As there is no mechanism in Hipe that may be used to determine whether a framing manager implements dialogs or not, a framing manager that does not implement dialog functionality must respond to a HIPE_OP_DIALOG or HIPE_OP_DIALOG_INPUT instruction with a HIPE_OP_DIALOG_RETURN instruction and arguments {"","0"} to indicate that the dialog has been cancelled. Otherwise, client applications that request dialogs may be left in an undefined or suspended state.

For providing suggested inputs to the user in arg[2], a possible use case might be to provide the user with the 5 most recently used commands, based on the user's previous inputs.

Instruction set reference

HIPE_OP_DIALOG_RETURN

This instruction is sent to a client application that has requested a dialog (either using a HIPE_OP_DIALOG or HIPE_OP_DIALOG_INPUT instruction), to allow the client application to receive the user's response to the dialog.

If the client application is running as a top-level frame, Hipe itself handles display of the dialog and sending the user's response back to the client. If the client application is running as a child frame of another application (such as a framing manager), the parent application is expected to handle display of an appropriate dialog box, and to send a HIPE_OP_DIALOG_RETURN instruction back to the client application (by specifying the location of the client frame) in order to communicate the user's response back to the appropriate client.

• location: Always 0 when received by a client frame. When sending to a child frame (from a parent frame that handles display of the dialog), use the location of the client frame that awaits the response.
• requestor: Relays back the value that was used in requesting the dialog.
• arg[0]: The text of the response chosen or entered by the user (or blank if cancelled by the user).
• arg[1]: The index number (numbered from 1) of the response chosen, or 0 if cancelled. If the dialog allowed free-form text entry rather than fixed choices, the index number will be 1 to indicate that the dialog was not cancelled by the user.

Notes

Framing managers without dialog support: As there is no mechanism in Hipe that may be used to determine whether a framing manager implements dialogs or not, a framing manager that does not implement dialog functionality must respond to a HIPE_OP_DIALOG or HIPE_OP_DIALOG_INPUT instruction with a HIPE_OP_DIALOG_RETURN instruction and arguments {"","0"} to indicate that the dialog has been cancelled. Otherwise, client applications that request dialogs may be left in an undefined or suspended state.

Instruction set reference

HIPE_OP_EDIT_ACTION

Performs a cut/copy/paste or other edit action on the text the user has selected, or at the text cursor, in the element that has keyboard focus.

Every application inside a top-level window is a frame of the same document hierarchy, so an edit action always applies to the frame that currently has keyboard focus. To stop one application acting on another's content, the rules depend on who sends the instruction:

• A top-level client (normally the framing manager) may always perform edit actions. If it names a child frame in location and the keyboard focus isn't inside that frame, focus is first moved to that frame, so the action applies to that application (for example, to its selection or its own undo history).
• Any other client may perform edit actions only while the keyboard focus is inside its own frame (or inside the child frame it names, or a frame nested within it). Otherwise the instruction is ignored. Setting the focus first, e.g. with HIPE_OP_SET_FOCUS, satisfies this. Paste (v and V) has an extra condition, described below.

• location: 0 to act on the current frame (including frames nested within it), or the location of a child frame to act on that frame instead.
• arg[0]: The "action code" character for the function required. See below.
• arg[1]: For the t action only, the text to insert. Empty to delete the selected text.

Action codes

Character	Editing operation
z	Undo
Z	Redo
a	Select all
x	Cut selected text to clipboard
c	Copy selected text to clipboard
v	Paste selected text from clipboard, matching destination formatting
V	Paste selected text from clipboard, preserving source formatting if applicable
b	Toggles bold if applicable
i	Toggles italic if applicable
u	Toggles underline if applicable
k	Toggles strikethrough if applicable
l	Align left if applicable
C	Align center if applicable
r	Align right if applicable
j	Align justified if applicable
d	Set text direction default
>	Set text direction left to right
<	Set text direction right to left
t	Insert the text given in arg[1], or delete the selected text if arg[1] is empty

Notes

This operation will succeed or fail silently. There is no response from the server. Use HIPE_OP_EDIT_STATUS to find out which actions are currently available.

Paste from a non-top-level client. Pasting gives the clipboard's contents to the client that receives them, so a client that isn't top-level may only paste in response to the user: within a few seconds after the user clicked or pressed a key in its frame, or after the framing manager relayed the user's answer to a dialog (HIPE_OP_DIALOG_RETURN) to it or to a frame containing it. In practice, send the paste instruction as soon as you receive the click, key press or dialog answer that asked for it. At other times it is ignored. The user can always paste with the keyboard shortcut, which doesn't use this instruction.

Insert text (t) puts the text in arg[1] at the text cursor, replacing any selected text, as if the user had typed it. Nothing happens unless the text cursor is in editable content (a text input, a <textarea>, or an element with the contenteditable attribute). The text is never treated as HTML: characters such as < and & are shown as typed. Each newline in the text becomes a line break, as when the user presses Enter in plain text (a single-line text input can't hold line breaks, so each newline becomes a space there), and the text cursor is left after the inserted text. The whole insertion is undone by a single undo; as with ordinary typing, that undo also removes anything the user typed immediately before it. A typical use is inserting a tab or indentation when the user presses Tab, after cancelling the key's default action (see HIPE_OP_EVENT_REQUEST).

If arg[1] is empty, t deletes the selected text instead, as the Delete key would, and leaves the text cursor where the selection was. This is one step for undo. If no text is selected (there is only a text cursor), nothing is deleted. To remove a particular range, select it first with HIPE_OP_CARAT_POSITION.

Undo and redo act on the undo history of the focused frame's document. With the hipecore display server backend each frame has its own undo history, so undoing in one application never reverts an edit made in another. With the Qt5WebKit backend, all frames in a window share one undo history: undo may invisibly revert the most recent edit in another application, even one not currently visible, rather than the last edit in the focused element. This might lead the user to undo several minutes of work in another app without realising it.

Instruction set reference

HIPE_OP_EDIT_CONTEXT_REQUEST

Receiving this instruction on a top-level frame indicates that there has been an unhandled context menu request either in that frame or in a child (or descendent) of that frame.

This normally means the user has right-clicked on a section of text somewhere in the frame hierarchy and expects to see a default menu of clipboard commands such as cut/copy/paste. Due to limitations in webkit and hipecore, further information is not available. However, a framing manager can respond by using a HIPE_OP_EDIT_STATUS instruction to query what commands are suitable for whatever the user has selected, and globally implement a default context menu that way.

This instruction is not generated if a context click event has already been handled by the application (e.g. to produce a more relevant menu at the application level).

• location: 0
•     arg[]: Not used.
• requestor:: Not used.

Instruction set reference

HIPE_OP_EDIT_STATUS

Used to determine which edit actions are available, i.e. applicable to the currently selected content or focused element. This is useful for creating an 'Edit' menu with unavailable options removed.

The answer describes the frame an edit action would apply to, under the same rules as HIPE_OP_EDIT_ACTION: a top-level client may query any child frame (and if the keyboard focus isn't inside that frame, focus is moved to it, as for an edit action), while any other client gets an answer only while the keyboard focus is inside its own frame or the child frame it names. Otherwise every action is reported as unavailable.

• location: 0 to query the current frame, or the location of a child frame.
• arg[0]: A string of "action code" characters for the functions that may be required. See below.

Action codes

Character	Editing operation
z	Undo
Z	Redo
a	Select all
x	Cut selected text to clipboard
c	Copy selected text to clipboard
v	Paste selected text from clipboard, matching destination formatting
V	Paste selected text from clipboard, preserving source formatting if applicable
b	Toggles bold if applicable
i	Toggles italic if applicable
u	Toggles underline if applicable
k	Toggles strikethrough if applicable
l	Align left if applicable
C	Align center if applicable
r	Align right if applicable
j	Align justified if applicable
d	Set text direction default
>	Set text direction left to right
<	Set text direction right to left
t	Insert text, or delete the selected text (available when the text cursor or selection is in editable content)

Notes

The server responds with a HIPE_OP_EDIT_STATUS instruction. Its arg[0] repeats the action codes that were asked about, and its arg[1] holds one status character for each of them, in the same order:

• 0 — available (and, for a toggle such as bold, not currently on);
• 1 — available, and currently on (for toggles such as bold);
• e — not available now, or not a recognised action code.

For example, asking about "zxcv" might return "0ee0": undo and paste are available, but cut and copy aren't because no text is selected.

Paste is reported as available whenever there is something to paste into, even for a client that isn't top-level; whether such a client may actually paste also depends on recent user input (see HIPE_OP_EDIT_ACTION).

Instruction set reference

HIPE_OP_EVENT

Generated by the server and sent to the client when a requested GUI event occurs.

• location: The tag element that the user interacted with
• arg[0]: The type of event (in the same form as in the event request)
• arg[1]: Detail about the event. This varies depending on the event type (see the table below). (E.g. for a "click" event, this will be the mouse button that generated the click, followed by the modifier keys held.)
• requestor: Sends back the user-defined value that was passed to Hipe in the HIPE_OP_EVENT_REQUEST call that set up these particular events.

Event details

The detail in arg[1] is a comma-separated list of numbers:

Event	arg[1]
keydown, keyup	keyCode,modifiers
keypress	charCode (the character typed; no modifiers)
click	button,modifiers
mousedown, mouseup, mousemove, mouseenter, mouseleave, mouseover, mouseout	button,pageX,pageY,offsetX,offsetY,modifiers
dblclick, contextmenu (hipecore only)	button,pageX,pageY,offsetX,offsetY,modifiers
wheel (hipecore only)	deltaX,deltaY,deltaMode,modifiers (deltaMode: 0 = pixels, 1 = lines, 2 = pages)
Other events	0

button is 1 for the left mouse button, 2 for the middle and 3 for the right.

modifiers is always present, and is 0 when no modifier keys are held. Otherwise it's the sum of: 1 = Shift, 2 = Alt, 4 = Ctrl, 8 = Meta. For example, Ctrl+S gives a keydown detail of 83,4, and Shift+Tab gives 9,1. On the keyup of a modifier key itself, that modifier is already released, so it isn't included.

With the Qt5WebKit backend, dblclick, contextmenu, wheel and other events report only the DOM's event.which value.

Notes

Events that can arrive in fast bursts are combined before they are sent, so that a client isn't flooded with them. Each request gets its own combined stream. Such events are sent a few tens of milliseconds after they occur, at most:

• mousemove, scroll and resize: only the latest event of a burst is sent, since each one describes the current state.
• wheel: the deltas of a burst are added up and sent as one event, so no wheel travel is lost. For example, a quick spin of six notches of 60 pixels each arrives as a single event with a deltaY of 360. Events with a different deltaMode or modifier mask (e.g. Ctrl pressed during the spin) aren't combined with each other. Clients should therefore act on the size of the deltas (for example, zoom in proportion to the wheel travel) rather than treating each event as one notch: a single notch of some mice also arrives as several smaller deltas, which may or may not be combined.

The event detail provided in arg[1] may be inadequate for what you require. In this case, it may be necessary to use HIPE_OP_GET_ATTRIBUTE in order to obtain further information about how the tag has changed following the user's interaction.

Instruction set reference

HIPE_OP_EVENT_CANCEL

Send this instruction to the server to stop receiving events of a certain type on the specified element

• location: The element for which you would like to stop receiving a particular type of event.
• arg[0]: The type of event to stop receiving.
• arg[1]: Pass "1" to request a reply from the Hipe server. Otherwise pass nothing if no reply is needed. If "1" is passed, Hipe will send the same instruction back to the client to acknowledge that the event has been cancelled. (This can be useful if a client application needs confirmation that no further events with a particular type/location/requestor will be received in order to safely free values from memory.)

Notes

Cancelling removes every active request for that event type on the element. With the hipecore backend, which supports multiple listeners per event type per element, this includes all of them, whatever requestor values they were made with. The Qt5WebKit backend supports only one listener per event type per element, so there is only ever one request to remove. See HIPE_OP_EVENT_REQUEST.

Instruction set reference

HIPE_OP_EVENT_REQUEST

Send this instruction to the server to request notifications of a particular event on a particular element.

• location: The element for which you require event notifications.
• arg[0]: The type of event (see notes below).
• arg[1]: Optional (hipecore only). Which of these events should have their default action cancelled, e.g. to stop the Tab key moving the keyboard focus, or the mouse wheel scrolling. See "Cancelling default actions" below.
• requestor: user value to be passed back to the client each time the requested event arises.

Notes

For specifying the type of event, names of events are the same as their HTML/Javascript equivalents, except without the "on" prefix.

For example, to get reports of click events, you would pass "click" in arg[0] (not "onclick"), or for a key pressed down event you would pass "keydown" (not "onkeydown" as in HTML/Javascript).

Each event is reported with HIPE_OP_EVENT, which lists the detail reported for each event type, including which modifier keys (Shift, Alt, Ctrl, Meta) were held.

keyup and keydown events can be requested on a child iframe: they report keys pressed while the keyboard focus is inside the client occupying that frame (or inside any frame nested within it). The events carry the requestor value of your most recent request for that event on that iframe, and each key is reported once: requesting keydown or keyup again on the same iframe replaces the requestor rather than adding another report. The detail includes the modifier mask as for any other keydown or keyup event. The same keys also reach your body element, so if you have requested keydown or keyup on the body as well, you receive both reports. keypress events remain within the iframe and don't propagate out to the parent client.

How many requests can be active for the same event on the same element depends on the display server backend:

• hipecore supports multiple listeners per event type per element. Each request adds a new listener, and all of them stay active, so each event is reported once per request. This happens even if the requests use the same requestor value. For example, if you request the click event on the same button twice, each click on that button is reported twice.
• Qt5WebKit supports only one listener per event type per element. A new request replaces the previous one, so if you request the click event on the same button twice, only the second request applies.

To replace a request in a way that works on both backends, cancel it with HIPE_OP_EVENT_CANCEL before requesting the event again.

Cancelling default actions

With the hipecore backend, arg[1] can cancel an event's default action: what would happen without your app (a key typing text or moving the focus, the wheel scrolling, a right-click opening the edit menu, and so on). The event is cancelled as it happens, before the default action, so the decision is made from rules given in advance. You still receive the event as usual, and can then do something else instead (e.g. indent a line when Tab is pressed).

arg[1] is a list of rules separated by ;. An event is cancelled if it matches any of them. Each rule is code,modifiers, written like the event's detail in HIPE_OP_EVENT:

• code: the keyCode for keydown and keyup, the character code for keypress, or the mouse button (1 = left, 2 = middle, 3 = right) for mouse events.
• modifiers: the modifier mask (1 = Shift, 2 = Alt, 4 = Ctrl, 8 = Meta, added together), which must match exactly. 0 means no modifier keys held.

* matches anything, and ,modifiers can be left out to match any modifiers. So * alone cancels every event. A rule with a specific code or modifier mask never matches an event that doesn't have one: e.g. wheel events have no code (only * matches), and events such as input or scroll have neither. Rules that can't be read are ignored.

Event	arg[1]	Cancels
keydown	9,0;9,1	Tab and Shift+Tab (the focus doesn't move)
keydown	83,4	Ctrl+S
keydown	9	Tab with any modifier keys
wheel	*,4	Ctrl+wheel (plain wheel still scrolls)
mousedown	1	left-button presses (no focus change or text selection)
contextmenu	-	nothing: the edit menu still opens

Notes:

• The rules apply to events on the element and on everything inside it, so put them on the smallest element that needs them. For example, cancelling Tab on the body would also stop Tab working in any text box in your app.
• Cancelling a keydown also stops the key typing any text (its keypress doesn't happen) and stops any editing command for it (e.g. Ctrl+A selecting everything). Text entered through an input method (e.g. with dead keys) isn't affected.
• Cancelling doesn't depend on the client: it happens even while your app is busy. But your response to the event arrives later than the key itself, so a key the user types straight afterwards may take effect first.
• A new request for the same event on the same element replaces its rules (an empty arg[1] or - removes them), although events are still reported once per request. HIPE_OP_EVENT_CANCEL removes them.
• contextmenu: an empty arg[1] cancels every right-click, as requesting this event always has, so your app replaces the framing manager's edit menu. Use - to be told about right-clicks and still show the edit menu.
• Rules on a child iframe don't affect the child client's own events, and a client can't cancel keys that its framing manager relies on (such as Esc and the function keys): these still reach it.
• With the Qt5WebKit backend, arg[1] is ignored (contextmenu is always cancelled).

Instruction set reference

HIPE_OP_FIFO_ADD_ABILITY

This instruction is usually sent by a client to its parent frame (the framing manager for the desktop environment) to indicate that the client may be called on to carry out a particular action. This means the client can act as a FIFO host when the user selects the listed ability.

• location: Sending a message: A value of 0 (corresponding to the body element of the client frame) means the message should be sent to the direct parent of this client.
  Receiving a message: A location value corresponding to a child frame means the message came from that client.
• arg[0]: The name of the ability offered. For example "Save", "Print", "Open".
• arg[1]: The set of supported access modes. For example, "rwa". See below.
• arg[2]: Additional line-separated metadata including extended description and supported file types.

Name of ability

The name of the ability serves two purposes: (1) it is shown to the user to help the user decide which host function to select when exchanging data with another application. (2) it is used to identify the particular ability within Hipe (together with the client ID).

If a client application offers multiple host abilities, each must have a unique name.

The name of the ability is case sensitive.

FIFO access modes

The following specifiers can be used to control how data is read or written to the FIFO stream. The direction of transfer is specified from the client's point of view.

Typically, a host should not be expected to implement all of these access modes. For example, it might not be appropriate to save a document to a scanner or to load a file from a printer, but reading a scanned page from a scanner and sending it to a printer is more reasonable. Likewise, for some sources of data, it is only sensible (or technically feasible) to transfer the data sequentially from beginning to end, while a database system might allow random access from any position within a file.

Specifier	Description
r	Read sequentially from the beginning of the data. Data to be read should already exist at the host.
R	Read data from a specified position, rather than from the start of the file. Data to be read should already exist at the host.
w	Write new data sequentially from the beginning, discarding all existing data held by the host.
W	Write data from a specified position, overwriting a section of existing data held by the host.
a	Write data by appending it to the end of the existing data held by the host. Existing data is preserved. If there is no pre-existing data in the resource, data will be written from the beginning.
n	Make a new, empty directory inside a directory resource. No data is transferred.
m	Move or rename an entry inside a directory resource. Fails if something already has the new name. No data is transferred.
M	As m, but if a file already has the new name, it is replaced. No data is transferred.
d	Delete an entry inside a directory resource: a file, or an empty directory. No data is transferred.

Notes on access modes

• If the initial mode used for a resource is r or R, it is expected that the host will select an existing resource (ideally containing existing data) rather than creating a new empty resource. For example, if the user wishes to open a file on a drive for viewing, the file manager should not prompt the user to create a brand new file for saving to.
• The R and W modes effectively work as random access modes because they allow the client to select a position to read or write from. (For example, write an entry 215 bytes into the file.) This is useful for database-style storage where the file is organised into fixed-length sections and the correct lookup position can be figured out using knowledge of the file format. However, not all hosts may support such functionality. Regular file seek operations (e.g. lseek, fseek and rewind in C) are not supported by FIFOs and cannot be used. Instead, the position within a file or resource can be manipulated by closing and reopening the resource in the desired position using the appropriate hipe instructions – which communicates the request to the host.
• If a host offers R and/or W functionality, it should also list support for the corresponding r and w equivalent(s) which are effectively subsets of this functionality with a seek position of 0. The reason to list both is because a client may specify sequential access as the minimal required access code, even though it is capable of instead using random access if available.
• The modes n, m, M and d change what a directory resource contains and transfer no data. They are described under HIPE_OP_FIFO_OPEN. A host lists the ones it supports along with its other access modes, so a client can offer the user only the operations the host can carry out. A host that offers M should also offer m.

Order of access modes

The order of access mode specifiers is significant: where appropriate, the expected initial access mode should be specified first. For example, "rw" means that data will initially be read, and may be written back to later, while "wr" means that fresh data will be written from the start. An initial access mode of r or R means that the host acts (initially at least) as a source of data rather than a destination.

An example of "read then write" ordering would be a file which is opened for editing. First the editor must read the file to load its contents. Later the user may save changes back into the file.

Metadata about ability

The metadata argument is used to specify what sort of data the host can work with. This information spans multiple lines, separated by a newline character (in C, \n is used to represent a newline character).

Line	Description	Example
1	Description of ability	Get image from scanner
2	Preferred file format pattern	pdf:Portable document format
3	Alternative file format pattern (optional)	jpg;jpeg;gif:Graphical image
...	Additional lines for other file formats as necessary.	txt:scan to text

Where multiple file formats are supported, the filename extension normally associated with that format is used. For example, gif means a GIF image format. To prevent ambiguity (in cases where two very different file formats might share a common filename extension), a description is added. The description is not used to identify the file, but is displayed to the user so the user can exclude inappropriate files where prompted to select a file from disk. The client application will probably use a different description for the same file format. Since descriptions are intended for user information only and are subject to be altered in transit, descriptions alone cannot be used to differentiate between different file formats with the same extension. (Therefore each extension should only be listed once in the entire metadata argument).

We use Windows-style file extensions to filter file formats as they are well-understood in practice. Why are MIME types not used? Whilst MIME types were envisaged as a way to remove ambiguity from file format types, they tend to produce less clarity than confusion in reality.

The file type (extension) should be in lowercase, and should not include the *. prefix often used in Windows where the file type follows a dot at the end of each filename. It is worth noting that the host may not organise files with filename extensions, but may use a different scheme.

Some FIFO-hosts can handle any file format. In this case, a single * is specified to indicate a single file of any type. (Note, the * character does not work for matching filename patterns, and should be used by itself only.)

Directory resources

In some cases, the resource is not a single file-style resource, but a directory resource (the client can access multiple files in the directory, which are indexed by filenames). This is useful in cases where a client works on an entire project rather than a single file. To specify that any directory is allowed, use a single forward slash / for the type. To require a directory to have a certain filename extension (e.g. to denote an application, python project, etc.) place the slash after the type, e.g. pro/ would match a directory named myproject.pro/. Note that 'directories' here are an abstract resource. It may not be a physical directory on disk, but something with a directory-like structure, like a set of database tables.

Notes

Abilities are added by FIFO 'hosts' (applications that provide access to a FIFO resource) and the framing manager is expected to maintain a list of these. The list is not given to FIFO-client applications, which never see the name of the ability they access. The framing manager mediates the connection by displaying the ability for the user to select, after which the FIFO-client receives the filename of the FIFO resource.

Instruction set reference

HIPE_OP_FIFO_CLOSE

Sent by either end of a FIFO relationship (and relayed to the other end by the framing manager) to say that the sender has finished with the current transfer, and whether the transfer succeeded at its end. The resource still exists and may be opened again later.

Each end sends this instruction once per transfer. The end that finishes first sends it, and the other end closes the FIFO at its own end and answers with its own HIPE_OP_FIFO_CLOSE. The transfer is over when both have been sent, and the resource is then ready to be opened again, in a different mode if required.

• location: Sending a message: A value of 0 (corresponding to the body element of the client frame) means the message should be sent to the direct parent of this client. A location corresponding to a child frame means send the message to the client connected to that frame. Receiving a message: A value of 0 (corresponding to body element) means the message came from the direct parent of this frame. A location value corresponding to a child frame means the message came from that client.
• arg[0]: The FIFO resource ID string that was provided to the client when the resource was made available through a HIPE_OP_FIFO_RESPONSE message.
• arg[1]: The outcome of the transfer at the sender's end. Empty if it ended normally. Otherwise the transfer failed at the sender's end, and this is the reason, as text that can be shown to the user (for example No space left on device).

Who sends it, and what the outcome means

Situation	What is sent	What the receiver should do
The client has finished writing.	The client sends HIPE_OP_FIFO_CLOSE with arg[1] empty, after writing all its data and closing its end.	The host reads the remaining data, stores it, and answers as in the next two rows.
The host has stored what the client wrote.	The host answers with arg[1] empty.	The client can report the data as saved.
The host could not store what the client wrote (disk full, no permission...).	The host answers with the reason in arg[1].	The client reports that saving failed, and can show the reason.
The client gives up part-way through writing.	The client sends HIPE_OP_FIFO_CLOSE with a reason in arg[1].	The host discards what it received, leaving the stored data as it was, and answers.
The host has finished writing what the client asked to read.	The host sends HIPE_OP_FIFO_CLOSE with arg[1] empty, after writing all the data.	The client reads the remaining data and answers.
The host fails part-way through writing (the file became unreadable...).	The host sends HIPE_OP_FIFO_CLOSE with the reason in arg[1].	The client discards what it received, reports the failure, and answers.
The client needs no more of what it is reading.	The client sends HIPE_OP_FIFO_CLOSE with arg[1] empty.	The host stops writing and answers.
The host cannot do what a HIPE_OP_FIFO_OPEN asked (no such file, no permission...).	The host sends HIPE_OP_FIFO_CLOSE with the reason in arg[1], in place of relaying the HIPE_OP_FIFO_OPEN back.	The client closes its end and reports the failure. No transfer was opened, so it sends no answer.

Notes

A client that writes data should treat it as saved only once the host's answer arrives with arg[1] empty. Until then the host may still fail to store it.

A program should act only on whether arg[1] is empty. The text itself comes from the other application and is meant for the user; its wording is not defined.

A HIPE_OP_FIFO_DROP_PEER for the resource that arrives while a transfer is open also ends the transfer, as a failure: the other application has gone or has ended the relationship. An application should also give up on a transfer whose other end stays silent for too long.

Applications written before arg[1] was defined send it empty and ignore it when receiving, so they report every transfer as successful.

Like the other FIFO instructions, this one is passed between frames without the Hipe display server interpreting its contents.

Instruction set reference

HIPE_OP_FIFO_DROP_PEER

In a client-host relationship, this instruction is used when a client wishes to tell a host that access to the FIFO resource will no longer be required (for example, the user has closed a certain document that was being accessed through the resource).

In the normal use case, the client would send this instruction to location 0 (to be picked up by the parent frame), and the parent frame on receiving the instruction should pass it on to the corresponding host frame.

• location: Sending a message: A value of 0 (corresponding to the body element of the client frame) means the message should be sent to the direct parent of this client. A location corresponding to a child frame means send the message to the client connected to that frame. Receiving a message: A value of 0 (corresponding to body element) means the message came from the direct parent of this frame. A location value corresponding to a child frame means the message came from that client.
• arg[0]: The FIFO resource ID string that was provided to the client when the resource was made available through a HIPE_OP_FIFO_RESPONSE message.

Notes

Either end of the peer relationship can initiate terminating the FIFO relationship, however the host is the end responsible for actually deleting the shared FIFO resource on disk. Whichever end initiates dropping the peer should send this instruction via the framing manager to the opposite end of the relationship.

After receiving this message, the FIFO-host should discard and clean up the shared FIFO resource. (Or if the host is the initator of the drop peer request, it should delete the FIFO resource at the same time as it sends the message to the client.

After this instruction is sent, it should be assumed that the peer relationship no longer exists and no further instructions referencing that that particular FIFO resource should be sent through hipe.

Instruction set reference

HIPE_OP_FIFO_GET_PEER

Requests (or handles a request) for a program to begin communications with a FIFO peer that has the required ability. This leads to the creation of a FIFO resource between the two applications.

There is a one-to-many relationship between a supported ability and the number of peers that may be making use of that ability.

• location: Sending a message: A value of 0 (corresponding to the body element of the client frame) means the message should be sent to the direct parent of this client. A location corresponding to a child frame means send the message to the client connected to that frame. Receiving a message: A value of 0 (corresponding to body element) means the message came from the direct parent of this frame. A location value corresponding to a child frame means the message came from that client.
• requestor: An optional user-defined value that will be received back by the client when the HIPE_OP_FIFO_RESPONSE arrives. A complex client program with multiple sources for requests should use unique requestor values for different requests to ensure that responses can be dealt with without ambiguity.
• arg[0]: A suggested default 'filename' to be given to the resource, for example untitled picture. The FIFO-host may or may not use this suggestion where a new file is to be created. Some FIFO-hosts may use this name to identify the document for the user's benefit. This filename should not include the filename extension (nor a trailing slash for directories) as this information is provided separately through arg[2]. May be blank under certain circumstances (see Notes below).
• arg[1]: Minimal required access mode(e.g. r), optionally followed by a space, and the full set of supported access modes that the FIFO-client can take advantage of. See below.
• arg[2]: Metadata formatted using the same convention as that given by the FIFO-host in HIPE_OP_FIFO_ADD_ABILITY, except from the client's point of view. The metadata describes the function the client requires and the file formats the FIFO-client can work with. The framing manager attempts to match the client to a host based on both having supported file types in common.
• arg[3]: Initially blank when sent from a client, however the framing manager should place the unique name of the chosen ability in this argument when it relays the instruction to the host selected by the user.

FIFO access modes

The following specifiers can be used to control how data is read or written to the FIFO stream. The direction of transfer is specified from the client's point of view.

Typically, a host should not be expected to implement all of these access modes. For example, it might not be appropriate to save a document to a scanner or to load a file from a printer, but reading a scanned page from a scanner and sending it to a printer is more reasonable. Likewise, for some sources of data, it is only sensible (or technically feasible) to transfer the data sequentially from beginning to end, while a database system might allow random access from any position within a file.

Specifier	Description
r	Read sequentially from the beginning of the data. Data to be read should already exist at the host.
R	Read data from a specified position, rather than from the start of the file. Data to be read should already exist at the host.
w	Write new data sequentially from the beginning, discarding all existing data held by the host.
W	Write data from a specified position, overwriting a section of existing data held by the host.
a	Write data by appending it to the end of the existing data held by the host. Existing data is preserved. If there is no pre-existing data in the resource, data will be written from the beginning.
n	Make a new, empty directory inside a directory resource. No data is transferred.
m	Move or rename an entry inside a directory resource. Fails if something already has the new name. No data is transferred.
M	As m, but if a file already has the new name, it is replaced. No data is transferred.
d	Delete an entry inside a directory resource: a file, or an empty directory. No data is transferred.

Notes on access modes

• If the initial mode used for a resource is r or R, it is expected that the host will select an existing resource (ideally containing existing data) rather than creating a new empty resource. For example, if the user wishes to open a file on a drive for viewing, the file manager should not prompt the user to create a brand new file for saving to.
• The R and W modes effectively work as random access modes because they allow the client to select a position to read or write from. (For example, write an entry 215 bytes into the file.) This is useful for database-style storage where the file is organised into fixed-length sections and the correct lookup position can be figured out using knowledge of the file format. However, not all hosts may support such functionality. Regular file seek operations (e.g. lseek, fseek and rewind in C) are not supported by FIFOs and cannot be used. Instead, the position within a file or resource can be manipulated by closing and reopening the resource in the desired position using the appropriate hipe instructions – which communicates the request to the host.
• If a host offers R and/or W functionality, it should also list support for the corresponding r and w equivalent(s) which are effectively subsets of this functionality with a seek position of 0. The reason to list both is because a client may specify sequential access as the minimal required access code, even though it is capable of instead using random access if available.
• The modes n, m, M and d change what a directory resource contains and transfer no data. They are described under HIPE_OP_FIFO_OPEN. A host lists the ones it supports along with its other access modes, so a client can offer the user only the operations the host can carry out. A host that offers M should also offer m.

Order of access modes

The order of access mode specifiers is significant: where appropriate, the expected initial access mode should be specified first. For example, "rw" means that data will initially be read, and may be written back to later, while "wr" means that fresh data will be written from the start. An initial access mode of r or R means that the host acts (initially at least) as a source of data rather than a destination.

An example of "read then write" ordering would be a file which is opened for editing. First the editor must read the file to load its contents. Later the user may save changes back into the file.

Minimal vs desired access modes

An application might be able to deal with a multitude of access modes (such as file seeking, reading and writing) but may also be able to make do with a minimal set of access modes. For example, a text editor might be capable of opening a file for reading and writing. However, in the worst case, loading a file read-only may be supported too. In this case, arg[1] might be specified as: "r rw"

Notes

In certain cases a peer relationship needs to be set up to transfer a group of files that are not physically located in a particular named directory. For this case, request a peer using a blank filename in arg[0] and the directory type (/) specified via arg[2]. The treatment of a group of files is the same as a directory of files except that the lack of a filename tells the peer that they should not be copied into a new directory but should be placed within a given location.

Instruction set reference

HIPE_OP_FIFO_OPEN

In a client-host relationship between two applications, the client sends this instruction to the framing manager to coordinate opening a FIFO resource which has previously been granted to it through a HIPE_OP_FIFO_RESPONSE instruction. A framing manager that supports FIFO-based communication among applications is then required to relay the instruction to and from the host application.

When the host receives this instruction, it is required to open the FIFO resource at its end in the complementary direction of transfer, and relay the same HIPE_OP_FIFO_OPEN instruction back to the client to acknowledge that the resource is now likely to be open at both ends and ready to be used. The FIFO resource ID string (FIFO path) is used to uniquely identify the FIFO resource on the system, and the framing manager should use this to identify where to relay the acknowledgement back to when the host retransmits it.

This does not mean establishing a shared resource (done through HIPE_OP_FIFO_GET_PEER), but beginning a transfer in a particular direction. The same resource may be opened or closed multiple times in the lifetime of a FIFO resource.

• location: Sending a message: A value of 0 (corresponding to the body element of the client frame) means the message should be sent to the direct parent of this client. A location corresponding to a child frame means send the message to the client connected to that frame. Receiving a message: A value of 0 (corresponding to body element) means the message came from the direct parent of this frame. A location value corresponding to a child frame means the message came from that client.
• arg[0]: The FIFO resource ID string that was provided to the client when the resource was made available through a HIPE_OP_FIFO_RESPONSE message.
• arg[1]: The access mode that the client will be using.
• arg[2]: Depends on the access mode. For W and R modes, specifies starting position and optionally total length of the transfer (see below). For m and M modes, the entry's new name (see "Changing the contents of a directory" below). Not used in other modes.
• arg[3]: If directory index mode is supported, this argument contains the name of the file to be opened, or of the entry to be made, moved or deleted.

Synchronising opening a FIFO resource at both ends of transfer

A FIFO is a special file in a UNIX-style environment that does not buffer any data on the disk. One end is written to (in one application) while the other end is read from (in another application). In the Linux programming environment, the C open() and close() function are normally used to tell the operating system to open a FIFO resource. Often a Hipe application would open a FIFO in 'nonblocking' mode which means an application will not freeze up if the other end of the transfer is too slow to process data or open the resource. However this means that the application that is going to read from the FIFO must open its end of the FIFO first before the other end begins writing. If the reader has not opened the FIFO yet, any data written into the FIFO will have nowhere to go and will be discarded by the operating system. So to avoid data loss, both applications must cooperate to ensure the reading end is opened first.

1. The FIFO resource should initially be in a closed state at both ends. (If in an open state, the HIPE_OP_FIFO_CLOSE instruction is used to coordinate closing both ends.
2. The client opens its end of the FIFO resource for either reading or writing depending on the mode being used, but does not actually begin reading or writing yet.
3. The client should then send a HIPE_OP_FIFO_OPEN instruction to location 0 (which then goes to the parent frame/framing manager to be relayed to the host application that it shares the FIFO resource with)
4. The host application receives the HIPE_OP_FIFO_OPEN instruction and opens the FIFO at its end in the opposite direction to the mode requested by the client (e.g. if the client is reading, the host opens the FIFO for writing).
5. At this point the host updates its internal status and may begin reading/writing operations on the FIFO.
6. The host application sends the HIPE_OP_FIFO_OPEN instruction back in the other direction (by sending it to location 0). The arguments should be the same as those it received except that the file position should be updated as necessary to reflect the actual position in the file represented by the host (e.g. if the file is opened in append mode, the host should send back the position of the existing end of the file). The designated host application is always required to relay this instruction back regardless of the access mode. The framing manager relays it back to the client.
7. The client receives the HIPE_OP_FIFO_OPEN instruction, and begins reading/writing at its end.
8. At this point the client updates its internal status and may begin reading/writing operations on the FIFO.

If the host cannot open the resource as asked (for example the file no longer exists, or it has no permission), it does not relay the HIPE_OP_FIFO_OPEN back. It sends a HIPE_OP_FIFO_CLOSE for the resource with the reason in arg[1]. So a client waiting for the HIPE_OP_FIFO_OPEN to come back must also accept a HIPE_OP_FIFO_CLOSE (or a HIPE_OP_FIFO_DROP_PEER) for that resource: either means no transfer was opened, and the client should close its end. See HIPE_OP_FIFO_CLOSE for how the end of a transfer, and its success or failure, is reported.

Access mode

The access mode should be a single specifier from those that were granted to the client when the HIPE_OP_FIFO_RESPONSE instruction was relayed to the client. For example, if "w" access (write mode) was not granted, then "w" should not be specified. The access mode tells the host what it should now do.

FIFO access modes

The following specifiers can be used to control how data is read or written to the FIFO stream. The direction of transfer is specified from the client's point of view.

Typically, a host should not be expected to implement all of these access modes. For example, it might not be appropriate to save a document to a scanner or to load a file from a printer, but reading a scanned page from a scanner and sending it to a printer is more reasonable. Likewise, for some sources of data, it is only sensible (or technically feasible) to transfer the data sequentially from beginning to end, while a database system might allow random access from any position within a file.

Specifier	Description
r	Read sequentially from the beginning of the data. Data to be read should already exist at the host.
R	Read data from a specified position, rather than from the start of the file. Data to be read should already exist at the host.
w	Write new data sequentially from the beginning, discarding all existing data held by the host.
W	Write data from a specified position, overwriting a section of existing data held by the host.
a	Write data by appending it to the end of the existing data held by the host. Existing data is preserved. If there is no pre-existing data in the resource, data will be written from the beginning.
n	Make a new, empty directory inside a directory resource. No data is transferred.
m	Move or rename an entry inside a directory resource. Fails if something already has the new name. No data is transferred.
M	As m, but if a file already has the new name, it is replaced. No data is transferred.
d	Delete an entry inside a directory resource: a file, or an empty directory. No data is transferred.

Notes on access modes

• If the initial mode used for a resource is r or R, it is expected that the host will select an existing resource (ideally containing existing data) rather than creating a new empty resource. For example, if the user wishes to open a file on a drive for viewing, the file manager should not prompt the user to create a brand new file for saving to.
• The R and W modes effectively work as random access modes because they allow the client to select a position to read or write from. (For example, write an entry 215 bytes into the file.) This is useful for database-style storage where the file is organised into fixed-length sections and the correct lookup position can be figured out using knowledge of the file format. However, not all hosts may support such functionality. Regular file seek operations (e.g. lseek, fseek and rewind in C) are not supported by FIFOs and cannot be used. Instead, the position within a file or resource can be manipulated by closing and reopening the resource in the desired position using the appropriate hipe instructions – which communicates the request to the host.
• If a host offers R and/or W functionality, it should also list support for the corresponding r and w equivalent(s) which are effectively subsets of this functionality with a seek position of 0. The reason to list both is because a client may specify sequential access as the minimal required access code, even though it is capable of instead using random access if available.
• The modes n, m, M and d change what a directory resource contains and transfer no data. They are described under HIPE_OP_FIFO_OPEN. A host lists the ones it supports along with its other access modes, so a client can offer the user only the operations the host can carry out. A host that offers M should also offer m.

Starting position/transfer length

For modes r,w,a, the starting position is implied and the total length is never specified when opening the transfer. arg[2] is not used in these modes. If the client is reading, the host writes the whole contents down the FIFO pipe until the end of the file or close of transfer. If the client is writing (or appending), it writes as much as it needs to and then closes the transfer.

For modes R and W, the client is able to specify a starting position within the file for the host to seek to. If it is reading, it is also useful to specify a maximum number of characters required so that the host does not write everything to the end of the file if the client only requires a fixed number of characters (e.g. a customer record in a database).

For these modes arg[2] is specified as a starting position, optionally followed by a comma and a length in bytes, without spaces. A negative starting position means a distance from the end of the file, such that -1 in W mode is equivalent to a. A specified length of 0 is equivalent to omitting the length.

Directories

If the filename of the shared resource has a trailing slash /, this means the resource is treated as a directory, and filenames within the directory can be specified in arg[3] regardless of the access mode used. If no filename is specified here, the client can access the directory itself, which shall be formatted as follows:

[iso date] [iso date] [size] [accessmodes] [filename]\n

Note that for filenames within a directory, the filename extension should be included if present (e.g. a_photograph.jpg) since for clients that are capable of dealing with directories, Hipe does not filter client abilities by file type within a directory, only the type of the main directory itself.

Representing files within subdirectories

Many real-world directories also contain files within subdirectories. These should also be included in the same flat list (Hipe's FIFO interface treats all files within the base directory on the same footing regardless of how deep they are in a subdirectory hierarchy) however the subdirectory structure is preserved within the filename of each entry as follows.

• Each subdirectory is included in the list with a trailing slash at the end of the filename. For example, subdir/, or for a subdirectory within another, subdir/another_dir/.
• A file within a subdirectory is prefixed by its subdirectory path, for example a picture with filename something.jpg inside an img/ subdirectory would have its filename written as img/something.jpg.

Subject to what is sensible for each implementation, subdirectories are normally represented as separate items in the list regardless of whether they are empty or contain files. The presence of a trailing slash at the end of the filename indicates that the entry is a subdirectory. The size value given to a subdirectory is undefined and is not used, since there is no data to be read or transmitted through the FIFO from the subdirectory itself.

Changing the contents of a directory

Four access modes change what a directory resource contains, without transferring any data: n makes a new directory, m and M move or rename an entry, and d deletes one. A client may use only those the host granted it.

These work differently from a transfer. Neither application opens the FIFO. The client sends HIPE_OP_FIFO_OPEN and the host carries out the operation at once. The host does not relay the HIPE_OP_FIFO_OPEN back: it answers with a HIPE_OP_FIFO_CLOSE for the resource, whose arg[1] is empty if the operation was done, or says why it was not (see HIPE_OP_FIFO_CLOSE). The client sends no HIPE_OP_FIFO_CLOSE of its own. As with a transfer, the client must wait for the answer before opening the resource again.

Mode	arg[3]	arg[2]	What the host does	It fails if
n	The directory to make, e.g. img/thumbs/	Not used	Makes one new, empty directory.	The directory it would be made in doesn't exist, or something already has that name.
m	An existing entry, e.g. notes.txt	Its new name, e.g. old/notes-2019.txt	Gives the entry the new name, which may place it in a different directory of the resource. A directory keeps its contents.	The entry doesn't exist, the directory the new name is in doesn't exist, or something already has the new name.
M	As for m	As for m	As m, except that a file which already has the new name is replaced, in a single step: the new name refers to the old file's contents until it refers to the moved entry's, and is never missing.	As for m, except that a file with the new name is not a failure. It still fails if a directory has the new name, or if the entry being moved is a directory and a file has the new name.
d	The entry to delete	Not used	Deletes a file, or a directory that has nothing in it.	The entry doesn't exist, or it is a directory that still has entries in it.

Names are written as they appear in the directory's list: relative to the directory resource, and with a trailing slash for a directory (for m and M, in both the old and the new name).

m is the mode for renaming at the user's request: because it never replaces anything, a client can ask the user before anything is lost. M lets a client save a file safely, by writing the new contents under a temporary name and then moving that over the original.

A host may include m, M and d in an entry's access modes in the directory's list to show that the entry may be moved or deleted, and n in a directory's access modes to show that directories may be made in it. The client should be prepared for the host to refuse all the same.

The directory's list is not updated for the client. After a change, the client reads the list again if it needs the new contents.

What deleting means is up to the host. For example, a file manager might move the entry to a wastebasket of its own. In all cases the entry is no longer in the directory resource afterwards. A host should also refuse names that would reach outside the directory it is sharing.

Notes

Hipe is just the messenger here. It does not open anything, but merely relays the request to the client. The access mode and arguments tell the FIFO-host what to do with the shared resource. Both host and client should then open and access the resource using regular file read/write operations.

This instruction works in the same way as HIPE_OP_MESSAGE in that the instruction contents are passed to a child or parent frame without interpretation of the contents by the Hipe display server. This means that applications are required to supply and/or read the specified arguments in order to understand one another, but the Hipe display server is not itself involved in interpreting them.

Instruction set reference

HIPE_OP_FIFO_REMOVE_ABILITY

Where an application is capable of acting as a host in a FIFO relationship, this instruction provides a way for the application to notify the framing manager that it should no longer be called on to perform a particular action.

• location: Sending a message: A value of 0 (corresponding to the body element of the client frame) means the message should be sent to the direct parent of this application.
  Receiving a message: A location value corresponding to a child frame means the message came from that application.
• arg[0]: The name of the ability (the unique name that was specified when the ability was added).

Notes

An application can only remove an ability that it previously added.

There's no guarantee that an application will remove all its abilities before it terminates. So a supporting framing manager should clean up outstanding abilities for applications that terminate.

Instruction set reference

HIPE_OP_FIFO_RESPONSE

In a client/host relationship between applications, this instruction is used to relay a message from the host to the client (via the framing manager), whereby the host either rejects the peer relationship, or informs the client of the path to the shared FIFO resource.

The framing manager will receive this message from a FIFO-host and is responsible for relaying it back to the corresponding FIFO-client (which made the initial HIPE_OP_FIFO_GET_PEER request).

The framing manager should also respond to this message by returning active focus back to the FIFO-client, since the FIFO-host will have been brought to the foreground by the framing manager as part of the user-selection process.

• location: Sending a message: A value of 0 (corresponding to the body element of the client frame) means the message should be sent to the direct parent of this client. A location corresponding to a child frame means send the message to the client connected to that frame. Receiving a message: A value of 0 (corresponding to body element) means the message came from the direct parent of this frame. A location value corresponding to a child frame means the message came from that client.
• requestor: The FIFO-host should respond with the same requestor value it received when it got the HIPE_OP_FIFO_GET_PEER instruction. The framing manager should maintain (and substitute its own) requestor values as necessary so it can unambiguously determine which client to send responses back to. The framing manager should relay the same requestor back to the client as the client used when it sent the HIPE_OP_FIFO_GET_PEER request.
• arg[0]: On success, the absolute path to the FIFO resource that has been created by the FIFO-host. Since such paths are guaranteed to uniquely identify the FIFO on the system, the resource path is subsequently used by the framing manager to uniquely identify the peer relationship. A blank value indicates rejection (e.g. cancellation of the request by the user)
• arg[1]: On success, the set of access modes that has been made available to the FIFO-client. This should be a subset of the access modes requested by the FIFO-client.
• arg[2]: On success, the filename which the FIFO-host has assigned to the resource (for display to the user).
• arg[3]: On success, the file type (formatted the same as a line of metadata from HIPE_OP_FIFO_ADD_ABILITY).

Notes

A blank value for arg[0] always indicates rejection of the peer request, e.g. cancellation by the user. In this case the remaining arguments are superfluous.

Instruction set reference

HIPE_OP_FILE_RETURN

Sent to the client after the client requests a file (e.g. a snapshot of the frame contents).

• location: The element relevant to the requested file, if applicable.
• arg[0]: The contents of the file (on error, this will be empty).
• arg[1]: On success, empty. On error, a string stating the nature of the error (e.g. "File access error").

Notes

requestor carries the value of the instruction that requested the file.

Instruction set reference

HIPE_OP_FIND_RESULT

Sent to the client in reply to HIPE_OP_FIND_TEXT.

• location: The location given in the HIPE_OP_FIND_TEXT instruction.
• arg[0]: The number of matches found.
• arg[1]: The position of the selected match among them, counting from 1. 0 if nothing was found (or the search text was empty).
• arg[2]: "1" if the search wrapped round to reach the selected match (past the end, or past the start when finding backwards), otherwise "0".
• arg[3]: "+" if the search stopped at its limit of 1000 matches, so there may be more. Otherwise empty.

Notes

requestor carries the value of the HIPE_OP_FIND_TEXT instruction.

A search tool can show these values as e.g. "3 of 12", or "3 of 1000+" when arg[3] is "+".

Instruction set reference

HIPE_OP_FIND_TEXT

Finds text in the style of a web browser's 'find on page' feature. All matches are highlighted, and the next one is selected and scrolled into view. The server replies with HIPE_OP_FIND_RESULT.

• location: Where to search. 0 searches the client's whole document. An element searches that element's content. An <iframe> that the client owns searches the content of the child client's frame. Frames nested inside the searched content are searched too, in the order they appear in the document.
• arg[0]: The text to find. An empty string removes the highlighting from the searched content and selects nothing.
• arg[1]: Search options. Any combination of these letters, or empty for none:
  • b: find backwards, selecting the previous match instead of the next.
  • c: match case. Without it, the search ignores case.
  • w: whole words only. A match must begin and end at a word boundary.

Notes

The match selected is the first one after the current selection or text cursor within the searched content (or the last one before it, with b). If there's none, the search wraps round to the first (or last) match. If there's no selection there, the first (or last) match is selected. Sending the same instruction again therefore steps through the matches one by one. Any selection left in another frame within the searched content is removed, so the search always carries on from the latest match.

Keyboard focus doesn't move. A user can go on typing in a search box while the matches are being selected.

Each search replaces the highlighting within the searched content. Highlighting elsewhere (e.g. from a search of a different element) stays.

A client can only search its own content, including the frames of child clients it owns. It can't search the frame of its parent or of any other client.

At most 1000 matches are found. Beyond that, the reply's arg[3] is "+", and later matches aren't highlighted or reachable.

Text that can't be selected, because it has the style -webkit-user-select: none, isn't searched, since a match there couldn't be selected. Use this to leave out e.g. line numbers, or a layer that repeats text shown elsewhere. The style is inherited, and -webkit-user-select: text on a descendant makes its text searchable again. (The unprefixed user-select property isn't recognised by the hipecore backend.)

Text is matched as it is laid out (as HIPE_OP_GET_CONTENT mode 2 reads it), including text in form fields, but a match can't span two frames.

Appearance

With the hipecore backend, the highlighting is styled with the CSS ::search-text pseudo-element (from CSS Pseudo-Elements Level 4). It supports two properties:

• background-color: the highlight behind each match.
• color: the colour of the text within a match. If it isn't set, the text keeps its own colour.

The selected match is shown as the selection, so it's styled with ::selection instead.

The standard Hipe themes set ::search-text to suit their colours (e.g. black text on yellow). Without a rule, matches get a translucent yellow background and keep their own text colour, so they stay readable on light and dark backgrounds alike. For example, a theme or client can use:

::search-text { background-color: yellow; color: black; }

A client can override the theme for its own elements with a rule of its own (e.g. with HIPE_OP_ADD_STYLE_RULE). Each property is decided separately, so a client rule that sets only background-color still gets the theme's color: set both if the text colour matters.

A rule applies to the text directly inside the elements it selects, not to text inside their child elements: #editor::search-text doesn't style a match inside a <span> in the editor. To cover everything inside an element, include its descendants too:

#editor::search-text, #editor *::search-text { background-color: lime; color: black; }

A rule without an element selector, like the theme example above, applies everywhere.

color is also used where the text itself is invisible. For example, a code editor might have an editable layer with color: transparent above a syntax-highlighted copy of its text. There, color: black would draw matches in black over the copy, while a translucent background with color: transparent lets the copy's own colours show through:

#editor::search-text { background-color: rgba(255, 200, 60, 0.3); color: transparent; }

With the Qt5WebKit backend, the search always covers the whole top-level window, whatever location is. The options are ignored, nothing is selected, and the reply's values are all 0.

Instruction set reference

HIPE_OP_FRAME_CLOSE

Sent to a client frame (by the display server, or by a framing manager) to indicate that the user has requested a client be closed/terminated.

• location: 0 (body element) if receiving a request to close. If sending a close request to a child frame, use the location of that frame.
•     arg[0]: Send an empty argument to disconnect a child frame's client from the display server by force (the client will not receive a HIPE_OP_FRAME_CLOSE instruction, but will instead be immediately disconnected and see HIPE_OP_SERVER_DENIED when it tries to obtain the next instruction). Or, send "1" to pass a HIPE_OP_FRAME_CLOSE instruction to the client, which should then react accordingly.
  Other non-empty arguments (e.g. "0") are presently undefined and should not be used.

Notes

You are required and expected to check for this instruction in your application, and respond in a reasonable way. It may not be appropriate for your application to terminate immediately - an acceptable response might be to ask the user for confirmation before discarding unsaved changes to a document.

Unless the close operation is forced, receiving this instruction will not actually close your application. You are required to handle the received instruction, to close the hipe client session and then terminate your application.

A forced close operation makes no guarantee that the client process will terminate; only that it will be removed from the display server. A poorly written application might continue to run in the background after it no longer has access to the display, although most ought to terminate.

Instruction set reference

HIPE_OP_FRAME_EVENT

Sent by the server to a client that manages one or more sub-frames to indicate an event affecting a direct sub-frame of this one. Frame events usually relate to a change in some information about the client in the subframe, rather than user interaction events happening within the subframe itself.

• location: The iframe element whose client triggered the event.
•     arg[0]: The type of client event.
•     arg[1]: Event detail (if applicable to a specific event type).
• requestor: The requestor value that was originally passed by this client, last time GET_FRAME_KEY was called on this iframe element.

Notes

Frame events are sent automatically once HIPE_OP_GET_FRAME_KEY has been requested for that frame.

Frame events are different to regular events in Hipe, and usually refer to a change in information about the client frame. The framing client doesn't get to specify which events should be listened for. All of the following events will be received if they occur

Event types are defined by macros in hipe_instruction.h, and have the prefix: HIPE_FRAME_EVENT_. These are represented by the raw char value of the first character in arg[0], and can be checked by evaluating the value of (received instruction).arg[0][0]

Client event types

arg[0]	arg[1]	arg[2]
HIPE_FRAME_EVENT_CLIENT_CONNECTED	Client title	Client process ID (or 0)
HIPE_FRAME_EVENT_CLIENT_DISCONNECTED	-	-
HIPE_FRAME_EVENT_TITLE_CHANGED	Client title string	-
HIPE_FRAME_EVENT_ICON_CHANGED	binary PNG image data	-
HIPE_FRAME_EVENT_COLOR_CHANGED	new foreground color	-
HIPE_FRAME_EVENT_BACKGROUND_CHANGED	new background color	-

Instruction set reference

HIPE_OP_FREE_LOCATION

Send this instruction to the display server to free server resources associated with a hipe_loc location handle the client application no longer needs.
Usually a location that has been deleted. After this operation, the tag may still exist on the screen but no longer has a location value connected to it.

• location: The location reference to be discarded.
• no arguments.

Notes

Do not free a location that still exists, if you have requested to receive events from that location and not cancelled those requests. Otherwise your application will receive events from undefined locations.

Location handle resources held by the display server are freed automatically when your application terminates. However, it is still polite to free unneeded location handles from time to time, especially if your application uses a lot of them.

Discard any local copies of hipe_loc values whenever you free them, since they are no longer valid for use in Hipe instructions.

Instruction set reference

HIPE_OP_GEOMETRY_RETURN

The display server sends this instruction out to a client application in reply to a request for geometry information. For example, a HIPE_OP_GET_GEOMETRY or HIPE_OP_GET_SCROLL_GEOMETRY request.

• location: The element for which geometry information was requested.
•   arg[0]: left edge co-ordinate in pixels
•   arg[1]: top edge co-ordinate in pixels
•   arg[2]: width in pixels
•   arg[3]: height in pixels

Notes

When the requested information is scroll geometry on a scrollable element, the left and top co-ordinates relate to the visible edges of the scrollable content relative to the edge of the scrollable element, while the width and height relate to the total dimensions of the scrollable content inside the scrollable element.

Instruction set reference

HIPE_OP_GET_ATTRIBUTE

Requests the current value of an HTML attribute for a particular element.

• location: the location of the element whose attribute to retrieve.
• arg[0]: the name of the HTML attribute.
• requestor: A user defined value to be passed back to the client in the return instruction.

Notes

After sending this instruction to the display server, the Hipe server process will send a HIPE_OP_ATTRIBUTE_RETURN instruction back to the client in reply.

Instruction set reference

HIPE_OP_GET_AUDIOVIDEO_STATE

Requests the current playback state of an <audio> or <video> element. The server responds with a HIPE_OP_AUDIOVIDEO_STATE instruction containing the element's current position, playback speed, playing/paused status and volume.

• location: The <audio> or <video> element to query.
• no arguments.

Notes

If the location isn't an <audio> or <video> element, the reply's four arguments are all empty.

Instruction set reference

HIPE_OP_GET_BY_ID

Looks up an element using its id attribute. The server then sends a HIPE_OP_LOCATION_RETURN instruction back to the client containing the location of the requested element.

• location: Not used
• arg[0]: The id attribute of the required element.

Instruction set reference

HIPE_OP_GET_CARAT_POSITION

Gets the current position of the text entry cursor in an element, or the range of text selected in it.

The display server responds with a HIPE_OP_CARAT_POSITION instruction. Its arg[0] is the character offset of the selection's anchor (where the selection starts) and its arg[1] is the offset of the selection's focus (where it ends, which is where the cursor is). They are equal when no text is selected, and arg[1] is less than arg[0] when the text was selected backwards. Offsets are counted as described on the HIPE_OP_CARAT_POSITION page.

• location: The element for which you require the current cursor position or selection range.

Notes

A cursor with no text selected is still a position: it is reported with both arguments equal, e.g. "3" and "3".

If the element contains neither the cursor nor selected text, arg[0] and arg[1] of the reply are both empty strings. A document has only one cursor or selection at a time, so this is the case when it is somewhere else: for example, the user has clicked into another editable element or on ordinary text elsewhere in the document, or nothing has been clicked or focused yet. It is also the case when a selection extends beyond the element, starting inside it and ending outside (this can't happen within a contenteditable element, whose editing selection stays inside it). input and textarea elements keep their own cursor position even when they don't have focus, so they always report one.

An empty string is distinct from "0", which is a cursor before the first character, so check the argument's length before converting it to a number (for example, atoi would return 0 for an empty string).

This works for the cursor in editable content and also for text the user has selected in non-editable content inside the element. To get the selected text itself, use HIPE_OP_GET_SELECTION.

Instruction set reference

HIPE_OP_GET_CONTENT

Requests the inner content of an element. The server responds with a HIPE_OP_CONTENT_RETURN instruction containing the requested content.

• location: The element whose content is being requested.
• arg[0]: Selects the format the content should be returned in:
  • 0 (or left blank) — unformatted plain text (default): all the text inside the element, exactly as stored, whether or not it is displayed. Line breaks are included only where the text itself contains them; line-break tags such as <br> are not converted.
  • 1 — content formatted as HTML.
  • 2 — content formatted as plain text as it is laid out (preserving line breaks etc., unlike mode 0): block elements and line-break tags such as <br> become line breaks. Elements styled display:none are left out (see notes).
  • 3 — the element's value attribute, rather than its inner content. This is needed for form elements such as <input> and <textarea>, where the user-entered text is held in value rather than as child content of the element.
  • 4 — the changes to the element's text (as mode 0 returns it) since this client's previous mode 4 request for the element, rather than the whole text. The first request returns the whole text. See HIPE_OP_CONTENT_RETURN for the reply. Modes 0 to 3 each return a plain copy of the content; mode 4 returns a richer reply that says what changed.
• arg[1]: For mode 4 only. Pass full to get the whole text and start again from it, instead of the changes. Do this after changing the element's text yourself (e.g. replacing it with HIPE_OP_SET_TEXT), since changes are reported relative to the text of the previous mode 4 reply, which your own copy no longer matches.

Notes

Mode 4 is for editors and other clients that keep their own copy of a large text. Reading only the changes saves transferring, decoding and comparing the whole text after every edit. Apply each reply to your copy (replace arg[2] characters at arg[1] with arg[0], or replace everything when arg[3] is full), and the copy stays exactly equal to the element's text. The display server keeps the last text it returned in mode 4 for each element (freed with the location, e.g. by HIPE_OP_FREE_LOCATION).

Modes 0 and 2 both return text whether or not it is currently visible on screen, including text in an element or frame that is hidden or has never been shown. They differ in what they include: mode 0 returns every piece of text inside the element, including text inside elements styled display:none, while mode 2 leaves those out. Text styled visibility:hidden is included by both.

Mode 0 is the most faithful way to read back text that must not be lost, such as the contents of an editor. For an editable element using contenteditable="plaintext-only", line breaks are stored as real newline characters, so mode 0 returns them.

On the Qt5WebKit backend, mode 2 may return an empty string for text that isn't displayed.

Instruction set reference

HIPE_OP_GET_FIRST_CHILD

Send to the server to request the location of the first child element inside the specified element.

• location: The location of the element whose first child element is required.
• requestor: User defined value to be passed back by the server when the child location is sent back in reply.

Notes

The server responds to this instruction by sending a HIPE_OP_LOCATION_RETURN instruction back to the client.

Instruction set reference

HIPE_OP_GET_FRAME_KEY

Send this instruction to requests a host key for a child frame (iframe element) at the specified location. Hipe will respond by sending a HIPE_OP_KEY_RETURN instruction back to the client. This key can then be passed to another application to allow that application to be hosted within that frame.

• location: The iframe you wish to allow another application and/or Hipe session to connect to.
• no arguments.

Instruction set reference

HIPE_OP_GET_GEOMETRY

Send this instruction to the display server to request the position and size of a particular element as it is laid out.

• location: The element for which you require geometry information
• No arguments.

Notes

The Hipe display server sends back a HIPE_OP_GEOMETRY_RETURN instruction, containing the left and top position coordinates, as well as the width and height of the specified element.

The left and top coordinates are in pixels, measured from the nearest containing element that is positioned (one whose position style is relative, absolute or fixed) or is a table or table cell, or from the top-left of the frame's content if there is none. They are not screen coordinates, and they do not change when the element, or anything containing it, is scrolled.

Instruction set reference

HIPE_OP_GET_LAST_CHILD

Send to the server to request the location of the last child element inside the specified element.

• location: The location of the element whose last child element is required.
• requestor: User defined value to be passed back by the server when the child location is sent back in reply.

Notes

The server responds to this instruction by sending a HIPE_OP_LOCATION_RETURN instruction back to the client.

Instruction set reference

HIPE_OP_GET_NEXT_SIBLING

Send to the server to request the location of the element that follows after the current element on the same level.

• location: The location of the element whose next sibling is required.
• requestor: User defined value to be passed back by the server when the sibling location is sent back in reply.

Notes

The server responds to this instruction by sending a HIPE_OP_LOCATION_RETURN instruction back to the client.

Instruction set reference

HIPE_OP_GET_PREV_SIBLING

Send to the server to request the location of the element that follows immediately before the current element on the same level.

• location: The location of the element whose previous sibling is required.
• requestor: User defined value to be passed back by the server when the sibling location is sent back in reply.

Notes

The server responds to this instruction by sending a HIPE_OP_LOCATION_RETURN instruction back to the client.

Instruction set reference

HIPE_OP_GET_RANGE_GEOMETRY

Requests where a range of text in an element appears on screen, as one rectangle per line, or where a text cursor appears. This is useful for placing something next to the cursor or a piece of text (such as a completion list or a tooltip), or for highlighting text.

• location: The element containing the text.
• arg[0]: The character offset where the range starts.
• arg[1]: The character offset where the range ends. If empty, the request is for the position of a cursor at arg[0]. If both arguments are empty, the request is for the element's actual text cursor (the end of the selection where the cursor is), if the cursor or selected text is in the element.

The display server responds with a HIPE_OP_RANGE_GEOMETRY instruction.

Notes

Offsets are counted exactly as for HIPE_OP_CARAT_POSITION: in characters, in the element's value for input and textarea elements and otherwise in its text as laid out (the text HIPE_OP_GET_CONTENT returns in mode 2). Negative offsets count from the end: -1 is the position after the last character. For example, "0" and "-1" request the whole text. The order of the two offsets doesn't matter.

To find where the cursor would be drawn at a given offset without moving it, give just arg[0].

This instruction needs the hipecore display server backend. With the Qt5WebKit backend, the reply's arg[0] is always empty.

Instruction set reference

HIPE_OP_GET_SCROLL_GEOMETRY

Send this instruction to the display server to request the scroll position geometry of content within a particular scrollable element as rendered on screen.

• location: The scrollable element for which you require the current scroll position information.
• No arguments.

Notes

The Hipe display server sends back a HIPE_OP_GEOMETRY_RETURN instruction, containing the scroll position of the content inside the scrollable element at its left and top edge, as well as the total width and height of the scrollable content inside the element.

Instruction set reference

HIPE_OP_GET_SELECTION

Gets the current user-selected text in the document (if the user has selected any content) and requests the server to send back a HIPE_OP_CONTENT_RETURN instruction. The server sends back an instruction even if there is no selection: in this case a blank string is sent in the reply instruction.

• location: Not used. This instruction applies to the whole document.
• arg[0]: Pass "0" here (or leave empty) to request the contents of the selection in the client's own frame. Pass "1" from a top-level frame to request the global selection; meaning that the selected text is returned even if it is within a child frame of the requesting client.

Notes

If a client that does not occupy a top-level frame attempts to ask for the global selection, a blank selection "" is always returned. This is a security feature to prevent clients from snooping on other client frames.

Instruction set reference

HIPE_OP_GET_SRC

Reads back the data of an img element, or the contents of a canvas, as a file. The display server replies with HIPE_OP_SRC_RETURN.

This instruction needs the hipecore display server backend. With the Qt5WebKit backend the reply is always an error.

• location: the img or canvas element to read from.
• arg[0]: for a canvas only, the format wanted: "png" (the default) or "pdf". Not used for an img.

Element	What is returned
img	The bytes most recently given to it with HIPE_OP_SET_SRC, unchanged, with their mime type.
canvas	A picture of what is currently drawn on it. As "png", an image of the canvas's size in pixels. As "pdf", a one-page document with no margins whose page is the size of the canvas at 96 pixels to the inch, which is convenient for printing.
audio, video and other elements	Nothing: the reply is an error. A client that needs a media file again should keep its own copy.

Notes

The "pdf" of a canvas contains the same pixels as the "png": a canvas holds a picture, not the shapes that were drawn. To capture a whole frame, use HIPE_OP_TAKE_SNAPSHOT.

Instruction set reference

HIPE_OP_GET_STYLE

Requests the resolved value of a CSS style property on a particular element - i.e. the actual value in effect once the display server applies cascading and inheritance, not just whatever (if anything) happens to be set directly on the element itself. Use this instead of HIPE_OP_GET_ATTRIBUTE with an attribute name of "style" when the property you want might only be in effect via an inherited or cascaded rule - for example, a background colour coming from a loaded theme stylesheet rather than a literal style="..." written onto the element.

• location: the location of the element whose style to resolve. 0 for the client's own <body> element.
• arg[0]: the name of the CSS property (e.g. "background-color", "color").
• requestor: A user defined value to be passed back to the client in the return instruction.

Notes

After sending this instruction to the display server, the Hipe server process will send a HIPE_OP_STYLE_RETURN instruction back to the client in reply.

This instruction does not retry or block waiting for a layout pass to complete. If the element hasn't actually been rendered yet, or the property name given isn't a CSS property the display server recognises, the value returned may be an empty string - if that matters for your use case, retry the request again after a short delay.

Instruction set reference

HIPE_OP_GET_X11_XID

Turns an object element into a place where the window of an X11 application can be embedded. The display server creates an X11 window at the element's position and keeps it at the element's position and size from then on. It replies with HIPE_OP_X11_XID_RETURN, which carries the window's XID.

• location: the object element to embed into.
• No arguments.

Notes

The client does the embedding itself: once it has the XID, it reparents the other application's window into it over its own connection to the X server (for example with XReparentWindow).

The embedded window is a real X11 window and is drawn above everything in the Hipe frame, so nothing in the document can be placed over it. To hide it for a while (for example, to show a menu or a dialog where it is), give the object element the style visibility: hidden. The window reappears when the element is made visible again.

Don't hide it with display: none. That destroys the X11 window, and the application's window embedded in it is destroyed too. Making the element visible again creates a new, empty window with a new XID.

The reply's XID is 0, and nothing is created, if:

• the element isn't an object element;
• the display server uses the Qt5WebKit backend (this instruction needs hipecore); or
• hiped isn't itself running on X11. Where both X11 and Wayland are available, Qt may choose Wayland; start the display server with QT_QPA_PLATFORM=xcb hiped to make it use X11.

Instruction set reference

HIPE_OP_INSERT_TAG

Inserts a new HTML tag element before the specified tag element.

• location: The existing element that comes after where the new tag needs to be inserted.
•   arg[0]: The tag type (e.g. span or button).
•   arg[1]: An optional id string to uniquely identify the new element. The tag id can be used in conjunction with CSS style rules or later in conjunction with HIPE_OP_GET_BY_ID.
•   arg[2]: Optional. A space-separated list of CSS classes to give the new element, as if added with HIPE_OP_TOGGLE_CLASS.
•   arg[3]: Optional. Initial text content for the new element, handled as HIPE_OP_SET_TEXT handles its arg[0] in text mode 0: the characters <, >, &, " and ' are shown as typed, and newlines and tabs are not converted. Ignored for void elements such as br, img and input, which can't have content.

Notes

Only tags that Hipe allows are created; any other tag type is ignored. See "Allowed tags, attributes and styles".

Setting the class and text in the same instruction (arg[2] and arg[3]) is much faster than following up with HIPE_OP_TOGGLE_CLASS and HIPE_OP_SET_TEXT, which matters when building many small elements, such as the coloured spans of syntax-highlighted text.

Prior to version 2, Hipe accepted an extra argument in arg[2] where passing "1" would cause the server to reply with a HIPE_OP_LOCATION_RETURN instruction describing the newly appended tag. This was removed in version 2, and arg[2] is now the class list. A more efficient way to obtain the new location is by calling the hipe_newest_location() function (C) or the hipe::loc::appendAndGetTag() method (C++) in the hipe API.

Instruction set reference

HIPE_OP_KEY_RETURN

This instruction is sent back to the client from the server in response to a HIPE_OP_GET_FRAME_KEY request.

• location: The client frame for which the host key was required.
• arg[0]: The host key corresponding to the client frame.
• requestor: Returns back any user value that was passed in the client's original request.

Instruction set reference

HIPE_OP_LOCATION_RETURN

Sent to the client by the display server in reply to a request for a location handle to a particular element.

• requestor: A copy of whatever value was passed when the request was made.
• location: The location handle that was requested.

Notes

Location handles should be freed using HIPE_OP_FREE_LOCATION when no longer required. They are also freed automatically when the client application terminates.

The location value 0 is returned if the element does not exist or the element exists but its location handle has been freed/de-allocated from use. (With the C++ library, this can happen if all hipe::loc objects corresponding to an element have been discarded.)

Instruction set reference

HIPE_OP_MEASURE_TEXT

Measures how much space some text would take up if it were the content of an element, without adding anything to the document. This is useful for fitting text to a space (for example choosing a font size or where to break a label), finding the width of a character in a monospace font, or placing things alongside text.

• location: The element whose style the text is measured in.
• arg[0]: The text to measure.
• arg[1]: Optional. A font size in CSS pixels (e.g. "18" or "12.5") to measure the text at, instead of the element's own font size. The line height is scaled to match.

The display server responds with a HIPE_OP_TEXT_METRICS instruction.

Notes

The text is measured as if it were placed directly inside the element as its only content: in the element's font (family, size, weight and style, including inherited values), with its letter and word spacing, tab size, text-transform and white-space rules applied. For example, in an element that collapses white space, a run of spaces counts as one space, and spaces at the start and end of a line don't count.

The text is not wrapped: its width is the width of the widest line, however narrow the element is. If the element preserves newlines (e.g. a pre element, or white-space:pre-wrap), each newline in arg[0] starts a new line; otherwise newlines count as spaces. To fit text into a given width, measure different line breaks and font sizes and choose the one that fits.

The element doesn't have to be displayed: an element styled display:none can still be used to measure text.

This instruction needs the hipecore display server backend. With the Qt5WebKit backend, all four values in the reply are empty.

Instruction set reference

HIPE_OP_MESSAGE

Sends a user-defined message to another client, which must be a direct child of the sending client, or the direct parent of the sending client.

• location: Sending a message: A value of 0 (corresponding to the body element of the client frame) means the message should be sent to the direct parent of this client. A location corresponding to a child frame means send the message to the client connected to that frame. Receiving a message: A value of 0 (corresponding to body element) means the message came from the direct parent of this frame. A location value corresponding to a child frame means the message came from that client.
•     arg[]: User defined message data may be passed through up to 4 arguments.
• requestor:: User defined message data may be passed through here.

Notes

Unlike most Hipe instructions, this instruction may be either sent or received by the client. It passes more or less straight through the server from one client to another.

Instruction set reference

HIPE_OP_OPEN_LINK

This instruction sends a link resource (such as a hyperlink URL) to the parent frame or desktop environment to be opened for the user. When used within another desktop environment, this action might launch a web browser or similar to make use of the link resource. On an embedded system, this action might display a QR code for the user to scan on a mobile device. The exact behaviour and implementation depends on the framing manager and user environment.

• location: 0 if sending the link. If receiving this instruction (in the framing manager) the location corresponds to the frame that produced the open-link request.
• arg[0]: The fully qualified link string, e.g. "http://hipe.generaldevelopment.net".
• arg[1]: [reserved for future applications]

Instruction set reference

HIPE_OP_RANGE_GEOMETRY

Sent by the display server in response to a HIPE_OP_GET_RANGE_GEOMETRY instruction.

• location: The element the request was made for.
• arg[0]: The rectangles, one for each line the range covers, separated by semicolons. Each rectangle is four comma-separated numbers: x,y,width,height. For example: 0,3,63,26;0,36,125,26.

Notes

Coordinates are in CSS pixels, relative to the top-left corner of the element (its border edge) as it is currently displayed. If the element, or anything containing it, is scrolled, the rectangles move with the text: they describe where the text appears, not where it would be if nothing were scrolled.

Text on the same line forms a single rectangle, even when it spans several elements or font sizes. Each rectangle covers the text itself, not the full height of the line. Lines within the range that contain no text, such as empty lines, have no rectangle.

For a cursor position, there is a single rectangle with a width of 0, as tall as the line the cursor is on.

arg[0] is empty if there is nothing to report: the element isn't displayed, the range covers no text, or the request was for the element's cursor and the cursor isn't in the element.

Instruction set reference

HIPE_OP_REMOVE_ATTRIBUTE

Removes (unsets) an HTML attribute from a particular HTML tag element.

• location: The location of the tag element.
•     arg[0]: The attribute to remove.

Instruction set reference

HIPE_OP_REQUEST_CONTAINER

This instruction is produced by a client application and sent to the display server in order to initiate a client session and request a frame for the application.

You never need to deal with this instruction directly. It is sent to the display server automatically when you call hipe_open_session().

• location: 0 — not used.
•     arg[0]: host_key
•     arg[1]: client_name
•     arg[2]: Theme index value or blank
• requestor: transmits client process identifier to the server

Notes

The client process identifier sent to the Hipe display server should not be retrieved or relied upon without some form of additional verification. As with X11, the display server's record of the client's PID is dependent on the honesty of the client application.

The theme index value is used for cases where multiple stylesheet themes are loaded into hiped, and different clients require a different theme; usually specified via an environment variable. If blank the default CSS theme will be used. A value of 0 means that only minimal default styling should be used, which then gives the client absolute control over GUI styling.

Instruction set reference

HIPE_OP_SCROLL_BY

Scrolls the contents of a scrollable element by a relative amount compared to the current scroll position.

• location: The element to be affected by the scroll operation
• arg[0]: The relative left-coordinate offset (horizontal scrolling) to apply to the element
• arg[1]: The relative top-coordinate offset (vertical scrolling) to apply to the element
• arg[2]: Specify "%" here for scrolling according to a percentage of the total scroll-track range; or leave unspecified to use the default units of pixels.

Notes

Leave arg[0] or arg[1] blank if scrolling in a certain direction is not required.

Instruction set reference

HIPE_OP_SCROLL_TO

Scrolls the contents of a scrollable element to a new scroll position.

• location: The element to be affected by the scrolling operation
• arg[0]: The new left-coordinate offset (horizontal scroll position)
• arg[1]: The new top-coordinate offset (vertical scroll position)
• arg[2]: Specify "%" here for scrolling according to a percentage of the total scroll-track range; or leave unspecified to use the default units of pixels.

Notes

Leave arg[0] or arg[1] blank if scrolling in a certain direction is not required.

Instruction set reference

HIPE_OP_SERVER_DENIED

Sent by the server when a request is received but cannot be acted on due to some critical violation. Usually this means that the client has not followed protocol, e.g. is trying to send instructions even though a container request was previously denied. Or, the session has been terminated at the server end.

This is also the opcode reported (via instruction_ret->opcode) when hipe_next_instruction() returns -1 because the connection to the display server has been lost. Client applications must check for it and stop calling hipe_next_instruction() when it occurs – see the warning under hipe_next_instruction().

• location: not used.
• No arguments.

Instruction set reference

HIPE_OP_SET_ATTRIBUTE

Sets an HTML attribute for a particular tag element.

• location: The HTML tag element to set the attribute on.
•     arg[0]: The attribute name.
•     arg[1]: The attribute value string.

Notes

Only attributes that Hipe allows are set; any other attribute name is ignored. In particular class, style and src have instructions of their own. See "Allowed tags, attributes and styles".

Instruction set reference

HIPE_OP_SET_CURSOR

Send this instruction to the display server to apply a custom mouse cursor to the specified location. The mouse cursor is generated from a character symbol and can be any unicode character for which the necessary font is available on the system.

• location: The tag element to apply the custom mouse cursor to.
•     arg[0]: The character from which a mouse cursor should be generated. For example "⇖". (If you are viewing this documentation on a mobile device without symbolic fonts, that symbol might look weird.)

Notes

As with all text data in Hipe, the character symbol is assumed to be UTF8 encoded.

Instruction set reference

HIPE_OP_SET_FOCUS

Gives keyboard focus to the specified element.

• location: The location to which to apply keyboard focus.

Instruction set reference

HIPE_OP_SET_ICON

Sets or updates the icon image for the application. This instruction is sent by a client node; it is never received by an application. If the client is running inside a framing manager, the framing manager receives a HIPE_OP_FRAME_EVENT instruction containing the icon data to decorate the client with.

• location: 0. Not used.
•     arg[0]: The raw byte-data of a PNG image file.

Instruction set reference

HIPE_OP_SET_SRC

Sends the data of an image, audio or video file to an img, audio or video element, or a block of raw pixels to a canvas. In Hipe an element's source is always the data itself, never an address.

• location: The element to give the data to.
•     arg[0]: The raw bytes of the file (or of this chunk of it).
•     arg[1]: The mime type of the data, e.g. "image/jpeg" or "video/mp4". Optional for an img, where "image/png" is assumed. Required for audio and video.
•     arg[2]: Optional. "1" if more chunks of the same file will follow. See "Sending a file in chunks".
•     arg[3]: Optional, for chunked audio and video. The size of the whole file in bytes. See "Audio and video".

Sending a file in chunks

A large file can be sent over several HIPE_OP_SET_SRC instructions to the same location, so that the client doesn't have to hold it all in memory or send it as one huge instruction. Set arg[2] to "1" on every chunk except the last.

• arg[1] and arg[3] are read from the first chunk only.
• If you don't know which chunk is the last when you send it, send "1" with every chunk, then finish with one more instruction that has an empty arg[0] and no arg[2].
• A chunked file may be up to 500 MB, and a client may have up to 8 chunked files in progress at once. Beyond either limit the file is discarded without an error. A client that goes far beyond them is disconnected.
• A canvas can't be sent to in chunks.
• Chunks need the hipecore display server backend. With the Qt5WebKit backend arg[2] is ignored, and each instruction is treated as a complete file.

Images

A chunked image is drawn progressively as its chunks arrive. The exception is an element that is already showing a complete image: it keeps showing that until the new one has fully arrived, then swaps, so that the user doesn't see a half-loaded replacement.

Audio and video

Sent as a single instruction, a file plays as soon as playback is started. Playback, speed and volume are controlled with HIPE_OP_AUDIOVIDEO_STATE.

Sent in chunks, when playback can start depends on arg[3]:

arg[3] on the first chunk	What happens
The size of the whole file in bytes	Playback can start once the start of the file has arrived (typically its first tenth), and the element's own controls show how much has arrived. If playback catches up with the data, it pauses by itself and resumes when more has arrived.
Empty	Nothing plays until the last chunk has arrived, although the duration may be reported earlier. Use this when the total size isn't known in advance.

Once the whole file has arrived, a chunked file behaves exactly like one sent in a single instruction, including seeking and looping.

To play something else in the same element, send the new file to it: the old one stops and is replaced.

Canvas

Sending arg[1] = "image/x-raw-rgba" to a canvas writes pixels straight into it (the equivalent of putImageData() in HTML). This needs the hipecore backend.

• The canvas must already have a "2d" context selected with HIPE_OP_USE_CANVAS.
• arg[0] is 4 bytes per pixel in the order red, green, blue, alpha (each 0 to 255), row by row from the top, with nothing between rows and no header.
• By default the pixels fill the whole canvas, so arg[0] must be exactly width × height × 4 bytes. To write to part of the canvas, first set the area with the setSrcRegion method of HIPE_OP_CANVAS_ACTION; arg[0] must then match that area's size.
• If there is no context, or the size doesn't match, the instruction is ignored.

Notes

To read an image's data or a canvas's contents back, use HIPE_OP_GET_SRC.

Instruction set reference

HIPE_OP_SET_STYLE

Send to the display server to apply a CSS style property to the specified location element.

• location: The tag element to be styled.
•     arg[0]: The style property (e.g. "border").
•     arg[1]: The new value of the style property (e.g. "1px solid").

Notes

The instruction is ignored if the property or value contains <, >, {, } or url(. See "Allowed tags, attributes and styles".

You cannot use this instruction to add background images to elements. Use HIPE_OP_SET_STYLE_SRC instead.

Instruction set reference

HIPE_OP_SET_STYLE_SRC

Send this instruction to the display server to specify background image data, or other binary data for the specified style property on the specified tag element.

• location: The location to which to apply the background image.
•   arg[0]: The style property which requires binary data (e.g. "background-image")
•   arg[1]: The raw byte-data of the image file without null termination. (e.g. the raw contents of a PNG graphic file)
•   arg[2]: (optional) The mime type of the background image. If not specified, "image/png" is assumed.
•   arg[3]: (optional) Any additional parameters to be specified after the source data for the CSS property

Notes

arg[3] may be used to facilitate working with CSS properties that take additional parameters that follow after the source image. For example, for the background property in CSS, you might wish to specify not only the background image itself, but also "repeat-x repeat-y" or similar CSS values that modify the behaviour of the CSS property. These would be placed in arg[3] and are treated as a suffix to the style property setting. Values that must be specified before the source data cannot be specified in this way.