Reference

button(label; widget=nothing, observable=nothing)
button(; label=nothing, widget=nothing, observable=nothing)

Create a push button with text-label label. Optionally provide:

• a GtkButton widget (by default, creates a new one)
• the (Observables.jl) observable coupled to this button (by default, creates a new observable)

checkbox(value=false; widget=nothing, observable=nothing, label="")

Provide a checkbox with the specified starting (boolean) value. Optionally provide:

• a GtkCheckButton widget (by default, creates a new one)
• the (Observables.jl) observable coupled to this checkbox (by default, creates a new observable)
• a display label for this widget

togglebutton(value=false; widget=nothing, observable=nothing, label="")

Provide a togglebutton with the specified starting (boolean) value. Optionally provide:

• a widget (by default, creates a new GtkToggleButton)
• the (Observables.jl) observable coupled to this button (by default, creates a new observable)
• a display label for this widget

slider(range; widget=nothing, value=nothing, observable=nothing, orientation="horizontal", snap=false)

Create a slider widget with the specified range. Optionally provide:

• the GtkScale widget (by default, creates a new one)
• the starting value (defaults to the median of range)
• the (Observables.jl) observable coupled to this slider (by default, creates a new observable)
• the orientation of the slider.
• whether to snap the slider value to an element of range.

textbox(value; widget=nothing, observable=nothing, range=nothing, syncsig=true, own=nothing, gtksignal="activate")
textbox(T::Type; widget=nothing, value=nothing, observable=nothing, range=nothing, syncsig=true, own=nothing, gtksignal="activate")

Create a box for entering text. value is the starting value, and its type determines the type of the entry; if you don't want to provide an initial value, you can constrain the type with T. Optionally specify the allowed range (e.g., -10:10) for numeric entries, and/or provide the (Observables.jl) observable coupled to this text box. Entries that cannot be parsed as the required type revert to the previous value, and numeric entries are rounded to the nearest element of range.

gtksignal is a String naming the Gtk4 signal that triggers updating the observable: "activate" (the default; pressing Enter), "changed" (every edit; not supported for numeric types), or "focus-leave" (the entry losing keyboard focus).

textarea(value=""; widget=nothing, observable=nothing)

Creates an extended text-entry area. Optionally provide a GtkTextView widget and/or the (Observables.jl) observable associated with this widget. The observable updates when you type.

dropdown(choices; widget=nothing, value=nothing, observable=nothing, own=nothing)
dropdown(; choices, widget=nothing, value=nothing, observable=nothing, own=nothing)

Create a "dropdown" widget. choices can be a vector (or other iterable) of options. These options might either be a list of strings, or a list of choice::String => func pairs so that an action encoded by func can be taken when choice is selected.

Optionally specify

• the GtkComboBoxText widget (by default, creates a new one)
• the starting value; if it is nothing (the default), the first choice is selected
• the observable coupled to this dropdown (by default, creates a new observable)

Examples

dd = dropdown(["one", "two", "three"])

To link a callback to the dropdown, use

dd = dropdown(("turn red"=>colorize_red, "turn green"=>colorize_green))
on(dd.mappedsignal) do cb
    cb(img)                     # img is external data you want to act on
end

cb does not fire for the initial value of dd; if this is desired, manually execute dd[] = dd[] after defining this action.

dd.mappedsignal is a function-observable only for the pairs syntax for choices.

player(range; style="with-textbox", id=1)
player(slice::Observable, range; style="with-textbox", id=1)

Create a movie-player widget for the integer range and return a Player; frame(p) gives the GtkFrame holding the widget. The player's observable holds the currently selected index; pass your own Observable slice to couple the player to it.

The only supported style is "with-textbox", which provides play, play backwards, stop, and step forward/backward buttons, a slider, and a textbox for entering a slice by keyboard.

You can create up to two player widgets for the same GUI, as long as you pass id=1 and id=2, respectively.

label(value; widget=nothing, observable=nothing)

Create a text label displaying value as a string. Optionally specify

• the GtkLabel widget (by default, creates a new one)
• the (Observables.jl) observable coupled to this label (by default, creates a new observable)

canvas(U=DeviceUnit, w=-1, h=-1; init_back=false, modifier_ref=nothing) -> c::GtkObservables.Canvas
canvas(w, h; init_back=false, modifier_ref=nothing) -> c::GtkObservables.Canvas

Create a canvas for drawing and interaction. Optionally specify the width w and height h. U refers to the units for the canvas (for both drawing and reporting mouse pointer positions), see DeviceUnit and UserUnit. init_back=true creates the canvas's image surface immediately, which is useful for precompilation. modifier_ref is a Ref holding the keyboard-modifier state reported in mouse events; it exists so tests can simulate events. See also GtkObservables.Canvas.

GtkObservables.Canvas{U}(w=-1, h=-1; own=true, init_back=false, modifier_ref=nothing)

Create a canvas for drawing and interaction. The keyword arguments are described under canvas. The relevant fields are:

