From f821b6b1b1c44a11d477de9dbaec1fd8d8dbebde Mon Sep 17 00:00:00 2001 From: Fabien_ Date: Fri, 18 Nov 2005 11:06:09 +0000 Subject: [PATCH] Improved documentation git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/gui/trunk@22033 72102866-910b-0410-8b05-ffd578937521 --- ChangeLog | 4 ++ Source/NSOpenPanel.m | 56 ++++++++++------- Source/NSSavePanel.m | 133 ++++++++++++++++++++------------------- Source/NSTextField.m | 70 ++++++++++++++++----- Source/NSTextFieldCell.m | 16 +++++ 5 files changed, 179 insertions(+), 100 deletions(-) diff --git a/ChangeLog b/ChangeLog index b31673f95..091a5831b 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,6 +1,10 @@ 2005-11-18 fabien * Source/NSSliderCell.m: Improved documentation + * Source/NSTextField.m: Improved documentation + * Source/NSTextFieldCell.m: Improved documentation + * Source/NSSavePanel.m: Improved documentation + * Source/NSOpenPanel.m: Improved documentation 2005-11-17 fabien diff --git a/Source/NSOpenPanel.m b/Source/NSOpenPanel.m index f672ec593..94ddb2654 100644 --- a/Source/NSOpenPanel.m +++ b/Source/NSOpenPanel.m @@ -255,10 +255,7 @@ static NSOpenPanel *_gs_gui_open_panel = nil; } } -/* - * Accessing the NSOpenPanel shared instance - */ -/** Returns the shared NSOpenPanel instance */ +/**

Creates ( if needed ) and returns the shared NSOpenPanel instance

*/ + (NSOpenPanel *) openPanel { if (!_gs_gui_open_panel) @@ -290,47 +287,62 @@ static NSOpenPanel *_gs_gui_open_panel = nil; /* * Filtering Files */ -/** Allows the user to select multiple files if flag is YES. */ +/**

Allows the user to select multiple files if flag is YES. + The default behavior is not to allow multiple selections

+

See Also: -allowsMultipleSelection

+*/ - (void) setAllowsMultipleSelection: (BOOL)flag { [_browser setAllowsMultipleSelection: flag]; } -/** Returns YES if the user is allowed to select multiple files. The - default behavior is not to allow mutiple selections. */ +/**

Returns YES if the user is allowed to select multiple files. The + default behavior is not to allow mutiple selections.

+

See Also: -setAllowsMultipleSelection:

+*/ - (BOOL) allowsMultipleSelection { return [_browser allowsMultipleSelection]; } -/** Allows the user to choose directories if flag is YES. */ +/**

Allows the user to choose directories if flag is YES. The default + behavior is to allow choosing directories.

+

See Also: -canChooseDirectories

+*/ - (void) setCanChooseDirectories: (BOOL)flag { _canChooseDirectories = flag; [_browser setAllowsBranchSelection: flag]; } -/** Returns YES if the user is allowed to choose directories The - default behavior is to allow choosing directories. */ +/**

Returns YES if the user is allowed to choose directories The + default behavior is to allow choosing directories.

+

See Also: -setCanChooseDirectories:

+ */ - (BOOL) canChooseDirectories { return _canChooseDirectories; } -/** Allows the user to choose files if flag is YES */ +/**

Allows the user to choose files if flag is YES.The default behavior it + to allow choosing files.

See Also: -canChooseFiles

+*/ - (void) setCanChooseFiles: (BOOL)flag { _canChooseFiles = flag; } -/** Returns YES if the user is allowed to choose files. The - default behavior it to allow choosing files. */ +/**

Returns YES if the user is allowed to choose files. The + default behavior it to allow choosing files.

+

See Also: -setCanChooseFiles:

+*/ - (BOOL) canChooseFiles { return _canChooseFiles; } -/** Returns the absolute path of the file selected by the user. */ +/**

Returns the absolute path of the file selected by the user.

+*/ - (NSString*) filename { NSArray *ret; @@ -343,9 +355,9 @@ static NSOpenPanel *_gs_gui_open_panel = nil; return nil; } -/** Returns an array containing the absolute paths (as NSString - objects) of the selected files and directories. If multiple - selections aren't allowed, the array contains a single name. +/**

Returns an array containing the absolute paths (as NSString + objects) of the selected files and directories. If multiple + selections aren't allowed, the array contains a single name.

*/ - (NSArray *) filenames { @@ -408,8 +420,9 @@ static NSOpenPanel *_gs_gui_open_panel = nil; /* * Running the NSOpenPanel */ -/** Displays the open panel in a modal session, filtering for - files that have the specified types +/**

Displays the open panel in a modal session, filtering for + files that have the specified types

+

See Also: -runModalForDirectory:file:types:

*/ - (int) runModalForTypes: (NSArray *)fileTypes { @@ -418,10 +431,11 @@ static NSOpenPanel *_gs_gui_open_panel = nil; types: fileTypes]; } -/** Displays the open panel in a modal session, with the directory +/**

Displays the open panel in a modal session, with the directory path shown and file name (if any) selected. Files are filtered for the specified types. If the directory is nil, then the directory shown in - the open panel is the last directory selected. + the open panel is the last directory selected.

+

See Also: -runModalForTypes:

*/ - (int) runModalForDirectory: (NSString *)path file: (NSString *)name diff --git a/Source/NSSavePanel.m b/Source/NSSavePanel.m index 41880bfe7..e667adc5a 100644 --- a/Source/NSSavePanel.m +++ b/Source/NSSavePanel.m @@ -631,7 +631,8 @@ selectCellWithString: (NSString*)title } } -/** Returns the shared NSSavePanel instance */ +/**

Creates ( if needed) and returns the shared NSSavePanel instance

+ */ + (NSSavePanel *) savePanel { if (_gs_gui_save_panel == nil) @@ -681,13 +682,13 @@ selectCellWithString: (NSString*)title return self; } -/** Sets an accessory view which is shown near the bottom of the +/**

Sets an accessory view which is shown near the bottom of the panel. The panel is automatically expanded with enough room to show the extra view. You can use this extra view to customize various characteristics of the file selection mechanism. For instance you could add a popup button which allows the user to select the format that the file is saved in (e.g. rtf or txt). See - also -validateVisibleColumns . + also -validateVisibleColumns .

See Also: -accessoryView

*/ - (void) setAccessoryView: (NSView*)aView { @@ -795,12 +796,11 @@ selectCellWithString: (NSString*)title } } -/** - * Sets the title of the NSSavePanel to title. By default, - * 'Save' is the title string. If you adapt the NSSavePanel - * for other uses, its title should reflect the user action - * that brings it to the screen. - */ +/**

Sets the title of the NSSavePanel to title. By default, + 'Save' is the title string. If you adapt the NSSavePanel + for other uses, its title should reflect the user action + that brings it to the screen.

See Also: -title

+*/ - (void) setTitle: (NSString*)title { [_titleField setStringValue: title]; @@ -810,30 +810,35 @@ selectCellWithString: (NSString*)title [_titleField sizeToFit]; } -/** Returns the title of the save panel */ +/**

Returns the title of the save panel

+

See Also: -setTitle:

+*/ - (NSString*) title { return [_titleField stringValue]; } -/** - * Returns the prompt of the Save panel field that holds - * the current pathname or file name. By default this - * prompt is 'Name: '. - */ +/**

Returns the prompt of the Save panel field that holds + the current pathname or file name. By default this + prompt is 'Name: '.

See Also: -prompt

+*/ - (void) setPrompt: (NSString*)prompt { [[_form cellAtIndex: 0] setTitle: prompt]; [_form setNeedsDisplay: YES]; } -/** Returns the prompt used in the current path field. */ +/**

Returns the prompt used in the current path field.

+

See Also: -setPrompt:

+*/ - (NSString*) prompt { return [[_form cellAtIndex: 0] title]; } -/** Returns the accesory view (if any). */ +/**

Returns the accesory view (if any).

+

See Also: -setAccessoryView:

+*/ - (NSView*) accessoryView { return _accessoryView; @@ -862,9 +867,9 @@ selectCellWithString: (NSString*)title } -/** - * Sets the current path name in the Save panel's browser. - * The path argument must be an absolute path name. +/**

Sets the current path name in the Save panel's browser. + The path argument must be an absolute path name.

+

See Also: -directory

*/ - (void) setDirectory: (NSString*)path { @@ -881,24 +886,22 @@ selectCellWithString: (NSString*)title } } -/** - * Specifies the type, a file name extension to be appended to - * any selected files that don't already have that extension; - * The argument type should not include the period that begins - * the extension. Invoke this method each time the Save panel - * is used for another file type within the application. If - * you do not invoke it, or set it to empty string or nil, no - * extension will be appended, indicated by an empty string - * returned from -requiredFileType . +/**

Specifies the type, a file name extension to be appended to + any selected files that don't already have that extension; + The argument type should not include the period that begins + the extension. Invoke this method each time the Save panel + is used for another file type within the application. If + you do not invoke it, or set it to empty string or nil, no + extension will be appended, indicated by an empty string + returned from -requiredFileType .

See Also: -requiredFileType

*/ - (void) setRequiredFileType: (NSString*)fileType { ASSIGN(_requiredFileType, fileType); } -/** - * Returns the required file type. The default, indicated by empty string, - * is no required file type. +/**

Returns the required file type. The default, indicated by empty string, + * is no required file type.

See Also: -setRequiredFileType:

*/ - (NSString*) requiredFileType { @@ -933,27 +936,26 @@ selectCellWithString: (NSString*)title return _treatsFilePackagesAsDirectories; } -/** - * Sets the NSSavePanel's behavior for displaying file packages - * (for example, MyApp.app) to the user. If flag is YES, the - * user is shown files and subdirectories within a file - * package. If NO, the NSSavePanel shows each file package as - * a file, thereby giving no indication that it is a directory. +/**

Sets the NSSavePanel's behavior for displaying file packages + (for example, MyApp.app) to the user. If flag is YES, the + user is shown files and subdirectories within a file + package. If NO, the NSSavePanel shows each file package as + a file, thereby giving no indication that it is a directory.

+

See Also: -treatsFilePackagesAsDirectories

*/ - (void) setTreatsFilePackagesAsDirectories: (BOOL)flag { _treatsFilePackagesAsDirectories = flag; } -/** - * Validates and possibly reloads the browser columns that are visible +/**

Validates and possibly reloads the browser columns that are visible * in the Save panel by causing the delegate method * -panel:shouldShowFilename: to be invoked. One situation in * which this method would find use is whey you want the * browser to show only files with certain extensions based on the * selection made in an accessory-view pop-up list. When the * user changes the selection, you would invoke this method to - * revalidate the visible columns. + * revalidate the visible columns.

*/ - (void) validateVisibleColumns { @@ -970,26 +972,26 @@ selectCellWithString: (NSString*)title return _canCreateDirectories; } -/** - * Shows the save panel for the user. This method invokes - * -runModalForDirectory:file: with empty strings for the filename. - * Returns NSOKButton (if the user clicks the OK button) or - * NSCancelButton (if the user clicks the Cancel button). +/**

Shows the save panel for the user. This method invokes + -runModalForDirectory:file: with empty strings for the filename. + Returns NSOKButton (if the user clicks the OK button) or + NSCancelButton (if the user clicks the Cancel button).

+

See Also: -runModalForDirectory:file:

*/ - (int) runModal { return [self runModalForDirectory: nil file: @""]; } -/** - * Initializes the panel to the directory specified by path and, - * optionally, the file specified by filename, then displays it and - * begins its modal event loop; path and filename can be empty - * strings. The method invokes [NSApplication:-runModalForWindow:] - * method with self as the argument. Returns NSOKButton (if the user - * clicks the OK button) or NSCancelButton (if the user clicks the - * Cancel button). If path is nil then the panel displays the last - * selected directory or as a last resort, the current working directory. +/**

Initializes the panel to the directory specified by path and, + optionally, the file specified by filename, then displays it and + begins its modal event loop; path and filename can be empty + strings. The method invokes [NSApplication:-runModalForWindow:] + method with self as the argument. Returns NSOKButton (if the user + clicks the OK button) or NSCancelButton (if the user clicks the + Cancel button). If path is nil then the panel displays the last + selected directory or as a last resort, the current working directory.

+

See Also: -runModal

*/ - (int) runModalForDirectory: (NSString*)path file: (NSString*)filename { @@ -1021,10 +1023,9 @@ selectCellWithString: (NSString*)title contextInfo: contextInfo]; } -/** - * Returns the directory choosen by the user. Do not invoke directory - * within a modal loop because the information that these methods - * fetch is updated only upon return. +/**

Returns the directory choosen by the user. Do not invoke directory + within a modal loop because the information that these methods + fetch is updated only upon return.

See Also: -setDirectory:

*/ - (NSString*) directory { @@ -1034,10 +1035,9 @@ selectCellWithString: (NSString*)title return @""; } -/** - * Returns the absolute filename choosen by the user. Do not invoke - * filename within a modal loop because the information that these - * methods fetch is updated only upon return. +/**

Returns the absolute filename choosen by the user. Do not invoke + filename within a modal loop because the information that these + methods fetch is updated only upon return.

*/ - (NSString*) filename { @@ -1059,6 +1059,10 @@ selectCellWithString: (NSString*)title return [NSURL fileURLWithPath: [self filename]]; } +/**

Invoked by the 'Cancel' button. Saves the current directory browsed + and stop the modal event loop using [NSApplication-stopModalWithCode:]

+

See Also: -ok:

+ */ - (void) cancel: (id)sender { ASSIGN(_directory, [_browser pathToColumn:[_browser lastColumn]]); @@ -1066,6 +1070,9 @@ selectCellWithString: (NSString*)title [self close]; } +/**

Invoked by the "OK" button. TODO

+ *

See Also: -cancel:

+ */ - (void) ok: (id)sender { NSMatrix *matrix; diff --git a/Source/NSTextField.m b/Source/NSTextField.m index 25cf128ec..5ff041069 100644 --- a/Source/NSTextField.m +++ b/Source/NSTextField.m @@ -105,19 +105,25 @@ static Class textFieldCellClass; [super dealloc]; } -// -// Setting User Access to Text -// +/**

