Highlevel api

GtkFortran High Level API

Window

hl_gtk_window_new

  function hl_gtk_window_new(title, destroy, delete_event, data_destroy, &
       & data_delete_event, border, wsize, sensitive) result(win)

Higher-level interface to make a gtk_window

Argument	Type	Required?	Description
TITLE	String	optional	Title for the window
DESTROY	c_funptr	optional	Callback for the "destroy" signal
DELETE_EVENT	c_funptr	optional	Callback for the "delete-event" signal
DATA_DESTROY	c_ptr	optional	Data to be passed to the destroy signal handler
DATA_DELETE_EVENT	c_ptr	optional	Data to be passed to the delete_event signal handler
BORDER	integer	optional	Size of the window border
WSIZE	integer(2)	optional	Size of the window
SENSITIVE	boolean	optional	Whether the widget should initially be sensitive or not.

Buttons

hl_gtk_button_new

  function hl_gtk_button_new(label, clicked, data, tooltip, sensitive) &
       & result(but)

Higher-level button

Argument	Type	Required?	Description
LABEL	string	required	The label on the button
CLICKED	c_funptr	optional	callback routine for the "clicked" signal
DATA	c_ptr	optional	Data to be passed to the clicked callback
TOOLTIP	string	optional	tooltip to be displayed when the pointer is held over the button.
SENSITIVE	boolean	optional	Whether the widget should initially be sensitive or not.

hl_gtk_check_button_new

  function hl_gtk_check_button_new(label, toggled, data, tooltip, &
       & initial_state, sensitive) result(but)

Higher level check box.

Argument	Type	Required?	Description
LABEL	string	required	The label on the button.
TOGGLED	c_funptr	optional	Callback function for the "toggled" signal.
DATA	c_ptr	optional	Data to pass to/from the toggled callback.
TOOLTIP	string	optional	A tooltip for the check_button.
INITIAL_STATE	integer	optional	set the initial state of the check_button.
SENSITIVE	boolean	optional	Whether the widget should initially be sensitive or not.

hl_gtk_radio_button_new

  function hl_gtk_radio_button_new(group, label, toggled, data, tooltip, &
       & sensitive) result(but)

Radio button

Argument	Type	Required?	Description
GROUP	c_ptr	required	The group to which the button belongs. This is an INOUT argument so it must be a variable of type(c_ptr). To start a new group (menu) initialize the variable to NULL, to add a new button use the value returned from the last call to hl_gtk_radio_button_new. This is the variable which you use to do things like setting the selection.
LABEL	string	required	The label for the button.
TOGGLED	c_funptr	optional	call back to be executed when the button is toggled
DATA	c_ptr	optional	Data to pass to/from the "toggled" callback.
TOOLTIP	string	optional	A tooltip for the radio button
SENSITIVE	boolean	optional	Whether the widget should initially be sensitive or not.

hl_gtk_radio_group_set_select

  subroutine hl_gtk_radio_group_set_select(group, index)

Set the indexth button of a radio group

Argument	Type	Required?	Description
GROUP	c_ptr	required	The group of the last button added to the radio menu
INDEX	integer	required	The index of the button to set (starting from the first as 0).

hl_gtk_radio_group_get_select

  function hl_gtk_radio_group_get_select(group) result(index)

Find the selected button in a radio group.

Argument	Type	Required?	Description
GROUP	c_ptr	required	The group of the last button added to the radio menu

Text Entry

hl_gtk_entry_new

  function hl_gtk_entry_new(len, editable, activate, data, tooltip, value, &
       & sensitive) result(entry)

Higher level text entry box

Argument	Type	Required?	Description
LEN	integer	optional	The maximum length of the entry field.
EDITABLE	boolean	optional	whether the entry box can be edited by the user
ACTIVATE	c_funptr	optional	Callback function for the "activate" signal
DATA	c_ptr	optional	Data to be passed to the activate callback
TOOLTIP	string	optional	tooltip to be displayed when the pointer is held over the button.
VALUE	string	optional	An initial value for the entry box.
SENSITIVE	boolean	optional	Whether the widget should initially be sensitive or not.

