Methods

Sub AddSubview(parent As Ptr, child As Ptr)

—

Function Alloc(cls As Ptr) As Ptr

—

Sub ApplyColor(tv As Ptr, c As Color)

—

Function Autorelease(obj As Ptr) As Ptr

Gives up ownership of an object WITHOUT destroying it right away: the pool releases it at the end of the current loop pass. This is what you need when handing an object to AppKit — it will retain it for itself, but AFTER you return.An immediate release would destroy the object before AppKit took it; doing nothing leaks it. Autorelease is the only one of the three that is right. Returns the object, so it can be written at the end of an expression: Return Autorelease(v).

Function BuildRichTextEditor(hostView As Ptr, width As Double, height As Double) As Ptr

Creates an NSScrollView + NSTextView (rich text) and adds it to the host view (the DesktopCanvas's NSView). Returns the pointer to the NSTextView (keep it to drive the formatting).

Function ClassRef(name As String) As Ptr

—

Function ConvertFontTrait(fm As Ptr, font As Ptr, trait As UInteger) As Ptr

—

Function DataWithContentsOfFile(path As String) As Ptr

—

Sub ExportRTF(tv As Ptr, file As FolderItem)

—

Function FontOfSelection(tv As Ptr) As Ptr

—

Function FromNSStr(p As Ptr) As String

NSString * -> Xojo String, WITHOUT CFStringRef.A return declared as CFStringRef makes Xojo take ownership of the object and release it. But -[NSString description] returns self without incrementing the count: every call on a string belonging to AppKit over-releases it, and the breakage shows up later, elsewhere. So we go through UTF8String, which transfers no ownership. The return of a CString declare is not implicitly converted in an extension method call: it has to be assigned first.

Sub ImportRTF(tv As Ptr, file As FolderItem)

—

Function InitWithFrame(obj As Ptr, frame As NSRect) As Ptr

—

Function NSColorRGBA(r As Double, g As Double, b As Double, a As Double) As Ptr

—

Function MacOSVersionAtLeast(major As Integer, minor As Integer = 0) As Boolean

Operating system version, read once only. To be used for presentation only: to decide whether an API exists, Responds() is safer — a selector that is present is a proof, a version number a guess.

Function MainQueue() As Ptr

GCD's main queue.dispatch_get_main_queue() is not a function but a macro naming the exported _dispatch_main_q structure: you read the symbol's ADDRESS, and that address IS the queue. The opposite nuance to ExportedString, where the symbol holds a pointer that must be dereferenced.

Sub PerformOnMainThread(callback As Ptr, context As Ptr)

Runs a callback on the interface thread, later, without waiting.Apple's completion blocks arrive on a service queue, not on the interface thread, and the Xojo runtime is not built to be woken from a thread it does not know. The block stores a pointer, raises a flag, and comes back through here. callback is an AddressOf on a Shared method taking a Ptr.

Function Responds(obj As Ptr, selectorName As String) As Boolean

Does the object respond to this selector? This is THE way to test for the presence of an API: it observes instead of assuming.

Function ExportedString(symbolName As String) As String

Reads an NSString constant exported by AppKit — toolbar item identifier, pasteboard type — rather than copying out its value. They do not all follow the same convention, and a copied string becomes wrong without warning the day Apple changes it.NUANCE: dlsym returns the ADDRESS of the symbol, and the symbol CONTAINS a pointer to the NSString — hence the slot.Ptr(0) dereference. For a symbol declared as an array, on the contrary, the address IS the object.

Function NSStr(s As String) As Ptr

—

Function OwnerOf(handle As Ptr) As Object

Finds the Xojo object that owns an ObjC instance created at runtime. Used from the Shared callback methods, which receive nothing but the ObjC “self”.

Sub RegisterOwner(handle As Ptr, owner As Object)

Maps an ObjC instance (delegate, dataSource, target…) to its Xojo owner. The reference is weak: registering does not keep the Xojo object alive.

Sub ReplaceRangeWithRTF(tv As Ptr, range As NSRange, data As Ptr)

—

Function RTFFromRange(tv As Ptr, range As NSRange) As Ptr

—

Function SelectedRange(tv As Ptr) As NSRange

—

Sub SetAllowsUndo(tv As Ptr, flag As Boolean)

—

Sub SetAutoresizingMask(view As Ptr, mask As UInteger)

—

Sub SetDocumentView(scroll As Ptr, view As Ptr)

—

Sub SetEditable(tv As Ptr, flag As Boolean)

—

Sub SetFontRange(tv As Ptr, font As Ptr, range As NSRange)

—

Sub SetHasVerticalScroller(scroll As Ptr, flag As Boolean)

—

Sub SetRichText(tv As Ptr, flag As Boolean)

—

Sub SetTextColorRange(tv As Ptr, color As Ptr, range As NSRange)

—

Sub SetViewFrame(view As Ptr, frame As NSRect)

Puts back a frame read with ViewFrame. Needed when Xojo REPLACES a view and misplaces the one it has just created — toggling Password on a DesktopTextField destroys the view, creates another, and that one lands at coordinates which are not its own.Always the same rule: size through the Xojo API, position through AppKit.

Function SharedFontManager() As Ptr

—

Function TextLength(tv As Ptr) As UInteger

—

Sub ToggleTrait(tv As Ptr, mask As UInteger)

mask : NSItalicFontMask=1, NSBoldFontMask=2

Function TraitsOfFont(fm As Ptr, font As Ptr) As UInteger

—

Sub UnderlineSelection(tv As Ptr)

—

Sub UnregisterOwner(handle As Ptr)

—

Function ViewFrame(view As Ptr) As NSRect

A view's REAL frame, to compare against what Xojo believes it set. A difference means the view was moved behind one of their backs.y counts from the bottom in AppKit and from the top in Xojo: a difference in y is not necessarily an anomaly, one in x or in the width is.

Function WriteDataToFile(data As Ptr, path As String) As Boolean

—

Methods

Shared Function Handle(kind As Kinds) As Ptr

The LIVE NSColor, to hand straight to AppKit. It stays dynamic: it resolves at every draw, so it follows an appearance change with nothing to reset. This is the form to prefer as soon as the colour goes to a view. Returns Nil when the colour does not exist on this system.

Shared Function Value(kind As Kinds, fallback As Color = &c000000) As Color

The RESOLVED colour, for drawing on the Xojo side.It is a SNAPSHOT: the value is resolved in the current appearance and will not move again. Switching to dark mode does not update it — read it again and redraw. A limit of the conversion, not of the implementation: a Xojo Color is three bytes, it cannot carry anything dynamic. Alpha is preserved, and it must be: the secondary to quinary labels, the separator and the five fills are translucent by construction; in Xojo, Alpha is 0 for opaque and 255 for transparent.

Shared Function Available(kind As Kinds) As Boolean

Availability read BY SELECTOR, not inferred from a version number — the doctrine of the rest of the library. The palette runs from 10.8 to 14.0: quinaryLabelColor in 11.0, systemCyanColor in 12.0, textInsertionPointColor and the five fills in 14.0.

Shared Function SelectorName(kind As Kinds) As String

The colour's AppKit name. Useful on screen and in logs: it says exactly which API is in play, which a translated enum name would not.

Constructor

Sub Constructor(className As String, superClassName As String = "NSObject")

Methods

Sub AddMethod(selectorName As String, handle As Ptr, signature As String)

Grafts a Xojo implementation (AddressOf of a Shared method) onto the class. The signature is the ObjC type encoding: return type, then "@:" (self and _cmd), then one character per argument.q=Int64 d=Double @=id c/B=BOOL v=void see the Objective-C Runtime Programming Guide, “Type Encodings”.

Sub AddProtocol(protocolName As String)

Declares formal conformance. Optional: AppKit asks respondsToSelector: in any case. Without effect if the protocol is not visible to the runtime.

Function CreateInstance() As Ptr

Returns a RETAINED instance. The retain is not a precaution, it is the condition for working at all: AppKit's delegate, dataSource and target are weak zeroing references. Without a strong owner, the instance is deallocated at once, the weak reference goes back to Nil, and no callback ever arrives. The caller is responsible for the matching ReleaseInstance.

Function Handle() As Ptr

The Class pointer, for a manual alloc/init (view subclasses, for example).

Function IsNew() As Boolean

False if the class already existed and was reused as it was.

Shared Sub ReleaseInstance(obj As Ptr)

—

Function Responds(selectorName As String) As Boolean

Consistency check: does the class really expose the grafted selector?

Shared Function MetaClassOf(cls As Ptr) As Ptr

The metaclass carries the CLASS methods: it is the one to ask to know whether a factory of the +itemWithFoo: kind exists on this version.

Shared Function SelectorFor(selectorName As String) As Ptr

—

Methods

Shared Sub Center(anchor As DesktopUIControl, view As Ptr)

Same principle as Fill, but the view keeps its own size and stays centred. For a control with an intrinsic size — an NSSwitch, for example, which it would make no sense to stretch.

Shared Sub Detach(view As Ptr)

—

Shared Function MakeFlippedContainer(width As Double, height As Double) As Ptr

Like MakeContainer, but FLIPPED: y counts from the top, as in the rest of the library and as in the Xojo designer.isFlipped is not settable, it has to be overridden — hence the class created at runtime. ObjCClass reuses a class that is already registered, so several callers can ask for it without duplicating it.

Shared Function MakeContainer(width As Double, height As Double) As Ptr

A bare NSView, for the places that accept ONLY ONE view where several would be needed: the accessory view of a file panel or an alert, the contentView of an NSGlassEffectView.The view is RETAINED: it is up to the caller to keep it in a property and give it back through Cocoa.ObjCClass.ReleaseInstance. AppKit coordinates, origin at the bottom — including for what is added to it.

Shared Sub SetFrame(view As Ptr, x As Double, y As Double, width As Double, height As Double)

Sets the frame of an AppKit view without adding it anywhere — to prepare a view destined for a container that will place it itself: the contentView of an NSGlassEffectView, the accessory view of an NSAlert.AppKit coordinates, so origin AT THE BOTTOM, unless the parent view is flipped — which is the case for a NativePopover's, not for the others.

Shared Sub Fill(anchor As DesktopUIControl, view As Ptr)

Places an AppKit view IN the view of a Xojo control serving as an anchor — an empty DesktopCanvas, typically — and lets it fill it entirely.Hosting INSIDE the anchor rather than beside it avoids the whole geometry problem: Xojo carries on placing and sizing the anchor, and the autoresizing mask makes the AppKit view follow. No position is calculated, so there is nothing to resynchronise on resize.

Shared Sub SetCompactMetrics(view As Ptr, compact As Boolean)

macOS 26: asks a view — and everything it contains — for the system's COMPACT metrics. It is a property of NSView, so valid for any wrapped control: hence its place here rather than copied into every class.

Shared Sub SetSelectionAnchor(view As Ptr, x As Double, y As Double, width As Double, height As Double)

macOS 15. States WHERE the selection is inside the view: the system places the keyboard context menu and popovers there instead of at the centre. Only applies to views built by MakeFlippedContainer — a system class cannot receive the method without being subclassed.

Shared Sub ClearSelectionAnchor(view As Ptr)

No more selection: the system returns to the centre of the view.

Enumerations

Methods

Shared Sub SetLicence(licensee As String, key As String)

To be called in App.Opening, BEFORE any window is dressed. The name must be copied EXACTLY as it appears on the licence: it goes into the code's computation, and one extra space is enough for it to be refused. Two empty strings = no licence.

Shared Function Licensed() As Boolean · LicensedTo · StatusText · Notice

The state, the licensee's name, and texts ready to show in an “About” box.

Shared Function Inspect(licensee As String, key As String, ByRef majorCovered As Integer, ByRef reason As String) As Boolean

Checks a key without installing it, and says WHY it is refused — length, prefix, signature. It is what the generator uses.

Shared Function MakeLicence(licensee As String, majorCovered As Integer) As String

Builds a key — the generator's business, not the application's. A 33-character key, VDS01-XXXXXX-…: HMAC-SHA256 truncated to 120 bits, in base32 without the letters I, L, O and U.

Shared Sub ApplyWatermark(window As Ptr)

The watermark of unlicensed builds: a light badge with a border, bold black text, bottom right. One per window, also placed by MarkHost, which the library calls from view hosting and from the Opening of the controls dropped in the IDE.The background is translucent through its LAYER, not through the view's alpha, or the text would fade with it. The view returns Nil from hitTest:: it takes no clicks.

Constructor

Sub Constructor(win As DesktopWindow)

Methods

Function DetailHeight() As Double

—

Function DetailWidth() As Double

—

Function HasInspector() As Boolean

—

Sub Install(sidebarView As Ptr, sidebarWidth As Double, minWidth As Double = 180, maxWidth As Double = 340)

Hands the window's contentViewController to an NSSplitViewController: Xojo's contentView becomes the view of the detail pane, and the view passed as an argument that of the sidebar pane.What this arrangement gives for free: vibrancy and animated collapsing of the sidebar pane, the system “toggle” toolbar item through the responder chain, automatic toolbar breaking, and safe-area handling (so no inset to compensate under the titlebar).

Sub InstallInspector(inspectorView As Ptr, width As Double, minWidth As Double = 200, maxWidth As Double = 420)

A third pane, on the right. inspectorWithViewController: (macOS 14+) brings the same system treatment as the sidebar: animated collapsing, and above all the NSToolbarToggleInspectorItem / NSToolbarInspectorTrackingSeparatorItem identifiers, which then work without a line of code.

Function IsInspectorCollapsed() As Boolean

—

Function IsSidebarCollapsed() As Boolean

—

Shared Function MakeTitleView(title As String, subtitle As String = "") As Ptr

Title + subtitle stacked, to be set as the VIEW of a toolbar item.Why: NSWindow.title is placed by AppKit at the HEAD of the bar, hence on the sidebar side. To align it with the start of the detail — which is what the system applications do — an item is needed, placed by hand just after the tracking separator. In that case the system title is hidden (chrome.TitleVisible = False) so as not to show it twice.

Sub PlaceView(v As Ptr, x As Double, y As Double, w As Double, h As Double)

Placement in AppKit coordinates: origin at the BOTTOM left, Xojo's contentView not being “flipped”. To be used for the POSITION only — the size must go through the Xojo property, see the DetailResized event.

Sub Relayout()

Two stages, and the order matters: 1) the SIZE is announced to the window (event), which writes it through the Xojo properties — the only gesture that triggers the layout of a PagePanel's child controls; 2) the window then corrects the POSITION with PlaceView, the Xojo geometry being wrong under NSSplitViewController. The top-level views of the detail must have LockRight and LockBottom at False in the designer, failing which Xojo lays them out on its side and you see two passes follow one another.

Function SafeAreaTop() As Double

Height taken by the titlebar and the toolbar ABOVE the detail.With FullHeightSidebar, the detail pane rises to the top of the window: without this offset, the content passes under the toolbar. safeAreaInsets (macOS 11+) gives the exact value, which varies with the bar style and the display mode — hard-coding it would be wrong as soon as the style changes.

Function ScrollEdgeEffectAvailable() As Boolean

macOS 26. The style CLASS is queried, not the version number: a selector that is present is a proof, a version number a guess.

Function SetScrollEdgeEffect(style As ScrollEdgeStyles) As Integer

NSScrollEdgeEffectStyle (macOS 26): the way the content fades under a title bar or a pane when scrolling — soft edge, or hard cut.This is NOT a control but a style object, and it goes only on ACCESSORY controllers: those of the title bar and those of the panes. So it is applied to all the window's title accessories — including the one AppKit installs for the RTF format bar. Returns the NUMBER of accessories actually styled: zero is not an error, it means there is none to style for the moment.

Function SplitViewHandle() As Ptr

—

Shared Function SystemIdentifier(symbolName As String) As String

Reads an NSToolbarItemIdentifier constant exported by AppKit rather than guessing its value — they do not all follow the same convention. The machinery lives in the Cocoa module: it also serves the pasteboard types of drag and drop.

Sub ToggleInspector()

—

Sub ToggleSidebar()

The programmatic equivalent of the system toolbar item.

Function AddTopAccessory(area As SplitAreas, view As Ptr) As Ptr

macOS 26. An accessory bar at the top of ONE given pane — the same family as the titlebar accessory the RTF bar puts on the whole window, but confined to the targeted pane. Returns the created controller's pointer, to keep for removing or hiding it.

Function AddBottomAccessory(area As SplitAreas, view As Ptr) As Ptr

The symmetric one, below the pane's content.

Sub RemoveAccessory(controller As Ptr)

Goes through removeFromParentViewController, which the header recommends: no need to find the index in the top or bottom list.

Sub SetAccessoryHidden(controller As Ptr, hidden As Boolean)

Collapses the accessory to zero height without removing it — reversible without rebuilding the view.

Sub SetAllowsOverlay(area As SplitAreas, allow As Boolean)

macOS 26, automaticallyAdjustsSafeAreaInsets. Other panes may then overlay this one, its safeAreaInsets following that overlay.

Properties

FullHeightSidebar As Boolean

True: the sidebar pane rises behind the titlebar and the toolbar starts only at the divider — this is the arrangement of the system applications, and the condition for NSWindow.title to fall on the detail side.

Subtitle As String

A secondary line under the title, in grey (macOS 11+). Empty = no line.

Title As String

The title of the WINDOW, shown in bold in the unified bar. Nothing to do with the Label or Title of a NativeToolbarItem: it is this title/subtitle pair that the system applications show.

TitleVisible As Boolean

False hides both title AND subtitle, so that a custom view can take their place. That is what the demo used to do — and it is precisely what stopped the system presentation from being seen.

Events

• Event DetailResized(w As Double, h As Double)

