Callbacks

When an object is designated by the user to perform an action, the user may need to call a specific function, a callback, that the user has defined. These functions are usually called by the handleEvent method of the object.

There are two ways you can set a specific callback to be called when an action is triggered:

  • Register the callback as a pointer to a user-defined function.

This function must be an IlvGraphicCallback type.

The type IlvGraphicCallback is defined in the file <ilviews/base/graphic.h>:

#include <ilviews/base/graphic.h>

typedef void (* IlvGraphicCallback)(IlvGraphic* obj, IlAny arg);

The first argument (obj) is the graphic object that called the callback and the second argument (arg) is the user data. The user data could be defined when setting the callback to a particular gadget. If no data is defined, the parameter is the graphic object’s client data that you can set with the IlvGraphic::setClientData method.

  • Register a callback name that is in turn associated with a function to be called by the graphic object container. The association between a callback function and its name must be unique for a particular container.

Registering Callbacks

The methods used to register a callback in a container are:

#include <ilviews/base/contain.h>

 

void registerCallback(const char* callbackName,

IlvGraphicCallback callback);

void unregisterCallback(const char* callbackName);

IlvGraphicCallback getCallback(const IlSymbol* callbackName) const;

Callback Types

An object can define several callback types. Each callback type corresponds to a specific action. For example, you can find, in every gadget, a “Focus In” callback type that refers to the callbacks to be invoked when the gadget receives the keyboard focus.

Each callback type stores a list of callbacks to be invoked when the related event occurs. The class IlvGraphic contains generic methods that allow you to add or remove a callback for a specific callback type:

#include <ilviews/base/graphic.h>

 

void addCallback(const IlSymbol* callbackType,

IlvGraphicCallback callback);

void addCallback(const IlSymbol* callbackType,

const IlSymbol* callbackName);

void addCallback(const IlSymbol* callbackType,

IlvGraphicCallback callback,

IlAny data);

void addCallback(const IlSymbol* callbackType,

const IlSymbol* callbackName,

IlAny data);

void removeCallback(const IlSymbol* callbackType,

IlvGraphicCallback callback);

void removeCallback(const IlSymbol* callbackType,

const IlSymbol* callbackName);

The argument data that you can pass when adding a callback is sent to the callback. It corresponds to the argument named arg in the IlvGraphicCallback definition.

The Main Callback

The Main callback type can be used to perform the main action of an object that is designated to perform several actions. For example, it could be used when a button object is activated, or when you double-click on an item in a string list.

Some useful methods help you set the Main callback of an object:

#include <ilviews/base/graphic.h>

 

IlvGraphicCallback getCallback() const;

IlSymbol* getCallbackName() const;

void setCallback(IlvGraphicCallback callback);

void addCallback(IlvGraphicCallback callback);

void setCallback(IlvGraphicCallback callback, IlAny data);

void addCallback(IlvGraphicCallback callback, IlAny data);

void setCallback(const IlSymbol* callbackName);

void setCallback(const IlSymbol* callbackName, IlAny data);

void setCallbackName(const IlSymbol* callbackName);