hl_gtk_entry_get_text

  subroutine hl_gtk_entry_get_text(entry, text, status)

Return the text in an entry box as a fortran string.

Argument	Type	Required?	Description
ENTRY	c_ptr	required	The text entry to read
TEXT	f_string	required	The text read.
STATUS	c_int	optional	Returns -1 if the string is truncated.

To return the text as a c-pointer use gtk_entry_get_text

List1

This is a single column list based on the GtkTreeView widget system.

hl_gtk_list1_new

  function hl_gtk_list1_new(scroll, width, changed, data, multiple, &
       & sensitive, tooltip, title, height) result(list)

A single column selectable list based on the GTK Tree View

Argument	Type	Required?	Description
SCROLL	c_ptr	required	The scroll box containing the list (used for packing etc.)
WIDTH	integer	optional	The width of the displayed column.
CHANGED	c_funptr	optional	Callback function for the "changed" signal to the associated selection object.
DATA	c_ptr	optional	Data to be passed to/from the callback.
MULTIPLE	boolean	optional	Whether multiple selections are allowed.
SENSITIVE	boolean	optional	Whether the widget is intially sensitive.
TOOLTIP	string	optional	Tooltip for the widget
TITLE	string	optional	Title for the visible column.
HEIGHT	integer	optional	The height of the display (this is actually the height of the scroll box).

hl_gtk_list1_ins

  subroutine hl_gtk_list1_ins(list, text, row)

Insert a row into a list

Argument	Type	Required?	Description
LIST	c_ptr	required	The list to insert to.
TEXT	string	required	The text to insert.
ROW	integer	optional	The row at which to insert the text (omit to append)

hl_gtk_list1_rem

  subroutine hl_gtk_list1_rem(list, row)

Remove a row or clear a list

Argument	Type	Required?	Description
LIST	c_ptr	required	The list to modify
ROW	integer	optional	The row to remove, if absent clear the list

hl_gtk_list1_get_selections

  function hl_gtk_list1_get_selections(list, indices, selection) result(count)

Get the indices of the selected rows

Argument	Type	Required?	Description
LIST	c_ptr	required	The list whose selections are to be found.
INDICES	integer	optional	An allocatable array to return the list of selections. (If count = 0 it will not be allocated). If this argument is not given, then the number of selected rows is returned.
SELECTION	c_ptr	optional	A selection. If this is given then LIST is ignored. This is most often used in the callback routine for the changed signal when that needs to find which element(s) are selected.

Returns the number of selections.

Pulldown Menu

hl_gtk_menu_new

  function hl_gtk_menu_new(orientation) result(menu)

Menu initializer (mainly for consistency)

Argument	Type	Required?	Description
ORIENTATION	integer	optional	Whether to lay out the top level horizontaly or vertically.

hl_gtk_menu_submenu_new

  function hl_gtk_menu_submenu_new(menu, label, tooltip, pos) result(submenu)

Make a submenu node

Argument	Type	Required?	Description
MENU	c_ptr	required	The parent of the submenu
LABEL	string	required	The label of the submenu
TOOLTIP	string	optional	A tooltip for the submenu.
POS	integer	optional	The position at which to insert the item (omit to append)

hl_gtk_menu_item_new

  function hl_gtk_menu_item_new(menu, label, activate, data, tooltip, pos) &
       & result(item)

Make a menu item or separator

Argument	Type	Required?	Description
MENU	c_ptr	required	The parent menu.
LABEL	string	optional	The label for the menu, if absent then insert a separator.
ACTIVATE	c_funptr	optional	The callback function for the activate signal
DATA	c_ptr	optional	Data to pass to the callback.
TOOLTIP	string	optional	A tooltip for the menu item.
POS	integer	optional	The position at which to insert the item (omit to append)

Progress Bar

hl_gtk_progress_bar_new

  function hl_gtk_progress_bar_new(vertical, reversed, step) result(bar)

Intializer for a progress bar

Argument	Type	Required?	Description
ORIENTATION	integer	optional	The orientation of the bar.
STEP	double	optional	The fractional step to advance when pulsing the bar

