Stock Items: GTK+ 3 Reference Manual

## Stock Items Stock Items — Prebuilt common menu/toolbar items and corresponding icons |

## Functions

void | gtk_stock_add ()
void | gtk_stock_add_static ()
GtkStockItem * | gtk_stock_item_copy ()
void | gtk_stock_item_free ()
GSList * | gtk_stock_list_ids ()
gboolean | gtk_stock_lookup ()
void | gtk_stock_set_translate_func ()

## Types and Values

struct | GtkStockItem
#define | GTK_STOCK_ABOUT
#define | GTK_STOCK_ADD
#define | GTK_STOCK_APPLY
#define | GTK_STOCK_BOLD
#define | GTK_STOCK_CANCEL
#define | GTK_STOCK_CAPS_LOCK_WARNING
#define | GTK_STOCK_CDROM
#define | GTK_STOCK_CLEAR
#define | GTK_STOCK_CLOSE
#define | GTK_STOCK_COLOR_PICKER
#define | GTK_STOCK_CONVERT
#define | GTK_STOCK_CONNECT
#define | GTK_STOCK_COPY
#define | GTK_STOCK_CUT
#define | GTK_STOCK_DELETE
#define | GTK_STOCK_DIALOG_AUTHENTICATION
#define | GTK_STOCK_DIALOG_ERROR
#define | GTK_STOCK_DIALOG_INFO
#define | GTK_STOCK_DIALOG_QUESTION
#define | GTK_STOCK_DIALOG_WARNING
#define | GTK_STOCK_DIRECTORY
#define | GTK_STOCK_DISCARD
#define | GTK_STOCK_DISCONNECT
#define | GTK_STOCK_DND
#define | GTK_STOCK_DND_MULTIPLE
#define | GTK_STOCK_EDIT
#define | GTK_STOCK_EXECUTE
#define | GTK_STOCK_FILE
#define | GTK_STOCK_FIND
#define | GTK_STOCK_FIND_AND_REPLACE
#define | GTK_STOCK_FLOPPY
#define | GTK_STOCK_FULLSCREEN
#define | GTK_STOCK_GOTO_BOTTOM
#define | GTK_STOCK_GOTO_FIRST
#define | GTK_STOCK_GOTO_LAST
#define | GTK_STOCK_GOTO_TOP
#define | GTK_STOCK_GO_BACK
#define | GTK_STOCK_GO_DOWN
#define | GTK_STOCK_GO_FORWARD
#define | GTK_STOCK_GO_UP
#define | GTK_STOCK_HARDDISK
#define | GTK_STOCK_HELP
#define | GTK_STOCK_HOME
#define | GTK_STOCK_INDENT
#define | GTK_STOCK_INDEX
#define | GTK_STOCK_INFO
#define | GTK_STOCK_ITALIC
#define | GTK_STOCK_JUMP_TO
#define | GTK_STOCK_JUSTIFY_CENTER
#define | GTK_STOCK_JUSTIFY_FILL
#define | GTK_STOCK_JUSTIFY_LEFT
#define | GTK_STOCK_JUSTIFY_RIGHT
#define | GTK_STOCK_LEAVE_FULLSCREEN
#define | GTK_STOCK_MEDIA_FORWARD
#define | GTK_STOCK_MEDIA_NEXT
#define | GTK_STOCK_MEDIA_PAUSE
#define | GTK_STOCK_MEDIA_PLAY
#define | GTK_STOCK_MEDIA_PREVIOUS
#define | GTK_STOCK_MEDIA_RECORD
#define | GTK_STOCK_MEDIA_REWIND
#define | GTK_STOCK_MEDIA_STOP
#define | GTK_STOCK_MISSING_IMAGE
#define | GTK_STOCK_NETWORK
#define | GTK_STOCK_NEW
#define | GTK_STOCK_NO
#define | GTK_STOCK_OK
#define | GTK_STOCK_OPEN
#define | GTK_STOCK_ORIENTATION_LANDSCAPE
#define | GTK_STOCK_ORIENTATION_PORTRAIT
#define | GTK_STOCK_ORIENTATION_REVERSE_LANDSCAPE
#define | GTK_STOCK_ORIENTATION_REVERSE_PORTRAIT
#define | GTK_STOCK_PAGE_SETUP
#define | GTK_STOCK_PASTE
#define | GTK_STOCK_PREFERENCES
#define | GTK_STOCK_PRINT
#define | GTK_STOCK_PRINT_ERROR
#define | GTK_STOCK_PRINT_PAUSED
#define | GTK_STOCK_PRINT_PREVIEW
#define | GTK_STOCK_PRINT_REPORT
#define | GTK_STOCK_PRINT_WARNING
#define | GTK_STOCK_PROPERTIES
#define | GTK_STOCK_QUIT
#define | GTK_STOCK_REDO
#define | GTK_STOCK_REFRESH
#define | GTK_STOCK_REMOVE
#define | GTK_STOCK_REVERT_TO_SAVED
#define | GTK_STOCK_SAVE
#define | GTK_STOCK_SAVE_AS
#define | GTK_STOCK_SELECT_ALL
#define | GTK_STOCK_SELECT_COLOR
#define | GTK_STOCK_SELECT_FONT
#define | GTK_STOCK_SORT_ASCENDING
#define | GTK_STOCK_SORT_DESCENDING
#define | GTK_STOCK_SPELL_CHECK
#define | GTK_STOCK_STOP
#define | GTK_STOCK_STRIKETHROUGH
#define | GTK_STOCK_UNDELETE
#define | GTK_STOCK_UNDERLINE
#define | GTK_STOCK_UNDO
#define | GTK_STOCK_UNINDENT
#define | GTK_STOCK_YES
#define | GTK_STOCK_ZOOM_100
#define | GTK_STOCK_ZOOM_FIT
#define | GTK_STOCK_ZOOM_IN
#define | GTK_STOCK_ZOOM_OUT