Enumerations

Methods

Shared Sub Configure(w As DesktopWindow, mode As Modes, identifier As String = "")

To be called BEFORE Show. The identifier is what allows two windows to become tabs of one another.

Shared Function UserPreference() As Preferences

The system “Prefer tabs” setting: Manual, Always or InFullScreen. It decides what AppKit does with a window in Automatic mode.

Shared Sub AddTab(host As DesktopWindow, tab As DesktopWindow)

Adds a window as a tab of another, bypassing the system setting.

Shared Sub ToggleTabBar(w As DesktopWindow)

Shows or hides the tab bar — the “Show Tab Bar” item of the View menu.

Shared Sub ToggleOverview(w As DesktopWindow)

The animated overview, “Show All Tabs”.

Shared Sub MergeAll(w As DesktopWindow)

Gathers every compatible window into tabs of a single one.

Shared Sub MoveToNewWindow(w As DesktopWindow)

Detaches the current tab into its own window.

Shared Sub SelectNext(w As DesktopWindow) · SelectPrevious

Navigation from tab to tab.

Shared Function TabCount(w As DesktopWindow) As Integer · TabBarVisible

tabGroup is created ON DEMAND and returned through a WEAK reference: read it again on every call rather than holding it.

Enumerations

Methods

Shared Sub SetLevel(w As DesktopWindow, level As Levels)

The stacking level. The enum values are MEASURED, not copied: the header does not spell them out, it defines them through kCGNormalWindowLevel and friends, computed by CGWindowLevelForKey(). Measured at runtime on macOS 15.7.9 — Normal 0, Floating 3, ModalPanel 8, MainMenu 24, Status 25, PopUpMenu 101, ScreenSaver 1000.Submenu and TornOffMenu are 3 as well, exactly Floating: they are not included, they would be three names for one value.

Shared Sub SetLevelRaw(w As DesktopWindow, value As Integer)
Shared Function LevelRaw(w As DesktopWindow) As Integer

As a number, because NSWindowLevel is declared NS_TYPED_EXTENSIBLE_ENUM: any value is legitimate, and « Floating + 1 » is a common idiom to sit just above the palettes.

Shared Sub SetAlpha(w As DesktopWindow, value As Double)
Shared Function Alpha(w As DesktopWindow) As Double

The opacity of the WHOLE window, chrome included, from 0 to 1. The value is clamped to that range: AppKit accepts anything, but a window at −3 disappears without saying why.

Shared Sub SetCollectionBehavior(w As DesktopWindow, behaviors() As Behaviors)
Shared Sub SetCollectionBehavior(w As DesktopWindow, behavior As Behaviors)

Behaviour towards spaces, Exposé and full screen.ORDER MATTERS: the header states that the default behaviour DEPENDS on the level — Managed and ParticipatesInCycle when the level is Normal, Transient and IgnoresCycle otherwise. Set the level first. And « at most one per group »: at most one of Managed/Transient/Stationary, at most one of ParticipatesInCycle/IgnoresCycle, at most one of the three FullScreen bits — nothing checks it, neither AppKit nor this class.

Shared Function CollectionBehaviorRaw(w As DesktopWindow) As Integer
Shared Function HasBehavior(w As DesktopWindow, behavior As Behaviors) As Boolean

The raw mask, and the readable way to test one bit. Default being zero, testing it against the mask would always be false: HasBehavior then answers the question as it is actually asked — is the mask empty?

Shared Sub SetMovable(w As DesktopWindow, movable As Boolean)
Shared Function Movable(w As DesktopWindow) As Boolean

macOS 10.6. When false, the server stops dragging the window by its title bar or background.Two surprises written into the header: the window stays RESIZABLE if it was, and its frame remains settable programmatically; and the system stops moving it on a display reconfiguration, which can leave it off screen.

Shared Sub SetMovableByBackground(w As DesktopWindow, value As Boolean)
Shared Function MovableByBackground(w As DesktopWindow) As Boolean

Drag the window from anywhere in its background.Ignored without a word on a non-movable window — « setMovableByWindowBackground:YES is ignored on a window that returns NO from -isMovable ». Setting Movable false then this true does nothing at all.

Methods

Sub Refit()

The source-list style adds a horizontal margin BEYOND the column width: the view becomes wider than its visible area and the selection overflows. To be called AFTER layout — sizeLastColumnToFit does nothing while the dimensions are not established.

Properties

EmphasizedSelection As Boolean

True: blue selection. False: grey, like a list without focus. NOT ReloadList: reloadData DESELECTS. isEmphasized is queried at drawing time, so a simple redraw is enough — and it preserves the selection.

Width As Double read-only

The pane's real width, read from the view. Read-only: it is the container that fixes it, not the sidebar.

Constructor

Sub Constructor()

Methods

Sub Add(title As String, sfSymbol As String)

—

Sub Add(title As String, sfSymbol As String, iconColor As Color)

—

Sub AddSection(title As String)

Section header: small grey capitals, not selectable. Kind 2 in mKinds — 0 = item, 1 = separator, 2 = header.

Sub AddSeparator()

—

Function BuildSidebarView(width As Double, height As Double, topInset As Double = 0) As Ptr

Builds the sidebar view ALONE — vibrancy + source-list table + footer. No NSSplitView, no styleMask, no contentView: the container is the caller's business — NativeWindowChrome mounts this view in an NSSplitViewItem.

Function Count() As Integer

—

Sub Insert(index As Integer, title As String, sfSymbol As String)

—

Function PageForTitle(title As String) As Integer

Aiming at a page by its TITLE rather than by a number: a caller that hard-codes “page 15” is wrong as soon as an entry is inserted above it.The comparison is made with “=”, and that is deliberate: in Xojo the equality of two Strings ignores CASE — the same insensitivity that makes “isa” BE the IsA operator. To compare strictly, StrComp(a, b, 1) would be needed.

Function RowForPage(page As Integer) As Integer

The exact inverse of PageForRow.

Function SelectPage(page As Integer) As Boolean

VERIFIED rather than assumed: selectRowIndexes:byExtendingSelection: DOES warn the delegate — tableViewSelectionDidChange: fires just as on a click. An application listening to SelectionChanged therefore sees the page arrive on its own; there is no need to push it a second time.Except when the row is ALREADY selected: AppKit does not notify an unchanged selection. That is correct — nothing moved —, but a caller relying on the event to synchronise itself needs to know.

Function PageForRow(row As Integer) As Integer

The rank of the row among the SELECTABLE rows, separators excluded. Saves the caller hard-coding the position of the separators — arithmetic that breaks as soon as one is added.

Sub Remove(index As Integer)

—

Sub SetBadge(index As Integer, text As String)

A badge counter on an entry, Mail-style. An empty string = no badge.

Sub SetFooter(title As String, sfSymbol As String)

A special row pinned AT THE BOTTOM (separator + clickable icon/label). To be called BEFORE BuildSidebarView. The click fires the FooterClicked event.

Properties

SelectedIndex As Integer

—

Events

• Event FooterClicked()
• Event SelectionChanged(index As Integer)

Constructor

Sub Constructor()

Methods

Function AddSection(title As String) As Integer

Returns the index of the section, to be passed to AddItem afterwards.

Sub AddItem(section As Integer, title As String, sfSymbol As String = "", iconColor As Color = &c8E8E93)

—

Function BuildSidebarView(width As Double, height As Double) As Ptr

Hierarchical sidebar: NSOutlineView in source-list style, in an NSScrollView, on an NSVisualEffectView. The sections are collapsible “group rows”; the triangle appears on hover, as in the Finder.

Sub CollapseAll()

—

Sub ExpandAll()

—

Function ItemCount(section As Integer) As Integer

—

Sub SetBadge(section As Integer, item As Integer, text As String)

A badge counter on an entry. An empty string = no badge.

Function SectionCount() As Integer

—

Properties

SelectedPage As Integer read-only

The rank of the selected row among ALL the items, sections excluded: the caller thus gets back a page index just as with NativeSidebar.

Events

• Event SelectionChanged(page As Integer)

Constructor

Sub Constructor(identifier As String)

Methods

Sub AddItem(item As NativeToolbarItem)

The DEFAULT set: what the bar shows as long as the user has customised nothing, and the bottom row of the customisation sheet.

Sub AddAvailableItem(item As NativeToolbarItem)

The CATALOGUE: the item is offered in the customisation sheet without being placed in the bar. AppKit can only build what the delegate announces in toolbarAllowedItemIdentifiers:, hence the registration here.

Sub Attach(w As DesktopWindow)

—

Sub Attach(windowHandle As Ptr)

Every item must have been added BEFORE: it is at the setToolbar: moment that AppKit asks toolbarDefaultItemIdentifiers: in order to populate the bar.

Sub SetItemIdentifiers(identifiers() As String)

macOS 15. Sets the bar's CONTENT in one assignment, AppKit doing the diff — animated insertions and removals, without rebuilding. The header warns: “will override any customizations the user has made”. On a customisable, autosaving bar, this call wipes out the user's arrangement.

Function ItemIdentifiers() As String()

What the bar shows RIGHT NOW, the user's customisation included — unlike the default set, which does not move.

Sub RemoveItem(identifier As String)

macOS 15. Removes ONE item by its identifier, where RemoveAll is all or nothing. Two points from the header: if several items share the identifier, the FIRST one goes, and the change propagates immediately to every toolbar with the same identifier. The item leaves the bar, not the catalogue — so it is still offered in the palette.

Sub RemoveAll()

Empties the bar. Useful for rebuilding it in another style — item groups, for example, are refused by the Preference style.

Sub ResetConfiguration()

Clears the saved customisation and puts the default set back. AppKit exposes nothing for this: the configuration is written to the preferences under “NSToolbar Configuration <identifier>”, and removing it is not enough — the live bar keeps its items, they have to be set again.

Sub RunCustomizationPalette()

Opens the customisation palette; requires AllowsUserCustomization = True.

Function Handle() As Ptr

—

Function Item(identifier As String) As NativeToolbarItem

—

Sub ValidateVisibleItems()

—

Properties

AllowsDisplayModeCustomization As Boolean

macOS 15. The “Icon and Text / Icon Only / Text Only” part of the contextual menu and of the sheet. INDEPENDENT of AllowsUserCustomization, which governs only the order of the items. Default YES for an application linked on macOS 15 — so active without being asked for.

AllowsUserCustomization As Boolean

—

AutosavesConfiguration As Boolean

At True, AppKit itself writes to the preferences whatever the user changes — item order, removed items, display mode — and reads it back the next time a bar with the same identifier is built. To be set BEFORE Attach: the configuration is read at setToolbar: time. Default False.

DisplayMode As DisplayModes

—

Visible As Boolean

—

Style As ToolbarStyles

Applicable before or after Attach: ApplyStyle is replayed on attaching.

Events

• Event ItemPressed(item As NativeToolbarItem)

Enumerations

Constructor

Sub Constructor(identifier As String, objcClassName As String = "NSToolbarItem")

Methods

Shared Function FlexibleSpaceItem() As NativeToolbarItem

System identifier: AppKit builds the item itself, the delegate returns Nil.

Shared Function ContainerItem(identifier As String, container As DesktopContainer) As NativeToolbarItem

An item whose view is that of a DesktopContainer. If the container implements ToolbarItemContainer, its SetEnabled is called on every state change: AppKit does not know how to dim the controls of a custom view.

Shared Function SystemItem(identifier As String) As NativeToolbarItem

An identifier supplied by AppKit (sidebar toggle, automatic breaking, spaces): the delegate returns Nil and AppKit builds and then drives the item itself.

Sub WireSubItems(target As Ptr, action As Ptr)

Without effect for a plain item; NativeToolbarItemGroup overrides it.

Function SubItems() As NativeToolbarItem()

Empty for a plain item; NativeToolbarItemGroup overrides it.

Function Handle() As Ptr

The underlying NSToolbarItem. Nil for system identifiers (spaces).

Function IsSystemItem() As Boolean

—

Function ItemIdentifier() As String

—

Function RespondsToClicks() As Boolean

False for the spaces and the tracking separator: no target/action on those.

Sub ClearBadge()

—

Function BadgeSupported() As Boolean

macOS 26+. Lets the caller adapt its interface rather than offer a setting without effect.

Sub SetBadge(count As Integer)

A numbered badge (macOS 26+).

Sub SetBadge(text As String)

A text badge, or a plain dot if the text is empty (macOS 26+).

Sub SetIcon(sfSymbolName As String, accessibilityDescription As String = "")

—

Sub SetView(view As Ptr)

A custom view (title field, bespoke control…).The item then stops asking the bar for a target/action: when the view is an NSControl, AppKit passes the item's target/action DOWN ONTO it and overwrites the control's own target — its event then never fires again. A custom view handles its own interaction.

Shared Function SpaceItem() As NativeToolbarItem

—

Shared Function TrackingSeparatorToolbarItem(identifier As String, splitView As Ptr, dividerIndex As Integer) As NativeToolbarItem

Toolbar break aligned on an NSSplitView divider (macOS 11+).

Properties

AutoValidates As Boolean

