Properties and Atoms: GDK 2 Reference Manual

## Properties and Atoms Properties and Atoms |

## Functions

#define | GDK_ATOM_TO_POINTER()
#define | GDK_POINTER_TO_ATOM()
gint | gdk_text_property_to_text_list ()
gint | gdk_text_property_to_text_list_for_display ()
void | gdk_free_text_list ()
gint | gdk_text_property_to_utf8_list ()
gint | gdk_text_property_to_utf8_list_for_display ()
gint | gdk_string_to_compound_text ()
gint | gdk_string_to_compound_text_for_display ()
void | gdk_free_compound_text ()
gchar * | gdk_utf8_to_string_target ()
gboolean | gdk_utf8_to_compound_text ()
gboolean | gdk_utf8_to_compound_text_for_display ()
GdkAtom | gdk_atom_intern ()
GdkAtom | gdk_atom_intern_static_string ()
gchar * | gdk_atom_name ()
gboolean | gdk_property_get ()
void | gdk_property_change ()
void | gdk_property_delete ()

## Types and Values

typedef | GdkAtom
#define | GDK_NONE
enum | GdkPropMode

## Includes

    #include <gdk/gdk.h>

## Description

## Functions

### GDK_ATOM_TO_POINTER()

    #define GDK_ATOM_TO_POINTER(atom) (atom)

### GDK_POINTER_TO_ATOM()

    #define GDK_POINTER_TO_ATOM(ptr)  ((GdkAtom)(ptr))

### gdk_text_property_to_text_list ()

    gint
    gdk_text_property_to_text_list (GdkAtom encoding,
                                    gint format,
                                    const guchar *text,
                                    gint length,
                                    gchar ***list);

`gdk_text_property_to_text_list` is deprecated and should not be used in newly-written code.

### gdk_text_property_to_text_list_for_display ()

    gint
    gdk_text_property_to_text_list_for_display
                                   (GdkDisplay *display,
                                    GdkAtom encoding,
                                    gint format,
                                    const guchar *text,
                                    gint length,
                                    gchar ***list);

`gdk_text_property_to_text_list_for_display` has been deprecated since version 2.24 and should not be used in newly-written code.

Use `gdk_x11_display_text_property_to_text_list()`

Convert a text string from the encoding as it is stored in a property into an array of strings in the encoding of the current locale. (The elements of the array represent the nul-separated elements of the original text string.)

#### Parameters

display | The GdkDisplay where the encoding is defined. |
encoding | an atom representing the encoding. The most common values for this are STRING, or COMPOUND_TEXT. This is value used as the type for the property. |
format | the format of the property. |
text | The text data. |
length | The number of items to transform. |
list | location to store a terminated array of strings in the encoding of the current locale. This array should be freed using `gdk_free_text_list()`. |

#### Returns

the number of strings stored in list, or 0, if the conversion failed.

Since: 2.2

### gdk_free_text_list ()

    void
    gdk_free_text_list (gchar **list);

`gdk_free_text_list` is deprecated and should not be used in newly-written code.

### gdk_text_property_to_utf8_list ()

    gint
    gdk_text_property_to_utf8_list (GdkAtom encoding,
                                    gint format,
                                    const guchar *text,
                                    gint length,
                                    gchar ***list);

`gdk_text_property_to_utf8_list` is deprecated and should not be used in newly-written code.

Convert a text property in the giving encoding to a list of UTF-8 strings.

#### Parameters

encoding | an atom representing the encoding of the text |
format | the format of the property |
text | the text to convert |
length | the length of `text` , in bytes |
list | location to store the list of strings or `NULL`. The list should be freed with `g_strfreev()`. |

#### Returns

the number of strings in the resulting list.

### gdk_text_property_to_utf8_list_for_display ()

    gint
    gdk_text_property_to_utf8_list_for_display
                                   (GdkDisplay *display,
                                    GdkAtom encoding,
                                    gint format,
                                    const guchar *text,
                                    gint length,
                                    gchar ***list);

Converts a text property in the given encoding to a list of UTF-8 strings.

#### Parameters

display | a GdkDisplay |
encoding | an atom representing the encoding of the text |
format | the format of the property |
text | the text to convert |
length | the length of `text` , in bytes |
list | location to store the list of strings or `NULL`. The list should be freed with `g_strfreev()`. |

#### Returns

the number of strings in the resulting list.

Since: 2.2

### gdk_string_to_compound_text ()

    gint
    gdk_string_to_compound_text (const gchar *str,
                                 GdkAtom *encoding,
                                 gint *format,
                                 guchar **ctext,
                                 gint *length);

`gdk_string_to_compound_text` is deprecated and should not be used in newly-written code.

### gdk_string_to_compound_text_for_display ()

    gint
    gdk_string_to_compound_text_for_display
                                   (GdkDisplay *display,
                                    const gchar *str,
                                    GdkAtom *encoding,
                                    gint *format,
                                    guchar **ctext,
                                    gint *length);

