gwydgetutils: Gwyddion Widgets Library Reference Manual

## gwydgetutils gwydgetutils — Miscellaneous widget utilities |

## Functions

#define | gwy_adjustment_get_int()
GtkWidget * | gwy_table_attach_spinbutton ()
void | gwy_table_attach_row ()
GtkWidget * | gwy_table_attach_hscale ()
GtkWidget * | gwy_table_attach_adjbar ()
void | gwy_table_hscale_set_sensitive ()
GtkWidget * | gwy_table_hscale_get_scale ()
GtkWidget * | gwy_table_hscale_get_check ()
GtkWidget * | gwy_table_hscale_get_label ()
GtkWidget * | gwy_table_hscale_get_units ()
GtkWidget * | gwy_table_hscale_get_middle_widget ()
GtkWidget * | gwy_table_get_child_widget ()
void | gwy_color_selector_for_mask ()
void | gwy_mask_color_selector_run ()
void | gwy_list_store_row_changed ()
GtkWidget * | gwy_hbox_new ()
GtkWidget * | gwy_vbox_new ()
gboolean | gwy_dialog_prevent_delete_cb ()
GtkWidget * | gwy_label_new_header ()
GtkWidget * | gwy_stock_like_button_new ()
GtkWidget * | gwy_tool_like_button_new ()
gboolean | gwy_widget_get_activate_on_unfocus ()
void | gwy_widget_set_activate_on_unfocus ()
void | gwy_widget_sync_sensitivity ()
PangoFontMap * | gwy_get_pango_ft2_font_map ()

## Includes

    #include <libgwydgets/gwydgets.h>

## Description

## Functions

### gwy_adjustment_get_int()

    #define             gwy_adjustment_get_int(adj)

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

#### Parameters

adj | A GtkAdjustment to get value of. |

### gwy_table_attach_spinbutton ()

    GtkWidget *
    gwy_table_attach_spinbutton (GtkWidget *table,
                                 gint row,
                                 const gchar *name,
                                 const gchar *units,
                                 GtkObject *adj);

Attaches a spinbutton with two labels to a table.

#### Parameters

table | A GtkTable. |
row | Table row to attach to. |
name | The label before `adj` . |
units | The label after `adj` . |
adj | An adjustment to create spinbutton from. |

#### Returns

The spinbutton as a GtkWidget.

### gwy_table_attach_row ()

    void
    gwy_table_attach_row (GtkWidget *table,
                          gint row,
                          const gchar *name,
                          const gchar *units,
                          GtkWidget *middle_widget);

Attaches a widget with two labels to a table.

#### Parameters

table | A GtkTable. |
row | Table row to attach to. |
name | The label before `middle_widget` . |
units | The label after `adj` . |
middle_widget | A widget. |

### gwy_table_attach_hscale ()

    GtkWidget *
    gwy_table_attach_hscale (GtkWidget *table,
                             gint row,
                             const gchar *name,
                             const gchar *units,
                             GtkObject *pivot,
                             GwyHScaleStyle style);

Attaches a spinbutton with a scale and labels, or something else, to a table row.

The group of controls takes four table columns: label, scale, spinbutton and units.

You can use functions `gwy_table_hscale_get_scale()`, `gwy_table_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

table | A GtkTable. |
row | Row in `table` 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 table. |

#### Returns

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

### gwy_table_attach_adjbar ()

    GtkWidget *
    gwy_table_attach_adjbar (GtkWidget *table,
                             gint row,
                             const gchar *name,
                             const gchar *units,
                             GtkObject *pivot,
                             GwyHScaleStyle style);

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

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

You can use functions `gwy_table_hscale_get_scale()`, `gwy_table_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

table | A GtkTable. |
row | Row in `table` 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 table. |

#### Returns

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

Since: 2.49

### gwy_table_hscale_set_sensitive ()

    void
    gwy_table_hscale_set_sensitive (GtkObject *pivot,
                                    gboolean sensitive);

Sets sensitivity of a group of controls create by `gwy_table_attach_hscale()` or `gwy_table_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.

This function can also be used with rows created by `gwy_table_attach_spinbutton()` too if the spinbutton is passed as `pivot` .

#### Parameters

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

### gwy_table_hscale_get_scale ()

    GtkWidget *
    gwy_table_hscale_get_scale (GtkObject *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_table_attach_hscale()`. |

