Widget utilities: Gwyddion Widgets Library Reference Manual

## Widget utilities Widget utilities — Miscellaneous widget utilities |

## Functions

#define | gwy_adjustment_get_int()
GtkWidget * | gwy_gtkgrid_attach_adjbar ()
void | gwy_gtkgrid_hscale_set_sensitive ()
GtkWidget * | gwy_gtkgrid_hscale_get_scale ()
GtkWidget * | gwy_gtkgrid_hscale_get_check ()
GtkWidget * | gwy_gtkgrid_hscale_get_label ()
GtkWidget * | gwy_gtkgrid_hscale_get_units ()
GtkWidget * | gwy_gtkgrid_hscale_get_middle_widget ()
void | gwy_mask_color_selector_run ()
void | gwy_list_store_row_changed ()
GtkWidget * | gwy_label_new_header ()
GtkWidget * | gwy_create_stock_like_button ()
GtkWidget * | gwy_create_image_menu_item ()
void | gwy_set_image_menu_item_icon ()
void | gwy_set_image_menu_item_pixbuf ()
const gchar * | gwy_stock_label ()
const gchar * | gwy_stock_icon_name ()
gint | gwy_stock_response ()
GtkWidget * | gwy_stock_add_button_to_dialog ()
GtkWidget * | gwy_create_stock_button ()
gboolean | gwy_widget_get_activate_on_unfocus ()
void | gwy_widget_set_activate_on_unfocus ()
void | gwy_widget_sync_sensitivity ()
gboolean | gwy_widget_is_hbox ()
GtkWidget * | gwy_add_button_to_dialog ()
void | gwy_set_message_label ()
void | gwy_set_widget_margins ()
gboolean | gwy_get_screen_size ()
gchar * | gwy_strip_menu_item_label ()

## Types and Values

enum | GwyStockItem
enum | GwyHScaleStyle
enum | GwyResponseType

## Includes

    #include <libgwyui/gwyui.h>

## Description

For the consistency of labelling and mnemonic letters (and general convenience), several common labels are predefined in GwyStockItem enum. Use `gwy_stock_label()` to obtain a predefined label. A couple of helper functions directly creating widgets are also provided.

## Functions

### gwy_adjustment_get_int()

    #define gwy_adjustment_get_int(adj) ((gint)floor(gtk_adjustment_get_value(GTK_ADJUSTMENT(adj)) + 0.5))

Gets a properly rounded integer value from an adjustment, cast to gint.

#### Parameters

adj | A GtkAdjustment to get value of. |

### gwy_gtkgrid_attach_adjbar()

    GtkWidget *
    gwy_gtkgrid_attach_adjbar (GtkGrid *grid,
                               gint row,
                               const gchar *name,
                               const gchar *units,
                               GObject *pivot,
                               GwyHScaleStyle style);

Attaches an adjustment bar with spinbutton and labels, or something else, to a grid row.

The group of controls takes three grid columns: adjustment bar, spinbutton and units.

You can use functions `gwy_gtkgrid_hscale_get_scale()`, `gwy_gtkgrid_hscale_get_check()`, etc. to get the various widgets from pivot later.

The function usually does the right thing but what exactly happens with various `style` values is a bit convoluted.

#### Parameters

grid | A GtkGrid. |
row | Row in `grid` to attach stuff to. |
name | The label before `pivot` widget. |
units | The label after `pivot` widget. |
pivot | Either a GtkAdjustment, or a widget to use instead of the spin button and scale widgets (if `style` is `GWY_HSCALE_WIDGET`). |
style | A mix of options an flags determining what and how will be attached to the grid. |

#### Returns

The middle widget. If a spinbutton is attached, then this spinbutton is returned. Otherwise (in `GWY_HSCALE_WIDGET` case) `pivot` itself.

### gwy_gtkgrid_hscale_set_sensitive()

    void
    gwy_gtkgrid_hscale_set_sensitive (GObject *pivot,
                                      gboolean sensitive);

Sets sensitivity of a group of controls created by `gwy_gtkgrid_attach_adjbar()`.

