Legacy Document
Important: The information in this document is obsolete and should not be used for new development.
NSPanel
| Inherits from | |
| Implements | |
| Package | com.apple.cocoa.application |
| Companion guide |
Overview
A panel is a special kind of window, typically serving an auxiliary function in an application.
Tasks
Constructors
Configuring Panel Behavior
-
setFloatingPanel
-
isFloatingPanel
-
setBecomesKeyOnlyIfNeeded
-
becomesKeyOnlyIfNeeded -
setWorksWhenModal
-
worksWhenModal
Constructors
NSPanel
Creates an empty NSPanel.
public NSPanel()
Creates a new NSPanel.
public NSPanel(NSRect contentRect, int styleMask, int backingType, boolean defer)
Discussion
The contentRect argument specifies the location and size of the panel’s content area in screen coordinates. Note that the window server limits window position coordinates to ±16,000 and sizes to 10,000.
The styleMask argument specifies the panel’s style. Either it can be NSWindow.BorderlessWindowMask, or it can contain any of the options described in NSWindow’s “Constants,” combined using the C bitwise OR operator.
Borderless windows display none of the usual peripheral elements and are generally useful only for display or caching purposes; you should normally not need to create them. Also, note that an NSWindow’s style mask should include NSWindow.TitledWindowMask if it includes any of the others.
The backingType argument specifies how the drawing done in the panel is buffered by the object’s window device, and possible values are described in NSWindow’s “Constants.”
The defer argument determines whether the window server creates a window device for the new panel immediately. If defer is true, it defers creating the window until the panel is moved onscreen. All display messages sent are postponed until the panel is created, just before it’s moved on screen. Deferring the creation of the window improves launch time and minimizes the virtual memory load on the window server.
The new panel creates an instance of NSView to be its default content view. You can replace it with your own object by using the setContentView method.
Creates a new NSPanel.
public NSPanel(NSRect contentRect, int styleMask, int bufferingType, boolean defer, NSScreen aScreen)
Discussion
This constructor is equivalent to the preceding one, except contentRect is specified relative to the lower-left corner of aScreen.
If aScreen is null, contentRect is interpreted relative to the lower-left corner of the main screen. The main screen is the one that contains the current key window or, if there is no key window, the one that contains the main menu. If there’s neither a key window nor a main menu (if there’s no active application), the main screen is the one where the origin of the screen coordinate system is located.
Instance Methods
becomesKeyOnlyIfNeeded
public boolean becomesKeyOnlyIfNeeded()
Discussion
Returns true if the receiver becomes the key window only when the user clicks a view object that needs to be first responder to receive event and action messages—for example, if it edits text or otherwise accepts keyboard input. Returns false if it becomes the key window whenever clicked. NSPanel by default returns false, indicating that panels become key as other windows do.
See Also
isFloatingPanel
Returns true if the receiver is set to float above normal windows, false otherwise.
public boolean isFloatingPanel()
Discussion
A floating panel’s window level is NSWindow.FloatingWindowLevel. NSPanel by default returns false, indicating that the receiver inhabits the normal window level.
See Also
-
setFloatingPanel -
level(NSWindow)
setBecomesKeyOnlyIfNeeded
Controls whether the receiver becomes the key window only when the user clicks a view object that edits text or otherwise accepts keyboard input.
public void setBecomesKeyOnlyIfNeeded(boolean flag)
Discussion
If flag is true, the receiver becomes the key window only when keyboard input is needed; if flag is false, it becomes the key window whenever clicked. This behavior is not set by default. You should consider setting it only if most controls in the NSPanel aren’t text fields, and if the choices that can be made by entering text can also be made in another way (such as by clicking an item in a list).
If the receiver is a non-activating panel, then it becomes key only if the hit view returns true from needsPanelToBecomeKey. In this way, a non-activating panel can control whether it takes keyboard focus.
See Also
setFloatingPanel
Controls whether the receiver floats above normal windows.
public void setFloatingPanel(boolean flag)
Discussion
If flag is true, sets the receiver’s window level to NSWindow.FloatingWindowLevel; if flag is false, sets the receiver’s window level to NSWindow.NormalWindowLevel. The default is false. It’s appropriate for an NSPanel to float above other windows only if all of the following conditions are true:
It’s small enough not to obscure whatever’s behind it.
It’s oriented more to the mouse than to the keyboard—that is, if it doesn’t become the key window or becomes so only when needed.
It needs to remain visible while the user works in the application’s normal windows—for example, if the user must frequently move the cursor back and forth between a normal window and the panel (such as a tool palette), or if the panel gives information relevant to the user’s actions in a normal window.
It hides when the application is deactivated (the default behavior for panels).
See Also
-
isFloatingPanel -
setLevel(NSWindow)
setWorksWhenModal
Controls whether the receiver receives keyboard and mouse events even when some other window is being run modally.
public void setWorksWhenModal(boolean flag)
Discussion
If flag is true, the application object sends events to the receiver even during a modal loop or session; if flag is false, the receiver gets no events while a modal loop or session is running. See “How Modal Windows Work” for more information on modal windows and panels.
See Also
-
worksWhenModal -
runModalForWindow(NSApplication) -
runModalSession(NSApplication)
worksWhenModal
Returns true if the receiver is able to receive keyboard and mouse events even when some other window is being run modally, false otherwise.
public boolean worksWhenModal()
Discussion
NSPanels by default return false, indicating their ineligibility for events during a modal loop or session. See “How Modal Windows Work” for more information on modal windows and panels.
See Also
-
setWorksWhenModal -
runModalForWindow(NSApplication) -
runModalSession(NSApplication)
Constants
These constants define the possible return values for such methods as the runModal... methods of NSOpenPanel, which tell which button (OK or Cancel) the user has clicked on an open panel:
NSPanel defines the following constants for panel styles:
© 1997, 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-02-01)