Xojo Conferences
XDCMay2019MiamiUSA

Platforms to show: All Mac Windows Linux Cross-Platform

Next items

NSApplicationMBS.activateIgnoringOtherApps(flag as boolean)
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Cocoa MBS MacCocoa Plugin 11.2 Yes No No Yes, macOS only No
Function: Makes the receiver the active application.
Notes:
flag: If false, the application is activated only if no other application is currently active. If true, the application activates regardless.

The flag parameter is normally set to false. When the Finder launches an application, using a value of false for flag allows the application to become active if the user waits for it to launch, but the application remains unobtrusive if the user activates another application. Regardless of the setting of flag, there may be a time lag before the application activates—you should not assume the application will be active immediately after sending this message.

You rarely need to invoke this method. Under most circumstances, the Application Kit takes care of proper activation. However, you might find this method useful if you implement your own methods for inter-application communication.

You don't need to send this message to make one of the application's NSWindows key. When you send a makeKeyWindow message to an NSWindow object, you ensure that it is the key window when the application is active.

Feedback, Comments & Corrections

NSApplicationMBS.addWindowsItem(win as NSWindowMBS, title as string, isFilename as boolean)
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Cocoa MBS MacCocoa Plugin 11.1 Yes No No Yes, macOS only No
Function: Adds an item to the Window menu for a given window.
Notes:
win: The window being added to the menu. If this window object already exists in the Window menu, this method has no effect.
Title: The string to display for the window's menu item. How the string is interpreted is dependent on the value in the isFilename parameter.
isFilename: If false, title appears literally in the menu; otherwise, title is assumed to be a converted pathname with the name of the file preceding the path (the way the NSWindow method setTitleWithRepresentedFilename shows a title)

You rarely need to invoke this method directly because Cocoa places an item in the Window menu automatically whenever you set the title of an NSWindow object.

Feedback, Comments & Corrections

NSApplicationMBS.arrangeInFront
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Cocoa MBS MacCocoa Plugin 11.1 Yes No No Yes, macOS only No
Function: Arranges windows listed in the Window menu in front of all other windows.
Example:
dim a as new NSApplicationMBS
a.arrangeInFront
Notes: Windows associated with the application but not listed in the Window menu are not ordered to the front.

Feedback, Comments & Corrections

NSApplicationMBS.cancelUserAttentionRequest(request as Integer)
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Cocoa MBS MacCocoa Plugin 11.2 Yes No No Yes, macOS only No
Function: Cancels a previous user attention request.
Notes:
request: The request identifier returned by the requestUserAttention method.

A request is also canceled automatically by user activation of the application.

Feedback, Comments & Corrections

NSApplicationMBS.changeWindowsItem(win as NSWindowMBS, title as string, isFilename as boolean)
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Cocoa MBS MacCocoa Plugin 11.1 Yes No No Yes, macOS only No
Function: Changes the item for a given window in the Window menu to a given string.
Notes:
win: The window whose title you want to change in the Window menu. If win is not in the Window menu, this method adds it.
title: The string to display for the window's menu item. How the string is interpreted is dependent on the value in the isFilename parameter.
isFilename: If false, title appears literally in the menu; otherwise, title is assumed to be a converted pathname with the name of the file preceding the path (the way the NSWindow method setTitleWithRepresentedFilename shows a title)

Feedback, Comments & Corrections

NSApplicationMBS.completeStateRestoration
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Cocoa MBS MacCocoa Plugin 13.2 Yes No No Yes, macOS only No
Function: Completes the extended state restoration.
Notes:
This method informs the application that the extended state restoration is completed for the balancing .

If a window has some state that may take a long time to restore, such as a web page, you may use this method and methods to completeStateRestoration to extend the period of this crash protection beyond the default.

You call extendStateRestoration within your implementation of restoreWindowWithIdentifier. You would then call completeStateRestoration some time after the window is fully restored. If the app crashes in the interim, then it may offer to discard restorable state on the next launch.