• widget: the "raw" Gtk widget (from Gtk4.jl)
• mouse: the MouseHandler{U} for this canvas.

The canvas provides the actions canvas.save (write the image to a PNG file) and canvas.copy (copy the image to the clipboard), which can be attached to menus or shortcuts.

See also canvas.

MouseHandler{U<:CairoUnit}

A type with Observable fields for which you can map callback actions. The fields are:

• buttonpress for clicks (of type MouseButton);
• buttonrelease for release events (of type MouseButton);
• motion for move and drag events (of type MouseButton);
• scroll for wheelmouse or track-pad actions (of type MouseScroll);

U should be either DeviceUnit or UserUnit and determines the coordinate system used for reporting mouse positions.

DeviceUnit(x)

Represent a number x as having "device" units (aka, screen pixels). See the Cairo documentation.

UserUnit(x)

Represent a number x as having "user" units, i.e., whatever units have been established with calls that affect the transformation matrix, e.g., Graphics.set_coordinates or Cairo.set_matrix.

XY(x, y)

A type to hold x (horizontal), y (vertical) coordinates, where the number increases to the right and downward. If used to encode mouse pointer positions, the units of x and y are either DeviceUnit or UserUnit.

MouseButton(position, button, clicktype, modifiers, n_press=1)

A type to hold information about a mouse button event (e.g., a click). position is the canvas position of the pointer (see XY). button is an integer identifying the button, where 1=left button, 2=middle button, 3=right button. clicktype may be BUTTON_PRESS or BUTTON_RELEASE. modifiers indicates whether any keys were held down during the click; they may be any combination of SHIFT, CONTROL, or MOD1 stored as a bitfield (test with btn.modifiers & SHIFT). Multiple clicks can be handled by setting the n_press argument. For example, a double click event corresponds to n_press=2.

The fieldnames are the same as the argument names above.

MouseButton{UserUnit}()
MouseButton{DeviceUnit}()

Create a "dummy" MouseButton event, useful as the initial value of an Observable that will later hold events.

MouseScroll(position, direction, modifiers)

A type to hold information about a mouse wheel scroll. position is the canvas position of the pointer (see XY). direction may be UP, DOWN, LEFT, or RIGHT. modifiers indicates whether any keys were held down during the scroll; they may be 0 (no modifiers) or any combination of SHIFT, CONTROL, or MOD1 stored as a bitfield.

MouseScroll{UserUnit}()
MouseScroll{DeviceUnit}()

Create a "dummy" MouseScroll event, useful as the initial value of an Observable that will later hold events.

SHIFT

Modifier flag for the SHIFT key. The modifiers field of a MouseButton or MouseScroll event is a bitfield, so test for a key with (evt.modifiers & SHIFT) == SHIFT. See also CONTROL and MOD1.

CONTROL

Modifier flag for the CONTROL key. The modifiers field of a MouseButton or MouseScroll event is a bitfield, so test for a key with (evt.modifiers & CONTROL) == CONTROL. See also SHIFT and MOD1.

MOD1

Modifier flag for the ALT key. The modifiers field of a MouseButton or MouseScroll event is a bitfield, so test for a key with (evt.modifiers & MOD1) == MOD1. See also SHIFT and CONTROL.

BUTTON_PRESS

Value of the clicktype field of a MouseButton event generated by pressing a mouse button.

BUTTON_RELEASE

Value of the clicktype field of a MouseButton event generated by releasing a mouse button.

UP

Value of the direction field of a MouseScroll event for an upward scroll. See also DOWN, LEFT, and RIGHT.

DOWN

Value of the direction field of a MouseScroll event for a downward scroll. See also UP, LEFT, and RIGHT.

LEFT

Value of the direction field of a MouseScroll event for a leftward scroll. See also UP, DOWN, and RIGHT.

RIGHT

Value of the direction field of a MouseScroll event for a rightward scroll. See also UP, DOWN, and LEFT.

ZoomRegion(fullinds) -> zr
ZoomRegion(fullinds, currentinds) -> zr
ZoomRegion(img) -> zr
ZoomRegion(fullview::XY, currentview::XY) -> zr
ZoomRegion(fullview::XY, bb::BoundingBox) -> zr

Create a ZoomRegion object zr for selecting a rectangular region-of-interest for zooming and panning. fullinds and currentinds should be pairs (yrange, xrange) of integer unit ranges. Pass an array img to take the indices from axes(img). fullview and currentview are XY objects holding ClosedIntervals; if bb is provided, the current view is set to it.

zr.currentview holds the currently-active region of interest. zr.fullview stores the original fullinds from which zr was constructed; these are used to reset to the original limits and to confine zr.currentview.

pan_x(zr::ZoomRegion, frac) -> zr_new

Pan the x-axis by a fraction frac of the current x-view. frac>0 means that the coordinates shift right, which corresponds to a leftward shift of objects.

pan_y(zr::ZoomRegion, frac) -> zr_new

Pan the y-axis by a fraction frac of the current y-view. frac>0 means that the coordinates shift downward, which corresponds to an upward shift of objects.

