diff --git a/ChangeLog b/ChangeLog index 54455efd1..4a4d4c601 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,6 @@ +2004-06-06 Quentin Mathe + * Source/NSComboBox.m: Added complete documentation. + 2004-06-04 Fred Kiefer * Headers/Additions/GNUstepGUI/GSDragView.h: diff --git a/Source/NSComboBox.m b/Source/NSComboBox.m index b2663272e..67279f75f 100644 --- a/Source/NSComboBox.m +++ b/Source/NSComboBox.m @@ -36,12 +36,27 @@ static Class usedCellClass; static Class comboBoxCellClass; static NSNotificationCenter *nc; +/** + + Class Description + An NSComboBox is what we can call a completion/choices box, derived from + NSTextField, it allows you to enter text like in a text field but also to click + in the ellipsis button (indicating the fact other user inputs is possible) on + the right of it to obtain a list of choices which you can use as the text field + value by selecting a row in this list. You can also obtain direct completion + when it is enabled via setCompletes: to get a suggested text + field value updated as you type. + Like other NSControls, NSComboBox is a wrapper around a core piece which + implements the combo box behavior, a cell, which is in this case an + NSComboBoxCell. + +*/ @implementation NSComboBox + (void) initialize { - if (self == [NSComboBox class]) // Is such test case really needed ? + if (self == [NSComboBox class]) { [self setVersion: 1]; comboBoxCellClass = [NSComboBoxCell class]; @@ -63,167 +78,356 @@ static NSNotificationCenter *nc; usedCellClass = factoryId ? factoryId : comboBoxCellClass; } - +/** + * Returns YES when the combo box cell displays a vertical scroller for its + * list, returns NO otherwise. + * Take note that the scroller will be displayed even when the sum of the items + * height in the list is inferior to the minimal height of the list displayed + * area. + */ - (BOOL)hasVerticalScroller { return [_cell hasVerticalScroller]; } +/** + * Sets whether the combo box cell list displays a vertical scroller, by default + * it is the case. When flag is NO and the combo cell list has more + * items (either in its default list or from its data source) than the number + * returned by numberOfVisibleItems, only a subset of them will be + * displayed. Uses scroll related methods to position this subset in the combo + * box cell list. + * Take note that the scroller will be displayed even when the sum of the items + * height in the list is inferior to the minimal height of the list displayed + * area. + */ - (void)setHasVerticalScroller:(BOOL)flag { [_cell setHasVerticalScroller:flag]; } +/** + * Returns the width and the height (as the values of an NSSize variable) + * between each item of the combo box cell list. + */ - (NSSize)intercellSpacing { return [_cell intercellSpacing]; } +/** + * Sets the width and the height between each item of the combo box cell list to + * the values in aSize. + */ - (void)setIntercellSpacing:(NSSize)aSize { [_cell setIntercellSpacing:aSize]; } +/** + * Returns the height of the items in the combo box cell list. + */ - (float)itemHeight { return [_cell itemHeight]; } +/** + * Sets the height of the items in the combo box cell list to + * itemHeight. + */ - (void)setItemHeight:(float)itemHeight { [_cell setItemHeight:itemHeight]; } +/** + * Returns the maximum number of allowed items to be displayed in the combo box + * cell list. + */ - (int)numberOfVisibleItems { return [_cell numberOfVisibleItems]; } +/** + * Sets the maximum number of allowed items to be displayed in the combo box + * cell list. + */ - (void)setNumberOfVisibleItems:(int)visibleItems { [_cell setNumberOfVisibleItems:visibleItems]; } +/** + * Marks the combo box cell in order to have its items list reloaded in the + * case it uses a data source, and to have it redisplayed. + */ - (void)reloadData { [_cell reloadData]; } +/** + * Informs the combo box cell that the number of items in its data source has + * changed, in order to permit to the scrollers in its displayed list being + * updated without needing the reload of the data. + * It is recommended to use this method with a data source that continually + * receives data in the background, to keep the the combo box cell responsive to + * the user while the data is received. + * Take a look at the NSComboBoxDataSource informal protocol + * specification to know more on the messages NSComboBox sends to its data + * source. + */ - (void)noteNumberOfItemsChanged { [_cell noteNumberOfItemsChanged]; } +/** + * Returns YES when the combo box cell uses a data source (which is external) to + * populate its items list, otherwise returns NO in the case it uses its default + * list. + */ - (BOOL)usesDataSource { return [_cell usesDataSource]; } +/** + * Sets according to flag whether the combo box cell uses a data + * source (which is external) to populate its items list. + */ - (void)setUsesDataSource:(BOOL)flag { [_cell setUsesDataSource:flag]; } +/** + * Scrolls the combo box cell list vertically in order to have the item at + * index in the closest position relative to the top. There is no + * need to have the list displayed when this method is invoked. + */ - (void)scrollItemAtIndexToTop:(int)index { [_cell scrollItemAtIndexToTop:index]; } +/** + * Scrolls the combo box cell list vertically in order to have the item at + * index visible. There is no need to have the list displayed when + * this method is invoked. + */ - (void)scrollItemAtIndexToVisible:(int)index { [_cell scrollItemAtIndexToVisible:index]; } +/** + * Selects the combo box cell list row at index. + * Take note no changes occurs in the combo box cell list when this method is + * called. + * Posts an NSComboBoxSelectionDidChangeNotification to the default notification + * center when there is a new selection different from the previous one. + */ - (void)selectItemAtIndex:(int)index { [_cell selectItemAtIndex:index]; } +/** + * Deselects the combo box cell list row at index in the case this + * row is selected. + * Posts an NSComboBoxSelectionDidChangeNotification to the default notification + * center, when there is a new selection. + */ - (void)deselectItemAtIndex:(int)index { [_cell deselectItemAtIndex:index]; } +/** + * Returns the index of the selected item in the combo box cell list or -1 when + * there is no selection, the selected item can be related to the data source + * object in the case usesDataSource returns YES else to the + * default items list. + */ - (int)indexOfSelectedItem { return [_cell indexOfSelectedItem]; } +/** + * Returns the number of items in the the combo box cell list, the numbers of + * items can be be related to the data source object in the case + * usesDataSource returns YES else to the default items list. + */ - (int)numberOfItems { return [_cell numberOfItems]; } +/** + * Returns the combo box cell data source object which is reponsible to provide + * the data to be displayed. To know how to implement a data source object, + * take a look at the NSComboBoxDataSource informal protocol description. In + * the case usesDataSource returns NO, this method logs a warning. + */ - (id)dataSource { return [_cell dataSource]; } +/** + * Sets the combo box cell data source to aSource. Just calling this + * method doesn't set usesDataSource to return YES, you must call + * setUsesDataSource: with YES before or a warning will be logged. + * To know how to implement a data source objects, take a look at the + * NSComboBoxDataSource informal protocol description. When aSource + * doesn't respond to the methods numberOfItemsInComboBox: + * comboBox:objectValueForItemAtIndex:, this method + * logs a warning. + */ - (void)setDataSource:(id)aSource { [_cell setDataSource:aSource]; } +/** + * Adds an item to the combo box cell default items list which is used when + * usesDataSource returns NO. In the case + * usesDataSource returns YES, this method logs a warning. + */ - (void)addItemWithObjectValue:(id)object { [_cell addItemWithObjectValue:object]; } +/** + * Adds several items in an array to the combo box cell default items list which + * is used when usesDataSource returns NO. In the case + * usesDataSource returns YES, this method logs a warning. + */ - (void)addItemsWithObjectValues:(NSArray *)objects { [_cell addItemsWithObjectValues:objects]; } +/** + * Inserts an item in the combo box cell default items list which + * is used when usesDataSource returns NO. In the case + * usesDataSource returns YES, this method logs a warning. + */ - (void)insertItemWithObjectValue:(id)object atIndex:(int)index { [_cell insertItemWithObjectValue:object atIndex:index]; } +/** + * Removes an item in the combo box cell default items list which + * is used when usesDataSource returns NO. In the case + * usesDataSource returns YES, this method logs a warning. + */ - (void)removeItemWithObjectValue:(id)object { [_cell removeItemWithObjectValue:object]; } +/** + * Removes the item with the specified index in the combo box cell + * default items list which is used when usesDataSource returns NO. + * In the case usesDataSource returns YES, this method logs a warning. + */ - (void)removeItemAtIndex:(int)index { [_cell removeItemAtIndex:index]; } +/** + * Removes all the items in the combo box cell default items list which is used + * when usesDataSource returns NO. In the case + * usesDataSource returns YES, this method logs a warning. + */ - (void)removeAllItems { [_cell removeAllItems]; } +/** + * Selects the first item in the default combo box cell list which is equal to + * object. In the case usesDataSource returns YES, this + * method logs a warning. + * Take note that this method doesn't update the text field part value. + * Posts an NSComboBoxSelectionDidChange notification to the default + * notification center when the new selection is different than the previous + * one. + */ - (void)selectItemWithObjectValue:(id)object { [_cell selectItemWithObjectValue:object]; } +/** + * Returns the object value at index within combo box cell default + * items list. When the index is beyond the end of the list, an NSRangeException is + * raised. In the case usesDataSource returns YES, this method logs + * a warning. + */ - (id)itemObjectValueAtIndex:(int)index { return [_cell itemObjectValueAtIndex:index]; } +/** + * Returns the object value of the selected item in the combo box cell default + * items list or nil when there is no selection. In the case + * usesDataSource returns YES, this method logs a warning. + */ - (id)objectValueOfSelectedItem { return [_cell objectValueOfSelectedItem]; } +/** + * Returns the lowest index associated with a value in the combo box + * cell default items list, which is equal to object, and returns + * NSNotFound when there is no such value. In the case + * usesDataSource returns YES, this method logs a warning. + */ - (int)indexOfItemWithObjectValue:(id)object { return [_cell indexOfItemWithObjectValue:object]; } +/** + * Returns the combo box cell default items list in an array. + */ - (NSArray *)objectValues { return [_cell objectValues]; } +/** + * Sets whether the combo box cell automatic completion is active or not. + * The automatic completion tries to complete what the user types in the text + * field part, it tries to complete only when the the user adds characters at + * the end of the string, not when it deletes characters or when the insertion + * point precedes the end of the string. + * To do the automatic completion, the completedString: method is + * called, and when the returned string is longer than the current one in the text + * field, the completion occurs and the completed part gets selected. + */ - (void)setCompletes:(BOOL)completes { [_cell setCompletes: completes]; } +/** + * Returns YES when the combo box cell automatic completion is active, returns + * NO otherwise. + * Take a look at the setCompletes: method documentation to know + * how the automatic completion works. + */ - (BOOL)completes { return [_cell completes];