The extendStateRestoration and completeStateRestoration method act as a counter. Each call to extendStateRestorationincrements the counter, and must be matched with a corresponding call to completeStateRestoration which decrements it. When the counter reaches zero, the app is considered to have been fully restored, and any further calls are silently ignored.

This method is thread safe.
Available in OS X v10.7 and later.

Feedback, Comments & Corrections

NSApplicationMBS.Constructor
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Cocoa MBS MacCocoa Plugin 11.1 Yes No No Yes, macOS only No
Function: The constructor.
Example:
dim n as new NSApplicationMBS

n.dockTile.badgeLabel = "Hello"
n.dockTile.showsApplicationBadge = true
Notes: Creates an object which points to the shared NSApplication instance.

Feedback, Comments & Corrections

NSApplicationMBS.deactivate
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Cocoa MBS MacCocoa Plugin 11.2 Yes No No Yes, macOS only No
Function: Deactivates the receiver.
Example:
dim a as new NSApplicationMBS

a.deactivate
Notes: Normally, you shouldn't invoke this method—the Application Kit is responsible for proper deactivation.

Feedback, Comments & Corrections

NSApplicationMBS.disableRelaunchOnLogin
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Cocoa MBS MacCocoa Plugin 11.2 Yes No No Yes, macOS only No
Function: Disable relaunching this app on login, if the app was running at the time the user logged out.
Notes:
These methods increment and decrement a counter respectively; if the counter is 0 at the time the user logs out, then the app may be relaunched when the user logs back in. The counter is initially zero, so by default apps are relaunched.

If your app should not be relaunched because it launches via some other mechanism (e.g. launchd), then the recommended usage is to call disableRelaunchOnLogin once, and never pair it with an enable call.

If your app should not be relaunched because it triggers a restart (e.g. an installer), then the recommended usage is to call disableRelaunchOnLogin immediately before you attempt to trigger a restart, and enableRelaunchOnLogin immediately after. This is because the user may cancel restarting; if the user later restarts for another reason, then your app should be brought back.

These methods are thread safe.
Available on Mac OS X 10.7 or newer.

Feedback, Comments & Corrections

NSApplicationMBS.discardEventsMatchingMask(mask as Integer, beforeEvent as NSEventMBS)
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Cocoa MBS MacCocoa Plugin 17.5 Yes No No Yes, macOS only No
Function: Removes all events matching the given mask and generated before the specified event.
Notes:
mask: Contains one or more flags indicating the types of events to discard. The constants section of the NSEvent class defines the constants you can add together to create this mask. The discussion section also lists some of the constants that are typically used.
lastEvent: A marker event that you use to indicate which events should be discarded. Events that occurred before this event are discarded but those that occurred after it are not.

Use this method to ignore any events that occurred before a specific event. For example, suppose your app has a tracking loop that you exit when the user releases the mouse button. You could use this method, specifying NSAnyEventMask as the mask argument and the ending mouse-up event as the lastEvent argument, to discard all events that occurred while you were tracking mouse movements in your loop. Passing the mouse-up event as lastEvent ensures that any events that might have occurred after the mouse-up event (that is, that appear in the queue after the mouse-up event) are not discarded.

Typically, you send this message to an NSWindow object, rather than to the app object. Discarding events for a window clears out all of the events for that window only, leaving events for other windows in place.

For the mask parameter, you can add together event type constants such as the following:
  • NSLeftMouseDownMask
  • NSLeftMouseUpMask
  • NSRightMouseDownMask
  • NSRightMouseUpMask
  • NSMouseMovedMask
  • NSLeftMouseDraggedMask
  • NSRightMouseDraggedMask
  • NSMouseEnteredMask
  • NSMouseExitedMask
  • NSKeyDownMask
  • NSKeyUpMask
  • NSFlagsChangedMask
  • NSPeriodicMask
  • NSCursorUpdateMask
  • NSAnyEventMask
