XtAllocateGC(Xt)  X Version 11 (Release 5) 6 January 1993   XtAllocateGC(Xt)


 Name

    XtAllocateGC - obtain shareable GC with modifable fields

 Syntax


    GC XtAllocateGC(object, depth, value_mask, values, dynamic_mask, unused_mask)
          Widget object;
          Cardinal depth;
          XtGCMask value_mask;
          XGCValues *values;
          XtGCMask dynamic_mask;
          XtGCMask unused_mask;


 Arguments

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

    dynamicmask
              Specifies fields of the GC that may be modified by the caller.

    object    Specifies an object, giving the screen for which the returned
              GC is valid. Must be of class Object or any subclass thereof.

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

    values    Specifies the values for the initialized fields.

    valuemask
              Specifies fields of the GC that are initialized from values.

 Description

    The Intrinsics provide a mechanism whereby cooperating objects can share
    a graphics context (GC), thereby reducing both the number of GCs created
    and the total number of server calls in any given application.  The mech-
    anism is a simple caching scheme and allows for clients to declare both
    modifiable and nonmodifiable fields of the shared GCs.

    The XtAllocateGC function returns a shareable GC that may be modified by
    the client.  The object 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 valuemask argument specifies fields of the GC that will be initial-
    ized with the respective member of the values structure.  The
    dynamicmask argument specifies fields that the caller intends to modify
    during program execution.  The caller must insure that the corresponding
    GC field is set prior to each use of the GC.  The unusedmask 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 unusedmask.  The caller may assume that at all times all fields not
    specified in either dynamicmask or unusedmask have their default value
    if not specified in valuemask or the value specified by values.  If a
    field is specified in both valuemask and dynamicmask, the effect is as
    if it were specified only in dynamicmask and then immediately set to the
    value in values.  If a field is set in unusedmask and also in either
    valuemask or dynamicmask, the specification in unusedmask is ignored.

    XtAllocateGC tries to minimize the number of unique GCs created by com-
    paring the arguments with those of previous calls and returning an exist-
    ing GC when there are no conflicts.  XtAllocateGC may modify and return
    an existing GC if it was allocated with a nonzero unusedmask.


 See also

    XtGetGC(Xt), and XtCreateGC(XS).

    X Toolkit Intrinsics - C Language Interface
    Xlib - C Language X Interface