False = the Enabled state set by hand is authoritative, AppKit does not revalidate. True (AppKit's default) = validateToolbarItem: is queried periodically; NativeToolbar answers it by returning Enabled, so the result is the same.

IsHidden As Boolean

—

Navigational As Boolean

Puts the item in the navigation area, on the left (macOS 11+).

VisibilityPriority As Integer

The higher the value, the more the item resists the shrinking of the bar.

Bordered As Boolean

—

Enabled As Boolean

—

Title As String

Text SHOWN INSIDE the button, beside or instead of the icon (macOS 10.15+). Not to be confused with Label, which is the caption UNDER the item.

BackgroundTintColor As Color

macOS 26+. Silently ignored below: the selector is queried rather than the version number — present or absent, that is a fact.

Style As ItemStyles

macOS 26+: Plain, or Prominent for an item brought forward, “Done”-style.

Label As String

—

ToolTip As String

—

Enumerations

Constructor

Sub Constructor(identifier As String)

Methods

Sub AddItem(item As NativeToolbarItem)

The subitems are retained on the Xojo side: setSubitems: guarantees the survival of the ObjC objects, not of our wrappers.

Sub WireSubItems(target As Ptr, action As Ptr)

AppKit routes a group's click to its SUBITEMS: without a target/action on them, the group is inert. But setting one on them once they already belong to the group ends the process at the first layout pass — reproduced twice.The hypothesis tested here: the group copies its subitems on assembly, and forming a weak reference (NSToolbarItem.target is one) to an instance of a runtime-created class during that copy is what breaks. So we wire them while they belong to nobody, then reassemble.

Function SubItems() As NativeToolbarItem()

Accessor: the subitems belong to the group, not to the bar. NEVER write target/action to them — that is what made AppKit crash at the first layout pass.

Properties

ControlRepresentation As ControlRepresentations

Collapsed = a single button that pulls down a menu; Expanded = all visible.

SelectedIndex As Integer

—

SelectionMode As SelectionModes

—

Enumerations

Constructor

Sub Constructor(identifier As String)

Methods

Sub AddMenuItem(title As String, tag As Integer = -1)

Adds an entry to the pull-down menu. The tag comes back in the MenuItemSelected event; if it is omitted, the rank of the entry is used.

Sub AddSeparator()

—

Properties

ShowsIndicator As Boolean

False = the button does not show the menu chevron.

Events

• Event MenuItemSelected(title As String, tag As Integer)

Constructor

Sub Constructor(identifier As String)

Methods

Sub BeginSearchInteraction()

Expands the field and gives it the focus.

Function SearchFieldHandle() As Ptr

The NSSearchField hosted by the item.

Properties

PlaceholderText As String

—

PreferredWidth As Double

—

Text As String

—

Events

• Event SearchEnded()
• Event SearchStarted()
• Event TextChanged(text As String)

Constructor

Sub Constructor(identifier As String)

Methods

Sub SetFiles(paths() As String)

The files offered for sharing. Copied on the Xojo side, read again on every click.

Methods

Sub SetEnabled(enabled As Boolean)

Called when the toolbar item hosting this container changes state: it is up to the container to propagate enabling or dimming to its own controls, AppKit not knowing how to do it for a custom view.

Constructor

Sub Constructor(title As String, style As BezelStyles = BezelStyles.Push)

Methods

Function Handle() As Ptr

—

Sub Refit()

To be called again after changing the title, the style or the symbol: the ideal size of a button depends on its bezel as much as on its content.

Sub SetButtonType(type_ As ButtonTypes)

The TYPE decides the behaviour on click — momentary, toggle, checkbox, radio — where the bezel decides only the drawing. The two are independent: a checkbox keeps a bezel, a push button can behave as a toggle. The constructor sets MomentaryPushIn, the ordinary button.Careful: setButtonType: RESETS the bezel and the image to values proper to the type. To be called BEFORE setting BezelStyle, never after.

Sub SetBordered(bordered As Boolean)

Without a border, a symbol button becomes a plain clickable icon: that is what is wanted in a command bar that already carries its own background.

Sub SetControlSize(size As ControlSizes)

—

Shared Function FontSizeForControlSize(size As ControlSizes) As Double

The font size the system pairs with this control size — measured on macOS 15.7.9: Regular 13, Small 11, Mini 9, Large 13. AppKit does NOT link the two properties: setControlSize: only affects metrics and never changes a control's font. To make a label follow the control size, set FontSize yourself from this value.Large is identical to Regular. ExtraLarge returns 12 on a system older than macOS 26: a meaningless fallback, not to be used before checking against the macOS 26 SDK.

Sub SetDefault(isDefault As Boolean)

The default button is not a style: it is the one that answers Return. AppKit then tints it with the accent colour, of its own accord.

Sub SetDestructive(destructive As Boolean)

macOS 11+. The button turns red, like “Delete” in an alert. On an earlier system the call is simply without effect.

Sub SetSymbol(symbolName As String, accessibilityDescription As String = "")

An SF symbol rather than a title — indispensable for round bezels (Circular) where a word would not fit.

Sub SetImage(item As FolderItem)

An image from DISK, when the subject does not exist as a symbol — an application logo, say.

Sub SetPicture(source As Picture)

A Xojo Picture, for whatever the application draws itself. CopyOSHandle returns an NSImage you OWN — “Copy” in the name — and the button retains it on its side: it is released once set.

Properties

ImagePosition As ImagePositions

Where the icon sits relative to the title. NSCellImagePosition, read from NSCell.h — the values follow no visual order: Below is 4 and Above 5. Leading and Trailing follow the writing direction; Left and Right never move.MEASURED: fittingSize IGNORES Above and Below — it returns the same height as with no image, 24 points. The height is yours to set.

ImageHugsTitle As Boolean

True places the icon next to the title and centres the pair — almost always what you want. False pins it against the frame edge and centres the title in what remains: the icon then looks stranded away from the word.

BezelStyle As BezelStyles

—

State As Integer

NSControlStateValue: Off = 0, On = 1, Mixed = -1. Only meaningful with a stateful type — Switch, Radio, PushOnPushOff, OnOff.

Enabled As Boolean

—

Title As String

—

BorderShape As NativeControlHost.BorderShapes

macOS 26. The SELECTOR is queried, not the version number: on an earlier system the control keeps its look instead of raising.

TintProminence As NativeControlHost.TintProminences

macOS 26. The SELECTOR is queried, not the version number: on an earlier system the control keeps its look instead of raising.

Events

• Event Pressed()

Enumerations

Constructor

Sub Constructor(title As String, style As Styles = Styles.Split)

In Split style, the arrow is a separate zone: clicking the title fires the action, clicking the arrow opens the menu. In Unified, a single segment: since the action is set, a click fires it and the menu appears only on press and hold — the header says so, and this class always sets its action.

Methods

Function Handle() As Ptr

—

Sub AddItem(title As String)

The header is explicit: the menu items carry THEIR OWN target and action, independent of the button's main action. The tag carries the index, the only way to know which one was chosen.

Sub RemoveAllItems()
Function ItemCount() As Integer

Empties the menu and resets the counter: each item's tag is its rank, and items added afterwards would otherwise carry shifted indexes.

Sub SetItems(ParamArray titles() As String)

—

Sub SetSymbol(symbolName As String, accessibilityDescription As String = "")

—

Properties

Style As Styles

—

Title As String

—

Events

• Event ItemChosen(index As Integer, title As String)
• Event Pressed()

Enumerations

Constructor

Sub Constructor(pullsDown As Boolean = False, style As NativeButton.BezelStyles = NativeButton.BezelStyles.Push)

Methods

Function Handle() As Ptr

—

Sub AddItem(title As String)

—

Sub AddSeparator()

—

Function Count() As Integer

—

Sub RemoveAllItems()

—

Sub SetItems(ParamArray titles() As String)

—

UsesItemFromMenu As Boolean

macOS 15. On a PULL-DOWN, YES makes the first item serve as the title and hides it from the list; NO leaves the button carrying its own title, which is empty until one is set. The setter calls synchronizeTitleAndSelectedItem: AppKit does NOT re-derive the title when going back to YES, and without it, unticking then re-ticking leaves the button permanently silent.

AltersStateOfSelectedItem As Boolean

macOS 15. YES ticks the chosen item. “This property is ignored for pull-down buttons”: a pull-down has no selected item to tick.

Properties

BezelStyle As NativeButton.BezelStyles

—

SelectedIndex As Integer

—

SelectedTitle As String read-only

—

Events

• Event Changed(index As Integer)

Constructor

Sub Constructor(onState As Boolean = False)

Methods

Function Handle() As Ptr

—

Properties

Value As Boolean

NSControlStateValue: Off = 0, On = 1 (Mixed = -1, not applicable here).

Events

• Event Changed(value As Boolean)

Constructor

Sub Constructor(minimum As Double = 0, maximum As Double = 100, increment As Double = 1, value As Double = 0)

Methods

Function Handle() As Ptr

—

Sub SetBehaviour(autorepeat As Boolean, wraps As Boolean)

autorepeat: holding the arrow runs through the values. wraps: past the maximum, it starts again from the minimum — useful for hours.

Properties

Value As Double

—

Events

• Event Changed(value As Double)

Constructor

Sub Constructor(placeholder As String = "", style As Bezels = Bezels.Square)

Methods

Function Handle() As Ptr

—

Sub SetAlignment(alignment As Alignments)

NSTextAlignment is not the same number on every architecture: the SDK switches on TARGET_ABI_USES_IOS_VALUES. On Apple Silicon, Centre = 1 and Right = 2; on Intel, the other way round.

Sub SetBordered(bordered As Boolean, drawsBackground As Boolean = True)

—

Sub SetEditable(editable As Boolean, selectable As Boolean = True)

—

Sub SetPlaceholders(ParamArray items() As String)

macOS 26: SEVERAL placeholders, which the field cycles through one after another — “Search for a package”, then “Search for a component”…The fallback is not “do nothing”: on an earlier system we set the FIRST one. A field that lost every placeholder would be a regression, not a degradation.

AllowsWritingTools As Boolean

macOS 15.2, default YES. To be set to NO on a field that holds no prose: an identifier, a path, a licence key.

AllowsWritingToolsAffordance As Boolean

macOS 15.4, default NO. The button the system places in the field. Only meaningful if the previous one is true.

Sub SetContentType(kind As ContentTypes)

NSTextContentType — a semantic hint about what the field EXPECTS, not access to anything. It is what lets the system offer, above the field, the one-time code received by SMS or iMessage: the app never reads the message, only the system does. Telephone, Email and URL have no visible effect without data the system already knows — it is a hint, not a rendering.

Shared Function SymbolFor(kind As ContentTypes) As String

The exported AppKit symbol name for a given value. Public and shared: NativeTextFieldControl uses it too, rather than duplicating the 43 cases.

Properties

Bezel As Bezels

setBezelStyle: has an effect only on a bordered field: without a border there is no bezel to draw.On macOS 27, Square and Rounded are drawn identically — same rounded corners, same line of about 12 % grey, measured pixel by pixel on a 27.0 system. The setting stays applied and keeps its meaning on macOS 15. See the pitfall “a white field on a white window”.

Placeholder As String

—

Text As String

—

Events

• Event Accepted(text As String)
• Event Changed(text As String)

Enumerations

Constructor

Sub Constructor(placeholder As String = "")

We stay in “internal list” mode (usesDataSource = NO): the items live in the control, with no dataSource to hold.

Methods

Function Handle() As Ptr

—

Sub AddItem(value As String)

—

Function Count() As Integer

—

Sub RemoveAllItems()

—

Sub SetCompletes(completes As Boolean)

The typing completes itself on the first item that starts the same way, like Mail's address field.

Sub SetItems(ParamArray values() As String)

—

Sub SetVisibleItems(count As Integer)

The number of rows shown before the list scrolls. 5 by default.

Properties

Placeholder As String

—

SelectedIndex As Integer

−1 when the typed text matches no item — the normal case for a combo box, which accepts free values.

Text As String

—

Events

• Event Accepted(text As String)
• Event Changed(text As String)
• Event SelectionChanged(index As Integer, value As String)

Constructor

Sub Constructor(placeholder As String = "")

Methods

Function Handle() As Ptr

—

Function RecentSearches() As String()

—

Sub SetLiveSearch(live As Boolean)

By default the action fires only on validation. In live mode, it fires on every keystroke — handy for filtering a list as you type.

Sub SetRecentsMenu(maximumRecents As Integer = 10)

Without a template menu, the magnifier stays silent. AppKit itself replaces the items marked with a special tag; we merely supply the mould.

Sub SetPlaceholders(ParamArray items() As String)

macOS 26: SEVERAL placeholders, which the field cycles through one after another — “Search for a package”, then “Search for a component”…The fallback is not “do nothing”: on an earlier system we set the FIRST one. A field that lost every placeholder would be a regression, not a degradation.

Properties

Placeholder As String

—

Text As String

—

Events

• Event Changed(text As String)

Constructor

Sub Constructor(style As Styles = Styles.DiscreteCapacity, minimum As Double = 0, maximum As Double = 10, value As Double = 5)

Methods

Function Handle() As Ptr

—

Sub SetEditable(editable As Boolean)

Makes the gauge editable with the mouse — indispensable for a rating.

Sub SetBands(thresholds() As Double, colors() As Color)

Generalises SetThresholds to any number of bands.thresholds must be increasing, and colors must have one element more: the value takes colors(i) as soon as it is <= thresholds(i), the last colour covering everything beyond the last threshold. The reading direction therefore rests solely on the order of the colours — red first for a battery gauge, green first for a disk fill. SetBands(Array(2.0, 4.0, 7.0), Array(red, orange, yellow, green))

Sub SetThresholds(warning As Double, critical As Double, inverted As Boolean = False)

Two semantics, and only one is native.NORMAL (inverted = False): ABOVE the warning threshold the gauge turns yellow, above the critical threshold red. This is AppKit's behaviour, documented as such in the header — “values above the warning threshold”. Suits a disk fill: the higher, the worse. INVERTED (inverted = True): BELOW the warning threshold yellow, below the critical one red — the direction of a battery gauge. AppKit cannot do it, so this is nothing but a particular case of SetBands with three bands.

Sub SetTicks(count As Integer, major As Integer = 0)

—

Properties

Value As Double

—

Events

• Event Changed(value As Double)

Enumerations

Constructor

Sub Constructor(initialColor As Color = &c007AFF, style As Styles = Styles.Standard)

Methods

Function Handle() As Ptr

—

Properties

Style As Styles

colorWellStyle dates from macOS 13; below that, the well keeps the classic presentation without anyone having to worry about it.

Value As Color

—

MaximumLinearExposure As Double

macOS 26. The SELECTOR is queried, not the version number: on an earlier system the control keeps its look instead of raising. Beyond 1, the well allows HDR colours to be chosen: the value is the maximum linear exposure accepted.

Events

• Event Changed(value As Color)

Enumerations

Constructor

Sub Constructor()

Its only method takes an Objective-C BLOCK. Xojo has built one since 2019r2 with the framework's ObjCBlock class: you give it a Delegate, it returns a Handle to pass to the Declare. Nothing to assemble in memory.

Methods

Function Handle() As Ptr

—

Function Show() As Boolean

Returns False if the eyedropper is not available — system too old. The sampling is ASYNCHRONOUS: Show returns at once, the Picked event arrives later. The instance must therefore survive until then, in a property of the window.

Events

• Event Picked(value As Color, cancelled As Boolean)

Delegate

• Delegate Sub SamplerHandler(nsColor As Ptr)

Constructor

Sub Constructor(style As Styles = Styles.TextFieldAndStepper)

Methods

Function Handle() As Ptr

—

Sub SetBordered(bezeled As Boolean, bordered As Boolean = False)

—

Sub SetElements(dateElements As DateElements, timeElements As TimeElements)

NSDatePickerElementFlags is a BIT FIELD, not a plain enumeration: the two groups combine. YearMonthDay is 224 and already contains YearMonth (192); HourMinuteSecond (14) contains HourMinute (12).

Sub SetRange(minimum As DateTime, maximum As DateTime)

Passing Nil on both sides removes the bounds.

Properties

Duration As Double

In Range mode, the duration in seconds covered from Value onwards; 0 in OneDate mode.

Mode As Modes

—

Style As Styles

—

Value As DateTime

—

Events

• Event Changed(value As DateTime, duration As Double)

Enumerations

Constructor

Sub Constructor(width As Double = 600, height As Double = 300)

The model, since 14 September 2026. The outline holds the nodes in storage order, their parents (Nil for the root) and a number → row table rebuilt after every structural change. The keys handed to AppKit are tied to the node's number, never to its row: they stay right whatever moves. The former model returned the row index as identifier, and only appending could animate.

Building

Function AddNode(parent As NativeOutlineNode, ParamArray cells() As String) As NativeOutlineNode
Function AddNodeArray(parent As NativeOutlineNode, cells() As String) As NativeOutlineNode

Adds a node as the last child of parent — Nil for the root — and returns it: that is what you keep, and pass as the parent of its children.No animation: the form used to build a tree before showing it. AddNodeArray is public because a ParamArray does not carry from one method to another. And AddRow, inherited from the table, now creates a top-level node instead of growing the storage with no node.

Function AddFolder(parent As NativeOutlineNode, item As FolderItem, depth As Integer = 3) As NativeOutlineNode

Populates the tree from disk. The kind comes from NativeFileKind: an application or a Photos library is a folder to the file system, but we do not go into it — the Finder does not either.Writes three columns: name, kind, size. The following ones stay empty — that is where a checkbox goes to compose a payload.

Changing, animated

Function InsertNode(parent As NativeOutlineNode, index As Integer, cells() As String, animation As NativeTableView.Animations = SlideDown) As NativeOutlineNode
Function AddNodeAnimated(parent As NativeOutlineNode, cells() As String, animation As NativeTableView.Animations = FadeSlideDown) As NativeOutlineNode

Inserts a node at position index among parent's children; out of bounds, last. AddNodeAnimated is the same in last position.Storage follows sibling order: the row is placed just before the row of the sibling it precedes. The index handed to AppKit is the final position — the insertObjects:atIndexes: semantics the header adopts.

Sub RemoveNode(node As NativeOutlineNode, animation As NativeTableView.Animations = SlideUp)

Removes the node and all its descendants. The other nodes keep their number; only the removed ones become invalid, and every method then ignores them without raising.

Function MoveNode(node As NativeOutlineNode, newParent As NativeOutlineNode, index As Integer) As Boolean

Moves the node with its descendants to position index among newParent's children — final position, counted without the node. Returns False, doing nothing, for a move into its own descendants.Proven before being written: 180,000 random operations — insertions, removals, moves — without a single discrepancy between this model, a reference tree and the view AppKit rebuilds from the indexes it is sent alone, row formatting included.

When animating is not safe

An index AppKit does not know raises an Objective-C exception, which stops a Xojo application. AppKit knows the children only of a parent that is shown and expanded, and nothing before its first load. Outside those cases, the tree is reloaded instead — without loss: the keys being tied to the number, expansion and selection survive.

Dragging nodes

AllowsRowReordering As Boolean

Inherited from the table, and valid for the outline since 14 September 2026, through its own data source methods: outlineView:pasteboardWriterForItem:, validateDrop:proposedItem:proposedChildIndex: and acceptDrop:item:childIndex:. You drop between two nodes, or onto a node to put it inside, last — the proposed index is then -1.Dropping into its own descendants is refused while hovering, and the cursor shows it. Several nodes drop as a block, in on-screen order: each is placed in turn just before an anchor — the first non-dragged sibling after the drop point —, and a node whose ancestor is also dragged travels with it. Proven on 14,407 random drops against an independent computation — remove the block, reinsert it at once —, without a single discrepancy. The dragged type is specific to outlines, and a drag coming from another view is ignored: a node number only means something in its own tree.

Event NodesMoved(nodes() As NativeOutlineNode, newParent As NativeOutlineNode, index As Integer)

The dropped nodes, in on-screen order, their new parent — Nil for the root — and the position of the first. The counterpart of RowsMoved; the block stays selected, and a drop onto a collapsed node expands it.

Walking

Function Contains(node As NativeOutlineNode) As Boolean
Function NodeCount() As Integer
Function ParentOf(node As NativeOutlineNode) As NativeOutlineNode
Function ChildCount(parent As NativeOutlineNode) As Integer
Function ChildAt(parent As NativeOutlineNode, index As Integer) As NativeOutlineNode
Function IndexOf(node As NativeOutlineNode) As Integer

Nil means the root. Contains is true for a node of this outline that has not been removed; ParentOf also returns Nil for a foreign node, and Contains decides. IndexOf gives the index InsertNode and MoveNode expect.

Function RowOf(node As NativeOutlineNode) As Integer
Function NodeAt(row As Integer) As NativeOutlineNode

The link to the inherited row methods, which take a storage row.The row changes as soon as something is inserted, removed or moved elsewhere: do not keep it, keep the node.

Cells, selection and expansion, by node

Function NodeCell(node, column) As String · Sub SetNodeCell(node, column, value)
Function NodeChecked(node, column) As Boolean · Sub SetNodeChecked(node, column, checked)
Sub SetNodeIcon(node, symbolName) · Sub SetNodeSubtitle(node, column, subtitle)
Sub SetNodeBold(node, column, bold) · Sub SetNodeTextColor(node, column, textColor)
Sub SetNodeBackground(node, column, backColor) · Sub ReloadNode(node)

The node version of each inherited row method: RowOf does the translation. ReloadNode redraws a node already on screen — after a SetNodeIcon, for instance.

Sub SelectNode(node) · Function SelectedNode() As NativeOutlineNode
Function SelectedNodes() As NativeOutlineNode() · Sub ScrollToNode(node)
Sub ExpandNode(node, withChildren As Boolean = False) · Sub CollapseNode(node, withChildren As Boolean = False)
Function IsNodeExpanded(node) As Boolean · Sub ExpandAll() · Sub CollapseAll()

SelectNode(Nil) deselects. A node under a collapsed parent has no row on screen: it cannot be selected.

Events

Event NodeSelectionChanged(node As NativeOutlineNode)
Event NodeCellChanged(node As NativeOutlineNode, column As Integer, value As String)
Event NodeDoubleClicked(node As NativeOutlineNode)

Raised in addition to the table's, which give a storage row. Prefer these: a row changes as soon as something is inserted or moved.

Why a type of its own

A stable number kept as an Integer would have compiled everywhere, and matched the row… until the first removal, then silently broken everything. With a type of its own, the compiler points at every place to revisit. The link to the tree is weak: keeping nodes does not keep the tree alive.

Methods

Function Id() As Integer

A number specific to the tree, never reused — not even after RemoveAllRows. To compare two nodes, Is is enough: the tree always returns the same object for the same node.

Function IsValid() As Boolean

False if the node was removed, if the tree was cleared, or if it no longer exists.

Function Tree() As NativeOutlineView
Function BelongsTo(tree As NativeOutlineView) As Boolean

The node's tree, through a weak link; Nil if it is gone.

Sub Constructor(owner As NativeOutlineView, nodeId As Integer)

Reserved to the tree. A hand-made node, even with an existing number, is not recognised: Contains requires the object the tree returned.

Constructor

Sub Constructor(style As Styles = Styles.Standard)

Methods

Function Handle() As Ptr

—

Sub SetAllowedTypes(ParamArray types() As String)

Extensions or UTIs. Used by the NSOpenPanel the control opens by itself in editable PopUp style; with no list, everything is accepted.

Sub SetAllowedTypeArray(types() As String)

The array form, for NativePathBarControl. An empty array sets nil: for the header, an empty list would allow nothing.

Sub SetEditable(editable As Boolean)

Combined with the PopUp style, adds the “Choose…” entry that opens the panel.

Sub SetPlaceholder(text As String)

—

Properties

Path As String

—

Style As Styles

—

Value As FolderItem

—

Events

• Event Changed(item As FolderItem, path As String)
• Event DoubleClicked(item As FolderItem, path As String)

Enumerations

Constructor

Sub Constructor(labels() As String, selectOne As Boolean = True)

Methods

Function Handle() As Ptr

—

Function IsSelected(index As Integer) As Boolean

Only meaningful in SelectAny mode: elsewhere, SelectedIndex is enough.

Sub Refit()

To be called again after a change of style, symbol or width: the ideal size depends on all three.

Sub SetDistribution(distribution As Distributions)

macOS 10.13+. Decides the fate of the remaining space: left empty, shared out, or segments equalised. Without effect below.

Sub SetSelected(index As Integer, selected As Boolean)

The counterpart of IsSelected, for ticking several segments in SelectAny.

Sub SetSymbol(index As Integer, symbolName As String, accessibilityDescription As String = "")

An SF symbol instead of — or beside — the label. A symbol that cannot be found simply leaves the segment as it is.

Sub SetWidth(index As Integer, width As Double)

0 makes the segment dynamic: the distribution then decides.

Properties

SelectedIndex As Integer

—

Style As Styles

—

TrackingMode As TrackingModes

—

BorderShape As NativeControlHost.BorderShapes

macOS 26. The SELECTOR is queried, not the version number: on an earlier system the control keeps its look instead of raising.

Events

• Event Changed(index As Integer)

Enumerations

Constructor

Sub Constructor(minimum As Double = 0, maximum As Double = 100, value As Double = 50, width As Double = 120, leadingSymbol As String = "", trailingSymbol As String = "")

If SF symbols are supplied, the slider is framed by two small images in a host view — the Preview or Photos pattern. Handle then returns that host view, SliderHandle the slider itself.

Methods

Function Handle() As Ptr

The view to hand to the item: icons + slider together where applicable.

Sub SetTicks(count As Integer, valuesOnly As Boolean = False)

Tick marks under the slider. valuesOnly forces the values to align on them.

Sub SetTooltip(text As String)

—

Function SliderHandle() As Ptr

—

Properties

Value As Double

—

TintProminence As NativeControlHost.TintProminences

macOS 26. The SELECTOR is queried, not the version number: on an earlier system the control keeps its look instead of raising.

NeutralValue As Double

macOS 26. The SELECTOR is queried, not the version number: on an earlier system the control keeps its look instead of raising. The ORIGIN of the fill, not a bound: a balance slider fills from the centre rather than from the left.

Events

• Event Changed(value As Double)

Constructor

Sub Constructor(indeterminate As Boolean = True, width As Double = 120)

Methods

Function Handle() As Ptr

—

Sub StartAnimation()

—

Sub StopAnimation()

—

Properties

Value As Double

0 to 100 by default (minValue/maxValue unchanged).

Constructor

Sub Constructor(placeholder As String = "")

NSTokenField inherits from NSTextField, but its objectValue is NOT a string: it is an NSArray. Reading stringValue returns only the flattened representation, separated by the tokenizing character set.

Methods

Function Handle() As Ptr

—

Sub SetCompletions(ParamArray candidates() As String)

The list completion draws on. Empty = no completion.

Sub SetTokenizingCharacter(separator As String = ",")

The character that validates a token. A comma by default in AppKit; the semicolon is common for addresses.

Sub SetTokens(ParamArray values() As String)

—

Sub SetTokenArray(values() As String)
Sub SetCompletionArray(candidates() As String)

The array forms of SetTokens and SetCompletions: a ParamArray cannot be passed from one method to another, and NativeTokenFieldControl forwards lists read from the Inspector.

Function Tokens() As String()

objectValue is an NSArray, NOT a string — that is the whole difference with the NSTextField that NSTokenField inherits from. Reading stringValue would return only the flattened version, glued back together by the tokenizing character.

Properties

Placeholder As String

—

Style As Styles

—

Events

• Event Changed(tokens() As String)

Enumerations

Constructor

Sub Constructor(width As Double = 520, height As Double = 260)

The scroll view serves scrolling and the RULER. It is NOT needed for the format bar — see ShowFormatBar, which is not what one assumes.

Methods

Function Handle() As Ptr

The SCROLL VIEW — that is what is hosted, not the text view. Same convention as NativeSlider with its host view.

Sub LoadRTF(file As FolderItem)

Replaces the whole content. The RTF primitives already live in the Cocoa module: no need to redeclare them here.

Sub SaveRTF(file As FolderItem)

—

Sub SetAdaptiveDarkMode(adaptive As Boolean)

macOS 10.14+. Without it, an RTF document whose colours are hard-coded stays unreadable in dark mode: the system does not remap them.

Sub SetBorder(kind As Borders)

When the editor is housed in a frame that already draws its border, the scroll view's is redundant.

Sub SetEditable(editable As Boolean, richText As Boolean = True)

—

Sub SetOptions(spellChecking As Boolean = True, linkDetection As Boolean = True, importsGraphics As Boolean = True, fontPanel As Boolean = True)

importsGraphics allows images to be dropped into the text; fontPanel connects the editor to the system Font panel (Cmd-T).

Sub SetWritingTools(behavior As WritingTools)

macOS 15+. None (-1) excludes the view from the writing tools; Complete asks for inline rewriting, Limited the overlay panel.

Sub SetRulerAccessory(view As Ptr)

The THIRD route, and the only one that houses a bar INSIDE the text area: the ruler's accessory view. Verified in Objective-C — the accessory becomes a subview of the NSRulerView, hence of the scroll view; no window accessory is created and the content view does not move.TRAP: setAccessoryView: RAISES AN EXCEPTION if the ruler's clientView has not been set — “you must set the client view of the ruler before you can have an accessory view”. This is not a no-op, it is a crash. Also worth knowing: the graduated ruler comes WITH it. In the trial, a 60-point ruler for 28 of accessory. For a bar on its own in a frame, NativeRichTextEditor's home-made bar remains preferable.

Sub ShowFindBar(visible As Boolean)

TextEdit's search bar, Cmd-F. incrementalSearching highlights as you type.

Sub ShowFormatBar(visible As Boolean)

THE TextEdit RTF bar: font, size, bold/italic/underline, text and background colours. It is usesInspectorBar, which appeared in 10.7.BUT IT DOES NOT BELONG TO THE EDITOR. Verified in Objective-C: AppKit installs an NSTitlebarAccessoryViewController on the WINDOW — an __NSInspectorBarView view, 28 points, layoutAttribute 4, hence under the toolbar and across the full width — and SHRINKS the content view by as much. Turning it off removes the accessory and gives the 28 points back. Three consequences: 1) the bar cannot be confined to a frame: it is at window level, exactly as in TextEdit; 2) any layout that positions its own views must be redone after the call, otherwise the bar covers the content instead of pushing it; 3) neither the scroll view nor the order of the calls changes anything at all — tested without a scroll view, set before setDocumentView:, and outside a window: the accessory is installed in all three cases.

