---
name: "XtAllocateGC"
section: "3"
platform: "linux"
package: "libxt"
version: "1.3.1-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/XtAllocateGC"
---

# XtAllocateGC(3)

obtain a shareable GC with modifiable fields

## NAME

XtAllocateGC - obtain a shareable GC with modifiable fields

## SYNTAX

\#include \<X11/Intrinsic.h\>

GC XtAllocateGC(Widget *w*, Cardinal *depth*, XtGCMask *value\_mask*, XGCValues \**values*, XtGCMask *dynamic\_mask*, XtGCMask *unused\_mask*);

## ARGUMENTS

- *values*

  Specifies the actual values for this GC.

- *value\_mask*

  Specifies which fields of the values are specified.

- *w*

  Specifies the widget.

- *depth*

  Specifies the depth for which the returned GC is valid, or 0.

- *dynamic\_mask*

  Specifies the fields of the GC that will be modified by the caller.

- *unused\_mask*

  Specifies the fields of the GC that will not be needed by the caller.

## DESCRIPTION

The **XtAllocateGC** function returns a shareable GC that may be modified by the client. The *screen* field of the specified widget or of the nearest widget ancestor of the specified object and the specified *depth* argument supply the root and drawable depths for which the GC is to be valid. If *depth* is zero the depth is taken from the *depth* field of the specified widget or of the nearest widget ancestor of the specified object.

The *value\_mask* argument specifies the fields of the GC that will be initialized with the respective members of the *values* structure. The *dynamic\_mask* argument specifies fields that the caller intends to modify during program execution. The caller must ensure that the corresponding GC field is set prior to each use of the GC. The *unused\_mask* argument specifies fields of the GC that are of no interest to the caller. The caller may make no assumptions about the contents of any fields specified in *unused\_mask*. The caller may assume that at all times all fields not specified in either *dynamic\_mask* or *unused\_mask* have their default value if not specified in *value\_mask* or the value specified by *values*. If a field is specified in both *value\_mask* and *dynamic\_mask*, the effect is as if it were specified only in *dynamic\_mask* and then immediately set to the value in *values*. If a field is set in *unused\_mask* and also in either *value\_mask* or *dynamic\_mask*, the specification in *unused\_mask* is ignored.

**XtAllocateGC** tries to minimize the number of unique GCs created by comparing the arguments with those of previous calls and returning an existing GC when there are no conflicts. **XtAllocateGC** may modify and return an existing GC if it was allocated with a nonzero *unused\_mask*.

## SEE ALSO

**XtGetGC**\
 *X Toolkit Intrinsics - C Language Interface*\
 *Xlib - C Language X Interface*