hl_gtk_progress_bar_set_f

  subroutine hl_gtk_progress_bar_set_f(bar, val, string, text)

Set the value of a progress bar (fraction or pulse)

Argument	Type	Required?	Description
BAR	c_ptr	required	The bar to set
VAL	double	optional	The value to set. If absent, the bar is pulsed
STRING	boolean	optional	Whether to put a string on the bar.
TEXT	string	optional	Text to put in the bar, (overrides STRING)

This routine is normally accessed via the generic interface hl_gtk_progress_bar

hl_gtk_progress_bar_set_ii

  subroutine hl_gtk_progress_bar_set_ii(bar, val, maxv, string, text)

Set the value of a progress bar (n of m)

Argument	Type	Required?	Description
BAR	c_ptr	required	The bar to set
VAL	int	required	The value to set.
MAXV	int	required	The maximum value for the bar
STRING	boolean	optional	Whether to put a string on the bar.
TEXT	string	optional	Text to put in the bar, (overrides STRING)

This routine is normally accessed via the generic interface hl_gtk_progress_bar

Dialogue

The message dialogue provided is here because, the built-in message dialogue GtkMessageDialog cannot be created without calling variadic functions which are not compatible with Fortran, therefore this is based around the plain GtkDialog family.

hl_gtk_message_dialog_show

  function hl_gtk_message_dialog_show(message, button_set, title) &
       & result(resp)

A DIY version of the message dialogue, needed because both creators for the built in one are variadic and so not callable from Fortran.

Argument	Type	Required?	Description
MESSAGE	string(n)	required	The message to display. Since this is a string array, the CNULL terminations are provided internally
BUTTON_SET	integer	required	The set of buttons to display
TITLE	string	optional	Title for the window.

The return value is the response code, not the widget.

Box

A simplified way to make vertical or horizontal boxes This was added because the gtk_box_pack_start_defaults procedure is removed from GTK3.x

hl_gtk_box_new

  function hl_gtk_box_new(horizontal, homogeneous, spacing) result(box)

Generic packing box

Argument	Type	Required?	Description
HORIZONTAL	boolean	optional	Set to TRUE to make a row box. FALSE or absent implies a column box.
HOMOGENEOUS	boolean	optional	If set to TRUE then all children are the same size, FALSE or absent allows each widget to take its natural size.
SPACING	c_int	optional	Set the space between children.

hl_gtk_box_pack

  subroutine hl_gtk_box_pack(box, child, expand, fill, padding, atend)

Put a widget into a box

