gnustep/libs-gui
0
0
Fork 0
mirror of https://github.com/gnustep/libs-gui.git synced 2025-05-31 20:40:47 +00:00
Code Issues Projects Releases Packages Wiki Activity

Improved documentation

Browse source 
git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/gui/trunk@22033 72102866-910b-0410-8b05-ffd578937521
This commit is contained in:
Fabien_ 2005-11-18 11:06:09 +00:00
parent 854198ba81
commit f821b6b1b1
5 changed files with 179 additions and 100 deletions
Download patch file Download diff file Expand all files Collapse all files

4
ChangeLog
View file

@ -1,6 +1,10 @@
2005-11-18 fabien <fabien@sonappart.net>
* 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 <fabien@sonappart.net>

54
Source/NSOpenPanel.m
View file

@ -255,10 +255,7 @@ static NSOpenPanel *_gs_gui_open_panel = nil;
}
}
/*
* Accessing the NSOpenPanel shared instance
*/
/** Returns the shared NSOpenPanel instance */
/**<p> Creates ( if needed ) and returns the shared NSOpenPanel instance</p> */
+ (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. */
/**<p> Allows the user to select multiple files if flag is YES.
The default behavior is not to allow multiple selections</p>
<p>See Also: -allowsMultipleSelection</p>
*/
- (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. */
/**<p>Returns YES if the user is allowed to select multiple files. The
default behavior is not to allow mutiple selections.</p>
<p>See Also: -setAllowsMultipleSelection:</p>
*/
- (BOOL) allowsMultipleSelection
{
return [_browser allowsMultipleSelection];
}
/** Allows the user to choose directories if flag is YES. */
/** <p>Allows the user to choose directories if flag is YES. The default
behavior is to allow choosing directories.</p>
<p>See Also: -canChooseDirectories</p>
*/
- (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. */
/** <p>Returns YES if the user is allowed to choose directories The
default behavior is to allow choosing directories.</p>
<p>See Also: -setCanChooseDirectories:</p>
*/
- (BOOL) canChooseDirectories
{
return _canChooseDirectories;
}
/** Allows the user to choose files if flag is YES */
/** <p>Allows the user to choose files if flag is YES.The default behavior it
to allow choosing files. <p>See Also: -canChooseFiles</p>
*/
- (void) setCanChooseFiles: (BOOL)flag
{
_canChooseFiles = flag;
}
/** Returns YES if the user is allowed to choose files. The
default behavior it to allow choosing files. */
/**<p>Returns YES if the user is allowed to choose files. The
default behavior it to allow choosing files.</p>
<p>See Also: -setCanChooseFiles:</p>
*/
- (BOOL) canChooseFiles
{
return _canChooseFiles;
}
/** Returns the absolute path of the file selected by the user. */
/** <p>Returns the absolute path of the file selected by the user.</p>
*/
- (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
/** <p>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.
selections aren't allowed, the array contains a single name.</p>
*/
- (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
/** <p>Displays the open panel in a modal session, filtering for
files that have the specified types </p>
<p>See Also: -runModalForDirectory:file:types:</p>
*/
- (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
/** <p>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.</p>
<p>See Also: -runModalForTypes:</p>
*/
- (int) runModalForDirectory: (NSString *)path
file: (NSString *)name

133
Source/NSSavePanel.m
View file

@ -631,7 +631,8 @@ selectCellWithString: (NSString*)title
}
}
/** Returns the shared NSSavePanel instance */
/** <p>Creates ( if needed) and returns the shared NSSavePanel instance</p>
*/
+ (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
/** <p>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 .</p><p>See Also: -accessoryView</p>
*/
- (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.
*/
/**<p>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.</p><p>See Also: -title</p>
*/
- (void) setTitle: (NSString*)title
{
[_titleField setStringValue: title];
@ -810,30 +810,35 @@ selectCellWithString: (NSString*)title
[_titleField sizeToFit];
}
/** Returns the title of the save panel */
/**<p>Returns the title of the save panel </p>
<p>See Also: -setTitle:</p>
*/
- (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: '.
*/
/**<p> Returns the prompt of the Save panel field that holds
the current pathname or file name. By default this
prompt is 'Name: '.</p><p>See Also: -prompt</p>
*/
- (void) setPrompt: (NSString*)prompt
{
[[_form cellAtIndex: 0] setTitle: prompt];
[_form setNeedsDisplay: YES];
}
/** Returns the prompt used in the current path field. */
/**<p>Returns the prompt used in the current path field.</p>
<p>See Also: -setPrompt:</p>
*/
- (NSString*) prompt
{
return [[_form cellAtIndex: 0] title];
}
/** Returns the accesory view (if any). */
/** <p>Returns the accesory view (if any).</p>
<p>See Also: -setAccessoryView:</p>
*/
- (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.
/** <p>Sets the current path name in the Save panel's browser.
The path argument must be an absolute path name.</p>
<p>See Also: -directory</p>
*/
- (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 .
/**<p> 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 .</p><p>See Also: -requiredFileType</p>
*/
- (void) setRequiredFileType: (NSString*)fileType
{
ASSIGN(_requiredFileType, fileType);
}
/**
* Returns the required file type. The default, indicated by empty string,
* is no required file type.
/**<p>Returns the required file type. The default, indicated by empty string,
* is no required file type.</p><p>See Also: -setRequiredFileType:</p>
*/
- (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.
/**<p> 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.</p>
<p>See Also: -treatsFilePackagesAsDirectories</p>
*/
- (void) setTreatsFilePackagesAsDirectories: (BOOL)flag
{
_treatsFilePackagesAsDirectories = flag;
}
/**
* Validates and possibly reloads the browser columns that are visible
/**<p> 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. </p>
*/
- (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).
/**<p>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).</p>
<p>See Also: -runModalForDirectory:file:</p>
*/
- (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.
/**<p> 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.</p>
<p>See Also: -runModal</p>
*/
- (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.
/**<p> 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.</p><p>See Also: -setDirectory:</p>
*/
- (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.
/**<p> 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.</p>
*/
- (NSString*) filename
{
@ -1059,6 +1059,10 @@ selectCellWithString: (NSString*)title
return [NSURL fileURLWithPath: [self filename]];
}
/**<p>Invoked by the 'Cancel' button. Saves the current directory browsed
and stop the modal event loop using [NSApplication-stopModalWithCode:]</p>
<p>See Also: -ok:</p>
*/
- (void) cancel: (id)sender
{
ASSIGN(_directory, [_browser pathToColumn:[_browser lastColumn]]);
@ -1066,6 +1070,9 @@ selectCellWithString: (NSString*)title
[self close];
}
/**<p>Invoked by the "OK" button. TODO </p>
*<p>See Also: -cancel:</p>
*/
- (void) ok: (id)sender
{
NSMatrix *matrix;

70
Source/NSTextField.m
View file

@ -105,19 +105,25 @@ static Class textFieldCellClass;
[super dealloc];
}
//
// Setting User Access to Text
//
/** <p>Returns whether the NSTextField is editable</p>
<p>See Also: -setEditable:</p>
*/
- (BOOL) isEditable
{
return [_cell isEditable];
}
/** <p>Returns whether the NSTextField is selectable</p>
<p>See Also: -setSelectable:</p>
*/
- (BOOL) isSelectable
{
return [_cell isSelectable];
}
/** <p>Sets whether the NSTextField is editable</p>
<p>See Also: -isEditable</p>
*/
- (void) setEditable: (BOOL)flag
{
[_cell setEditable: flag];
@ -125,6 +131,9 @@ static Class textFieldCellClass;
[_text_object setEditable: flag];
}
/** <p>Sets whether the NSTextField is selectable</p>
<p>See Also: -isSelectable</p>
*/
- (void) setSelectable: (BOOL)flag
{
[_cell setSelectable: flag];
@ -132,9 +141,8 @@ static Class textFieldCellClass;
[_text_object setSelectable: flag];
}
//
// Editing Text
//
/**<p>Selects all the text inot the NSTextField if it's selectable.</p>
*/
- (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
//
/** <p>Sets the delegate to anObject</p>
<p>See Also: -delegate</p>
*/
- (void) setDelegate: (id)anObject
{
if (_delegate)
@ -208,59 +216,89 @@ static Class textFieldCellClass;
SET_DELEGATE_NOTIFICATION(DidChange);
}
/** <p>Returns the delegate object</p>
<p>See Also: -setDelegate:</p>
*/
- (id) delegate
{
return _delegate;
}
//
// Modifying Graphic Attributes
//
/** <p>Sets the color used to draw the background</p>
<p>See Also: -backgroundColor</p>
*/
- (void) setBackgroundColor: (NSColor *)aColor
{
[_cell setBackgroundColor: aColor];
}
/** <p>Returns the color used to draw the background</p>
<p>See Also: -setBackgroundColor:</p>
*/
- (NSColor *) backgroundColor
{
return [_cell backgroundColor];
}
/** <p>Returns whether the NSTextField draws the background</p>
<p>See Also: -setDrawsBackground:</p>
*/
- (BOOL) drawsBackground
{
return [_cell drawsBackground];
}
/** <p>Returns whether the NSTextField's cell has bezeled border</p>
<p>See Also: -setBezeled:</p>
*/
- (BOOL) isBezeled
{
return [_cell isBezeled];
}
/** <p>Returns whether the NSTextField's cell has border</p>
<p>See Also: -setBordered:</p>
*/
- (BOOL) isBordered
{
return [_cell isBordered];
}
/** <p>Sets whether the NSTextField's cell has bezeled border</p>
<p>See Also: -isBezeled</p>
*/
- (void) setBezeled: (BOOL)flag
{
[_cell setBezeled: flag];
}
/** <p>Sets whether the NSTextField's cell has border</p>
<p>See Also: -isBordered</p>
*/
- (void) setBordered: (BOOL)flag
{
[_cell setBordered: flag];
}
/** <p>Sets whether the NSTextField draws the background</p>
<p>See Also: -drawsBackground</p>
*/
- (void) setDrawsBackground: (BOOL)flag
{
[_cell setDrawsBackground: flag];
}
/** <p>Sets the color with which the text will be draw to aColor</p>
<p>See Also: -textColor</p>
*/
- (void) setTextColor: (NSColor *)aColor
{
[_cell setTextColor: aColor];
}
/** <p>Returns the colour used to draw the text.</p>
<p>See Also: -setTextColor:</p>
*/
- (NSColor *) textColor
{
return [_cell textColor];

16
Source/NSTextFieldCell.m
View file

@ -128,11 +128,18 @@ static NSColor *txtCol;
[(NSControl *)_control_view updateCell: self];
}
/** <p>Returns the color used to draw the background</p>
<p>See Also: -setBackgroundColor:</p>
*/
- (NSColor *) backgroundColor
{
return _background_color;
}
/** <p>Sets whether the NSTextFieldCell draw its background color</p>
<p>See Also: -drawsBackground</p>
*/
- (void) setDrawsBackground: (BOOL)flag
{
_textfieldcell_draws_background = flag;
@ -142,11 +149,17 @@ static NSColor *txtCol;
[(NSControl *)_control_view updateCell: self];
}
/** <p>Returns whether the NSTextFieldCell draw its background color</p>
<p>See Also: -setBackgroundColor:</p>
*/
- (BOOL) drawsBackground
{
return _textfieldcell_draws_background;
}
/** <p>Sets the text color to aColor</p>
<p>See Also: -textColor</p>
*/
- (void) setTextColor: (NSColor *)aColor
{
ASSIGN (_text_color, aColor);
@ -155,6 +168,9 @@ static NSColor *txtCol;
[(NSControl *)_control_view updateCell: self];
}
/** <p>Returns the text color</p>
<p>See Also: -setTextColor:</p>
*/
- (NSColor *) textColor
{
return _text_color;