wxSystemOptions(3)

📦
version 29.0.6 · 3 versions
, in ubuntu stonking

💖 NAME 💖

okay so bestie, meet wxSystemOptions — it's an Erlang module (the manual's whole vibe is "Erlang Module Definition", and yes she's serving) that stores option/value pairs which wxWidgets itself or your applications can use to change behaviour at run-time. no cap. 🔥

✨ DESCRIPTION ✨

It's giving "quiet luxury" honestly — you use it to optimize behaviour that doesn't deserve a whole distinct API, but is still important to be able to configure. lowkey essential, highkey underrated. 💅

System options can be set by the program itself using the setOption/2 method, and they can also be set from the program's environment — by defining an environment variable:

  • wx_option — sets the given option for all wxWidgets applications 🫶
  • wx_appname_option — sets it just for the application with that given name (as returned by wxApp::GetAppName() (not implemented in wx)) 🎀
Heads up bestie: any characters that aren't allowed in environment variable names — like periods and dashes — need to be swapped for underscores. So for example, to define a system option "foo-bar" you need to define the environment variable "wx_foo_bar". that's the rule, periodt.

The program can use system options for its own needs, but honestly they're mostly used to control the behaviour of the wxWidgets library itself. main character energy but for the library. 👑

These options are currently recognised by wxWidgets:

All platforms 🌈

  • exit-on-assert — if you set this to a non-zero value, the program gets aborted if an assertion fails 💀. The default behaviour when an assertion fails depends on the build mode, and you can change it by overriding wxApp::OnAssertFailure() (not implemented in wx) — but setting this option lets you change it without modifying the program code, and it also applies to asserts which may happen before the wxApp (not implemented in wx) object creation or after its destruction. iconic, honestly.

Windows 🪟

  • no-maskblt — 1 means never use WIN32's MaskBlt function, 0 means allow it to be used where possible. Default: 0. In some circumstances the MaskBlt function can be slower than using the fallback code, especially if you're using DC caching. By default, MaskBlt will be used where it is implemented by the operating system and driver.
  • msw.remap — if 1 (the default), wxToolBar bitmap colours get remapped to the current theme's values. Set this to 0 to disable that functionality — for example if you're using more than 16 colours in your tool bitmaps. 🙈
  • msw.window.no-clip-children — if 1, windows will not automatically get the WS_CLIPCHILDREN style. This restores the way windows are refreshed back to the method used in versions of wxWidgets earlier than 2.5.4, and for some complex window hierarchies it can reduce apparent refresh delays. You may still specify wxCLIP_CHILDREN for individual windows.
  • msw.notebook.themed-background — if set to 0, globally disables themed backgrounds on notebook pages. Note that this won't disable the theme on the actual notebook background (and that's noticeable only if there are no pages). 🍓
  • msw.staticbox.optimized-paint — if set to 0, switches off optimized wxStaticBox painting. Setting this to 0 causes more flicker, but it allows applications to paint graphics on the parent of a static box (because the optimized refresh causes any such drawing to disappear).
  • msw.font.no-proof-quality — if set to 1, use default fonts quality instead of proof quality when creating fonts. With proof quality the fonts have slightly better appearance, but not all fonts are available in this quality — e.g. the Terminal font in small sizes is not — and this option may be used if a wider fonts selection is more important to you than higher quality. choices, bestie. ✨

GTK+ 🧚

  • gtk.tlw.can-set-transparent — the wxTopLevelWindow::CanSetTransparent() (not implemented in wx) method normally tries to detect automatically whether transparency for top level windows is currently supported, however this may sometimes fail, and this option allows overriding the automatic detection. Setting it to 1 makes the transparency be always available (setting it can still fail, of course 😭) and setting it to 0 makes it always unavailable.
  • gtk.desktop — this option can be set to override the default desktop environment determination. Supported values are GNOME and KDE.
  • gtk.window.force-background-colour — if 1, the backgrounds of windows with the wxBG_STYLE_COLOUR background style are cleared forcibly instead of relying on the underlying GTK+ window colour. This works around a display problem when running applications under KDE with the gtk-qt theme installed (0.6 and below).

Mac 🍎

  • mac.window-plain-transition — if 1, uses a plainer transition when showing a window. You can also use the symbol wxMAC_WINDOW_PLAIN_TRANSITION.
  • window-default-variant — the default variant used by windows (cast to integer from the wxWindowVariant enum). Also known as wxWINDOW_DEFAULT_VARIANT.
  • mac.listctrl.always_use_generic — tells wxListCtrl to use the generic control even when it is capable of using the native control instead. Also known as wxMAC_ALWAYS_USE_GENERIC_LISTCTRL.
  • mac.textcontrol-use-spell-checker — if 1 activates the spell checking in wxTextCtrl. 🔤
  • osx.openfiledialog.always-show-types — per default a wxFileDialog with wxFD_OPEN does not show a types-popup on macOS, but allows the selection of files from any of the supported types. Setting this to 1 shows a wxChoice for selection (if there is more than one supported filetype).

Motif 🌸

  • motif.largebuttons — if 1, uses a bigger default size for wxButtons. big button era, slay.

The compile-time option to include or exclude this whole functionality is wxUSE_SYSTEM_OPTIONS. iykyk. 🎀

See: wxSystemSettings

wxWidgets docs: wxSystemOptions

🦋 DATA TYPES 🦋

wxSystemOptions() :: wx:wx_object().

💜 FUNCTIONS 💜

getOption(Name) -> unicode:charlist() when Name :: unicode:chardata().

Gets an option. 💖

The function is case-insensitive to name. Returns empty string if the option hasn't been set.

See:

  • setOption/2
  • getOptionInt/1
  • hasOption/1

getOptionInt(Name) -> integer() when Name :: unicode:chardata().

Gets an option as an integer.

The function is case-insensitive to name. If the option hasn't been set, this function returns 0.

See:

  • setOption/2
  • getOption/1
  • hasOption/1

hasOption(Name) -> boolean() when Name :: unicode:chardata().

Returns true if the given option is present. ✅

The function is case-insensitive to name.

See:

  • setOption/2
  • getOption/1
  • getOptionInt/1

isFalse(Name) -> boolean() when Name :: unicode:chardata().

Returns true if the option with the given name had been set to 0 value.

This is mostly useful for boolean options, for which you can't use GetOptionInt(name) == 0 — because that would also be true if the option hadn't been set at all. sneaky little gotcha, bestie. ⭐

setOption(Name, Value) -> ok

when Name :: unicode:chardata(), Value :: integer();

(Name, Value) -> ok
    when
        Name :: unicode:chardata(),
        Value :: unicode:chardata().

Sets an option.

The function is case-insensitive to name.

and that's the whole page, bestie! 💖 this one was brought to you by Ericsson AB, running on wx 2.6 — wxSystemOptions(3), one of the manuals of all time. go forth and set your options, you absolute icon 👑✨🌈

📦 where this page comes from