For controls without an enable/disable check button controls the sensitivity as expected. If the hscale was created with `GWY_HSCALE_CHECK` you usually manage its sensitivity by setting state of the check button instead. Only use this function when you want to enable/disable the entire group of controls, including the check button.

#### Parameters

pivot | The same object that was passed to `gwy_gtkgrid_attach_hscale()` as `pivot` . |
sensitive | `TRUE` to make the row sensitive, `FALSE` to insensitive. |

### gwy_gtkgrid_hscale_get_scale()

    GtkWidget *
    gwy_gtkgrid_hscale_get_scale (GObject *pivot);

Gets the horizontal scale associated with a pivot object.

May return `NULL` if constructed with `GWY_HSCALE_NO_SCALE`, `GWY_HSCALE_WIDGET`, or `GWY_HSCALE_WIDGET_NO_EXPAND`.

#### Parameters

pivot | Pivot object passed to `gwy_gtkgrid_attach_hscale()`. |

### gwy_gtkgrid_hscale_get_check()

    GtkWidget *
    gwy_gtkgrid_hscale_get_check (GObject *pivot);

Gets the check button associated with a pivot object.

May return `NULL` if not constructed with `GWY_HSCALE_CHECK`.

#### Parameters

pivot | Pivot object passed to `gwy_gtkgrid_attach_hscale()`. |

### gwy_gtkgrid_hscale_get_label()

    GtkWidget *
    gwy_gtkgrid_hscale_get_label (GObject *pivot);

Gets the (left) label associated with a pivot object.

May return `NULL` if constructed with `GWY_HSCALE_CHECK`.

#### Parameters

pivot | Pivot object passed to `gwy_gtkgrid_attach_hscale()`. |

### gwy_gtkgrid_hscale_get_units()

    GtkWidget *
    gwy_gtkgrid_hscale_get_units (GObject *pivot);

Gets the units label associated with a pivot object.

May return `NULL` if constructed without units.

#### Parameters

pivot | Pivot object passed to `gwy_gtkgrid_attach_hscale()`. |

### gwy_gtkgrid_hscale_get_middle_widget()

    GtkWidget *
    gwy_gtkgrid_hscale_get_middle_widget (GObject *pivot);

Gets the middle widget associated with a pivot object.

#### Parameters

pivot | Pivot object passed to `gwy_gtkgrid_attach_hscale()`. |

### gwy_mask_color_selector_run()

    void
    gwy_mask_color_selector_run (const gchar *dialog_title,
                                 GtkWindow *parent,
                                 GwyColorButton *color_button,
                                 GwyDict *container,
                                 GQuark quark);

Creates and runs a color selector dialog for a mask.

Note this function does not return anything, it runs the color selection dialog modally and returns when it is finished.

#### Parameters

dialog_title | Title of the color selection dialog (`NULL` to use default). | [nullable]
parent | Dialog parent window. The color selector dialog will be made transient for this window. | [nullable][transfer none]
color_button | Color button to update on color change (or `NULL`). | [nullable][transfer none]
container | Container to initialize the color from and save it to. | [transfer none]
quark | Quark key of the color in `container` . |

### gwy_list_store_row_changed()

    void
    gwy_list_store_row_changed (GtkListStore *store,
                                GtkTreeIter *iter,
                                GtkTreePath *path,
                                gint row);

Convenience function to emit "GtkTreeModel::row-changed" signal on a tree store.

At least one of `iter` , `path` , `row` must be set to identify the row to emit "row-changed" on, and usually exactly one should be set. The remaining information necessary to call `gtk_tree_model_row_changed()` is inferred automatically.

The behaviour of this function is undefined for specified, but inconsistent `iter` , `path` , and `row` .

#### Parameters

store | A list store. |
iter | A tree model iterator in `store` , or `NULL` for none. |
path | A tree model path in `store` , or `NULL` for none. |
row | A row number in `store` , or -1 for none. |

### gwy_label_new_header()

    GtkWidget *
    gwy_label_new_header (const gchar *text);

Creates a bold, left aligned label.

The purpose of this function is to avoid propagation of too much markup to translations (and to reduce code clutter by avoiding dummy constructor and left-aligning automatically).

#### Parameters

text | Text to put into the label. It must be a valid markup and it will be made bold by adding appropriate markup around it. |