zoom(zr::ZoomRegion, scaleview, pos::XY) -> zr_new

Zooms in (scaleview < 1) or out (scaleview > 1) by a scaling factor scaleview, in a manner centered on pos.

zoom(zr::ZoomRegion, scaleview)

Zooms in (scaleview < 1) or out (scaleview > 1) by a scaling factor scaleview, in a manner centered around the current view region.

signals = init_zoom_rubberband(canvas::GtkObservables.Canvas,
                               zr::Observable{ZoomRegion},
                               initiate = btn->(btn.button == 1 && btn.clicktype == BUTTON_PRESS && btn.n_press == 1 && (btn.modifiers & CONTROL) == CONTROL),
                               reset = btn->(btn.button == 1 && btn.clicktype == BUTTON_PRESS && btn.n_press == 2 && (btn.modifiers & CONTROL) == CONTROL),
                               minpixels = 2)

Initialize rubber-band selection that updates zr. signals is a dictionary holding the Observables.jl signals needed for rubber-banding. Push true/false to signals["enabled"] to turn rubber banding on and off, respectively; signals["active"] is true while a selection is in progress. The remaining entries ("init", "drag", and "finish") are the mouse-event handlers. Your application is responsible for making sure that signals does not get garbage-collected (which would turn off rubberbanding).

initiate(btn) returns true when the condition for starting a rubber-band selection has been met (by default, clicking mouse button 1 while holding the CONTROL key). The argument btn is a MouseButton event. reset(btn) returns true when restoring the full view (by default, double-clicking mouse button 1 while holding the CONTROL key). minpixels can be used for aborting rubber-band selections smaller than some threshold.

signals = init_zoom_scroll(canvas::GtkObservables.Canvas,
                           zr::Observable{ZoomRegion},
                           filter::Function = evt->(evt.modifiers & CONTROL) == CONTROL,
                           focus::Symbol = :pointer,
                           factor = 2.0,
                           flip = false)

Initialize zooming-by-mouse-scroll for canvas and update zr. signals is a dictionary holding the signals needed for scroll-zooming; you can push true/false to signals["enabled"] to turn scroll-zooming on and off, respectively. The "zoom" entry is the scroll handler. Your application is responsible for making sure that signals does not get garbage-collected (which would turn off scroll-zooming).

filter is a function that returns true when the conditions for scroll-zooming are met; the argument is a MouseScroll event. The default is to hold down the CONTROL key while scrolling the mouse.

The focus argument controls how the zooming progresses as you scroll the mouse wheel. :pointer means that whatever feature of the canvas is under the pointer will stay there as you zoom in or out. The other choice, :center, keeps the canvas centered on its current location.

Each scroll step scales the visible region by factor; scrolling up zooms in and scrolling down zooms out. Pass flip=true to reverse the direction.

signals = init_pan_drag(canvas::GtkObservables.Canvas,
                        zr::Observable{ZoomRegion},
                        initiate = btn->(btn.button == 1 && btn.clicktype == BUTTON_PRESS && (btn.modifiers & CONTROL) == 0))

Initialize click-drag panning that updates zr. signals is a dictionary holding the signals needed for pan-drag: signals["active"] is true while a drag is in progress, and the "init", "drag", and "finish" entries are the mouse-event handlers. Your application is responsible for making sure that signals does not get garbage-collected (which would turn off pan-dragging).

initiate(btn) returns true when the condition for starting click-drag panning has been met (by default, clicking mouse button 1 without holding the CONTROL key, which is reserved for zooming). The argument btn is a MouseButton event.

signals = init_pan_scroll(canvas::GtkObservables.Canvas,
                          zr::Observable{ZoomRegion},
                          filter_x::Function = evt->(evt.modifiers & SHIFT) == SHIFT || evt.direction == LEFT || evt.direction == RIGHT,
                          filter_y::Function = evt->(evt.modifiers & SHIFT) == 0 && (evt.direction == UP || evt.direction == DOWN),
                          xpanflip = false,
                          ypanflip  = false)

Initialize panning-by-mouse-scroll for canvas and update zr. signals is a dictionary holding the Observables.jl signals needed for scroll-panning; you can push true/false to signals["enabled"] to turn scroll-panning on and off, respectively. The "pan" entry is the scroll handler. Your application is responsible for making sure that signals does not get garbage-collected (which would turn off scroll-panning).

filter_x and filter_y are functions that return true when the conditions for x- and y-scrolling are met; the argument is a MouseScroll event. By default, vertical scrolling pans in y when SHIFT is not held, whereas scrolling while holding down the SHIFT key, or scrolling horizontally, pans in x. Scroll events with the CONTROL key held are ignored, since they are reserved for zooming.

You can flip the direction of either pan operation with xpanflip and ypanflip, respectively.

observable(w) -> obs

Return the Observable obs associated with widget w.

frame(w) -> f

Return the GtkFrame f associated with widget w.

gc_preserve(widget::GtkWidget, obj)

Preserve obj until widget has been destroyed.