wxTopLevelWindow(3)

💖 wxTopLevelWindow 💖

okay bestie, welcome to the wxTopLevelWindow page — it's an Erlang module definition, and no cap, it's the glow-up you didn't know you needed. 🫶

---

🌸 NAME 🌸

wxTopLevelWindow — it's the common base class for wxDialog and wxFrame. That's the whole gig. 👑

---

✨ DESCRIPTION ✨

So here's the tea: wxTopLevelWindow is an abstract base class, meaning you literally never work with objects of this class directly. It's giving main character who never shows up on screen 😭 — but every single one of its methods is also applicable for the two classes above. So it's the blueprint, the blueprint-iest blueprint.

Also important: instances of wxTopLevelWindow are managed by wxWidgets in the internal top level window list. So wxWidgets is holding the clipboard, not you. 💅

See:

• wxDialog
• wxFrame

This class is derived, and can use functions, from:

• wxWindow
• wxEvtHandler

wxWidgets docs: wxTopLevelWindow

🌈 Events 🌈

Event types emitted from this class:

• maximize
• move
• show

---

🎀 DATA TYPES 🎀

wxTopLevelWindow() :: wx:wx_object().

---

💅 FUNCTIONS 💅

centerOnScreen(This, [Option]) -> ok

centerOnScreen(This, [Option]) -> ok
                        when
                            This :: wxTopLevelWindow(),
                            Option :: {dir, integer()}.

Equivalent to: centreOnScreen/2

centreOnScreen(This, [Option]) -> ok

centreOnScreen(This, [Option]) -> ok
                        when
                            This :: wxTopLevelWindow(),
                            Option :: {dir, integer()}.

Centres the window on screen. Right in the middle. Iconic behavior honestly. 🎯

See: wxWindow:centreOnParent/2

getIcon(This) -> wxIcon:wxIcon()

getIcon(This) -> wxIcon:wxIcon() when This :: wxTopLevelWindow().

Returns the standard icon of the window. 🖼️

Heads up though: the icon will be invalid if it hadn't been previously set by setIcon/2. So if you never set it, don't come crying, bestie.

See: getIcons/1

getIcons(This) -> wxIconBundle:wxIconBundle()

getIcons(This) -> wxIconBundle:wxIconBundle()
                  when This :: wxTopLevelWindow().

Returns all icons associated with the window — and there will be none of them if neither setIcon/2 nor setIcons/2 had been called before. None. Zero. Empty. 🕳️

Use getIcon/1 to get the main icon of the window.

See: wxIconBundle

getTitle(This) -> unicode:charlist()

getTitle(This) -> unicode:charlist()
                  when This :: wxTopLevelWindow().

Gets a string containing the window title. That little text at the top. You know the one. ✨

See: setTitle/2

iconize(This, [Option]) -> ok

iconize(This, [Option]) -> ok
                 when
                     This :: wxTopLevelWindow(),
                     Option :: {iconize, boolean()}.

Iconizes or restores the window. Squish it down, bring it back up. 🐣

Note that in wxGTK the change to the window state is not immediate, i.e. isIconized/1 will typically return false right after a call to iconize/2 and its return value will only change after the control flow returns to the event loop and the notification about the window being really iconized is received. So yeah, give it a sec. Patience is a vibe. 🧘

See:

• isIconized/1
• wxIconizeEvent

isActive(This) -> boolean()

isActive(This) -> boolean() when This :: wxTopLevelWindow().

Returns true if this window is currently active, i.e. if the user is currently working with it. It's literally the window with main character energy right now. 👑

isFullScreen(This) -> boolean()

isFullScreen(This) -> boolean() when This :: wxTopLevelWindow().

Returns true if the window is in fullscreen mode. The whole screen. No crumbs. 🖥️

See: showFullScreen/3

isIconized(This) -> boolean()

isIconized(This) -> boolean() when This :: wxTopLevelWindow().

Returns true if the window is iconized.

isMaximized(This) -> boolean()

isMaximized(This) -> boolean() when This :: wxTopLevelWindow().

Returns true if the window is maximized. Big mode: activated. 📈

maximize(This, [Option]) -> ok

