---
name: "gicContextRead"
section: "3"
platform: "linux"
package: "libgiigic1-dev"
version: "1.1.2-2"
release: "Debian 6.0 (Squeeze)"
platforms: ["linux"]
url: "https://new.carta.tech/gicContextAllocate"
---

# gicContextRead(3)

Contexts

Part of [gicContextAllocate(3)](/gicContextAllocate/3.md).

## NAME

**gicContextAllocate**, **gicContextFree**, **gicContextAttachControl**, **gicContextDetachControl**, **gicContextLookupControl**, **gicContextGetControl**, **gicContextNumControls**, **gicContextGetName**, **gicContextWrite**, **gicContextRead**, **gicContextMapActions**, **gicContextFindConflict**, **gicContextHandleEvent** - Contexts

## SYNOPSIS

```
#include <ggi/gic.h>
gic_context *gicContextAllocate(gic_handle_t hand,char *name);
void gicContextFree(gic_handle_t hand,gic_context *context);
int gicContextAttachControl(gic_handle_t hand,
      gic_context *context,gic_control *control);
int gicContextDetachControl(gic_handle_t hand,
      gic_context *context,gic_control *control);
gic_control *gicContextLookupControl(gic_handle_t hand,
      gic_context *context,const char *name);
gic_control *gicContextGetControl(gic_handle_t hand,
      gic_context *context,int number);
int gicContextNumControls(gic_handle_t hand,
      gic_context *context);
int gicContextGetName(gic_handle_t hand,
      gic_context *context, char *string, size_t maxlen);
int gicContextWrite(gic_handle_t hand,
      gic_context *context,FILE *file);
gic_context *gicContextRead(gic_handle_t hand,FILE *file);
int gicContextMapActions(gic_handle_t hand,
      gic_context *context,gic_actionlist *actions);
int gicContextFindConflict(gic_handle_t hand,
      gic_context *context,gic_recognizer *rec,
      gic_recognizer **start_and_return,gic_feature **optional);
int gicContextHandleEvent(gic_handle_t hand,
      gic_context *context, gii_event *event);
```

## DESCRIPTION

A gic\_context is a collection of controls that make sense in a given situation (context) of the application. A control is an abstract  object that usually describes a type of motion (e.g. sliding).  It can have multiple subobjects (called features) that can further break that down (e.g. into up/down/left/right).

Most applications will not need to handle that themselves. **[gicHeadRead(3)](/gicHeadRead/3.md)** will provide all they need. For those that want to build up contexts themselves, the following functions are provided:

To allocate a new gic\_context, call **gicContextAllocate**. To free a context that is not needed anymore, call **gicContextFree**.

**gicContextAttachControl** and **gicContextDetachControl** are used to  attach and detach controls from a context. A control refers to a  collection of features that describe a common motion. Most contexts  will have multiple such controls, like one for sliding and one for turning a player.

**gicContextLookupControl** and **gicContextGetControl** can be used to get  access to controls attached to a context. The former accesses the controls  by name, the latter by number. You can use **gicContextNumControls** to  query for the number of controls.

**gicContextGetName** can be used to query for the name of a context.

**gicContextWrite** writes a description of the context given to the given file. It can be read back with **gicContextRead** which will allocate and return context if successful. Afterwards **gicContextMapActions** should be called to reestablish the mapping between actions and callbacks.

In learning-mode, **gicContextFindConflict** is useful to check, if there are conflicting controls.

When the context is active, you feed it with events using **gicContextHandleEvent** which will cause it to activate the relevant callbacks.

When an application is in a context, you should feed the events to  **gicContextHandleEvent** to activate the relevant callbacks.

## RETURN VALUE

**gicContextRead** and **gicContextAllocate** return the read/allocated  context on return or NULL on failure.

**gicContextAttachControl**, **gicContextDetachControl**, **gicContextWrite** and **gicContextMapActions** return 0 on success and an `gii-error(3)` code on failure.

**gicContextLookupControl** and **gicContextGetControl** return the requested  control or NULL on failure.

**gicContextNumControls** return the number of controls attached to the  context.

## SEE ALSO

`gicHeadRead(3)`, `gic_context(3)`