Sub ShowRuler(visible As Boolean)

The graduated ruler, with tab stops and indents. It shares the area with the format bar: both can coexist, one above the other.

Sub ChangeSize(bigger As Boolean)

The “Bigger” / “Smaller” actions of the Format menu: it is the NSFontManager that carries them out, according to the TAG of the object handed to it.

Function IsBold() As Boolean

—

Function IsItalic() As Boolean

—

Sub SetAlignment(alignment As Alignments)

Native NSText actions: they already know which paragraphs to touch.

Sub ShowColorPanel()

The panel sends changeColor: to the first responder: it is the NSTextView that applies the colour, there is nothing to copy out.

Sub ShowFontPanel()

—

Sub ToggleBold()

—

Sub ToggleBullets()

The only command in the bar with NO native equivalent: AppKit exposes only orderFrontListPanel:, a panel, not a toggle. So “•⇥” is prefixed to each paragraph of the selection, or removed.

Sub ToggleItalic()

—

Sub ToggleUnderline()

A native action, this one: NSText supplies it directly.

Function TextViewHandle() As Ptr

The NSTextView itself, to be passed to the Cocoa module's primitives — ApplyColor, SetTextColorRange, TextLength.

Sub Highlight(scheme As HighlightSchemes = HighlightSchemes.Default)

macOS 15. The Notes highlighter. The colour is NOT passed as an argument: “The sender should be a menu item with a representedObject of type NSTextHighlightColorScheme” — so a throwaway menu item is built to carry it. Calling the same colour again removes the highlight.

Function HighlightSupported() As Boolean

To ADAPT the interface, not to guard the call.

Function WritingToolsActive() As Boolean

macOS 15. Are the tools rewriting the text RIGHT NOW? That is the moment to suspend an autosave or a content analysis, which would work on an intermediate state.

Sub SetAllowedWritingToolsResults(options As Integer)

macOS 15. What the tools are allowed to RETURN. A bit field whose values imply one another: List and Table imply RichText, and PresentationIntent (macOS 26) implies all three. An editor that cannot display a table has every interest in not being offered one.The highlight LOOK — textHighlightAttributes — is deliberately NOT exposed. Tried and withdrawn: the background set that way paints over the glyphs and hides the text, with two colours as with one; forcing a redisplay makes it worse, drawTextHighlightBackgroundForTextRange: being a drawing method that cannot be called outside its pass. Highlight's named schemes do work.

Sub ShowWritingTools()

macOS 15.2. Sends showWritingTools: straight to the view, without depending on the first responder.

Properties

Text As String

The BARE text: the attributes are lost. To keep the formatting, go through SaveRTF.

Events

• Event Changed()

Enumerations

Constructor

Sub Constructor(width As Double = 620, height As Double = 320)

Everything is built in NSBox and not in layers: an NSBox paints with REAL NSColors, so it follows dark mode on its own. A CGColor set in a CALayer is frozen the moment it is written and never updates.

Methods

Function Editor() As NativeTextView

The text view, for everything the bar does not cover: Text, LoadRTF, SaveRTF, ShowRuler, and the native ShowFormatBar.

Function Handle() As Ptr

—

Sub ShowCommandBar(visible As Boolean)

The component's bar and the system's native bar are ALTERNATIVES, not layers: the native one sits on the window (see NativeTextView.ShowFormatBar), this one lives in the frame. Showing both gives two rows of commands that do the same thing.

Sub SetFooter(text As String, buttonTitle As String = "")

The footer: an explanation on the left, a button on the right. Passing an empty title shows no button.

Events

• Event Changed()
• Event CommandUsed(index As Integer)
• Event FooterPressed()

Constructor

Sub Constructor(width As Double = 300, height As Double = 140, accepts As Kinds = Kinds.FilesAndText)

Here the VIEW is itself the destination: no separate target object, so the Cocoa registry maps the view pointer directly to the Xojo object.

Methods

Function Handle() As Ptr

—

Sub SetAccepts(kinds As Kinds)

Registers the accepted types again. unregisterDraggedTypes first: otherwise the old types would remain in addition to the new ones, and the view would carry on accepting what has just been refused it.

Properties

Operation As Operations

The operation announced to the system: it decides the CURSOR the user sees — the “+” of a copy, the curved arrow of an alias.

Events

• Event Dropped(files() As FolderItem, text As String) As Boolean
• Event Entered(hasFiles As Boolean, hasText As Boolean) As Boolean
• Event Exited()

Enumerations

Constructor

Sub Constructor(width As Double = 220, height As Double = 130)

Three overrides, and none is decorative — each answers a measured fact:

mouseDown:

NSView does not implement it: without an override, NSResponder passes the event UP to the nextResponder and the view never follows the gesture. This empty body is therefore a deliberate sink. mouseDragged: that is where the session starts — beginDraggingSession… requires an NSEvent, there is no dragging without a gesture. hitTest:

Methods

Sub AddContent(view As Ptr)

The well draws nothing of itself: you put in it whatever you want shown — a NativeImageView, a NativeBox, a label. hitTest: guarantees that the content will not steal the gesture, whatever it is.

Function Handle() As Ptr

—

Sub SetFiles(files() As FolderItem)

What the drag CARRIES. Replaces any previous content.

Sub SetText(value As String)

—

Properties

Operation As UInteger

What the SOURCE allows. The destination chooses within that set: offering Copy alone means forbidding a move.

PreviewSide As Double

—

StackMultipleItems As Boolean

—

Events

• Event Ended(operation As UInteger)
• Event CancelDrag() As Boolean

Constants

• kFormationStack = 4
• OperationCopy = 1
• OperationLink = 2
• OperationMove = 16

Constructor

Sub Constructor(width As Double = 96, height As Double = 96, scaling As Scalings = Scalings.ProportionallyUpOrDown)

Methods

Sub Clear()

—

Function Handle() As Ptr

—

Sub ShowFile(item As FolderItem)

A preview of the content if it is an image, otherwise the Finder icon — which exists for EVERYTHING: folder, application, unknown document. initWithContentsOfFile returns Nil for a folder as for a text file, hence the fallback.

Sub ShowFinderIcon(item As FolderItem)

The icon the Finder shows for this particular item — not the one for its type. A folder, a package and an application each have their own.

Function ShowThumbnail(item As FolderItem, maxSide As Double = 512) As Boolean

The REAL QuickLook thumbnail — the first page of a PDF, the image itself, the 3D rendering of an STL — and not the icon of the type.WHY THIS ROUTE, and not QLPreviewView: a LIVE preview installs an NSRemoteView served by SceneKitQLPreviewExtension, and displaying a 3D model then destroys the process's drag and drop FOR GOOD — measured, nothing restores it but quitting. The thumbnail, for its part, goes through SceneKitQLThumbnailExtension, the one the Finder uses constantly: it returns an IMAGE, puts no view in our window, and leaves no process behind it. QLThumbnailImageCreate has been deprecated since 10.15 but is still present, and it is SYNCHRONOUS — 43 ms on an STL — where the modern API demands a block and a callback off the main thread. The day it disappears, it will return Nil and we will fall back to the icon: the breakage is already provided for. ONE SIDE ONLY, and it is measured: the size asked for is a BOX the thumbnail has to fit into, and the 3D generator returns 4:3. A box narrower than that ratio makes it fail without a word — 840 x 340 returns Nil, 512 x 512 returns 512 x 384. So we ask for a SQUARE, which contains any natural ratio, and let the view scale it. Beyond 1024, the generator caps itself.

Sub ShowSymbol(symbolName As String, accessibilityDescription As String = "")

—

Sub SetTint(useTint As Boolean, tint As Color = &c000000)

10.14+, and acts only on “template” images — an SF symbol, typically.

Properties

FrameStyle As Frames

—

Scaling As Scalings

—

Enumerations

Constructor

Sub Constructor(width As Double = 480, height As Double = 240, viewClass As String = "NSTableView", dsClass As String = "VDSTableDS")

NativeSidebarBase also wraps an NSTableView, but for a source list: one column, no header, no sorting. The two do not overlap.

The LAST TWO parameters are reserved for subclasses. AppKit derives NSOutlineView from NSTableView: NativeOutlineView does the same, and therefore has only its view class and the name of its data source to supply.

Methods

Sub AddColumn(title As String, width As Double = 140, sortable As Boolean = False, kind As CellKinds = CellKinds.Text, minWidth As Double = 40)

The columns BEFORE the rows: the storage is flat — index = row × number of columns + column —, adding one afterwards would shift everything. Rather than corrupt silently, we clear.

Sub AddRow(ParamArray cells() As String)

The convenient form. The work is in AddRowArray: a ParamArray cannot be passed from one method to another, and a subclass needs the array form — AddNode simply adds a parent to it.

Function CellAt(row As Integer, column As Integer) As String

—

Function CellChecked(row As Integer, column As Integer) As Boolean

A ticked box has no separate storage: it is “1” in the same grid of strings as everything else. One single source of truth.

Function ColumnCount() As Integer

—

Function Handle() As Ptr

The view to SET: the NSScrollView, not the table — the table is its documentView and has no useful size of its own.

Sub Reload()

—

Sub RemoveAllRows()

—

Function RowCount() As Integer

—

Sub ScrollTo(row As Integer)

—

Sub SelectRow(row As Integer)

—

Sub SetCell(row As Integer, column As Integer, value As String)

