Update BFilePanel docs, especially detailed description and constructor

docs/user/storage/FilePanel.dox

@@ -91,15 +91,79 @@
 
 	An open dialog looks similar but doesn't have a text box for the file name.
 
-	Creating a basic open or save panel is easy:
+	You generally construct a BFilePanel object in response to a user action
+	for example the user clicks on a "Open" or "Save"/"Save As" menu item.
+	Constructing an open or save panel is easy:
 
 \code
 	BFilePanel* openPanel = new BFilePanel(B_OPEN_PANEL);
 	BFilePanel* savePanel = new BFilePanel(B_SAVE_PANEL);
 \endcode
 
-	There are many options but they can generally be set after the object has
-	been constructed.
+	You can then call methods to indicate what directory to display, whether
+	or not multiple selections are allowed, whether or not the user is
+	allowed to open a directory, what target view to send send notifications,
+	and more. See the constructor for details.
+
+	You can modify the look of your BFilePanel object by calling the
+	SetButtonLabel() and SetSaveText() methods. If you want to change the look
+	even more radically you can get alter the panel's BWindow and BView
+	objects. You get the window by calling the Window() method. With a pointer
+	to the panel's BWindow object you can drill down to the various views
+	contained therein.
+
+	Once you have constructed and customized your BFilePanel object you should
+	call the Show() method to display the panel to the user.
+
+	When the user confirms or cancels a BMessage object is constructed and sent
+	to the target of the BFilePanel object. You can specify a different
+	target in the constructor or by calling the SetTarget() method.
+
+	<b>Open Notifications</b>
+
+	For open notifications the default target is \c be_app_messenger and is
+	caught by the RefsReceived() method The \c what field is set to
+	\c B_REFS_RECEIVED. You can set your own message by calling the
+	SetMessage() method; in this case the message will be sent to the target's
+	MessageReceived() method instead.
+
+	The \c refs field of the message contains an \c entry_ref structure
+	for each entry that the user has selected. The \c refs field is of
+	type \c B_REF_TYPE. If the selected entry is a symlink to a file you'll 
+	need to dereference the file yourself. You can do this more easily by
+	turning the \c ref into a BEntry passing \c true into the \c traverse
+	argument like this:
+
+\code
+	BEntry entry(ref, true);
+\endcode
+
+	<b>Save Notifications</b>
+
+	Save notifications are always sent to the target's MessageReceived()
+	method unlike open notifications. The \c what field of the message is
+	set to \c B_SAVE_REQUESTED. The \c directory field contain a single
+	\c entry_ref structure that points to the directory that the entry is
+	saved to. The text that the user typed in the save panel's text view
+	is put in the \c name field and is of type \c B_STRING_TYPE.
+
+	<b>Cancel Notifications</b>
+
+	Cancel notifications are sent when the panel is hidden whether by the
+	user clicking the cancel button, closing the dialog, or confirming the
+	action (assuming hide-when-done is turned on).
+
+	Cancel notifications can be caught by the MessageReceived() method of
+	the target. The \c what field is set to \c B_CANCEL. The \c old_what
+	field is set to the previous what value which is useful if you have
+	overridden the default message. The \c what field of the message you
+	sent is put in the \c old_what field.
+
+	The \c source field is a pointer of \c B_POINTER_TYPE to the closed
+	BFilePanel object. When the BFilePanel object is closed it is not
+	destroyed, it is hidden instead. You can then delete the BFilePanel
+	object or leave it be and simply call Show() to use the panel next time
+	you need it.
 */
 
 
@@ -109,18 +173,27 @@
 		BMessage* message, BRefFilter* filter, bool modal, bool hideWhenDone)
 	\brief Creates and initializes a BFilePanel object.
 
-	The panel is not displayed until call the Show() method.
+	The constructor has many parameters but they may generally be set after
+	the object has been constructed. The only parameters that must be set
+	during construction are the \a mode, \a nodeFlavors, \a multipleSelection,
+	and \a modal parameters. The rest may be set after the object has been
+	constructed by the SetTarget(), SetPanelDirectory(), SetMessage(),
+	SetRefFilter(), and SetHideWhenDone() methods.
 
-	\param mode Either \c B_OPEN_PANEL or \c B_SAVE_PANEL.
+	\param mode Set to \c B_OPEN_PANEL for an open panal or \c B_SAVE_PANEL
+		for a save panel. Default is \c B_OPEN_PANEL.
 	\param target The BMessenger object that sends messages to the BLooper
 		or BHandler controlled by the file panel.
 	\param ref The directory to display, by default the current working
 		directory.
-	\param nodeFlavors Option flags, this applies to open panels only.
-	\param multipleSelection Determines whether or not the user is allowed
-		to select more than one item.
-	\param message Override the default message sent by the file panel.
-	\param filter Filter Hook function to call.
+	\param nodeFlavors One or more option flags, this applies to open panels only.
+		- \c B_FILE_NODE Can select files and symlinks to files.
+		- \c B_DIRECTORY_NODE Can select directories and symlinks to directories.
+		- \c B_SYMLINK_NODE Can select symlinks only.
+	\param multipleSelection Whether or not the user is allowed to select more
+		than one item to open. Save panels should always set this to \c false.
+	\param message Message sent by the file panel on confirms or cancels.
+	\param filter Hook method to call.
 	\param modal Whether or not the panel is modal, defaults to \c false.
 	\param hideWhenDone Set to \c false to keep the panel even after the user
 		confirms or cancels. The close button will hide the panel regardless.