Copyright: Copyright ©1996 NeXT Software, Inc.
Citation: Copyright ©1996 NeXT Software, Inc.


4.1 Conversion Notes


Adding Keyboard UI to Your Controls


AppKit Changes Prior to 4.0

There are tops scripts to assist PR1 to PR2 and PR2 to 4.0 migration.  Many of the API changes that  have happened between prereleases can be automatically applied to your code with these commands:

tops -semiverbose -scriptfile /NextDeveloper/OpenStepConversion/ConversionScripts/PR1toPR2.tops *.[mchCM] *.psw *.pswm

tops -semiverbose -scriptfile /NextDeveloper/OpenStepConversion/ConversionScripts/PR2to40.tops *.[mchCM] *.psw *.pswm

Formatting and Validation

NSFormatter and NSDateFormatter have moved into the Foundation Kit. FoundationKit now also includes a number formatter. Imports of <AppKit/NSFormatter.h> or <AppKit/NSDateFormatter.h> will need to be changed to import the corresponding file from Foundation; imports of <AppKit/AppKit.h> don't need to be changed. The tops script mentioned above takes care of this.  Also, a new NSNumberFormatter has been added.

The control delegate message control:validateObject: has been changed to control:isValidObject:.

NSApplication

NSApplication defines a new delegate method similar to -application:openFile: called

-(void)application:(NSApplication *)app printFile:(NSString *)path

Upon launching, an application scans its command line arguments for -NSOpen and, now, -NSPrint arguments.  These arguments are followed by the path to a file to open or print respectively.  NSApplication sends the above messages to its delegate if it responds in this way for the files specified on the command line.  These messages are also invoked in response to Speaker/Listener interaction, but this aspect is perhaps less interesting to developers.

This new message (and the new command-line argument -NSPrint) is supported on both Mach and Windows.

Under Windows NT, when you install OPENSTEP, Explorer associations are automatically created for each file extension that the OPENSTEP applications claim.  The file-type's icon is associated with its extension and Open and Print commands are registered as well.  These commands work through the new command-line options, and can be accessed through Explorer's right-mouse context menu.  So, for example, right clicking an RTF file in Explorer will give you a menu that includes both Open and Print as well as some other stuff.  Choosing Open or Print will cause TextEdit to open or print the file.  Open is registered as the default command for these file extensions, so double-clicking an RTF file will open it in TextEdit.

A new notification, NSApplicationWillTerminateNotification, has been added to OpenStep.  It is sent before the Application's terminate method after applicationShouldTerminate is queried.

A Windows-specific method has been added to allow access to the Windows application handle.  This will only be of interest to developers calling the Win32 API directly.  (Arguments that varioius types of Windows handles are declared as void currently to avoid polluting the namespace with the vast amount of un-prefixed names in the Windows system headers.)

- (void * /*HINSTANCE*/)applicationHandle;

A Windows-specific method has been added to allow developers to look up an NSWindow object given a Windows HWND handle.  This will only be of interest to developers calling the Win32 API directly.

- (NSWindow *)windowWithWindowHandle:(void * /*HWND*/)hWnd;

A Windows-specific method has been added for developers who choose to implement their own WinMain() function  If you do so, call the method below before doing any other AppKit calls.  The arguments are those passed to WinMain() from the system.

+ (void)setApplicationHandle:(void * /*HINSTANCE*/)hInstance

previousHandle:(void * /*HINSTANCE*/)PrevInstance

commandLine:(NSString *)cmdLine

show:(int)cmdShow;

NSTableView

The table view has a new mode where it resizes all the columns, not just the last one, to fill the scroll view.  In this mode, if the table view fits exactly into its scroll view, and is then grown, it will grow all of its resizable columns to keep itself the size of the scroll view.  Here are the new methods to enable this:

- (void)setAutoresizesAllColumnsToFit:(BOOL)flag;

- (BOOL)autoresizesAllColumnsToFit;

While tracking a cell or performing the table view's action, one may discover what cell was clicked on to cause the action to perform with these additional methods:

- (int)clickedColumn;

- (int)clickedRow;

NSAttributedString

Parts of NSAttributedString and NSMutableAttributedString have moved into the Foundation Kit.  Just using Foundation, without the Application Kit, you can create and manipulate attributed strings; however you do not have access to the standard attribute types such as color, font, and paragraph style. The rest of the attributed string functionality is provided by categories in Application Kit.

The following names have changed in NSAttributedString:

NSAttributedStringEditedAttributes -> NSTextStorageEditedAttributes

NSAttributedStringEditedCharacters -> NSTextStorageEditedCharacters

The following methods to read RTF:

+ (NSAttributedString *)attributedStringFromRTF:(NSData *)rtfData;

+ (NSAttributedString *)attributedStringFromRTFD:(NSData *)rtfData;

+ (NSAttributedString *)attributedStringFromRTFDFile:(NSString *)rtfdPath;

have been replaced by:

- (id)initWithRTF:(NSData *)data documentAttributes:(NSDictionary **)dict;

- (id)initWithRTFD:(NSData *)data documentAttributes:(NSDictionary **)dict;

- (id)initWithPath:(NSString *)path documentAttributes:(NSDictionary **)dict;

- (id)initWithRTFDFileWrapper:(NSFileWrapper *)wrapper documentAttributes:(NSDictionary **)dict;

The optional dict argument is for returning document-wide attributes, which currently include "PaperSize", "LeftMargin", "RightMargin", "TopMargin", and "BottomMargin". Pass NULL for dict if you don't care about these.

The following methods to write RTF:

- (NSData *)RTFFromRange:(NSRange)range;

- (NSData *)RTFDFromRange:(NSRange)range;

- (BOOL)writeRTFDToFile:(NSString *)path atomically:(BOOL)flag;

have been replaced by:

- (NSData *)RTFFromRange:(NSRange)range documentAttributes:(NSDictionary *)dict;

- (NSData *)RTFDFromRange:(NSRange)range documentAttributes:(NSDictionary *)dict;

- (NSFileWrapper *)RTFDFileWrapperFromRange:(NSRange)range documentAttributes:(NSDictionary *)dict;

Pass nil for dict if you don't want to specify any of the document attributes.

To write RTFD to file you will need to send writeToFile:atomically:updateFilenames: to the NSFileWrapper you get back from RTFDFileWrapperFromRange:documentAttributes:. The updateFilenames: flag should usually be YES (unless you are doing a "Save To").

The following method names are changed in NSMutableAttributedString:

Before:

- (void)fixAttributesAfterEditingRange:(NSRange)range;

- (void)fixFontAttributeAfterEditingRange:(NSRange)range;

- (void)fixParagraphStyleAfterEditingRange:(NSRange)range;

- (void)fixAttachmentAfterEditingRange:(NSRange)range;

After:

- (void)fixAttributesInRange:(NSRange)range;

- (void)fixFontAttributeInRange:(NSRange)range;

- (void)fixParagraphStyleAttributeInRange:(NSRange)range;

- (void)fixAttachmentAttributeInRange:(NSRange)range;

The value of NSAttachmentCharacter has been changed from 0xF6FF to 0xFFFC to match the one proposed in the Unicode standard. Code which uses this value will need to be recompiled; places where this value is archived explicitly might need to check for the old value. (RTF files did archive this value, so no need for changes there.) If the old value ever appears in an attributed string at runtime, the new value will be used, and a warning will be generated (single warning per app session).

The method updateAttachmentsFromPath: has been added to NSMutableAttributedString to allow updating the file name information in all the attachments in the attributed string.

NSImage

NSImage now understands the bmp, ico, and cur image formats. ico and cur files with multiple images will be loaded as images with multiple representations. Typically these representations will have different sizes (unlike multiple-representation tiffs, which have different depths); by default, NSImage will choose the largest image when compositing.

Windows-specific methods have been added to NSImage and NSBitmapImageRep which allow creation of these objects from a Windows icon handle or bitmap handle.  These will only be of interest to developers calling the Win32 API directly.

- (id)initWithIconHandle:(void * /* HICON */)icon;

- (id)initWithBitmapHandle:(void * /* HBITMAP */)bitmap;

setFlipped: and flipped have been brought back into the API.

Compositing Operation Name Changes

Some of the constants declared by DPSClient for various compositing operations have had their names corrected:

Old Name	New Name

NSCompositeDataOver	NSCompositeDestinationOver

NSCompositeDataInreplace	NSCompositeDestinationIn

NSCompositeDataOut	NSCompositeDestinationOut

NSCompositeDataAtop	NSCompositeDestinationAtop

NSCursor

In order to make NSCursor immutable, the following methods:

- (id)initWithImage:(NSImage *)newImage;

- (void)setImage:(NSImage *)newImage;

- (void)setHotSpot:(NSPoint)spot;

have been replaced by:

- (id)initWithImage:(NSImage *)newImage hotSpot:(NSPoint)aPoint;

- (id)initWithImage:(NSImage *)newImage

      foregroundColorHint:(NSColor *)fg

      backgroundColorHint:(NSColor *)bg

      hotSpot:(NSPoint)hotSpot;

The color hints in the latter method are ignored in OPENSTEP for Windows and for Mach.

The initWithImage: and setImage: methods are somewhat generic and hard to detect, so the tops script might fail to catch all your uses.

Another change in NSCursor since PR2 is the support for custom cursor selections on Windows. OPENSTEP applications will use the correct arrow and I-beam cursors where applicable. If you ask for the image of one of these standard cursors on OPENSTEP for Windows, you will get back the correct image used by the system. You should note that the size of this image may be different than the traditional 16x16 used on Mach. For animated cursors you will simply get back the first frame.

NSText

The following method names are changed in the NSText API:

Before:

- (NSString *)text;

- (void)setText:(NSString *)string;

- (void)setText:(NSString *)string range:(NSRange)range;

- (void)replaceRange:(NSRange)range withRTF:(NSData *)rtfData;

- (void)replaceRange:(NSRange)range withRTFD:(NSData *)rtfdData;

- (void)setColor:(NSColor *)color ofRange:(NSRange)range;

- (void)setFont:(NSFont *)font ofRange:(NSRange)range;

After:

- (NSString *)string;

- (void)setString:(NSString *)string;

- (void)replaceCharactersInRange:(NSRange)range withString:(NSString *)aString;

- (void)replaceCharactersInRange:(NSRange)range withRTF:(NSData *)rtfData;

- (void)replaceCharactersInRange:(NSRange)range withRTFD:(NSData *)rtfdData;

- (void)setTextColor:(NSColor *)color range:(NSRange)range;

- (void)setFont:(NSFont *)font range:(NSRange)range;

NSTextView

The following methods are added to NSTextView:

- (void)pasteAsPlainText:(id)sender;

- (void)pasteAsRichText:(id)sender;

- (NSPoint)textContainerOrigin;

- (void)invalidateTextContainerOrigin;

- (NSRange)rangeForUserTextChange;

- (NSRange)rangeForUserCharacterAttributeChange;

- (NSRange)rangeForUserParagraphAttributeChange;

- (BOOL)smartInsertDeleteEnabled;

- (void)setSmartInsertDeleteEnabled:(BOOL)flag;

- (NSRange)smartDeleteRangeForProposedRange:(NSRange)proposedCharRange;

- (void)smartInsertForString:(NSString *)pasteString replacingRange:(NSRange)charRangeToReplace

        beforeString:(NSString **)beforeString afterString:(NSString **)afterString;

The following method names are changed in the NSTextView API to allow richer specification of selected text attributes:

Before:

- (void)setSelectionColor:(NSColor *)color;

- (NSColor *)selectionColor;

After:

- (void)setSelectedTextAttributes:(NSDictionary *)attributeDictionary;

- (NSDictionary *)selectedTextAttributes;

Underlining is now supported in the new text system; NSSingleUnderlineStyle has been added as a possible value for the NSUnderlineStyleAttributeName attribute.

The delegate method textView:clickedOnCell:inRect: has been added to indicate single-clicks on text attachments.

The method attachmentForDraggedFilename: has been removed from the API.

NSTextStorage

NSTextStorage now sends out notification messages after edits:

NSTextStorageWillProcessEditingNotification

NSTextStorageDidProcessEditingNotification

It also has a delegate who gets the following messages:

- (void)textStorageWillProcessEditing:(NSNotification *)notification;

- (void)textStorageDidProcessEditing:(NSNotification *)notification;

These methods are called during post-edit processing (basically after endEditing has been called, or, if endEditing was not in effect, after each edit that causes edited:range:changeInLength:). The first notification is sent before attributes are fixed, the second is sent after the attributes are fixed, but before the layout managers are notified. During the execution of textStorageWillProcessEditing: the delegate can change the attributed string all it wants; during textStorageDidProcessEditing: it should refrain from changing the character contents. The changes done by the delegate will not cause further notifications to be sent. However, during the execution of these methods and notifications the delegate and the observers can obtain information about what's changed via the following methods:

- (unsigned)editedMask;

- (NSRange)editedRange;

- (int)changeInLength;

NSTextStorage now also has a clear funnel point for all post-edit processing:

- (void)processEditing;

This method sends the above notification methods, calls fixAttributesInRange:, and informs the layout managers of the changes.

The following methods, now much less useful, have been removed from the API:

- (void)verifyEdited:(unsigned)mask range:(NSRange)range changeInLength:(int)delta;

- (void)notifyEdited:(unsigned)mask range:(NSRange)range changeInLength:(int)delta

    invalidatedRange:(NSRange)invRange;

Subclassers, note: NSTextStorage is now a semi-abstract class. It implements change management (beginEditing/endEditing), verification of attributes, and layout management notification. The one aspect it does not implement is the actual attributed string storage--this is left up to the subclassers, which need to override the two NSMutableAttributedString primitives replaceCharactersInRange:withString: and setAttributes:range:. These primitives should perform the change then call edited:range:changeInLength: to get everything else to happen.

Here is a sample NSTextStorage subclasser:

@implementation SimpleTextStorage

/* Provide your own init methods, whatever you wish... Here we provide one (initWithAttributedString:) and override the DI from super (init). */

- (id)initWithAttributedString:(NSAttributedString *)attrStr {

    if (self = [super init]) {

        contents = attrStr ? [attrStr mutableCopyWithZone:[self zone]] :

              [[NSMutableAttributedString allocWithZone:[self zone]] init];

    }

    return self;

}

- init {

    return [self initWithAttributedString:nil];

}

- (void)dealloc {

    [contents release];

    [super dealloc];

}

/* The next set of methods are the primitives for attributed and mutable attributed string... */

- (NSString *)string {

    return [contents string];

}

- (NSDictionary *)attributesAtIndex:(unsigned)location effectiveRange:(NSRange *)range {

    return [contents attributesAtIndex:location effectiveRange:range];

}

/* In the mutable primitives (and any non-primitives which are overridden and which don't go through the primitives), we need to call edited:range:changeInLength: to allow the text storage change management to do its job. */

- (void)replaceCharactersInRange:(NSRange)range withString:(NSString *)str {

    [contents replaceCharactersInRange:range withString:str];

    [self edited:NSAttributedStringEditedCharacters

range:range changeInLength:(int)[str length] - (int)range.length];

}

- (void)setAttributes:(NSDictionary *)attrs range:(NSRange)range {

    [contents setAttributes:attrs range:range];

    [self edited:NSAttributedStringEditedAttributes range:range changeInLength:0];

}

@end

NSFileWrapper

A new public class has been added to the AppKit.  NSFileWrapper provides support for the concept of a document wrapper (like a .rtfd, .nib, or many other NEXTSTEP file types).  The new text system uses this class to handle RTFD documents, but it is designed to be generally useful.  It handles reading and writing file packages in the file system as well as serializing them for use with the Pasteboard.  See the General Reference for details.

NSTextAttachment

The following changes in NSTextAttachment take advantage of NSFileWrapper:

Before:

- (id)initWithContentsOfFile:(NSString *)path;

- (BOOL)writeToFile:(NSString *)path atomically:(BOOL)flag;

After:

- (id)initWithFileWrapper:(NSFileWrapper *)fileWrapper;  /* Designated initializer */

- (void)setFileWrapper:(NSFileWrapper *)fileWrapper;

- (NSFileWrapper *)fileWrapper;

The name and setName: methods have also been removed from the API.

NSParagraphStyle

Subclassers, note: NSParagraphStyle and NSMutableParagraphStyle used to be abstract; they are now concrete.

setParagraphStyle: has been added to NSMutableParagraphStyle to allow setting all the values with one call.

NSRulerView/NSRulerMarker

The delegate method rulerView:willSetClientView: has been added to NSRulerView to give the existing client a chance to clean up.

The following method names are changed in NSRulerMarker:

Before:

- (void)setLocation:(float)location;

- (float)location;

- (id)initWithRulerView:(NSRulerView *)ruler location:(float)location image:(NSImage *)image imageOrigin:(NSPoint)imageOrigin;

After:

- (void)setMarkerLocation:(float)location;

- (float)markerLocation;

- (id)initWithRulerView:(NSRulerView *)ruler location:(float)location image:(NSImage *)image imageOrigin:(NSPoint)imageOrigin;

NSWorkspace

