Prima::MDI(3)

✨ bestie, you’ve landed on Prima::MDI(3) — a page from the User Contributed Perl Documentation 💅

🎀 NAME 🎀

Prima::MDI - top-level window emulation 👑

🦋 DESCRIPTION 🦋

okay so MDI stands for Multiple Document Interface, and it’s a Microsoft Windows user interface vibe: you get multiple non-top-level windows that belong to an application window. The module contains classes that give you similar functionality; these sub-window widgets do a set of operations just like the real top-level windows do — iconize, maximize, cascade, etc. ✨

The basic classes you need to use the MDI are Prima::MDIOwner and Prima::MDI, which are, correspondingly, the sub-window owner class and the sub-window class. 🫶 Prima::MDIWindowOwner is the same as Prima::MDIOwner but it’s a Prima::Window descendant: both owner classes are different only in the class they’re derived from. Their second ascendant is the Prima::MDIMethods package, and that’s where all the owner class functionality lives. 💖

Usage of Prima::MDI extends beyond the multi-document paradigm, fr fr. The Prima::DockManager module uses the class as a base of the dockable toolbar window class (see Prima::DockManager. 👀

🌈 SYNOPSIS 🌈

use Prima qw(Application MDI Buttons);

my $owner = Prima::MDIWindowOwner-> new;
my $mdi   = $owner-> insert( 'Prima::MDI');
$mdi-> client-> insert( 'Prima::Button' => centered => 1 );

run Prima;

🎀 Properties 🎀

Okay bestie, these are the knobs and dials on your MDI subwindow. Each one's got a type in ALL CAPS so you know what to feed it ✨

• borderIcons INTEGER — controls the window decorations, meaning the buttons on the title bar and the title bar itself. Set it to 0, or to any combo of the mbi::XXX constants — and jsyk those are a superset of the bi::XXX constants (peep "borderIcons" in Prima::Window) and totally interchangeable with them:

mbi::SystemMenu  - system menu button with an icon is shown
mbi::Minimize    - minimize button
mbi::Maximize    - maximize and restore buttons
mbi::TitleBar    - window title
mbi::Close       - close button
mbi::All         - all of the above

Default value: mbi::All 💅

• borderStyle INTEGER — one of the bs::XXX constants, which decide the whole border vibe:

bs::None      - no border
bs::Single    - thin border
bs::Dialog    - thick border
bs::Sizeable  - thick border with interactive resize capabilities

bs::Sizeable is the special one — it's a unique mode, fr. Pick it and the user can resize the window interactively with their mouse. The other border styles say no thank you to resizing, and only mess with the border width and design.

Default value: bs::Sizeable 🦋

• client OBJECT — picks the client widget at run time. Heads up though: when you swap the client, the old client's children do not get reparented to the new one (rude, but that's the rules). Also you can't use this property to set the client while the MDI window is being created — use clientClass and clientProfile for that instead.

And when you're setting a new client object, note that it has to be named MDIClient, and that the window gets automatically destroyed after the client is destroyed. 😭

• clientClass STRING — assigns the client widget class.

Create-only property, iykyk.

Default value: Prima::Widget

• clientProfile HASH — assigns a hash of properties that get passed to the client during creation.

Create-only property too 🫶

• dragMode SCALAR — a three-state variable managing the visual feedback style while the user moves or resizes a window:
  • If it's 1, the window moves or resizes simultaneously with the user's mouse or keyboard actions — live, no cap.
  • If it's 0, a marquee rectangle gets drawn instead, and that rectangle moves or resizes as the user sends commands; the window itself only gets positioned and/or resized after the dragging session finishes successfully.
  • If it's undef, you get the system-dependent dragging style (see "get_system_value" in Prima::Application).

The dragging session can be aborted by hitting the Esc key or by calling the sizemove_cancel method. 🧚

Default value: undef.

• icon HANDLE — picks a custom image to draw in the left corner of the toolbar. If it's 0, the default image (the menu button icon) gets drawn instead.

Default value: 0

• iconMin HANDLE — the minimized button image, in the normal state.
• iconMax HANDLE — the maximized button image, in the normal state.
• iconClose HANDLE — the close button image, in the normal state.
• iconRestore HANDLE — the restore button image, in the normal state.
• iconMinPressed HANDLE — the minimize button image, in the pressed state.
• iconMaxPressed HANDLE — the maximize button image, in the pressed state.
• iconClosePressed HANDLE — the close button image, in the pressed state. 🔥
• iconRestorePressed HANDLE — the restore button image, in the pressed state.
• tileable BOOLEAN — decides whether the window is allowed to join in on the cascading and tiling auto-arrangements, which get performed by the cascade and tile methods respectively. If it's 0, the window position is left completely alone by those methods. 🍓

Default value: 1

• titleHeight INTEGER — sets the height of the title bar in pixels. If it's 0, the default system value is used.

Default value: 0