Argument	Type	Required?	Description
BOX	c_ptr	required	The box into which to put the child
CHILD	c_ptr	required	The child to pack
EXPAND	boolean	optional	If TRUE then expand this child when filling the box, if FALSE don't, (Default TRUE)
FILL	boolean	optional	If TRUE, then expand the widget when expanding, if FALSE, then put space round it. (Default TRUE, ignored if EXPAND==FALSE.
PADDING	c_int	optional	Extra space to put around the child in the fill direction.
ATEND	boolean	optional	If present and TRUE, then put the child at the end of the box rather than the start.

Sliders and Spin buttons

GTK sliders and spin buttons use floating point values, the HL interface implements an automatic interface selection between a floating point or an integer slider.

Although they belong to completely different widget families in GTK, the interfaces are very similar, which is why they are grouped together here.

hl_gtk_slider_flt_new

  function hl_gtk_slider_flt_new(vmin, vmax, step, vertical, initial_value, &
       & value_changed, data, digits, sensitive, tooltip, draw, length) &
       & result(slider)

Floating point version of a slider

Argument	Type	Required?	Description
VMIN	c_double	required	The minimum value for the slider
VMAX	c_double	required	The maximum value for the slider
STEP	c_double	required	The step for the slider.
VERTICAL	boolean	optional	if TRUE then a vertical slider is created if FALSE or absent, then a horizontal silder is created.
INITIAL_VALUE	c_double	optional	Set the intial value of the slider
VALUE_CHANGED	c_funptr	optional	Callback function for the "value-changed" signal.
DATA	c_ptr	optional	User data to pass the the value_changed callback.
DIGITS	c_int	optional	Number of decimal places to show.
SENSITIVE	boolean	optional	Whether the widget is created in the sensitive state.
TOOLTIP	string	optional	A tooltip to display.
DRAW	boolean	optional	Set to FALSE to suppress writing the value.
LENGTH	c_int	optional	Set the length of the slider in pixels

This routine is usually called via its generic interface hl_gtk_slider_new

hl_gtk_slider_int_new

  function hl_gtk_slider_int_new(imin, imax, vertical, initial_value, &
       & value_changed, data, sensitive, tooltip, draw, length) result(slider)

Floating point version of a slider

Argument	Type	Required?	Description
IMIN	c_int	required	The minimum value for the slider
IMAX	c_int	required	The maximum value for the slider
VERTICAL	boolean	optional	if TRUE then a vertical slider is created if FALSE or absent, then a horizontal silder is created.
INITIAL_VALUE	c_int	optional	Set the intial value of the slider
VALUE_CHANGED	c_funptr	optional	Callback function for the "value-changed" signal.
DATA	c_ptr	optional	User data to pass the the value_changed callback.
SENSITIVE	boolean	optional	Whether the widget is created in the sensitive state.
TOOLTIP	string	optional	A tooltip to display.
DRAW	boolean	optional	Set to FALSE to suppress writing the value.
LENGTH	c_int	optional	Set the length of the slider in pixels

This routine is usually called via its generic interface hl_gtk_slider_new

hl_gtk_slider_get_value

  function hl_gtk_slider_get_value(slider) result(val)

Get the value of a slider

Argument	Type	Required?	Description
SLIDER	c_ptr	required	The slider to read.

Note even for an integer slider we get a float value but there's no problem letting Fortran do the truncation

hl_gtk_slider_set_flt

  subroutine hl_gtk_slider_set_flt(slider, val)

Set a floating point value for a slider

Argument	Type	Required?	Description
SLIDER	c_ptr	required	The slider to set.
VAL	c_double	required	The value to set.

This is usually accessed via the generic interface hl_gtk_slider_set_value

hl_gtk_slider_set_int

  subroutine hl_gtk_slider_set_int(slider, val)

Set a floating point value for a slider

Argument	Type	Required?	Description
SLIDER	c_ptr	required	The slider to set.
VAL	c_int	required	The value to set.

This is usually accessed via the generic interface hl_gtk_slider_set_value

hl_gtk_spin_button_flt_new

  function hl_gtk_spin_button_flt_new(vmin, vmax, step, initial_value, &
       & value_changed, data, digits, sensitive, tooltip, wrap) &
       & result(spin_button)

Floating point version of a spin_button

Argument	Type	Required?	Description
VMIN	c_double	required	The minimum value for the spin_button
VMAX	c_double	required	The maximum value for the spin_button
STEP	c_double	required	The step for the spin_button.
INITIAL_VALUE	c_double	optional	Set the intial value of the spin_button
VALUE_CHANGED	c_funptr	optional	Callback function for the "value-changed" signal.
DATA	c_ptr	optional	User data to pass the the value_changed callback.
DIGITS	c_int	optional	Number of decimal places to show.
SENSITIVE	boolean	optional	Whether the widget is created in the sensitive state.
TOOLTIP	string	optional	A tooltip to display.
WRAP	boolean	optional	If set to TRUE then wrap around if limit is exceeded

This routine is usually called via its generic interface hl_gtk_spin_button_new

hl_gtk_spin_button_int_new

  function hl_gtk_spin_button_int_new(imin, imax, initial_value, &
       & value_changed, data, sensitive, tooltip, wrap) result(spin_button)

Floating point version of a spin_button

Argument	Type	Required?	Description
IMIN	c_int	required	The minimum value for the spin_button
IMAX	c_int	required	The maximum value for the spin_button
INITIAL_VALUE	c_int	optional	Set the intial value of the spin_button
VALUE_CHANGED	c_funptr	optional	Callback function for the "value-changed" signal.
DATA	c_ptr	optional	User data to pass the the value_changed callback.
SENSITIVE	boolean	optional	Whether the widget is created in the sensitive state.
TOOLTIP	string	optional	A tooltip to display.
WRAP	boolean	optional	If set to TRUE then wrap around if limit is exceeded

This routine is usually called via its generic interface hl_gtk_spin_button_new

hl_gtk_spin_button_get_value

  function hl_gtk_spin_button_get_value(spin_button) result(val)

Get the value of a spin_button

Argument	Type	Required?	Description
SPIN_BUTTON	c_ptr	required	The spin_button to read.

Note even for an integer spin_button we get a float value but there's no problem letting Fortran do the truncation

hl_gtk_spin_button_set_flt

  subroutine hl_gtk_spin_button_set_flt(spin_button, val)

Set a floating point value for a spin_button

Argument	Type	Required?	Description
SPIN_BUTTON	c_ptr	required	The spin_button to set.
VAL	c_double	required	The value to set.

This is usually accessed via the generic interface hl_gtk_spin_button_set_value

hl_gtk_spin_button_set_int

  subroutine hl_gtk_spin_button_set_int(spin_button, val)

Set a floating point value for a spin_button

Argument	Type	Required?	Description
SPIN_BUTTON	c_ptr	required	The spin_button to set.
VAL	c_int	required	The value to set.

This is usually accessed via the generic interface hl_gtk_spin_button_set_value

Multi-line text box

This is based around the GtkTextView widget family. The HL interface hides the text buffer from the user, except in some callbacks where the signal is attached to the buffer not the view.

If you do need to access the text buffer directly it can be obtained with the gtk_text_view_get_buffer function, or it can be returned via the optional BUFFER argument to the constructor.

hl_gtk_text_view_new

  function hl_gtk_text_view_new(scroll, editable, changed, data_changed, &
       & insert_text, data_insert_text, delete_range, data_delete_range, &
       & initial_text, sensitive, tooltip, ssize, buffer) result(view)

A multiline text edit widget

Argument	Type	Required?	Description
SCROLL	c_ptr	optional	A scrolled window in which the text editor is placed. If it is present, then it must be used used for packing the widget into your application. If it is not used, then scroll bars will not be added if the text goes beyond the edge of the box.
EDITABLE	boolean	optional	Set to FALSE to make a non-editable text box.
CHANGED	c_funptr	optional	Callback for the "activate" signal.
DATA_CHANGED	c_ptr	optional	User data to pass to/from the activate callback
INSERT_TEXT	c_funptr	optional	Callback for the "insert-text" signal. This handler is attached to the text buffer not the text view.
DATA_INSERT_TEXT	c_ptr	optional	User data for the insert-text callback.
DELETE_RANGE	c_funptr	optional	Callback for the "delete-range" signal. This handler is attached to the text buffer not the text view.
DATA_DELETE_RANGE	c_ptr	optional	User data for the delete-range callback.
INITIAL_TEXT	string()	optional	Initial text to put in the text window.
SENSITIVE	boolean	optional	Set to FALSE to make the widget start in an insensitive state.
TOOLTIP	string	optional	A tooltip to display when the pointer is held over the widget.
SSIZE	c_int(2)	optional	Size of the scroll widget.
BUFFER	c_ptr	optional	Variable to return the buffer pointer/

NOTE -- The insert-text and delete-range callbacks take extra arguments. They are called before the buffer is actually modified. The changed callback is called after the change.

hl_gtk_text_view_insert

  subroutine hl_gtk_text_view_insert(view, text, line, column, replace, &
       & at_cursor, buffer)

Insert text to an text view

Argument	Type	Required?	Description
VIEW	c_ptr	required	The text view into which to insert.
TEXT	string()	required	The text to insert.
LINE	c_int	optional	The line at which to insert (if omitted, then the text is appended).
COLUMN	c_int	optional	The column as which to insert the text (If omitted, then insert at the start of the line).
REPLACE	boolean	optional	If set to TRUE and LINE and COLUMN are omitted then replace the text in the buffer.
AT_CURSOR	boolean	optional	Set to TRUE to insert the text at the cursor.
BUFFER	c_ptr	optional	The text buffer in which to insert the text If this is given, then VIEW is ignored -- used in signal handlers attached to the buffer.

hl_gtk_text_view_delete

  subroutine hl_gtk_text_view_delete(view, line, column, n_chars, n_lines, &
       & buffer)

Delete from a text view

Argument	Type	Required?	Description
VIEW	c_ptr	required	The text view from which to delete.
LINE	c_int	optional	The line at which to start the deletion
COLUMN	c_int	optional	The column at which to start the deletion. required if N_CHARS is given. Ignored if N_LINES is given.
N_CHARS	c_int	optional	How many characters to delete.
N_LINES	c_int	optional	How many lines to delete.
BUFFER	c_ptr	optional	The text buffer from which to delete. If this is given, then VIEW is ignored, used in signal handlers attached to the buffer.

If no location specifiers are given then the buffer is cleared

hl_gtk_text_view_get_text

  subroutine hl_gtk_text_view_get_text(view, text, start_line, start_column, &
       & end_line, end_column, hidden, buffer)

Get text from s text view.

Argument	Type	Required?	Description
VIEW	c_ptr	required	The text view to read.
TEXT	string()	required	A variable to contain the output text.
START_LINE	c_int	optional	The first line to read.
START_COLUMN	c_int	optional	The column at which to start reading.
END_LINE	c_int	optional	The last line to read.
END_COLUMN	c_int	optional	The column at which to stop reading.
HIDDEN	boolean	optional	If set to FALSE, then do not get hidden characters
BUFFER	c_ptr	optional	The text buffer from which to read. If this is given, then VIEW is ignored, useful for signal handlers attached to the buffer.

Note the rules for selection.

• If no selection arguments are present, the whole text is returned.
• If either start_column or end_column is absent, but the matching line is present, then selection is by line.
• If end_line is absent, but both columns are present, then the selection is within start_line
• If neither start_line nor start_column is present, then the selection is from the start of the buffer
• If neither end_line nor end_column is present, then the selection is to the end of the buffer.

hl_gtk_text_view_get_cursor

  function hl_gtk_text_view_get_cursor(view, buffer) result(ipos)

Get the current cursor location

Argument	Type	Required?	Description
VIEW	c_ptr	required	The text view to query
BUFFER	c_ptr	optional	The buffer to query (if given, then VIEW is ignored).

Returns a 3-element array with the line, column and offset of the cursor

hl_gtk_text_view_get_selection

  function hl_gtk_text_view_get_selection(view, s_start, s_end, buffer) &
       & result(issel)

Get the selection range

Argument	Type	Required?	Description
VIEW	c_ptr	required	The text view to query.
S_START	c_int()	required	The start of the selection. (line, column, offset)
S_END	c_int()	required	The end of the selection. (line, column, offset)
BUFFER	c_ptr	optional	The text buffer to query. If present, then the view argument is ignored.

Returns TRUE if there is a selection, FALSE if there isn't

hl_gtk_text_view_get_modified

  function hl_gtk_text_view_get_modified(view) result(ismod)

Check if the buffer of a text view is modified

Argument	Type	Required?	Description
VIEW	c_ptr	required	The text view to check.

N.B. No BUFFER argument is provided as gtk_text_buffer_get_modified is just a single call

hl_gtk_text_view_set_modified

  subroutine hl_gtk_text_view_set_modified(view, state)

Set/clear the modified flag on the text buffer of a text view

Argument	Type	Required?	Description
VIEW	c_ptr	required	The text view to set
STATE	boolean	required	The state to set the flag to.

hl_gtk_text_view_get_info

  subroutine hl_gtk_text_view_get_info(view, nlines, nchars, ncline, buffer)

Get various useful information about a text view

Argument	Type	Required?	Description
VIEW	c_ptr	required	The view to query
NLINES	c_int	optional	Return the number of lines in the view
NCHARS	c_int	optional	Return the number of characters in the view
NCLINE	c_int()	optional	Return the nuber of characters in each line. Must be an allocatable array.
BUFFER	c_ptr	optional	If present use this buffer and ignore the VIEW argument