`gdk_string_to_compound_text_for_display` has been deprecated since version 2.24 and should not be used in newly-written code.

Use `gdk_x11_display_string_to_compound_text()`

Convert a string from the encoding of the current locale into a form suitable for storing in a window property.

#### Parameters

display | the GdkDisplay where the encoding is defined. |
str | a nul-terminated string. |
encoding | location to store the encoding atom (to be used as the type for the property). |
format | location to store the format of the property |
ctext | location to store newly allocated data for the property. |
length | the length of `text` , in bytes |

#### Returns

0 upon success, non-zero upon failure.

Since: 2.2

### gdk_free_compound_text ()

    void
    gdk_free_compound_text (guchar *ctext);

`gdk_free_compound_text` is deprecated and should not be used in newly-written code.

### gdk_utf8_to_string_target ()

    gchar *
    gdk_utf8_to_string_target (const gchar *str);

Converts an UTF-8 string into the best possible representation as a STRING. The representation of characters not in STRING is not specified; it may be as pseudo-escape sequences \x{ABCD}, or it may be in some other form of approximation.

#### Parameters

str | a UTF-8 string |

#### Returns

the newly-allocated string, or `NULL` if the conversion failed. (It should not fail for any properly formed UTF-8 string unless system limits like memory or file descriptors are exceeded.)

### gdk_utf8_to_compound_text ()

    gboolean
    gdk_utf8_to_compound_text (const gchar *str,
                               GdkAtom *encoding,
                               gint *format,
                               guchar **ctext,
                               gint *length);

`gdk_utf8_to_compound_text` is deprecated and should not be used in newly-written code.

Convert from UTF-8 to compound text.

#### Parameters

str | a UTF-8 string |
encoding | location to store resulting encoding |
format | location to store format of the result |
ctext | location to store the data of the result |
length | location to store the length of the data stored in `ctext` |

#### Returns

`TRUE` if the conversion succeeded, otherwise false.

### gdk_utf8_to_compound_text_for_display ()

    gboolean
    gdk_utf8_to_compound_text_for_display (GdkDisplay *display,
                                           const gchar *str,
                                           GdkAtom *encoding,
                                           gint *format,
                                           guchar **ctext,
                                           gint *length);

`gdk_utf8_to_compound_text_for_display` has been deprecated since version 2.24 and should not be used in newly-written code.

Use `gdk_x11_display_utf8_to_compound_text()`

Converts from UTF-8 to compound text.

#### Parameters

display | a GdkDisplay |
str | a UTF-8 string |
encoding | location to store resulting encoding |
format | location to store format of the result |
ctext | location to store the data of the result |
length | location to store the length of the data stored in `ctext` |

#### Returns

`TRUE` if the conversion succeeded, otherwise `FALSE`.

Since: 2.2

### gdk_atom_intern ()

    GdkAtom
    gdk_atom_intern (const gchar *atom_name,
                     gboolean only_if_exists);

### gdk_atom_intern_static_string ()

    GdkAtom
    gdk_atom_intern_static_string (const gchar *atom_name);

Finds or creates an atom corresponding to a given string.

Note that this function is identical to `gdk_atom_intern()` except that if a new GdkAtom is created the string itself is used rather than a copy. This saves memory, but can only be used if the string will always exist. It can be used with statically allocated strings in the main program, but not with statically allocated memory in dynamically loaded modules, if you expect to ever unload the module again (e.g. do not use this function in GTK+ theme engines).

#### Parameters

atom_name | a static string |

#### Returns

the atom corresponding to `atom_name`

Since: 2.10

### gdk_atom_name ()

    gchar *
    gdk_atom_name (GdkAtom atom);

### gdk_property_get ()

    gboolean
    gdk_property_get (GdkWindow *window,
                      GdkAtom property,
                      GdkAtom type,
                      gulong offset,
                      gulong length,
                      gint pdelete,
                      GdkAtom *actual_property_type,
                      gint *actual_format,
                      gint *actual_length,
                      guchar **data);

### gdk_property_change ()

    void
    gdk_property_change (GdkWindow *window,
                         GdkAtom property,
                         GdkAtom type,
                         gint format,
                         GdkPropMode mode,
                         const guchar *data,
                         gint nelements);

### gdk_property_delete ()

    void
    gdk_property_delete (GdkWindow *window,
                         GdkAtom property);

## Types and Values

### GdkAtom

    typedef struct _GdkAtom            *GdkAtom;

### GDK_NONE

    #define GDK_NONE            _GDK_MAKE_ATOM (0)

### enum GdkPropMode

#### Members

GDK_PROP_MODE_REPLACE |  |
GDK_PROP_MODE_PREPEND |  |
GDK_PROP_MODE_APPEND |  |