Module ui.uimanager

This module manages widgets.

Functions

UIManager:show (widget, refreshtype, refreshregion, x, y, refreshdither) Registers and shows a widget.
UIManager:close (widget, refreshtype, refreshregion, refreshdither) Unregisters a widget.
UIManager:scheduleIn (seconds, action, ...) Schedules task in a certain amount of seconds (fractions allowed) from now.
UIManager:unschedule (action) Unschedules an execution task.
UIManager:setDirty (widget, refreshtype, refreshregion, refreshdither) Registers a widget to be repainted and enqueues a refresh.
UIManager:setRefreshRate (rate, night_rate) Sets full refresh rate for e-ink screen.
UIManager:getRefreshRate () Gets full refresh rate for e-ink screen.
UIManager:getTopWidget () Get top widget.
UIManager:quit () Signals to quit.
UIManager:sendEvent (event) Transmits an event to an active widget.
UIManager:broadcastEvent (event) Transmits an event to all registered widgets.
UIManager:_refresh (mode, region, dither) Enqueues a refresh.
UIManager:_repaint () Repaints dirty widgets.

Issues

UIManager:setDirty-fixme15

We can't consume the return values of refreshtype by running it, because for a reason that is beyond me (scoping? gc?), that renders it useless later, meaning we then enqueue refreshes with bogus arguments...

    Thankfully, we can track them in _refresh()'s logging very soon after that...
UIManager:_repaint-fixme16 Force close looper when there is unhandled error, otherwise the looper will hang. Any better solution?


Functions

UIManager:show (widget, refreshtype, refreshregion, x, y, refreshdither)
Registers and shows a widget.

Modal widget should be always on top. For refreshtype & refreshregion see description of setDirty().

Parameters:

  • widget a widget object
  • refreshtype "full", "flashpartial", "flashui", "partial", "ui", "fast"
  • refreshregion a Geom object
  • x int
  • y int
  • refreshdither an optional bool

See also:

UIManager:close (widget, refreshtype, refreshregion, refreshdither)
Unregisters a widget.

For refreshtype & refreshregion see description of setDirty().

Parameters:

  • widget a widget object
  • refreshtype "full", "flashpartial", "flashui", "partial", "ui", "fast"
  • refreshregion a Geom object
  • refreshdither an optional bool

See also:

UIManager:scheduleIn (seconds, action, ...)
Schedules task in a certain amount of seconds (fractions allowed) from now.

Parameters:

  • seconds
  • action
  • ...
UIManager:unschedule (action)
Unschedules an execution task.

In order to unschedule anonymous functions, store a reference.

Parameters:

  • action

Usage:

    self.anonymousFunction = function() self:regularFunction() end
    UIManager:scheduleIn(10, self.anonymousFunction)
    UIManager:unschedule(self.anonymousFunction)
UIManager:setDirty (widget, refreshtype, refreshregion, refreshdither)
Registers a widget to be repainted and enqueues a refresh.

the second parameter (refreshtype) can either specify a refreshtype (optionally in combination with a refreshregion - which is suggested) or a function that returns refreshtype AND refreshregion and is called after painting the widget. Here's a quick rundown of what each refreshtype should be used for: full: high-fidelity flashing refresh (e.g., large images).

  Highest quality, but highest latency.
  Don't abuse if you only want a flash (in this case, prefer flashpartial or flashui).

partial: medium fidelity refresh (e.g., text on a white background).

     Can be promoted to flashing after FULL_REFRESH_COUNT refreshes.
     Don't abuse to avoid spurious flashes.

ui: medium fidelity refresh (e.g., mixed content).

Should apply to most UI elements.

fast: low fidelity refresh (e.g., monochrome content).

  Should apply to most highlighting effects achieved through inversion.
  Note that if your highlighted element contains text,
  you might want to keep the unhighlight refresh as "ui" instead, for crisper text.
  (Or optimize that refresh away entirely, if you can get away with it).

flashui: like ui, but flashing.

     Can be used when showing a UI element for the first time, to avoid ghosting.

flashpartial: like partial, but flashing (and not counting towards flashing promotions).

          Can be used when closing an UI element, to avoid ghosting.
          You can even drop the region in these cases, to ensure a fullscreen flash.
          NOTE: On REAGL devices, "flashpartial" will NOT actually flash (by design).
                As such, even onClose, you might prefer "flashui" in some rare instances.

NOTE: You'll notice a trend on UI elements that are usually shown over some kind of text

  of using "ui" onShow & onUpdate, but "partial" onClose.
  This is by design: "partial" is what the reader uses, as it's tailor-made for pure text
  over a white background, so this ensures we resume the usual flow of the reader.
  The same dynamic is true for their flashing counterparts, in the rare instances we enforce flashes.
  Any kind of "partial" refresh *will* count towards a flashing promotion after FULL_REFRESH_COUNT refreshes,
  so making sure your stuff only applies to the proper region is key to avoiding spurious large black flashes.
  That said, depending on your use case, using "ui" onClose can be a perfectly valid decision, and will ensure
  never seeing a flash because of that widget.

The final parameter (refreshdither) is an optional hint for devices with hardware dithering support that this repaint could benefit from dithering (i.e., it contains an image).

Parameters:

  • widget a widget object
  • refreshtype "full", "flashpartial", "flashui", "partial", "ui", "fast"
  • refreshregion a Geom object
  • refreshdither an optional bool

Usage:

    UIManager:setDirty(self.widget, "partial")
    UIManager:setDirty(self.widget, "partial", Geom:new{x=10,y=10,w=100,h=50})
    UIManager:setDirty(self.widget, function() return "ui", self.someelement.dimen end)
UIManager:setRefreshRate (rate, night_rate)
Sets full refresh rate for e-ink screen.

Also makes the refresh rate persistent in global reader settings.

Parameters:

  • rate
  • night_rate
UIManager:getRefreshRate ()
Gets full refresh rate for e-ink screen.
UIManager:getTopWidget ()
Get top widget.
UIManager:quit ()
Signals to quit.
UIManager:sendEvent (event)
Transmits an event to an active widget.

Parameters:

  • event
UIManager:broadcastEvent (event)
Transmits an event to all registered widgets.

Parameters:

  • event the widget's event handler might close widgets in which case a simple iterator like ipairs would skip over some entries
UIManager:_refresh (mode, region, dither)
Enqueues a refresh.

Widgets call this in their paintTo() method in order to notify UIManager that a certain part of the screen is to be refreshed.

Parameters:

  • mode
    refresh mode ("full", "flashpartial", "flashui", "partial", "ui", "fast")
    
  • region
    Rect() that specifies the region to be updated
    optional, update will affect whole screen if not specified.
    Note that this should be the exception.
    
  • dither
    Bool, a hint to request hardware dithering (if supported)
    optional, no dithering requested if not specified or not supported.
    
UIManager:_repaint ()
Repaints dirty widgets.

Issues

UIManager:setDirty-fixme15

We can't consume the return values of refreshtype by running it, because for a reason that is beyond me (scoping? gc?), that renders it useless later, meaning we then enqueue refreshes with bogus arguments...

    Thankfully, we can track them in _refresh()'s logging very soon after that...
UIManager:_repaint-fixme16
Force close looper when there is unhandled error, otherwise the looper will hang. Any better solution?
generated by LDoc 1.4.6 Last updated 2020-12-04 20:24:06