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
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 (including 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. 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 and can still be referenced again at any time, but it will be allocated a new location handle). 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.
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.