### gwy_table_hscale_get_check ()

    GtkWidget *
    gwy_table_hscale_get_check (GtkObject *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_table_attach_hscale()`. |

### gwy_table_hscale_get_label ()

    GtkWidget *
    gwy_table_hscale_get_label (GtkObject *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_table_attach_hscale()`. |

### gwy_table_hscale_get_units ()

    GtkWidget *
    gwy_table_hscale_get_units (GtkObject *pivot);

Gets the units label associated with a pivot object.

May return `NULL` if constructed without units.

#### Parameters

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

### gwy_table_hscale_get_middle_widget ()

    GtkWidget *
    gwy_table_hscale_get_middle_widget (GtkObject *pivot);

Gets the middle widget associated with a pivot object.

#### Parameters

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

### gwy_table_get_child_widget ()

    GtkWidget *
    gwy_table_get_child_widget (GtkWidget *table,
                                gint row,
                                gint col);

Finds a widget in GtkTable by its coordinates.

Coordinates (`col` , `row` ) are taken as coordinates of widget top left corner. More precisely, the returned widget either contains the specified grid point or it is attached by its left side, top side, or top left corner to this point.

If there are multiple matches due to overlapping widgets, a random match is returned.

#### Parameters

table | A GtkTable. |
row | Row in `table` . |
col | Column in `table` . |

#### Returns

The widget at (`col` , `row` ) or `NULL` if there is no such widget.

### gwy_color_selector_for_mask ()

    void
    gwy_color_selector_for_mask (const gchar *dialog_title,
                                 GwyColorButton *color_button,
                                 GwyContainer *container,
                                 const gchar *prefix);

Creates and runs a color selector dialog for a mask.

See `gwy_mask_color_selector_run()` for details.

#### Parameters

dialog_title | Title of the color selection dialog (`NULL` to use default). |
color_button | Color button to update on color change (or `NULL`). |
container | Container to initialize the color from and save it to. |
prefix | Prefix in `container` (normally "/0/mask"). |

### gwy_mask_color_selector_run ()

    void
    gwy_mask_color_selector_run (const gchar *dialog_title,
                                 GtkWindow *parent,
                                 GwyColorButton *color_button,
                                 GwyContainer *container,
                                 const gchar *prefix);

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). |
parent | Dialog parent window. The color selector dialog will be made transient for this window. |
color_button | Color button to update on color change (or `NULL`). |
container | Container to initialize the color from and save it to. |
prefix | Prefix in `container` (normally "/0/mask"). |

Since: 2.1

### 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_hbox_new ()

    GtkWidget *
    gwy_hbox_new (gint spacing);

Creates a new horizontal GtkBox.

This is a lowest common denominator wrapper for creating an inhomogeneous horizontal box. Use `gtk_box_set_homogeneous()` to get a homogeneous box.

#### Parameters

spacing | The number of pixels to place between children by default. |

#### Returns

A new horizontal GtkBox.

Since: 2.59

### gwy_vbox_new ()

    GtkWidget *
    gwy_vbox_new (gint spacing);

Creates a new vertical GtkBox.

This is a lowest common denominator wrapper for creating an inhomogeneous vertical box. Use `gtk_box_set_homogeneous()` to get a homogeneous box.

#### Parameters

spacing | The number of pixels to place between children by default. |

#### Returns

A new vertical GtkBox.

Since: 2.59

### gwy_dialog_prevent_delete_cb ()

    gboolean
    gwy_dialog_prevent_delete_cb (void);

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

Returns `TRUE`.

Use `gtk_true()` instead.

#### Returns

`TRUE`.

### 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_stock_like_button_new ()

    GtkWidget *
    gwy_stock_like_button_new (const gchar *label_text,
                               const gchar *stock_id);

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

#### Parameters

label_text | Button label text (with mnemonic). |
stock_id | Button icon stock id. |

#### Returns

The newly created button as GtkWidget.

### gwy_tool_like_button_new ()

    GtkWidget *
    gwy_tool_like_button_new (const gchar *label_text,
                              const gchar *stock_id);

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

#### Parameters

label_text | Button label text (with mnemonic). |
stock_id | Button icon stock id. |

#### Returns

The newly created button as GtkWidget.

### 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.

Since: 2.5

### 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. |

Since: 2.5

### 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. |

Since: 2.8

### gwy_get_pango_ft2_font_map ()

    PangoFontMap *
    gwy_get_pango_ft2_font_map (gboolean unref);

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

Returns global Pango FT2 font map, eventually creating it.

FT2 portability to Win32 is questionable, use PangoCairo instead.

#### Parameters

unref | If `TRUE`, function removes the font map reference and returns `NULL`. |

#### Returns

Pango FT2 font map. Add your own reference if you want it to never go away.