This method can also be called in subthreads. Events posted in subthreads bubble up in the main thread event queue.

Feedback, Comments & Corrections

NSApplicationMBS.enableRelaunchOnLogin
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Cocoa MBS MacCocoa Plugin 11.2 Yes No No Yes, macOS only No
Function: Enable relaunching this app on login, if the app was running at the time the user logged out.
Notes:
These methods increment and decrement a counter respectively; if the counter is 0 at the time the user logs out, then the app may be relaunched when the user logs back in. The counter is initially zero, so by default apps are relaunched.

If your app should not be relaunched because it launches via some other mechanism (e.g. launchd), then the recommended usage is to call disableRelaunchOnLogin once, and never pair it with an enable call.

If your app should not be relaunched because it triggers a restart (e.g. an installer), then the recommended usage is to call disableRelaunchOnLogin immediately before you attempt to trigger a restart, and enableRelaunchOnLogin immediately after. This is because the user may cancel restarting; if the user later restarts for another reason, then your app should be brought back.

These methods are thread safe.
Available on Mac OS X 10.7 or newer.

Feedback, Comments & Corrections

NSApplicationMBS.extendStateRestoration
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Cocoa MBS MacCocoa Plugin 13.2 Yes No No Yes, macOS only No
Function: Allows an application to extend its state restoration period.
Notes:
This method allows an application to extend the state restoration period beyond the usual. For example, the app crashes before state restoration is complete, then it may offer to discard restorable state on the next launch.

If a window has some state that may take a long time to restore, such as a web page, you may use this method and methods to completeStateRestoration to extend the period of this crash protection beyond the default.

You call extendStateRestoration within your implementation of restoreWindowWithIdentifier. You would then call completeStateRestoration some time after the window is fully restored. If the app crashes in the interim, then it may offer to discard restorable state on the next launch.

The extendStateRestoration and completeStateRestoration method act as a counter. Each call to extendStateRestoration increments the counter, and must be matched with a corresponding call to completeStateRestoration which decrements it. When the counter reaches zero, the app is considered to have been fully restored, and any further calls are silently ignored.

This method is thread safe.
Available in OS X v10.7 and later.

Feedback, Comments & Corrections

NSApplicationMBS.hide
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Cocoa MBS MacCocoa Plugin 11.1 Yes No No Yes, macOS only No
Function: Hides all the receiver's windows, and the next application in line is activated.
Example:
NSApplicationMBS.sharedApplication.hide
Notes: This method is usually invoked when the user chooses Hide in the application's main menu. When this method begins, it posts an NSApplicationWillHideNotification to the default notification center. When it completes successfully, it posts an NSApplicationDidHideNotification.

Feedback, Comments & Corrections

NSApplicationMBS.hideOtherApplications
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Cocoa MBS MacCocoa Plugin 11.1 Yes No No Yes, macOS only No
Function: Hides all applications, except the receiver.
Example:
NSApplicationMBS.sharedApplication.hideOtherApplications

Feedback, Comments & Corrections

NSApplicationMBS.invalidateRestorableState
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Cocoa MBS MacCocoa Plugin 11.2 Yes No No Yes, macOS only No
Function: Invalidates the restorable state.
Notes: applicationWillEncodeRestorableState event will be called soon in your NSApplicationDelegateMBS subclass to get a new state encoded.

Feedback, Comments & Corrections

NSApplicationMBS.miniaturizeAll
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Cocoa MBS MacCocoa Plugin 11.1 Yes No No Yes, macOS only No
Function: Miniaturizes all the receiver's windows.
Example:
NSApplicationMBS.sharedApplication.miniaturizeAll

Feedback, Comments & Corrections

NSApplicationMBS.modalWindow as NSWindowMBS
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Cocoa MBS MacCocoa Plugin 11.2 Yes No No Yes, macOS only No
Function: Returns the modal window that the receiver is displaying.
Example:
// show title of current dialog
MsgBox NSApplicationMBS.sharedApplication.modalWindow.Title
Notes:
Returns the modal window being displayed or nil if no modal window is being displayed.

