From d91296979365a18454a22f8f1a83794daff2b690 Mon Sep 17 00:00:00 2001 From: Shane Landrum Date: Wed, 29 Dec 2004 15:12:34 +0000 Subject: [PATCH] 2004-12-29 Shane Landrum * en/Gtk/FileChooserEmbed.xml * en/Gtk/FileChooserDialog.xml * en/Gtk/FileChooserWidget.xml * en/Gtk/FileFilter.xml * en/Gtk/FileFilterFlags.xml * en/Gtk/FileChooser.xml: file chooser and filter docs. svn path=/trunk/gtk-sharp/; revision=38156 --- doc/ChangeLog | 9 + doc/en/Gtk/FileChooser.xml | 14 +- doc/en/Gtk/FileChooserDialog.xml | 349 +++++++++++++++++++++++-------- doc/en/Gtk/FileChooserEmbed.xml | 4 +- doc/en/Gtk/FileChooserWidget.xml | 332 +++++++++++++++++++++-------- doc/en/Gtk/FileFilter.xml | 2 +- doc/en/Gtk/FileFilterFlags.xml | 8 +- 7 files changed, 529 insertions(+), 189 deletions(-) diff --git a/doc/ChangeLog b/doc/ChangeLog index 39948e5d9..3809907c0 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,12 @@ +2004-12-29 Shane Landrum + + * en/Gtk/FileChooserEmbed.xml + * en/Gtk/FileChooserDialog.xml + * en/Gtk/FileChooserWidget.xml + * en/Gtk/FileFilter.xml + * en/Gtk/FileFilterFlags.xml + * en/Gtk/FileChooser.xml: file chooser and filter docs. + 2004-12-28 Jeroen Zwartepoorte * en/Gnome.Vfs/*.xml: more docs. diff --git a/doc/en/Gtk/FileChooser.xml b/doc/en/Gtk/FileChooser.xml index 5a9a57d2a..d4f6f057c 100644 --- a/doc/en/Gtk/FileChooser.xml +++ b/doc/en/Gtk/FileChooser.xml @@ -1,4 +1,4 @@ - +e gtk-sharp @@ -9,8 +9,8 @@ Gtk# is thread aware, but not thread safe; See the Gtk# Thread Programming for details. - Class for a file-chooser dialog. - + Interface for a file-chooser. + See for an actual implementation. @@ -499,7 +499,7 @@ Applications that want to draw the whole preview area themselves should set this to false and display the name themselves in their preview widget. - + @@ -545,7 +545,7 @@ or . It cannot be set with either of the folder actions. - + @@ -594,8 +594,8 @@ Sets the type of operation that that the chooser is performing; the - user interface is adapted to suit the selected action. - + user interface is adapted to suit the selected action. + a For example, diff --git a/doc/en/Gtk/FileChooserDialog.xml b/doc/en/Gtk/FileChooserDialog.xml index dc191d42c..c14031136 100644 --- a/doc/en/Gtk/FileChooserDialog.xml +++ b/doc/en/Gtk/FileChooserDialog.xml @@ -10,8 +10,7 @@ Gtk# is thread aware, but not thread safe; See the Gtk# Thread Programming for details. A dialog box for choosing files. - - + Similar to but in a dialog. Gtk.Dialog @@ -55,11 +54,15 @@ - To be added - a - a + + Sets the current folder for the chooser from an URI. + + a , the URI to use + a , true if the folder could be changed successfully, false otherwise - + The user will be shown the full contents of the current folder, + plus user interface elements for navigating to other folders. + @@ -70,9 +73,8 @@ - To be added - - + Unselects all the files in the current folder of a file chooser. + @@ -85,11 +87,26 @@ - To be added + + Sets as the current filename for + the file chooser; + If the file name isn't in the current folder of the file chooser, then the + current folder of the file chooser will be changed to the folder containing + . + a - a + a , true if both the + folder could be changed and the file was + selected successfully, false otherwise. - + This is equivalent to a sequence of + + followed by . + + Note that the file must exist, or nothing will be done except + for the directory change. To pre-enter a filename for the user, as in + a save-as dialog, use . + @@ -102,11 +119,14 @@ - To be added + + Removes a folder URI from a file chooser's list of shortcut folders. + a a - + See also . + @@ -119,11 +139,18 @@ - To be added + + Adds a folder URI to be displayed with the shortcut folders in a file + chooser. + a - a + a , true if the folder + could be added successfully, false otherwise. - + Note that shortcut folders do not get saved, as they are provided + by the application. For example, you can use this to add a + "file:///usr/share/mydrawprogram/Clipart" folder to the volume list. + @@ -134,7 +161,7 @@ - To be added + Selects all the files in the current folder of a file chooser. @@ -149,9 +176,15 @@ - To be added + + Selects the file at . If the URI doesn't refer to a + file in the current folder of the file chooser, then the current folder of + the file chooser will be changed to the folder that's part of . + a - a + a , true if both the + folder could be changed and the URI was + selected successfully, false otherwise. @@ -166,10 +199,10 @@ - To be added + Removes from the list of filters that the user can select between. a - + @@ -182,11 +215,14 @@ - To be added + Adds a folder to be displayed with the shortcut folders in a file chooser. a a - + Note that shortcut folders do not get saved, as they are provided by the + application. For example, you can use this to add a + "/usr/share/mydrawprogram/Clipart" folder to the volume list. + @@ -199,11 +235,14 @@ - To be added + Selects a filename. a a - + If the file name isn't in the current + folder of the file chooser, then the current folder of the file chooser will + be changed to the folder containing . + @@ -216,10 +255,14 @@ - To be added + + Unselects a currently selected filename. + a - + If the filename is not in the current directory, does not exist, or + is otherwise not currently selected, does nothing. + @@ -232,10 +275,15 @@ - To be added + + Adds to the list of filters that the + user can select between. + a - + When a filter is selected, only files that are passed by that + filter are displayed. + @@ -248,11 +296,10 @@ - To be added + Removes a folder from a file chooser's list of shortcut folders. a a - - + See also . @@ -265,10 +312,14 @@ - To be added + + Unselects the file referred to by . + a - + If the file is not in the current directory, does not exist, or + is otherwise not currently selected, does nothing. + @@ -281,11 +332,15 @@ - To be added + + Sets the current folder for the file chooser from a local filename. + a a - + The user will be shown the full contents of the current folder, + plus user interface elements for navigating to other folders. + @@ -298,10 +353,25 @@ - To be added + + Sets the file referred to by as the + current file for the the file chooser. + a - a + a , true if both the folder + could be changed and the URI was + selected successfully, false otherwise. + If the file name isn't in the current folder of the file chooser, + then the current folder of the file chooser will be changed to the folder containing + . This is equivalent to a sequence of + + followed by . + + Note that the file must exist, or nothing will be done except + for the directory change. To pre-enter a filename for the user, as in + a save-as dialog, use . + @@ -361,7 +431,7 @@ - To be added + Protected constructor. a a @@ -376,8 +446,8 @@ - To be added - a + Constructor for internal use. + a , pointer to underlying C object. a @@ -393,10 +463,10 @@ - To be added - a - a - a + Public constructor. + a , title for the dialog + a , parent window + a , the action this dialog should be doing a @@ -436,7 +506,7 @@ - To be added + The of this object. a @@ -450,7 +520,7 @@ - To be added + The file chooser's current folder, if set from a URI. a @@ -464,7 +534,7 @@ - To be added + An application-supplied widget to provide extra options to the user. a @@ -477,10 +547,16 @@ System.String - To be added + + Property to represent the current name in the file selector, + as if entered by the user. + a - + Note that the name passed in here is a UTF-8 + string rather than a filename. This function is meant for + such uses as a suggested name in a "Save As..." dialog. + @@ -491,7 +567,7 @@ - To be added + The currently-applied file filter. a @@ -505,10 +581,22 @@ - To be added + + Sets whether only local files can be selected in the + file selector. + a - + If true (the default), + then the selected file are files are guaranteed to be + accessible through the operating systems native file + file system and therefore the application only + needs to worry about the filename functions in + , like + , + rather than the URI functions like + . + @@ -519,10 +607,14 @@ - To be added + + Sets whether the preview widget set by + should be shown for the current filename. + a - - + When this property is set to false, the file chooser + may display an internally generated preview of the current file + or it may display no preview at all. @@ -533,10 +625,9 @@ - To be added + Internal function; gets the filename that should be previewed in a custom preview. a - - + Not for general programmer use. @@ -547,10 +638,15 @@ - To be added + The URI for the currently selected file in + the file selector. a - + If multiple files are selected, + one of the filenames will be returned at random. + If the file chooser is in folder mode, this function returns the + selected folder. + @@ -561,10 +657,16 @@ - To be added + + Sets whether the file chooser should display a stock label with the name of + the file that is being previewed; the default is true. + a - + Applications that + want to draw the whole preview area themselves should set this + to false and display the name themselves in their preview widget. + @@ -575,7 +677,7 @@ - To be added + The current filename selected by the file chooser. a @@ -589,7 +691,7 @@ - To be added + The URI that should be previewed in a custom preview widget. a @@ -603,10 +705,16 @@ - To be added + + Sets whether multiple files can be selected in the file selector. + a - + This is only relevant if the action is set to be + or + . + It cannot be set with either of the folder actions. + @@ -617,10 +725,32 @@ - To be added + + An application-supplied widget to use to display a custom preview + of the currently selected file. + a - + + To implement a preview, after setting the + preview widget, you connect to the + + signal, and check + or + + on each change. If you can + display a preview of the new file, update your widget and + set the preview active using + + Otherwise, set the preview inactive. + + + When there is no application-supplied preview widget, or the + application-supplied preview widget is not active, the file chooser + may display an internally generated preview of the current file or + it may display no preview at all. + + @@ -631,10 +761,17 @@ - To be added + + Sets the type of operation that that the chooser is performing; the + user interface is adapted to suit the selected action. + a - + For example, + an option to create a new folder might be shown if the action is + but not if the action is + . + @@ -645,7 +782,7 @@ - To be added + The current folder for the file chooser, when the chooser has selected a local filename. a @@ -659,7 +796,7 @@ - To be added + The filenames selected by this widget. a @@ -673,7 +810,7 @@ - To be added + The URIs selected by this dialog. a @@ -687,7 +824,7 @@ - To be added + The filters currently in use by this dialog for patterns of files to display. a @@ -701,7 +838,7 @@ - To be added + The shortcut folders currently in use for this dialog. a @@ -715,7 +852,7 @@ - To be added + The shortcut URIs currently allowed for this dialog. a @@ -729,9 +866,9 @@ - To be added + This event is fired every time the selected file changes. - + @@ -742,9 +879,17 @@ - To be added + + This signal is emitted when the user "activates" a file in the file + chooser. + - + This event can happen by double-clicking on a file in the file list, or + by pressing Enter. + + Normally you do not need to connect to this signal. It is used internally + by the file chooser code to know when to activate the default button in the dialog. + @@ -755,9 +900,29 @@ - To be added + + This signal is emitted when the preview in a file chooser should be + regenerated. For example, this can happen when the currently + selected file changes. + - + You should use this signal if you want your file chooser to have + a preview widget. + + Once you have installed a preview widget with + , you should update it when this + signal is emitted. You can use the properties + or + + to get the name of the file to preview. + Your widget may not be able to preview all kinds of files; your callback + must set to inform the file + chooser about whether the preview was generated successfully or not. + + + TODO: insert example from gtkfilechooser-preview in gtk+ docs. + + @@ -768,10 +933,20 @@ - To be added + + This signal is emitted when the current folder in a file chooser + changes. + - + This event can happen due to the user performing some action that + changes folders, such as selecting a bookmark or visiting a folder on the + file list. It can also happen as a result of calling a function to + explicitly change the current folder in a file chooser. + + Normally you do not need to connect to this signal, unless you need to keep + track of which folder a file chooser is showing. + - \ No newline at end of file + diff --git a/doc/en/Gtk/FileChooserEmbed.xml b/doc/en/Gtk/FileChooserEmbed.xml index 8cf39b9f4..fe86d9b61 100644 --- a/doc/en/Gtk/FileChooserEmbed.xml +++ b/doc/en/Gtk/FileChooserEmbed.xml @@ -9,7 +9,7 @@ Gtk# is thread aware, but not thread safe; See the Gtk# Thread Programming for details. - To be added + An interface allowing file choosers to be embedded in other widgets. @@ -28,7 +28,7 @@ - To be added + Event fired when the default size of the file chooser object changes. diff --git a/doc/en/Gtk/FileChooserWidget.xml b/doc/en/Gtk/FileChooserWidget.xml index fe960dd46..da1487bbf 100644 --- a/doc/en/Gtk/FileChooserWidget.xml +++ b/doc/en/Gtk/FileChooserWidget.xml @@ -9,7 +9,7 @@ Gtk# is thread aware, but not thread safe; See the Gtk# Thread Programming for details. - To be added + Widget to allow the selection of files from a directory. @@ -43,7 +43,7 @@ - To be added + Override to accomplish actions that must happen before object destruction. @@ -58,11 +58,15 @@ - To be added - a - a + + Sets the current folder for the chooser from an URI. + + a , the URI to use + a , true if the folder could be changed successfully, false otherwise - + The user will be shown the full contents of the current folder, + plus user interface elements for navigating to other folders. + @@ -73,9 +77,8 @@ - To be added - - + Unselects all the files in the current folder of a file chooser. + @@ -88,11 +91,26 @@ - To be added + + Sets as the current filename for + the file chooser; + If the file name isn't in the current folder of the file chooser, then the + current folder of the file chooser will be changed to the folder containing + . + a - a + a , true if both the + folder could be changed and the file was + selected successfully, false otherwise. - + This is equivalent to a sequence of + + followed by . + + Note that the file must exist, or nothing will be done except + for the directory change. To pre-enter a filename for the user, as in + a save-as dialog, use . + @@ -105,11 +123,14 @@ - To be added + + Removes a folder URI from a file chooser's list of shortcut folders. + a a - + See also . + @@ -122,11 +143,18 @@ - To be added + + Adds a folder URI to be displayed with the shortcut folders in a file + chooser. + a - a + a , true if the folder + could be added successfully, false otherwise. - + Note that shortcut folders do not get saved, as they are provided + by the application. For example, you can use this to add a + "file:///usr/share/mydrawprogram/Clipart" folder to the volume list. + @@ -137,7 +165,7 @@ - To be added + Selects all the files in the current folder of a file chooser. @@ -152,9 +180,15 @@ - To be added + + Selects the file at . If the URI doesn't refer to a + file in the current folder of the file chooser, then the current folder of + the file chooser will be changed to the folder that's part of . + a - a + a , true if both the + folder could be changed and the URI was + selected successfully, false otherwise. @@ -169,10 +203,10 @@ - To be added + Removes from the list of filters that the user can select between. a - + @@ -185,11 +219,14 @@ - To be added + Adds a folder to be displayed with the shortcut folders in a file chooser. a a - + Note that shortcut folders do not get saved, as they are provided by the + application. For example, you can use this to add a + "/usr/share/mydrawprogram/Clipart" folder to the volume list. + @@ -202,11 +239,14 @@ - To be added + Selects a filename. a a - + If the file name isn't in the current + folder of the file chooser, then the current folder of the file chooser will + be changed to the folder containing . + @@ -219,10 +259,14 @@ - To be added + + Unselects a currently selected filename. + a - + If the filename is not in the current directory, does not exist, or + is otherwise not currently selected, does nothing. + @@ -235,10 +279,15 @@ - To be added + + Adds to the list of filters that the + user can select between. + a - + When a filter is selected, only files that are passed by that + filter are displayed. + @@ -251,11 +300,10 @@ - To be added + Removes a folder from a file chooser's list of shortcut folders. a a - - + See also . @@ -268,10 +316,14 @@ - To be added + + Unselects the file referred to by . + a - + If the file is not in the current directory, does not exist, or + is otherwise not currently selected, does nothing. + @@ -284,11 +336,15 @@ - To be added + + Sets the current folder for the file chooser from a local filename. + a a - + The user will be shown the full contents of the current folder, + plus user interface elements for navigating to other folders. + @@ -301,9 +357,14 @@ - To be added + + Sets the file referred to by as the + current file for the the file chooser. + a - a + a , true if both the folder + could be changed and the URI was + selected successfully, false otherwise. @@ -376,7 +437,7 @@ - To be added + Protected constructor. a a @@ -391,8 +452,8 @@ - To be added - a + Constructor for internal use. + a , pointer to underlying C object a @@ -406,8 +467,8 @@ - To be added - a + Public constructor. + a , the action this chooser will perform a @@ -422,9 +483,9 @@ - To be added - a - a + Public constructor. + a , the action this widget should perform + a , the filesystem back-end to use. a @@ -438,7 +499,7 @@ - To be added + The for this object. a @@ -452,7 +513,7 @@ - To be added + The file chooser's current folder, if set from a URI. a @@ -466,7 +527,7 @@ - To be added + An application-supplied widget to provide extra options to the user. a @@ -479,10 +540,16 @@ System.String - To be added + + Property to represent the current name in the file selector, + as if entered by the user. + a - + Note that the name passed in here is a UTF-8 + string rather than a filename. This function is meant for + such uses as a suggested name in a "Save As..." dialog. + @@ -493,7 +560,7 @@ - To be added + The currently-applied file filter. a @@ -507,10 +574,22 @@ - To be added + + Sets whether only local files can be selected in the + file selector. + a - + If true (the default), + then the selected file are files are guaranteed to be + accessible through the operating systems native file + file system and therefore the application only + needs to worry about the filename functions in + , like + , + rather than the URI functions like + . + @@ -521,10 +600,14 @@ - To be added + + Sets whether the preview widget set by + should be shown for the current filename. + a - - + When this property is set to false, the file chooser + may display an internally generated preview of the current file + or it may display no preview at all. @@ -535,10 +618,9 @@ - To be added + Internal function; gets the filename that should be previewed in a custom preview. a - - + Not for general programmer use. @@ -549,10 +631,15 @@ - To be added + The URI for the currently selected file in + the file selector. a - + If multiple files are selected, + one of the filenames will be returned at random. + If the file chooser is in folder mode, this function returns the + selected folder. + @@ -563,10 +650,16 @@ - To be added + + Sets whether the file chooser should display a stock label with the name of + the file that is being previewed; the default is true. + a - + Applications that + want to draw the whole preview area themselves should set this + to false and display the name themselves in their preview widget. + @@ -577,7 +670,7 @@ - To be added + The current filename selected by the file chooser. a @@ -591,7 +684,7 @@ - To be added + The URI that should be previewed in a custom preview widget. a @@ -605,10 +698,16 @@ - To be added + + Sets whether multiple files can be selected in the file selector. + a - + This is only relevant if the action is set to be + or + . + It cannot be set with either of the folder actions. + @@ -619,10 +718,32 @@ - To be added + + An application-supplied widget to use to display a custom preview + of the currently selected file. + a - + + To implement a preview, after setting the + preview widget, you connect to the + + signal, and check + or + + on each change. If you can + display a preview of the new file, update your widget and + set the preview active using + + Otherwise, set the preview inactive. + + + When there is no application-supplied preview widget, or the + application-supplied preview widget is not active, the file chooser + may display an internally generated preview of the current file or + it may display no preview at all. + + @@ -633,10 +754,17 @@ - To be added + + Sets the type of operation that that the chooser is performing; the + user interface is adapted to suit the selected action. + a - + For example, + an option to create a new folder might be shown if the action is + but not if the action is + . + @@ -647,7 +775,7 @@ - To be added + The current folder for the file chooser, when the chooser has selected a local filename. a @@ -661,7 +789,7 @@ - To be added + The filenames selected by this widget. a @@ -675,7 +803,7 @@ - To be added + The URIs selected by this widget. a @@ -689,7 +817,7 @@ - To be added + The filters currently in use by this widget for patterns of files to display. a @@ -703,7 +831,7 @@ - To be added + The shortcut folders currently in use for this widget. a @@ -717,7 +845,7 @@ - To be added + The shortcut URIs currently allowed for this widget. a @@ -731,9 +859,9 @@ - To be added + This event is fired every time the selected file changes. - + @@ -744,9 +872,17 @@ - To be added + + This signal is emitted when the user "activates" a file in the file + chooser. + - + This event can happen by double-clicking on a file in the file list, or + by pressing Enter. + + Normally you do not need to connect to this signal. It is used internally + by the file chooser code to know when to activate the default button in the dialog. + @@ -757,9 +893,29 @@ - To be added + + This signal is emitted when the preview in a file chooser should be + regenerated. For example, this can happen when the currently + selected file changes. + - + You should use this signal if you want your file chooser to have + a preview widget. + + Once you have installed a preview widget with + , you should update it when this + signal is emitted. You can use the properties + or + + to get the name of the file to preview. + Your widget may not be able to preview all kinds of files; your callback + must set to inform the file + chooser about whether the preview was generated successfully or not. + + + TODO: insert example from gtkfilechooser-preview in gtk+ docs. + + @@ -770,7 +926,7 @@ - To be added + Event fired when the chooser changes the folder it's looking at. @@ -783,10 +939,10 @@ - To be added + Event fired when the size of the widget changes. - \ No newline at end of file + diff --git a/doc/en/Gtk/FileFilter.xml b/doc/en/Gtk/FileFilter.xml index 76a0d9093..03cb506d0 100644 --- a/doc/en/Gtk/FileFilter.xml +++ b/doc/en/Gtk/FileFilter.xml @@ -144,7 +144,7 @@ - To be added + The of this object. a diff --git a/doc/en/Gtk/FileFilterFlags.xml b/doc/en/Gtk/FileFilterFlags.xml index 9e84c0e35..39a9bd160 100644 --- a/doc/en/Gtk/FileFilterFlags.xml +++ b/doc/en/Gtk/FileFilterFlags.xml @@ -41,7 +41,7 @@ - To be added + The filename. @@ -54,7 +54,7 @@ - To be added + A URI. @@ -67,7 +67,7 @@ - To be added + The filename to display. @@ -80,7 +80,7 @@ - To be added + The MIME type of the file.