Ginger88895
/
warzone2100
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update the betawidget library; add Doxygen docblocks for the methods in widget.h; make the event handler callbacks accept void *userData. 

git-svn-id: svn+ssh://svn.gna.org/svn/warzone/trunk@4772 4a71c877-e1ca-e34f-864e-861f7616d084
master
Freddie Witherden 2008-04-25 23:20:16 +00:00
parent 1ee52fc422
commit b22e2c8aae
2 changed files with 102 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
lib/betawidget/widget.c
View File

@ -180,11 +180,14 @@ widget *widgetFindById(widget *self, const char *id)
*/
bool widgetAddChildImpl(widget *self, widget *child)
{
// FIXME: We need to do some arbitration
// TODO: We need to assert that id is unique;
// widgetFindById(widgetGetRoot(self), child->id) == NULL should do
// Add the widget
vectorAdd(self->children, child);
// FIXME: We need to do some arbitration
// Set ourself as its parent
child->parent = self;
@ -217,12 +220,13 @@ void widgetRemoveChildImpl(widget *self, widget *child)
/*
*
*/
int widgetAddEventHandlerImpl(widget *self, eventType type, callback handler)
int widgetAddEventHandlerImpl(widget *self, eventType type, callback handler, void *userData)
{
eventTableEntry *entry = malloc(sizeof(eventTableEntry));
entry->type = type;
entry->callback = handler;
entry->userData = userData;
// Add the handler to the table
vectorAdd(self->eventVtbl, entry);
@ -249,7 +253,7 @@ bool widgetFireCallbacksImpl(widget *self, event *evt)
if (handler->type == evt->type)
{
handler->callback(self, evt);
handler->callback(self, evt, handler->userData);
}
}
@ -433,9 +437,10 @@ void widgetRemoveChild(widget *self, widget *child)
WIDGET_GET_VTBL(self)->removeChild(self, child);
}
int widgetAddEventHandler(widget *self, eventType type, callback handler)
int widgetAddEventHandler(widget *self, eventType type,
callback handler, void *userData)
{
return WIDGET_GET_VTBL(self)->addEventHandler(self, type, handler);
return WIDGET_GET_VTBL(self)->addEventHandler(self, type, handler, userData);
}
void widgetRemoveEventHandler(widget *self, int id)

109
lib/betawidget/widget.h
View File