Returns whether the NSTextField is editable

+

See Also: -setEditable:

+*/ - (BOOL) isEditable { return [_cell isEditable]; } +/**

Returns whether the NSTextField is selectable

+

See Also: -setSelectable:

+*/ - (BOOL) isSelectable { return [_cell isSelectable]; } +/**

Sets whether the NSTextField is editable

+

See Also: -isEditable

+*/ - (void) setEditable: (BOOL)flag { [_cell setEditable: flag]; @@ -125,6 +131,9 @@ static Class textFieldCellClass; [_text_object setEditable: flag]; } +/**

Sets whether the NSTextField is selectable

+

See Also: -isSelectable

+*/ - (void) setSelectable: (BOOL)flag { [_cell setSelectable: flag]; @@ -132,9 +141,8 @@ static Class textFieldCellClass; [_text_object setSelectable: flag]; } -// -// Editing Text -// +/**

Selects all the text inot the NSTextField if it's selectable.

+ */ - (void) selectText: (id)sender { if ([self isSelectable] && (_super_view != nil)) @@ -143,18 +151,18 @@ static Class textFieldCellClass; [_text_object selectAll: self]; else { - NSText *t = [_window fieldEditor: YES forObject: self]; + NSText *text = [_window fieldEditor: YES forObject: self]; int length; - if ([t superview] != nil) - if ([t resignFirstResponder] == NO) + if ([text superview] != nil) + if ([text resignFirstResponder] == NO) return; // [NSCursor hide]; /* [self stringValue] generates a call to validateEditing so we need to call it before setting up the _text_object */ length = [[self stringValue] length]; - _text_object = [_cell setUpFieldEditorAttributes: t]; + _text_object = [_cell setUpFieldEditorAttributes: text]; [_cell selectWithFrame: _bounds inView: self editor: _text_object @@ -188,9 +196,9 @@ static Class textFieldCellClass; [self setPreviousKeyView: anObject]; } -// -// Assigning a Delegate -// +/**

Sets the delegate to anObject

+

See Also: -delegate

+*/ - (void) setDelegate: (id)anObject { if (_delegate) @@ -208,59 +216,89 @@ static Class textFieldCellClass; SET_DELEGATE_NOTIFICATION(DidChange); } +/**

Returns the delegate object

+

See Also: -setDelegate:

+*/ - (id) delegate { return _delegate; } -// -// Modifying Graphic Attributes -// +/**

Sets the color used to draw the background

+

See Also: -backgroundColor

+ */ - (void) setBackgroundColor: (NSColor *)aColor { [_cell setBackgroundColor: aColor]; } +/**

Returns the color used to draw the background

+

See Also: -setBackgroundColor:

+ */ - (NSColor *) backgroundColor { return [_cell backgroundColor]; } +/**

Returns whether the NSTextField draws the background

+

See Also: -setDrawsBackground:

+ */ - (BOOL) drawsBackground { return [_cell drawsBackground]; } +/**

Returns whether the NSTextField's cell has bezeled border

+

See Also: -setBezeled:

+ */ - (BOOL) isBezeled { return [_cell isBezeled]; } +/**

Returns whether the NSTextField's cell has border

+

See Also: -setBordered:

+ */ - (BOOL) isBordered { return [_cell isBordered]; } +/**

Sets whether the NSTextField's cell has bezeled border

+

See Also: -isBezeled

+ */ - (void) setBezeled: (BOOL)flag { [_cell setBezeled: flag]; } +/**

Sets whether the NSTextField's cell has border

+

See Also: -isBordered

+ */ - (void) setBordered: (BOOL)flag { [_cell setBordered: flag]; } +/**

Sets whether the NSTextField draws the background

+

See Also: -drawsBackground

+ */ - (void) setDrawsBackground: (BOOL)flag { [_cell setDrawsBackground: flag]; } +/**

Sets the color with which the text will be draw to aColor

+

See Also: -textColor

+ */ - (void) setTextColor: (NSColor *)aColor { [_cell setTextColor: aColor]; } +/**

Returns the colour used to draw the text.

+

See Also: -setTextColor:

+ */ - (NSColor *) textColor { return [_cell textColor]; diff --git a/Source/NSTextFieldCell.m b/Source/NSTextFieldCell.m index 18278ae5e..a0449d8e7 100644 --- a/Source/NSTextFieldCell.m +++ b/Source/NSTextFieldCell.m @@ -128,11 +128,18 @@ static NSColor *txtCol; [(NSControl *)_control_view updateCell: self]; } +/**

Returns the color used to draw the background

+

See Also: -setBackgroundColor:

+ */ - (NSColor *) backgroundColor { return _background_color; } + +/**

Sets whether the NSTextFieldCell draw its background color

+

See Also: -drawsBackground

+ */ - (void) setDrawsBackground: (BOOL)flag { _textfieldcell_draws_background = flag; @@ -142,11 +149,17 @@ static NSColor *txtCol; [(NSControl *)_control_view updateCell: self]; } +/**

Returns whether the NSTextFieldCell draw its background color

+

See Also: -setBackgroundColor:

+ */ - (BOOL) drawsBackground { return _textfieldcell_draws_background; } +/**

Sets the text color to aColor

+

See Also: -textColor

+ */ - (void) setTextColor: (NSColor *)aColor { ASSIGN (_text_color, aColor); @@ -155,6 +168,9 @@ static NSColor *txtCol; [(NSControl *)_control_view updateCell: self]; } +/**

Returns the text color

+

See Also: -setTextColor:

+ */ - (NSColor *) textColor { return _text_color;