NSForm Class Reference

Inherits from
NSMatrix : NSControl : NSView : NSResponder : NSObject
Conforms to
NSUserInterfaceValidations (NSMatrix)
NSAnimatablePropertyContainer (NSView)
NSUserInterfaceItemIdentification (NSView)
NSDraggingDestination (NSView)
NSCoding (NSResponder)
NSObject (NSObject)
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.0 and later.
Declared in
NSForm.h
Companion guides
Form Programming Topics
Matrix Programming Guide
Related sample code

Overview

An NSForm object is a vertical matrix of NSFormCell objects to implement the fields.

Tasks

Adding and Removing Entries

Changing the Appearance of All the Entries

Getting Cells and Indices

Displaying a Cell

Autolayout Sizing

Editing Text

Instance Methods

addEntry:

Adds a new entry to the end of the receiver and gives it the specified title.

- (NSFormCell *)addEntry:(NSString *)title
Parameters
title

The title for the new form entry.

Return Value

The form cell object that was created for the entry.

Discussion

The new entry has no tag, target, or action, but is enabled and editable.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSForm.h

cellAtIndex:

Returns the entry at the specified index.

- (id)cellAtIndex:(NSInteger)entryIndex
Parameters
entryIndex

The index of the desired entry.

Return Value

The form cell object at the specified index.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSForm.h

drawCellAtIndex:

Displays the entry at the specified index.

- (void)drawCellAtIndex:(NSInteger)entryIndex
Parameters
entryIndex

The index of the entry to draw.

Discussion

Because this method is called automatically whenever a cell needs drawing, you never need to invoke it explicitly. It is included in the API so you can override it if you subclass NSFormCell.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSForm.h

indexOfCellWithTag:

Returns the index of the entry whose tag is tag.

- (NSInteger)indexOfCellWithTag:(NSInteger)tag
Parameters
tag

The tag of the desired entry.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSForm.h

indexOfSelectedItem

Returns the index of the selected entry.

- (NSInteger)indexOfSelectedItem
Return Value

The index of the selected entry, or -1 if no entry is selected.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSForm.h

insertEntry:atIndex:

Inserts an entry with the specified title into the receiver.

- (NSFormCell *)insertEntry:(NSString *)title atIndex:(NSInteger)entryIndex
Parameters
title

The title for the new form entry.

entryIndex

The zero-based index at which to insert the entry.

Return Value

The form cell object that was created for the entry.

Discussion

The new entry has no tag, target, or action, but is enabled and editable.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSForm.h

preferredTextFieldWidth

The preferred width of the form’s cells when using auto layout.

- (CGFloat)preferredTextFieldWidth
Return Value

The field’s width.

Discussion

If the width is negative, the cellSize matches the historic behavior, which is that it is large enough to accommodate the title, bezel, and the current text.

The default is -1.

Availability
  • Available in OS X v10.8 and later.
See Also
Declared In
NSForm.h

removeEntryAtIndex:

Removes and releases the entry at the specified index.

- (void)removeEntryAtIndex:(NSInteger)entryIndex
Parameters
entryIndex

The zero-based index identifying the desired entry.

Discussion

If the specified index is invalid, this method does nothing.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSForm.h

selectTextAtIndex:

Selects the entry at the specified index.

- (void)selectTextAtIndex:(NSInteger)entryIndex
Parameters
entryIndex

The index of the entry to select. If the specified index is invalid, this method does nothing.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSForm.h

setBezeled:

Sets whether the receiver's entries should display a bezel around their editable text.

- (void)setBezeled:(BOOL)flag
Parameters
flag

YES to display a bezel around all entries; otherwise, NO to show no bezel around all entries.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSForm.h

setBordered:

Sets whether the receiver's entries should display a border around their editable text fields.

- (void)setBordered:(BOOL)flag
Parameters
flag

YES to display a border around all entries; otherwise, NO to show no border around all entries.