• windowState STATE — a three-state property running the state of a window. STATE can be one of three ws::XXX constants:

ws::Normal
ws::Minimized
ws::Maximized

You can change this either by an explicit set-mode call or by the user doing it — either way, a WindowState notification fires off. 📣

There are three convenience wrappers, because we love a shortcut: maximize(), minimize(), and restore().

Heads up! The ws::Fullscreen constant is not supported, and there's no corresponding fullscreen() method. Don't come for me, that's just how it is. 💀

Default value: ws::Normal

See also: WindowState

---

💖 Methods 💖

• arrange_icons — arranges the minimized sibling MDI windows geometrically. Cute little tidy-up 🎀
• cascade — arranges sibling MDI windows so they form a cascade-like structure: the lowest window gets expanded to the full owner window inferior rectangle, the next window takes the inferior rectangle of the first one, and so on down the line. Only windows with tileable set to 1 get arranged, bestie.
• client2frame X1, Y1, X2, Y2 — returns the rectangle the window would occupy if its client rectangle were assigned to the X1, Y1, X2, Y2 rectangle. Math but make it fashion ✨
• frame2client X1, Y1, X2, Y2 — the opposite direction: returns the rectangle the window client would occupy if the window rectangle were assigned to X1, Y1, X2, Y2.
• get_client_rect [ WIDTH, HEIGHT ] — returns a rectangle in the window coordinate system that the client would occupy if the window extensions are WIDTH and HEIGHT. If WIDTH and HEIGHT are undefined, it just uses the current window size. 🦋
• keyMove — kicks off a window-moving session, navigated by the keyboard.
• keySize — kicks off a window-resizing session, navigated by the keyboard.
• mdis — returns an array of sibling MDI windows. Your little window friend group 👑
• maximize — maximizes the window. A shortcut for windowState(ws::Maximized).
• minimize — minimizes the window. A shortcut for windowState(ws::Minimized).
• post_action STRING — posts an action to the window, and that action is deferred and executed in the next message loop. Why? So you avoid unnecessary state checks while the action-executing code is returning, that's why. The current implementation accepts these string commands: "min", "max", "restore", "close". 🙈
• repaint_title [ STRING = "title" ] — invalidates the part of the title bar matching STRING, which can be one of:

left    - redraws the menu button
right   - redraws minimize, maximize, and close buttons
title   - redraws the title

• restore — brings the window back to the normal state from minimized or maximized. A shortcut for windowState(ws::Normal). 🌈
• sizemove_cancel — cancels the active moving or resizing session and returns the window to its previous state. The "nvm, undo" of window dragging 💅
• tile — arranges sibling MDI windows into a grid-like structure where all windows get equal space, if that's possible. Only windows with tileable set to 1 get processed.
• xy2part X, Y — maps a point in the (X,Y) coordinates to a string matching the part of the window: title bar, button, or a piece of the border. That last one can only come back to you if borderStyle is set to bs::Sizeable. The possible return values:

border   - window border; the window is not sizeable
client   - client widget
caption  - title bar; the window is not movable
title    - title bar; the window is movable
close    - close button
min      - minimize button
max      - maximize button
restore  - restore button
menu     - menu button
desktop  - the point does not belong to the window

Bonus round: if the window is sizeable, these constants can come back too, telling you which bit of the border you're on:

SizeN    - upper side
SizeS    - lower side
SizeW    - left side
SizeE    - right side
SizeSW   - lower left corner
SizeNW   - upper left corner
SizeSE   - lower right corner
SizeNE   - upper right corner

---

🌸 Events 🌸

• Activate — triggered when the user activates the window. That activation mark usually sits on the window holding the keyboard focus, fyi. The module does not give you a dedicated activation function, so use the select() call for this one. ⭐
• Deactivate — triggered when the user deactivates the window. A window is normally marked inactive when it's got no keyboard focus. Again, no dedicated de-activation function from this module — use deselect() instead.
• WindowState STATE — triggered when the window state changes, whether that's from an explicit windowState() call or from the user. STATE is the new window state, one of the three ws::XXX constants. 🎀

👀 SEE ALSO 👀

okay bestie, when you're done here and you're like "wait, what else do I need" — go check these out, they're the whole supporting cast 💖

• Prima — the main character, the base module everything else lives in ✨
• Prima::Widget — the generic widget situation, your go-to for the everyday stuff 🎀
• Prima::Window — windows themselves, top-level and all that 🦋
• Prima::DockManager — for the docking/dragging-around vibe, lowkey iconic 💅
• examples/mdi.pl — the actual working example, fr fr go read it, it's giving tutorial 🌸

---

and that's the whole page, bestie!! 🫶 you made it to the end, I'm so proud 😭💜 go write something iconic with your MDI windows, no cap 👑

little credit where it's due before you go: this page is from perl v5.42.0, dated 2024-08-20 — that's the source and version info, keeping it 💯 for you 🎀✨