This method returns the current standalone modal window. It does not return sheets that are attached to other windows. If you need to retrieve a sheet window, use the attachedSheet method of NSWindow.

Feedback, Comments & Corrections

NSApplicationMBS.nextEventMatchingMask(mask as Integer, untilDate as date, mode as String, dequeueFlag as boolean) as NSEventMBS
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Cocoa MBS MacCocoa Plugin 17.5 Yes No No Yes, macOS only No
Function: Returns the next event matching a given mask, or nil if no such event is found before a specified expiration date.
Example:
Function MouseDown(X As Integer, Y As Integer) Handles MouseDown as Boolean
// in mousedown event

dim a as NSApplicationMBS = NSApplicationMBS.sharedApplication

// check current event
dim e as NSEventMBS = a.currentEvent

// check next mouse up event
dim d as new date
d.Second = d.Second + 2 // maximum 2 seconds wait time
dim n as NSEventMBS = a.nextEventMatchingMask(NSEventMBS.NSLeftMouseUpMask, d, NSRunLoopMBS.NSDefaultRunLoopMode, false)


// e-> mouseDown
// e-> mouseUp, if already available

Break
End Function
Notes:
mask: Contains one or more flags indicating the types of events to return. The constants section of the NSEvent class defines the constants you can add together to create this mask. The discardEventsMatchingMask method also lists several of these constants.
expiration: The expiration date for the current event request. Specifying nil for this parameter is equivalent to returning a date object using the distantPast method.
mode: The run loop mode in which to run while looking for events. The mode you specify also determines which timers and run-loop observers may fire while the app waits for the event.
flag: Specify true if you want the event removed from the queue.

Returns the event object whose type matches one of the event types specified by the mask parameter.

You can use this method to short circuit normal event dispatching and get your own events. For example, you may want to do this in response to a mouse-down event in order to track the mouse while its button is down. (In such an example, you would pass the appropriate event types for mouse-dragged and mouse-up events to the mask parameter and specify the NSEventTrackingRunLoopMode run loop mode.) Events that do not match one of the specified event types are left in the queue.
You can specify one of the run loop modes defined by AppKit or a custom run loop mode used specifically by your app. AppKit defines the following run-loop modes:
  • NSDefaultRunLoopMode
  • NSEventTrackingRunLoopMode
  • NSModalPanelRunLoopMode
  • NSConnectionReplyMode

Feedback, Comments & Corrections

NSApplicationMBS.orderFrontCharacterPalette
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Cocoa MBS MacCocoa Plugin 11.2 Yes No No Yes, macOS only No
Function: Opens the character palette.
Example:
dim a as new NSApplicationMBS
a.orderFrontCharacterPalette
Notes:
Available in Mac OS X v10.3 and later.
This shows the special characters palette.

Feedback, Comments & Corrections

NSApplicationMBS.orderFrontStandardAboutPanel
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Cocoa MBS MacCocoa Plugin 11.2 Yes No No Yes, macOS only No
Function: Displays a standard About window.
Example:
dim a as new NSApplicationMBS

a.orderFrontStandardAboutPanel
Notes: This method calls orderFrontStandardAboutPanelWithOptions with a nil argument. See orderFrontStandardAboutPanelWithOptions for a description of what's displayed.

Feedback, Comments & Corrections

NSApplicationMBS.orderFrontStandardAboutPanelWithOptions(options as dictionary)
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Cocoa MBS MacCocoa Plugin 11.2 Yes No No Yes, macOS only No
Function: Displays a standard About window with information from a given options dictionary.
Example:
dim a as new NSApplicationMBS

// this image has no mask, so you'll see a white border
dim p as Picture = LogoMBS(500)
dim n as new NSImageMBS(p)
dim options as new Dictionary

// show window with default values
'a.orderFrontStandardAboutPanel

