Heads

Name

gicHeadAllocate, gicHeadFree, gicHeadAttachContext, gicHeadDetachContext, gicHeadLookupContext, gicHeadGetContext, gicHeadNumContexts, gicHeadWrite, gicHeadRead, gicHeadMapActions : Heads

Synopsis

#include <ggi/gic.h>

struct gic_head *gicHeadAllocate(struct gg_stem *stem, const char *name);
void gicHeadFree(struct gg_stem *stem, struct gic_head *head);
int gicHeadAttachContext(struct gg_stem *stem,
      struct gic_head *head, struct gic_context *context);
int gicHeadDetachContext(struct gg_stem *stem,
      struct gic_head *head, struct gic_context *context);
struct gic_context *gicHeadLookupContext(struct gg_stem *stem,
      struct gic_head *head, const char *name);
struct gic_context *gicHeadGetContext(struct gg_stem *stem,
      struct gic_head *head, int number);
int gicHeadNumContexts(struct gg_stem *stem, struct gic_head *head);
int gicHeadWrite(struct gg_stem *stem,
      struct gic_head *head, FILE *file);
struct gic_head *gicHeadRead(struct gg_stem *stem, FILE *file);
int gicHeadMapActions(struct gg_stem *stem,
      struct gic_head *head, struct gic_action actions[]);

Description

A struct gic_head is LIBGIIGIC's notion of a collection of contexts. Each context describes the mappings between inputs and actions for a given situation in a program.

Thus a head usually describes all the contexts of a program that are managed by libgiigic.

Usually a program will not have to bother with most functions as it will read its config via gicHeadRead. However when building apps that can (re)build the configuration files, the other functions become useful.

A struct gic_head is allocated using gicHeadAllocate, which takes the gic handle it will be associated with and a name for the Head. It returns the allocated head or NULL on failure.

gicHeadFree frees an allocated struct gic_head.

gicHeadAttachContext and gicHeadDetachContext are used to attach and detach contexts from a head. A context refers to a situation in a program that has an input mapping attached to it. Most programs will have multiple such contexts, like one for accessing the menus, one for the game mode, etc.

gicHeadLookupContext and gicHeadGetContext can be used to get access to contexts attached to a head. The former accesses the contexts by name, the latter by number. You can use gicHeadNumContexts to query for the number of contexts.

gicHeadWrite can be used to write out a textual description of the head. This is usually used to write out a config file after it changed.

gicHeadRead will read such a file, allocate a struct gic_head and fill it with the read data. After that, you should call gicHeadMapActions to reestablish the connection between the actions and the action callbacks.

Return value

gicHeadRead and gicHeadAllocate return the read/allocated head on return or NULL on failure.

gicHeadAttachContext, gicHeadDetachContext, gicHeadWrite and gicHeadMapActions return 0 on success and an gg-error(3) code on failure.

gicHeadLookupContext and gicHeadGetContext return the requested context or NULL on failure.

gicHeadNumContexts return the number of contexts attached to the head.

See Also

TODO