—

Sub SetCellBackground(row As Integer, column As Integer, backColor As Color)

A background that is SET does not follow dark mode: it is a colour chosen by the application, not a system colour. To be reserved for meaning — a late item in red, an agreement in green — never for decoration.

Sub ClearCellBackground(row As Integer, column As Integer)

—

Sub SetCellTextColor(row As Integer, column As Integer, textColor As Color)

—

Sub SetCellBold(row As Integer, column As Integer, bold As Boolean)

—

Sub SetCellChecked(row As Integer, column As Integer, checked As Boolean)

—

Sub SetCellAlignment(row As Integer, column As Integer, alignment As Alignments)

Overrides the column for THIS cell. Useful where a value changes nature within a single column — a number among text, a total at the bottom of a list.

Sub ClearCellAlignment(row As Integer, column As Integer)

Returns the cell to its column's alignment.

Sub SetCellVerticalAlignment(row As Integer, column As Integer, alignment As VerticalAlignments)

—

Sub ClearCellVerticalAlignment(row As Integer, column As Integer)

—

Sub SetColumnVerticalAlignment(column As Integer, alignment As VerticalAlignments)

AppKit offers NOTHING for this: an NSTextField centres its text in the frame it is given, and that is all. Vertical alignment is therefore done by placing the FRAME in the cell, not by setting a property.

Sub SetColumnAlignment(column As Integer, alignment As Alignments)

—

Sub SetColumnChoices(column As Integer, ParamArray items() As String)

The choices of a Popup column. Stored joined by a line break: an array of arrays does not lend itself to the text format of a Xojo class.

Sub SortBy(column As Integer, ascending As Boolean = True)

The default sort: ALPHABETICAL and case-insensitive, since the model stores nothing but text. To sort numbers or dates, SortChanged must be intercepted and return True.The STYLES follow the rows: a red background set on “late” must stay with it, not stay in third place in the table. An OUTLINE refuses: its rows are nodes, and the parent table designates nodes by their INDEX. Permuting them would break the parent-child link in silence.

Function TableHandle() As Ptr

—

Sub SetRowIcon(row As Integer, symbolName As String)

A system symbol at the start of the FIRST column. The name is the SF Symbols one — “folder”, “doc.text” — and an empty string removes it.

Properties

SelectedRow As Integer read-only

For an OUTLINE, the visible row depends on what is expanded: CurrentRow then returns the node, which is the stable identity.

BezeledEditableCells As Boolean

—

DoubleClickAction As Boolean

EDITING a cell traditionally starts on the second click, and the table's double-click action aims at the same gesture. So the two fight over the mouse on an editable column: disengaging the action hands editing back. A nil SEL disarms cleanly: AppKit sends nothing more.

AlternatingRowColors As Boolean

—

GridMask As UInteger

—

AllowsMultipleSelection As Boolean

—

RowHeight As Double

—

Style As Styles

setStyle: exists only from macOS 11 onwards: on an earlier system the table keeps its original look rather than raising.

ShowsHeader As Boolean

Hiding a header means setting Nil: AppKit then folds away the area the NSScrollView was reserving for it. Bringing it back means PUTTING BACK the one that was set aside at the start. Building a fresh one works too, BUT it has to be given a height: an NSTableHeaderView with a zero frame really is installed, and the scroll view restores its area — at a height of zero. So you see “nothing”, with not the slightest error to say so.

Events

• Event CellChanged(row As Integer, column As Integer, value As String)
• Event RowDoubleClicked(row As Integer)
• Event SelectionChanged(row As Integer)
• Event SortChanged(column As Integer, ascending As Boolean) As Boolean

Enumerations

Constants

• GridNone = 0
• GridVertical = 1
• GridHorizontal = 2

Row animations

Sub InsertRow(index As Integer, cells() As String, animation As Animations = Animations.SlideDown)

Inserts a row AT AN INDEX and animates it, where AddRow appends and forces a full reload.THE MODEL FIRST, AppKit after: insertRowsAtIndexes: immediately asks the data source for the new row; if the store is not already updated, the table reads a row that does not exist.

Sub RemoveRow(index As Integer, animation As Animations = Animations.SlideUp)

Removes a row and animates it.The header notes that indexes passed to removeRowsAtIndexes: refer to the DISPLAYED state, not the final one. No consequence for a single row, but it would matter for several.

Sub MoveRow(fromIndex As Integer, toIndex As Integer)

Moves a row. No animation option, and that is not an oversight: moveRowAtIndex:toIndex: accepts none — the view is neither destroyed nor recreated, the same one simply changes position, and the move animates itself.

Sub BeginUpdates()
Sub EndUpdates()

macOS 10.7. Several changes animate TOGETHER between the two, the starting state being the one before BeginUpdates. Calls nest.Unnecessary for a single change — the header says so — but essential as soon as there are two, otherwise each animates on its own and the result jumps.

Sub ReloadRow(row As Integer)

macOS 10.6. Redraws ONE row instead of reloading the whole table: selection, scrolling and the other rows' views are preserved. Works for an outline too.

Enum Animations

None, Fade, Gap, the four slides and the four fade combinations.The slide options are NOT flags, despite appearances. Measured: SlideUp 16, SlideDown 32, SlideLeft 48, SlideRight 64 — and SlideUp Or SlideLeft gives 48, that is SlideLeft. It is a FIELD, and the header confirms it: « only one option from this group may be specified at a time ». Only the fade truly combines, hence the ready-made combinations rather than an addition that would silently give the wrong value.

Two-line cell

Sub SetCellSubtitle(row As Integer, column As Integer, subtitle As String)
Function CellSubtitle(row As Integer, column As Integer) As String

The second line of a CellKinds.Subtitle cell — the Mail-list pattern: a title, and below it a smaller, paler line. Kept in its own parallel array, like every other per-cell property, rather than encoding two values in one string — which would make CellAt return « title + separator + subtitle ».It needs height: two lines do not fit in a standard 22-point row. Below RowHeight = 34 the subtitle is clipped.

Columns and selection

Function SelectedRows() As Integer()
Sub SelectRows(rows() As Integer, extend As Boolean = False)
Function IsRowSelected(row As Integer) As Boolean

AllowsMultipleSelection already existed, but nothing let you READ the selection — a multiple selection you can switch on without being able to read it is half a feature. SelectedRow only returns the current row.Walking the NSIndexSet is bounded by the row count rather than compared against NSNotFound. That one is NSIntegerMax — 9223372036854775807 — which a Double cannot represent: it rounds to …808, the comparison would never be true and the loop would never end. Verified, not assumed.

AllowsColumnReordering As Boolean
AllowsColumnResizing As Boolean

Drag columns to reorder them, resize them by dragging between headers. Both default to True in AppKit, and this class keeps that default.A column only resizes if it allows it for itself — see -[NSTableColumn setResizingMask:]. And programmatic changes remain possible whatever the setting.

Sub SetIntercellSpacing(horizontal As Double, vertical As Double)
Function IntercellSpacing() As Cocoa.NSSize

The spacing between cells. AppKit's default is 3 × 2.The height ADDS to RowHeight: a row's real rectangle is rowHeight plus intercellSpacing.height, as the header states about rectOfRow:.

Event ColumnClicked(column As Integer)
Event ColumnDragged(column As Integer)

A click on a header, distinct from sorting, and the end of a column drag.

Event ShouldRefuseColumnReorder(column As Integer, toColumn As Integer) As Boolean

The veto. It asks what to REFUSE, not what to allow, and the inversion is deliberate: a RaiseEvent with no handler returns False, so asking the question the other way round would forbid every move by default. Inverted, no handler means everything is allowed — like AppKit when the delegate method is not implemented.toColumn is -1 on the FIRST call, when the column is grabbed and before any destination exists. The header says so: refusing at that moment forbids moving that column at all.

Row dragging

AllowsRowReordering As Boolean

Move a row by dragging it with the mouse. The drop calls MoveRow, so the move animation serves here with no extra line of code. Also valid for NativeOutlineView since 14 September 2026, through its own data source methods — see its card.As in Numbers: the original row stays in place and selected, a ghost — a copy of the grabbed rows on a card with an accent-colour border and a pronounced drop shadow — follows the cursor inside the table, and AppKit draws the insertion line (Regular feedback style). Non-contiguous rows are packed together in the ghost.The ghost is a real view placed in the table, made of photos taken when the rows are grabbed; AppKit's drag image is emptied. The Gap style, used at first, hid the grabbed row: the selection vanished and an empty hole remained. A drop proposed on a row is retargeted above it.

Event RowsMoved(sources() As Integer, firstRow As Integer)

Raised after a successful drop: the ORIGINAL indices in ascending order, and where the block landed. A non-contiguous selection gives several at once.The drop arithmetic is the one delicate spot. AppKit gives the insertion index in the coordinate space BEFORE the move, and each removed row shifts everything after it by one — with a multiple selection those shifts compound. The algorithm is not reasoned but verified: simulated over the 1757 cases formed by every size up to seven rows, every selection subset and every drop point, compared against an independently computed result. Zero divergence.

Constructor

Sub Constructor(width As Double = 600, height As Double = 300, itemWidth As Double = 104, itemHeight As Double = 104)

VERIFIED rather than assumed: an NSCollectionViewItem accepts having its view SET, and loadView is then never called. It is the same trick NativeWindowChrome uses for its NSViewController, and it does away with nibs entirely.

Methods

Sub AddFile(item As FolderItem)

The Finder icon accounts for THIS particular item — folder, application, document — and not for its type. It is what the user sees.

Sub AddItem(title As String, symbolName As String = "")

—

Function Count() As Integer

—

Function Handle() As Ptr

The view to SET: the NSScrollView, not the grid — the grid is its documentView and resizes itself.

Sub Reload()

—

Sub RemoveAllItems()

—

Sub SetItemSize(width As Double, height As Double)

—

Sub SetSpacing(betweenItems As Double, betweenLines As Double)

—

Properties

HorizontalScrolling As Boolean

—

AllowsMultipleSelection As Boolean

—

Events

• Event SelectionChanged(index As Integer)

Constructor

Sub Constructor(width As Double = 560, height As Double = 180)

The editor GROWS with the rules added: so it lives in an NSScrollView, without which the bottom rows fall outside the frame.

Methods

Sub AddField(keyPath As String, kind As Kinds = Kinds.Text)

The field is designated by its KEY PATH — “name”, “size”. That is what appears in the first menu of each rule, and what will be found again in the predicate produced.

Sub Build()

One row template per TYPE, not per field: AppKit expects to be given all the left-hand expressions sharing the same type and the same operators in a single NSPredicateEditorRowTemplate.

Sub AddRow()

addRow: RAISES an NSRangeException inside AppKit — verified — if the root row is not COMPOUND. The editor falls into that state as soon as a simple predicate is set on it, and the “add” button then becomes a mine. So the root is restored before adding.

Function Handle() As Ptr

The view to SET: the NSScrollView, the editor growing with its rules.

Function PredicateFormat() As String

The TEXTUAL form of the predicate — “name CONTAINS "a" AND size > 100”. It is what gets saved, and the only thing that can be read back.

Function RowCount() As Integer

—

Sub SetPredicateFormat(format As String)

DANGER, and it is real: predicateWithFormat: raises an NSInvalidArgumentException on a malformed string — verified —, and an Objective-C exception CANNOT be caught from Xojo: it ends the process. Pass only strings here that you produced yourself, typically read back from PredicateFormat.

Properties

NestingMode As NestingModes

—

RowHeight As Double

—

Events

• Event Changed(predicateFormat As String)

Enumerations

Properties

ControlSize As NativeButton.ControlSizes

AppKit control size. The font is reapplied by hand: DesktopButton already sets an explicit one before Opening, which prevents the automatic size adjustment.

Bordered As Boolean

Button border (setBordered:).

ShowsBorderOnlyOnHover As Boolean

The border appears only while the mouse is inside.

Symbol As String

The NAME of an SF Symbol — square.and.arrow.up — not a file: a symbol follows the text size, dark mode and accentuation, which no placed image does. Empty = no icon. An unknown name leaves the button as it is.

ImagePosition As NativeButton.ImagePositions

Where the icon sits, settable in the Inspector. Leading by default.

ImageHugsTitle As Boolean

Icon next to the title, the pair centred. True by default.

Properties

Caption As String

The title, as on a Xojo button.

SymbolName As String

The NAME of an SF Symbol — square.and.arrow.up. Empty removes the icon; an unknown name leaves the button as it is. A file image or a Picture go through SetImage and SetPicture.

ImagePosition As NativeButton.ImagePositions

Where the icon sits. Leading by default.Above and Below need ANOTHER BEZEL: with Push, the title is drawn outside the frame — measured from 32 to 60 points tall. FlexiblePush and SmallSquare contain both.

ImageHugsTitle As Boolean

Icon next to the title, the pair centred. True by default. False pins the icon against the frame edge.

BezelStyle As NativeButton.BezelStyles

The frame drawing, down to the help circle and the capsule.

ControlSize As NativeButton.ControlSizes

The system control size. The button is re-centred on every change.

Methods

Function Inner() As NativeButton

The hosted object, for everything the Inspector does not expose.

Sub SetImage(item As FolderItem) · Sub SetPicture(source As Picture)

An image from disk or a Xojo Picture, instead of the symbol.

Events

Event Pressed()

—

Properties

ControlSize As NativeButton.ControlSizes

AppKit control size. The font is reapplied by hand: DesktopButton already sets an explicit one before Opening, which prevents the automatic size adjustment.

MixedState As Boolean

Indeterminate state (allowsMixedState + state = -1): neither on nor off. Not to be confused with the Inspector's VisualState, which only drives the editor preview — Value overrides it at runtime.

Properties

ControlSize As NativeButton.ControlSizes

AppKit control size. The font is reapplied by hand: DesktopButton already sets an explicit one before Opening, which prevents the automatic size adjustment.

Properties

Sub ReapplyNativeSettings()

Call after any change to Password. Toggling Password makes Xojo DESTROY the view and CREATE another, and Opening is not raised on the new one: everything this class had set disappears with no error and no warning.Measured on a live object — the Handle pointer changes on every toggle, three toggles giving three distinct views; contentType returned one-time-code before and none after. Xojo offers no way to intercept a write to an inherited property, so the re-apply cannot be automatic.And the call must be DEFERRED — Timer.CallLater, not an immediate call: asking for the Handle before Xojo has finished installing the replacement view forces its creation OUTSIDE its panel, and the field ends up placed at window level.

EchosBullets As Boolean

The bullets of a password field. A CELL property, which NSSecureTextField does not forward, and which exists only while Password is True — otherwise the cell is a plain XOJTextFieldCell that does not answer the selector.

ContentType As NativeTextField.ContentTypes

NSTextContentType semantic hint: what the field EXPECTS. It is what lets the system offer a code received by SMS. The lookup table is shared with NativeTextField.SymbolFor, not duplicated.

AllowsWritingTools As Boolean

macOS 15.2.

AllowsWritingToolsAffordance As Boolean

macOS 15.4. Only applies when AllowsWritingTools is true.

Properties

ContinuousSpellChecking As Boolean

Spell checking as you type.

AutomaticLinkDetection As Boolean

Only fires on text TYPED afterwards, not on text already present.

UsesFindBar As Boolean

TextEdit's find bar (Cmd-F), with incremental searching.

Properties

AltersStateOfSelectedItem As Boolean

Ticks the selected item. Ignored on a pull-down button.

UsesItemFromMenu As Boolean

Only applies to a PULL-DOWN button — DesktopPopupMenu stays pop-up style. Reapplies synchronizeTitleAndSelectedItem, without which unticking then re-ticking leaves the button silent.

Properties

VisibleItems As Integer

Rows shown before scrolling. Zero = AppKit's own setting kept.

ItemHeight As Double

Row height. Zero = AppKit's own setting kept.

ButtonBordered As Boolean

Border of the arrow button.

Properties

NeutralValue As Double

macOS 26. The fill starts from this value rather than from the minimum — a centred equaliser, for instance.

Properties

TitleFontSize As Double

DesktopGroupBox applies Bold/FontSize to its CONTENT, never to its own title — which stayed at the system size regardless.

Properties

Template As Boolean

NSImage.isTemplate: automatic recolouring by the system, black on light and white on dark. The setting belongs to the IMAGE: reassigning Image afterwards builds a new NSImage and loses the flag.

Methods

Sub ReapplyNativeSettings()

Call after any change to Indeterminate. The toggle makes Xojo DESTROY the view and create another, and Opening is not raised on the new one: ControlSize and DisplayedWhenStopped are lost with no error.All fifteen placeable controls went through the same test, with Password on a text field as the positive control. Enabled, Visible and Width recreate the view on none of them; Indeterminate and Password are the only two cases found.

Sub StartAnimation()

Without a way to stop, DisplayedWhenStopped would never get a chance to matter.

Sub StopAnimation()

—

Properties

ControlSize As NativeButton.ControlSizes

A “small” bar is noticeably thinner than the regular one.

DisplayedWhenStopped As Boolean

When false, the indicator vanishes as soon as it stops animating.

Methods

Sub StartAnimation()

—

Sub StopAnimation()

—

Properties

ControlSize As NativeButton.ControlSizes

—

DisplayedWhenStopped As Boolean

When false, the wheel disappears at rest.

Properties

TabPosition As TabPositions

macOS 10.12. None, Top, Left, Bottom, Right. The one thing Xojo cannot do.

BorderType As BorderTypes