#### Returns

A newly created GtkLabel.

### gwy_create_stock_like_button()

    GtkWidget *
    gwy_create_stock_like_button (const gchar *label_text,
                                  const gchar *icon_name);

Creates a button that looks like a stock button, but can have different label text.

The button created by this function always have an icon if it exists, regardless of user preferences.

#### Parameters

label_text | Button label text (with mnemonic). |
icon_name | Name of icon from the default icon theme. |

#### Returns

The newly created button as GtkWidget.

[transfer full]

### gwy_create_image_menu_item()

    GtkWidget *
    gwy_create_image_menu_item (const gchar *label_text,
                                const gchar *icon_name,
                                gboolean always_show);

Creates a menu item with image.

This function either wraps the deprecated GtkImageMenuItem and contains the deprecation in one place, or it reimplements menu items with images by other means. The returned widget is a subclass of GtkMenuItem.

The icon can later be changed by `gwy_set_image_menu_item_icon()`.

#### Parameters

label_text | Menu item label text (with mnemonic). | [nullable]
icon_name | Name of icon from the default icon theme. | [nullable]
always_show | `TRUE` to always show the image; `FALSE` to show it according to GTK+ settings. |

#### Returns

The newly created menu item as GtkWidget.

[transfer full]

### gwy_set_image_menu_item_icon()

    void
    gwy_set_image_menu_item_icon (GtkMenuItem *item,
                                  const gchar *icon_name);

Sets the icon of a menu item with image.

#### Parameters

item | A menu item with image created with `gwy_create_image_menu_item()`. |
icon_name | Name of icon from the default icon theme. | [nullable]

### gwy_set_image_menu_item_pixbuf()

    void
    gwy_set_image_menu_item_pixbuf (GtkMenuItem *item,
                                    GdkPixbuf *pixbuf);

Sets the image of a menu item with image to a pixbuf.

#### Parameters

item | A menu item with image created with `gwy_create_image_menu_item()`. |
pixbuf | Pixbuf to use as the icon. | [nullable]

### gwy_stock_label()

    const gchar *
    gwy_stock_label (GwyStockItem item);

Obtains a predefined common label.

The returned string is already translated.

The label goes together with the icon obtained with `gwy_stock_icon_name()` and response code obtained with `gwy_stock_response()`.

#### Parameters

item | A stock item identifier. |

#### Returns

The predefined label.

### gwy_stock_icon_name()

    const gchar *
    gwy_stock_icon_name (GwyStockItem item);

Obtains a predefined common icon name.

Not all items have an associated icon name. The function may return `NULL`.

The icon goes together with the label obtained with `gwy_stock_label()` and response code obtained with `gwy_stock_response()`.

#### Parameters

item | A stock item identifier. |

#### Returns

The predefined icon name.

[nullable]

### gwy_stock_response()

    gint
    gwy_stock_response (GwyStockItem item);

Obtains a predefined dialog response.

The response is from GwyResponseType enum and goes together with the label obtained with `gwy_stock_label()` and icon obtained with `gwy_stock_icon_name()`.

#### Parameters

item | A stock item identifier. |

#### Returns

The predefined respose.

### gwy_stock_add_button_to_dialog()

    GtkWidget *
    gwy_stock_add_button_to_dialog (GtkDialog *dialog,
                                    GwyStockItem item);

Adds a standard button to a dialog.

The button may actually have an icon or it may not, depending on user preferences. Create a button directly with `gwy_create_stock_like_button()` if the button must have an icon.

#### Parameters

dialog | A dialog window. |
item | A stock item identifier. |

#### Returns

The button widget in case it is needed.

[transfer none]

### gwy_create_stock_button()

    GtkWidget *
    gwy_create_stock_button (GwyStockItem item);

Creates a standard button.

See `gwy_stock_add_button_to_dialog()` if you want to add a standard button to a dialog. The button created by this function always has an icon if the stock item has one associtated, regardless of user preferences.

#### Parameters

item | A stock item identifier. |

#### Returns

The newly created button.

[transfer full]

### gwy_widget_get_activate_on_unfocus()

    gboolean
    gwy_widget_get_activate_on_unfocus (GtkWidget *widget);

