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

# gicControlAllocate(3)

Controls

## NAME

**gicControlAllocate**, **gicControlFree**, **gicControlAttachFeature**, **gicControlDetachFeature**, **gicControlLookupFeature**, **gicControlGetFeature**, **gicControlNumFeatures**, **gicControlGetName**, **gicControlWrite**, **gicControlRead**, **gicControlMapActions**, **gicControlFindConflict**, **gicControlHandleEvent** - Controls

## SYNOPSIS

```
#include <ggi/gic.h>
gic_control *gicControlAllocate(gic_handle_t hand,
      char *name,char *shortname);
void gicControlFree(gic_handle_t hand, gic_control *control);
int gicControlAttachFeature(gic_handle_t hand,
      gic_control *control,gic_feature *feature);
int gicControlDetachFeature(gic_handle_t hand,
      gic_control *control,gic_feature *feature);
gic_feature *gicControlLookupFeature(gic_handle_t hand,
      gic_control *context,const char *name);
gic_feature *gicControlGetFeature(gic_handle_t hand,
      gic_control *context,int number);
int gicControlNumFeatures(gic_handle_t hand,
      gic_control *context);
int gicControlGetName(gic_handle_t hand,
      gic_control *control, char *string, size_t maxlen);
int gicControlWrite(gic_handle_t hand,
      gic_control *control,FILE *file);
gic_control *gicControlRead(gic_handle_t hand, FILE *file);
int gicControlMapActions(gic_handle_t hand,
      gic_control *control,gic_actionlist *actions);
int gicControlFindConflict(gic_handle_t hand,
      gic_control *control,gic_recognizer *feature,
      gic_recognizer **start_and_return,gic_feature **optional);
int gicControlHandleEvent(gic_handle_t hand,
      gic_control *control, gii_event *event);
```

## DESCRIPTION

A gic\_control is LIBGIIGIC's notion of a collection of things that control a motion or similar.

Usually applications do not need to handle this themselves.

To allocate a new `gic_control(3)`, call **gicControlAllocate**. To free a context that is not needed anymore, call **gicControlFree**.

**gicControlAttachFeature** and **gicControlDetachFeature** are used to attach and detach features from a control. Multiple features like up/down/left/right make up a control (like sliding).

**gicControlLookupFeature** and **gicControlGetFeature** can be used to get access to features attached to a control. The former accesses the features by name, the latter by number. You can use **gicControlNumFeatures** to query for the number of controls.

**gicControlGetName** can be used to query for the name of a control.

**gicControlWrite** writes a description of the control given to the given *file*. It can be read back with **[gicContextRead(3)](/gicContextRead/3.md)** which will allocate and return a control if successful. Afterwards **gicControlMapActions** should be called to reestablish the mapping between actions and callbacks.

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

You can feed events to **gicControlHandleEvent** to activate the relevant callbacks. However, usually one uses **[gicContextHandleEvent(3)](/gicContextHandleEvent/3.md)**.

## RETURN VALUE

**gicControlRead** and **gicControlAllocate** return the read/allocated  context on return or NULL on failure.

**gicControlAttachFeature**, **gicControlDetachFeature**, **gicControlWrite** and **gicControlMapActions** return **0** on success and an `gii-error(3)` code on failure.

**gicControlLookupFeature** and **gicControlGetFeature** return the requested  feature or NULL on failure.

**gicControlNumFeatures** return the number of features attached to the  control.

## SEE ALSO

`gicContextRead(3)`