XAllocClassHint(XS)      X Version 11 (Release 5)        XAllocClassHint(XS)
                                6 January 1993


 Name

    XAllocClassHint - allocate class hints structure and set or read a
    window's WM_CLASS property

 Syntax


    XClassHint *XAllocClassHint()

    XSetClassHint(display, w, class_hints)
          Display *display;
          Window w;
          XClassHint *class_hints;

    Status XGetClassHint(display, w, class_hints_return)
          Display *display;
          Window w;
          XClassHint *class_hints_return;


 Arguments


    display           Specifies the connection to the X server.

    classhints       Specifies the XClassHint structure that is to be used.

    classhintsreturn
                      Returns the XClassHint structure.

    w                 Specifies the window.

 Description

    The XAllocClassHint function allocates and returns a pointer to a
    XClassHint structure.  Note that the pointer fields in the XClassHint
    structure are initially set to NULL.  If insufficient memory is avail-
    able, XAllocClassHint returns NULL.  To free the memory allocated to this
    structure, use XFree.

    The XSetClassHint function sets the class hint for the specified window.
    If the strings are not in the Host Portable Character Encoding the result
    is implementation dependent.

    XSetClassHint can generate ``BadAlloc'' and ``BadWindow'' errors.

    The XGetClassHint function returns the class hint of the specified window
    to the members of the supplied structure.  If the data returned by the
    server is in the Latin Portable Character Encoding, then the returned
    strings are in the Host Portable Character Encoding.  Otherwise, the
    result is implementation dependent.  It returns nonzero status on suc-
    cess; otherwise it returns a zero status.  To free resname and resclass
    when finished with the strings, use XFree on each individually.

    XGetClassHint can generate a ``BadWindow'' error.

 Properties


    WMCLASS       Set by application programs to allow window and session
                   managers to obtain the application's resources from the
                   resource database.

 Structures

    The XClassHint structure contains:

       typedef struct {
            char *res_name;
            char *res_class;
       } XClassHint;

    The resname member contains the application name, and the resclass
    member contains the application class.  Note that the name set in this
    property may differ from the name set as WMNAME.  That is, WMNAME
    specifies what should be displayed in the title bar and, therefore, can
    contain temporal information (for example, the name of a file currently
    in an editor's buffer).  On the other hand, the name specified as part of
    WMCLASS is the formal name of the application that should be used when
    retrieving the application's resources from the resource database.

 Diagnostics


    ``BadAlloc''   The server failed to allocate the requested resource or
                   server memory.

    ``BadWindow''  A value for a Window argument does not name a defined Win-
                   dow.

 See also

    XAllocIconSize(XS), XAllocSizeHints(XS), XAllocWMHints(XS), XFree(XS),
    XSetCommand(XS), XSetTransientForHint(XS), XSetTextProperty(XS),
    XSetWMClientMachine(XS), XSetWMColormapWindows(XS), XSetWMIconName(XS),
    XSetWMName(XS), XSetWMProperties(XS), XSetWMProtocols(XS),
    XStringListToTextProperty(XS)
    Xlib - C Language X Interface