## Includes

    #include <gtk/gtk.h>

## Description

> Since GTK+ 3.10, stock items are deprecated. You should instead set up whatever labels and/or icons you need using normal widget API, rather than relying on GTK+ providing ready-made combinations of these.

Stock items represent commonly-used menu or toolbar items such as “Open” or “Exit”. Each stock item is identified by a stock ID; stock IDs are just strings, but macros such as GTK_STOCK_OPEN are provided to avoid typing mistakes in the strings. Applications can register their own stock items in addition to those built-in to GTK+.

Each stock ID can be associated with a GtkStockItem, which contains the user-visible label, keyboard accelerator, and translation domain of the menu or toolbar item; and/or with an icon stored in a GtkIconFactory. The connection between a GtkStockItem and stock icons is purely conventional (by virtue of using the same stock ID); it’s possible to register a stock item but no icon, and vice versa. Stock icons may have a RTL variant which gets used for right-to-left locales.

## Functions

### gtk_stock_add ()

    void
    gtk_stock_add (const GtkStockItem *items,
                   guint n_items);

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

Registers each of the stock items in `items` . If an item already exists with the same stock ID as one of the `items` , the old item gets replaced. The stock items are copied, so GTK+ does not hold any pointer into `items` and `items` can be freed. Use `gtk_stock_add_static()` if `items` is persistent and GTK+ need not copy the array.

#### Parameters

items | a GtkStockItem or array of items. | [array length=n_items]
n_items | number of GtkStockItem in `items` |

### gtk_stock_add_static ()

    void
    gtk_stock_add_static (const GtkStockItem *items,
                          guint n_items);

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

Same as `gtk_stock_add()`, but doesn’t copy `items` , so `items` must persist until application exit.

#### Parameters

items | a GtkStockItem or array of GtkStockItem. | [array length=n_items]
n_items | number of items |

### gtk_stock_item_copy ()

    GtkStockItem *
    gtk_stock_item_copy (const GtkStockItem *item);

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

Copies a stock item, mostly useful for language bindings and not in applications.

[skip]

#### Parameters

item | a GtkStockItem |

#### Returns

a new GtkStockItem

### gtk_stock_item_free ()

    void
    gtk_stock_item_free (GtkStockItem *item);

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

Frees a stock item allocated on the heap, such as one returned by `gtk_stock_item_copy()`. Also frees the fields inside the stock item, if they are not `NULL`.

#### Parameters

item | a GtkStockItem |

### gtk_stock_list_ids ()

    GSList *
    gtk_stock_list_ids (void);

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

Retrieves a list of all known stock IDs added to a GtkIconFactory or registered with `gtk_stock_add()`. The list must be freed with `g_slist_free()`, and each string in the list must be freed with `g_free()`.

#### Returns

a list of known stock IDs.

[element-type utf8][transfer full]

### gtk_stock_lookup ()

    gboolean
    gtk_stock_lookup (const gchar *stock_id,
                      GtkStockItem *item);

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

Fills `item` with the registered values for `stock_id` , returning `TRUE` if `stock_id` was known.

#### Parameters

stock_id | a stock item name |
item | stock item to initialize with values. | [out]

#### Returns

`TRUE` if `item` was initialized

### gtk_stock_set_translate_func ()

    void
    gtk_stock_set_translate_func (const gchar *domain,
                                  GtkTranslateFunc func,
                                  gpointer data,
                                  GDestroyNotify notify);

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

Sets a function to be used for translating the `label` of a stock item.

If no function is registered for a translation domain, `g_dgettext()` is used.

The function is used for all stock items whose `translation_domain` matches `domain` . Note that it is possible to use strings different from the actual gettext translation domain of your application for this, as long as your GtkTranslateFunc uses the correct domain when calling `dgettext()`. This can be useful, e.g. when dealing with message contexts:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    GtkStockItem items[] = {
     { MY_ITEM1, NC_("odd items", "Item 1"), 0, 0, "odd-item-domain" },
     { MY_ITEM2, NC_("even items", "Item 2"), 0, 0, "even-item-domain" },
    };

    gchar *
    my_translate_func (const gchar *msgid,
                       gpointer     data)
    {
      gchar *msgctxt = data;

      return (gchar*)g_dpgettext2 (GETTEXT_PACKAGE, msgctxt, msgid);
    }

    ...

    gtk_stock_add (items, G_N_ELEMENTS (items));
    gtk_stock_set_translate_func ("odd-item-domain", my_translate_func, "odd items");
    gtk_stock_set_translate_func ("even-item-domain", my_translate_func, "even items");

#### Parameters

domain | the translation domain for which `func` shall be used |
func | a GtkTranslateFunc |
data | data to pass to `func` |
notify | a GDestroyNotify that is called when `data` is no longer needed |

Since: 2.8