Respected only when TabPosition is None — the header is categorical, and measuring all fifteen combinations goes further: the property always stores the value it was given and reads back faithfully, but tabViewType, the one that drives the drawing, stays …Bezel as soon as the position is not None. The three borders only differ at position None, where tabViewType takes NoTabsNoBorder, NoTabsLine or NoTabsBezel.Reading the property back therefore does NOT reveal that the setting is inert. A UI exposing BorderType should grey it out away from that position.

ControlSize As NativeButton.ControlSizes

Subsumes Xojo's SmallTabs, which has only two states: Small does the same, with three more sizes.

AllowsTruncatedLabels As Boolean · DrawsBackground As Boolean

The second applies only to a borderless tab view — “only relevant for borderless tab view type”.

Methods

Sub SelectNext() · SelectPrevious() · SelectFirst() · SelectLast()

AppKit's four navigation actions, which Xojo does not expose: otherwise you compute the next index and handle the bounds yourself.

Function ContentRect() As Cocoa.NSRect · Function MinimumSize() As Cocoa.NSSize

The area actually available for a page, and the size below which the tabs no longer fit. AppKit coordinates, origin at the bottom.

Properties

ScrollerStyle As ScrollerStyles

Legacy always takes up its space; Overlay sits on top of the content and fades when idle. Setting it deliberately contradicts the person's global preference, which PreferredScrollerStyle lets you read first.

KnobStyle As KnobStyles

Dark and Light apply ONLY to an overlay bar: a legacy one takes the system colours. It is the setting that makes a bar readable over a dark background painted by hand. Measured by rendering the bar into a bitmap and comparing the bytes — reading the property back is always faithful and tells you nothing: with the legacy style all three values produce a pixel-identical image.On an overlay bar Dark is also identical to Default: the enum has three values for two renderings. A UI exposing KnobStyle should grey it out with the legacy style.

ControlSize As NativeButton.ControlSizes

Since NSScroller is an NSControl, it takes the system sizes: a mini bar is noticeably thinner.

KnobProportion As Double

The share of the track the knob occupies, from 0 to 1. Xojo writes this property too — that is how it sizes the knob from PageStep: a value set by hand holds only until the next refresh.

Shared methods

Shared Function WidthForControlSize(size As NativeButton.ControlSizes, style As ScrollerStyles) As Double

The width AppKit would give such a bar. Use it to size the anchor rather than hard-coding 16: the value changes with the style.

Shared Function PreferredScrollerStyle() As ScrollerStyles · OverlayScrollersSupported() As Boolean

The person's choice in System Settings, and the question the header asks: are overlay scrollers possible here? To adapt an interface, not to guard a call.

Properties

LineBreakMode As LineBreakModes

The most glaring gap. Xojo lets the text be cut at the end and nothing else; AppKit truncates at the head (…wxyz), the middle (ab…yz), the tail (abcd…), clips without an ellipsis, or wraps by word or by character. macOS 10.10, on NSControl, which forwards to its cell.

MaximumNumberOfLines As Integer

macOS 10.11. Zero means no limit, and is the default.A trap written into the header: past that count the text is CLIPPED, and only truncated with an ellipsis if TruncatesLastVisibleLine is set. Its value also changes what FittingSize returns.

TruncatesLastVisibleLine As Boolean

A CELL property, which NSTextField does not forward. Honoured only under WordWrapping or CharWrapping — the header is categorical. Set under any other mode it does nothing, and still reads back faithfully.Same mechanism as the tab border and the knob style: a UI exposing it should grey it out away from the two wrapping modes.

AllowsDefaultTighteningForTruncation As Boolean

macOS 10.11. Tightens inter-character spacing slightly before giving up and truncating — which spares you an … on a word that overflowed by two points.

AllowsExpansionToolTips As Boolean

macOS 10.8. The bubble that shows the full text on hover when it is cut, the one the Finder puts on an over-long file name. The system only builds it when the text is actually truncated.

Bordered As Boolean

A one-point frame around the label. Xojo only has Transparent, which acts on the background alone.

DrawsBackground As Boolean

Governs the background. BackgroundColor paints nothing without it.These notes first assumed an overlap with Xojo's Transparent. That is wrong, and measured: on a fresh label, Transparent is False while drawsBackground is False too — if either governed the other, a non-transparent label would paint its background. The two flags are independent.

BackgroundColor As Color

The background colour, Xojo → Cocoa conversion included: in Xojo, Alpha is 0 for opaque and 255 for transparent, the reverse of the Cocoa convention.

Methods

Sub SetViewOrigin(x As Double, y As Double)

Puts the frame origin back, in AppKit coordinates — so y counts from the BOTTOM of the parent view. Writing Width at runtime on a DesktopPagePanel child moves the view, and Xojo does not notice: it keeps reporting the original Left and Top.Measured: before, Xojo 230, 100 · 460 × 90 and AppKit 28, 589 · 464 × 90, agreeing to within the inset; after Width = 700, Xojo still says 230, 100 while AppKit moved to 3, 641. The remedy is three steps: read ViewFrame, write the size, put SetViewOrigin back.

Function ViewFrame() As Cocoa.NSRect

The view's REAL frame, to compare against the Left, Top, Width and Height Xojo believes it set. If the two diverge, something moved the view behind one of their backs, and no screenshot will say so for you.y counts from the bottom in AppKit and from the top in Xojo: a difference in y is not necessarily an anomaly, whereas one in x or in the width is.

Function FittingSize() As Cocoa.NSSize

The size it would take to show everything, WITHOUT touching the frame.sizeToFit is deliberately not exposed: it resizes the view behind Xojo's back, and Xojo keeps its own Width and Height and restores them at the next refresh. Measure, then write Me.Width.

Function SingleLineMode() As Boolean

Read-only diagnostic: the real value of usesSingleLineMode, the AppKit counterpart of what Xojo calls Multiline. Reading it says which of the two governs, instead of assuming a correspondence.

Function ReadsDrawsBackground() As Boolean

Same use for drawsBackground against Xojo's Transparent.

Methods

Function Table() As NativeTableView

The table itself, for everything this control does not forward.NativeTableView has some forty public methods; forwarding them all would be as much code to maintain twice, diverging at the first addition. Forwarded are the ones used on every table — columns, rows, cells, selection — and the rest goes through Table, with no detour and no loss.

Sub AddColumn(…)
Sub AddRow(ParamArray cells() As String)
Sub SetCell(…)
Function CellAt(…) As String
Sub RemoveAllRows()
Sub Reload()
Function RowCount() As Integer
Function ColumnCount() As Integer
Sub SelectRow(row As Integer)
SelectedRow As Integer

What is forwarded. AddRow goes through AddRowArray: a ParamArray does not carry from one method to another, and this control does not inherit the table — it hosts it.

Event SelectionChanged · CellChanged · RowDoubleClicked · SortChanged · RowsMoved

The table's events, re-raised by the control: whoever drops it implements them without knowing there is a table inside.

An outline is a table that indents

Everything separating it from its parent fits in MakeTable: it lodges a NativeOutlineView instead of a NativeTableView, and re-raises its three node events. The rest is inherited: the deferred hosting in Paint, the Inspector properties, the table's events. A node is a NativeOutlineNode, no longer a row number: inserting, removing and moving animate.

Methods

Function Tree() As NativeOutlineView

The same instance as Table, but typed: whatever is not forwarded goes through it — Tree.SetNodeIcon, Tree.NodeCell, Tree.ExpandNode.

Function AddNode(parent As NativeOutlineNode, ParamArray cells() As String) As NativeOutlineNode
Function InsertNode(parent, index, cells(), animation = SlideDown) As NativeOutlineNode
Function AddNodeAnimated(parent, cells(), animation = FadeSlideDown) As NativeOutlineNode
Sub RemoveNode(node, animation = SlideUp)
Function MoveNode(node, newParent, index) As Boolean
Function AddFolder(parent, item As FolderItem, depth As Integer = 3) As NativeOutlineNode
Function ParentOf(node) · ChildCount(parent) · ChildAt(parent, index) · IndexOf(node)
Function SelectedNode() · Sub SelectNode(node) · Sub ExpandAll() · Sub CollapseAll()

What is forwarded: building, removing, moving, walking, selecting. Nil as the parent means the root.

Event NodeSelectionChanged · NodeCellChanged · NodeDoubleClicked · NodesMoved

Re-raised from the outline, with the node.The table's events — SelectionChanged, CellChanged, RowDoubleClicked — coexist and give a storage row. Prefer these: a row changes as soon as something is inserted or moved.

Methods

Function Inner() As NativeSwitch

The hosted object, for whatever is not forwarded.Named Inner in all ten hosted controls: a name taken from the class would have given SearchField or SegmentedControl, class names from Xojo's old API that would mask the type at call sites.

Value As Boolean
ControlSize As NativeButton.ControlSizes

Set in the Inspector.Setting Value from code does not raise ValueChanged: AppKit sends its action only on the user's gesture.

Event ValueChanged(value As Boolean)

The hosted class's Changed, under Xojo's API 2 name.

Methods

Function Inner() As NativeStepper

The hosted object.

Value · MinimumValue · MaximumValue · Increment As Double
Autorepeat · ValueWraps As Boolean
ControlSize As NativeButton.ControlSizes

Set in the Inspector. ValueWraps makes the value start again from the minimum past the maximum.

Event ValueChanged(value As Double)

The hosted class's Changed.

Methods

Function Inner() As NativeSegmentedControl

The hosted object.

Labels As String

The labels in a single field, separated by semicolons: “Day;Week;Month”.Changeable after construction thanks to NativeSegmentedControl.SetLabels, added for this control.

SelectedIndex As Integer
Style As NativeSegmentedControl.Styles
TrackingMode As NativeSegmentedControl.TrackingModes
Distribution As NativeSegmentedControl.Distributions
BorderShape As NativeControlHost.BorderShapes
ControlSize As NativeButton.ControlSizes

Set in the Inspector.BorderShape acts only from macOS 26 on.

Function SegmentCount() As Integer
Function IsSelected(index As Integer) As Boolean
Sub SetSelected(index As Integer, selected As Boolean)
Sub SetSymbol(index As Integer, symbolName As String, accessibilityDescription As String = "")
Sub SetWidth(index As Integer, width As Double)

Forwarded. In SelectAny tracking, several segments can be selected at once.

Event SelectionChanged(index As Integer)

The hosted class's Changed.

Methods

Function Inner() As NativeLevelIndicator

The hosted object.

Style As NativeLevelIndicator.Styles
Value · MinimumValue · MaximumValue As Double
Editable As Boolean

Set in the Inspector. Editable, the indicator is set by clicking: that is what makes a Rating a rating.

WarningValue · CriticalValue As Double
InvertedThresholds As Boolean
TickMarks · MajorTickMarks As Integer

Two zero thresholds give AppKit's default look. InvertedThresholds puts the warning at the bottom: a battery rather than a disk.

Event ValueChanged(value As Double)

The hosted class's Changed.

Methods

Function Inner() As NativeSearchField

The hosted object.

Text · Placeholder As String
LiveSearch As Boolean
MaximumRecents As Integer

Set in the Inspector.MaximumRecents at zero removes the menu template — and the header says so, without a template recent searches are no longer tracked. The hosted class could set it, not remove it.

Function RecentSearches() As String()

Forwarded. SetPlaceholders is not: a ParamArray does not carry from one method to another; it stays reachable through Inner.

Event TextChanged(text As String)

The hosted class's Changed, under Xojo's API 2 name.

Methods

Function Inner() As NativeColorWell

The hosted object.

Value As Color
Style As NativeColorWell.Styles

Set in the Inspector.

MaximumLinearExposure As Double

macOS 26. AppKit's header: any value under 1 is ignored, and from 2 on the picked colour may carry a linear exposure.

Event ValueChanged(value As Color)

The hosted class's Changed.

Methods

Function Inner() As NativeDatePicker

The hosted object.

Style As NativeDatePicker.Styles
Mode As NativeDatePicker.Modes
DateElements As NativeDatePicker.DateElements
TimeElements As NativeDatePicker.TimeElements
Bezeled · Bordered As Boolean

Set in the Inspector.

Value As DateTime
Duration As Double
Sub SetRange(minimum As DateTime, maximum As DateTime)

From code only: a DateTime cannot be set in the Inspector, and the control starts from today's date.Duration is the range length in seconds, in DateRange mode.

Event ValueChanged(value As DateTime, duration As Double)

The hosted class's Changed.

Methods

Function Inner() As NativeTokenField

The hosted object.

TokenList · Placeholder · Completions As String
Style As NativeTokenField.Styles
TokenizingCharacter As String

Set in the Inspector.Read back, TokenList returns the committed tokens, joined by semicolons. An empty TokenizingCharacter keeps AppKit's comma.

Function Tokens() As String()
Sub SetTokens(values() As String)

The tokens as they are. The text being typed is not part of them yet: it becomes a token on the tokenizing character, on Return or when focus is lost.An array and not a ParamArray, which would not pass through to the hosted class. A token containing a semicolon can only go through here.

Event TokensChanged(tokens() As String)

The hosted class's Changed.

Methods

Function Inner() As NativePathControl

The hosted object.

Path · Placeholder · AllowedTypes As String
Style As NativePathControl.Styles
Editable As Boolean

Set in the Inspector.Two styles: NavigationBar, value 1, has been deprecated since macOS 10.7. AppKit makes the bar editable by default; this control starts from False. And for the header, an empty type list allows nothing — nil allows everything, and that is what an empty field sets.

Value As FolderItem

From code only: a FolderItem cannot be set in the Inspector.

Event PathSelected(item As FolderItem, path As String)
Event PathDoubleClicked(item As FolderItem, path As String)

The hosted class's two events.DoubleClicked is already a DesktopCanvas event, with coordinates: the bar's one therefore takes another name.

Methods

Function Inner() As NativeComboButton

The hosted object.

Caption · Items · SymbolName As String
Style As NativeComboButton.Styles
ControlSize As NativeButton.ControlSizes

Set in the Inspector.Items fits in one field, separated by semicolons; changing it rebuilds the whole menu through NativeComboButton.RemoveAllItems, added for this control. Caption and not Title: that is Xojo's API 2 name.

Function ItemCount() As Integer

The number of menu items.

Event Pressed()
Event MenuItemSelected(index As Integer, title As String)

Each menu item carries its own target; its tag is its rank, and that is what MenuItemSelected reports.

Constructor

Sub Constructor(width As Double = 260, height As Double = 160)

A popover REQUIRES an NSViewController. There is no need to subclass one: a bare NSViewController given a view with setView: is enough, which stops loadView being called.

Methods

Sub AddView(view As Ptr, x As Double, y As Double, width As Double, height As Double)

y counts from the TOP: the content view is flipped on purpose.

Sub Close()

—

Function ContentView() As Ptr

The view in which to house the content. Flipped: y from the top.

Function Handle() As Ptr

—

Sub SetContentSize(width As Double, height As Double)

Resizes the bubble AND its content view: both must follow, otherwise the content ends up clipped or floating.

Sub SetFullSizeContent(fullSize As Boolean)

macOS 14+: the content also occupies the arrow's area. Without effect below.

Sub Show(anchor As DesktopUIControl, edge As Edges = Edges.MinY)

Anchors the bubble to a Xojo control: its view serves as the positioning view, its bounds as the anchoring rectangle.

Properties

Animates As Boolean

—

Behavior As Behaviors

—

IsShown As Boolean read-only

—

Events

• Event DidClose()
• Event DidShow()
• Event WillClose()

Enumerations

Constructor

Sub Constructor(messageText As String, informativeText As String = "")

Methods

Function Handle() As Ptr

—

Function AddButton(title As String) As Integer

Returns the index of the button, 0 for the first one added. CAREFUL: it is the order of ADDITION, not the order on screen — the first one added is the default button, hence the RIGHTMOST one.With no call at all, NSAlert sets a single “OK” button.

Function RunModal() As Integer

Returns the 0-based index of the button, in order of addition; -1 if the alert could not be built.An alert MODAL to the application, and therefore blocking: the call returns only on the click. For the form attached to a window, see RunSheet.

Sub RunSheet(parent As DesktopWindow)

Presented as a SHEET, attached to the window — the correct form on macOS for a question that concerns a document.It is asynchronous: RunSheet returns immediately and the Completed event arrives later. Two consequences, and both are traps: 1. the block AND its delegate are kept in properties, never in locals; 2. the NativeAlert instance must survive until the callback — so a property of the window, never a Var in the click handler.

Sub SetAccessoryView(view As Ptr, width As Double = 0, height As Double = 0)

Any NSView at all — hence the Handle of any control. If a size is supplied, it is applied first: NSAlert sizes its panel from the view's frame, without renegotiating it.

Sub SetCancelButton(index As Integer)

Esc triggers this button. AppKit already does it on its own for a button titled “Annuler” or “Cancel”; to be specified as soon as the label leaves those two words.

Sub SetDefaultButton(index As Integer)

Moves the Return key. Indispensable with a destructive button: Apple's rules want the irreversible action NEVER to be the one triggered by reflex, yet AddButton makes the first one added the default button. So the keyboard equivalent is taken away from all the others.

Sub SetDestructiveButton(index As Integer, destructive As Boolean = True)

NSAlert itself has no notion of “destructive”: it is its BUTTONS that have one, since buttons is an array of NSButton. That is how the Finder gets its red “Delete”.hasDestructiveAction dates from macOS 11; below that, the call is without effect and the button stays grey.

Sub SetHelp(shown As Boolean, anchor As String = "")

—

Sub SetSuppression(shown As Boolean, title As String = "")

The “Do not ask me again” box. It is up to the application to remember the choice: AppKit only displays it and reports its state.

Sub SetSymbol(symbolName As String, accessibilityDescription As String = "")

Replaces the application icon with an SF symbol. Passing "" restores it.

Properties

InformativeText As String

—

MessageText As String

