
@c %start of fragment

@deftp Class <gdk-atom>
@end deftp

@deffn Function gdk-atom-intern  (atom_name@tie{}@code{mchars}) (only_if_exists@tie{}@code{bool}) @result{}@tie{} (ret@tie{}@code{<gdk-atom>})
Finds or creates an atom corresponding to a given string.

@table @var
@item atom-name
a string.

@item only-if-exists
if @samp{@code{#t}}, GDK is allowed to not create a new atom, but just return
@samp{GDK_NONE} if the requested atom doesn't already exists. Currently, the
flag is ignored, since checking the existance of an atom is as expensive as
creating it.

@item ret
the atom corresponding to @var{atom-name}.

@end table

@end deffn

@deffn Function gdk-atom-name  (atom@tie{}@code{<gdk-atom>}) @result{}@tie{} (ret@tie{}@code{mchars})
Determines the string corresponding to an atom.

@table @var
@item atom
a @code{<gdk-atom>}.

@item ret
a newly-allocated string containing the string corresponding to @var{atom}. When
you are done with the return value, you should free it using @code{g-free}.

@end table

@end deffn

@deffn Function gdk-property-get  (window@tie{}@code{<gdk-window*>}) (property@tie{}@code{<gdk-atom>}) (type@tie{}@code{<gdk-atom>}) (offset@tie{}@code{unsigned-long}) (length@tie{}@code{unsigned-long}) (pdelete@tie{}@code{int}) (actual_property_type@tie{}@code{<gdk-atom*>}) (data@tie{}@code{<guchar**>}) @result{}@tie{} (ret@tie{}@code{bool}) (actual_format@tie{}@code{int}) (actual_length@tie{}@code{int})
Retrieves a portion of the contents of a property. If the property does not
exist, then the function returns @samp{@code{#f}}, and @samp{GDK_NONE} will be
stored in @var{actual-property-type}.

The @code{x-get-window-property} function that @code{gdk-property-get} uses has
a very confusing and complicated set of semantics. Unfortunately,
@code{gdk-property-get} makes the situation worse instead of better (the
semantics should be considered undefined), and also prints warnings to stderr in
cases where it should return a useful error to the program. You are advised to
use @code{x-get-window-property} directly until a replacement function for
@code{gdk-property-get} is provided.

@table @var
@item window
a @code{<gdk-window>}.

@item property
the property to retrieve.

@item type
the desired property type, or @samp{GDK_NONE}, if any type of data is
acceptable. If this does not match the actual type, then @var{actual-format} and
@var{actual-length} will be filled in, a warning will be printed to stderr and
no data will be returned.

@item offset
the offset into the property at which to begin retrieving data, in 4 byte units.

@item length
the length of the data to retrieve in bytes. Data is considered to be retrieved
in 4 byte chunks, so @var{length} will be rounded up to the next highest 4 byte
boundary (so be careful not to pass a value that might overflow when rounded
up).

@item pdelete
if @samp{@code{#t}}, delete the property after retrieving the data.

@item actual-property-type
location to store the actual type of the property.

@item actual-format
location to store the actual return format of the data; either 8, 16 or 32 bits.

@item actual-length
location to store the length of the retrieved data, in bytes. Data returned in
the 32 bit format is stored in a long variable, so the actual number of 32 bit
elements should be be calculated via @var{actual-length}/sizeof(glong) to ensure
portability to 64 bit systems.

@item data
location to store a pointer to the data. The retrieved data should be freed with
@code{g-free} when you are finished using it.

@item ret
@samp{@code{#t}} if data was sucessfully received and stored in @var{data},
otherwise @samp{@code{#f}}.

@end table

@end deffn

@deffn Function gdk-property-change  (window@tie{}@code{<gdk-window*>}) (property@tie{}@code{<gdk-atom>}) (type@tie{}@code{<gdk-atom>}) (format@tie{}@code{int}) (mode@tie{}@code{<gdk-prop-mode>}) (data@tie{}@code{<guchar*>}) (nelements@tie{}@code{int})
Changes the contents of a property on a window.

@table @var
@item window
a @code{<gdk-window>}.

@item property
the property to change.

@item type
the new type for the property. If @var{mode} is @samp{GDK_PROP_MODE_PREPEND} or
@samp{GDK_PROP_MODE_APPEND}, then this must match the existing type or an error
will occur.

@item format
the new format for the property. If @var{mode} is @samp{GDK_PROP_MODE_PREPEND}
or @samp{GDK_PROP_MODE_APPEND}, then this must match the existing format or an
error will occur.

@item mode
a value describing how the new data is to be combined with the current data.

@item data
the data (a @samp{guchar *}@samp{gushort *}, or @samp{gulong *}, depending on
@var{format}), cast to a @samp{guchar *}.

@item nelements
the number of elements of size determined by the format, contained in
@var{data}.

@end table

@end deffn

@deffn Function gdk-property-delete  (window@tie{}@code{<gdk-window*>}) (property@tie{}@code{<gdk-atom>})
Deletes a property from a window.

@table @var
@item window
a @code{<gdk-window>}.

@item property
the property to delete.

@end table

@end deffn


@c %end of fragment