// we overwrite default values with new values
options.Value("Credits") = NSAttributedStringMBS.attributedStringWithString("Written by Christian Schmitz")
options.Value("ApplicationName") = "MyCoolApp"
options.Value("Version") = "1.2.3"
options.Value("Copyright") = "© 2011 Monkeybread Software"
options.Value("ApplicationIcon") = n

a.orderFrontStandardAboutPanelWithOptions(options)

Exception ex as NSExceptionMBS
MsgBox ex.message
Notes:
options: A dictionary whose keys define the contents of the About window. See the discussion for a description of the available keys.

The following strings are keys that can occur in optionsDictionary:

" "An NSAttributedStringMBS displayed in the info area of the panel. If not specified, this method then looks for a file named "Credits.html", "Credits.rtf", and "Credits.rtfd", in that order, in the bundle returned by the NSBundle class method mainBundle. The first file found is used. If none is found, the info area is left blank.
"ApplicationName"A string displayed as the application's name. If not specified, this method then uses the value of CFBundleName (localizable). If neither is found, this method uses the process name.
"ApplicationIcon"A NSImageMBS object displayed as the application's icon. If not specified, this method then looks for an image named "NSApplicationIcon", using NSImageMBS.imageNamed("NSApplicationIcon"). If neither is available, this method uses the generic application icon.
"Version"A string with the build version number of the application ("58.4"), displayed as "(v58.4)". If not specified, obtain from the CFBundleVersion key in infoDictionary; if not specified, leave blank (the "(v)" is not displayed).
"Copyright"A string with a line of copyright information. If not specified, this method then looks for the value of NSHumanReadableCopyright in the localized version infoDictionary. If neither is available, this method leaves the space blank.
"ApplicationVersion"A string with the application version ("Mac OS X", "3", "WebObjects 4.5", "AppleWorks 6",...). If not specified, obtain from the CFBundleShortVersionString key in infoDictionary. If neither is available, the build version, if available, is printed alone, as "Version x.x".

Feedback, Comments & Corrections

NSApplicationMBS.OverlayApplicationIconImage(image as NSImageMBS)
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Cocoa MBS MacCocoa Plugin 11.2 Yes No No Yes, macOS only No
Function: Overlays the image.
Example:
// draw a picture with a red dot on the top left

dim p as new Picture(512,512,32)

dim g as Graphics = p.Graphics
g.ForeColor = &cFF0000
g.FillRect 0,0,128,128

g = p.mask.Graphics

g.ForeColor = &cFFFFFF
g.Fillrect 0,0,512,512
g.ForeColor = &c000000
g.Filloval 0,0,128,128

Backdrop = p

// create nsimage
dim n as new NSImageMBS(p,p.mask)

// and overlay over original image
NSApplicationMBS.sharedApplication.OverlayApplicationIconImage n
Notes:
Same as setting applicationIconImage, but instead overlays the original image with the new image. This way you can show custom badges. For normal text badges, use NSDockTileMBS class.

Pass image = nil to reset application dock icon.

Size of the image seems to be 128 Pixel by default, but could go up to 1024 in the future. Plugin scales up or down as needed for you.

Feedback, Comments & Corrections

NSApplicationMBS.postEvent(e as NSEventMBS, atStart as boolean)
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Cocoa MBS MacCocoa Plugin 17.5 Yes No No Yes, macOS only No
Function: Adds a given event to the receiver’s event queue.
Notes:
anEvent: The event object to post to the queue.
flag: Specify true to add the event to the front of the queue; otherwise, specify false to add the event to the back of the queue.

This method can also be called in subthreads. Events posted in subthreads bubble up in the main thread event queue.

Feedback, Comments & Corrections

NSApplicationMBS.preventWindowOrdering
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Cocoa MBS MacCocoa Plugin 13.2 Yes No No Yes, macOS only No
Function: Suppresses the usual window ordering in handling the most recent mouse-down event.
Notes: This method is only useful for mouse-down events when you want to prevent the window that receives the event from being ordered to the front.

