diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 3350d2605f..11cfaff2be 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,14 @@ +2004-02-27 Federico Mena Quintero + + * gtk/migrating-GtkAction.sgml: Put explicit elements + instead of #Symbol, because the latter doesn't get substituted by + gtk-doc outside of template files. Thanks to Matthias for + pointing this out. + + * gtk/migrating-GtkFileChooser.sgml: Likewise. + + * gtk/gtk-sections.txt: Removed gtk_file_chooser_{set,get}_folder_mode. + Fri Feb 27 22:51:35 2004 Matthias Clasen * gtk/tmpl/gtkoptionmenu.sgml: diff --git a/docs/reference/gtk/gtk-sections.txt b/docs/reference/gtk/gtk-sections.txt index 4f30665c2a..1c757027c8 100644 --- a/docs/reference/gtk/gtk-sections.txt +++ b/docs/reference/gtk/gtk-sections.txt @@ -1112,8 +1112,6 @@ GtkFileChooserError gtk_file_chooser_error_quark gtk_file_chooser_set_action gtk_file_chooser_get_action -gtk_file_chooser_set_folder_mode -gtk_file_chooser_get_folder_mode gtk_file_chooser_set_local_only gtk_file_chooser_get_local_only gtk_file_chooser_set_select_multiple diff --git a/docs/reference/gtk/migrating-GtkAction.sgml b/docs/reference/gtk/migrating-GtkAction.sgml index a0ed93672b..00f45fa62c 100644 --- a/docs/reference/gtk/migrating-GtkAction.sgml +++ b/docs/reference/gtk/migrating-GtkAction.sgml @@ -15,36 +15,40 @@ Prior to GTK+ 2.4, there were several APIs in use to create menus - and toolbars. GTK+ itself included #GtkItemFactory, which was + and toolbars. GTK+ itself included GtkItemFactory, which was historically used in the GIMP; libgnomeui provided the gnome-ui set of macros; libbonoboui provided a complex mechanism to do menu merging across embedded components. GTK+ 2.4 includes a system for creating menus and toolbars, with merging of items, based - around the #GtkAction mechanism. + around the GtkAction mechanism.
Actions and Action Groups - A #GtkAction represents an operation that the user can perform - from the menus and toolbars of an application. It is similar to - "verbs" in other menu systems. A #GtkAction has a name, which - is its identifier, and it can have several widgets that - represent it in the user interface. For example, an action for - EditCopy can have a menu item as well as a + A GtkAction represents an + operation that the user can perform from the menus and toolbars + of an application. It is similar to "verbs" in other menu + systems. A GtkAction has a + name, which is its identifier, and it can have several widgets + that represent it in the user interface. For example, an action + for EditCopy can have a menu item as well as a toolbar button associated to it. If there is nothing selected in the document, the application can simply de-sensitize the EditCopy action; this will cause both the menu item and the toolbar button to be de-sensitized automatically. Similarly, whenever the user selects the menu item or the toolbar button associated to the EditCopy - action, the corresponding #GtkAction object will emit an + action, the corresponding GtkAction object will emit an "activate" signal. - #GtkActionGroup is simply a group of #GtkAction objects. An + GtkActionGroup is simply a + group of GtkAction objects. An application may want to have several groups: one for global actions such as "new document", "about", and "exit"; then one group for each open document with actions specific to the @@ -68,20 +72,22 @@ User Interface Manager Object - #GtkUIManager is an object that can construct menu and toolbar - widgets from an XML description. These widgets are in turn - associated to corresponding actions and action groups. + GtkUIManager is an object + that can construct menu and toolbar widgets from an XML + description. These widgets are in turn associated to + corresponding actions and action groups. - #GtkUIManager supports merging of menus and toolbars for - applications that have multiple components, each with separate - sets of commands. For example, a word processor that can embed - images may want to have toolbar buttons for Bold and Italic when - the cursor is on a text block, but Crop and Brightness/Contrast - buttons when the cursor is on an image. These actions, which - change depending on the state of the application, can be merged - and de-merged from a #GtkUIManager as appropriate. + GtkUIManager supports + merging of menus and toolbars for applications that have + multiple components, each with separate sets of commands. For + example, a word processor that can embed images may want to have + toolbar buttons for Bold and Italic when the cursor is on a text + block, but Crop and Brightness/Contrast buttons when the cursor + is on an image. These actions, which change depending on the + state of the application, can be merged and de-merged from a + GtkUIManager as appropriate.
@@ -135,25 +141,28 @@ Separate your existing GnomeUIInfo entries into normal - actions, toggle actions, and radio actions, and then create a - separate array of #GtkActionEntry structures for each - group. This will allow you to create the necessary - #GtkActionGroup objects. Note that this does not describe - the actual "shape" that your menus and toolbars will have; - it simply defines the set of commands that will appear in them. + actions, toggle actions, and radio actions, and then create + a separate array of GtkActionEntry structures + for each group. This will allow you to create the necessary + GtkActionGroup + objects. Note that this does not describe the actual + "shape" that your menus and toolbars will have; it simply + defines the set of commands that will appear in them. Create an XML description of your menus and toolbars for use - with #GtkUIManager. This defines the actual shape of the - menus and toolbars. + with GtkUIManager. This + defines the actual shape of the menus and toolbars. Port the code that uses gnome-app and gnome-app-helper to - #GtkAction and #GtkUIManager. + GtkAction and GtkUIManager. @@ -248,14 +257,14 @@ static GnomeUIInfo menubar[] = { The following code is the set of actions that are present in the previous example. Note that the toggle and radio entries are - separate from normal actions. Also, note that #GtkActionEntry - structures take key names in the format of - gdk_accelerator_parse() rather than key values plus modifiers; - you will have to convert these values by hand. For example, - GDK_F11 with no modifiers is equivalent - to a key name of "F11". Likewise, - "o" with - GDK_CONTROL_MASK is equivalent to + separate from normal actions. Also, note that GtkActionEntry structures take + key names in the format of gdk_accelerator_parse() rather than + key values plus modifiers; you will have to convert these + values by hand. For example, GDK_F11 + with no modifiers is equivalent to a key name of + "F11". Likewise, "o" + with GDK_CONTROL_MASK is equivalent to "<ontrol>O". @@ -290,15 +299,15 @@ static GtkRadioActionEntry radio_entries[] = { After extracting the actions, you will need to create an XML description of the actual layout of your menus and toolbars - for use with #GtkUIManager. The following code shows a simple - menu bar that corresponds to the previous example. Note - that the File and View - menus have their names specified in the action entries, - not in the XML itself. This is because the XML description - only contains identifiers for the items - in the GUI, rather than human-readable names. + for use with GtkUIManager. + The following code shows a simple menu bar that corresponds to + the previous + example. Note that the File and + View menus have their names specified in + the action + entries, not in the XML itself. This is because the + XML description only contains identifiers + for the items in the GUI, rather than human-readable names. @@ -328,13 +337,16 @@ static const char *ui_description = Creating the Menu Bar - In this last example, we will create a #GtkActionGroup based - on the action - entries we created above. We will then create a - #GtkUIManager with the XML - description of the menu layout. We will also extract - the accelerator group and the widgets from the #GtkUIManager - put them into a window. + In this last example, we will create a GtkActionGroup based on the + action + entries we created above. We will then create a GtkUIManager with the XML description of the menu + layout. We will also extract the accelerator group and the + widgets from the GtkUIManager put them into a + window. diff --git a/docs/reference/gtk/migrating-GtkFileChooser.sgml b/docs/reference/gtk/migrating-GtkFileChooser.sgml index fb3d48ffb9..8316ff6f07 100644 --- a/docs/reference/gtk/migrating-GtkFileChooser.sgml +++ b/docs/reference/gtk/migrating-GtkFileChooser.sgml @@ -14,33 +14,42 @@ Migrating from GtkFileSelection to GtkFileChooser - #GtkFileChooser, starting with GTK+ 2.4, is the new set of APIs - for file selection widgets and dialogs. Previous versions of GTK+ - used #GtkFileSelection, which has numerous problems. + GtkFileChooser, starting + with GTK+ 2.4, is the new set of APIs for file selection widgets + and dialogs. Previous versions of GTK+ used GtkFileSelection, which has + numerous problems. - #GtkFileChooser is an abstract interface that can be implemented - by widgets that perform file selection tasks. Two widgets in GTK+ - implement this interface: #GtkFileChooserDialog and - #GtkFileChooserWidget. Most applications simply need to use - #GtkFileChooserDialog, which is a dialog box that allows the user - to select existing files for opening them, or to pick new - filenames for saving documents. #GtkFileChooserWidget is for - special applications that need to embed a file selection widget - inside a larger window. In the context of GTK+, - #GtkFileChooserDialog is simply a #GtkDialog box with a - #GtkFileChooserWidget inside. + GtkFileChooser is an + abstract interface that can be implemented by widgets that perform + file selection tasks. Two widgets in GTK+ implement this + interface: GtkFileChooserDialog and + GtkFileChooserWidget. + Most applications simply need to use GtkFileChooserDialog, which + is a dialog box that allows the user to select existing files for + opening them, or to pick new filenames for saving documents. + GtkFileChooserWidget + is for special applications that need to embed a file selection + widget inside a larger window. In the context of GTK+, GtkFileChooserDialog is + simply a GtkDialog box with a + GtkFileChooserWidget + inside.
Creating a GtkFileChooserDialog - To create a #GtkFileChooserDialog, you simply call - gtk_file_chooser_dialog_new(). This function is similar to - gtk_dialog_new() in that it takes parameters for the title - of the dialog box and its transient parent, as well as its + To create a GtkFileChooserDialog, you + simply call gtk_file_chooser_dialog_new(). This function is + similar to gtk_dialog_new() in that it takes parameters for the + title of the dialog box and its transient parent, as well as its buttons. In addition, it takes in an argument that determines whether the file chooser dialog will be used for opening existing files or for saving to a possibly new file. @@ -57,24 +66,26 @@ Selection Modes - #GtkFileChooser can be used in two modes, to select a single - file at a time or to select a set of more than one file. To set - this, use gtk_file_chooser_set_select_multiple(). In - single-selection mode, you can use - gtk_file_chooser_get_filename() to get a file name from the - local file system or gtk_file_chooser_get_uri() to get a - full-formed URI. In multiple-selection mode, you can use - gtk_file_chooser_get_filenames() to get a #GSList of filename - strings, or gtk_file_chooser_get_uris() to get a list of URI - strings. + GtkFileChooser can be used + in two modes, to select a single file at a time or to select a + set of more than one file. To set this, use + gtk_file_chooser_set_select_multiple(). In single-selection + mode, you can use gtk_file_chooser_get_filename() to get a file + name from the local file system or gtk_file_chooser_get_uri() to + get a full-formed URI. In multiple-selection mode, you can use + gtk_file_chooser_get_filenames() to get a GSList of filename strings, or + gtk_file_chooser_get_uris() to get a list of URI strings. - Also, you can configure #GtkFileChooser to select files or - folders. Consider a backup program that needs to let the user - select a folder that will be backed up along with its - subfolders. To configure whether #GtkFileChooser is used to - select files or folders, use gtk_file_chooser_set_action(). In + Also, you can configure GtkFileChooser to select files + or folders. Consider a backup program that needs to let the + user select a folder that will be backed up along with its + subfolders. To configure whether GtkFileChooser is used to select + files or folders, use gtk_file_chooser_set_action(). In addition, this lets you configure whether the file chooser will be used to select existing files or folders (e.g. for "File/Open"), or to type in new filenames (for @@ -88,9 +99,11 @@ Many applications need to have a preview facility within their file chooser dialogs. Previous to GTK+ 2.4, one needed to - access the #GtkFileSelection widget hierarchy directly to hook - in a preview widget. With #GtkFileChooser, there is a dedicated - API to do this. + access the GtkFileSelection widget + hierarchy directly to hook in a preview widget. With GtkFileChooser, there is a + dedicated API to do this. @@ -119,15 +132,18 @@ New features - New features in #GtkFileChooser include the following: + New features in GtkFileChooser include the + following: Ability to select URIs rather than just local files. You - must use a #GtkFileSystem implementation that supports this, - for example GtkFileSystemGnomeVFS. + must use a GtkFileSystem implementation + that supports this, for example the gnome-vfs backend. @@ -150,8 +166,9 @@ - To see how to use these features, please consult the - #GtkFileChooser reference documentation. + To see how to use these features, please consult the GtkFileChooser reference + documentation.