—

Style As Styles

—

Suppressed As Boolean read-only

Valid only after RunModal.

Events

• Event Completed(buttonIndex As Integer)
• Event HelpRequested() As Boolean

Delegate

• Delegate Sub SheetHandler(response As Integer)

Enumerations

Constructor

Sub Constructor(width As Double = 200, height As Double = 120, style As Styles = Styles.Regular)

Handle returns Nil below macOS 26; it is up to the caller to fall back on something else.

Methods

Function Available() As Boolean

—

Shared Function InteractiveSupported() As Boolean

To ADAPT the interface: Interactive is already inert below macOS 27, where the view exists without knowing this setting.

Function Handle() As Ptr

—

Sub SetContentView(view As Ptr)

—

Sub SetTint(useTint As Boolean, tint As Color = &c000000)

Passing False puts tintColor back to Nil: the glass returns to its neutral tint.

Properties

CornerRadius As Double

—

Interactive As Boolean

macOS 27, effectIsInteractive. The header: to be enabled for glass used as the background or container of controls — it then responds to hover and click. Default NO: glass carrying buttons stays static until asked.

Style As Styles

—

Enumerations

Constructor

Sub Constructor(width As Double = 200, height As Double = 120)

Handle returns Nil below macOS 26; the caller must fall back to something else.

Methods

Function Available() As Boolean

—

Function Handle() As Ptr

—

Sub SetContentView(view As Ptr)

The panes to merge go as DESCENDANTS of this view, not directly in the container.

Properties

Spacing As Double

The proximity at which panes begin merging. Zero by default: batching, with no visible merge and no distortion of merely neighbouring views.

Constructor

Sub Constructor(width As Double = 400, height As Double = 240)

The intended use is precise — placing a view that overflows the safe area, under the title bar, the sidebar or the inspector. The content itself stays INSIDE the safe area; it is its edges that the system stretches and blurs to fill the rest. So you get an image that seems to pass under the toolbar without really being clipped by it.

Handle returns Nil before macOS 26: it is up to the caller to fall back on something else, typically the content view set on its own.

Methods

Function Available() As Boolean

True only if the class REALLY exists in the system in use. The class is queried, not the version number: a selector that is present is a proof, a version number a guess.

Function Handle() As Ptr

—

Sub SetContentView(view As Ptr)

The view to extend. It becomes a subview of the extension and, by default, is placed in the safe area — see AutomaticPlacement.

Function ContentView() As Ptr

—

Properties

AutomaticPlacement As Boolean

At True — the default —, the system itself places the content view in the safe area. At False, it is up to the caller to set the frame or the constraints, and the extension effect fills what remains around it.

Constructor

Sub Constructor(title As String = "")

Methods

Function AddItem(title As String, symbolName As String = "", subtitle As String = "") As Integer

Returns the index of the item, which serves as the tag and comes back in the Chosen event.

Function AddSectionHeader(title As String) As Integer

macOS 14: a real section header, not selectable and drawn as such. Below that, we fall back on a disabled item — not identical, but readable, and with no test for the caller to write.

Sub AddSeparator()

—

Function AddSubmenu(title As String, submenu As NativeMenu, symbolName As String = "") As Integer

The submenu is RETAINED by the item; keeping the Xojo object alive remains the caller's business, otherwise its destructor will release the NSMenu under the item.

Function AddColorPalette(title As String, colors() As Color, titles() As String, checkSize As Double = 10) As Integer

macOS 14: the row of coloured swatches, like the Finder tags.Two constraints the header states and that cannot be worked around: a palette menu must be the SUBMENU of an item of an ordinary menu, and it can be neither pulled down by PopUp nor attached to a pop-up menu. Hence the signature: you give the title of the carrying item, not the menu itself. The factory's selection handler is optional: you pass Nil and read SelectedIndexes on the submenu — which spares you having to build an Objective-C block.

Function PaletteSelection(index As Integer) As Integer()

The indexes selected in the palette carried by the given item.

Function Handle() As Ptr

—

Function PopUp(anchor As DesktopUIControl, dx As Double = 0, dy As Double = 0) As Boolean

Pulls the menu down under a Xojo control and returns True if an item was chosen. The call is SYNCHRONOUS: it returns only when the menu closes, which allows the selection to be read just afterwards.AppKit coordinates, origin at the BOTTOM: (0,0) is the bottom-left corner of the anchor, so the menu opens just below it.

Sub RemoveAll()

—

Function SelectedIndexes() As Integer()

macOS 14, and only in SelectOne or SelectAny selection mode: the ticked items of one and the same selection group.

Sub SetBadge(index As Integer, count As Integer, kind As Badges = Badges.Plain)

macOS 14. The three named types carry a label localised by the system — “3 updates”, “2 new items” — where Plain shows only the number. Without effect below 14.

Sub SetBadgeText(index As Integer, text As String)

—

Sub SetEnabled(index As Integer, enabled As Boolean)

—

Sub SetIndent(index As Integer, level As Integer)

—

Sub SetImageVisibility(index As Integer, visibility As ImageVisibilities)

The same for ONE item.

Shared Function ImageVisibilitySupported() As Boolean

To ADAPT the interface: on an earlier system, images show anyway.

Sub SetState(index As Integer, state As Integer)

NSControlStateValue: Off = 0, On = 1, Mixed = -1.

Sub SetSymbol(index As Integer, symbolName As String)

—

Sub AttachTo(control As DesktopUIControl) · AttachTo(view As Ptr)

Makes this menu the CONTEXT menu. The overload on a view is needed as soon as a view is PLACED in the anchoring control: the right-click reaches the view on top, not the Xojo control's own.

Shared Sub ShowForSelection(control As DesktopUIControl) · ShowForSelection(view As Ptr)

macOS 15. Shows the view's context menu where the selection is — what the system key does, Ctrl-Return by default. Nothing has to be written for that key to work: the header is categorical, “Most applications should not override this method”. The system walks the responder chain up to NSApplication, which sends showContextMenuForSelection:, and NSView's default implementation shows the menu returned by menuForEvent: — hence the one AttachTo set. This method only triggers the same thing programmatically.Placement: NSView uses selectionAnchorRect. A view that does not implement it — which is the case for the views created here — sees the menu appear at the CENTRE of its bounds; AppKit's text views put it on the selection.

Shared Function ContextMenuKeySupported() As Boolean

Only useful to hide a button where it would do nothing: the key itself needs no test.

Sub AddWritingToolsItems()

macOS 15.2. “Each call returns an array of newly allocated instances”: fresh items, safe to place without sharing them — unlike the palette checkmark image.

Sub AutomaticallyInsertsWritingToolsItems(yes As Boolean)

macOS 15.2. Applies ONLY when the menu is used as a context menu — “if used as a context menu”. A menu pulled down by PopUp is not one.

Properties

Count As Integer read-only

—

PresentationStyle As Styles

macOS 14. In Palette, the menu presents itself as a compact row — but it can then NOT be pulled down by PopUp nor attached to a pop-up menu: it must be the submenu of an item of an ordinary menu.

SelectionMode As SelectionModes

macOS 14. Acts only on the items of one and the same selection GROUP — that is to say, with no separator or header between them.

ImageVisibility As ImageVisibilities

macOS 27. NSMenuItem's header: from macOS 27 on, AppKit decides the visibility of menu item images and “will typically hide images”. Visible by default in this class, not Automatic as in AppKit: a symbol passed to AddItem is an explicit request. Applies to existing and future items; Automatic hands the decision back to the system.The header warns that even Visible may be overridden “in some cases”. A palette menu's swatches are not affected: measured on macOS 27.0, their items have no image.

Events

• Event Chosen(index As Integer, title As String)

Enumerations

Constructor

Sub Constructor(width As Double = 260, height As Double = 200, material As Materials = Materials.WindowBackground, blending As Blendings = Blendings.BehindWindow)

The materials are SEMANTIC: you ask for “sidebar” or “window background”, not for a colour. The system decides the rendering according to the appearance, the reduced-transparency setting and the position in the window. The old Light and Dark have been deprecated since 10.14 and are not exposed here.

Methods

Sub AddView(view As Ptr, x As Double, y As Double, width As Double, height As Double)

AppKit coordinates, origin at the BOTTOM: an NSVisualEffectView is not flipped. To count from the top, set a view from NativeControlHost.MakeFlippedContainer first and add the content to it.

Function Handle() As Ptr

—

Sub SetContentView(view As Ptr)

A single view, filling the whole surface and following resizes.

Sub SetCornerRadius(radius As Double)

Goes through the layer, and it is safe here: a RADIUS is not a colour. CGColors set in a layer are frozen at the moment of writing and do not follow dark mode — a geometry does.

Properties

Blending As Blendings

BehindWindow lets the desktop and the windows behind show through; WithinWindow blends only with what is behind the view WITHIN the window. The first has an effect only if the window itself is translucent.

Emphasized As Boolean

10.12+. Used to signal that an associated view has the keyboard focus. CAREFUL, the header is explicit: “Some, but not all, materials change their look when emphasized.” On most materials — Sidebar, WindowBackground, Popover… — the effect is nil or imperceptible. It is on SELECTION that it shows: the material goes from the accent tint to grey, exactly like a selected row in a list that loses the focus.

Material As Materials

—

State As States

FollowsWindowActiveState is the system behaviour: the material goes out when the window moves to the background.

Enumerations

Constructor

Sub Constructor(width As Double = 420, height As Double = 170)

WHY NOT QLPreviewView, which would do the same thing in one line: it installs an NSRemoteView served by SceneKitQLPreviewExtension, and displaying a 3D model then destroys the process's drag and drop FOR GOOD — measured, nothing restores it but quitting the application. SCNView is an ordinary NSView: nothing leaves the process, apart from the parsing of the file.

WHY NOT RealityKit, which has replaced SceneKit since macOS 26: it exposes NO view class to Objective-C — neither ARView, nor RealityView, nor Entity. Verified at runtime: the framework's only ObjC classes are Swift internals with mangled names. RealityKit can only be driven from Swift, hence not from Xojo. SceneKit is deprecated but remains, to this day, the only workable route.

Methods

Function Available() As Boolean

—

Sub Clear()

—

Function Handle() As Ptr

—

Function Item() As FolderItem

—

Shared Function CanShow(item As FolderItem) As Boolean

“Handles” would have been the natural name — it is a RESERVED WORD in Xojo, the one for menu handlers. And case makes no difference.The formats SceneKit opens by itself or through ModelIO. A LIST, and that is owned: SceneKit offers no way to ask “can you read this?” without attempting the read, which would cost a full load.

Function Show(item As FolderItem) As Boolean

TWO routes, and the second catches what the first misses: sceneWithURL: knows SceneKit's native formats, ModelIO opens others — STL among them. We try the direct one, then the bridge.

Properties

CameraControl As Boolean

Lets the user turn, zoom and move the model with the mouse.

RendersContinuously As Boolean

Redraws continuously, at the screen's rate: needed for an ANIMATION contained in the file. Costly, hence optional.

Constructor

Sub Constructor(width As Double = 300, height As Double = 200, kind As Kinds = Kinds.Custom)

Its virtue comes down to one point: an NSBox paints with REAL NSColors. So it follows dark mode and increased contrast on its own, where a CGColor set in a CALayer is frozen the moment it is written and is never updated. That is why NativeRichTextEditor is built in NSBox.

Methods

Sub AddView(view As Ptr, x As Double, y As Double, width As Double, height As Double)

Adds to the content. If UseFlippedContent has been called, y counts from the TOP; otherwise it is the AppKit frame, origin at the bottom.

Function ContentView() As Ptr

The view in which to house the content: the one that was set, or the one NSBox manages.

Function Handle() As Ptr

—

Shared Function Separator(x As Double, y As Double, width As Double, height As Double) As NativeBox

A separator: horizontal or vertical according to its proportions, and it takes the system tint without anyone naming it. A one-point-thick view painted by hand would have neither the right colour nor the right behaviour in dark mode.

Sub SetColors(fill As Color, border As Color, borderWidth As Double = 1, cornerRadius As Double = 0)

Has an effect only with the Custom type: the other types draw themselves.

Sub SetContentView(view As Ptr)

—

Sub SetSystemColors(fillName As String = "controlBackgroundColor", borderName As String = "separatorColor", borderWidth As Double = 1, cornerRadius As Double = 6)

The right way: SEMANTIC colours, alive, that follow the appearance. A name unknown to the system is ignored rather than painting black.

Sub SetTitle(title As String, position As TitlePositions = TitlePositions.AtTop)

—

Sub SetTransparent(transparent As Boolean)

Neither background nor border, but the title and the layout remain: the way to group without drawing anything.

Sub UseFlippedContent(width As Double, height As Double)

Replaces the content view with a FLIPPED view: y then counts from the top, as in the Xojo designer and as everywhere else here.

Enumerations

Constructor

Sub Constructor(columnSpacing As Double = 12, rowSpacing As Double = 8)

Two facts verified in Objective-C before writing this: 1) built with initWithFrame:, the grid keeps translatesAutoresizingMaskIntoConstraints at YES — so it places by frame like all the rest of the library; 2) addRowWithViews: sets that same flag to NO on the views handed to it. The caller has nothing to do: the grid takes charge of its children.

Methods

Function AddRow(ParamArray views() As Ptr) As Integer

Returns the index of the row created. For an empty cell, pass EmptyCell — AppKit uses it as a marker, a Nil in the array would not do.

Function CellView(row As Integer, column As Integer) As Ptr

—

Shared Function EmptyCell() As Ptr

The empty-cell marker, to be passed to AddRow. It is a CLASS property of NSGridCell, not an instance to create.

Function FittingSize() As Cocoa.NSSize

The natural size computed by Auto Layout. CAREFUL: it is expressed in ALIGNMENT rectangles — the frame of an NSButton overflows its own by a few points. A grid of buttons therefore deserves a little margin.

Function Handle() As Ptr

—

Sub MergeCells(column As Integer, columnCount As Integer, row As Integer, rowCount As Integer)

Merges a rectangular block — a title running across the full width, for example. The cell kept is the one at the top left of the block.

Sub Refit(padding As Double = 0)

Fits the frame to the natural size. The extra compensates for the overflow of the alignment rectangles when the grid contains buttons.

Sub SetColumnHidden(column As Integer, hidden As Boolean)

A hidden column shrinks to zero AND hides its views: it is the clean way to make an option disappear without dismantling the grid.

Sub SetColumnWidth(column As Integer, width As Double)

Passing SizeForContent returns the column to automatic fitting.

Sub SetPlacement(horizontal As Placements, vertical As Placements)

The grid's DEFAULT placement. Rows, columns and cells can override it; “Inherited” on a cell refers back to the level above.

Sub SetRowAlignment(alignment As RowAlignments)

FirstBaseline aligns the baselines of a row: it is what makes a label and a field look as though they sit on the same line, where a vertical centring offsets them visibly.

Sub SetRowHeight(row As Integer, height As Double)

—

Sub SetRowHidden(row As Integer, hidden As Boolean)

—

Sub SetRowPadding(row As Integer, top As Double, bottom As Double)

The total space between two rows is the bottomPadding of the first, plus rowSpacing, plus the topPadding of the second.

Sub SetSpacing(columnSpacing As Double, rowSpacing As Double)

—

Shared Function SizeForContent() As Double

NSGridViewSizeForContent, the “fit yourself to the content” sentinel. It is an exported CGFloat equal to FLT_MIN: we READ it rather than copy a literal, AppKit's comparison being an exact equality.

Properties

ColumnCount As Integer read-only

—

RowCount As Integer read-only

—

Enumerations

Constructor

Sub Constructor(orientation As Orientations = Orientations.Horizontal, spacing As Double = 8)

CONSTRUCTION TRAP, verified in Objective-C: the class factory stackViewWithViews: returns a stack whose translatesAutoresizingMaskIntoConstraints is NO — impossible to place by frame, it would ignore its own. initWithFrame: leaves it at YES, and is therefore the only route compatible with the rest of the library.

Methods

Sub AddView(view As Ptr)

addArrangedSubview: — the stack takes charge of placing the view and sets its translatesAutoresizingMaskIntoConstraints to NO, as NSGridView does. Nothing to adjust on the caller's side.

Sub AddViews(ParamArray views() As Ptr)

—

Function FittingSize() As Cocoa.NSSize

The natural size, expressed in ALIGNMENT rectangles: the frame of an NSButton overflows its own by a few points. A stack of buttons therefore needs an extra — see Refit.

Function Handle() As Ptr

—

Sub InsertView(view As Ptr, index As Integer)

—

Sub Refit(padding As Double = 0)

—

Sub RemoveView(view As Ptr)

Removes the view from the layout AND from the hierarchy: removeArrangedSubview: alone would leave it a subview, hence drawn but no longer placed.

Sub SetCustomSpacing(afterView As Ptr, spacing As Double)

A particular spacing AFTER a given view — that is how groups are separated within one stack without slipping an empty view in.

Sub SetDetachesHiddenViews(detaches As Boolean)

When a hidden view is detached, the stack closes up as if it did not exist. Otherwise it keeps its place, empty.

Sub SetInsets(top As Double, leading As Double, bottom As Double, trailing As Double)

—

Sub SetVisibilityPriority(view As Ptr, priority As Double)

Below 1000, the stack is allowed to detach the view when room runs short — it is the mechanism of the bars that thin out as they shrink. MustHold = 1000, DetachOnlyIfNecessary = 900, NotVisible = 0.

Properties

Alignment As Alignments

Alignment on the CROSS axis: for a horizontal stack, CenterY, Top, Bottom or FirstBaseline; for a vertical one, CenterX, Leading or Trailing. An alignment taken on the wrong axis is simply ignored.