The following NSWorkspace methods will raise under OPENSTEP for Windows to indicate that they are not implemented (and the return value, being wrong, shouldn't be relied upon):

- (BOOL)fileSystemChanged;

- (BOOL)userDefaultsChanged;

- (NSArray *)mountedRemovableMedia;

- (NSArray *)mountNewRemovableMedia;

The following methods are no-ops:

- (void)checkForRemovableMedia;

- (void)findApplications;

- (void)hideOtherApplications;

- (void)noteUserDefaultsChanged;

- (void)noteFileSystemChanged;

- (BOOL)getFileSystemInfoForPath:isRemovable:isWritable:isUnmountable:description:type:;

- (int)extendPowerOffBy;

- (void)slideImage:(NSImage *)image from:(NSPoint)fromPoint to:(NSPoint)toPoint;

In addition, note that the NSWorkspaceRecycleOperation will currently remove the files in OPENSTEP for Windows.

NSBrowser

The width of columns are now dealt with as floats rather than ints to be consistent with the rest of the AppKit:

Before:

- (void)setMinColumnWidth:(int)columnWidth;

- (int)minColumnWidth;

After:

- (void)setMinColumnWidth:(float)columnWidth;

- (float)minColumnWidth;

A couple other API items changed names:

Before:

- (void)drawTitle:(NSString *)title inRect:(NSRect)aRect ofColumn:(int)column;

- (BOOL)browser:(NSBrowser *)sender selectCell:(NSString *)title inColumn:(int)column;

After:

- (void)drawTitleOfColumn:(int)column inRect:(NSRect)aRect;

- (BOOL)browser:(NSBrowser *)sender selectCellWithString:(NSString *)title inColumn:(int)column;

Selection may now be done by index as well as path.  Previously the developer was forced to resort to NSMatrix apis when trying to select a row in a browser column by index.  Now she may use:

- (void)selectRow:(int)row inColumn:(int)column;

- (int)selectedRowInColumn:(int)column;

And the following delegate method was added in parallel to allow the delegate to perform the selection:

- (BOOL)browser:(NSBrowser *)sender selectRow:(int)row inColumn:(int)column;

Alerts

Two pairs of new functions have been added to support the alert styles found in the Windows UI. NSRunInformationalAlertPanel() and NSRunCriticalAlertPanel() take the same paramenters as NSRunAlertPanel(), but on Windows they present an alert with the "informational" or "critcal" icons, respectively.  On Windows NSRunAlertPanel() presents an alert with the "warning" icon.  On Mach calling any of the three functions produces the same UI.  Also note that on Windows alerts have no title, so the title argument to these functions is not displayed in the UI.  In addition, NSGetInformationalAlertPanel() and NSGetCriticalAlertPanel() have been added, which have the same relationship to the existing NSGetAlertPanel().

The function NSRunLocalizedAlertPanel() is removed from the API; use NSRunAlertPanel() with explicitly localized arguments instead.

Services

The API involved in vending services has changed in PR2.  The need for two names to resolve a service provider has been removed.  In PR1, services were advertised in the Info.plist using a combination of NSExecutable, and NSProviderName.  The provider name is now obsolete, so you simply advertise a single name under the entry NSPortName.  This entry has the same meaning as in 3.3 services.  Usually NSPortName will be the name of your application as NSExecutable was (e.g. "Webster").  The following API changes have also been made:

•	registerServiceProvider:withName: has been obsoleted.  Use setServicesProvider:.

•	unregisterServiceProviderNamed: has been obsolete.  Use setServicesProvider:nil.

Two new functions, NSRegisterServiceProvider() and NSUnregisterServicesProvider() can be used to register service providers under a given name.  These functions should only be used by service providers not creating an application object (filter services often fall into this category).  The name argument should be the same as that specified by the NSPortName entry of the Info.plist.  See the Services documentation for more details.

NSWindow

The following new methods control the resizing behavior of the window.  The first pair are used to make a window resize in fixed increments.  The second pair are used to make a window resize such that it maintains an aspect ratio.

- (void)setResizeIncrements:(NSSize)increments;

- (NSSize)resizeIncrements;

- (void)setAspectRatio:(NSSize)ratio;

- (NSSize)aspectRatio;

The following new methods provide an OpenStep alternative to the NEXTSTEP-specific feature of instance drawing.  The first method saves away a part of the window's image.  Typically after this step, some temporary drawing is done.  The second method restores the previously saved image, undoing any drawing that has happened since it was saved.  The third method releases the memory used to hold the saved image.

- (void)cacheImageInRect:(NSRect)aRect;

- (void)restoreCachedImage;

- (void)discardCachedImage;

The fax: method has been removed from the OpenStep specification, and is now specific to the Mach platform.

A Windows-specific method has been added to allow access to the Windows window handle of an NSWindow object.  This will only be of interest to developers calling the Win32 API directly.

- (void * /*HWND*/)windowHandle;

NSView

The following new method removes a view from its view hierarchy, without marking that the now exposed region in its superview needs redisplay.  This can be useful when a view is temporaily swapped in so as to draw something on behalf of its superview.

- (void)removeFromSuperviewWithoutNeedingDisplay;

The following method was added in order to preserve the utility of panels that "become key only if needed" (the Font Panel, for example).  This feature was defeated by the advent of increased keyboard accessibility to the UI, as nearly all widgets now accept becoming the first responder, which meant the panel would become key almost no matter where the user clicked.  The following method is implemented by a widget to return YES if clicking on it should cause one of these panels to become key (which is the same role acceptsFirstResponder used to play in these panels).

- (BOOL)needsPanelToBecomeKey;

The fax: method has been removed from the OpenStep spec, and is now specific to the Mach platform.

The following API was removed because it was unused in any of the OPENSTEP products.

@interface NSView(NSRIBPrinting)

- (BOOL)canPrintRIB;

@end

typedef enum _NSPosition {

NSNoPosition = 0,

NSLeft = 1,

NSRight = 2,

NSTop = 3,

NSBottom = 4

} NSPosition;

A new method has been added to NSView, which is to be overridden by subclassers to find when their view is installed in a new superview.

- (void)viewWillMoveToSuperview:(NSView *)newSuperview;

Two new display methods have been added to round out the existing set.

- (void)displayIfNeededInRect:(NSRect)rect;

- (void)displayIfNeededInRectIgnoringOpacity:(NSRect)rect;

The NSViewBoundsChangedNotification notification present in PR1 has been added to the OpenStep spec.

Updating in NSApplication, NSWindow and DPSClient

Various updating mechanisms in the Application Kit are now driven by a new Foundation feature, where NSRunLoop will perform selectors registered by clients in a given order during it's next cycle. (See performSelector:target:argument:order:modes: in NSRunLoop.)  The following constants represent these uses within the Application Kit:

NSUpdateWindowsRunLoopOrdering (500000)	All Windows are sent the update message.  This is also the time when menu items are enabled and disabled.

NSDisplayWindowRunLoopOrdering (600000)	All Windows holding Views needing redisplay are given the chance to redraw.

NSResetCursorRectsRunLoopOrdering (700000)	If needed, cursor rectangles are reestablished.

DPSFlushContextRunLoopOrdering (800000)	The IPC channel to the Window Server is flushed, ensuring any buffered data is executed.

NSResponder

The insertNewLine: method was renamed to insertNewline:.

NSApplicationMain

The AppKit now provides a function NSApplicationMain() to take care of the initialization and startup of your application.  This function is declared in NSApplication.h.  Because of this, ProjectBuilder will now generate a trivial main function for your application:

#import <AppKit/NSApplication.h>

int main(int argc, const char *argv[]) {

    NSApplicationMain(argc, argv);

}

Although developer's should not need access to the body of NSApplicationMain(), it is documented here in the rare case that it is necessary.  If at all possible, avoid copying this code, as doing so may prevent your application from automatically inheriting features added in future releases.

int NSApplicationMain(int argc, const char *argv[]) {

    NSAutoreleasePool * pool     = [[NSAutoreleasePool alloc] init];

    NSDictionary *info           = [[NSBundle mainBundle] infoDictionary];

    NSString *principalClassName = [info objectForKey: @"NSPrincipalClass"];

    NSString *mainNibFile        = [info objectForKey: @"NSMainNibFile"];

    if (principalClassName) {

Class principalClass = NSClassFromString(principalClassName);

if (principalClass) {

    [principalClass sharedApplication];

    if ([NSBundle loadNibNamed: mainNibFile owner: NSApp]) {

[pool release];

[(NSApplication *)NSApp run];

[NSApp release];

exit(0);

    }

    else NSLog(@"Unable to load nib file: %@, exiting", mainNibFile);

}

else NSLog(@"Unable to find class: %@, exiting", principalClassName);

    }

    else NSLog(@"No NSPrincipalClass specified in info dictionary, exiting");

    [NSApp release];

    [pool release];

    exit(1);

    return 0;

}

NSHost

NSHost (or NXHost)'ing is supported only between OPENSTEP for Mach machines or from NEXTSTEP 3.x machines to OPENSTEP for Mach.  You cannot run an OPENSTEP application NSHost'ed to a 3.x machine. NSHost'ing is also not supported on OPENSTEP for Windows.

ObjectLinks

ObjectLinks have been removed from the OpenStep specification, and in general the feature is not supported in OPENSTEP for Mach or Windows.  The exception is that the following subset of the API may be used on either platform to walk through the linked data from documents written in NEXTSTEP 3.X:

@interface NSDataLinkManager : NSObject <NSCoding> {

- (id)initWithDelegate:(id)obj fromFile:(NSString *)path;

- (NSEnumerator *)sourceLinkEnumerator;

- (NSEnumerator *)destinationLinkEnumerator;

@end

@interface NSDataLink : NSObject <NSCopying, NSCoding>

- (NSArray *)types;

- (NSSelection *)sourceSelection;

- (NSSelection *)destinationSelection;

- (NSString *)sourceFilename;

- (NSString *)currentSourceFilename;_- (NSString *)destinationFilename;

- (NSString *)sourceApplicationName;

- (NSString *)destinationApplicationName;

- (NSDataLinkManager *)manager;

- (NSDate *)lastUpdateTime;

- (NSDataLinkNumber)linkNumber;

- (NSDataLinkDisposition)disposition;

@end

@interface NSSelection : NSObject <NSCopying, NSCoding>

+ (NSSelection *)emptySelection;

+ (NSSelection *)allSelection;

+ (NSSelection *)currentSelection;

- (NSData *)descriptionData;

- (BOOL)isWellKnownSelection;

@end

Note that this API is a subset of the previously provided ObjectLinks API, with one exception:  The currentSourceFilename method has been added to NSDataLink to allow the application to query the current location of the source file (whereas the sourceFilename method returns the original name).

-NSShowPS

On Windows NT, when apps are run with the arguments "-NSShowPS YES", they will produce a dump of their PostScript output in the file $TEMP\showps.txt (where $TEMP is an environment variable usually containing "C:\temp".

NSColor

The following methods have been added to NSColor:

@interface NSColor (NSDynamicSystemColors)         // OpenStep/Mach:    Windows Name:

+ (NSColor *)controlShadowColor;                   // darkGrayColor     COLOR_3DSHADOW

+ (NSColor *)controlDarkShadowColor;               // blackColor        COLOR_3DDKSHADOW

+ (NSColor *)controlColor;                         // lightGrayColor    COLOR_3DFACE

+ (NSColor *)controlHighlightColor;                // lightGrayColor    COLOR_3DLIGHT

+ (NSColor *)controlLightHighlightColor;           // whiteColor        COLOR_3DHILIGHT

+ (NSColor *)textColor;                            // blackColor        COLOR_WINDOWTEXT

+ (NSColor *)textBackgroundColor;                  // whiteColor        COLOR_WINDOW

+ (NSColor *)selectedTextColor;                    // blackColor        COLOR_HIGHLIGHTTEXT

+ (NSColor *)selectedTextBackgroundColor;          // lightGrayColor    COLOR_HIGHLIGHT

+ (NSColor *)controlBackgroundColor;               // lightGrayColor    COLOR_WINDOW

+ (NSColor *)controlTextColor;                     // blackColor        COLOR_BTNTEXT

+ (NSColor *)selectedControlTextColor;             // blackColor        COLOR_HIGHLIGHTTEXT

+ (NSColor *)selectedControlColor;                 // whiteColor        COLOR_HIGHLIGHT

+ (NSColor *)scrollBarColor;                       // grayColor         COLOR_SCROLLBAR

+ (NSColor *)gridColor;                            // grayColor         COLOR_3DFACE

@end

These colors should be used by developers who want to create custom controls or subclass existing controls which honor the user's color preferences.  For example, where

PSsetgray(NX_LTGRAY);

was used,

[[NSColor controlColor] set];

is now used.

These colors belong to their own color space, namely:

extern NSString *NSDynamicSystemColorSpace;

Since these colors may change dynamically, they do not respond to the component accessor methods declared in NSColor.h.  To extract the components of a system color, you must use NSColor's colorUsingColorSpaceName: method to convert the color to a color space known to respond to the component accessor methods you need.

The following notification has been added which is sent when the system colors have been changed (such as through a system control panel interface):

extern NSString *NSSystemColorsDidChangeNotification;

The default NSCMYKAdjust is now YES by default. This basically enables the WindowServer's ability to use an enhanced algorithm for rendering device-dependent CMYK colors on an RGB device, resulting in a greater accuracy in the on-screen appearance of CMYK colors.

Applications can turn this off by registering this default with a NO value at startup time.

Platform-specific Resources

Under PR1 and PR2 including platform-specific versions of resource files (nibs, for instance), required Makefile kludgery and/or source changes. This is no longer necessary.

NSBundle has been changed so that when it fetches a resource, it will look in the directory where the resource was found one additional time to check for a platform-specific version. The platform specific versions are indicated by appending "-platformname" to the base name of the resource. Valid platform names include winnt and nextstep.

For example, to include a Windows-specific version of Doc.draw in your project, simply add it as Doc-winnt.draw. The call [bundle pathForResource:@"Doc" ofType:@"draw"] will find the latter under OPENSTEP for Windows. Similarly a Windows-specific version of Edit.nib can be added as Edit-winnt.nib.

Note that ProjectBuilder also provides ways to specify platform-specific app and document icons, paths, and build options.

NSMenu

The OpenStep spec was amended to make NSMenu a subclass of NSObject, not NSPanel, and to replace NSMenuCell with the NSMenuItem protocol.  NeXT's OPENSTEP products also provide an NSMenuItem class which conforms to the NSMenuItem protocol.

NSMenu and NSMenuItem provide almost all of the functionality of the old classes, but some window and cell specific features are no longer available.  This change was motivated by the very different ways menus are handled on different operating systems (such as Microsoft Windows).  See the headers for more detail.

The NSWindow and NSView have additional support for menus to support Microsoft Windows conventions.  Each NSWindow can have its own menu bar or no menu bar at all.  By default NSWindow objects have the application's main menu as their menu bar while NSPanels have no menu bar.  Use -[NSWindow setMenu:] to set a different NSMenu to be used as the  menu bar in an NSWindow.  setMenu: in NSWindow only has an affect in OPENSTEP for Windows since on Mach, windows do not have menu bars, but the API does exist on both platforms.

NSViews can now have menus associated with them as well.  An NSView's menu is used as a contextual popup menu accessed by right-clicking the view (this should be a familiar feature to users of Windows 95).  By default an NSView has no contextual menu, but some AppKit objects will provide default context menus.  Currently only NSTextView (and therefore also editable controls) have a default menu, but this is likely to change.  You can set a menu to be used as the context menu for a view through -[NSView setMenu:].  Context menus currently only work on OPENSTEP for Windows.

Setting a menu for either a window or view on Mach has no affect, so there is no need to do this conditionally inside an #ifdef WIN32 or anything.  Context menus for views may even be supported on Mach in a later release.

Interface Style

Some aspects of the new support for multiple interface styles (or UIs) have been made public.

The header NSInterfaceStyle.h is now public and can be used by developers writing classes that need to tailor their appearance to the current interface style  (usually NSControl or NSView subclasses, but not always).  The function NSInterfaceStyleForKey() can be used to determine which style is in effect at a given time.  This API should be used instead of relying on #ifdef WIN32 so that your drawing will be correct in all cases.  For instance, InterfaceBuilder lets the user specify what interface style to show when editing nibs so that you can see what your interface will look like on any supported platform without actually having to be running on that platform.

The default NSInterfaceStyle can be used to control what style to use.  By default the native interface style will be used, but you can override that with this default.  Currently supported values are Windows95 and Mach.  Not everything can obey this setting, but most AppKit objects do.

NSPopUpButton

NSPopUpButtons no longer have NSButtonCells for items, the items in a popup now have the type (id <NSMenuItem>).  Also, The -(NSMatrix *)itemMatrix method has been replaced with -(NSArray *)itemArray which returns an NSArray instead of an NSMatrix.

NSButton and NSButtonCell

The setType: method in NSButton and NSButtonCell has been renamed to setButtonType:, because the old name overloaded a method inherited from NSCell.

NSMatrix

Two new convenience methods have been added to NSMatrix:

- (int)numberOfRows;

- (int)numberOfColumns;

NSSavePanel

NSSavePanel now inherits from NSObject in the OpenStep specification to gain greater portability.  This means that although on Mach NSSavePanel is implemented as a subclass of NSPanel, methods inherited from NSPanel and NSWindow are not considered part of the spec.  In fact, on Windows NSSavePanel is implemented as subclass of NSObject since we are using the native UI.

A new method has been added to the SavePanel to validate the visible columns.  For instance, say your filtering criteria have changed.  Call this method to get the correct files displayed:

- (void)validateVisibleColumns;

NSScrollView

Methods have been added to access the content view of the ScrollView.  The content view is the scroll view's clip view:

- (void)setContentView:(NSClipView *)contentView;

- (NSClipView *)contentView;

Windows Application Lifetime Issues

Applications under Windows introduce some interesting life cycle issues.  One issue is that because the menus are only present inside of windows, an application with no open windows has no UI.  Another issue is that when you double-click a file, Windows generally starts a fresh copy of the associated application to open it even if there's another copy already running.  In OPENSTEP we have addressed these issues by defining some default behaviors and providing some new API to ensure that developers can control the behaviors if necessary.

By default, on Windows, an Application will terminate when the last menu-bearing window is closed.  In general, this is the right thing to do.  Sometimes, however, you may need to do something different.  A new NSApplication delegate message has been added to allow you to override this default behavior.  When NSApplication notices the last menu-bearing window has been closed, it will send -(BOOL)applicationShouldTerminateAfterLastWindowClosed:(NSApplication *)sender to the application's delegate if it responds.  This message is sent on both Mach and Windows so it may be necessary to tailor your app's response for the platform.  On Mach, application do not, by default, terminate when windows are closed.  If you implement this method you should return YES if the application should terminate and NO if it should not.  If you return YES you will shortly receive an -applicationShouldTerminate: messageas well.  If you return NO you should also have arranged for some UI to remain.  If you return NO and do nothing else, you are likely to lose all UI to your app and leave the user with no way to quit or do anything else.

On the other end of the life cycle, a new Windows-only feature has been added to NSApplication.  If the arguments to the application on the command line includes the argument pair "-NSUseRunningCopy YES" then the app will check to see if a copy of itself is already running, and if it is, it will hand off to the running copy and exit.  Any -NSOpen or -NSPrint requests will be forwarded on to the existing copy.  When file associations are made for OpenStep apps, these arguments are included in the association.  Therefore, double-clicking multiple .draw documents should end up opening them in a single copy of Draw.  This feature is supported through a single NSApplication method.  +(void)useRunningCopyOfApplication is called from the default implementation of the WinMain function.  Apps that never want to use this feature can implement their own WinMain and avoid calling this method, but there should be very few good reasons to want to do that.

 NSPasteboard and the NSFileContentsPboardType

NSFileContentsPboardType has been modified slightly to be the same as NSFileWrapper's serializedRepresentation.  We expect this change to make the type much more useful.  Among other things this means that NSFileContentsPboardType and NSRTFDPboardType use identical formats.  There is still a semantic difference between the two, however.  NSRTFDPboardType is used only for RTFD text and it must satisfy certain constraints on the actual file contents written (eg there must be a file inside called TXT.rtf and so forth).

In support of this change, and to make it easier to use NSFileContentsPboardType in your applications, NSPasteboard has some new API for dealing with this type.  In the past you had to write this type onto the pasteboard from the filesystem.  And when you read it from the pasteboard you had to write it to the file system.  Now it is possible to wirte this type from an NSFileWrapper instance and to read it out and get a new NSFileWrapper instance.  The disk need not be involved anymore.  The new API is:

- (BOOL)writeFileWrapper:(NSFileWrapper *)wrapper;

- (NSFileWrapper *)readFileWrapper;

Notification Name Changes

Some of the names of AppKit notifications have changed to follow the general naming guidelines.

Old Name	New Name

NSColorListChangedNotification	NSColorListDidChangeNotification

NSColorPanelColorChangedNotification	NSColorPanelColorDidChangeNotification

NSImageRepRegistryChangedNotification	NSImageRepRegistryDidChangeNotification

NSViewFocusChangedNotification	NSViewFocusDidChangeNotification

NSViewFrameChangedNotification	NSViewFrameDidChangeNotification

NSViewBoundsChangedNotification	NSViewBoundsDidChangeNotification

NSDragOperation Removed

The NSDragOperation typedef has been removed from the API, and all uses are replaced by unsigned int, since the values used for this type must be often or'ed together.

NSPageLayout

NSPageLayout now inherits from NSObject in the OpenStep specification to gain greater portability.  This means that although on Mach NSPageLayout is implemented as a subclass of NSPanel, methods inherited from NSPanel and NSWindow are not considered part of the spec.  In fact, on Windows NSPageLayout is implemented as subclass of NSObject since we are using the native UI.

In addition, the following methods and types have been removed from the OpenStep specification, but are still available on the Mach platform:

- (void)convertOldFactor:(float *)old newFactor:(float *)new

- (void)pickedButton:(id)sender.

- (void)pickedOrientation:(id)sender

- (void)pickedPaperSize:(id)sender

- (void)pickedUnits:(id)sender

enum {

NSPLImageButton,_NSPLTitleField,

NSPLPaperNameButton,

NSPLUnitsButton,

NSPLWidthForm,

NSPLHeightForm,

NSPLOrientationMatrix,

NSPLCancelButton,

NSPLOKButton

};

The runModal and runModalWithPrintInfo: methods now return NSOKButton or NSCancelButton on all platforms._

NSPrintInfo

There are two new keys available in the NSPrintInfo dictionary on the Windows platform:

NSPrintMustCollate

NSPrintFormName

NSPrintMustCollate indicates whether collation occurs when multiple copies are printed. NSPrintFormName is the form name associated with the current print request, which might be different from the NSPrintPaperName.

NSPrinter

A new method has been added to return the names of configured printers available to the system.  This name can then be passed to printerWithName: to create an NSPrinter.  If no printers are available, an empty array is returned. If an error occurs, nil is returned.

+ (NSArray *)printerNames

NSPrintPanel

The NSPrintPanel class has been removed from the OpenStep specification. In addition, these related methods in NSPrintOperation have been removed from the specification :

- (void)setPrintPanel:(NSPrintPanel *)panel;

- (NSPrintPanel *)printPanel;

NSPrintPanel is still available as a platform specific interface; however, it now inherits from NSObject rather than NSPanel.

NSPrintOperation

The following methods were added to NSPrintOperation in the OpenStep specification to allow the accessory view to be set in the print panel:

- (void)setAccessoryView:(NSView *)aView;

- (NSView *)accessoryView;

The following methods have also been added to the specification. These methods are sent to the accessory view passed to the above methods if it responds to them.

- (void)updateFromPrintInfo;

- (void)finalWritePrintInfo;

New Graphics Functions

Four new functions have been added to support conformance to the Windows UI look:

void NSRectFillListWithColors(const NSRect *rects, NSColor *colors, int count);

Fills each rectangle in the array rects with the color whose value is stored at the corresponding location in the array colors. Both arrays must be count elements long. Avoid rectangles that overlap, because the order in which they'll be filled can't be guaranteed.

void NSDrawDarkBezel(NSRect aRect, NSRect clipRect)

Draws a bordered rectangle with the appearance of a pushed-in button, clipped by intersecting with clipRect.

NSRect NSDrawColorTiledRects(NSRect boundsRect, NSRect clipRect, const NSRectEdge *sides,

NSColor *colors, int count)

Draws an unfilled rectangle, clipped by clipRect, whose border is defined by the parallel arrays sides and colors, both of length count. Each element of sides specifies an edge of the rectangle, which is drawn with a width of 1.0 using the corresponding color from colors. If the edges array contains recurrences of the same edge, each is inset within the  previous edge.

void NSDrawLightBezel(NSRect aRect, NSRect clipRect)

Draws a rectangle with the appearance of an editable text field. Only the area that intersects clipRect is drawn.

NSFont

The method maximumAdvancement was added to the API to return the advancement of the widest glyph in the given font.  If the font is fixed-pitch, this is the advancement of all the glyphs.

The following API additions (which are not in OPENSTEP) allow one to get/set a list of the user's "preferred" fonts, which are checked (in order) before any other fonts when searching for a font to render some character that cannot be rendered in a pre-given or specified font.  The list should typically contain fonts with different encodings and glyph complements, as available.

 + (NSArray *)preferredFontNames;

 + (void)setPreferredFontNames:(NSArray *)array;

API has also been added to access the Windows system fonts.

+ (NSFont *)menuFontOfSize:(float)fontSize;

+ (NSFont *)titleBarFontOfSize:(float)fontSize;

+ (NSFont *)messageFontOfSize:(float)fontSize;

+ (NSFont *)paletteFontOfSize:(float)fontSize;

+ (NSFont *)toolTipsFontOfSize:(float)fontSize;

The existing NSFont methods systemFontOfSize: and boldSystemFontOfSize: now return the same as messageFontOfSize: and titleBarFontOfSize: respectively.  This API is valid on Mach and Windows.  On Mach it returns the standard system or bold system fonts.  On WIndows it will return the user's font settings from the Display options control panel if the user's chosen fonts can be supported (currently bitmap fonts are not supported, but TrueType fonts are).

NSFontManager

NSFixedPitchFontMask mask was added so that the font manager can determine whether or not a font is fixed-pitch.  It may be used in trait queries.

The method fontNamed:hasTraits: was added to help in searching for fonts with specified traits.  The available traits are specified by the trait masks.

The new method availableFontNamesWithTraits: uses the given mask (which may contain several one bits) in testing the available fonts.  The names of all fonts matching the given bits are returned in an array.

NSInputManager/NSInputServer

The method doCommandByName: was removed from the API and from the NSTextInput protocol in favor of doCommandBySelector:.  (The latter was already in the API, but has been added to the NSTextInput protocol.) Along the same lines the NSInputServer method doCommandByName:sender:conversation: was also obsoleted.

The method localizedInputManagerName replaces the method inputManagerName.

Dead Keys

Dead key handling in DPSClient is now off by default. The new text object and keyboard UI rely on the input management layer to simulate dead keys. NSCStringText will turn dead key handling on and off as it gains and loses first responder status. Other custom views which need dead keys to be handled by DPSClient should also use the same approach.

Help System

The AppKit's Help API has changed significantly.  NSHelpPanel has been obsoleted in favor of a new class, NSHelpManager.  NSHelpManager provides a more platform-independent approach to presenting help.

Previously, the only way for your application to present help was through the NEXTSTEP Help panel.  Context-sensitive help and all other help for your application was displayed in the Help panel.  This made sense when NEXTSTEP was the only platform for your application.

OpenStep applications, however, can run on multiple platforms, and each platform provides its own support for online help.  It's important to users that applications use the native online help system (on Windows, for instance, users want the Windows help system and don't want to have to learn how to use a different help system), so NSHelpManager does not provide a comprehensive solution for presenting help.  Instead, it provides cross-platform support for context-sensitive help, and allows you to present more comprehensive help (conceptual and task-based help) in any way you choose.

Context Help

Context-sensitive help (also referred to as context help) gives the user a small amount of information when they help-click on an interface item.  For example, if the user help-clicks on a menu item called "Copy", they should get context help that says something like "Copies the currently selected text to the pasteboard."  This text appears in a small window near where the user help-clicked, and the window disappears when the user clicks anywhere else in the application.

To provide context help for your application, follow these steps:

1.	For each interface item that needs context help, create an .rtf or .rtfd file containing the text and any images you want to appear when the user help-clicks on that interface item.  Try to keep the text as brief as possible and the images as small as possible.

2.	If you don't need to localize your context help files, in Project Builder simply add these files to the Context Help suitcase of your project.

If you do need to localize your context help files, first copy the files into the appropriate .lproj directory of your project, then use Project Builder to add them to the Context Help suitcase of your project.

3. 	In Interface Builder,  connect each interface item to its context help file by doing the following:

a.  Bring up the Interface Builder inspector and choose the Help display.  The Help display lists all the context help files associated with your application.

b.  Select an interface item.

c.  In the inspector, choose the appropriate help file.

When you compile your application, /usr/bin/compileHelp packages your help files into a property list named Help.plist.  NSHelpManager knows how to extract context help from an Help.plist file.

Comprehensive Help

Most applications provide some form of online help that is more comprehensive and detailed than context-sensitive help, such as conceptual or task help.  NSHelpManager allows you to provide this sort of comprehensive help in any way you choose.  Some help authors prefer to provide comprehensive help in HTML using a World-Wide Web browser; others use tools such as Digital Librarian or Concurrence; on Windows a full-featured native help system is available.  Given the availability of rich tools like Digital Librarian and HTML browsers, OpenStep on Mach no longer supplies a native help system for comprehensive help.

When the user chooses the Help menu item, NSHelpManager simply asks the Workspace Manager to open the help file you have specified for your application.  That file should be the starting point of your help, and should allow users to access whatever information they might need.

To specify a help file for your application, do one of the following:

•	The simplest approach, not requiring you to specify the help file anywhere in your application, is to place the help file in your app wrapper and name it after your application.  If you haven't specified a help file, NSHelpManager looks in the app wrapper for an appropriately named file.

On Mach, it must be an rtf file called <appName>.rtf.

On Windows, it must be a Windows help file called <appName>.hlp.

•	To specify a help file that applies to all platforms, define the NSHelpFile key in your project's CustomInfo.plist file:

{

NSHelpFile = "ApplicationHelp.rtfd";

}

If your project does not have a CustomInfo.plist, simply create one (as in the example), and add it to your project's "Supporting Files" file category.  When you build your project, the contents of CustomInfo.plist will be merged into your application's Info.plist

The specified value for the NSHelpFile key can be a full or relative path, and if it is relative, it is assummed to be a bundle resource (resolved using [[NSBundle mainBundle] pathForResource:<NSHelpFile value> ofType:nil]).


AppKit Changes Since 4.0

The following list all the API changes and some of the bug fixes that were done in the Application Kit between 4.0 and 4.1.

Note that in your application if you use any API which was added between 4.0 and 4.1, your application might not run under 4.0. (If you are not deploying under 4.0, then this is not an issue.) You can catch some of the potential problems by defining STRICT_40 at compile time. This #define is used in the Application and Foundation Kits to mark new API.

Similarly, if you rely on a bug fix done in 4.1, your application may not function correctly under 4.0. Make sure you test on your intended deployment platform.

NSApplication

IBOutlet and IBAction are now defined in the kit and automatically imported if you import AppKit.h. You can remove your own custom definitions of these (if you had any).

The hide: method has been changed to do nothing on Windows.

The default value of the NSUseRunningCopy command line option has been changed to YES. This means that anytime you cause a second copy of the application to be launched, it will connect you to the already running copy. You should also If you wish to run multiple copies of an application, you should use "-NSUseRunningCopy NO". You might need this if you need to debug a new instance of the application while it's already running.

Another change is that all command line options which are not defaults options (meaning a pair of arguments where the first one starts with a "-") are now treated as file names to be opened, as if they were prefixed with -NSOpen.

As a result of these two changes, you can now associate documents with OPENSTEP apps on Windows simply by providing the location of the app. The default command line provided by the Explorer will be enough to open documents and also connect to a running copy of the application, if there is one.

On Windows,  [NSApplication init] (called by sharedApplication) changes the current directory to the root of the drive from which the application is launched. This is done in order to avoid problems associated with the application starting off in random places (such as the directory of a file wrapper, when launched by double-clicking on a file in a file wrapper). One consequence of this is that any directory changes which take place in the main() function, before sharedApplication, will fail to stick.

NSWindow

In OPENSTEP for Windows, document edited state is now indicated in the title bar by prefixing the title with an asterisk. OPENSTEP for Mach still uses a broken "X".

Tracking rects are now implemented on Windows.

The following are not actually changes since 4.1, but are a couple things to be aware of concerning NSWindows in OPENSTEP for Windows.

•	Under Windows, the frameRect and contentRect are currently the same size.  The frameRect of an NSWindow under OPENSTEP for WIndows NT does NOT include the title bar, menu bar, resize border, etc...

•	Under Windows, the contentView while a window is miniaturized is a NSImageView, not the original contentView.  The contentView is restored when the window is deminiaturized.  This is necessary because under some versions of Windows NT, the same actual window is used when the window is full size or miniaturized.  It is just moved and resized when miniaturing or restoring.  Since most content views are not prepared to size themselves that small, the content view is removed from the window while it miniaturizes and is restored when the window is restored.

NSTableView

A new notification, NSTableViewSelectionDidChangeNotification, and a corresponding delegate method, tableViewSelectionIsChanging:, have been added to NSTableView. The existing NSTableViewSelectionDidChangeNotification is only sent after the user has moused up when changing a selection.  The new notification is sent while the selection is changing.

NSSavePanel

The save panel will now put up an alert letting you confirm before you replace an existing file.

NSInputServer

The following methods were added to NSInputServer. They are sent by current input manager when the application changes state so that the server can update its concept of who's current.  The actually "active" sender is the last one to have sent a senderDidBecomeActive: message.  These methods may not arrive in the expected order.

- (void)senderDidBecomeActive:(id)sender;

- (void)senderDidResignActive:(id)sender;

This method is sent by input manager when the conversation within a particular sender changes:

- (void)activeConversationWillChange:(id)sender oldConversation:(long)conv newConversation:(long)new;

NSTextView

To allow entering a character without an appropriate keyboard, you can now use the Alt key in conjunction with the digit keys from the keypad.  While holding down the Alt key, type the index of the desired character in the encoding of the current font (in most cases this will be the NEXTSTEP encoding). The appropriate character will be inserted into the text when the Alt key is released.

NSWorkspace

The openFile:withApplication: will now correctly open the file with the specified application. In 4.0 this method always returned NO when an application name was supplied.

OPENSTEP for Window now contains an "open" command.  Like on Mach, "open filename" will open the specified file in its registered application. You can also use the "-e" flag to open the file in TextEdit or the "-a" flag to launch an application.

NSAttributedString

If supplied a plain text file, the initWithPath:documentAttributes: method will now go ahead and still create an attributed string from the plain text contents. Note that if the file looks like an RTF file (has the appropriate magic header), but fails to open, the method will still return nil.

NSColor

Unarchived NSColors and NSColors created with colorWithCalibratedRed:green:blue:alpha: and colorWithCalibratedWhite:alpha: will be replaced by the cached and uniqued colors returned by methods such as [NSColor whiteColor] if they are exactly the same. In some cases this will greatly reduce the number of colors created at runtime and speed up certain operations. However, in the unlikely event that this causes problems in your application, or prevents your 4.0 application from running correctly under 4.1, you can set the NSCachedColorConversion default to NO.

System colors (such as those returned by [NSColor controlColor]) have been improved to generate colors which match those used by Windows. Under 8-bit color this should result in a visible improvement in certain color schemes.


Application Kit
Application Kit Framework

OPENSTEP Enterprise Release 4.1  Copyright ©1996 by NeXT Software, Inc.  All Rights Reserved.

New Features in 4.1

ComboBox

The NSComboBox class has been added to the Application Kit. It offers similar functionality to the Combo Box control defined in the MicrosoftTM Windows® user interface.

Splash Screen

OPENSTEP for Windows now provides support for a "splash" screen in applications—basically a panel that comes up with a static image as the application is being launched. To use this feature, simply provide an 8-bit uncompressed bmp image named Splash.bmp as a resource in your application. You can make it localizable if you wish. (Thus the image will be either in appname.app/Resources or appname.app/Resources/language.lproj.) At launch time, the image will be loaded and displayed before any other initialization in the application, and will be removed from the screen before the first window is displayed.

For other changes in 4.1 please refer to the "Changes since 4.0" section below.

New Features in 4.0

OpenStep

OpenStep brings numerous API changes to the AppKit relative to Release 3.3.  These changes and the tools provided for applications to convert to OpenStep are described in /NextLibrary/Documentation/NextDev/Conversion/ConversionGuide, available on OPENSTEP for Mach.

New Text System

4.0 includes a new text system composed of several different classes: NSTextView (front-end UI), NSTextStorage and NSAttributedString (back-end text storage), NSLayoutManager (management of text layout process and info), and NSTextContainer (description of text flow areas).  These classes provide an open, powerful interface and allow text editing in multiple languages, using the Unicode standard. Please refer to the documentation for detailed info. An overview can be found in /NextLibrary/Documentation/NextDev/TasksAndConcepts/ProgrammingTopics/TextOverview.rtfd (Mach) or in the /NextLibrary/Documentation/NextDev/TasksAndConcepts/Topics.hlp (Windows). There is also a separate release note which describes some of the defaults that can be used to customize the new text system and how to remap or add to the standard supported keybindings. In addition to these notes, the source code to several text-specific examples, including the full source to TextEdit, can be found in the /NextDeveloper/Examples/AppKit directory.

TableView

TableView has been completely rewritten and moved into the AppKit.  All four classes making up the new TableView are public and fully subclassable.

Keyboard UI

Keyboard access is now provided to most of the controls in the AppKit.  For more information, see the separate Keyboard UI Release Notes.

Formatting and Validation

Cells may now be assigned arbitrary object values, which are converted into presentation strings by associated formatter objects.  This allows the developer to directly set an NSDate, for instance, as the value of a cell.  The cell's associated date formatter will present a localized string representation of the date to the user.  The formatter objects, along with control delegates, can also perform validation on user-entered data, thereby restricting entries to valid ranges or quantities, for instance only allowing dates between January 1, 1995 and June 30, 1995.

Rich Text in Cells

NSCell and subclasses can now display and edit rich text. The rich text is specified via instances of NSAttributedString. The new formatting/validation API also includes support for attributed strings.

RulerView

NSRulerView is designed as a general-purpose ruler that can be associated with any scroll view and used by any view that's in the scroll view. It supports both horizontal and vertical rulers, allows arbitrary markers along the rule, and can accept an accessory view.

System Colors

New API has been added to access system-defined colors, such as the color of buttons, controls, text and text selection colors. On Windows, where the user can change the system colors at any point, these colors will change at runtime to match the user's selection.

Help System

The AppKit's Help API has changed significantly.  NSHelpPanel has been obsoleted in favor of a new class, NSHelpManager, which provides a more platform-independent approach to presenting help.

Known Problems in This Release

NSComboBox

Reference:	71826

Problem:	NSComboBox should support keyboard interface

Description:	NSComboBox does not support keyboard accelerators to open, dismiss, or navigate its popup list.

Workaround: 	None.

Reference:	60438

Problem:	NSComboBox uses a private cell class.

Description:	For the OPENSTEP 4.1 release, the cell class for NSComboBox is private.

Workaround: 	None.

NSTableView

TableView does not yet have printing support.

Reference:	51731

Problem:	TableView does not fully support keyboard ui

Description:	Only simple tabbing between editable cells is implemted in TableView.  Arrow keys do not affect selection.

Workaround: 	Override keyDown: in a subclass or in the owning window and change the selection accordingly.

Reference:	63967

Problem:	Header and row height do not change relative to font size

Description:	When the developer changes the font size of the header view cells or data cells in a TableView, the heights of the header view and rows do not change appropriately.

Workaround: 	Manually change the height of the header view and row height.

NSCell

Reference:	52511

Problem:	setUpFieldEditorAttributes: called only when editing

Description:	setUpFieldEditorAttributes: is not called when non-editable text is displayed in cells. This makes it difficult to change colors in custom subclasses of NSCell.

Workaround: 	To display colored text in cells, text fields or attributed string values may be used.

NSImage

Reference:	60413

Problem:	JPEG TIFFs don't work on Windows.

Description:	Because the imageserver process is not yet available under Windows, JPEG TIFFs cannot be loaded in.

Workaround: 	None. The images can be compressed using another compression scheme using tiffutil on OpenStep for Mach.

New Text System

Reference:	58479

Problem:	Rotated text views don't so selection very well

Description:	The selection drawing (at least) in a rotated NSTextView needs work.  The selection is generally drawn too large and leaves pixels around.

Workaround: 	None.  Avoid editable rotated NSTextViews for now.

Reference:	50123

Problem:	Some features are currently unimplemented

Description:	The following features are currently unimplemented: Full justification, tabs other than left, certain paragraph style attributes, scaled images.

Workaround: 	None.

Reference:	54951

Problem:	Screen fragments in containers with holes

Description:	If you attempt to create an NSTextContainer with holes such that one physical line can have multiple line fragments, there are still problems with erasing old drawing below the hole when text is deleted.

Workaround: 	None.

Reference:	49744

Problem:	Images are not scaled in scaled text

Description:	Using the standard NSTextAttachment class, the images appear at 100%.

Workaround: 	This problem can be fixed by using a custom attachment cell.

Reference:	68768

Problem:	Sometimes two lines will appear on top of each other

Description:	The backing store is fine, but the text is laid out with two lines right on top of each other.  This is fairly rare but somewhat disconcertin

Workaround: 	Typing a character in the overlapped lines and then deleting it will fix the layout.

NSWindow

Reference:	71671

Problem:	Flash active caption bar" visual warning option might cause apps to hang

Description:	If you have enabled SoundSentry (under Accessibility Options in the Control Panel), and turned on "Flash active caption bar" visual warning option, there is a good chance apps will hang when they call NSBeep(). This function is called by the Application Kit in a few cases—when you perform an unrecognized command key, for instance.

Workaround: 	None. Use one of the other visual warning options.

Reference:	72040

Problem:	Resizing a modal panel causes it stop processing mouse down events

Description:	If you resize a modal panel it will stop responding to mouse down events until it is dismissed and brought back on the screen again.

Workaround: 	Because keyboard events still work, you can dismiss the panel by navigating to the appropriate button via keyboard UI.

Reference:	71648

Problem:	Closing a modal window or panel does not always end the modal session

Description:	Closing a modal window or panel by clicking on the close box will not always end the modal session, leaving the application in a state where mouse clicks and key strokes are ignored.  On Windows, modal panels often have a close box.  This acts the same as a cancel button and, by default, clicking the close box while running modal will stop the modal session with the NSCancelButton return code.  However, if the Window's delegate decides to control when the window should close by implementing windowShouldClose:, then it is also up to the delegate to stop the modal session in windowWillClose:.  On Mach, modal windows and panels rarely have a close box; if they do they must stop modal in windowWillClose:.

Workaround: 	On Windows, a window delegate implementing windowShouldClose should stop the modal session in windowWillClose:.  On Mach, any modal window or panel with a close box should stop the modal session in windowWillClose:

Reference:	64988

Problem:	NSBackingStoreNonretained don't work under Windows

Description:	Under Windows, nonretained windows aren't implemented.

Workaround: 	Use retained or buffered windows instead.

Reference:	69973

Problem:	Miniaturizing and then restoring a window under Windows causes first responder to be lost

Description:	When a window is miniaturized it loses track of its current first responder.  When it is restored again, the first responder is not restored.

Workaround: 	You can use makeFirstResponder to set a first responder yourself or just make the user click something.

Reference:	69327

Problem:	Clicking in the contents a window which is key won't bring it to the front

Description:	Under Windows, if a non-key panel is in front of the key window, clicking in the content view of the key window will not bring it to the front.

Workaround: 	Clicking the title bar will bring it to the front.

Drag/Drop

Reference:	60829

Problem:	On Windows, ignoreModifierKeysWhileDragging is never invoked on drag source

Workaround: 	None.

Reference:	67620

Problem:	On Windows draggedImage always returns nil.

Description:	During a dragging session, the DraggingInfo will always return nil when queried for its draggedImage.

Workaround: 	None.

Reference:	63466

Problem:	On Windows, the drag source's image offset is ignored

Description:	Currently the dragged image will appear to the lower right of the cursor's hot spot.

Workaround: 	None.

NSFont

Reference:	61824

Problem:	Microsoft's WingDings font is not supported well under OPENSTEP for Windows

Description:	There isn't currently a Unicode mapping for any of the glyphs in it, even into the User Zone, so it works as any other "unknown" font (i.e., characters 0-255 are mapped directly to glyphs  0-255).

Workaround: 	None.

Keyboard UI

Reference:	51182

Problem:	AccessoryViews are not added to keyView loop

Description:	When a panel supporting accessory views, such as the SavePanel, is brought on screen, the accessory views are not automatically added to the keyView loop.

Workaround: 	Add the accessory view to the keyView loop by hand using setNextKeyView: before brining the panel on screen.

NSOpenPanel

Reference:	63490

Problem:	On Windows, one can open file packages but not directories without extensions.

Description:	The OpenPanel on Windows does not provide a way to select and open plain directories.  Clicking on directories without extensions will expand the directory rather than opening it.  Directories with extensions are correctly dealt with as file packages.

Workaround: 	Either require selectable directories to have extensions or provide a well defined file inside the directory for the user to select.

NSOpenPanel

Reference:	69292

Problem:	AppKit lib is missing DPScomposite(), among others.

Description:	On Windows, all single-operator wrap functions in DPSClient that take an explicit context argument (DPSmoveto, for example) are not available at link time (these functions are present in the dll, but not the lib).

Workaround:	Assuming that you need one of these functions, you can work around this problem by adding -Xlinker /force to your WINDOWS_LDFLAGS. There is a drawback to this workaround, however: if you have other unresolved symbols, your app will build successfully, but crash. In this case, you’ll have to sift through the linker’s warnings to figure out what happened.

Accessory Views

On Windows, the PageLayout panel does not yet support application supplied accessory views.  Also on Windows, accessory views in the Open, Save and Print panels work only on NT 4.0, not NT 3.51.


Changes Prior to 4.0


Changes Since 4.0


Changes to Foundation API Declaration Locations

SYMBOL	OLD HEADER	NEW HEADER

ABS	NSUtilities.h	NSObjCRuntime.h	(NeXT) (40PR2) (40PR1)

MAX	NSUtilities.h	NSObjCRuntime.h	(NeXT) (40PR2) (40PR1)

MIN	NSUtilities.h	NSObjCRuntime.h	(NeXT) (40PR2) (40PR1)

NSCharacterConversionException	NSException.h	NSString.h	(NeXT) (40PR1)

NSComparisonResult	NSObject.h	NSObjCRuntime.h	(NeXT) (40PR2) (40PR1) (EOF11) (NS33)	For OpenStep compatibility, import NSObject.h

NSEnumerator class	NSUtilities.h	NSEnumerator.h	(NeXT) (40PR2) (40PR1) (EOF11) (NS33)	For OpenStep compatibility, import NSUtilities.h

NSLog()	NSUtilities.h	NSObjCRuntime.h	(NeXT) (40PR2) (40PR1) (EOF11) (NS33)	For OpenStep compatibility, import NSUtilities.h

NSLogv()	NSUtilities.h	NSObjCRuntime.h	(NeXT) (40PR2) (40PR1) (EOF11) (NS33)	For OpenStep compatibility, import NSUtilities.h

NSNotFound	NSObject.h	NSObjCRuntime.h	(NeXT) (40PR2) (40PR1) (EOF11) (NS33)	For OpenStep compatibility, import NSObject.h

NXReadNSObject()	NSArchiver.h	NSCompatibility.h	(NeXT) (EOF11) (NS33)

NXWriteNSObject()	NSArchiver.h	NSCompatibility.h	(NeXT) (EOF11) (NS33)

[NSCoder -decodeNXObject:]	NSArchiver.h	NSCompatibility.h	(NeXT) (EOF11) (NS33)

[NSCoder -encodeNXObject:]	NSArchiver.h	NSCompatibility.h	(NeXT) (EOF11) (NS33)

[NSDictionary -descriptionInStringsFileFormat]	NSUtilities.h	NSDictionary.h	(NeXT) (40PR2) (40PR1) (EOF11) (NS33)	For OpenStep compatibility, import NSUtilities.h

[NSString -propertyListFromStringsFileFormat]	NSUtilities.h	NSString.h	(NeXT) (40PR2) (40PR1) (EOF11) (NS33)	For OpenStep compatibility, import NSUtilities.h

[NSString -propertyList]	NSUtilities.h	NSString.h	(NeXT) (40PR2) (40PR1) (EOF11) (NS33)	For OpenStep compatibility, import NSUtilities.h

[Object +allocWithZone:]	NSUtilities.h	NSCompatibility.h	(NeXT) (EOF11) (NS33)

[Object +instanceMethodForSelector:]	NSUtilities.h	NSCompatibility.h	(NeXT) (EOF11) (NS33)

[Object +instancesRespondToSelector:]	NSUtilities.h	NSCompatibility.h	(NeXT) (EOF11) (NS33)

[Object +poseAsClass:]	NSUtilities.h	NSCompatibility.h	(NeXT) (EOF11) (NS33)

[Object -autorelease]	NSUtilities.h	NSCompatibility.h	(NeXT) (EOF11) (NS33)

[Object -conformsToProtocol:]	NSUtilities.h	NSCompatibility.h	(NeXT) (EOF11) (NS33)

[Object -copyWithZone:]	NSUtilities.h	NSCompatibility.h	(NeXT) (EOF11) (NS33)

[Object -dealloc]	NSUtilities.h	NSCompatibility.h	(NeXT) (EOF11) (NS33)

[Object -doesNotRecognizeSelector:]	NSUtilities.h	NSCompatibility.h	(NeXT) (EOF11) (NS33)

[Object -isKindOfClass:]	NSUtilities.h	NSCompatibility.h	(NeXT) (EOF11) (NS33)

[Object -isMemberOfClass:]	NSUtilities.h	NSCompatibility.h	(NeXT) (EOF11) (NS33)

[Object -methodForSelector:]	NSUtilities.h	NSCompatibility.h	(NeXT) (EOF11) (NS33)

[Object -release]	NSUtilities.h	NSCompatibility.h	(NeXT) (EOF11) (NS33)

[Object -respondsToSelector:]	NSUtilities.h	NSCompatibility.h	(NeXT) (EOF11) (NS33)

[Object -retainCount]	NSUtilities.h	NSCompatibility.h	(NeXT) (EOF11) (NS33)

[Object -retain]	NSUtilities.h	NSCompatibility.h	(NeXT) (EOF11) (NS33)


Compiler

OPENSTEP Enterprise 4.1 Copyright 1996 by NeXT Software, Inc.  All Rights Reserved.

This file contains developer release notes for the Windows and PDO compilers shipped with OPENSTEP Enterprise Release 4.1.

In this release, the compilers are based on the GNU C compiler version 2.7.2.  (The compiler in prerelease 2 for Windows NT was based on the GNU C compiler version 2.6.1.)

New Features

•	Compiling C++ and Objective-C++ programs.  If the name of your source file ends in .cc, .cxx, .cpp, or .C, gcc will attempt to compile your program with the C++ compiler.  Similarly, if the name of your source file ends in .mm or .M, gcc will attempt to compile your program with the Objective-C++ compiler.

•	The Objective-C++ compiler is now much more useable than the one that was included with OPENSTEP for Windows Prerelease 3.

Including Windows Header Files in Objective-C Code

In general, you should be able to include any Windows header file in an Objective-C source module without problems. The System framework contains Microsoft's header files, with slight modifications to make them compatible with gcc. For instance, slight changes have been made for unnamed unions, Microsoft assembly, and so on. If you have problems including any of the Windows header files, try including the file winnt-pdo.h before the Windows header file that is causing problems.

The -Wmost Compiler Flag

The -Wmost compiler flag is equvalent to FSF's -Wall, except that it doesn't turn on -Wparenthesis. -Wmost also suppresses warning messages about inline functions and static constants that are not actually used. This flag is for internal use and is not officially supported. It's definition may change in a future release.

Known Bugs and Limitations

The following bugs or limitations are worth noting  for the GNU C and C++ compilers for this prerelease.

•	Constant strings (both char * and NSString) should be 7-bit only. Unless constant strings are 7-bit, your code will be non-portable as compilers will deal with 8-bit strings in a machine-dependent encoding.

•	Objective-C++ global constructors.  The Objective-C++ compiler sometimes ignores global constructors; they don't always get called.

•	Random name given to executable by default (66861).  If you create an executable and don’t use the -o flag to explicitly tell gcc what to name it, gcc will most likely give it a random name.

•	Using pipes to communicate between compiler passes (61306).  The -pipe flag does not work.

•	-ObjC++ requires -lstdc++ when using C++ streams on PDO (69156). When compiling C++ programs that use C++ streams with gcc on PDO platforms, if you specify the ObjC++ flag you must also specify the -lstdc++ flag. So, for example, a program "foo" that uses cout (and therefore includes iostream.h) would be compiled using gcc as follows:

gcc -ObjC++ foo.cc -lstdc++

•	__declspec(dllexport) __stdcall doesn't work (69194). On Windows NT, functions that are declared as __declspec(dllexport)__stdcall aren't handled properly. This may affect some Windows header files that you include in your programs.

•	The compiler sometimes tries to create a library instead of an executable (69087). This happens on Windows NT when a function is declared as __declspec(dllimport) (perhaps in a header file), but the function is actually defined in the file being compiled. The workaround is to remove the offending __declspec(dllimport).

•	-Wno-precomp flag isn't supported (63746). On Windows NT and on PDO platforms, gcc refuses to do anything when the -Wno-precomp flag is specified. Currently, the precomp option isn't supported.

•	Reporting bugs (68122).  In some cases, when the compiler detects an internal error, it prints a message requesting that you send a bug report to some electronic mail address.  Please disregard this message.  All compiler bugs should be reported to the appropriate channels at NeXT Software.

•	cc -MM Foo.mm produces Foo.mm.o (40491). Compiling a file that has either a .M or .mm extension with -M or -MM will produce a file whose name is the same as the source file with the addition of  .o. The original extension is not stripped off before constructing the name of the .o file.

•	-traditional-cpp acts differently on Mach than on NT or PDO (60175). On Windows NT and on PDO, -traditional-cpp changes the behavior of the preprocessor in the same way that -traditional does. This can result in compilation errors when recompiling an existing NEXTSTEP project on Windows NT.

•	Inconsistent function declarations involving stdcall produce unexpected results (69506). On Windows NT, if a function is forward-declared to be stdcall but not declared to be stdcall in the actual function definition, the compiler will emit code to pop the arguments off the stack, but won't adjust the function name.

•	The linker complains about objects exported as CONSTANT (70212). On Windows NT, if you're building a framework and you create your own DEF file for it, defining exported objects as CONSTANT will produce a warning from the linker advising you to use the word DATA instead. If you substitute the word DATA for CONSTANT in your DEF file, some or all of your objects won't be exported correctly; the linker will be unable to find them. As a workaround, simply leave the declarations CONSTANT and ignore the linker warnings.

•	-static option ycauses linking to fail (70326). The -static and -dynamic compiler flags are meaningless on Windows NT, and shouldn't be used.

•	Programs that use posing sometimes crash (72283). If a program compiled with the Objective-C compiler contains an object that accesses its superclass while posing on a category, it will crash. To workaround this problem, either rewrite your code so that it doesn't do this, or compile the program with the Objective-C++ compiler (to do this, use the -x objective-c++ switch).


Contents

Important Information

Complete Release Notes on NeXTanswers

New Linker

Known Problems in Deployed Systems

Uninstalling OPENSTEP Enterprise

Application Kit

New Features in 4.1

New Features in 4.0

Known Problems in This Release

Changes Prior to 4.0

Changes Since 4.0

Foundation

Notes for Users of Previous Foundation Releases

General Changes in Public Foundation API Methods

General Changes in Public Foundation API Symbols

Method Return Type Changes in Foundation

Changes to Foundation API Declaration Locations

General Comments

Known Problems in This Release

D'OLE

Posix

Bourne Shell

Project Builder

New Features for 4.1

New Features for 4.0

4.1 Conversion Note

Known Problems in This Release-Windows

Known Problems in This Release-Mach and Windows

Interface Builder

New Features

Problems Fixed in This Release

Known Problems in This Release

Compiler

New Features

Known Bugs and Limitations

Debugger

GDB Version

New Features

Known Problems

Keyboard UI

Using Keyboard UI

Hooking Up Keyboard UI in Your Application

Adding Keyboard UI to Your Controls

Preventing Keyboard UI

The API at a Glance

The API in Detail

What about nextText?

Things to Note

Printing

Windows Specific Notes

Known Problems in This Release

Samba

TextEdit

Known Problems in This Release

TrueType Fonts

Known Bugs

Window Server

New Features


D'OLE

Known Problems in This Release

This section documents additional problems that are known to exist in this release of OPENSTEP 4.0.

Reference:	68449

Problem:	Can’t get a proxy for a distributed OLE object using NSDO

Description:	When trying to get a proxy for an OLE object, you may get the following error: “deserializeObjectAt: class ‘NSDistantIDispatchProxy’ not loaded”.

Workaround:	Include nxorb.m (from NextDeveloper/Libraries) in your client Although the D’OLE Developer’s Guide states that nxorb.m is only needed for use with NXConnections, it’s needed in some circumstances for NSConnections as well.


Debugger
The GNU Source-Level Debugger

OPENSTEP Enterprise 4.1  Copyright 1996 by NeXT Computer, Inc.  All Rights Reserved.

This file contains information about GDB, the GNU Debugger.  For more information, see the debugging chapter in the OPENSTEP Development Tools Reference manual. On Mach, you may also refer to the gdb(1) manual page.

Notes Specific to GDB on Mach:

New GDB Version

The GDB debugger in OPENSTEP 4.1 for Mach is based on the version 4.14 release from GNU/FSF.  This brings with it many bug fixes and new features, many of which are mentioned in the debugging chapter of the OPENSTEP Development Tools Reference manual.

New Features

Dynamic Link-Editor Support

GDB supports debugging of dynamic shared libraries (sometimes known as Frameworks or Bundles in the OPENSTEP world).  The presence of dynamic shared libraries has some impact on debugging, which is described in this section.

Debugging symbols for dynamic shared libraries are not present in the program itself.  GDB obtains them when the running program attaches and links to the shared library.  This means that before the program is actually running, GDB has no information about the contents of the dynamic shared libraries that it uses.

Because of this, it is not possible to set ordinary breakpoints in a shared library before that library has been attached.  GDB provides a new command for this purpose, future-break  or fb.  If GDB cannot find the necessary symbols to resolve a future-break command, it defers the breakpoint and attempts to resolve it later, when new symbols from a shared library become available.  Caveat: since the future-break command deals with names and symbols that are as yet unknown to the debugger, it cannot check spelling for you; if you make a spelling mistake, it will never be detected and the breakpoint will never take effect.

There is also an environment variable, DYLD_LIBRARY_PATH, which tells the dynamic link-editor where to search for dynamic libraries.  This variable can be used to cause a library with debugging symbols to be linked, even though the library on the default path has no symbols.  This environment can be set from within GDB by using the setenv command.  In order to affect the program being debugged, it should be set before running the program.

The view interface

In prior releases, GDB supported a GUI interface that used the NEXTSTEP Edit application as a source file viewer (invoked by the view command).   Edit has been replaced by Project Builder as the source file viewer for GDB, and the view command now connects GDB to Project Builder.  You must start Project Builder yourself before giving GDB the view command (GDB will not start Project Builder automatically).  Project Builder has its own user interface for interacting with GDB (see the Project Builder documentation).

Methods with Variable Number of Arguments

GDB now understands the syntax for calling a method with a variable number of arguments (eg. [MyClass myMethod: 1, 2, 3, 4]).

Known Problems

Known Problems with Dynamic Link-Editor Support

It has been observed that GDB sometimes hangs or crashes if you run a program that uses a dynamic shared library (Framework or Bundle), then recompile the dynamic shared library, and run the program again.  If this happens to you, it is recommended that you quit GDB and start a new debugging session every time you rebuild the library.  You can use the .gdbinit file to help re-establish things such as breakpoints that you need in your debugging session.

Interrupting with ^C during Dynamic Symbol Loading

Immediately after you start your program running under GDB, the program will start to load dynamic shared libraries, and GDB will begin reading symbols from these libraries.  If you attempt to interrupt GDB by typing ^C (control-C) during this process, the debugger will be left in a confused internal state from which the only known recovery is to quit the debugger and start over.

Notes Specific to GDB on Windows:

GDB Version

The GDB debugger for OPENSTEP Enterprise is based on  the version 4.15.1 release from GNU.  This brings with it many, if not most of the features of debugging on UNIX and Mach, although there are inevitably some differences.

New Features

Dynamically Loaded Library (DLL) Support

GDB supports debugging of dynamically loaded libraries (DLL’s).  In OPENSTEP Enterprise, Frameworks and Bundles are implemented as DLL’s.   The presence of DLL’s has some impact on debugging, which is described in this section.

Debugging symbols for dynamically loaded libraries are not present in the program itself.  GDB obtains them when the running program attaches and links to the DLL.  This means that before the program is actually running, GDB has no information about the contents of the DLL’s that it uses.

Because of this, it is not possible to set breakpoints in a DLL before the DLL has been attached by the program, or to access data contained in the DLL.   If you need to debug code in a DLL, or set breakpoints on a function or method in a DLL, you should first set a breakpoint on main (or some place in the program after the DLL has been attached but before the code you want to debug has been executed).  Run your program up to that point.  The program will load the DLL, and GDB will gain access to it’s symbols, after which you should be able to set breakpoints in the DLL.  If the DLL was built with the OPENSTEP compiler (gcc), and with -g debugging symbols, you should be able to step into functions or methods in the DLL just like ordinary functions or methods in your program.

Attach and Detach

GDB’s attach command works pretty much as it does on Mach.  The process ID to attach to can be obtained by having the attachee call getpid() and output the result.

NSLog(@Process ID: %d\n", getpid());

However when GDB attaches to an already-running process, GDB will not learn about symbols from DLL’s that the process has already linked to.

The detach command is only partially useful at this time.  detach will let the attached process continue to run, but a parent/child relationship continues to exist between the debugger and the detached process, so that if you then quit the debugger, the detached process will also die.

When you attach to a running process, you will frequently find yourself in a non-debuggable area of code from which you cannot even get a backtrace.  See the section on known problems, “Non-Debuggable Code” below.

Add-Symbol-File

When GDB attaches to a running process, it does not read any symbols from DLL’s that the process has previously linked itself to.  If you need those symbols for debugging, you can explicitly cause GDB to load them by using the add-symbol-file command.  This command takes two arguments: the fully qualified filename of the DLL file, and a base address.  For a DLL that you build, this base address will be the base address at which you linked the DLL plus 0x1000.  Here are the base addresses to give to the add-symbol-file command for the major OPENSTEP DLL’s:

•	0x30001000	System

•	0x31001000	nextpdo

•	0x32011000	Foundation

•	0x34021000	AppKit

•	0x38031000	NeXTApps

•	0x3A041000	DevKit

•	0x3C051000	ProjectBuilder

•	0x3C051000	InterfaceBuilder

•	0x40001000	Message

•	0x42011000	WebObjects

•	0x44021000	EOControl

•	0x46031000	EOAccess

•	0x48041000	EOInterface

•	0x4A051000	Sybase

•	0x4C061000	Oracle

•	0x4E071000	Informix

•	0x50081000	nextorb

•	0x52091000	EOModeler

Command Editing

GDB's command-line history can be accessed by using the up and down arrow keys, or by using the EMACS key bindings (^P and ^N to scroll thru previous commands, ^B, ^A, ^E etc to move around on a line, and so on).   Also, set history expansion on  enables C-shell-like command history within GDB (!!, !print and so on).  As usual, an empty newline repeats the previous command (except where specifically disabled, as with the run command).

Debugging Objective-C: Differences from Mach GDB

The Windows version of GDB is more of a multi-language debugger than the older GDB on Mach (especially the older version of GDB available with previous releases of NEXTSTEP).  This GDB has separate features for many different languages, including Objective-C.  It attempts to guess the source language by looking at the extension of the source file name (“.m” or “.M” for Objective-C).  To find out what GDB’s “current language” is, type show language.  To force the current language to Objective-C, type set language objective-c.

Calling Methods from GDB

To call a method in your program from GDB, use the print, set, or call commands with an argument that looks just like a method call in Objective C, eg.

(gdb) print [myClass showValue: 12]

If the method comes from a Category, you must include the category name, eg.

(gdb) print [myClass(myCategory) showValue: 12]

Listing and Setting Breakpoints on Methods

To refer to a method in a list or break command, you can give the full class and method name, including a ‘+’ or ‘-’ to indicate a class method or instance method.  If there is a category name, you must give that too:

(gdb) list +[myClass init]

(gdb) break -[myClass(myCategory) showValue]

You can also set breakpoints or list a method just by giving a selector.  If the selector is implemented by more than one class, gdb will list the corresponding methods and ask you to choose one or more:

(gdb) break init

[0] cancel

[1] all

[2] -[Change init] at Change.m:20

[3] -[DrawApp init] at DrawApp.m:130

[4] -[Graphic init] at Graphic.m:139

>

You would then enter your choice or choices at the ">" prompt.

Info about Classes and Methods

GDB for Windows now has the info classes and info selectors commands.  These commands accept the same regular expression language as GDB's info type and info function commands (that is,  the Unix style regular expression language).  This is a change from the Mach gdb, where info classes and info selectors accept a slightly different regular expression language.     For instance, to learn about class names beginning with NS (using the "^" character to designate ªbeginning withº):

(gdb) info classes ^NS

 To learn about selectors, you can use the info selectors command.  To find every selector containing the string "withObject:" you could enter:

(gdb) info selector withObject:

To learn about methods, you can use the info function command, which also takes a regular expression.  Since the square bracket characters ‘[‘ and ‘]’ are significant in regular expressions, you can quote them with a backward slash to prevent their being treated as special characters.  To list all the methods of a class, you might say:

(gdb) info function \[MyClass

To list all the methods whose selector ends with “count:”, you might say:

(gdb) info function count:\]

If you want to know about a specific method of a specific class, but you are not sure if it belongs to a category, you could use the “.*” wildcard sequence to stand for “any number of any characters”:

(gdb) info function MyClass.*mySelector:

Debugging Threads on Windows

The GDB for Windows is thread-aware.  If you are debugging a multi-threaded program, you can use the info threads command to see a list of the currently active threads.  Use the thread command to switch to one of the threads listed by info threads, giving it the number of the thread you want to debug (a small integer such as 1 or 2, not the thread ID).

When you switch threads, you will frequently find yourself in a non-debuggable area of code from which you cannot even get a backtrace.  See the section on known problems, “Non-Debuggable Code” below.

Known Problems

Non-Debuggable Code

When you interrupt a program with ^C, attach to a running program, or switch threads in a running program, sometimes the program will be in the middle of executing Windows code that cannot be debugged.  Often GDB cannot even give you a backtrace, because Windows has done something with the program stack.  When this happens, if you don’t want to simply let the program continue (e.g., you need to know exactly how you got to where you are), you can use the stepi command to step by single machine instructions until the Windows code cleans up the stack and returns, at which time you will suddenly be able to see symbols and backtraces again.  GDB will notify you when you have returned to a symbolic region (e.g., a function or a method) that it knows about.  Usually this does not take too long; on the order of a few dozen instruction steps.

Breaking on WINAPI Functions

Certain functions in the Windows programming environment are declared as WINAPI, STDCALL, and so on. These are usually functions in the Microsoft libraries, but sometimes you may have to write such functions. These functions have a special name-mangling scheme: their names become suffixed with the size in bytes of their argument list, preceeded by an "@" (for example, WinMain becomes WinMain@16). GDB does not understand this mangling scheme. If you need to, you can discover the mangled name of such a function and use that to set a breakpoint. Since such names are not legal identifiers in GDB's syntax, you must quote them.

(gdb) info function WinMain

All functions matchin regular expression "WinMain":

void WinMain@16(long, long, long, long);

(gdb) break 'WinMain@16'	// note quotes

You cannot set a breakpoint using just the method name.

Problems with underscores

gdb doesn’t correctly handle methods for which either the class, the category, or the selector has underscores in the name (except that leading underscores in the selector will probably get by).


Foundation
Foundation Framework

OPENSTEP Enterprise Release 4.1  Copyright ©1996 by NeXT Software, Inc.  All Rights Reserved.

The Foundation Framework is a library of Objective-C classes providing the infrastructure for non-user-interface object-based applications and other user-interface- and non-user-interface-based frameworks. The OPENSTEP Foundation is compliant with the Foundation portion of the OpenStep specification, and enriches OpenStep with a few extensions.

Within the Foundation are basic classes used by any Objective-C program: collection classes, Distributed Objects, persistence frameworks, Unicode and internationalization support, the foundations of event-driven programming, and facilities to insulate code from the underlying operating system.

These release notes are divided in four main sections:

•	Comments on compatibility with OPENSTEP 4.0

•	Notes specific to developers who have used previous releases of Foundation

•	General comments on often-encountered problem areas and interesting things

•	Known problems in this release

In the document below, "4.0" and "OPENSTEP 4.0" refer to all products that shipped with the 4.0 Foundation: OPENSTEP 4.0, D'OLE 4.0, and PDO 4.0 for HP-UXTM and SolarisTM.  "4.1" and "OPENSTEP 4.1" refers to OPENSTEP 4.1 for Mach and OPENSTEP Enterprise 4.1.

Changes and Compatibility Between OPENSTEP 4.0 and 4.1

There have been a number of changes to Foundation since the shipment of OPENSTEP 4.0, both defect fixes and a few method/function additions. These are enumerated in the section below.

Note that if your application uses API which was added between 4.0 and 4.1, your application might not run under 4.0. (If you do not want to deploy your application on 4.0, then this is not an issue.) You can catch some of the potential problems by defining the macro STRICT_40 at compile time. This #define is similar to STRICT_OPENSTEP and is used in the Application and Foundation Kits to mark new API. Similarly, if you rely (perhaps unintentionally) on a bug fixed in 4.1, your application may not function correctly under 4.0. Make sure you test on your intended deployment platform.

A number of performance improvements were also made to Foundation between 4.0 and 4.1. Customers developing on 4.1 may find performance to be significantly worse in some cases when a project is deployed on 4.0.

Here are the feature and semantic changes to Foundation in 4.1. A list of most of the bugs fixed follows. Note that a fixed bug may also represent a semantic change from the point of view of the application.

•	Some methods in 4.0 were not surrounded by #if !defined(STRICT_OPENSTEP) when they weren't, in fact, in OpenStep.

CLASS	HEADER	METHOD

NSCharacterSet	NSCharacterSet.h	+characterSetWithContentsOfFile:

NSConnection	NSConnection.h	-connection:shouldMakeNewConnection:

NSArray	NSPathUtilities.h	-pathsMatchingExtensions:

•	These methods have been made public in 4.1.  They were not public in 4.0, but existed in the 4.0 Foundation binary so there are no compatibility issues in using them.  They are not in OpenStep, however.

CLASS	HEADER	METHOD

NSArray	NSArray.h	-makeObjectsPerformSelector:

NSArray	NSArray.h	-makeObjectsPerformSelector:withObject:

NSSet	NSSet.h	-makeObjectsPerformSelector:

NSSet	NSSet.h	-makeObjectsPerformSelector:withObject:

•	These methods and functions were added to Foundation in 4.1 and are not present in the 4.0 Foundation binary. Applications which do not take some precaution in using them will not run correctly on OPENSTEP 4.0. These methods and functions are also not in OpenStep.

CLASS	HEADER	METHOD

NSBundle	NSBundle.h	+allBundles

NSBundle	NSBundle.h	+allFrameworks

NSFileHandle	NSFileHandle.h	+fileHandleWithNullDevice

NSFileHandle	NSFileHandle.h	-initWithNativeHandle:closeOnDealloc:

NSFileHandle	NSFileHandle.h	-initWithFileDescriptor:closeOnDealloc:

NSObject	NSObject.h	+instanceMethodSignatureForSelector:

FUNCTION	HEADER

NSFrameAddress	NSDebug.h

NSReturnAddress	NSDebug.h

NSCountFrames	NSDebug.h

•	The NSUserDefaults' _search instance variable changed type from NSMutableArray * to NSArray *.  This shouldn't be a problem, as applications should not be referencing the instance variables of NSUserDefaults directly.

•	NSArray -componentsJoinedByString: sends -description to each of the array's objects and concatenates the results of that together, rather than using the objects directly. This means that this method will now operate on arrays which are composed of objects that are not NSStrings.

•	The number-formatting sequences for NSCalendarDates (%d, %e, %H, %I, %j, %m, %M, %S, %w, %y, %Y) during the construction of a description can now contain formatting flags between the `%' and format code, to the extent that the string methods +stringWithFormat:, -appendFormat:, etc. understand them. Format flags are not understood during parsing from a format, however. Note that per 70220 [below], NSDateFormatters use their format string both to display the date and to parse a date from a string (which the user entered in a text field, for example), so this modest extension should not be used in the format string of NSDateFormatters. Setting the date formatter to allow natural language may obviate the problem [but may be undesirable for application reasons].

•	The default uncaught exception handler now includes the name of the exception and a "backtrace" in the logged message it generates. The backtrace consists only of the return addresses on the execution stack. Additionally, on WindowsTM, an application exception is raised (via RaiseException()), which can be handled by a debugger.

•	The byref keyword is no longer ignored when transporting NSCalendarDates (as a parameter or return value) over D.O. Thus, a parameter or return value which is declared with byref now results in a proxy to the calendar date instance, rather than a real calendar date instance. By default, NSCalendarDates still go over the wire bycopy. NSDates always go over the wire bycopy.

•	The NSBundle class method +pathForResource:ofType:inDirectory: now first searches a Resources subdirectory of the third parameter if such a subdirectory exists. It used to examine only the directory specified in the third parameter.

•	NSDate's -dateWithCalendarFormat:timeZone: and NSCalendarDate's -setCalendarFormat: now have the documented behavior with respect to the first parameter being nil. In 4.0, they would simply set the format to nil, which resulted in the various -description methods returning an empty string.

•	NSString -stringByAppendingPathComponent: would refuse to append a component that began with `~' in 4.0. This was to prevent the accidental concatenation of "~username" onto a path, but `~' is a valid (but perhaps uncommon) first character of a file name, and that behavior was of marginal benefit, so it was eliminated.

•	A missing strings file has been added to the Foundation, so in 4.1 error strings returned from the formatters (NSDateFormatter and NSNumberFormatter) will be localized.

This section contains many of the corrected defects to Foundation between OPENSTEP 4.0 and 4.1. Any of these present potential backwards-deployment issues.

_______________________________________________________________________________________

Reference:	48447 [FIXED]

Platforms:	HP-UXTM

Problem:	D.O. crashed sending some structures containing doubles

Description:	D.O. would crash when attempting to send a parameter or return value which was a structure larger than 8 bytes and contained a double field.

_______________________________________________________________________________________

Reference:	50670 [FIXED]

Platforms:	All

Problem:	NSMethodSignature's -getArgumentTypeAtIndex: and -methodReturnType returned too much information

Description:	These NSMethodSignature methods returned a string which contained the type descriptors for the requested argument plus all the type descriptors for the arguments following.

_______________________________________________________________________________________

Reference:	55579 [FIXED]

Platforms:	All

Problem:	Collections that contain themselves didn't unarchive well

Description:	Unarchiving an object graph with a collection which contained itself, or contained an object which archived a reference to the collection, might have caused a program either to crash immediately when the archiving system attempted to retain it, or to crash later when a freed object was sent a message. The problem here was that the collection got retained when the recursive reference was unarchived (which is normal) before it had completed its initialization in -initWithCoder:, which can be a problem for objects which keep track of their own retain count (as the collection classes do).

_______________________________________________________________________________________

Reference:	62019 [FIXED]

Platforms:	All

Problem:	Character tables were not Unicode 2.0 compliant

Description:	The tables used by NSCharacterSet and shipped as resources with the 4.0 Foundation were compliant with Unicode 1.1. The Unicode 2.0 tables were not yet available at the time of release. The tables in 4.1 are Unicode 2.0 compliant.

_______________________________________________________________________________________

Reference:	67201 [FIXED]

Platforms:	Windows NTTM

Problem:	Files mapped with -initWithContentsOfMappedFile: could not be removed

Description:	On WindowsTM, a file that a process has mapped cannot be removed; this is a feature of the operating system. However, even after an NSData initialized with -initWithContentsOfMappedFile: was deallocated, a program may not have been able to immediately remove the file. The problem was that an internal file-mapping object was autoreleased at the time the data was initialized.

_____________________________________________________________________________________________________

Reference:	68041 [FIXED]

Platforms:	All

Problem:	NSString's -stringByStandardizingPath raised an exception in certain circumstances

Description:	When passed an absolute path that ended with .., NSString's -stringByStandardizingPath method raised an exception.

_____________________________________________________________________________________________________

Reference:	68223 [FIXED]

Platforms:	All

Problem:	-stringByAbbreviatingWithTildeInPath sometimes incorrectly abbreviated

Description:	If the first part of a path matched the user's home directory, '~' would be substituted for that prefix, regardless of whether or not the partial component at the end of the prefix was a complete component or not. For example,

[@"/me-local/foo/bar" stringByAbbreviatingWithTildeInPath] => @"~/local/foo/bar"

if the example was executed by the "me" user whose account is "/me".

_____________________________________________________________________________________________________

Reference:	68447, 68781 [FIXED]

Platforms:	All

Problem:	D.O. and archiving type signature checks didn't take structure tags into account

Description:	The NeXT compiler does not include structure names in type encoding strings produced from typedefs of structures (for example, @encode(NSRange); instead, the structure tag is given as "?". This is a bug in the compiler, but one that cannot be fixed for backwards compatibility reasons. To achieve compatibility with SunSoft's compiler (which correctly emits all structure tags), a "?" as a structure tag was made to act as a "wildcard", matching anything. This is unlikely to affect user applications, but developers who construct their own type encoding strings should note this, as 4.1 will be more permissive than OPENSTEP 4.0 and NEXTSTEP was, a possible backwards-deployment issue.

_____________________________________________________________________________________________________

Reference:	68790 [FIXED]

Platforms:	All

Problem:	NSConnectionDidDieNotification not sent in some circumstances

Description:	If a client attempted to send a message to a server which had died before the client had processed the port death notification (which can take quite a while to arrive), an NSInvalidSendPortException would be raised rather than the NSConnectionDidDieNotification being sent.

_____________________________________________________________________________________________________

Reference:	69174 [FIXED]

Platforms:	All

Problem:	Lossy conversion to NSASCIIStringEncoding more lossy than intended

Description:	When NSString finds a non-ASCII character during lossy conversion to NSASCIIStringEncoding, NSString converts it to an underscore.  In 4.0, when NSString found a non-ASCII character during such conversion, NSString converted the character and all the remaining characters in the string to underscores, even if they were ASCII.

_____________________________________________________________________________________________________

Reference:	69321 [FIXED]

Platforms:	Windows NTTM

Problem:	D.O. leaked every messaged object

Description:	On NT, every object that was messaged via D.O. was leaked due to an extraneous retain.

_____________________________________________________________________________________________________

Reference:	69471 [FIXED]

Platforms:	All

Problem:	NSPipe leaked file descriptors

Description:	NSPipes and NSFileHandles do not take ownership of the file descriptor by default. If such an object was released without an explicit close of the descriptors, the descriptors were not recovered. The new methods -initWithNativeHandle:closeOnDealloc: and -initWithFileDescriptor:closeOnDealloc: allow for the creation of file handles which own the descriptors.

_____________________________________________________________________________________________________

Reference:	69699 [FIXED]

Platforms:	Windows NTTM

Problem:	NSLog() doesn't send duplicate output

Description:	When running under a debugger, NSLog() would send output to the debugger and the event viewer and the standard error handle (which is often not defined for applications, but is for tools and other console-oriented processes). Now when a process is running under a debugger, NSLog() only sends its output to the debugger. The normal behavior of NSLog() is to send the string to the event viewer and standard error.

_____________________________________________________________________________________________________

Reference:	69926 [FIXED]

Platforms:	All

Problem:	NSNotificationCenter sometimes sent duplicate notifications

Description:	In some situations, NSNotificationCenter sent observers two (or more) copies of a single notification. This only happened to observers which were registered to receive any notification name (perhaps with restriction to particular object).

_____________________________________________________________________________________________________

Reference:	70028 [FIXED]

Platforms:	All

Problem:	Fault objects could not forward messages

Description:	EOFault would cause an unrecognized selector exception rather than causing -forwardInvocation: to be invoked on the faulted object when the fault was sent a message that the faulted object did not understand (in other words, an object faulted would not get an opportunity for forward an unknown selector).  Faulted objects which wish to forward a message which may cause them to be faulted should override the new NSObject class method +instanceMethodSignatureForSelector: to return an NSMethodSignature for the eventual target of the forwarded message.  See the subsection Forwarding Messages in OpenStep in the General Comments section below.

_____________________________________________________________________________________________________

Reference:	70220 [FIXED]

Platforms:	All

Problem:	NSDateFormatter didn't convert input in the same way as output

Description:	NSDateFormatters did not use the output format string to parse user-entered strings, so in most cases strings could not be entered in the same format in which they were displayed. Now a date displayed with "%m/%y" (for example) can also be entered in that format.

_____________________________________________________________________________________________________

Reference:	70323 [FIXED]

Platforms:	All

Problem:	NSDateFormatter does not allow empty string

Description:	Once the user had begun typing in a text field that had a date formatter, the user could not leave the field without entering a valid date; in particular, the user could not leave the field empty. Empty is now valid, and the date formatter produces nil for an empty string in its -getObjectValue:forString:errorDescription: method.

_____________________________________________________________________________________________________

Reference:	70334 [FIXED]

Platforms:	All

Problem:	Time zones generated with wrong offset

Description:	The +timeZoneForSecondsFromGMT: was incorrectly using the negative of the supplied parameter to generate the returned time zone. This also affected the parsing of dates where the time zone was specified with a raw GMT offset, like "-0700", but not where the time zone was a name, such as "GMT-0800" or "PST".

_____________________________________________________________________________________________________

Reference:	70440 [FIXED]

Platforms:	All

Problem:	NSRunLoop incorrectly computed whether or not there was work to be done

Description:	In some situations using background monitoring of file handles, NSRunLoop would not take into account the file handles in deciding whether or not it had any more input sources.

_____________________________________________________________________________________________________

Reference:	70580 [FIXED]

Platforms:	All

Problem:	NSNumber hashed long long numbers incorrectly

Description:	NSNumber hashed long longs by simply casting the value to (unsigned int). This caused some equal numbers to have different hash values, breaking the hash–isEqual: invariant.

_____________________________________________________________________________________________________

Reference:	70612, 70718 [FIXED]

Platforms:	All

Problem:	NSDecimalNumber inaccuracies

Description:	An error in the text from which the division algorithm was taken caused inaccuracies in the less significant end of the result of -decimalNumberByDividingBy:withBehavior: (in the fractional part, the ones, and tens digits, depending on the size of the numbers). Also, digits of precision were being lost during initialization on the less significant end of the number, and the decimal point was being incorrectly positioned in the result of -decimalNumberBySubtracting:withBehavior:.

_____________________________________________________________________________________________________

Reference:	71006 [FIXED]

Platforms:	Windows NTTM

Problem:	NSFullUserName() always returned nil

Description:	The NETAPI32 DLL was not being loaded when needed. Note that this DLL is not implemented on Windows 95TM, so this function will always return nil on Windows 95TM. Applications should be prepared for a nil return value.

_____________________________________________________________________________________________________

Reference:	71288 [FIXED]

Platforms:	All

Problem:	Problem popping initial autorelease pool

Description:	A program could crash if it repeatedly created and released the top autorelease pool.

__________________________________________________________________________________________________________________________________________________________

Notes for Users of Foundation Prior to OPENSTEP 4.0

There were several releases of the Foundation Framework prior to OPENSTEP 4.0. Foundation shipped with:

•	NEXTSTEP 3.3

•	Enterprise Objects Framework 1.0

•	Enterprise Objects Framework 1.1

•	Portable Distributed Objects 3.0

•	D'OLE 3.5

•	OPENSTEP 4.0 Prerelease 1

•	OPENSTEP 4.0 Prerelease 2

•	PDO 4.0 Prerelease 1

This section describes only API changes that have been made between those releases and OPENSTEP 4.0. For changes since OPENSTEP 4.0, see the section above titled Changes and Compatibility Between OPENSTEP 4.0 and 4.1. The semantics of many things have changed, but most not in a way that will affect programs (NEXTSTEP 3.3 Foundation-based programs and EOF 1.1 programs, being older, are more likely to be affected). Unfortunately, at this time there is no single source for information about such changes±refer to the Foundation Framework Reference and specific class specifications for the current behavior. This document does not describe extensions to Foundation provided by various NeXT products (for example, WebObjects or EOF).

Foundation is now packaged as a ProjectBuilder framework, and resides in /NextLibrary/Frameworks/Foundation.framework. The headers can be found in /NextLibrary/Frameworks/Foundation.framework/Headers.

All programs based upon previous version of Foundation should be recompiled (even if no conversion is necessary) to function with this version of Foundation. Compiling against the old static "shlib" (the shared library shipped with NEXTSTEP 3.3, EOF 1.1, and PDO 3.0, and used by WebObjects) is not supported in OPENSTEP 4.0 (without EOF 1.1 installed).

This section is divided into a subsection for each of the previous releases of the Foundation Framework. There are no specific notes for Enterprise Objects Framework 1.0, Portable Distributed Objects 3.0, or WebObjects 1.0 developers; please refer to the section for Enterprise Objects Framework 1.1 developers. The API of the Foundation shipped with Portable Distributed Objects 3.0 and WebObjects 1.0 was identical to that in Enterprise Objects Framework 1.1 (other than extensions made by those products).

Notes Specific to NEXTSTEP 3.3 Developers

Items in the tables below (in the section titled Tables Showing Foundation API Changes) that are marked with "(NS33)" are changes made to Foundation between NEXTSTEP 3.3 and OPENSTEP 4.0. Also see the general comments in the section Notes Specific to Enterprise Objects Framework 1.1 Developers below. NEXTSTEP 3.3 developers should note the following additions to those comments:

•	The header NXAutoreleaseConnection.h was not in NEXTSTEP 3.3. Comments referring to this header do not apply to NEXTSTEP 3.3 developers.

•	Two additional headers, NSLock.h and NSThread.h, were not in NEXTSTEP 3.3, but are in OPENSTEP 4.0.

Notes Specific to Enterprise Objects Framework 1.1 Developers

Items in the tables below (in the section titled Tables Showing Foundation API Changes) marked with "(EOF11)" are changes made to Foundation between EOF 1.1 and OPENSTEP 4.0.

Some additional changes are not contained in the tables or are of particular note:

•	Headers are now imported as <Foundation/...>, rather than <foundation/...>.

•	The structure of imports has changed. The Foundation headers import all ANSI C headers they need and some of the Objective-C interfaces, but none of the operating system interfaces. The set of headers imported by each header has also changed in many places. Where a project was getting a header imported "for free" before, it may now need to import additional headers in order to compile.

•	The header NXAutoreleaseConnection.h has been removed. Its contents have been moved to NSCompatibility.h.

•	A Foundation.h header has been added, which includes the 15 ANSI C headers, and all Foundation headers except NSCompatibility.h and NSDebug.h.

•	The top-level NSAutoreleasePool is no longer created for automatically±a program needs to create it itself. See the Foundation Framework Reference and the NSAutoreleasePool class specification for more information on creating autorelease pools.

•	NSDictionary no longer constrains keys to be instances of NSString. Any object that meaningfully responds to -hash, -isEqual:, and -copyWithZone: can be an NSDictionary key.

•	The name of the exception variable in the NS_HANDLER...NS_ENDHANDLER region has been changed from exception to localException.

•	Some methods that are not in OpenStep, and were not guarded with #if !defined(STRICT_OPENSTEP), now are guarded.

•	NSObject no longer conforms to the NSCoding protocol. Instead, the classes that can be archived or distributed, and their subclasses, conform to the protocol explicitly.

•	NSBundle's and NSNotificationCenter's instance variables are now declared @private.

•	The type of the parameter to NSBundle's +bundleForClass: method changed from id to Class.

•	The type of the parameter to NSValue's +valueWithPointer: method changed from void * to const void *.

•	The typedef NSStringEncoding in NSString.h has changed from a typedef'd enumeration to a typedef'd scalar.

•	The value of the enumeration constant NSUnicodeStringEncoding in NSString.h has changed from 0 to 10.

•	The location of the resources has changed, and can now be found in the Foundation framework directory. If, in a previous release of the Foundation, your application was poking around in the Foundation resources, you should carefully consider why you were doing so, and stop doing it if possible.

•	The declarations of the NSAutoreleasePool debugging methods and aids have moved from NSAutoreleasePool.h to NSDebug.h. Some of the methods are destined for obsolescence, and some new methods have been added.

•	The header NSObjCRuntime.h now imports the headers objc/zone.h and stdarg.h.

•	Many declarations and definitions were removed from the header NSUtilities.h and moved elsewhere, but all the previous material is still defined by importing NSUtilities.h. The headers to which things were moved are NSEnumerator.h, NSObjCRuntime.h, NSDictionary.h, and NSString.h.

Finally, the Foundation shipped with EOF 1.1 did not contain much of the functionality of the Foundation in OPENSTEP 4.0. These headers, and all the API they declare, were added between EOF 1.1 and OPENSTEP 4.0:

NSAttributedString.h	NSFormatter.h	NSPPL.h

NSByteOrder.h	NSGeometry.h	NSProcessInfo.h

NSCompatibility.h	NSHashTable.h	NSProtocolChecker.h

NSConnection.h	NSHost.h	NSProxy.h

NSDateFormatter.h	NSInvocation.h	NSRunLoop.h

NSDebug.h	NSMapTable.h	NSSerialization.h

NSDecimal.h	NSMethodSignature.h	NSSet.h

NSDecimalNumber.h	NSNotificationQueue.h	NSTask.h

NSDistantObject.h	NSNumberFormatter.h	NSTimer.h

NSDistributedLock.h	NSPort.h_NSUserDefaults.h

NSEnumerator.h	NSPortCoder.h

NSFileHandle.h	NSPortMessage.h

NSFileManager.h	NSPortNameServer.h

The API added by these headers is not included in the tables below.

Notes Specific to D'OLE 3.5 Developers

Items in the tables below (in the section titled Tables Showing Foundation API Changes) marked with "(40PR1)" are changes made to Foundation between OPENSTEP 4.0 PR1 and OPENSTEP 4.0. This symbol also marks changes that apply to D'OLE 3.5 developers, with the exceptions noted below. See also the general comments in the section Notes Specific to OPENSTEP 4.0 PR1 Developers below.

The following are exceptions to the changes noted between OPENSTEP 4.0 PR1 and OPENSTEP 4.0, for D'OLE 3.5 developers:

•	The header NSPPL.h isn't in D'OLE 3.5, but is in OPENSTEP 4.0. API changes referring to this header do not apply to D'OLE 3.5 developers.

•	These methods were in D'OLE 3.5, but not in OPENSTEP 4.0 PR1:

CLASS	HEADER	METHOD

NSString	NSPathUtilities.h	+pathWithComponents:	(+NeXT) (40PR1)

NSString	NSPathUtilities.h	-isAbsolutePath	(+NeXT) (40PR1)

NSString	NSPathUtilities.h	-pathComponents	(+NeXT) (40PR1)

Notes Specific to OPENSTEP 4.0 PR1 Developers

Items in the tables below (in the section titled Tables Showing Foundation API Changes) marked with "(40PR1)" are changes made to Foundation between OPENSTEP 4.0 PR1 and OPENSTEP 4.0.

Some additional changes are not contained in the tables or are of particular note:

•	All applications, frameworks, libraries, bundles, tools, etc. compiled in PR1 should be recompiled.

•	The header file NSAccount.h has been removed from Foundation. This header was NeXT-specific.

•	The header file NSByteStore.h has been removed from Foundation (both from OpenStep and from NeXT's implementation).

•	The import of the header NSDebug.h has been removed from Foundation.h; however, it still exists. This header contains features intended for debugging, but not for general use.

•	Foundation.h now imports the 15 ANSI C headers (assert.h, ctype.h, errno.h, float.h, limits.h, locale.h, math.h, setjmp.h, signal.h, stdarg.h, stddef.h, stdio.h, stdlib.h, string.h, time.h) as a convenience.

•	The header file NSObjCRuntime.h imported six obsolete headers (ansi/ansi.h, objc/typedstream.h, objc/objc-class.h, architecture/byte_order.h, objc/hashtable.h, streams/streams.h) in PR1. It no longer does so. This change may mean that some of these headers may need to be explicitly imported for code written on OPENSTEP 4.0 PR1 to recompile.

•	A STRICT_OPENSTEP preprocessor guard now surrounds all API in the headers NSDecimal.h and NSDecimalNumber.h.

•	The macro FOUNDATION_EXPORT is now always explicitly defined on WindowsTM (that is, it cannot be predefined with the -D compiler option) in NSObjCRuntime.h.

•	A new header and related functionality, NSTask.h, was added.

•	See also changes noted in the section Notes Specific to OPENSTEP 4.0 PR2 Developers. All changes listed apply to OPENSTEP 4.0 PR1 developers.

Notes Specific to OPENSTEP 4.0 PR2 Developers

Items in the tables below (in the section titled Tables Showing Foundation API Changes) marked with "(40PR2)" are changes made to Foundation between OPENSTEP 4.0 PR2 and OPENSTEP 4.0.

Some additional changes are not contained in the tables or are of particular note. This list of changes applies to both OPENSTEP 4.0 PR1 and PR2 developers:

•	The size of NSPort and NSRunLoop instances has changed. The NSPort class has become abstract and no longer has any instance variables. Applications, tools, frameworks, bundles, or libraries with subclasses of these two classes must be recompiled.

•	The header file NSPosixFileDescriptor.h has been removed from Foundation. This header was NeXT-specific. The header NSFileHandle.h provides portable replacement functionality.

•	A few new headers have been added. The API in these headers is not included in the tables below:

NSAttributedString.h	NSFormatter.h

NSDateFormatter.h	NSNumberFormatter.h

NSEnumerator.h	NSProtocolChecker.h

NSFileHandle.h

•	Many declarations and definitions were removed from the header NSUtilities.h and moved elsewhere, but all the previous material is still defined by importing NSUtilities.h. The headers to which things were moved are NSEnumerator.h, NSObjCRuntime.h, NSDictionary.h, and NSString.h.

•	The header NSObjCRuntime.h now imports the headers objc/zone.h and stdarg.h.

•	The type of the parameter to NSTask's -setStandardInput:, -setStandardOutput:, and -setStandardError: methods has changed from NSPosixFileDescriptor * to id.

•	The declarations of the NSAutoreleasePool debugging methods and aids have moved from NSAutoreleasePool.h to NSDebug.h. Some of the methods are destined for obsolescence, and some new methods have been added.

•	These methods are no longer declared on WindowsTM platforms:

CLASS	HEADER	METHOD

NSDictionary	NSFileManager.h	-fileSystemFileNumber

NSDictionary	NSFileManager.h	-fileSystemNumber

NSFileManager	NSFileManager.h	-createSymbolicLinkAtPath:pathContent:

NSFileManager	NSFileManager.h	-pathContentOfSymbolicLinkAtPath:

Although they are still declared on WindowsTM, an application should not use the string constants NSFileSystemNumber or NSFileSystemFileNumber, either.

Notes Specific to PDO 4.0 PR1 Developers

Items in the tables below (in the section titled Tables Showing Foundation API Changes) marked with "(P40PR1)" are changes made to Foundation between PDO 4.0 PR1 and OPENSTEP 4.0 and PDO 4.0.

Some additional changes are not contained in the tables or are of particular note:

•	The Foundation is now shipped as a shared library in PDO 4.0 for SolarisTM. All applications, tools, frameworks, bundles, libraries, etc. should be recompiled to take advantage of this.

•	The size of NSPort and NSRunLoop instances has changed. The NSPort class has become abstract and no longer has any instance variables. Applications, tools, frameworks, bundles, or libraries with subclasses of these two classes must be recompiled.

•	The header file NSPosixFileDescriptor.h has been removed from Foundation. This header was NeXT-specific. The header NSFileHandle.h provides portable replacement functionality.

•	A few new headers have been added. The API in these headers is not included in the tables below:

NSAttributedString.h	NSFormatter.h

NSDateFormatter.h	NSNumberFormatter.h

NSFileHandle.h	NSProtocolChecker.h

•	The type of the parameter to NSTask's -setStandardInput:, -setStandardOutput:, and -setStandardError: methods has changed from NSPosixFileDescriptor * to id.

Tables Showing Foundation API Changes

There are four tables that list the API changes between previous versions of Foundation and the version of Foundation in OPENSTEP 4.0. The first table lists general changes to API elements (classes, macros, functions, constants, and so on) except methods, the second table lists the changes to the set of methods offered by the classes in Foundation, the third table lists changes to the return values of methods (for methods that didn't change name, which are listed in the second table), and the fourth table lists changes in the location of declarations. Other miscellaneous changes that weren't described well in table format are given in the sections above.

Changes are noted from the perspective of a developer who used a previous release looking to port their Foundation-based code to OPENSTEP 4.0 (and not through any intermediate releases). For instance, changes that are marked as having been made between OPENSTEP 4.0 PR1 and PR2 do not necessarily apply to NEXTSTEP 3.3 developers (for example, an API might have been added for OPENSTEP 4.0 PR1, but removed for OPENSTEP 4.0 PR2).

The rows in the tables are marked with various symbols in the rightmost column. One set of symbols describes between which releases and OPENSTEP 4.0 the change was made:

SYMBOL	MEANING

(NS33)	Change occurred between NEXTSTEP 3.3 and OPENSTEP 4.0

(EOF11)	Change occurred between EOF 1.1 and OPENSTEP 4.0

(40PR1)	Change occurred between OPENSTEP 4.0 PR1 and OPENSTEP 4.0

(40PR2)	Change occurred between OPENSTEP 4.0 PR2 and OPENSTEP 4.0

The other set of symbols indicate how the API changed. Both NeXT's implementation of Foundation, and the OpenStep specification (since version 1.0 was published) have changed. These symbols attempt to describe what has happened:

SYMBOL	MEANING

(OpenStep,NeXT)	Generically, a change that did not add or remove API, but affects OpenStep and NeXT's implementation

(OpenStep)	Generically, a change that did not add or remove API and affects OpenStep, but not NeXT's implementation

(NeXT)	Generically, a change that did not add or remove API and affects NeXT's implementation, but not OpenStep

(+OpenStep,+NeXT)	Was in neither OpenStep nor NeXT's implementation, now in both

(+OpenStep,NeXT)	Was in NeXT's implementation only, now also in OpenStep

(+OpenStep,-NeXT)	Was in NeXT's implementation only, now in OpenStep only

(OpenStep,+NeXT)	Was in OpenStep only, now also in NeXT's implementation

(OpenStep,-NeXT)	Was in both, now in OpenStep only

(-OpenStep,+NeXT)	Was in OpenStep only, now in NeXT's implementation only

(-OpenStep,NeXT)	Was in both, now in NeXT's implementation only

(-OpenStep,-NeXT)	Was in both, now in neither

(+OpenStep)	Was in neither OpenStep nor NeXT's implementation, now in OpenStep only

(-OpenStep)	Was in OpenStep only, now in neither

(+NeXT)	Was in neither OpenStep nor NeXT's implementation, now in NeXT's implementation only

(-NeXT)	Was in NeXT's implementation only, now in neither

Occasionally, to the right of the rightmost column is a note for removed API which names the replacement.

The Tables

Click here to see a listing of changes made to public API symbols.

Click here to see a listing of changes made to public API methods.

Click here to see a listing of changes made to method return types.

Click here to see a listing of changes made to the location of API declarations.

General Comments

Foundation Examples

There are several Foundation examples in /NextDeveloper/Examples/Foundation.

Various examples illustrating the use of Distributed OLE and the NeXT ORB can be found on NeXTanswers. NeXTanswers can be accessed through NeXT's Web page, at http://www.next.com.

I/O Functionality

Two new Foundation classes, NSFileHandle and NSPipe, provide objects that represent open files or communications channels and support basic I/O operations. They make it easy for developers to write code that is directly portable to other platforms. The interfaces for these classes are declared in NSFileHandle.h. These classes replace the NSPosixFileDescriptor and NSPosixPipeDescriptor classes made available in OPENSTEP 4.0 prereleases. The differences from the predecessor classes for the most part involve naming and a refinement of semantics.

Archiving

NSUnarchivers own the objects that they decode. When an NSUnarchiver is deallocated, so are the objects that it has decoded, unless they have been retained. The following code, for example, will probably result in a decoded object being used after being freed:

NSAutoreleasePool *pool = [[NSAutoreleasePool allocWithZone:NULL] init];

NSUnarchiver *unarchiver = [[NSUnarchiver allocWithZone:NULL] initForReadingWithData:myData];

id object = [unarchiver decodeObject];

[unarchiver release];

[pool release];

... use or return object here ...

object should be retained before the NSUnarchiver is released, and probably also autoreleased if object is returned from the function or method. An exception to this are the -decodeValueOfObjCType:at: and -decodeValueOfObjCTypes:... methods. Objects "returned" from these two methods, like those returned from +allocWithZone: and -copyWithZone:, are not autoreleased, and must be explicitly released.

User Defaults

Foundation contains API (NSUserDefaults) which replaces the old defaults database suite of functions. User defaults with 4.0 applications are stored differently and in a different place than 3.3 user defaults. There is a new command-line utility called defaults that allows you to manipulate the new-style defaults just as dread, dwrite, and dremove allowed you to manipulate old-style defaults.

On Windows NTTM, defaults are stored in the WindowsTM registry. There is a program shipped with Windows NTTM, REGEDT32, for viewing and editing registry entries. NSUserDefaults stores its domains and their key-value pairs under the entry HKEY_CURRENT_USER\Software\NeXT\UserDefaults. The values are currently stored as strings in the property list format.

The command /usr/bin/defconvert, in OPENSTEP 4.0 for MACH, can be used to convert a user's 3.3 defaults database to 4.0-style defaults±simply run it from the command line with no parameters. This program converts all old-style defaults, even those of non-OpenStep applications, adding them to the user's new-style database. Since NEXSTEP 3.3 applications may not use the same default names after conversion to OPENSTEP 4.0, and 3.3 applications do not use the new defaults database, and increasing the size of the defaults database increases the amount of memory needed by each OpenStep application, converting an old defaults database to the new style usually provides little utility.

Errors in ASCII Property Lists

When a method like NSDictionary's +dictionaryWithContentsOfFile: is used to read and parse an ASCII property list from a file, parse errors and exceptions are suppressed, and nil is returned upon error. Sometimes a program wants to know about syntax errors in a property list, or wants finer-grained information about why a property list cannot be read and parsed. Another method, NSString's -propertyList, can be used for this purpose. The following example illustrates this:

- (id)readPropertyListFromFile:(NSString *)path mustBeOfType:(Class)targetClass logErrors:(BOOL)showErrors {

NSString *string;

id plist = nil;

string = [[NSString allocWithZone:NULL] initWithContentsOfFile:path];

if (showErrors && nil == string) {

NSLog(@"%@: string could not be read from '%@'", NSStringFromSelector(_cmd), path);

}

NS_DURING

plist = [string propertyList];

NS_HANDLER

if (showErrors) {

NSLog(@"%@: received exception while parsing: %@", NSStringFromSelector(_cmd), localException);

}

plist = nil;

NS_ENDHANDLER

[string release];

if (Nil != targetClass && ![plist isKindOfClass:targetClass]) {

if (showErrors) {

NSLog(@"%@: property list is not of desired type '%@'. It's an '%@'.",

NSStringFromSelector(_cmd), NSStringFromClass(targetClass), NSStringFromClass([plist class]));

}

[plist release];

plist = nil;

}

return plist;

}

Grammars for Serialization and ASCII Property List Formats

Grammars and description of the serialization (NSSerializer) and ASCII property list representation formats are available in the appendix to the OpenStep specification and in the OPENSTEP General Reference.

Strings which contain non-alphanumeric characters must be double quoted in property lists to ensure the entire string is parsed as one string object. Parse failures will result, otherwise.

Retain Cycles and Invalidation

The retain/release strategy used in Foundation allows an incautious programmer to create reference cycles in an object graph (that is, the graph of objects that retain one another in some manner). These cycles are self-sustaining and constitute a memory leak. The simplest example is to create a NSMutableArray instance and add it to itself. Since an array retains its objects, it retains itself independent of its normal usage. Retains are essentially distributed across the network via the Distributed Objects mechanism.

If retain cycles cannot be avoided by careful design, but are known a priori, the following technique can be used to recover the memory. For the objects in the cycle(s) whose retain counts are solely due to the cycle, all should be retained (perhaps in an array), each one told to release its retained objects, then all released. The action of releasing its retained objects would undoubtedly cause an object to become dysfunctional. Some objects already implement such a method by the name "-invalidate". It is a bug that neither NSObject nor the collections implement this method to facilitate cycle recovery.

More on Autoreleasing and Retaining

The following statements are false:

Returned objects are guaranteed to be valid for the scope of the current method.

Returned objects are guaranteed to be valid until the current autorelease pool is released.

Returned objects are guaranteed to be valid until the end of the current event loop.

The Foundation's retain count mechanism operates via -retain and -release. A code fragment such as:

id object = [collection returnObject];

creates a reference (in object) to the returned object, but does not increment the retain count of object. If you don't let the system know about your reference, by incrementing the retain count with -retain, the system can't ensure that your reference remains valid for any length of time. In practice, you can get away with such "weak references" most of the time. But the safest approach formalizes your reference to the object:

id object = [[collection returnObject] retain];

/* Do operations, some of which may be on 'object' */

...

/* Don't need object any longer */

[object release];

object = nil;

The -hash and -isEqual: Invariant

It is worthwhile to highlight an obscure requirement documented in NSObject class specification for the -hash method: The -hash and -isEqual: methods of a class must be defined so that if two objects are equal, their hash value is the same ([x isEqual:y] implies [x hash] == [y hash], but not the converse). This is easy to forget, but especially important to ensure when putting custom objects into some collections (such as NSSet and NSDictionary).

Forwarding Messages in OpenStep

Objects wishing to forward messages with the -forwardInvocation: method must also (re)implement the -methodSignatureForSelector: method. This is a result of the compiler not providing call stack descriptive information at each call site. Consequently, the runtime needs a source of information for how the stack frame is constructed. It needs this to build the invocation that will be supplied to the -forwardInvocation: method call. The -methodSignatureForSelector: method will need to be reimplemented to provide a method signature for selectors to which the object does not respond.

Fault objects in EOF which wish to forward messages should also override +instanceMethodSignatureForSelector:.

- (NSMethodSignature *)methodSignatureForSelector:(SEL)sel {

NSMethodSignature *result = [super methodSignatureForSelector:sel];

if (nil == result) {_// must not respond to the selector, no runtime information available

result = [target methodSignatureForSelector:sel];

}

return result;

}

- (void)forwardInvocation:(NSInvocation *)invocation {

[invocation invokeWithTarget:target];_// let target implement methods that we do not

}

See the ForwardInvocation example in /NextDeveloper/Examples/Foundation/ForwardInvocation.

Debugging Aids

The OpenStep Conversion Guide describes several techniques for debugging Foundation and AppKit applications. The header file NSDebug.h also has some global flags, functions, and methods which may be useful. But be warned: although this header file is public, its contents are mostly unsupported, largely undocumented, and are subject to change without warning. Do not depend on API within this header for the operation of production programs.

Object Allocation Analysis

One of the useful flags defined in NSDebug.h is NSKeepAllocationStatistics, which allows you to analyze the object allocation activity in a program. The AnalyzeAllocation command line program can be used to analyze the output generated by running with this option enabled. You can also use the ObjectAlloc demo application which comes OPENSTEP for Mach and Windows to graph the object allocation activity in real time.

The +load Method

The +load message is sent to classes when they are added to the Objective C runtime. +load is usually received before +initialize. +load is not inherited by subclasses.

The order in which +load messages are sent to classes is unspecified (and specifically, a class's superclass is not guaranteed to have its +load method called before the class receives the message). Therefore, you should not use any subsystems or classes which are loaded at the same time, or more generally, which you do not know have received the +load message. If you do, you will probably cause execution of code which assumes that +load (and anything that had to be done in +load) has been previously executed.

There are two situations typically when classes are added to the runtime:

•	when loaded dynamically from a bundle or framework by NSBundle

•	at application launch

The restrictions on +load are perhaps most serious at launch time. The Foundation has classes and subsystems (as might any other library) which depend on +load being called before they are fully functional. For example, you should not use NSZoneMalloc() to allocate memory in +load methods which are statically linked into an application. You certainly should not create any objects.

Note that calling +load on a class isn't a solution (and is a generally bad idea), because that will cause +initialize to be sent first, which the class may not handle. Not to mention that doing so places into your code dependencies on which classes implement +load in a particular version of a library.

+load is not intended as a general initialization mechanism, and should only be used when absolutely necessary. Use +initialize for early initialization whenever possible.

Performance and NSNotificationCenter

NSNotificationCenter, although heavily optimized, by its nature can become a significant performance bottleneck if heavy use of notifications is made. The notification mechanism should be used judiciously.

NSAutoreleasePool's -addObject: Method

You should never use the NSAutoreleasePool instance method -addObject:. Use the -autorelease method, or [NSAutoreleasePool addObject:] to autorelease an object. Using the instance method incurs the risk of adding an object to a pool which is not the top autorelease pool, a semantically suspect operation, since the autorelease pool model is one of a (per-thread) stack of pools. OPENSTEP 4.0 does allow you to add objects to an autorelease pool that is not the top pool, but be warned that it is a much more expensive operation (and always will be) than adding an object to the top pool.

Frameworks as NSBundles

Frameworks are a specialized form of bundle. An application can statically link against a framework at compile time (like a library), or dynamically load a framework (like a bundle) at runtime. However, as a specialized type of bundle, there are some constraints placed on frameworks:

•	A framework must have a .framework extension

•	The name of the executable code of a framework must have the same name as the framework directory, minus the .framework extension. For example, the file name of the executable code for the framework MyFramework.framework must be MyFramework (or on WindowsTM, MyFramework.dll).

•	On WindowsTM only: The framework directory must be stored in a directory called Frameworks. The executable code (.dll) must be stored in a directory called Executables that has the same parent as the Frameworks directory. If the framework is statically linked into applications, the Executables directory (full path) should be in the PATH environment variable. (On other OPENSTEP platforms, the executable code file is stored within the framework directory, like a bundle.)

How NSBundles Search for Resources

The algorithm that NSBundles use to find resources has changed somewhat from that of NXBundles, and there are changes to the structure of bundles themselves. A bundle's resources are now stored in a directory call Resources within the bundle directory. Within the Resources directory are the non-localized resources and the localized resource directories (English.lproj, Swedish.lproj, etc., as with NXBundle). The addition of the Resources directory is primarily a way to simplify Framework versioning. Other changes have been made to reduce the amount of computation required to find resources.

Suppose we are searching for the resource with name Main and type nib. The bundle's resource path, the "top level", is searched first, for the file Main.nib. If the file is not found there, each of the language subdirectories are each searched, in the user's preference order. This is a change from NXBundle's behavior, where the language subdirectories were searched first. This change means that the localized version of a resource that also exists at the top level will not be found, but the top level one will be. All non-localized resources should be placed in the top level, and no localized resources should exist at the top level.

When a resource is found, the algorithm checks to see if a resource of the name Main-$(PLATFORM_OS) of type nib exists. $(PLATFORM_OS) represents the make variable of the same name, and takes on the same values that the make variable takes on at compile time. For example, on WindowsTM, during a project build, $(PLATFORM_OS) in the Makefile.postamble will have the value "winnt". When Main.nib is found in a directory, the search algorithm does one final check to see if Main-winnt.nib exists in that same directory. If it does, the search algorithm returns the path to that resource; if it does not, the search algorithm returns the path to Main.nib. Note that for Main-winnt.nib to be found, a file named Main.nib must exist in the same directory; this also applies within each language resource directory. It is expected that a developer will choose one of the platform-specific versions to name without this $(PLATFORM_OS) suffix, and give the other platform-specific versions of the resource extended names. The values that $(PLATFORM_OS) can take on are currently "winnt" (on OPENSTEP for WindowsTM), "nextstep" (on OPENSTEP for MACH), "hpux"(on PDO for HP-UXTM), and "solaris" (on PDO for SolarisTM).

Another way to accommodate platform-specific resources is by using the inDirectory: parameter of the resource-searching methods. The inDirectory: parameter is primarily intended to facilitate the collection of resources of a common type or purpose into a single directory; for example, all images could be put into a directory called Images within the resource directory. (Note that the AppKit's +imageNamed: method in NSImage does not support searching arbitrary directories for images.) As such, the inDirectory: parameter can be used to manage platform-specific resources. This is less "automatic" however, and requires the developer to specify the name of the platform-specific directory as well as replicate the required resources and language projects within that directory. The $(PLATFORM_OS) mechanism described above is simpler to use, particularly if the number of platform-specific resources is small.

Using API not in OpenStep

Many new methods and classes were added for 4.0 and some new methods for 4.1, many outside the purview of the OpenStep specification. To restrict those that are defined to the methods and classes in OpenStep, add the flag -DSTRICT_OPENSTEP to the OTHER_CFLAGS variable in the project's Makefile.preamble.

The Pointer Returned from malloc()

Asking malloc() for a block of memory that is close to the size of a page will give you a pointer for which NXZoneFromPtr() returns NULL. This is not a bug; blocks of memory allocated from malloc() do not necessarily come from a zone.

__________________________________________________________________________________________________________________________________________________________

Known Problems in OPENSTEP 4.1

Click here to view a list of known Foundation problems in this release of OPENSTEP.


GDB Version


General Changes in Public Foundation API Methods

CLASS/PROTOCOL	HEADER	METHOD

NSArchiver	NSArchiver.h	+classNameEncodedForTrueClassName:	(-NeXT) (EOF11) (NS33)	Use -classNameEncodedForTrueClassName: instead

NSArchiver	NSArchiver.h	-classNameEncodedForTrueClassName:	(OpenStep,+NeXT) (EOF11) (NS33)

NSArchiver	NSArchiver.h	-encodeClassName:intoClassName:	(OpenStep,+NeXT) (EOF11) (NS33)

NSArchiver	NSArchiver.h	-replaceObject:withObject:	(+NeXT) (EOF11) (NS33)

NSArray	NSArray.h	+arrayWithArray:	(+NeXT) (40PR2) (40PR1) (EOF11) (NS33)

NSArray	NSArray.h	+arrayWithContentsOfFile:	(+OpenStep,+NeXT) (40PR1) (EOF11) (NS33)

NSArray	NSArray.h	+arrayWithObjects:count:	(+NeXT) (40PR2) (40PR1) (EOF11) (NS33)

NSArray	NSArray.h	-arrayByAddingObject:	(OpenStep,+NeXT) (EOF11) (NS33)

NSArray	NSArray.h	-arrayByAddingObjectsFromArray:	(OpenStep,+NeXT) (EOF11) (NS33)

NSArray	NSArray.h	-descriptionWithIndent:	(-NeXT) (EOF11) (NS33)	Use -descriptionWithLocale:indent: instead

NSArray	NSArray.h	-descriptionWithLocale:	(OpenStep,+NeXT) (EOF11) (NS33)

NSArray	NSArray.h	-descriptionWithLocale:indent:	(OpenStep,+NeXT) (EOF11) (NS33)

NSArray	NSArray.h	-getObjects:	(+OpenStep,+NeXT) (40PR1) (EOF11) (NS33)

NSArray	NSArray.h	-getObjects:range:	(+OpenStep,+NeXT) (40PR1) (EOF11) (NS33)

NSArray	NSArray.h	-indexOfObject:inRange:	(+OpenStep,+NeXT) (40PR1) (EOF11) (NS33)

NSArray	NSArray.h	-indexOfObjectIdenticalTo:inRange:	(+OpenStep,+NeXT) (40PR1) (EOF11) (NS33)

NSArray	NSArray.h	-initWithContentsOfFile:	(+OpenStep,+NeXT) (40PR1) (EOF11) (NS33)

NSArray	NSArray.h	-sortedArrayHint	(+OpenStep,+NeXT) (40PR1) (EOF11) (NS33)

NSArray	NSArray.h	-sortedArrayUsingFunction:context:hint:	(+OpenStep,+NeXT) (40PR1) (EOF11) (NS33)

NSArray	NSArray.h	-writeToFile:atomically:	(+OpenStep,+NeXT) (40PR1) (EOF11) (NS33)

NSArray	NSPathUtilities.h	-pathsMatchingExtensions:	(+NeXT) (40PR1) (EOF11) (NS33)

NSBundle	NSBundle.h	+pathForResource:ofType:inDirectory:	(+OpenStep,+NeXT) (P40PR1) (40PR2) (40PR1) (EOF11) (NS33)

NSBundle	NSBundle.h	+pathForResource:ofType:inDirectory:withVersion:	(-OpenStep,-NeXT) (40PR1) (EOF11) (NS33)

NSBundle	NSBundle.h	+setSystemLanguages:	(-NeXT) (EOF11) (NS33)

NSBundle	NSBundle.h	+stripAfterLoading:	(-OpenStep,-NeXT) (40PR1) (EOF11) (NS33)

NSBundle	NSBundle.h	-bundleVersion	(-OpenStep,-NeXT) (40PR1) (EOF11) (NS33)

NSBundle	NSBundle.h	-infoDictionary	(+NeXT) (EOF11) (NS33)

NSBundle	NSBundle.h	-localizedStringForKey:value:comment:	(-NeXT) (EOF11) (NS33)	Use -localizedStringForKey:value:table: instead

NSBundle	NSBundle.h	-localizedStringForKey:value:comment:table:	(-NeXT) (EOF11) (NS33)	Use -localizedStringForKey:value:table: instead

NSBundle	NSBundle.h	-localizedStringForKey:value:table:	(OpenStep,+NeXT) (EOF11) (NS33)

NSBundle	NSBundle.h	-pathForResource:ofType:inDirectory:	(+OpenStep,+NeXT) (40PR1) (EOF11) (NS33)

NSBundle	NSBundle.h	-pathsForResourcesOfType:inDirectory:	(+OpenStep,+NeXT) (40PR1) (EOF11) (NS33)

NSBundle	NSBundle.h	-resourcePath;	(+OpenStep,+NeXT) (40PR1) (EOF11) (NS33)

NSBundle	NSBundle.h	-setBundleVersion:	(-OpenStep,-NeXT) (40PR1) (EOF11) (NS33)

NSCalendarDate	NSDate.h	+calendarDate	(OpenStep,+NeXT) (EOF11) (NS33)

NSCalendarDate	NSDate.h	+dateWithString:calendarFormat:locale:	(OpenStep,+NeXT) (EOF11) (NS33)

NSCalendarDate	NSDate.h	-addYear:month:day:hour:minute:second:	(-OpenStep,-NeXT) (40PR1) (EOF11) (NS33)	Use -dateByAddingYears:months:days:hours:minutes:seconds: instead

NSCalendarDate	NSDate.h	-dateByAddingYears:months:days:hours:minutes:seconds:	(+OpenStep,+NeXT) (40PR1) (EOF11) (NS33)

NSCalendarDate	NSDate.h	-dayOfCommonEra	(OpenStep,+NeXT) (EOF11) (NS33)

NSCalendarDate	NSDate.h	-descriptionWithCalendarFormat:locale:	(OpenStep,+NeXT) (EOF11) (NS33)

NSCalendarDate	NSDate.h	-descriptionWithCalendarFormat:timeZone:	(-NeXT) (EOF11) (NS33)

NSCalendarDate	NSDate.h	-descriptionWithLocale:	(OpenStep,+NeXT) (EOF11) (NS33)

NSCalendarDate	NSDate.h	-initWithString:calendarFormat:locale:	(OpenStep,+NeXT) (EOF11) (NS33)

NSCalendarDate	NSDate.h	-years:months:days:hours:minutes:seconds:sinceDate:	(+OpenStep,+NeXT) (40PR1) (EOF11) (NS33)

NSCharacterSet	NSCharacterSet.h	+characterSetWithContentsOfFile:	(+NeXT) (EOF11) (NS33)

NSCharacterSet	NSCharacterSet.h	+punctuationCharacterSet	(+NeXT) (EOF11) (NS33)

NSCharacterSet	NSCharacterSet.h	+punctuationCharacterSet	(+OpenStep,NeXT) (40PR1)

NSCoder	NSCoder.h	-decodeBytesWithReturnedLength:	(+OpenStep,+NeXT) (40PR1) (EOF11) (NS33)

NSCoder	NSCoder.h	-encodeByrefObject:	(+NeXT) (40PR1) (EOF11) (NS33)

NSCoder	NSCoder.h	-encodeBytes:length:	(+OpenStep,+NeXT) (40PR1) (EOF11) (NS33)

NSConnection	NSConnection.h	+currentConversation	(+NeXT) (P40PR1) (40PR2) (40PR1)

NSConnection	NSConnection.h	-addRequestMode:	(+OpenStep,+NeXT) (40PR1)

NSConnection	NSConnection.h	-addRunLoop:	(+NeXT) (P40PR1) (40PR2) (40PR1)

NSConnection	NSConnection.h	-connection:shouldMakeNewConnection:	(+NeXT) (40PR1)

NSConnection	NSConnection.h	-createConversationForConnection:	(+NeXT) (P40PR1) (40PR2) (40PR1)

NSConnection	NSConnection.h	-enableMultipleThreads	(+NeXT) (P40PR1) (40PR2) (40PR1)

NSConnection	NSConnection.h	-invalidate	(+OpenStep,+NeXT) (40PR1)

NSConnection	NSConnection.h	-localObjects	(+NeXT) (P40PR1) (40PR2)

NSConnection	NSConnection.h	-multipleThreadsEnabled	(+NeXT) (P40PR1) (40PR2) (40PR1)

NSConnection	NSConnection.h	-remoteObjects	(+NeXT) (P40PR1) (40PR2)

NSConnection	NSConnection.h	-removeRequestMode:	(+OpenStep,+NeXT) (40PR1)

NSConnection	NSConnection.h	-removeRunLoop:	(+NeXT) (P40PR1) (40PR2) (40PR1)

NSConnection	NSConnection.h	-requestMode:	(-OpenStep,-NeXT) (40PR1)

NSConnection	NSConnection.h	-requestModes	(+OpenStep,+NeXT) (40PR1)

NSConnection	NSConnection.h	-runInNewThread	(+NeXT) (P40PR1) (40PR2) (40PR1)

NSConnection	NSConnection.h	-setRequestMode::	(-OpenStep,-NeXT) (40PR1)	Use -addRequestMode: instead

NSCopyingProtocol	NSObject.h	-copy	(-NeXT) (EOF11) (NS33)

NSData	NSData.h	+dataWithData:	(+NeXT) (40PR2) (40PR1) (EOF11) (NS33)

NSDate	NSDate.h	+dateWithNaturalLanguageString:	(+NeXT) (EOF11) (NS33)

NSDate	NSDate.h	+dateWithNaturalLanguageString:locale:	(+NeXT) (EOF11) (NS33)

NSDate	NSDate.h	+dateWithString:	(+NeXT) (40PR2) (40PR1) (EOF11) (NS33)

NSDate	NSDate.h	+dateWithTimeIntervalSince1970:	(OpenStep,+NeXT) (EOF11) (NS33)

NSDate	NSDate.h	-descriptionWithCalendarFormat:timeZone:	(-NeXT) (EOF11) (NS33)

NSDate	NSDate.h	-descriptionWithCalendarFormat:timeZone:locale:	(OpenStep,+NeXT) (EOF11) (NS33)

NSDate	NSDate.h	-descriptionWithLocale:	(OpenStep,+NeXT) (EOF11) (NS33)

NSDate	NSDate.h	-isEqualToDate:	(+OpenStep,+NeXT) (40PR1)

NSDate	NSDate.h	-timeIntervalSince1970	(OpenStep,+NeXT) (EOF11) (NS33)

NSDecimalNumber	NSDecimalNumber.h	+decimalNumberBehaviorWithRoundingMode:scale:raiseOnExactness:raiseOnOverflow:raiseOnUnderflow:raiseOnDivideByZero:	(-NeXT) (P40PR1) (40PR2) (40PR1)	Use +decimalNumberHandlerWithRoundingMode:... instead

NSDecimalNumber	NSDecimalNumber.h	+decimalNumberHandlerWithRoundingMode:scale:raiseOnExactness:raiseOnOverflow:raiseOnUnderflow:raiseOnDivideByZero:	(+NeXT) (P40PR1) (40PR2) (40PR1)

NSDecimalNumber	NSDecimalNumber.h	-decimalNumberBySubstracting:	(-NeXT) (P40PR1) (40PR2) (40PR1)

NSDecimalNumber	NSDecimalNumber.h	-decimalNumberBySubstracting:withBehavior:	(-NeXT) (P40PR1) (40PR2) (40PR1)

NSDecimalNumber	NSDecimalNumber.h	-decimalNumberBySubtracting:	(+NeXT) (P40PR1) (40PR2) (40PR1)

NSDecimalNumber	NSDecimalNumber.h	-decimalNumberBySubtracting:withBehavior:	(+NeXT) (P40PR1) (40PR2) (40PR1)

NSDecimalNumber	NSDecimalNumber.h	-maximumDecimalNumber	(+NeXT) (P40PR1) (40PR2) (40PR1)

NSDecimalNumber	NSDecimalNumber.h	-minimumDecimalNumber	(+NeXT) (P40PR1) (40PR2) (40PR1)

NSDecimalNumberBehavior	NSDecimalNumber.h	+defaultDecimalNumberBehavior	(-NeXT) (P40PR1) (40PR2) (40PR1)

NSDecimalNumberHandler	NSDecimalNumber.h	+defaultDecimalNumberHandler	(+NeXT) (P40PR1) (40PR2) (40PR1)

NSDictionary	NSDictionary.h	+dictionaryWithContentsOfFile:	(OpenStep,+NeXT) (EOF11) (NS33)

NSDictionary	NSDictionary.h	+dictionaryWithDictionary:	(+NeXT) (40PR2) (40PR1) (EOF11) (NS33)

NSDictionary	NSDictionary.h	+dictionaryWithObject:forKey:	(+NeXT) (40PR2) (40PR1) (EOF11) (NS33)

NSDictionary	NSDictionary.h	+dictionaryWithObjectsAndKeys:...	(OpenStep,+NeXT) (EOF11) (NS33)

NSDictionary	NSDictionary.h	-descriptionWithIndent:	(-NeXT) (EOF11) (NS33)	Use -descriptionWithLocale:indent: instead

NSDictionary	NSDictionary.h	-descriptionWithLocale:	(OpenStep,+NeXT) (EOF11) (NS33)

NSDictionary	NSDictionary.h	-descriptionWithLocale:indent:	(OpenStep,+NeXT) (EOF11) (NS33)

NSDictionary	NSDictionary.h	-initWithObjects:forKeys:	(OpenStep,+NeXT) (EOF11) (NS33)

NSDictionary	NSDictionary.h	-initWithObjectsAndKeys:...	(OpenStep,+NeXT) (EOF11) (NS33)

NSDictionary	NSDictionary.h	-keysSortedByValueUsingSelector:	(+NeXT) (40PR2) (40PR1) (EOF11) (NS33)

NSDictionary	NSDictionary.h	-objectsForKeys:notFoundMarker:	(+OpenStep,+NeXT) (40PR1) (EOF11) (NS33)

NSDictionary	NSFileManager.h	-fileGroupOwnerAccountName	(+NeXT) (40PR1)

NSDictionary	NSFileManager.h	-fileGroupOwnerAccountNumber	(-NeXT) (40PR1)	Use -fileGroupOwnerAccountName instead

NSDictionary	NSFileManager.h	-fileOwnerAccountName	(+NeXT) (40PR1)

NSDictionary	NSFileManager.h	-fileOwnerAccountNumber	(-NeXT) (40PR1)	Use -fileOwnerAccountName instead

NSDistantObjectRequest	NSConnection.h	-conversation	(+NeXT) (P40PR1) (40PR2)	Note class was added after OPENSTEP 4.0 PR1

NSEnumerator	NSEnumerator.h	-allObjects	(+OpenStep,+NeXT) (40PR1) (EOF11) (NS33)	For OpenStep compatibility, import NSUtilities.h

NSException	NSException.h	-exceptionName	(-NeXT) (EOF11) (NS33)

NSException	NSException.h	-exceptionReason	(-NeXT) (EOF11) (NS33)

NSException	NSException.h	-exceptionUserInfo	(-NeXT) (EOF11) (NS33)

NSException	NSException.h	-name	(OpenStep,+NeXT) (EOF11) (NS33)

NSException	NSException.h	-reason	(OpenStep,+NeXT) (EOF11) (NS33)

NSException	NSException.h	-userInfo	(OpenStep,+NeXT) (EOF11) (NS33)

NSMethodSignature	NSMethodSignature.h	+signatureWithObjCTypes:	(-OpenStep,-NeXT) (40PR1)

NSMethodSignature	NSMethodSignature.h	-argumentInfoAtIndex:	(-OpenStep,-NeXT) (40PR1)	Use -getArgumentTypeAtIndex: instead

NSMethodSignature	NSMethodSignature.h	-getArgumentTypeAtIndex:	(+OpenStep,+NeXT) (40PR1)

NSMutableArray	NSArray.h	-removeObject:inRange:	(+OpenStep,+NeXT) (40PR1) (EOF11) (NS33)

NSMutableArray	NSArray.h	-removeObjectIdenticalTo:inRange:	(+OpenStep,+NeXT) (40PR1) (EOF11) (NS33)

NSMutableArray	NSArray.h	-removeObjectsInRange:	(+OpenStep,+NeXT) (40PR1) (EOF11) (NS33)

NSMutableArray	NSArray.h	-replaceObjectsInRange:withObjectsFromArray:	(+OpenStep,+NeXT) (40PR1) (EOF11) (NS33)

NSMutableArray	NSArray.h	-replaceObjectsInRange:withObjectsFromArray:range:	(+OpenStep,+NeXT) (40PR1) (EOF11) (NS33)

NSMutableArray	NSArray.h	-setArray:	(OpenStep,+NeXT) (EOF11) (NS33)

NSMutableArray	NSArray.h	-sortUsingSelector:	(OpenStep,+NeXT) (EOF11) (NS33)

NSMutableCopyingProtocol	NSObject.h	-mutableCopy	(-NeXT) (EOF11) (NS33)

NSMutableData	NSData.h	-setData:	(+NeXT) (40PR2) (40PR1) (EOF11) (NS33)

NSMutableDictionary	NSDictionary.h	-setDictionary:	(OpenStep,+NeXT) (EOF11) (NS33)

NSMutableSet	NSSet.h	-setSet:	(+NeXT) (40PR2) (40PR1)

NSNotification	NSNotification.h	+notificationWithName:object:userInfo:	(OpenStep,+NeXT) (EOF11) (NS33)

NSNotification	NSNotification.h	-name	(OpenStep,+NeXT) (EOF11) (NS33)

NSNotification	NSNotification.h	-notificationName	(-NeXT) (EOF11) (NS33)

NSNotification	NSNotification.h	-notificationObject	(-NeXT) (EOF11) (NS33)

NSNotification	NSNotification.h	-object	(OpenStep,+NeXT) (EOF11) (NS33)

NSNotification	NSNotification.h	-userInfo	(OpenStep,+NeXT) (EOF11) (NS33)

NSNotificationCenter	NSNotification.h	-addObserver:selector:name:object:	(OpenStep,+NeXT) (EOF11) (NS33)

NSNotificationCenter	NSNotification.h	-addObserver:selector:notificationName:object:	(-NeXT) (EOF11) (NS33)

NSNotificationCenter	NSNotification.h	-postNotificationName:object:userInfo:	(OpenStep,+NeXT) (EOF11) (NS33)

NSNotificationCenter	NSNotification.h	-removeObserver:name:object:	(OpenStep,+NeXT) (EOF11) (NS33)

NSNotificationCenter	NSNotification.h	-removeObserver:notificationName:object:	(-NeXT) (EOF11) (NS33)

NSNumber	NSValue.h	-descriptionWithLocale:	(+NeXT) (EOF11) (NS33)

NSNumber	NSValue.h	-descriptionWithLocale:	(+OpenStep,NeXT) (40PR1)

NSNumber	NSValue.h	-initWithBool:	(+NeXT) (NS33)

NSNumber	NSValue.h	-initWithBool:	(+OpenStep,NeXT) (40PR1)

NSNumber	NSValue.h	-initWithChar:	(+NeXT) (NS33)

NSNumber	NSValue.h	-initWithChar:	(+OpenStep,NeXT) (40PR1)

NSNumber	NSValue.h	-initWithDouble:	(+NeXT) (NS33)

NSNumber	NSValue.h	-initWithDouble:	(+OpenStep,NeXT) (40PR1)

NSNumber	NSValue.h	-initWithFloat:	(+NeXT) (NS33)

NSNumber	NSValue.h	-initWithFloat:	(+OpenStep,NeXT) (40PR1)

NSNumber	NSValue.h	-initWithInt:	(+NeXT) (NS33)

NSNumber	NSValue.h	-initWithInt:	(+OpenStep,NeXT) (40PR1)

NSNumber	NSValue.h	-initWithLong:	(+NeXT) (NS33)

NSNumber	NSValue.h	-initWithLong:	(+OpenStep,NeXT) (40PR1)

NSNumber	NSValue.h	-initWithLongLong:	(+NeXT) (NS33)

NSNumber	NSValue.h	-initWithLongLong:	(+OpenStep,NeXT) (40PR1)

NSNumber	NSValue.h	-initWithShort:	(+NeXT) (NS33)

NSNumber	NSValue.h	-initWithShort:	(+OpenStep,NeXT) (40PR1)

NSNumber	NSValue.h	-initWithUnsignedChar:	(+NeXT) (NS33)

NSNumber	NSValue.h	-initWithUnsignedChar:	(+OpenStep,NeXT) (40PR1)

NSNumber	NSValue.h	-initWithUnsignedInt:	(+NeXT) (NS33)

NSNumber	NSValue.h	-initWithUnsignedInt:	(+OpenStep,NeXT) (40PR1)

NSNumber	NSValue.h	-initWithUnsignedLong:	(+NeXT) (NS33)

NSNumber	NSValue.h	-initWithUnsignedLong:	(+OpenStep,NeXT) (40PR1)

NSNumber	NSValue.h	-initWithUnsignedLongLong:	(+NeXT) (NS33)

NSNumber	NSValue.h	-initWithUnsignedLongLong:	(+OpenStep,NeXT) (40PR1)

NSNumber	NSValue.h	-initWithUnsignedShort:	(+NeXT) (NS33)

NSNumber	NSValue.h	-initWithUnsignedShort:	(+OpenStep,NeXT) (40PR1)

NSNumber	NSValue.h	-isEqualToNumber:	(+OpenStep,+NeXT) (40PR1) (EOF11) (NS33)

NSObject	NSConnection.h	-connection:handleRequest:	(+NeXT) (40PR1)

NSObject	NSObject.h	+copyWithZone:	(+OpenStep,+NeXT) (40PR1) (EOF11) (NS33)

NSObject	NSObject.h	+load	(+NeXT) (40PR1)

NSObject	NSObject.h	+load	(+OpenStep,NeXT) (P40PR1) (40PR2)

NSObject	NSObject.h	+mutableCopyWithZone:	(+OpenStep,+NeXT) (40PR1) (EOF11) (NS33)

NSObject	NSObject.h	-copy	(OpenStep,+NeXT) (EOF11) (NS33)

NSObject	NSObject.h	-description	(-NeXT) (EOF11) (NS33)

NSObject	NSObject.h	-mutableCopy	(OpenStep,+NeXT) (EOF11) (NS33)

NSObject	NSRunLoop.h	-performSelector:object:afterDelay:	(-OpenStep,-NeXT) (40PR1)

NSObject	NSRunLoop.h	-performSelector:withObject:afterDelay:	(+OpenStep,+NeXT) (40PR1)

NSObject	NSRunLoop.h	-performSelector:withObject:afterDelay:inModes:	(+NeXT) (P40PR1) (40PR2) (40PR1)

NSObjectProtocol	NSObject.h	-description	(OpenStep,+NeXT) (EOF11) (NS33)

NSObjectProtocol	NSObject.h	-perform:	(-OpenStep,-NeXT) (40PR1) (EOF11) (NS33)	Use -performSelector: instead

NSObjectProtocol	NSObject.h	-perform:withObject:	(-OpenStep,-NeXT) (40PR1) (EOF11) (NS33)	Use -performSelector:withObject: instead

NSObjectProtocol	NSObject.h	-perform:withObject:withObject:	(-OpenStep,-NeXT) (40PR1) (EOF11) (NS33)	Use -performSelector:withObject:withObject: instead

NSObjectProtocol	NSObject.h	-performSelector:	(+OpenStep,+NeXT) (40PR1) (EOF11) (NS33)

NSObjectProtocol	NSObject.h	-performSelector:withObject:	(+OpenStep,+NeXT) (40PR1) (EOF11) (NS33)

NSObjectProtocol	NSObject.h	-performSelector:withObject:withObject:	(+OpenStep,+NeXT) (40PR1) (EOF11) (NS33)

NSPort	NSPort.h	-addConnection:toRunLoop:forMode:	(+NeXT) (P40PR1) (40PR2) (40PR1)

NSPort	NSPort.h	-removeConnection:fromRunLoop:forMode:	(+NeXT) (P40PR1) (40PR2) (40PR1)

NSPort	NSPort.h	-reservedSpaceLength	(+NeXT) (P40PR1) (40PR2) (40PR1)

NSPort	NSPort.h	-sendBeforeDate:components:from:reserved:	(+NeXT) (P40PR1) (40PR2) (40PR1)

NSPortCoder	NSPortCoder.h	+portCoderWithReceivePort:sendPort:components:	(+NeXT) (P40PR1) (40PR2) (40PR1)

NSPortCoder	NSPortCoder.h	-dispatch	(+NeXT) (P40PR1) (40PR2) (40PR1)

NSPortCoder	NSPortCoder.h	-isByref	(+NeXT) (40PR1)

NSPortNameServer	NSPortNameServer.h	-portForName:host:	(+NeXT) (P40PR1) (40PR2) (40PR1)

NSPortNameServer	NSPortNameServer.h	-registerPort:name:	(+NeXT) (P40PR1) (40PR2) (40PR1)

NSProcessInfo	NSProcessInfo.h	-operatingSystem	(+NeXT) (40PR1)

NSProxy	NSProxy.h	+load	(+NeXT) (40PR1)

NSProxy	NSProxy.h	+load	(+OpenStep,NeXT) (P40PR1) (40PR2)

NSProxy	NSProxy.h	+respondsToSelector:	(+NeXT) (40PR1)

NSRunLoop	NSRunLoop.h	-addPosixFileDescriptor:forMode:	(-NeXT) (P40PR1) (40PR2) (40PR1)

NSRunLoop	NSRunLoop.h	-addRunLoopActivityMonitor:	(-NeXT) (40PR1)

NSRunLoop	NSRunLoop.h	-cancelPerformSelector:target:argument:	(+NeXT) (P40PR1) (40PR2) (40PR1)

NSRunLoop	NSRunLoop.h	-performSelector:target:argument:order:modes:	(+NeXT) (P40PR1) (40PR2) (40PR1)

NSRunLoop	NSRunLoop.h	-removePosixFileDescriptor:forMode:	(-NeXT) (P40PR1) (40PR2) (40PR1)

NSScanner	NSScanner.h	+localizedScannerWithString:	(OpenStep,+NeXT) (EOF11) (NS33)

NSScanner	NSScanner.h	-locale	(OpenStep,+NeXT) (EOF11) (NS33)

NSScanner	NSScanner.h	-scanHexInt:	(+NeXT) (EOF11) (NS33)

NSScanner	NSScanner.h	-scanHexInt:	(+OpenStep,NeXT) (40PR1) (EOF11) (NS33)

NSScanner	NSScanner.h	-setLocale:	(OpenStep,+NeXT) (EOF11) (NS33)

NSSet	NSSet.h	+setWithObjects:count:	(+NeXT) (40PR2) (40PR1)

NSSet	NSSet.h	+setWithSet:	(+NeXT) (40PR2) (40PR1)

NSString	NSPathUtilities.h	+pathWithComponents:	(+NeXT) (40PR1) (EOF11) (NS33)

NSString	NSPathUtilities.h	-fileSystemRepresentation	(+OpenStep,+NeXT) (40PR1) (EOF11) (NS33)

NSString	NSPathUtilities.h	-getFileSystemRepresentation:maxLength:	(+OpenStep,+NeXT) (40PR1) (EOF11) (NS33)

NSString	NSPathUtilities.h	-isAbsolutePath	(+NeXT) (40PR1) (EOF11) (NS33)

NSString	NSPathUtilities.h	-pathComponents	(+NeXT) (40PR1) (EOF11) (NS33)

NSString	NSPathUtilities.h	-stringsByAppendingPaths:	(+OpenStep,+NeXT) (40PR1) (EOF11) (NS33)

NSString	NSString.h	+availableStringEncodings	(OpenStep,+NeXT) (EOF11) (NS33)

NSString	NSString.h	+localizedNameOfStringEncoding:	(OpenStep,+NeXT) (EOF11) (NS33)

NSString	NSString.h	+localizedStringWithFormat:...	(OpenStep,+NeXT) (EOF11) (NS33)

NSString	NSString.h	+string	(+NeXT) (40PR2) (40PR1) (EOF11) (NS33)

NSString	NSString.h	+stringWithContentsOfFile:	(OpenStep,+NeXT) (EOF11) (NS33)

NSString	NSString.h	+stringWithString:	(+NeXT) (40PR2) (40PR1) (EOF11) (NS33)

NSString	NSString.h	-caseInsensitiveCompare:	(OpenStep,+NeXT) (EOF11) (NS33)

NSString	NSString.h	-doubleValue	(OpenStep,+NeXT) (EOF11) (NS33)

NSString	NSString.h	-getLineStart:end:contentsEnd:forRange:	(+NeXT) (P40PR1) (40PR2) (40PR1) (EOF11) (NS33)

NSString	NSString.h	-initWithFormat:locale:...	(OpenStep,+NeXT) (EOF11) (NS33)

NSString	NSString.h	-initWithFormat:locale:arguments:	(OpenStep,+NeXT) (EOF11) (NS33)

NSString	NSString.h	-lineRangeForRange:	(+NeXT) (P40PR1) (40PR2) (40PR1) (EOF11) (NS33)

NSString	NSString.h	-lossyCString	(+OpenStep,+NeXT) (40PR1) (EOF11) (NS33)

NSString	NSString.h	-substringFromRange:	(-OpenStep,-NeXT) (40PR1) (EOF11) (NS33)	Use -substringWithRange: instead

NSString	NSString.h	-substringWithRange:	(+OpenStep,+NeXT) (40PR1) (EOF11) (NS33)

NSString	NSString.h	-writeToFile:atomically:	(OpenStep,+NeXT) (EOF11) (NS33)

NSThread	NSThread.h	+exit	(OpenStep,+NeXT) (EOF11)

NSThread	NSThread.h	+sleepUntilDate:	(OpenStep,+NeXT) (EOF11)

NSThread	NSThread.h	-exit	(-NeXT) (EOF11)

NSTimer	NSTimer.h	-isValid	(+OpenStep,+NeXT) (40PR1)

NSUnarchiver	NSArchiver.h	-classNameDecodedForArchiveClassName:	(OpenStep,+NeXT) (EOF11) (NS33)

NSUnarchiver	NSArchiver.h	-decodeClassName:asClassName:	(OpenStep,+NeXT) (EOF11) (NS33)

NSUnarchiver	NSArchiver.h	-replaceObject:withObject:	(+NeXT) (EOF11) (NS33)

NSUserDefaults	NSUserDefaults.h	-setSearchList:	(+OpenStep,+NeXT) (40PR1)

NSValue	NSValue.h	+valueWithBytes:objCType:	(+NeXT) (EOF11) (NS33)

NSValue	NSValue.h	+valueWithBytes:objCType:	(+OpenStep,NeXT) (40PR1)

NSValue	NSValue.h	-initWithBytes:objCType:	(+NeXT) (EOF11) (NS33)

NSValue	NSValue.h	-initWithBytes:objCType:	(+OpenStep,NeXT) (40PR1)

NSValue	NSValue.h	-isEqualToValue:	(+OpenStep,+NeXT) (40PR1) (EOF11) (NS33)

Object	NSCompatibility.h	+allocWithZone:	(+NeXT) (EOF11) (NS33)

Object	NSCompatibility.h	+instanceMethodForSelector:	(+NeXT) (EOF11) (NS33)

Object	NSCompatibility.h	+instancesRespondToSelector:	(+NeXT) (EOF11) (NS33)

Object	NSCompatibility.h	+poseAsClass:	(+NeXT) (EOF11) (NS33)

Object	NSCompatibility.h	-autorelease	(+NeXT) (EOF11) (NS33)

Object	NSCompatibility.h	-conformsToProtocol:	(+NeXT) (EOF11) (NS33)

Object	NSCompatibility.h	-copyWithZone:	(+NeXT) (EOF11) (NS33)

Object	NSCompatibility.h	-dealloc	(+NeXT) (EOF11) (NS33)

Object	NSCompatibility.h	-doesNotRecognizeSelector:	(+NeXT) (EOF11) (NS33)

Object	NSCompatibility.h	-isKindOfClass:	(+NeXT) (EOF11) (NS33)

Object	NSCompatibility.h	-isMemberOfClass:	(+NeXT) (EOF11) (NS33)

Object	NSCompatibility.h	-methodForSelector:	(+NeXT) (EOF11) (NS33)

Object	NSCompatibility.h	-perform:withObject:	(-NeXT) (40PR1) (EOF11) (NS33)	Use -performSelector:withObject: instead

Object	NSCompatibility.h	-perform:withObject:withObject:	(-NeXT) (40PR1)	Use -performSelector:withObject:withObject: instead

Object	NSCompatibility.h	-performSelector:withObject:	(+NeXT) (40PR1)

Object	NSCompatibility.h	-performSelector:withObject:withObject:	(+NeXT) (40PR1)

Object	NSCompatibility.h	-release	(+NeXT) (EOF11) (NS33)

Object	NSCompatibility.h	-respondsToSelector:	(+NeXT) (EOF11) (NS33)

Object	NSCompatibility.h	-retain	(+NeXT) (EOF11) (NS33)

Object	NSCompatibility.h	-retainCount	(+NeXT) (EOF11) (NS33)


General Changes in Public Foundation API Symbols

SYMBOL	TYPE	HEADER

ABS	macro	NSObjCRuntime.h	(+NeXT) (40PR2) (40PR1) (EOF11) (NS33)

MAX	macro	NSObjCRuntime.h	(+NeXT) (40PR2) (40PR1) (EOF11) (NS33)

MIN	macro	NSObjCRuntime.h	(+NeXT) (40PR2) (40PR1) (EOF11) (NS33)

NSAccount	class	NSAccount.h	(-NeXT) (40PR1) (NS33)

NSAdobeStandardCyrillicStringEncoding	constant	NSString.h	(-NeXT) (40PR2) (40PR1)	Use NSWindowsCP1251StringEncoding instead

NSAllocateMemoryPages	function	NSZone.h	(OpenStep,+NeXT) (EOF11) (NS33)

NSArchiverArchiveInconsistency	exception	NSException.h	(-NeXT) (EOF11) (NS33)

NSArchiverClassError	exception	NSException.h	(-NeXT) (EOF11) (NS33)

NSArchiverDescriptorError	exception	NSException.h	(-NeXT) (EOF11) (NS33)

NSArchiverWriteReferenceError	exception	NSException.h	(-NeXT) (EOF11) (NS33)

NSArgumentInfo	typedef	NSMethodSignature.h	(-OpenStep,-NeXT) (40PR1)

NSBTreeBlock	class	NSByteStore.h	(-OpenStep,-NeXT) (40PR1)

NSBTreeComparator	typedef	NSByteStore.h	(-OpenStep,-NeXT) (40PR1)

NSBTreeCursor	class	NSByteStore.h	(-OpenStep,-NeXT) (40PR1)

NSBTreeStoreKeyTooLargeException	exception	NSByteStore.h	(-OpenStep,-NeXT) (40PR1)

NSBecomingMultiThreaded	notification	NSThread.h	(-OpenStep,-NeXT) (40PR1)	Use NSWillBecomeMultiThreadedNotification instead

NSBundleDidLoadNotification	notification	NSBundle.h	(+NeXT) (40PR1) (EOF11) (NS33)

NSBundleDidLoadNotification	notification	NSBundle.h	(+OpenStep,NeXT) (40PR2)

NSBundleLoaded	notification	NSBundle.h	(-NeXT) (40PR1)	Use NSBundleDidLoadNotification instead

NSByteStore 	class	NSByteStore.h	(-OpenStep,-NeXT) (40PR1)

NSByteStoreDamagedException	exception	NSByteStore.h	(-OpenStep,-NeXT) (40PR1)

NSByteStoreFile	class	NSByteStore.h	(-OpenStep,-NeXT) (40PR1)

NSByteStoreLockedException	exception	NSByteStore.h	(-OpenStep,-NeXT) (40PR1)

NSByteStoreVersionException	exception	NSByteStore.h	(-OpenStep,-NeXT) (40PR1)

NSCharacterConversionException	exception	NSString.h	(+OpenStep,+NeXT) (40PR1) (EOF11) (NS33)

NSCodingException	exception	NSException.h	(-NeXT) (EOF11) (NS33)

NSComparisonResult	typedef	NSObjCRuntime.h	(+NeXT) (40PR2) (40PR1) (EOF11) (NS33)

NSConnectionDeath	notification	NSConnection.h	(-OpenStep,-NeXT) (40PR1)	Use NSConnectionDidDieNotification instead

NSConnectionDidInitializeNotification	notification	NSConnection.h	(+NeXT) (P40PR1) (40PR2) (40PR1)

NSCopyMemoryPages	function	NSZone.h	(OpenStep,+NeXT) (EOF11) (NS33)

NSCurrencyString	default name	NSUserDefaults.h	(-OpenStep,NeXT) (40PR2)	Use NSCurrencySymbol instead

NSCurrencyString	default name	NSUserDefaults.h	(OpenStep,-NeXT) (40PR1)	Use NSCurrencySymbol instead

NSDateMissingTimeZone	exception	NSException.h	(-NeXT) (EOF11) (NS33)

NSDeallocateMemoryPages	function	NSZone.h	(OpenStep,+NeXT) (EOF11) (NS33)

NSDecimalNumberBehavior	class	NSDecimalNumber.h	(-NeXT) (P40PR1) (40PR2) (40PR1)

NSDecimalNumberBehavior	protocol	NSDecimalNumber.h	(-NeXT) (P40PR1) (40PR2) (40PR1)

NSDecimalNumberBehaviors	protocol	NSDecimalNumber.h	(+NeXT) (P40PR1) (40PR2) (40PR1)

NSDecimalNumberHandler	class	NSDecimalNumber.h	(+NeXT) (P40PR1) (40PR2) (40PR1)

NSDistantObjectRequest	class	NSConnection.h	(+NeXT) (40PR1)

NSEUCStringEncoding	constant	NSString.h	(-NeXT) (EOF11) (NS33)	Use NSJapaneseEUCStringEncoding instead

NSEqualRanges	function	NSRange.h	(OpenStep,+NeXT) (EOF11) (NS33)

NSExceptionBase	constant	NSException.h	(-NeXT) (EOF11) (NS33)

NSExtraRefCount	function	NSObject.h	(+OpenStep,+NeXT) (40PR1) (EOF11) (NS33)

NSFileGroupOwnerAccountName	dict. key	NSFileManager.h	(+NeXT) (40PR1)

NSFileGroupOwnerAccountNumber	dict. key	NSFileManager.h	(-NeXT) (40PR1)	Use NSFileGroupOwnerAccountName instead

NSFileOwnerAccountName	dict. key	NSFileManager.h	(+NeXT) (40PR1)

NSFileOwnerAccountNumber	dict. key	NSFileManager.h	(-NeXT) (40PR1)	Use NSFileOwnerAccountName instead

NSFullUserName	function	NSPathUtilities.h	(+NeXT) (40PR1) (EOF11) (NS33)

NSGetSizeAndAlignment	function	NSObjCRuntime.h	(+OpenStep,+NeXT) (40PR1) (EOF11) (NS33)

NSGroupAccount	class	NSAccount.h	(-NeXT) (40PR1)

NSHPUXOperatingSystem	constant	NSProcessInfo.h	(+NeXT) (40PR1)

NSHashStringLength	constant	NSString.h	(-OpenStep,-NeXT) (40PR1) (EOF11) (NS33)

NSISO2022JPStringEncoding	constant	NSString.h	(+NeXT) (P40PR1) (40PR2) (40PR1) (EOF11) (NS33)

NSISOLatin2StringEncoding	constant	NSString.h	(OpenStep,+NeXT) (EOF11) (NS33)

NSInconsistentArchiveException	exception	NSArchiver.h	(OpenStep,+NeXT) (EOF11) (NS33)

NSInternationalCurrencyString	default name	NSUserDefaults.h	(OpenStep,+NeXT) (P40PR1) (40PR2)

NSInternationalCurrencySymbol	default name	NSUserDefaults.h	(-NeXT) (P40PR1) (40PR2)	Use NSInternationalCurrencyString instead

NSIntersectsRect	function	NSGeometry.h	(+OpenStep,+NeXT) (40PR1)

NSInvalidReceivePort	exception	NSException.h	(-NeXT) (40PR1)	Use NSInvalidReceivePortException instead

NSInvalidReceivePortException	exception	NSException.h	(+NeXT) (EOF11) (NS33)

NSInvalidSendPort	exception	NSException.h	(-NeXT) (40PR1)	Use NSInvalidSendPortException instead

NSInvalidSendPortException	exception	NSException.h	(+NeXT) (EOF11) (NS33)

NSJapaneseEUCStringEncoding	constant	NSString.h	(OpenStep,+NeXT) (EOF11) (NS33)

NSLastException	constant	NSException.h	(-NeXT) (EOF11) (NS33)

NSLoadedClasses	constant	NSBundle.h	(+OpenStep,+NeXT) (P40PR1) (40PR2) (40PR1) (EOF11) (NS33)

NSLocalizedString	macro	NSBundle.h	(OpenStep,+NeXT) (EOF11) (NS33)

NSLocalizedStringFromTable	macro	NSBundle.h	(OpenStep,+NeXT) (EOF11) (NS33)

NSLocalizedStringFromTableInBundle	macro	NSBundle.h	(OpenStep,+NeXT) (EOF11) (NS33)

NSLogPageSize	function	NSZone.h	(OpenStep,+NeXT) (EOF11) (NS33)

NSMACHOperatingSystem	constant	NSProcessInfo.h	(+NeXT) (40PR1)

NSMakeRange	function	NSRange.h	(OpenStep,+NeXT) (EOF11) (NS33)

NSMallocException	exception	NSException.h	(OpenStep,+NeXT) (EOF11) (NS33)

NSNonRetainedObjectMapValueCallBacks	struct	NSMapTable.h	(+OpenStep,+NeXT) (40PR1)

NSNotFound	constant	NSObjCRuntime.h	(+NeXT) (40PR2) (40PR1) (EOF11) (NS33)

NSNotInArray	constant	NSArray.h	(-NeXT) (EOF11) (NS33)

NSOSF1OperatingSystem	constant	NSProcessInfo.h	(+NeXT) (40PR1)

NSObjCInadequateRuntimeInformation	exception	NSException.h	(-NeXT) (EOF11) (NS33)

NSOldStyleException	exception	NSException.h	(+NeXT) (EOF11) (NS33)

NSOpenStepRootDirectory	function	NSPathUtilities.h	(+NeXT) (40PR1) (EOF11) (NS33)

NSOpenStepUnicodeReservedBase	constant	NSCharacterSet.h	(OpenStep,+NeXT) (EOF11) (NS33)

NSOwnedObjectIdentityHashCallBacks	struct	NSHashTable.h	(+OpenStep,+NeXT) (40PR1)

NSOwnershipTransferException	exception	NSException.h	(-NeXT) (EOF11) (NS33)

NSPPLBecameDirty	notification	NSPPL.h	(-NeXT) (40PR1)	Use NSPPLDidBecomeDirtyNotification instead

NSPPLSaved	notification	NSPPL.h	(-NeXT) (40PR1)	Use NSPPLDidSaveNotification instead

NSPageSize	function	NSZone.h	(OpenStep,+NeXT) (EOF11) (NS33)

NSParseErrorException	exception	NSException.h	(-NeXT) (EOF11) (NS33)

NSPointFromString	function	NSGeometry.h	(+OpenStep,+NeXT) (40PR1)

NSPortInvalidation	notification	NSPort.h	(-NeXT) (40PR1)	Use NSPortDidBecomeInvalidNotification instead

NSPortNameRegistrationError	exception	NSException.h	(-NeXT) (EOF11) (NS33)

NSPortReceiveError	exception	NSException.h	(-NeXT) (40PR1)	Use NSPortReceiveException instead

NSPortReceiveException	exception	NSException.h	(+NeXT) (EOF11) (NS33)

NSPortSendError	exception	NSException.h	(-NeXT) (40PR1)	Use NSPortSendException instead

NSPortSendException	exception	NSException.h	(+NeXT) (EOF11) (NS33)

NSRangeFromString	function	NSRange.h	(+OpenStep,+NeXT) (40PR1) (EOF11) (NS33)

NSRealMemoryAvailable	function	NSZone.h	(OpenStep,+NeXT) (EOF11) (NS33)

NSRectFromString	function	NSGeometry.h	(+OpenStep,+NeXT) (40PR1)

NSRoundDownToMultipleOfPageSize	function	NSZone.h	(OpenStep,+NeXT) (EOF11) (NS33)

NSRoundUpToMultipleOfPageSize	function	NSZone.h	(OpenStep,+NeXT) (EOF11) (NS33)

NSShiftJISStringEncoding	constant	NSString.h	(+NeXT) (NS33)

NSShortDateFormatString	default name	NSUserDefaults.h	(+NeXT) (40PR1)

NSSizeFromString	function	NSGeometry.h	(+OpenStep,+NeXT) (40PR1)

NSSolarisOperatingSystem	constant	NSProcessInfo.h	(+NeXT) (40PR1)

NSStandardApplicationPaths	function	NSPathUtilities.h	(+NeXT) (40PR1) (EOF11) (NS33)

NSStandardLibraryPaths	function	NSPathUtilities.h	(+NeXT) (40PR1) (EOF11) (NS33)

NSSunOSOperatingSystem	constant	NSProcessInfo.h	(+NeXT) (40PR1)

NSTemporaryDirectory	function	NSPathUtilities.h	(+NeXT) (40PR1) (EOF11) (NS33)

NSThreadExiting	notification	NSThread.h	(-OpenStep,-NeXT) (40PR1) (EOF11)	Use NSThreadWillExitNotification instead

NSThreadWillExitNotification	notification	NSThread.h	(+OpenStep,+NeXT) (40PR1) (EOF11)

NSTimeIntervalSince1970	constant	NSDate.h	(OpenStep,+NeXT) (EOF11) (NS33)

NSUTF8StringEncoding	constant	NSString.h	(OpenStep,+NeXT) (EOF11) (NS33)

NSUTFStringEncoding	constant	NSString.h	(-NeXT) (EOF11) (NS33)	Use NSUTF8StringEncoding instead

NSUserAccount	class	NSAccount.h	(-NeXT) (40PR1)

NSUserDefaultsChanged	notification	NSUserDefaults.h	(-OpenStep,-NeXT) (40PR1)	Use NSUserDefaultsDidChangeNotification instead

NSUserDefaultsDidChangeNotification	notification	NSUserDefaults.h	(+OpenStep,+NeXT) (40PR1)

NSWillBecomeMultiThreadedNotification	notification	NSThread.h	(+OpenStep,+NeXT) (40PR1) (EOF11)

NSWinLatin1StringEncoding	constant	NSString.h	(-NeXT) (40PR2) (40PR1)	Use NSWindowsCP1252StringEncoding instead

NSWindows95OperatingSystem	constant	NSProcessInfo.h	(+NeXT) (40PR1)

NSWindowsCP1250StringEncoding	constant	NSString.h	(+NeXT) (40PR2) (40PR1) (EOF11) (NS33)

NSWindowsCP1251StringEncoding	constant	NSString.h	(+NeXT) (40PR2) (40PR1) (EOF11) (NS33)

NSWindowsCP1252StringEncoding	constant	NSString.h	(+NeXT) (40PR2) (40PR1) (EOF11) (NS33)

NSWindowsCP1253StringEncoding	constant	NSString.h	(+NeXT) (40PR2) (40PR1) (EOF11) (NS33)

NSWindowsCP1254StringEncoding	constant	NSString.h	(+NeXT) (40PR2) (40PR1) (EOF11) (NS33)

NSWindowsNTOperatingSystem	constant	NSProcessInfo.h	(+NeXT) (40PR1)

NSZoneFromPointer	function	NSZone.h	(OpenStep,+NeXT) (EOF11) (NS33)

NSZoneFromPtr	function	NSZone.h	(-NeXT) (EOF11)	Use NSZoneFromPointer instead

NS	VALRETURN	macro	NSException.h	(-OpenStep,-NeXT) (EOF11) (NS33)	Use NS	VALUERETURN instead

NS	VALUERETURN	macro	NSException.h	(+OpenStep,+NeXT) (EOF11) (NS33)

NXReadNSObjectFromCoder	function	NSCompatibility.h	(+NeXT) (P40PR1) (40PR2) (40PR1)

Nil	constant	NSObjCRuntime.h	(+NeXT) (EOF11) (NS33)

exception	variable	NSException.h	(-NeXT) (EOF11) (NS33)	Use localException instead for exception object in handler region

localException	variable	NSException.h	(OpenStep,+NeXT) (EOF11) (NS33)

obsolete	macro	NSObject.h	(-NeXT) (EOF11) (NS33)


Hooking Up Keyboard UI in Your Application


Important Information

OPENSTEP Enterprise Release 4.1  Copyright ©1996 by NeXT Software, Inc.  All Rights Reserved.

Complete Release Notes on NeXTanswers

The release notes that ship with this product are complete and up-to-date as of the time the CD-ROM was manufactured. Information about the release discovered since manufacture are continually being  incorporated into the release notes, which can be obtained from NeXTanswers. For the location of the most up-to-date release notes for this or any other NeXT product, request NeXTanswer #2455.

About NeXTanswers

NeXTanswers is an automated retrieval system that gives customers access to the latest product information, technical documents, drivers, and other software. You can access NeXTanswers through NeXT's website (http://www.next.com), or by:

Electronic mail: Send requests to nextanswers@next.com with a subject line of HELP to receive instructions on how to proceed.

Fax: Call 415-780-3990 from a touch-tone phone and follow instructions (you'll need to know the ID numbers of the files you want).

Anonymous FTP: Connect to FTP.NEXT.COM and read pub/NeXTanswers/README for further instructions.

 Call 415-780-2965, log in as "guest", and go to the Files section. From there you can download NeXTanswer documents.

Requests sent to NeXTanswers are answered electronically, and are not read or handled by a person. It does not answer your questions or forward your requests.

New Linker

The Microsoft linker is now the default for project builds with OPENSTEP Enterprise for Windows. This linker is the same one that ships with Visual C++. For information on this linker, consult the Visual C++ documentation.

Known Problems in Deployed Systems

The following two problems are known to have occured in systems configured for deployment as well as for development.

Reference:	72130

Problem:	Text could display incorrectly.

Description:	Depending on the length of the document you have and how fast you are typing, displayed text might sometimes have problems. For instance, you might get overlapping lines or large blank areas between two lines.

Workaround: 	Typing will usually fix this right away. Note that in all cases, even though the display is garbled, your document is still correct, so there's no need to exit or restart the application.

Reference:	71671

Problem:	"Flash active caption bar" visual warning option might cause applications to hang.

Description:	If you have enabled SoundSentry (under Accessibility Options in the Control Panel under NT 4.0), and turned on the "Flash active caption bar" visual warning option, applications could hang when they attempt to beep.

Workaround: 	None. Use one of the other visual warning options.

Uninstalling OPENSTEP Enterprise

The uninstaller supplied with OPENSTEP Enterprise doesn't remove OPENSTEP-specific references from your system environment variables. This can be done manually after uninstallation by simply deleting the NEXT_ROOT environment variable and removing all invalid references from both your Path and Lib environment variables.

If you would like more detailed instructions on how to make these changes, refer to the relevant step in "Uninstalling OPENSTEP for Windows" in the OPENSTEP Enterprise Installation Guide. Note that this guide is supplied in printed form only, and is packaged with the OPENSTEP Enterprise CD-ROM.


Interface Builder

OPENSTEP Enterprise Release 4.1  Copyright 1996 by NeXT Software, Inc.  All Rights Reserved.

This file contains release notes for Interface Builder distributed with OPENSTEP Enterprise Release 4.1.

Notes Specific to Release 4.1

New Features

This release of Interface Builder supports these new features:

•	Context Menus.  Interface Builder for Windows NT has a context menus within editable windows and panels. A context menu is activated by clicking the right mouse button within a window or panel. In this way, operations such as Cut, Copy, and Group can be performed.

•	Interface Styles.  Interface Builder has a new preference which permits nib files to be viewed and edited in either Mach or Windows user interface style. Nib files opened after a change in the interface style preference will have the new interface style.

•	Control mnemonics.  Interface Builder enables users to set mnemonics for user-interface controls.  In order to set a character in the title of a control to be a mnemonic, double-click the character while holding down the Alternate key.

•	OpenStep Compliance.  Interface Builder is OpenStep-compliant, and you can use it to create OpenStep nib files.

•	Custom Class Inspector.  You now use a new inspector display, the Custom Class Inspector, to specify a custom subclass of an object. For example, suppose you have defined a class MyButton to be a subclass of NSButton. To add an object of class MyButton to your interface, you do the following:

1. 	Define MyButton in the Classes view of the nib file window.

2. 	Drag the button from the Views palette to your interface.

3.	 Choose Custom Class from the pop-up list in the Inspector panel.

4. 	Select MyButton in the browser to set the class of the button.

Currently, this works only for NSView and NSWindow subclasses.

•	Connection Locking. Connection locking prevents connections from being deleted when a nib file is edited.  This feature is designed primarily for localization.  To turn connection locking on or off, use the Preferences panel.

•	Nib Dumping. A new tool, nibTool, prints the contents of a nib file in an ASCII format.  nibTool is located in /usr/bin. You can easily compare two versions of a nib file if you use this tool to create ASCII representations of each. Currently, nibTool does not support nib files that use objects from custom palettes.

•	Typed Outlets and Actions. The parser in Interface Builder has been improved, and many parsing bugs have been fixed.  In addition, you can now specify typed outlets.  Interface Builder considers any of the following to be an outlet when it appears in an interface:

id outlet;

id outlet1, outlet2, ...;

IBOutlet SomeClass *outlet;

IBOutlet SomeClass *outlet1, *outlet2, ...;

Typically, you will need to add the following to your interface to avoid compilation errors.

#define IBOutlet

You can also specify the type of the argument to an action, and you can specify the return type to of an action to be void.  Interface Builder considers any of the following to be an action:

- action:sender;

- (void)action:sender;

- action:(id)sender;

- (void)action:(id)sender;

- action:(SomeClass *)sender;

- (void)action:(SomeClass *)sender;

•	The layout of the standard palettes has changed.  There are two new views on the palettes, NSImageView and NSTableView.

Problems Fixed in This Release

These problems have been fixed in this release of Interface Builder:

•	Interface Builder now writes its defaults using the standard user defaults mechanism.

Known Problems

These problems exist in this release of Interface Builder:

•	Not all menu items in context menus are enabled even though they may be applicable.

•	Closing the last window when testing the interface causes Interface Builder to quit.

•	Miniaturizing windows may crash Interface Builder.

•	Under some circumstances, it becomes impossible to make a connection to an object in a window if that window overlaps another Interface Builder window.  You can work around the problem by moving the windows so that they don't overlap.

•	Alternate-clicking an object in the outline view can cause Interface Builder to crash.

•	Opening some NEXTSTEP Release 2 nib files may cause Interface Builder to crash.

•	Other NEXTSTEP Release 2 nib files containing bitmaps unknown to the Application Kit are not loaded correctly. As a workaround, open the nib file in a Release 3 Interface Builder and save it before opening it in 4.1 For a list of bitmaps that the Application Kit supports, see the file /NextLibrary/Frameworks/AppKit.framework/Headers/NSBitmapImageRep.h.

•	Interface Builder does not allow you to change the size of the document view when editing a ScrollView.

•	The context-sensitive help links don't work for anything in the palettes window, and they don't work in the ScrollView Attributes display.

•	Model files copied from a mail message are incorrectly referenced.  In Interface Builder, if you drag a model file in from a mail message, it turns into an entity controller.  Don't make a copy, and save the nib file.  Then drag the model file from the mail message into ~/Library/Models.  Go back into the nib file and delete the combined controller/data source object.  Then drag the model from ~/Library/Models into Interface Builder.  The resulting entity controller still references the model file in your mailbox.


Keyboard UI

OPENSTEP Enterprise Release 4.1  Copyright ©1996 by NeXT Software, Inc.  All Rights Reserved.

OPENSTEP Enterprise 4.1 includes a new feature called the “keyboard UI”.  Also known as keyboard navigation, this allows the user to navigate between fields and controls solely by use of the keyboard.  It also provides for changing the state of controls, scrolling, and pressing buttons using the keyboard.  Although it doesn’t eliminate the need for a mouse, it does allow a power user or someone performing data entry to increase their productivity when performing certain actions.

Using Keyboard UI

In some sense you are always using keyboard UI.  Whatever control you are focusing on generally is the target of your keyboard actions.  Controls show they are the focus in different ways:

•	Push buttons draw a dotted line around their titles and a black border:

 .

•	Radio buttons draw a dotted line around the current selection:

 .

•	Items in a list draw a dotted border around the current item:

  .

•	Text fields show a selection or blinking cursor.

To move to a different control, press the Tab key.  This will advance you to the next control in the keyboard UI navigation loop.  To move to the previous control, press Shift-Tab (also known as “backtab”).  Some controls, like the text object, use Tab to insert actual tab characters.  In these cases hold down the Control key as well.  So to move to the next control while typing text into a text object, type Control-Tab.

Some controls allow you to move around in them using the arrow keys.  For instance, in a matrix of button cells you may move down to the button below by pressing the down arrow key, and move to the button to the right by pressing the right arrow key.

In most cases, you use the spacebar to change the state of the control.  For example, if the current keyboard focus is on a button, you press the spacebar to click the button.  Likewise if you are focused on a checkbox then pressing the spacebar will toggle its state.  If you are in a list of items, pressing the spacebar will select the current item.  Pressing Shift-Space or Alt-Space modifies the selection in the same way that Shift-click and Alt-click do.  In some cases, the arrow buttons will modify the state.  In a set of radio buttons you arrow between the different possible selections.  You bring up a pop up button by pressing space, or hitting an arrow key, and then may arrow through the choices.

Controls may have mnemonics.  Visually, these appear as an underlined character in the title of a control.  For instance, this button has a mnemonic of “p”:

Pressing Alt-p will depress this button.  Mnemonics are case-insensitive.  If you aren’t currently on a control which accepts typing, then you can type the mnemonicÐin this case just “p”.  Conversely, if you are on a control, like the text object, which uses Alt-char to type special characters, you need to hold down Control as well.  So if you are typing in a text object, and wish to press the above button, you would type Alt-Control-p.  Note that under MS Windows the text object does not use the Alt key, so under MS Windows you need only type Alt-p.

Text fields may be used as labels.  A label is a non-editable text field that contains a mnemonic and allows the user to get to an associated control by typing that mnemonic.  For instance, in the following case the user may type Alt-a to get to “TheTextField”:

A window may have a default button.  This is the button which will be clicked when the Enter key is pressed.  It is indicated by having an extra black border.  Note that any button you tab to becomes the default button, but the original default button is reinstated when you tab to a different control.

You may dismiss Alert panels, and some others, by pressing Escape.  More panels will follow this behavior after PR2.

Hooking Up Keyboard UI in Your Application

Hooking up controls in your application to work with keyboard UI is very simple.  In fact, if you don’t hook anything up at all, then a default hookup is established at runtime.  However, this default setup may not be exactly what you want, and you are encouraged to hook up the keyboard UI yourself.

There are only two connections necessary for keyboard UI.  One is per view, the other per window.  Each view that wishes to be in the tabbing loop should connect its nextKeyView outlet to the view it wishes the user to move to when Tab is pressed.  Be careful to connect this up only to views; accidentally hooking this up to a cell in a matrix or a form is an error.  Also, be sure to connect everything up in a single loop.  Do not leave anything out, including labels.  The control a label points to must be its nextKeyView.

The second necessary connection is initialFirstResponder in NSWindow.  Since the keyboard UI architecture reuses the firstResponder mechanism, this specifies which control will be the “firstResponder” when a window is brought forward.  In other words, the “initialFirstResponder” is the control which gets focus when a window is brought on the screen.  Set this to something that the user would logically wish to access first.  For instance, the PrintPanel sets it the “number of copies” field and the SavePanel to the “filename” field.

Adding Keyboard UI to Your Controls

Chances are you will need to add little or no code to enable keyboard UI in your controls.  NSWindow and NSView do most of the work, all of which you will inherit.  They keep track of the current firstResponder (the view with the keyboard focus), moving between controls, processing and translating events, enabling and disabling the default button, and making the initialFirstResponder become first responder at the right time.

First, you should be sure that a control gives a visual indication of its first responder status.  As mentioned above, this may be a dotted highlight rect, a blinking cursor, or something appropriate for your specific control.

If you want your control to have a mnemonic you will need to implement this NSView method:

- (BOOL)performMnemonic:(NSString *)theString

It should do a case-insensitive compare on the passed string and the mnemonic it displays, and if they are the same perform the operation it would if it were clicked.  Returning YES means it performed the mnemonic.

Some controls are actually collections of controls, like NSMatrix.  They must implement:

- (void)selectNextKeyView:(id)sender

- (void)selectPreviousKeyView:(id)sender

to move to a new first responder when Tab or Shift-Tab is pressed.  These are optional responder methods that allow controls to hand select the next/previous key view.  If the next item to become key is in the control itself (say we are tabbing to another button in the matrix) then it stays first responder and just draws the new item with its key status.  If we are at the end of the control and need to make the next key view first responder, just ask the control’s window to do so ([[self window] makeFirstResponder:[self nextKeyView]]).

Preventing Keyboard UI

You may have some controls which you do not wish to become first responder when clicked.  For instance, it makes little sense for a toolbar to steal first responder when you click on one of its buttons to change the current tool.  To prevent a control from becomming first responder use the following methods on NSControl and NSCell:

- (void)setRefusesFirstResponder:(BOOL)flag;

- (BOOL)refusesFirstResponder;

So to prevent myButton from becomming first responder when clicked call:

[myButton setRefusesFirstResponder:YES];

The API at a Glance

NSWindow

- (void)setInitialFirstResponder:(NSView *)view

- (NSView *)initialFirstResponder

- (void)selectNextKeyView:(id)sender

- (void)selectPreviousKeyView:(id)sender

- (void)selectKeyViewFollowingView:(NSView *)aView

- (void)selectKeyViewPrecedingView:(NSView *)aView

- (NSSelectionDirection)keyViewSelectionDirection

- (void)setDefaultButtonCell:(NSButtonCell *)defButt

- (NSButtonCell *)defaultButtonCell

- (void)disableKeyEquivalentForDefaultButtonCell

- (void)enableKeyEquivalentForDefaultButtonCell

NSControl

- (void)setRefusesFirstResponder:(BOOL)flag;

- (BOOL)refusesFirstResponder;

NSView

- (BOOL)performMnemonic:(NSString *)theString

- (void)setNextKeyView:(NSView *)next

- (NSView *)nextKeyView

- (NSView *)previousKeyView

- (NSView *)nextValidKeyView

- (NSView *)previousValidKeyView

NSTextField, NSButton, NSBox

- (void)setTitleWithMnemonic:(NSString *)stringWithAmpersand

NSMatrix

- (void)setTabKeyTraversesCells:(BOOL)flag

- (BOOL)tabKeyTraversesCells

- (void)setKeyCell:(NSCell *)keyCell

- (id)keyCell

NSCell

- (BOOL)acceptsFirstResponder

- (void)setRefusesFirstResponder:(BOOL)flag;

- (BOOL)refusesFirstResponder;

- (void)setShowsFirstResponder:(BOOL)showFR

- (BOOL)showsFirstResponder

- (void)setMnemonicLocation:(unsigned)location

- (unsigned)mnemonicLocation

- (NSString *)mnemonic

- (void)setTitleWithMnemonic:(NSString *)stringWithAmpersand

NSButtonCell

- (void)setAlternateTitleWithMnemonic:(NSString *)stringWithAmpersand

- (void)setAlternateMnemonicLocation:(unsigned)location

- (unsigned)alternateMnemonicLocation

- (NSString *)alternateMnemonic

The API in Detail

NSWindow

- (void)setInitialFirstResponder:(NSView *)view

- (NSView *)initialFirstResponder

Specify the first responder when a window is brought on screen.

- (void)selectNextKeyView:(id)sender

- (void)selectPreviousKeyView:(id)sender

Cause the next (or previous) key view relative to the current first responder that accepts first responder to become first responder.

- (void)selectKeyViewFollowingView:(NSView *)aView

- (void)selectKeyViewPrecedingView:(NSView *)aView

Cause the next (or previous) key view relative to aView that accepts first responder to become first responder.

- (NSSelectionDirection)keyViewSelectionDirection

This is generally asked during a view’s “becomeFirstResponder” to figure out if we are tabbing or backtabbing to our view.  It is interesting for cases like matrix where we are interested whether we should select the first or last cell to become key.

- (void)setDefaultButtonCell:(NSButtonCell *)defButt

- (NSButtonCell *)defaultButtonCell

Set the button cell that will be pressed when the Enter key is hit.  It gives the button cell a “\r” key equivalent and remembers it for the methods below.

- (void)disableKeyEquivalentForDefaultButtonCell

- (void)enableKeyEquivalentForDefaultButtonCell

When we tab onto a button other than the default button cell, we wish temporarily to become the default button and act on the Enter key.  Thus in NSButton’s “becomeFirstResponder” we disable the current default button cell.  In “resignFirstResponder” we reenable it.  Likewise, when the window loses key we disable the key equivalent for the default button cell.

NSControl

- (void)setRefusesFirstResponder:(BOOL)flag;

- (BOOL)refusesFirstResponder;

If [self refusesFirstResponder] then always return NO for acceptsFirstResponder.  Otherwise use the normal logic to determine whether to accept first responder.

NSView

- (BOOL)performMnemonic:(NSString *)theString

Do a case-insensitive compare of theString and the view’s mnemonic string, if any.  If they are the same, perform the same action as if the view was clicked on (for example, for a button click the button; for a text field select the text).  If the mnemonic matched theString return YES.

- (void)setNextKeyView:(NSView *)next

- (NSView *)nextKeyView

- (NSView *)previousKeyView

These keep track of the singly-linked list of the keyboard navigation tabbing loop.  “previousKeyView” is calculated given the nextKeyView of the previous view.

- (NSView *)nextValidKeyView

- (NSView *)previousValidKeyView

Return the next or previous key view that accepts first responder.

NSCell

- (BOOL)acceptsFirstResponder

Return whether the cell may become first responder.  For instance, a disabled button cell may not become first responder but an enabled one may.  This is interesting for controls of mixed collections of cells, like matrix, which must ask their cells whether the control may become first responder.

- (void)setRefusesFirstResponder:(BOOL)flag;

- (BOOL)refusesFirstResponder;

If [self refusesFirstResponder] then always return NO for acceptsFirstResponder.  Otherwise use the normal logic to determine whether to accept first responder.

- (void)setShowsFirstResponder:(BOOL)showFR

- (BOOL)showsFirstResponder

Generally set by a control before causing the cell to draw, these tell the cell whether it should draw some visual indication of the control, and specifically the cell, being first responder.

- (void)setMnemonicLocation:(unsigned)location

- (unsigned)mnemonicLocation

Control the location of the mnemonic in a cell.  Location tells where the character(s) making up the mnemonic begin.  In some languages, multiple unichars in the title starting at mnemonicLocation make up a single graphical segment specifying the mnemonic.  NSNotFound indicates no mnemonic.

- (NSString *)mnemonic

The string representing the mnemonic.

- (void)setTitleWithMnemonic:(NSString *)stringWithAmpersand

Given a string containing a single ampersand, set the mnemonic location and the title (or string value) of the cell.  For instance, [myCell setTitleWithMnemonic:@ "Press &Me"] sets the title to “Press Me” with the “M” underlined as the mnemonic.

NSTextField, NSButton, NSBox

- (void)setTitleWithMnemonic:(NSString *)stringWithAmpersand

Given a string containing a single ampersand, set the mnemonic location and the title of the control.  For instance, [myButton setTitleWithMnemonic:@"Press &Me"] sets the title to “Press Me” with the “M” underlined as the mnemonic.

NSMatrix

- (void)setTabKeyTraversesCells:(BOOL)flag

- (BOOL)tabKeyTraversesCells

Sets whether the Tab key moves between cells in the matrix or moves to the next key view.  For instance, a matrix of text fields generally returns YES meaning you may tab between the text fields, but a matrix of radio buttons returns NO since you tab in and out of the matrix and use the arrow keys to change state.

- (void)setKeyCell:(NSCell *)keyCell

- (id)keyCell

Sets the cell which currently has the focus of the keyboard.  Sort of the “first responder cell” of the matrix.

NSButtonCell

- (void)setAlternateTitleWithMnemonic:(NSString *)stringWithAmpersand

- (void)setAlternateMnemonicLocation:(unsigned)location

- (unsigned)alternateMnemonicLocation

- (NSString *)alternateMnemonic

Identical to NSCell’s flavors except for NSButtonCell’s alternate title.

NSResponder

- (void)moveRight:(id)sender

- (void)moveLeft:(id)sender

- (void)moveUp:(id)sender

- (void)moveDown:(id)sender

Overridden by a subclass to move to a different selection or change state.

What about “nextText”?

You should no longer see a “nextText” outlet in IB, as these outlets automatically get converted to “nextKeyView” connections when a nib file is loaded.

Things to Note

NSTableView and NSSlider do not yet have keyboard UI implemented.

Some views did not used to become first responder, like NSButtons, but now do.  You should not rely upon the first responder in a given panel or window only becomming a text field, as you may have before.


Known Bugs and Limitations


Known Problems


Known Problems in Foundation

This section documents many of the known problems with Foundation in OPENSTEP 4.1.

_______________________________________________________________________________________

Reference:	47347

Platforms:	All

Problem:	NSArchiver and NSUnarchiver do not understand bitfields

Description:	Structures containing bitfields cannot be archived and unarchived.

Workaround:	Encode the members of a structure containing bitfields individually, encoding the bitfields as (unsigned) chars, shorts, or ints.

_______________________________________________________________________________________

Reference:	49084

Platforms:	All

Problem:	NSInvocation always retains the return value

Description:	NSInvocation always retains object return values. This can cause problems if the return value of a method is not a fully initialized object. Only +alloc and +allocWithZone: return uninitialized objects, so this is only a problem if you are using invocations to send either of those methods to a class object. If you write your own methods which return objects which are not fully initialized, you should avoid sending those messages with an NSInvocation or over Distributed Objects.

Workaround:	None

_______________________________________________________________________________________

Reference:	56644

Platforms:	All

Problem:	NSArchiver tracks char * pointers as equivalent to their contents

Description:	During archiving, NSArchiver keeps track of the char * strings it has seen by the address passed in for encoding. If one uses the stack or malloc() to construct a char *, then encodes it using the "*" type primitive (or @encode(char *)), the archiver only remembers the stack/malloc address, assuming it has constant contents.

Workaround:	Do not archive char * strings from the stack. Do not mutate or free malloc'd char * strings during archiving.

_______________________________________________________________________________________

Reference:	56659

Platforms:	All

Problem:	Proxies cannot be notification observers unless they are retained

Description:	Because NSNotificationCenter does not retain observers, registering an observer with a remote NSNotificationCenter (the observer would be a proxy in the remote process) will eventually cause a crash of the remote process when it tries to message a freed object, unless the remote process explicitly retains the proxy. This situation is a bit arcane, but the same type of problem can happen with other objects that don't retain objects that they know about.

Workaround:	Use an explicit protocol to tell the server (the process vending the notification center) to register and unregister an observer. The server then retains and registers the observer with the vended notification center, and unregisters and releases the observer when you tell it to do so. (If you don't include the unregister half of the protocol, the object will never be released.)

_______________________________________________________________________________________

Reference:	57984

Platforms:	All

Problem:	No way to get list of non-defaults command-line arguments

Description:	In NEXTSTEP 3.3 (and earlier releases), command-line arguments that looked like defaults were removed from NXArgv. The array returned by [[NSProcessInfo processInfo] arguments], NXArgv's replacement, however, contains all of the command-line arguments.

Workaround:	Code that expected defaults options to have been stripped from NXArgv will have to be rewritten to skip default option names and their values, or the arguments array will need to be processed to remove them before using it. The NSArgumentDomain dictionary can be retrieved from the standard user defaults instance to find out what NSUserDefaults interpreted as a default option.

_______________________________________________________________________________________

Reference:	59230

Platforms:	Mach, HP-UXTM, SolarisTM

Problem:	The main bundle can be allocated with the wrong directory

Description:	If an application is not launched with a full path, NSBundle attempts to create the main bundle instance with the current directory. If the application is launched from the command-line without a full path, and the application is not in the current directory (but found via the shell path), the main bundle will not be created, and the +mainBundle method will always return nil. This will also be a problem if the application is launched without a full path and changes its current working directory before the +mainBundle method is first sent. The Workspace Manager always launches applications as a full path, so this is not a problem for applications launched with Workspace Manager.

Workaround:	Launch the application with the full path; launch the app from the directory in which it exists (but not within an .app wrapper); create the main bundle instance before changing directories (if applicable); or within the app, change the working directory to the directory in which it lives and allocate the main bundle.

_______________________________________________________________________________________

Reference:	61520

Platforms:	All

Problem:	Handler is called twice when deleting a directory

Description:	NSFileManager's -removeFileAtPath:handler: method, when deleting a directory, calls the handler method -fileManager:shouldProceedAfterError: twice on each subdirectory or file error, and fails to call the handler for the top-level directory itself.

Workaround:	None

_______________________________________________________________________________________

Reference:	62235

Platforms:	All

Problem:	Can't search for characters case-insensitively

Description:	NSString's -rangeOfCharactersFromSet: ignores the NSCaseInsensitiveSearch flag. This also affects NSScanner's -scanCharactersFromSet:intoString: method when the scanner has been set to be case insensitive.

Workaround:	None

_______________________________________________________________________________________

Reference:	62812

Platforms:	All

Problem:	Changed defaults don't appear sometimes to have taken affect

Description:	The default NSUserDefaults domain search order places the NSArgumentDomain before the application's domain. This is usually desirable for reading defaults, but may not be if you set/change default values. If you set a value for a default that was passed as an option on the command-line, the value is correctly set/changed in the application's domain, but -objectForKey: will still return the value found in the NSArgumentDomain, because by default it is searched first.

Workaround:	There are various workarounds depending upon the application and its use of user defaults. The following options are relative to a particular NSUserDefaults instance (that is, if you create multiple user defaults instances, you'd have to do the workaround for each individually).

1.	Remove the NSArgumentDomain from the search list, perhaps after adding any keys it contains to the registration domain; command-line specified defaults will not be found, or not have priority over same-keyed defaults in the application's domain, however.

2.	Move the NSArgumentDomain after the application's domain; command-line specified defaults will not have priority over same-keyed defaults in the application's domain, however.

3.	Each time you set a default value, set it in the argument domain (difficult and not worth the trouble).

4.	Best solution: Create a subclass of NSUserDefaults. For each defaults instance created, create a new volatile domain, tell the instance about it (-setVolatileDomain:forName:) perhaps calling it "ChangedDefaults" (don't give it a name beginning with "NS"!), and insert it first in the domain search list of the new defaults instance. Override the -setObject:forKey: and -removeObjectForKey: methods to set/remove the value in the "ChangedDefaults" volatile domain, and then call [super ...] to do the same for the application domain. The following code illustrates what these override methods might look like:

- (void)setObject:(id)value forKey:(NSString *)defaultName {

NSDictionary *changedDomain;

id oldValue;

[super setObject:value forKey:defaultName];

changedDomain = [self volatileDomainForName:@"ChangedDefaults"];

oldValue = [changedDomain objectForKey:defaultName];

if (![oldValue isEqual:value]) {_// Something to do

NSMutableDictionary *newDomain;

newDomain = [[NSMutableDictionary allocWithZone:[self zone]]

initWithDictionary:changedDomain];

[newDomain setObject:value forKey:defaultName];

[self setVolatileDomain:newDomain forName:@"ChangedDefaults"];

[newDomain release];

}

}

- (void)removeObjectForKey:(NSString *)defaultName {

NSDictionary *changedDomain;

id oldValue;

[super removeObjectForKey:defaultName];

changedDomain = [self volatileDomainForName:@"ChangedDefaults"];

oldValue = [changedDomain objectForKey:defaultName];

if (oldValue) {_// Something to do

NSMutableDictionary *newDomain;

newDomain = [[NSMutableDictionary allocWithZone:[self zone]]

initWithDictionary:changedDomain];

[newDomain removeObjectForKey:defaultName];

[self setVolatileDomain:newDomain forName:@"ChangedDefaults"];

[newDomain release];

}

}

_______________________________________________________________________________________

Reference:	64605

Platforms:	HP-UXTM, SolarisTM

Problem:	NSBundles cannot dynamically load code

Description:	Unlike NeXT's implementations of OpenStep on other platforms, Foundation in PDO for HP-UXTM and SolarisTM cannot dynamically load code. This is due to limitations in the compiler and Objective C runtime, which we hope to resolve in a future release.

Workaround:	None

_______________________________________________________________________________________

Reference:	66411

Platforms:	SolarisTM

Problem:	Formatted floats sometimes lose sign

Description:	Formatted strings created with the NSString methods like +stringWithFormat: lose the sign of floats formatted with %f (and %g) in some cases. For instance, [NSString stringWithFormat:@"%f", -2.3e-2] results in @"0.023000". The situations in which this occurs have not been fully qualified.

Workaround:	Use sprintf() to create the character string with the desired format, then create the NSString from that with +stringWithCString:.

_______________________________________________________________________________________

Reference:	66538

Platforms:	All

Problem:	NSString +stringWithFormat: doesn't work with %p or some formatting flags

Description:	Unlike what the documentation says, NSString does not understand all ANSI C printf()-style formatting escapes and flags, and never has.

Workaround:	Use sprintf() to create the character string with the desired format, then create the NSString from that with +stringWithCString:.

_______________________________________________________________________________________

Reference:	66766

Platforms:	All

Problem:	NSBundle doesn't load _profile and _debug binaries in bundles

Description:	NSBundle does not attempt to load code from debug or profile versions of their binary code, which the makefiles give the _debug and _profile suffixes, respectively. If the non-debug/non-profile binary doesn't exist in the bundle, no code will be loaded. NSBundle doesn't care how the binary has been compiled, it just only looks for the file with the name given by the NSExecutable key in the Info.plist file in the Resources directory.

Workaround:	[Mach, SolarisTM, HP-UXTM]: Create a symbolic link named without the _profile or _debug suffix to the _profile or _debug binary at the top level of the bundle directory. [All platforms]: Move the _profile or _debug binary to a file of the same name without that suffix. [All platforms]: Modify the value of the NSExecutable key in the Info.plist file to include the desired _profile or _debug suffix.

_______________________________________________________________________________________

Reference:	68449

Platforms:	WindowsTM

Problem:	Cannot get a proxy for a distributed OLE object using OPENSTEP D.O.

Description:	When trying to get a proxy for an OLE object, you may get the following error: "deserializeObjectAt: class `NSDistantIDispatchProxy' not loaded".

Workaround:	Include nxorb.m (from NextDeveloper/Libraries) in your client. Although the D'OLE Developer's Guide states that nxorb.m is only needed for use with NXConnections, it's needed in some circumstances for NSConnections as well.

_______________________________________________________________________________________

Reference:	71118

Platforms:	All

Problem:	Collections that contain themselves don't describe

Description:	Sending the -description method to collections which contain themselves, or contain objects that contain the collection, causes infinite recursion.

Workaround:	None

_____________________________________________________________________________________________________


Known Problems in This Release (Windows and Mach)


Known Problems in This Release (Windows)


Method Return Type Changes in Foundation

CLASS/PROTO	HEADER	METHOD	OLD RET. TYPE	NEW RET. TYPE

NSBundle	NSBundle.h	-classNamed:	(id)	(Class)	(NeXT) (EOF11) (NS33)

NSBundle	NSBundle.h	-principalClass	(id)	(Class)	(NeXT) (EOF11) (NS33)

NSCalendarDate	NSDate.h	+calendarDate 	(NSCalendarDate *)	(id)	(NeXT) (40PR1)

NSCalendarDate	NSDate.h	+dateWithString:calendarFormat:	(NSCalendarDate *)	(id)	(NeXT) (40PR1) (EOF11) (NS33)

NSCalendarDate	NSDate.h	+dateWithString:calendarFormat:locale:	(NSCalendarDate *)	(id)	(NeXT) (40PR1)

NSCalendarDate	NSDate.h	+dateWithYear:month:day:hour:minute:second:timeZone:   (NSCalendarDate *)  (id)	(NeXT) (40PR1) (EOF11) (NS33)

NSDate	NSDate.h	+date	(NSDate *)	(id)	(NeXT) (40PR1) (EOF11) (NS33)

NSDate	NSDate.h	+dateWithTimeIntervalSince1970:	(NSDate *)	(id)	(NeXT) (40PR1)

NSDate	NSDate.h	+dateWithTimeIntervalSinceNow:	(NSDate *)	(id)	(NeXT) (40PR1) (EOF11) (NS33)

NSDate	NSDate.h	+dateWithTimeIntervalSinceReferenceDate:  (NSDate *)	(id)	(NeXT) (40PR1) (EOF11) (NS33)

NSDate	NSDate.h	+distantFuture	(NSDate *)	(id)	(NeXT) (40PR1) (EOF11) (NS33)

NSDate	NSDate.h	+distantPast	(NSDate *)	(id)	(NeXT) (40PR1) (EOF11) (NS33)

NSDate	NSDate.h	-addTimeInterval:	(NSDate *)	(id)	(NeXT) (EOF11) (NS33)

NSDate	NSDate.h	-initWithTimeInterval:sinceDate:	(NSDate *)	(id)	(NeXT) (40PR1) (EOF11) (NS33)

NSDate	NSDate.h	-initWithTimeIntervalSinceNow:	(NSDate *)	(id)	(NeXT) (40PR1) (EOF11) (NS33)

NSDecimalNumber	NSDecimalNumber.h  -initWithDecimal:	(NSDecimalNumber *)	(id)	(OpenStep,NeXT) (40PR2) (40PR1)

NSDecimalNumber	NSDecimalNumber.h  -initWithMantissa:exponent:isNegative:  (NSDecimalNumber *)	(id)	(OpenStep,NeXT) (40PR2) (40PR1)

NSDecimalNumber	NSDecimalNumber.h  -initWithString:	(NSDecimalNumber *)	(id)	(OpenStep,NeXT) (40PR2) (40PR1)

NSDecimalNumber	NSDecimalNumber.h  -initWithString:locale:	(NSDecimalNumber *)	(id)	(OpenStep,NeXT) (40PR2) (40PR1)

NSDictionary	NSFileManager.h	-filePosixPermissions	(unsigned int)	(unsigned long)	(NeXT) (40PR1)

NSDictionary	NSFileManager.h	-fileSize	(long long)	(unsigned long long)	(NeXT) (40PR1)

NSDictionary	NSFileManager.h	-fileSystemFileNumber	(unsigned int)	(unsigned long)	(NeXT) (40PR1)

NSDictionary	NSFileManager.h	-fileSystemNumber	(unsigned int)	(unsigned long)	(NeXT) (40PR1)

NSMethodSignature	NSMethodSignature.h  -methodReturnType	(char *)	(const char *)	(OpenStep,NeXT) (40PR1)

NSMutableString	NSString.h	+stringWithCapacity:	(NSMutableString *)	(id)	(OpenStep,NeXT) (40PR1) (EOF11) (NS33)

NSNotification	NSNotification.h	+notificationWithName:object:	(NSNotification *)	(id)	(NeXT) (EOF11) (NS33)

NSObject	NSObject.h	+initialize	(id)	(void)	(NeXT) (EOF11) (NS33)

NSObject	NSObject.h	+load	(id)	(void)	(NeXT) (EOF11) (NS33)

NSObject	NSObject.h	+superclass	(id)	(Class)	(NeXT) (EOF11) (NS33)

NSObjectProtocol	NSObject.h	-superclass	(id)	(Class)	(NeXT) (EOF11) (NS33)

NSPPL	NSPPL.h	+pplWithPath:create:readOnly:	(NSPPL *)	(id)	(NeXT) (40PR1)

NSPPL	NSPPL.h	+pplWithPath:fromPPLData:readOnly:	(NSPPL *)	(id)	(NeXT) (40PR1)

NSString	NSString.h	+localizedStringWithFormat:...	(NSString *)	(id)	(OpenStep,NeXT) (40PR1)

NSString	NSString.h	+stringWithCString:	(NSString *)	(id)	(OpenStep,NeXT) (40PR1) (EOF11) (NS33)

NSString	NSString.h	+stringWithCString:length:	(NSString *)	(id)	(OpenStep,NeXT) (40PR1) (EOF11) (NS33)

NSString	NSString.h	+stringWithCharacters:length:	(NSString *)	(id)	(OpenStep,NeXT) (40PR1) (EOF11) (NS33)

NSString	NSString.h	+stringWithContentsOfFile:	(NSString *)	(id)	(OpenStep,NeXT) (40PR1)

NSString	NSString.h	+stringWithFormat:...	(NSString *)	(id)	(OpenStep,NeXT) (40PR1) (EOF11) (NS33)

NSTask	NSTask.h	-standardInput	(NSPosixFileDescriptor *)	(id)	(NeXT) (P40PR1) (40PR2)

NSTask	NSTask.h	-standardOutput	(NSPosixFileDescriptor *)	(id)	(NeXT) (P40PR1) (40PR2)

NSTask	NSTask.h	-standardError	(NSPosixFileDescriptor *)	(id)	(NeXT) (P40PR1) (40PR2)

NSTask	NSTask.h	+launchedTaskWithLaunchPath:arguments:  (id)	(NSTask *)	(NeXT) (P40PR1) (40PR2)

NSTimeZone	NSDate.h	+timeZoneWithAbbreviation:	(NSTimeZone *)	(NSTimeZoneDetail *)	(NeXT) (EOF11) (NS33)

NSUserDefaults	NSUserDefaults.h	-searchList	(NSMutableArray *)	(NSArray *)	(OpenStep,NeXT) (40PR1)

Object	NSCompatibility.h	+poseAsClass:	(id)	(void)	(NeXT) (NS33)


New Features


New Features for 4.0


New Features for 4.1


Notes for Users of Previous Foundation Releases


Posix

A number of the functions provided by the Visual C++ posix layer do not have the behavior that standard posix platforms provide. This section lists the differences that we are aware of.

int chmod (const char* path, mode_t mode);

int fchmod (int fd, int mode);

int stat (char* path, struct stat* buf);

int lstat (char* path, struct stat* buf);

int fstat (int fd, struct stat* buf);

The NTFS and FAT file systems do not have permission values corresponding to the posix mode flags, so the above posix calls approximate to the best of their ability. In particular:

•	The flags for owner, group, and world are all identical. Changing the owner flags changes the group and world flags as well.

•	The “execute” bit is set for all directories and all paths ending in .exe, .cmd, or .bat, and for only these paths.

•	The “read” bit is always 1 (even if the NT security functions have been used to make the file unreadable)

•	The “write” bit is always 1 for directories mounted across the network.

Thus, the only bit that may be modified is bit 0400 (owner-write). The NT-provided constants _S_IREAD and _S_IWRITE may be used to toggle this bit.

int unlink (const char* path);

int rmdir (const char* path);

Whether a file or directory can be deleted depends on the write permissions of the file or directory itself, not of the directory which contains it.

int rename (const char* old, const char* new);

If there is already a file with the name new then this function fails rather than overwriting the file.

Warning: Simply deleting new before calling rename() is extremely dangerous, since if old and new differ only in case you will delete old.

(*signal(int sig, void (*func)(int)))(int);

Don’t use signal() to register handlers for the SIGINT signal. Use the windows function SetConsoleCtrlHandler() instead, and note that the function given to SetConsoleCtrlHandler() is of type int, not void. To get posix-like behavior this function should always return TRUE.

int spawnvpe (int mode, const char* command, const char* const* args,

const char* const* environment);

Occasionally this function will fail with errno=22 for no apparent reason. When this happens, just change the size of the environment block (by adding, removing, or changing an environment variable) and call it again. The second call will succeed.

utime() will return errors on read-only files and directories.


Preventing Keyboard UI


Printing

OPENSTEP Enterprise Release 4.1  Copyright ©1996 by NeXT Software, Inc.  All Rights Reserved.

The following notes relate to printing, and augment those found in the AppKit Release Notes.

Known Problems in This Release

Reference:	59276

Problem:	Default printer in NEXTSTEP 3.3 vs. OPENSTEP Enterprise apps

Description:	Different default mechanisms are used for NEXTSTEP 3.3 and OPENSTEP Enterprise 4.1 applications. As a result, if you select a printer in TextEdit, it will not be the default printer in Edit.

Windows-Specific Notes

Third-party software is required in order to print to non-PostScript printers from OPENSTEP Enterprise applications.


Problems Fixed in This Release


Project Builder

OPENSTEP Enterprise Release 4.1  Copyright 1996 by NeXT Software, Inc.  All Rights Reserved.

This file contains release notes for the Project Builder application distributed with OPENSTEP Enterprise 4.1. It includes information specific to OPENSTEP for Mach and to OPENSTEP for Windows as well as information general to both platforms.

Project Builder has undergone a radical redesign since NEXTSTEP 3.3. Its main window integrates a project browser with a full-featured code editor. You can bring up panels for building, debugging, finding information in the project, and setting project attributes. To familiarize yourself with the new Project Builder's capabilities and features, you can do one of the following.

•	On Mach, choose the Help command from the Info menu. This launches a Digital Librarian bookshelf containing the on-line book OpenStep Development: Tools and Techniques.

•	On Windows, choose the How To command from the Help menu. This launches a Windows Help version of the same book.

New Features for 4.1

New Makefiles

Project Builder includes new makefiles that offer several advantages over the previous ones. They:

Build projects with lower overhead.

Fix a number of extensibility problems.

Allow a higher degree of parallelism with gnumake -j.

Make it easier to diagnose problems.

When you first open a project that uses the old makefiles, Project Builder displays a panel that lets you :

Convert immediately to the new makefiles.

Keep your current makefiles.

Defer the decision to later.

If you convert to the new makefiles,  the project defines this path to them in MAKEFILEDIR:

$NEXT_ROOT/NextDeveloper/Makefiles/pb_makefiles

The original 4.0 Makefiles are located in this directory:

 	$NEXT_ROOT/NextDeveloper/Makefiles/project

Currently, you can override the MAKEFILEDIR attribute for your project in Makefile.preamble by setting it to the desired directory. Or you can edit the MAKEFILEDIR attribute in PB.project, but not through the user interface of Project Builder.  You are strongly encouraged to convert your projects to the new makefiles if that is feasible. For instance, a new facility that automatically generates .def files (see below) depends on these makefiles. However, you might keep older makefiles intact for those exceptional projects that depend upon unique implementation details in the project makefiles.

Microsoft Linker

The Microsoft linker is now the default for projects on Windows built with Project Builder. This is the same linker that ships with Visual C++.  For information on using the linker, consult the Visual C++ documentation. See the following item, "Automatic Generation of .def Files," for a related issue.

Automatic Generation of .def Files

On Windows, the Microsoft linker requires symbols exported from a framework DLL to be explictly specified. One way of doing this is in a .def file in the project (for example, "MyFramework.def"). In prior releases, this file had to be manually created. Project Builder now generates a .def file for frameworks and dynamic libraries (that is, library projects producing DLLs).  It re-creates the file the first time a project is built and, thereafter, updates it every time an object file changes.  To get this feature, you must update to the new makefiles (See "New Makefiles," above).

If you currently have a .def file for a framework, and it is not highly customized, delete it and let Project regenerate it for you. Otherwise, leave it where it is. Project Builder creates a .def file only if there isn't one already in the project.

The .def file that Project Builder creates is comprehensive, so if you want to create a customized .def file that is a subset of it, first build your project. Then add the generated .def file in derived_src to Supporting Files in your project and edit it as necessary.

Note 1:  You should use the CONSTANT keyword instead DATA in your .def file. The export of framework functions also requires a little extra code.  For more on both of these items, see "Known Problems in this Release, " below.

Note 2:  If you have prerelease versions of OPENSTEP 4.1 in which you used Makefile.preamble-winnt and Makefile.postamble-winnt to manually generate .def files,  you can delete these files and now use Project Builder's automatic .def generation facility.  Remember to remove all references to items involved in manual .def generation, particularly where your Makefiles include the platform-specific makefiles. Do this by disabling the option in your respective pûeamble and postamble files. For example:

#-include Makefile.preamble-$(PLATFORM_OS)

Specifying Installation Directories for Dynamic Libraries

On Windows, the makefiles for dynamic-library projects (that is, projects with "LIBRARY_STYLE = DYNAMIC") put the two files generated by the project in different locations. The .dll file is installed in INSTALLDIR and the .lib file is installed in the location for libraries that are imported into executable. You can specify this latter location in Makefile.preamble by setting IMPORT_LIBRARY_DIR to the correct path.

New Features for 4.0

Some or all of these new features may exist in the Windows version of Project Buiilder depending on its state at the time of the release.

•	The new Launcher Panel allows you to run or debug executables built by the project.

•	Printing is now supported.

•	The Build Attributes Inspector  allows you to specify OS specific values for compiler flags, linker flags, installation and build directories, and build tool.

•	The Build Options panel values persist across invocations of Project Builder. The values you specify on this panel are saved per-user, per-project.

•	In the Project Attributes Inspector  for an application project, you can specify a help file and icons for both NT (.ico, .ICO) and Mach (.eps, .tiff).

•	Project Builder by default sets tab stops at regular intervals of eight spaces each. There is now a dwrite, ªtabStopCharsº, that allows you alter this interval to any desired number of spaces, as long as that number is greater than zero.

4.1 Conversion Note

The _main.m files of 3.x applications have to be manually converted to the new _main.m content. To do this, copy the _main() code from existing 4.1 projects or create a new project and copy its _main() code.

#import <AppKit/AppKit.h>

int main(int argc, const char *argv[]) {

return NSApplicationMain(argc, argv);

}

Known Problems in this Release - Windows

These problems are known to exist with this release on Windows:

Reference:	72344

Problem:	Installation of .lib file in static library projects.

Description:	In static library projects (LIBRARY_STYLE=STATIC), the .lib file gets installed twice, once in the INSTALLDIR and once in the location specified by IMPORT_LIBRARY_DIR in Makefile.preamble. To have the .lib file installed only in the desired location (INSTALLDIR), set IMPORT_LIBRARY_DIR to INSTALLDIR.

Reference:	71975

Problem:	The libtool utility does not recognize the -read_only_relocs flag.

Description:	A serious side effect of this bug is that this option causes libtool to ignore all subsequent flags.  Currently there is no workaround except for not using this flag.

Reference:	69061

Problem:	Builds will fail if NEXT_ROOT has been modified to contain backward slashes.

Description:	The installer specifies NEXT_ROOT with forward slashes, for example:

C:/NeXT/

Do not edit this variable in the Environment section of the System control panel, even if to change the forward slashes to backward slashes.

Reference:	72307

Problem:	The Microsoft linker emits a bogus warning about CONSTANT keywords.

Description:	When you build framework projects, you will see messages complaining about the use of CONSTANT keywords in your .def file. Because of problems with the linker, CONSTANT should be used in place of DATA. You can ignore the warnings.

Reference:	72308

Problem:	Automatically generated .def files do not include public exported functions and variables.

Description:	In creating the .def file for frameworks and dynamic libraries (DLLs), Project Builder handles Objective-C symbols and data but not functions or variables. If you have functions in your framework that need to be callable from the outside,  or variables that should be externally accessible, define certain macros in a header file and then use them in your function declarations. These macros allow you to export non-static functions and variables from the DLL (FRAMEWORK_EXTERN) or to declare them as extern, but not exported (FRAMEWORK_PRIVATE_EXTERN).

Make a header file for each framework with functions and variables you wish to export (FrameworkDefines.h), and in it write the following macros (substitute your own framework name for FRAMEWORK):

#ifndef _FRAMEWORKDEFINES_H

#define _FRAMEWORKDEFINES_H

#if defined(WIN32)

//

// For Windows

//

#ifndef _FRAMEWORK_BUILDING_DLL

#define _FRAMEWORK_WINDOWS_DLL __declspec(dllimport)

#else

#define _FRAMEWORK_WINDOWS_DLL __declspec(dllexport)

#endif

#ifdef __cplusplus

#define FRAMEWORK_EXTERN _FRAMEWORK_WINDOWS_DLL extern "C"

#define FRAMEWORK_PRIVATE_EXTERN extern "C"

#else

#define FRAMEWORK_EXTERN _FRAMEWORK_WINDOWS_DLL extern

#define FRAMEWORK_PRIVATE_EXTERN extern

#endif

#else

//

// For MACH and PDO

//

#ifdef __cplusplus

// This isn't extern "C" because the compiler will not

// allow this if it has seen an extern "Objective-C"

#define FRAMEWORK_EXTERN extern

#define FRAMEWORK_PRIVATE_EXTERN __private_extern__

#else

#define FRAMEWORK_EXTERN extern

#define FRAMEWORK_PRIVATE_EXTERN __private_extern__

#endif

#endif

You need to import this header in all your other headers and declare your function prototypes accordingly. Then, before building your framework, specify "-DFRAMEWORK_BUILDING_DLL" in the Compiler Flags field of the Build Attributes inspector.

Additionally on Windows, Project Indexing doesn't work and, because of this, the "Definitions" and "References" searches in the Project Find Panel don't work either.

Known Problems in this Release - Mach and Windows

These problems are known to exist with this release on both Mach and Windows:

•	When Escape is defined as the Meta key in Preferences (and Tab is bound to indentation), Escape-/ (slash) does not cycle through all possible expansions (50288).

•	Queries in the Project Find panel for macro references do not find existing uses of macros (55187).

•	Comparing autosaved and last-saved versions of files in FileMerge does not work (56892).

•	Header files in Framework projects do not become Public by default (56924).

•	Renaming a subproject doesn't rename the directory the subproject lives in (57211).

•	Cannot switch to a second view when no files have been loaded into the code editor (57698).

Workaround—After selecting a text file in the upper browser, do cmd-1 cmd-2 to switch back to a single view and then split it again so it can double the text file in the upper view.

•	Indexing generates an error if a header file is empty (57790).

•	Build errors in tear-off windows appear in the main editing view (58863).

•	An exception may be raised when running a new executable (that is after selecting a different executable from the Launcher Options panel) with no arguments selected, and the previous executable had arguments. The work around is to deselect the argments from the old executable before selecting the new one.

•	Breakpoints on functions or methods without debugging information are not display in the breakpoint inspector. (67785)

•	Moving a breakpoint icon does not update the line number in the Breakpoint inspector. however, the location of the breakpoint is updated in gdb. (67712).


Samba

OPENSTEP Enterprise Release 4.1  Copyright 1996 by NeXT Software, Inc.  All Rights Reserved.

This release of OPENSTEP Enterprise includes an optional "Samba" package. Samba is a public domain implementation of a LanManager server for UNIX machines. The version provided is 1.9.15p6, which is the most current at the time of the release.

This package has been prepared 3-way FAT. Install the Samba files using Installer.app; they will be installed into /usr/samba. After running the installer package, you will have to run the install_samba script, located in /usr/samba, in order to finish the installation process. This script must be run as root and will make service entries in the /etc/inetd.conf file as well as two entries in NetInfo in /services. See the README.OPENSTEP file in /usr/samba for more information.

Samba can be configured in one of two ways. The first is to have it run as an inetd service; this is the way that it's currently configured. The other way is to have it run as a daemon from one of your rc files. Running it as an inetd service is slightly slower, but provides a more reliable server because if a server is killed or dies, a new one will automatically be started up.

For more information about Samba in general or specifics about its configuration files, please refer to the man pages provided. man samba displays the main man page and lists all of the programs that come as part of the package. man smb.conf will give specifics about the Samba configuration file (a default one is provided in /usr/samba/lib if you don't already have one).


Shell

Known Problems in This Release

This section lists known problems with the Bourne shell that is included with  OPENSTEP Enterprise.

Reference:	56415

Problem:	attempt to patch together ‘single-quoted argument string’

Description:	The shell doesn’t handle single quotes when invoked from the Windows command shell, so commands like the following may have unexpected results:

C:>/NeXT/NextLibrary/Executables/sh.exe -c ’echo hello’

Currently, the shell ends up with the following arguments:

argv[1]: "-c"

argv[2]: "’echo"

argv[3]: "hello’"

This problem also occurs if the shell is launched via CreateProcess().

Workaround:	The command works correctly if double quotes are used (C:>sh -c "echo hello") or if the command is entered from within SH.EXE rather than from within CMD.EXE ($sh -c ’echo hello’).

Reference:	None

Problem:	chmod doesn’t work on NT

Description:	The chmod command doesn’t change file access privileges. For instance, if you try to add “exec” privilege to a series of files on an NT machine, chmod reports that it set the requested privileges. A quick check of the file access privileges, however, shows that the “exec” privilege wasn’t actually set.

Workaround:	None.

Reference:	None

Problem:	tar rewinds the file pointer before writing to a redirect file

Description:	When tar redirects standard output to a file, it appears to rewind the file pointer before writing to the redirect file. For example, in the following script file the output of the second tar operation goes to the very beginning of the file c:/tmp/log, overwriting any existing file contents. This continues for the number of lines generated by the tar operation. Any lines in this file in excess of the number of lines output by tar aren’t affected.

cd $HOME

tar cf c:/tmp/t.tar .

cd c:/tmp/out

tar xvpf c:/tmp/t.tar  >> c:/tmp/log 2>&1


TextEdit

OPENSTEP Enterprise Release 4.1  Copyright ©1996 by NeXT Software, Inc.  All Rights Reserved.

TextEdit is a new application based on the new text system. In addition to the standard text editing features in the 3.3 Edit application, it provides:

•	"Wrap to Page" mode. This mode causes the document to be wrapped to the current page size (as opposed to the window size), and thus shows you a simple WYSIWYG representation of your pages. This mode also allows zooming.

•	Support for new text object features such as kerning, ligatures, and baseline offsets.

•	Ability to read/write plain text files in different 8-bit character encodings and Unicode. Coupled with the Kanji support in the new text object, you can read/write/edit Kanji files created by 3.3J or 4.1J. (You will need Kanji fonts and input manager.)

The alternate encoding to apply to a file is specified by a popup in the Open or Save panels. The default item, "Default," tells TextEdit to use either the default 8-bit encoding of the system or Unicode. Other choices let you select different encodings. You can also set the default setting of this popup via the Preferences panel.

Sources to TextEdit are available with the developer software, in /NextDeveloper/Examples/AppKit/TextEdit.

Known Problems in This Release

Reference:	58895

Problem:	Tabs in plain text mode

Description:	Tabs in a plain text window are by default set to a multiple of the font width. However this setting isn't readjusted when the font is changed, so the tabs get out of sync.

Workaround: 	Either don't change the font of a plain text window on the fly, or change it via defaults and restart the application.

Reference:	58741

Problem:	Displaying unrenderable characters too slow

Description:	When given characters which are not valid for the current font, the text system might spend too much time trying to find a font to render them. This means that files with random binary data could take a long time to load.

Workaround: 	Avoid binary files. A few binary characters are probably fine, and will be displayed as boxes, but a total binary file (for instance, an executable), could keep TextEdit busy for a while.

Reference:	None

Problem:	Encoding popup in Open/Save panels not available under NT3.51

Description:	Because accessory views aren't supported under NT3.51, there is no encoding popup in the Open/Save panels

Workaround: 	You can use the popup in the Preferences panel to set the default choice for the popup, which will then be used when files are opened or saved.

In addition, please refer to the Application Kit release notes for the new text system bugs.


The API at a Glance


The API in Detail


Things to Note


TrueType Fonts

OPENSTEP Enterprise Release 4.1  Copyright ©1996 by NeXT Software, Inc.  All Rights Reserved.

This file contains release notes for the 4.1 TrueType font support. TrueType Font support is new for the 4.1 release.

ttf2font

TrueType font files can be converted to font files which are usable by the OPENSTEP Enterprise WindowServer and AppKit. The ttf2font command line utility

converts a TrueType font file to a font directory which contains the Postscript Type 42 font definition as well as the Adobe Font Metrics file. The command line syntax is as follows

ttf2font [-o outputPath] trueTypeFont.ttf

where

       -o outputPath 	Output path where .font files will be placed.

For example, the command line

ttf2font -o ~/Library/Fonts TIMES.TTF

converts the TrueType font file TIMES.TTF and places the resultant .font directory into the ~/Library/Fonts directory using standard encoding.

More advance options are also available and are as follows;

- v 	Set to verbose mode where all errors and messages are printed to standard output.

- e encoding 	Use a specific encoding scheme, where encoding is one of

nextstep 	Nextstep encoding

standard 	Abobe standard encoding

isolatin1 	ISO latin 1 encoding

symbol 	Symbol encoding

font 	Font-specific encoding

Encoding schemes stored within the font file are font specific encoding schemes. The font vendor is responsible embeding a suitable encoding scheme for your platform.

Specifiying an encoding scheme other than font, causes the program to ignore the font specific encoding schemes stored within the file.

-p platformID 	Within a TrueType font file there are several tables which contain font specific encoding schemes.

-s platformSpecificID	These encoding schemes are organized by platform and there can be more that one encoding scheme stored within a file, each identifying a different platform.

These options allow you to override the default platform. The platformID and platformSpecificID pair must identify a valid encoding scheme store within the file. The  -v option  allows you to observe the platform encoding schemes stored within the file. See  The TrueType Font Format Specification for more details.

If no encoding option is specificed and the font does not contain alpha-numeric characters then the best font specific encoding scheme is used. Otherwise, the default encoding is standard encoding.

If no encoding schemes yield any glyph to character mappings, then all the glyphs are linearly mapped to character codes 32 through 255.

Known Bugs

Printing of TrueType fonts can only performed on printers with Postscript interpreter versions greater that 2013 which have Type 42 font support.

The TrueType fonts MS Line Draw and Symbol MT do not work.


Using Keyboard UI


What about nextText?


Window Server

OPENSTEP Enterprise Release 4.1  Copyright ©1996 by NeXT Software, Inc.  All Rights Reserved.

New Features in 4.0

A new release of DPS from Adobe (2015) has been integrated.

On Windows NT the WindowServer plays a different role in OPENSTEP than it does under Mach.  It is not involved in Window region management or event distribution.  Instead, it serves as a "drawing server" which interprets PostScript and  provides backing stores for Windows windows.  OPENSTEP applications still rendezvous with the WindowServer to do their drawing, but instead of creating windows via the WindowServer, they use WIN32 to create windows directly.  The application then passes the Windows window number to the WindowServer and a backing store is created.  All drawing is occurs in the WindowServer, and when flushgraphics is called, the backing store is transferred to the display via GDI's BitBlt.

Better Font Support

This release includes support for CID fonts and TrueType (type 42) fonts.  You can use the ttf2font conversion program to convert TTF files to a format suitable for use with OPENSTEP.  (see TrueType release notes for details).

NXHosting

NXHosting is not supported (inbound or outbound) on Windows NT.

Pixel Formats

We support drawing into the following DIB formats for backing stores:

8bit color (includes System Palette entries)

555 16bit color

565 16bit color

32 bit color

In Windows 16 color VGA mode, we use 8bit color backing stores.  This mode is supported for diagnostics, but is not recommended and has some really bad color artifacts.

In Windows 32bit color mode, our rendering code currently does not gamma correct.  This means that OPENSTEP applications will look dark, unless you display adaptor supports gamma correction in hardware.


Windows-Specific Notes