Hipe : The DOM on the desktop
How Hipe Works  |  Installation  |  Running hiped  |  Hipe API

The Hipe API
Including libhipe
libhipe functions
C++ extensions
Multithreading considerations
Hipe instructions
Interprocess communication
HIPE_OP_ADD_FONT
HIPE_OP_ADD_STYLE_RULE
HIPE_OP_ADD_STYLE_RULE_SRC
HIPE_OP_APPEND_TAG
HIPE_OP_APPEND_TEXT
HIPE_OP_ATTRIBUTE_RETURN
HIPE_OP_AUDIOVIDEO_STATE
HIPE_OP_CANVAS_ACTION
HIPE_OP_CANVAS_SET_PROPERTY
HIPE_OP_CARAT_POSITION
HIPE_OP_CLEAR
HIPE_OP_CONTAINER_GRANT
HIPE_OP_CONTENT_RETURN
HIPE_OP_DELETE
HIPE_OP_DIALOG
HIPE_OP_DIALOG_INPUT
HIPE_OP_DIALOG_RETURN
HIPE_OP_EDIT_ACTION
HIPE_OP_EDIT_STATUS
HIPE_OP_EVENT
HIPE_OP_EVENT_CANCEL
HIPE_OP_EVENT_REQUEST
HIPE_OP_FIFO_ADD_ABILITY
HIPE_OP_FIFO_CLOSE
HIPE_OP_FIFO_DROP_PEER
HIPE_OP_FIFO_GET_PEER
HIPE_OP_FIFO_OPEN
HIPE_OP_FIFO_REMOVE_ABILITY
HIPE_OP_FIFO_RESPONSE
HIPE_OP_FILE_RETURN
HIPE_OP_FIND_TEXT
HIPE_OP_FRAME_CLOSE
HIPE_OP_FRAME_EVENT
HIPE_OP_FREE_LOCATION
HIPE_OP_GEOMETRY_RETURN
HIPE_OP_GET_ATTRIBUTE
HIPE_OP_GET_AUDIOVIDEO_STATE
HIPE_OP_GET_BY_ID
HIPE_OP_GET_CARAT_POSITION
HIPE_OP_GET_CONTENT
HIPE_OP_GET_FIRST_CHILD
HIPE_OP_GET_FRAME_KEY
HIPE_OP_GET_GEOMETRY
HIPE_OP_GET_LAST_CHILD
HIPE_OP_GET_NEXT_SIBLING
HIPE_OP_GET_PREV_SIBLING
HIPE_OP_GET_SCROLL_GEOMETRY
HIPE_OP_GET_SELECTION
HIPE_OP_INSERT_TAG
HIPE_OP_KEY_RETURN
HIPE_OP_LOCATION_RETURN
HIPE_OP_MESSAGE
HIPE_OP_OPEN_LINK
HIPE_OP_REMOVE_ATTRIBUTE
HIPE_OP_REQUEST_CONTAINER
HIPE_OP_SCROLL_BY
HIPE_OP_SCROLL_TO
HIPE_OP_SERVER_DENIED
HIPE_OP_SET_ATTRIBUTE
HIPE_OP_SET_FOCUS
HIPE_OP_SET_ICON
HIPE_OP_SET_SRC
HIPE_OP_SET_STYLE
HIPE_OP_SET_STYLE_SRC
HIPE_OP_SET_TEXT
HIPE_OP_SET_TITLE
HIPE_OP_TAKE_SNAPSHOT
HIPE_OP_TOGGLE_CLASS
HIPE_OP_USE_CANVAS

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, hipetec 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 an 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::opeator=

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_LAST_CHILD will no longer produce a valid location value for that objeect). 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()

hipe::loc::prevSibling()

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="")