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 GtkCheckButton widget (by default, creates a new one)
• 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")

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.

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

Create a box for entering text. value is the starting value; 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. Finally, you can specify which Gtk observable (e.g. activate, changed) you'd like the widget to update with.

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=first(choices), observable=nothing, label="", with_entry=true, icons, tooltips)

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
• the (Observables.jl) observable coupled to this slider (by default, creates a new observable)
• whether the widget should allow text entry

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{Int}, range; style="with-textbox", id=1)

Create a movie-player widget. This includes the standard play and stop buttons and a slider; style "with-textbox" also includes play backwards, step forward/backward, 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) - 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. See also GtkObservables.Canvas.

GtkObservables.Canvas{U}(w=-1, h=-1, own=true)

Create a canvas for drawing and interaction. The relevant fields are:

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

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. Often useful for the fallback to Observables's filterwhen.

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 click; 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. Often useful for the fallback to Observables's filterwhen.

ZoomRegion(fullinds) -> zr
ZoomRegion(fullinds, currentinds) -> zr
ZoomRegion(img::AbstractMatrix) -> zr

Create a ZoomRegion object zr for selecting a rectangular region-of-interest for zooming and panning. fullinds should be a pair (yrange, xrange) of indices, an XY object, or pass a matrix img from which the indices will be taken.

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 x-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),
                               reset = btn->(btn.button == 1 && btn.clicktype == BUTTON_PRESS && btn.n_press == 2 && btn.modifiers == CONTROL),
                               minpixels = 2)

Initialize rubber-band selection that updates zr. signals is a dictionary holding the Observables.jl signals needed for rubber-banding; you can push true/false to signals["enabled"] to turn rubber banding on and off, respectively. 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). The argument btn is a MouseButton event. reset(btn) returns true when restoring the full view (by default, double-clicking mouse button 1). 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,
                           focus::Symbol = :pointer,
                           factor = 2.0,
                           flip = false)

Initialize zooming-by-mouse-scroll for canvas and update zr. signals is a dictionary holding the Observables.jl signals needed for scroll-zooming; you can push true/false to signals["enabled"] to turn scroll-zooming on and off, respectively. 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 keyword 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.

You can change the amount of zooming via factor and the direction of zooming with flip.

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

Initialize click-drag panning that updates zr. signals is a dictionary holding the Observables.jl signals needed for pan-drag; you can push true/false to signals["enabled"] to turn it on and off, respectively. 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). The argument btn is a MouseButton event.

signals = init_pan_scroll(canvas::GtkObservables.Canvas,
                          zr::Observable{ZoomRegion},
                          filter_x::Function = evt->evt.modifiers == SHIFT || event.direction == LEFT || event.direction == RIGHT,
                          filter_y::Function = evt->evt.modifiers == 0 || event.direction == UP || event.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. 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. The defaults are that vertical scrolling is triggered with an unmodified scroll, whereas horizontal scrolling is triggered by scrolling while holding down the SHIFT key.

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.