Feedback, Comments & Corrections

NSApplicationMBS.removeWindowsItem(win as NSWindowMBS)
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Cocoa MBS MacCocoa Plugin 11.1 Yes No No Yes, macOS only No
Function: Removes the Window menu item for a given window.
Notes:
Win: The window whose menu item is to be removed.

This method doesn't prevent the item from being automatically added again. Use the excludedFromWindowsMenu method of NSWindow if you want the item to remain excluded from the Window menu.

Feedback, Comments & Corrections

NSApplicationMBS.replyToApplicationShouldTerminate(reply as boolean)
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Cocoa MBS MacCocoa Plugin 11.2 Yes No No Yes, macOS only No
Function: Responds to NSTerminateLater once the application knows whether it can terminate.
Notes:
souldTerminate: Specify true if you want the application to terminate; otherwise, specify false.

If your application delegate returns NSTerminateLater from its applicationShouldTerminate event, your code must subsequently call this method to let the NSApplication object know whether it can actually terminate itself.

Feedback, Comments & Corrections

NSApplicationMBS.replyToOpenOrPrint(reply as Integer)
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Cocoa MBS MacCocoa Plugin 11.2 Yes No No Yes, macOS only No
Function: Handles errors that might occur when the user attempts to open or print files.
Notes:
reply: The error that occurred. For a list of possible values, see "Constants."

Delegates should invoke this method if an error is encountered in the applicationOpenFiles or applicationPrintFiles delegate methods.

Feedback, Comments & Corrections

NSApplicationMBS.requestUserAttention(type as Integer) as Integer
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Cocoa MBS MacCocoa Plugin 11.2 Yes No No Yes, macOS only No
Function: Starts a user attention request.
Example:
dim a as NSApplicationMBS = NSApplicationMBS.sharedApplication

if not a.isActive then // only when we are in background
call a.requestUserAttention(a.NSInformationalRequest) // dock bounces
end if
Notes:
requestType: The severity of the request. Can be NSInformationalRequest or NSCriticalRequest.

Returns the identifier for the request. You can use this value to cancel the request later using the cancelUserAttentionRequest method.

Activating the application cancels the user attention request. A spoken notification will occur if spoken notifications are enabled. Sending requestUserAttention to an application that is already active has no effect.

If the inactive application presents a modal panel, this method will be invoked with NSCriticalRequest automatically. The modal panel is not brought to the front for an inactive application.

Feedback, Comments & Corrections

NSApplicationMBS.runModalForWindow(win as NSWindowMBS) as Integer
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Cocoa MBS MacCocoa Plugin 18.2 Yes No No Yes, macOS only No
Function: Starts a modal event loop for the specified window.
Notes:
win: The window to be displayed modally. If it is not already visible, the window is centered on the screen using the value in its center method and made visible and key. If it is already visible, it is simply made key.

Returns an integer indicating the reason that this method returned.

This method runs a modal event loop for the specified window synchronously. It displays the specified window, makes it key, starts the run loop, and processes events for that window. (You do not need to show the window yourself.) While the app is in that loop, it does not respond to any other events (including mouse, keyboard, or window-close events) unless they are associated with the window. It also does not perform any tasks (such as firing timers) that are not associated with the modal run loop. In other words, this method consumes only enough CPU time to process events and dispatch them to the action methods associated with the modal window.

You can exit the modal loop by calling the stopModal, stopModalWithCode, or abortModal methods from your modal window code. If you use the stopModalWithCode method to stop the modal event loop, this method returns the argument passed to stopModalWithCode. If you use stopModal instead, this method returns the constant NSModalResponseStop (-1000). If you use abortModal, this method returns the constant NSModalResponseAbort (-1001).

Feedback, Comments & Corrections

Next items

The items on this page are in the following plugins: MBS MacCocoa Plugin.




Links
MBS Xojo Plugins