@ -21,7 +21,7 @@ typedef struct _eventMouseBtn eventMouseBtn;
typedef struct _eventKey eventKey;
typedef struct _eventMisc eventMisc;
typedef bool (*callback) (widget *widget, event *evt);
typedef bool (*callback) (widget *widget, event *evt, void *userData);
typedef struct _eventTableEntry eventTableEntry;
@ -55,6 +55,8 @@ enum _mouseButton
{
BUTTON_LEFT,
BUTTON_RIGHT,
BUTTON_WHEEL_UP,
BUTTON_WHELL_DOWN,
BUTTON_OTHER
};
@ -107,8 +109,11 @@ struct _eventKey
{
event event;
// The key which was pressed
int key;
// The key which was pressed, this should be used for text-input &c
int unicode;
// The keycode of the key which was pressed
int keycode;
// Active modifier keys
bool ctrl;
@ -131,6 +136,7 @@ struct _eventTableEntry
{
eventType type;
callback callback;
void *userData;
};
/*
@ -144,7 +150,8 @@ struct _widgetVtbl
void (*removeChild) (widget *self, widget *child);
bool (*fireCallbacks) (widget *self, event *evt);
int (*addEventHandler) (widget *self, eventType type, callback handler);
int (*addEventHandler) (widget *self, eventType type,
callback handler, void *userData);
void (*removeEventHandler) (widget *self, int id);
void (*focus) (widget *self);
@ -233,7 +240,8 @@ void widgetDestroyImpl(widget *instance);
bool widgetAddChildImpl(widget *self, widget *child);
void widgetRemoveChildImpl(widget *self, widget *child);
bool widgetFireCallbacksImpl(widget *self, event *evt);
int widgetAddEventHandlerImpl(widget *self, eventType type, callback handler);
int widgetAddEventHandlerImpl(widget *self, eventType type,
callback handler, void *userData);
void widgetRemoveEventHandlerImpl(widget *self, int id);
void widgetEnableImpl(widget *self);
void widgetDisableImpl(widget *self);
@ -248,38 +256,80 @@ bool widgetHandleEventImpl(widget *instance, event *evt);
/**
* Draws the widget along with its child widgets.
*
* @param self The widget to be drawn.
* @param cr The cairo context the widget should draw itself on.
*/
void widgetDraw(widget *self, cairo_t *cr);
/**
* Recursively searches the child widgets of self for a widget whose ->id is
* id. If no widget with such an id exists NULL is returned.
*
* @param self The widget to start the search from.
* @param id The id of the desired widget.
* @return A pointer to the widget if found, NULL otherwise.
*/
widget *widgetFindById(widget *self, const char *id);
/**
* Transverses up the hierarchy until it finds parent-less widget (known as
* the root widget). A pointer to this widget is returned.
*
* @param self The widget to find the root widget of.
* @return A pointer to the root widget.
*/
widget *windgetGetRoot(widget *self);
/**
* Attempts to add child as a child widget of self. The exact location of the
* widget (as well as its dimensions) are decided during an arbitration process
* between the self and the child.
*
* @param self The widget to add the child widget to.
* @param child The widget to be added.
* @return true if child was successfully added, false otherwise.
*/
bool widgetAddChild(widget *self, widget *child);
/**
* Attempts to remove child from the list of child widgets. If the child widget
* is found anywhere in the hierarchy it is removed and its destructor called.
*
* A convenient way of using this methid is as follows:
* widgetRemoveChild(self, widgetFindById(self, "id_to_remove"));
*
* @param self The widget to remove child from.
* @param child The child widget to remove.
*/
void widgetRemoveChild(widget *self, widget *child);
/**
* Adds handler to self's event handler table, registering it to respond to
* events of type. An unique id is assigned to the event when it is added. This
* id can be used at a later date to widgetRemoveEventHandler to remove the
* event.
*
* The userData pointer is passed verbatim to handler via the userData
* parameter. If no user data is required then NULL can be passed.
*
* It is perfectly legal for there to be multiple event handlers installed for
* a single event type. When this is the case the event handlers are fired in
* the order in which they were added.
*
* @param self The widget to add the event handler to.
* @param type The type of event that handler should respond to.
* @param handler The function to call when the event type fires.
* @return The id of the newly added event.
*/
int widgetAddEventHandler(widget *self, eventType type, callback handler);
int widgetAddEventHandler(widget *self, eventType type,
callback handler, void *userData);
/**
* Removes the event from the events table at offset id.
*
* @param self The widget to remove the event handler from.
* @param id The id of the event to be removed.
*/
void widgetRemoveEventHandler(widget *self, int id);
@ -287,20 +337,26 @@ void widgetRemoveEventHandler(widget *self, int id);
* Enables the current widget along with all of its child widgets. If the
* widget is currently enabled but one or more of its child widgets are not
* then they will also be enabled.
*
*
* If, however, the parent widget is disabled then this method is effectively
* a no-op.
*
* @param self The widget to enable.
*/
void widgetEnable(widget *self);
/**
* Disables the current widget along with all of its child widgets. If the
* widget is currently disabled then this method is a no-op.
*
* @param self The widget to disable.
*/
void widgetDisable(widget *self);
/**
* Destroys the widget and frees *all* memory associated with it.
*
* @param self The widget to destroy.
*/
void widgetDestroy(widget *self);
@ -309,40 +365,59 @@ void widgetDestroy(widget *self);
* has focus. If self does not currently have focus then NULL is returned.
* Should none of self's child widgets have focus (but it does) then self is
* returned.
*
* @param self The widget to get the further down focused child of.
* @return A pointer to the widget, or NULL if self is not focused.
*/
widget *widgetGetCurrentlyFocused(widget *self);
/**
* If the widget is capable of holding keyboard focus and does not currently
* hold it then this method should bring the widget into focus.
* hold it then this method will bring it into focus. Should ->parent not be
* focused then widgetFocus(self->parent) will be called to focus it.
*
* This method will also blur any widgets which will no longer be in focus as a
* result of self being focued. In addition it takes responsibility for firing
* the EVT_FOCUS callbacks for self.
*
* This method will call the blur() method of the root widget first.
* @param self The widget to focus.
*/
void widgetFocus(widget *self);
/**
* Blurs the current widget (removes keyboard focus from it) and fires the
* EVT_BLUR event handlers for affected widgets.
c * Blurs the current widget (removes keyboard focus from it). Before self is
* blurred any child widget with focus is blurred first. Finally the EVT_BLUR
* event handlers for self are fired.
*
* @param self The widget to blur.
*/
void widgetBlur(widget *self);
/**
*
* TODO
*/
bool widgetHandleEvent(widget *self, event *evt);
/**
*
*/
bool widgetFireCallbacks(widget *self, event *evt);
/*
* Protected methods
*/
/**
* A protected `pure virtual' method which is called to draw the widget. The
* cairo translation matrix is set-up such that (0,0) is the top-left of the
* widget.
*
* @param self The widget that should draw itself.
* @param cr The context to draw the widget to.
*/
void widgetDoDraw(widget *self, cairo_t *cr);
/**
* Fires all of the event handlers registered for evt->type on the widger self.
*
* @param self The widget to fire the callbacks on.
* @param evt The event to fire the callbacks for.
*/
bool widgetFireCallbacks(widget *self, event *evt);
#endif /*WIDGET_H_*/