Reference

Input widgets

GtkObservables.buttonFunction
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)
source
GtkObservables.checkboxFunction
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
source
GtkObservables.togglebuttonFunction
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
source
GtkObservables.sliderFunction
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.
source
GtkObservables.textboxFunction
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.

source
GtkObservables.textareaFunction
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.

source
GtkObservables.dropdownFunction
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.

source
GtkObservables.playerFunction
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.

source

Output widgets

GtkObservables.labelFunction
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)
source

Graphics

GtkObservables.canvasFunction
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.

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

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

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

See also canvas.

source
GtkObservables.MouseHandlerType
MouseHandler{U<:CairoUnit}

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

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

source
GtkObservables.XYType
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.

source
GtkObservables.MouseButtonType
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.

source
GtkObservables.MouseScrollType
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.

source

Pan/zoom

GtkObservables.ZoomRegionType
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.

source

Note that if you create a zrsig::Observable{ZoomRegion}, then

push!(zrsig, XY(1..3, 1..5))
push!(zrsig, (1..5, 1..3))
push!(zrsig, (1:5, 1:3))

would all update the value of the currentview field to the same value (x = 1..3 and y = 1..5).

GtkObservables.pan_xFunction
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.

source
GtkObservables.pan_yFunction
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.

source
GtkObservables.zoomFunction
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.

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

source
GtkObservables.init_zoom_rubberbandFunction
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.

source
GtkObservables.init_zoom_scrollFunction
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.

source
GtkObservables.init_pan_dragFunction
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.

source
GtkObservables.init_pan_scrollFunction
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.

source

API