Obtains the activate-on-unfocus state of a widget.

#### Parameters

widget | A widget. |

#### Returns

`TRUE` if signal "GtkWidget::activate" is emitted when focus leaves the widget.

### gwy_widget_set_activate_on_unfocus()

    void
    gwy_widget_set_activate_on_unfocus (GtkWidget *widget,
                                        gboolean activate);

Sets the activate-on-unfocus state of a widget.

When it is enabled, signal "GtkWidget::activate" is emited whenever focus leaves the widget.

#### Parameters

widget | A widget. |
activate | `TRUE` to enable activate-on-unfocus, `FALSE` disable it. |

### gwy_widget_sync_sensitivity()

    void
    gwy_widget_sync_sensitivity (GtkWidget *master,
                                 GtkWidget *slave);

Make widget's sensitivity follow the sensitivity of another widget.

The sensitivity of `slave` is set according to `master` 's effective sensitivity (as returned by `GTK_WIDGET_IS_SENSITIVE()`), i.e. it does not just synchronize GtkWidget:sensitive property.

#### Parameters

master | Master widget. |
slave | Slave widget. |

### gwy_widget_is_hbox()

    gboolean
    gwy_widget_is_hbox (GtkWidget *widget);

Checks if a widget is a GTK+ horizontal box.

The function checks whether the widget is a GtkBox and also whether it is horizontal. The latter can change in principle, so the check should to be used when it makes sense.

#### Parameters

widget | A widget. |

#### Returns

`TRUE` if widget is a horizontal GtkBox.

### gwy_add_button_to_dialog()

    GtkWidget *
    gwy_add_button_to_dialog (GtkDialog *dialog,
                              const gchar *label_text,
                              const gchar *icon_name,
                              gint response_id);

Adds a button with an icon to a dialog.

The button may actually have an icon or it may not, depending on user preferences. Create a button directly with `gwy_create_stock_like_button()` if the button must have an icon.

#### Parameters

dialog | A dialog. |
label_text | Button label text (with mnemonic). |
icon_name | Name of icon from the default icon theme. |
response_id | Dialog response id. |

#### Returns

The button widget, in case you need it.

### gwy_set_message_label()

    void
    gwy_set_message_label (GtkLabel *label,
                           const gchar *text,
                           GtkMessageType type,
                           gboolean is_markup);

Sets the text of a label according to message type style.

#### Parameters

label | A label widget. |
text | New label text. |
type | Message type. |
is_markup | `TRUE` if `text` is Pango markup, `FALSE` if it is raw text. |

### gwy_set_widget_margins()

    void
    gwy_set_widget_margins (GtkWidget *widget,
                            gint start,
                            gint end,
                            gint top,
                            gint bottom);

Set multiple widget margins.

This is a convenience wrapper for multiple calls to `gtk_widget_set_margin_start()` and similar functions.

#### Parameters

widget | A widget. |
start | Start (left) margin, or -1 to keep unchanged. |
end | End (right) margin, or -1 to keep unchanged. |
top | Top margin, or -1 to keep unchanged. |
bottom | Bottom margin, or -1 to keep unchanged. |

### gwy_get_screen_size()

    gboolean
    gwy_get_screen_size (GtkWidget *widget,
                         gint *width,
                         gint *height);

Gets the working area size of widget's screen.

If `widget` is NULL, the default screen is substituted. The function can be used to check whether we might be going to to create an unreasonably large window. If, for whatever reason, we cannot obtain the screen size, the function still sets the width and height to reasonable values.

#### Parameters

widget | A widget, possibly `NULL` (although not advisable). |
width | Location where to store the screen width. | [out][nullable]
height | Location where to store the screen height. | [out][nullable]

#### Returns

`TRUE` if the result should be real; `FALSE` when some default was substituted.

### gwy_strip_menu_item_label()

    gchar *
    gwy_strip_menu_item_label (gchar *label);

Removes mnemonics and ellipses from a label string.

The label should not contain XML. Pango markup is currently preserved, but it may be stripped in future, so the behaviour is undefined.

The label should not contain arbitrary content like file names. Odd labels can arise.