Discussion

The border is drawn as a thin line around the editable text field. An entry can have a border or a bezel, but not both.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSForm.h

setEntryWidth:

Sets the width of all the entries in the receiver.

- (void)setEntryWidth:(CGFloat)width
Parameters
width

The width of all entries, measured in points in the user coordinate space. This value represents the width of both the title and the text field.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSForm.h

setFrameSize:

Sets the size of the receiver’s frame size to the specified value.

- (void)setFrameSize:(NSSize)newSize
Parameters
newSize

The new size of the form.

Discussion

The width of NSFormCell objects always match the width of their encompassing NSForm object. The cell width is always changed to match the view regardless of the value returned by autosizesCells.

Availability
  • Available in OS X v10.3 and later.
Declared In
NSForm.h

setInterlineSpacing:

Sets the spacing between entries

- (void)setInterlineSpacing:(CGFloat)spacing
Parameters
spacing

The spacing between entries, measured in points in the user coordinate space.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSForm.h

setPreferredTextFieldWidth:

Sets the preferred text field width used by auto layout.

- (void)setPreferredTextFieldWidth:(CGFloat)preferredWidth
Parameters
preferredWidth

The preferred width.

Discussion

The preferred width is reflected in the cell's cellSize, which will be large enough to accommodate the title, bezel, and a text field of width preferredTextWidth. It is also reflected in the intrinsicContentSize of the form. That is, under autolayout, the form will try to size itself so that the text field cell is the given width, according to the usual content size constraint priorities.

If the width is negative, the cellSize matches the historic behavior, which is that it is large enough to accommodate the title, bezel, and the current text.

The preferred width is reflected in the cell's cellSize, which will be large enough to accommodate the title, bezel, and a text field of width preferredTextFieldWidth.

This method can aid migration to autolayout, and is sufficient for simple cases. However, for new apps, use NSTextField objects directly instead of NSForm.

The default is -1.

Availability
  • Available in OS X v10.8 and later.
See Also
Declared In
NSForm.h

setTextAlignment:

Sets the alignment for all of the receiver’s editable text.

- (void)setTextAlignment:(NSTextAlignment)alignment
Parameters
alignment

The alignment can be one of the following constants: NSRightTextAlignment, NSCenterTextAlignment, or NSLeftTextAlignment.

Discussion

The default alignment is NSLeftTextAlignment.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSForm.h

setTextBaseWritingDirection:

Sets the writing direction for the text content of every control embedded in the form.

- (void)setTextBaseWritingDirection:(NSWritingDirection)writingDirection
Parameters
writingDirection

This value can be one of the following constants: NSWritingDirectionNatural, NSWritingDirectionLeftToRight, or NSWritingDirectionRightToLeft.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
NSForm.h

setTextFont:

Sets the font for all of the receiver’s editable text fields

- (void)setTextFont:(NSFont *)font
Parameters
font

The font to use for all editable text fields.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSForm.h

setTitleAlignment:

Sets the alignment for all of the entry titles.

- (void)setTitleAlignment:(NSTextAlignment)alignment
Parameters
alignment

The alignment can be one of the following constants: NSRightTextAlignment, NSCenterTextAlignment, or NSLeftTextAlignment.

Discussion

The default alignment is NSRightTextAlignment.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSForm.h

setTitleBaseWritingDirection:

Sets the writing direction for the title of every control embedded in the form.

- (void)setTitleBaseWritingDirection:(NSWritingDirection)writingDirection
Parameters
writingDirection

This value can be one of the following constants: NSWritingDirectionNatural, NSWritingDirectionLeftToRight, or NSWritingDirectionRightToLeft.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSForm.h

setTitleFont:

Sets the font for all of the entry titles.

- (void)setTitleFont:(NSFont *)font
Parameters
font

The font to use for all entry titles.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSForm.h


© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-09-19)

Did this document help you? Yes It's good, but... Not helpful...