View Source ReflectOS.Kernel.Settings.System (reflect_os_kernel v0.10.1)

This module allows you to retrieve system settings, as well as subscribe to changes.

A common pattern is to default section configuration to use a system setting (e.g. time format), but allow users to override it for a given section.

If the default system setting is used, your section can subscribe to changes in the setting so the display can be updated in real-time. System Setting uses the excellent PropertyTable library under the hood, and the message sent to your section when you subscribe are the standard PropertyTable.Event struct.

Here is an example using the time_format/0 function, excerpted from the date/time section in ReflectOS Core:

defmodule ReflectOS.Core.Sections.DateTime do
  use ReflectOS.Kernel.Section, has_children: false

  alias ReflectOS.Kernel.Settings.System
  alias ReflectOS.Kernel.Section.Definition
  alias ReflectOS.Kernel.{OptionGroup, Option}


  embedded_schema do
    # Default time format to the system setting
    field(:time_format, :string, default: "system")
  end

  def section_options(),
    do: [
      %Option{
        key: :time_format,
        label: "Hour Format",
        config: %{
          type: "select",
          options: [
            {"12 Hour (6:30 PM)", "%-I:%M %p"},
            {"24 Hour (18:30)", "%-H:%M"},
            {"System Default", "system"}
          ]
        }
      }
    ]

  def init_section(scene, %__MODULE__{} = section_config, opts) do
    time_format =
      if section_config.time_format == "system" do
        # If we are using the system setting,
        # subscribe for updates
        System.subscribe("time_format")
        System.time_format()
      else
        # otherwise, use the user's selection
        section_config.time_format
      end


    {:ok, assign(scene, time_format: time_format)}
  end

  # Handle event when the time_format system setting changes.
  # This will only get called if the select time format for
  # the section is the "System Default"
  def handle_info(
        %PropertyTable.Event{
          property: ["system", "time_format"],
          value: time_format
        },
        scene
      ) do
    scene =
      scene
      |> assign(time_format: time_format)

    {:noreply, render(scene)}
  end
end

Summary

Types

"time_format" | "viewport_size" | "timezone"

Functions

Subscribes the current process to changes in the system setting. Works just like PropertyTable.subscribe/2, and will send the current process a PropertyTable.Event struct if the subscribed setting is updated.

Gets the system time format, which is a formatting string compatible with the Calendar.strftime/3 function.

Gets the system timezone.

Gets the viewport (screen) size formatted as a {width, height} tuple.

Types

@type system_settings_key() :: String.t()

"time_format" | "viewport_size" | "timezone"

Functions

@spec subscribe(system_settings_key()) :: :ok

Subscribes the current process to changes in the system setting. Works just like PropertyTable.subscribe/2, and will send the current process a PropertyTable.Event struct if the subscribed setting is updated.

See the example above for an example of how to handle this event. Note that the property field in the struct will be in the format ["system", "<subscribed setting>"].

@spec time_format() :: binary()

Gets the system time format, which is a formatting string compatible with the Calendar.strftime/3 function.

@spec timezone() :: binary()

Gets the system timezone.

@spec viewport_size() :: {width :: integer(), height :: integer()}

Gets the viewport (screen) size formatted as a {width, height} tuple.