#### Parameters

label | Menu item label to modify in place. |

#### Returns

The label again, for easier chaining.

## Types and Values

### enum GwyStockItem

Type of predefined labels.

#### Members

GWY_STOCK_NONE | No/invalid stock item. |
GWY_STOCK_APPLY | Apply stock item. |
GWY_STOCK_CANCEL | Apply stock item. |
GWY_STOCK_CLEAR | Apply stock item. |
GWY_STOCK_CLOSE | Close stock item. |
GWY_STOCK_COPY | Copy stock item. |
GWY_STOCK_DELETE | Delete stock item. |
GWY_STOCK_EDIT | Edit stock item. |
GWY_STOCK_ESTIMATE | Estimate stock item. |
GWY_STOCK_EXPORT | Export stock item. |
GWY_STOCK_FIT | Fit stock item. |
GWY_STOCK_HELP | Help stock item. |
GWY_STOCK_HIDE | Hide stock item. |
GWY_STOCK_LOAD | Load stock item. |
GWY_STOCK_NEW | New stock item. |
GWY_STOCK_OK | OK stock item. |
GWY_STOCK_OPEN | Open stock item. |
GWY_STOCK_REFINE | Refine stock item. |
GWY_STOCK_REMOVE | Remove stock item. |
GWY_STOCK_RESET | Reset stock item. |
GWY_STOCK_SAVE | Save stock item. |
GWY_STOCK_UPDATE | Update stock item. |

### enum GwyHScaleStyle

Options controlling `gwy_table_attach_adjbar()` and `gwy_table_attach_hscale()` behaviour.

#### Members

GWY_HSCALE_DEFAULT | Default label, hscale, spinbutton, and units widget row. Note that the default mapping is linear for hscales but signed square root for adjust bars. |
GWY_HSCALE_LOG | The scale mapping is logarithmic. |
GWY_HSCALE_SQRT | The scale mapping is signed square root. |
GWY_HSCALE_LINEAR | The scale mapping is linear. |
GWY_HSCALE_NO_SCALE | There is no hscale/adjust bar. |
GWY_HSCALE_WIDGET | An user-specified widget is used in place of the adjustment control(s). |
GWY_HSCALE_WIDGET_NO_EXPAND | An user-specified widget is used in place of hscale and spinbutton, and it is left-aligned instead of taking all the alloted space. |
GWY_HSCALE_CHECK | The label is actually a check button that controls sensitivity of the row. This is a flag, to be bitwise or-ed with other values. |
GWY_HSCALE_SNAP | The adjust bar snaps to ticks (hscales cannot snap). This is a flag, to be bitwise or-ed with other values. |

### enum GwyResponseType

Type of predefined dialog response types.

#### Members

GWY_RESPONSE_RESET | Reset of all parameters (that do not have the no-reset flag set). Adding it to a GwyDialog creates a Reset button which is normally handled fully by the dialog itself. |
GWY_RESPONSE_UPDATE | Update of the preview. Adding it to a GwyDialog creates an Update button which is normally handled fully by the dialog itself (including sensitivity tied to an instant updates parameter). |
GWY_RESPONSE_CLEAR | Clearing/resetting of selection. Adding it to a GwyDialog creates a Clear button. You need to connect to “response” and handle the response yourself. |
GWY_RESPONSE_COPY | Predefined response for a Copy button. |
GWY_RESPONSE_DELETE | Predefined response for a Delete or Remove button. |
GWY_RESPONSE_SAVE | Predefined response for a Save or Export button. |
GWY_RESPONSE_EXECUTE | Predefined response for an Excecute or Estimate button. |
GWY_RESPONSE_OPEN | Predefined response for an Open or Load button. |
GWY_RESPONSE_HELP | Predefined response for a Help button (usually handled by the libraries). |
GWY_RESPONSE_NEW | Predefined response for a New button. |
GWY_RESPONSE_EDIT | Predefined response for an Edit button. |
GWY_RESPONSE_REFINE | Predefined response for a Refine or Fit button. |
GWY_RESPONSE_USER | The smallest value to use for non-standard response codes. It is not used by anything in the library (and neither is any larger response code). |