Distribution As Distributions

—

Orientation As Orientations

—

Spacing As Double

—

Enumerations

Constructor

Sub Constructor(title As String = "", symbolName As String = "")

Variable length: the item fits its content. NSSquareStatusItemLength (-2) would keep it square, at the height of the bar.

Methods

Sub AddMenuItem(title As String)

A menu item carries its own target and its own tag, as in NativeComboButton: it is the tag that says which one was chosen.

Sub AddSeparator()

—

Function Handle() As Ptr

—

Sub Remove()

Without this call, the extra stays in the menu bar until the end of the process, even if the Xojo object has gone.

Sub SetSymbol(symbolName As String, accessibilityDescription As String = "")

—

Properties

Title As String

—

Visible As Boolean

—

Events

• Event Clicked(index As Integer, title As String)

Constructor

Sub Constructor(mode As Modes = Modes.Save)

The two panels share a class here because they share almost everything: NSOpenPanel inherits from NSSavePanel.

Methods

Function Handle() As Ptr

—

Function RunModal() As Boolean

Returns True if the user validated. NSModalResponseOK is 1 — not to be confused with NSAlert's 1000, which counts from NSAlertFirstButtonReturn.

Sub SetAccessoryView(view As Ptr, width As Double = 0, height As Double = 0)

Any NSView at all — hence the Handle of any control in the library. The panel sizes itself on the frame supplied.

Sub SetAllowedExtensions(ParamArray extensions() As String)

allowedContentTypes wants UTTypes (macOS 11+), not strings. We build them from extensions; an extension unknown to the system returns Nil and is simply ignored.

Sub SetOpenOptions(chooseFiles As Boolean = True, chooseDirectories As Boolean = False, multipleSelection As Boolean = False)

Without effect on a save panel: these settings exist only on NSOpenPanel.

Sub SetTexts(title As String = "", message As String = "", prompt As String = "")

prompt is the label of the validation button. Passing "" leaves the system's default text, already localised — better not to translate it yourself.

Function Values() As FolderItem()

The plural is only meaningful when opening with multiple selection; elsewhere the array contains at most one element.

Sub ShowContentTypes(visible As Boolean)

macOS 15. The FORMAT menu under the name field, drawn and populated by AppKit from the allowed types — what had to be built by hand in an accessory view. Without effect when opening, or if no type was declared.

Function ChosenContentType() As String

The type chosen, as a uniform identifier. To be read AFTER validation.

Properties

Directory As FolderItem

—

FileName As String

The name proposed in the field. Not applicable to an open panel.

Value As FolderItem read-only

Valid only after an accepted RunModal.

Enumerations

Methods

Shared Function Classify(item As FolderItem) As Kinds

What the Finder sees, and Xojo does not say: an application, an installer package, a Photos library are FOLDERS to the file system — FolderItem.IsFolder returns True — but documents to the user. The distinction is called a “package”, and only macOS knows it.The order of the questions matters: an alias to an application is an alias first, and an application is a package before it is a folder.

Shared Function Describe(item As FolderItem) As String

The Finder's “kind”, translated by the system: “Application”, “Installer package”, “Photos Library”, “Folder”. It is not made up here — the translation is macOS's own.

Shared Function IsApplication(item As FolderItem) As Boolean

—

Shared Function IsPackage(item As FolderItem) As Boolean

True for everything the Finder presents as a document although it is a folder: application, installer package, Photos library, Xcode project, RTFD document…

Shared Function TypeIdentifier(item As FolderItem) As String

The uniform type identifier: “com.apple.application-bundle”, “com.apple.photos.library”, “public.folder”. It is what allows a given application's library to be recognised.

Enumerations

Constructor

Sub Constructor(width As Double = 320, height As Double = 320, style As Styles = Styles.Normal)

ONE PECULIARITY, and it is decisive: QLPreviewView does not belong to AppKit but to QuickLookUI, which Xojo never links. Without an explicit load, the class simply does not exist — verified: a binary that does not link Quartz does not find QLPreviewView. Hence the dlopen, on the FULL PATH: the short name “Quartz” fails.

Methods

Sub Close()

RELEASES the preview and its resources — it is the only gesture that does.The header is categorical: without close, “your application leaks”. And since shouldCloseWithWindow is True by default, close only happens by itself when the WINDOW closes: in a single-window application, that means “on quitting”. A live preview therefore holds its QuickLook service for the whole session. CAREFUL, and it is irreversible: once closed, the view ACCEPTS NO further item. To preview again, another one has to be built — hence Available(), which will return False afterwards.

Function Available() As Boolean

The view obtained is queried, not the version number: QuickLookUI has existed since 10.7, but its loading can fail for other reasons. A CLOSED view is no longer usable either, and says so here.

Sub Clear()

—

Function Handle() As Ptr

—

Function Item() As FolderItem

—

Function Preview(item As FolderItem) As Boolean

VERIFIED: NSURL ALREADY conforms to the QLPreviewItem protocol — its previewItemURL returns the URL itself. So there is no runtime class to build, contrary to what reading the header leads you to fear.

Sub Refresh()

To be called when the FILE has changed under the preview: setting the same item again would not be enough, QuickLook having no reason to read it afresh.

Properties

Autostarts As Boolean

Starts documents that play — audio, video — by themselves.

CloseWithWindow As Boolean

At True, the preview closes with the window that carries it, which saves having to think about it. At False, it is up to the Destructor to see to it.

Enumerations

Methods

Shared Sub Install(menu As DesktopMenuItem)

Designates this item's submenu as NSApplication.windowsMenu. You pass the menu-bar ITEM, not the menu: on the ObjC side, the submenu of an NSMenuItem is the NSMenu expected. The parameterless Handle is checked with Cocoa.Responds(item, "submenu") before use — the parameterised form the reference documents belongs to MenuItem, the old name, and no overload accepts it.

Shared Function Installed() As Boolean

Observe rather than assume: if the menu could not be designated, the list will never fill and nothing else would say so.

Shared Sub Exclude(w As DesktopWindow, hidden As Boolean)

A utility window — palette, detached inspector — has no business in the list. It is a property of the WINDOW, not of the menu.

Shared Sub BringToFront(w As DesktopWindow)

makeKeyAndOrderFront: and not Show: on a window that is already visible, Show does not bring it forward and does not give it the keyboard focus.

Shared Sub BringAllToFront()

The “Bring All to Front” action of the Window menu.

Shared Function Front() As DesktopWindow

The KEY window according to AppKit, which is not App.Window(0): Xojo's list follows the order of creation, not the stacking order.

Shared Sub PerformClose()

performClose: and not a forced close: the system selector consults the window's delegate — windowShouldClose: may refuse —, animates the closing and beeps when the window has no close box.

Shared Sub ToggleFullScreen()

Native full screen, the one behind the green button, and not Xojo's FullScreen, which merely enlarges the window. Without effect if the window does not carry its full-screen button.

Methods

Shared Sub SetBadge(text As String)

The red badge — Mail's “3”. An empty string removes it. AppKit truncates an over-long label itself: no need to count characters.

Shared Function Badge() As String

What the badge carries, an empty string when there is none.

Shared Sub SetContentView(view As Ptr)

The icon becomes a VIEW, and you draw what you like in it. Nil restores the application icon.

Shared Sub Display()

To be called after EVERY change to the content view: the Dock does not redraw of its own accord.

Shared Function Size() As Cocoa.NSSize

The usable size of the view, in points. It FOLLOWS the Dock size setting: hard-coding it would give a wrong gauge as soon as the user changes it.

Shared Sub ShowsApplicationBadge(visible As Boolean)

Distinct from the text badge: this setting decides whether the application icon is inset into the custom view. With no custom view, it has nothing to do.

Methods

Shared Sub Perform(pattern As Patterns = Patterns.Alignment, when As Timing = Timing.Default)

Careful with the timing: Timing.Default means DrawCompleted, so the tap waits for the next drawing pass. To feel it on the click, pass Timing.Now.

Shared Function Available() As Boolean

To be used only to ADAPT the interface, never to guard the call: Perform is already without effect in that case.

Enumerations

Methods

Shared Sub SetColumnResize(directions As Horizontal = Horizontal.All) · SetRowResize

The cursors of the Finder in column view and of a table.

Shared Sub SetFrameResize(position As FramePositions, directions As FrameDirections = FrameDirections.All)

The cursor of a frame HANDLE: you give it the corner or edge grabbed, and the ways still possible.

Shared Sub SetZoom(zoomIn As Boolean)

The “plus” and “minus” magnifiers.

Shared Sub Restore()

Pops ONE cursor. The setters go through push and not set: a cursor set with set is overwritten at the next hover over a control. AppKit's stack has no “restore everything”, so one Restore per push.

Shared Function Available() As Boolean

To ADAPT the interface only: the methods above are already without effect on an earlier system.

Enumerations

Methods

Shared Function AccessBehavior() As Behaviors

macOS 15.4. What the system does when the application reads the pasteboard PROGRAMMATICALLY: ask, always allow, always deny. The user sets it per application in System Settings. Two nuances the header states: as long as an application has NEVER triggered the alert, it reports Default — it is the first access that flips the state to Ask, so reading Default does not mean “no alert will come”; and this setting does NOT touch what follows from a user gesture — a drag and drop, a Cmd-V never ask anything.

Shared Function ChangeCount() As Integer

The change counter, incremented on every write by anyone. It is the useful counterpart of the previous one: reading it does not count as access to the content, so it triggers no alert. An application that wants to enable a “Paste” button queries this counter instead of reading the pasteboard.

Sub Constructor() · Function Detect(ParamArray patterns() As Patterns) As Boolean

macOS 15.4. Asks whether the FIRST pasteboard item matches one of the patterns. The whole point is in one sentence of the header — “without notifying the person using the app”: you learn what is there without reading, hence without triggering the alert. The callback returns only the patterns RECOGNISED, never the values: getting those would mean reading, and that the system reports. Returns False if the call could not be made — the event will then never arrive, and that also covers a detection already in flight: one at a time.

Shared Function DetectionAvailable() As Boolean

To ADAPT the interface: Detect already returns False otherwise.

Shared Function Available() As Boolean

To ADAPT the interface only: AccessBehavior already returns Default on an earlier system.

Events

• Event Detected(patterns() As Patterns, failed As Boolean)

The completion block arrives on a service queue, NOT on the interface thread. It therefore only retains the NSSet and raises a flag, then calls Cocoa.PerformOnMainThread: Detected is raised from the main thread, where strings can safely be built. That retain is what forces uniqueness — two detections in flight would fight over the same pointer from two threads.

Enumerations

Methods

Shared Sub Play(imageView As Ptr, kind As Effects)

The image must be a real SF symbol: on an ordinary image the effect has nothing to animate.

Shared Sub RemoveAll(imageView As Ptr)

Indefinite effects — pulse, variable colour, rotate — run until this call; one-shot ones stop by themselves.

Shared Function Available(kind As Effects) As Boolean

Each effect is a distinct class, introduced in a different version. Ask the class, never the system number.

Enumerations

Factories

Shared Function MainApp() As NativeLoginItem

The app itself. The common case, and the only one needing nothing more than a normal .app bundle.

Shared Function LoginItem(bundleIdentifier As String) As NativeLoginItem

A helper app shipped under Contents/Library/LoginItems.

Shared Function Agent(plistName As String) As NativeLoginItem

A LaunchAgent under Contents/Library/LaunchAgents: inside the session, with the logged-in person's rights.

Shared Function Daemon(plistName As String) As NativeLoginItem

A LaunchDaemon under Contents/Library/LaunchDaemons: as root, outside the session. Registering one asks for an administrator authentication.

Methods

Function Register(ByRef errorMessage As String) As Boolean

True means the request succeeded, not necessarily that the service is active: the status that follows may be RequiresApproval.

Function Unregister(ByRef errorMessage As String) As Boolean

No effect and no error if the service was not registered.

Function Status() As Statuses

The state as the system sees it. Re-read it after every action: the person may have changed everything in System Settings meanwhile.

Shared Sub OpenSystemSettings()

Opens System Settings › General › Login Items & Extensions. The only move available when the status is RequiresApproval.

Shared Function Available() As Boolean

macOS 13. Before that, there is nothing to fall back on.

Function Handle() As Ptr

—

Enumerations

Methods

Shared Function Reveal(files() As FolderItem) As Boolean

macOS 10.6, activateFileViewerSelectingURLs:. Several files at once: the Finder selects them all and opens one window per folder involved — which no parent-folder workaround reproduces.The return says « the request reached the Finder », not « the Finder succeeded »: the selector returns nothing, the header declares it void. What Reveal does check is that at least one file EXISTS — without which the call goes nowhere and nothing visible happens.

Shared Function Reveal(file As FolderItem) As Boolean

The single-file case, which is the common one.

Methods

Function RequestAuthorization(alerts As Boolean = True, sounds As Boolean = True, badges As Boolean = False, provisional As Boolean = False) As Boolean

The system dialog only appears ONCE in the app's lifetime; afterwards the call returns the recorded answer without showing anything. provisional asks for quiet authorisation: no dialog at all, and notifications land silently in the centre.

Sub RequestSettings()

Reads the authorisation state without asking anyone. Answered by SettingsRead.

Function Send(identifier As String, title As String, body As String, subtitle As String = "", delaySeconds As Double = 0, withSound As Boolean = True, categoryIdentifier As String = "") As Boolean

A zero delaySeconds means "right now": no trigger is attached. The same identifier REPLACES the previous notification — that is how you update a progress without stacking ten banners.

Sub RequestPendingNotifications() · Sub RequestDeliveredNotifications()

What is scheduled, and what is still visible in the centre. Answered by PendingRead and DeliveredRead.

Sub RemovePendingRequests(ParamArray identifiers() As String) · Sub RemoveAllPendingNotifications()

—

Sub RemoveDeliveredNotifications(ParamArray identifiers() As String) · Sub RemoveAllDeliveredNotifications()

—

Sub SetBadgeCount(value As Integer)

macOS 13. A badge set by the notification centre, so subject to the "badges" authorisation. For a badge that does not depend on it, see NativeDockTile.

Sub AddResponseCategory(category As NativeNotificationCategory)

Declares a set of buttons — and optionally a text field — to the system. Before sending the notification that uses it: declaring afterwards fixes nothing. A category with the same identifier is replaced, not duplicated.

Sub RemoveAllResponseCategories()

setNotificationCategories: replaces the whole set on each call instead of adding to it; the list is therefore kept here, and that is what gets cleared.

Shared Sub SetForegroundPresentation(banner As Boolean = True, inList As Boolean = True, sound As Boolean = True, badge As Boolean = False)

What the system shows when a notification arrives while the app is active. All False amounts to showing nothing — macOS's behaviour without a delegate, exactly what this class fixes. A shared setting: the centre is a singleton.

Shared Sub OpenNotificationSettings()

Opens System Settings › Notifications, at the app's pane. The move to offer when the status is Authorized but AlertStyle is None: no API changes that setting on behalf of the person who chose it.

Shared Function Available() As Boolean

—

Read-only properties

AlertStyle As AlertStyles

Valid after SettingsRead. This setting, not the authorisation status, decides whether a banner appears. An app can be authorised with an alert style of None: the system accepts notifications, files them in the centre, and never shows anything.

ShowsAlerts As DeviceSettings · ShowsInNotificationCenter As DeviceSettings · PlaysSounds As DeviceSettings · ShowsBadges As DeviceSettings

—

Events

Event UserResponded(identifier As String, kind As Actions, actionIdentifier As String, textResponse As String)

The notification was opened or dismissed. actionIdentifier carries the raw value; kind classifies it, by reading the exported constants rather than copying their values.

Event AuthorizationAnswered(granted As Boolean, errorMessage As String)

—

Event SettingsRead(status As AuthorizationStatuses)

—

Event NotificationSent(identifier As String, errorMessage As String)

—

Event PendingRead(identifiers() As String) · Event DeliveredRead(identifiers() As String)

—

Enumerations

Properties

Identifier As String

What UserResponded will report. This, not the caption, is what tells actions apart.

Caption As String

The button text, as shown.

BringToForeground As Boolean

Brings the app to the front. Without it the action is handled without the window moving — the whole point of an interactive notification.

Destructive As Boolean

Red button. Cosmetic, but it is the convention.

AuthenticationRequired As Boolean

Requires Touch ID, the watch or the password before acting.

SystemImageName As String

An SF symbol on the button (UNNotificationActionIcon, macOS 12). Ignored on earlier systems, and absent from Xojo's iOS class: an addition here.

Methods

Shared Function Available() As Boolean

Loads UserNotifications.framework along the way: a category may be built before any NativeUserNotification instance exists.

Function Build() As Ptr

Builds the UNNotificationAction. Called by NativeNotificationCategory, overridden by NativeNotificationTextField.

Constructor

Sub Constructor(caption As String, identifier As String)

Yes/No buttons are two instances, each with its own identifier — that is what UserResponded reports.

Constructor and properties

Sub Constructor(caption As String, hint As String, sendCaption As String, identifier As String)

—

ButtonCaption As String · Hint As String

The send button's label, and the empty field's placeholder.

Constructor, properties, method

Sub Constructor(identifier As String)

That identifier is what you pass to Send as categoryIdentifier.

Actions() As NativeNotificationAction

The buttons and fields, in display order.

CustomDismiss As Boolean

Raises UserResponded even when the notification is merely DISMISSED. Without it, a dismissal goes unnoticed.

HiddenPreviewsBody As String · HiddenPreviewShowsTitle As Boolean · HiddenPreviewShowsSubtitle As Boolean

What stays visible when previews are hidden — lock screen, "Show previews" set to "Never".

Function Build() As Ptr

—