maximize(This, [Option]) -> ok
                    when
                        This :: wxTopLevelWindow(),
                        Option :: {maximize, boolean()}.

Maximizes or restores the window.

Note that, just as with iconize/2, the change to the window state is not immediate in at least wxGTK port. Same delay energy, different function. 😭

See: iconize/2

requestUserAttention(This, [Option]) -> ok

requestUserAttention(This, [Option]) -> ok
                                when
                                    This :: wxTopLevelWindow(),
                                    Option :: {flags, integer()}.

Use a system-dependent way to attract users attention to the window when it is in background. It's the polite "hey, over here bestie 👋" move.

flags may have the value of either ?wxUSER_ATTENTION_INFO (default) or ?wxUSER_ATTENTION_ERROR which results in a more drastic action. When in doubt, use the default value. Fr fr, when in doubt, default. 🙈

Note: This function should normally be only used when the application is not already in foreground.

This function is currently implemented for Win32 where it flashes the window icon in the taskbar, and for wxGTK with task bars supporting it.

setIcon(This, Icon) -> ok

setIcon(This, Icon) -> ok
                 when
                     This :: wxTopLevelWindow(), Icon ::
wxIcon:wxIcon().

Sets the icon for this window. 🎀

Remark: The window takes a 'copy' of icon, but since it uses reference counting, the copy is very quick. It is safe to delete icon after calling this function. So don't stress, the copy is instant. ✨

Note: In wxMSW, icon must be either 16x16 or 32x32 icon.

See:

• wxIcon
• setIcons/2

setIcons(This, Icons) -> ok

setIcons(This, Icons) -> ok
                  when
                      This :: wxTopLevelWindow(),
                      Icons :: wxIconBundle:wxIconBundle().

Sets several icons of different sizes for this window: this allows using different icons for different situations (e.g.

task switching bar, taskbar, window title bar) instead of scaling, with possibly bad looking results, the only icon set by setIcon/2. One icon per occasion, a whole wardrobe. 👗

Note: In wxMSW, icons must contain a 16x16 or 32x32 icon, preferably both.

See: wxIconBundle

setShape(This, Region) -> boolean()

setShape(This, Region) -> boolean()
                  when
                      This :: wxTopLevelWindow(),
                      Region ::
                          wxRegion:wxRegion() |
                          wxGraphicsPath:wxGraphicsPath().

If the platform supports it, sets the shape of the window to that depicted by region. Custom silhouette, we love to see it. 🦋

The system will not display or respond to any mouse event for the pixels that lie outside of the region. To reset the window to the normal rectangular shape simply call setShape/2 again with an empty wxRegion. Returns true if the operation is successful.

This method is available in this class only since wxWidgets 2.9.3, previous versions only provided it in wxTopLevelWindow.

Note that windows with non default shape have a fixed size and can't be resized using wxWindow:setSize/6.

setTitle(This, Title) -> ok

setTitle(This, Title) -> ok
                  when
                      This :: wxTopLevelWindow(),
                      Title :: unicode:chardata().

Sets the window title. Name your window, periodt. ✨

See: getTitle/1

showFullScreen(This, Show, [Option]) -> boolean()

showFullScreen(This, Show, [Option]) -> boolean()
                        when
                            This :: wxTopLevelWindow(),
                            Show :: boolean(),
                            Option :: {style, integer()}.

Depending on the value of show parameter the window is either shown full screen or restored to its normal state.

style is a bit list containing some or all of the following values, which indicate what elements of the window to hide in full-screen mode:

• ?wxFULLSCREEN_NOMENUBAR
• ?wxFULLSCREEN_NOTOOLBAR
• ?wxFULLSCREEN_NOSTATUSBAR
• ?wxFULLSCREEN_NOBORDER
• ?wxFULLSCREEN_NOCAPTION
• ?wxFULLSCREEN_ALL (all of the above)

This function has not been tested with MDI frames. So like... unknown territory, proceed with care. 💀

Note: Showing a window full screen also actually wxWindow:show/2s the window if it isn't shown.

See: isFullScreen/1

---

mwah 💋 that's the whole page bestie. Brought to you by Ericsson AB, running on wx 2.6 — this was wxTopLevelWindow(3), and you absolutely ate it. Go build something iconic 🫶✨🎀🦋