From a61895cb0c63834b1fc1b6fd88aa8868b790cd4c Mon Sep 17 00:00:00 2001 From: Miguel de Icaza Date: Fri, 6 Jul 2007 22:12:32 +0000 Subject: [PATCH] Apply patch from brian.nickel@gmail.com svn path=/trunk/gtk-sharp/; revision=81525 --- doc/en/Gtk/AboutDialog.xml | 236 +++++++++++++++------ doc/en/Gtk/AboutDialogActivateLinkFunc.xml | 18 +- doc/en/Gtk/AccelActivateArgs.xml | 25 +-- doc/en/Gtk/AccelActivateHandler.xml | 14 +- doc/en/Gtk/FontButton.xml | 138 ++++++++---- 5 files changed, 294 insertions(+), 137 deletions(-) diff --git a/doc/en/Gtk/AboutDialog.xml b/doc/en/Gtk/AboutDialog.xml index ad360c072..3a19b7673 100644 --- a/doc/en/Gtk/AboutDialog.xml +++ b/doc/en/Gtk/AboutDialog.xml @@ -7,7 +7,7 @@ Gtk# is thread aware, but not thread safe; See the Gtk# Thread Programming for details. - Display information about an application + This class extends , providing a dialog to show information about a program. The offers a simple way to display information about a program like its logo, name, copyright, website and license. It is also possible to give credits to the authors, documenters, translators and artists who have worked on the program. An about dialog is typically opened when the user selects the About option from the Help menu. All parts of the dialog are optional. @@ -19,6 +19,73 @@ About dialogs often contain links and email addresses. as convenient as possible, you can use the function which constructs and shows a dialog and keeps it around so that it can be shown again. --> + + The following example creates and shows a from both assembly attributes and stored values. + using Gtk; +using System.Reflection; + +[assembly:AssemblyTitleAttribute ("About Dialog Example")] +[assembly:AssemblyVersionAttribute ("1.0.0.0")] +[assembly:AssemblyDescriptionAttribute ( + "An example of the Gtk# AboutDialog using assembly attributes.")] +[assembly:AssemblyCopyrightAttribute("Copyright 2007 Brian Nickel")] + +static public class AboutDialogExample +{ + public static void Main () + { + Application.Init (); + + AboutDialog dialog = new AboutDialog (); + Assembly asm = Assembly.GetExecutingAssembly (); + + dialog.Name = (asm.GetCustomAttributes ( + typeof (AssemblyTitleAttribute), false) [0] + as AssemblyTitleAttribute).Title; + + dialog.Version = asm.GetName ().Version.ToString (); + + dialog.Comments = (asm.GetCustomAttributes ( + typeof (AssemblyDescriptionAttribute), false) [0] + as AssemblyDescriptionAttribute).Description; + + dialog.Copyright = (asm.GetCustomAttributes ( + typeof (AssemblyCopyrightAttribute), false) [0] + as AssemblyCopyrightAttribute).Copyright; + + dialog.License = license; + + dialog.Authors = authors; + + dialog.Run (); + } + + private static string [] authors = new string [] { + "Brian Nickel <name@domain.ext>", + "Rupert T. Monkey <name@domain.ext>" + }; + + private static string license = +@"Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +""Software""), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED ""AS IS"", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE +LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION +WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE."; +} + @@ -36,8 +103,8 @@ To make constructing a as convenient as possibl - Protected Constructor. - a + Constructs and initializes a new instance of for a specified native GLib type. + A object containing the native GLib type for the new instance. Chain to this constructor if you have manually registered a native value for your subclass. @@ -54,9 +121,9 @@ To make constructing a as convenient as possibl - Internal constructor - a - This is not typically used by C# code. + Constructs and initializes a new instance of using an existing unmanaged object as its base. + A pointing to the raw object to be managed by the new instance. + This is not typically used by managed code. It is primarily used for enclosing an existing object, created by unmanaged code, in a managed wrapper. @@ -65,8 +132,8 @@ To make constructing a as convenient as possibl - Default constructor - + Constructs and initializes a new instance of for the executing assembly. + With no properties set, the window will display only the name of the executing assembly. @@ -77,9 +144,9 @@ To make constructing a as convenient as possibl - GType Property. - a - Returns the native value for . + Gets the GLib type of the current instance. + A value representing the native GLib type of . + The value is used internally by the GLib type management system. @@ -90,9 +157,9 @@ To make constructing a as convenient as possibl - The license of the program. - a - This string is displayed in a text view in a secondary dialog, therefore it is fine to use a long multi-paragraph text. Note that the text is not wrapped in the text view, thus it must contain the intended linebreaks. + Gets and sets the license text of the program. + A object containing the license text to display with the current instance. + This string is displayed in a text view in a secondary dialog, therefore it is fine to use a long multi-paragraph text. Note that by default the text is not wrapped in the text view, thus it must contain the intended linebreaks. @@ -108,11 +175,9 @@ To make constructing a as convenient as possibl - The name of the program. - a - - - + Gets and sets the name of the program. + A object containing the name of the program. + The default value is the name of the executing assembly. This may be in the format "MyApplication.exe", "/path/to/MyApplication.exe", or "C:\Path\To\MyApplication.exe" depending on how the assembly was executed and on what platform. @@ -128,9 +193,11 @@ To make constructing a as convenient as possibl - Copyright information for the program. - a - + Gets and sets copyright information for the program. + A object containing copyright information for the program. + + The copyright text appears below the text and above the link on the dialog. If unset, not copyright text will appear. + @@ -146,9 +213,9 @@ To make constructing a as convenient as possibl - Credits to the translators. - a - This string should be marked as translatable. The string may contain email addresses and URLs, which will be displayed as links, see the introduction for more details. + Gets and sets credits for the translation of the program. + A object containing credits for the translation of the program. + This string should be marked as translatable. Each string may contain email addresses and URLs, which will be displayed as links. See the remarks on for more details. @@ -164,11 +231,25 @@ To make constructing a as convenient as possibl - A named icon to use as the logo for the about box. - a - This property overrides the property. - - + Gets and sets the name of the logo icon to display above the program name in the dialog. + A object containing the name of the logo icon to display above the program name in the dialog. + + +If set, this property overrides the property. + + The name should be equal to the name of the program, without any sort of extension, eg. "monodoc". The dialog will use that name to load an icon by trying the following: + + + The current icon theme, eg. "/usr/share/icons/Tango/48x48/apps/monodoc.png". + + + The pixmap directory, eg. "/usr/share/pixmaps/monodoc.png" + + + The broken image icon. + + + @@ -184,9 +265,9 @@ To make constructing a as convenient as possibl - The label for the link to the website of the program. - a - If this is not set, it defaults to the URL specified in the property. + Gets and sets the text label to display for the link to . + A containing the text label to display for the link to . + This value is used to provide a user friendly link to the website, for example "Visit home page." or "AppName website". If not set, the link defaults to the URL specified in the property. @@ -202,9 +283,14 @@ To make constructing a as convenient as possibl - A logo for the about box. - a - If this is not set, it defaults to . + Gets and sets a logo to display above the program name in the dialog. + A object containing a logo to display above the program name in the dialog. + + + The prefered way to set the logo is through . + + If this is not set, it defaults to . + @@ -220,9 +306,15 @@ To make constructing a as convenient as possibl - The URL for the link to the website of the program. - a - This should be a string starting with "http://". + Gets and sets the URL of the program's website. + A containing the URL of the program's website. + + The value should be a string starting with "http://". If set, the link is displayed at the bottom of the dialog, however if has not been used, the URL will appear as plain text and not be clickable. + + + may be used to provide a plain-text label for the link. + + @@ -238,9 +330,12 @@ To make constructing a as convenient as possibl - Comments about the program. - a - This string is displayed in a label in the main dialog, thus it should be a short explanation of the main purpose of the program, not a detailed list of features. + Gets and sets a comment about the program to appear immediately below the program name in the dialog. + A object containing a comment, description, or subtitle for the program. + + If unset, no comment text is displayed. + This string is displayed in a label in the main dialog, thus it should be a short explanation of the main purpose of the program, not a detailed list of features. + @@ -256,9 +351,9 @@ To make constructing a as convenient as possibl - The version of the program. - a - + Get and set the version of the program. + A object containing the version of the program. + The most appropriate value to put here would be the assembly version, but any string is valid, eg "2.0.0.1", "2.5.3", "2.0 RC1", etc. @@ -277,9 +372,13 @@ To make constructing a as convenient as possibl Installs a global function to be called whenever the user activates an email link in an about dialog. - a to call when an email link is activated. - a , the previous email hook. - + A delegate to be called when an email link is activated. + The delegate that was previously used as the email hook. + If no hook is set, email addresses will appear in the dialogs as standard non-clickable text. + +The following example uses the built in to open emails: Gtk.AboutDialog.SetEmailHook(delegate(Gtk.AboutDialog dialog, string email) { + Gnome.Url.Show("mailto:" + email); + }); @@ -293,9 +392,17 @@ To make constructing a as convenient as possibl Installs a global function to be called whenever the user activates a URL link in an about dialog. - a to call when a URL link is activated. - a that is the previous URL hook. - + A to be called when a URL link is activated. + The delegate that was the previous used as the URL hook. + + If no hook is set, the will in the dialogs appear as standard non-clickable text. + + The following example uses the built in to open links: + Gtk.AboutDialog.SetUrlHook(delegate(Gtk.AboutDialog dialog, string link) { + Gnome.Url.Show(link); + }); + + @@ -310,9 +417,9 @@ To make constructing a as convenient as possibl System.String[] - The people documenting the program. - a . - Each string may contain email addresses and URLs, which will be displayed as links, see the introduction for more details. + Gets and sets the list of people who contributed documentation to the program. + A containing the list of people who contributed documentation to the program. + Each string may contain email addresses and URLs, which will be displayed as links. See the remarks on for more details. @@ -327,9 +434,9 @@ To make constructing a as convenient as possibl System.String[] - The authors of the program. - a . - Each string may contain email addresses and URLs, which will be displayed as links, see the introduction for more details. + Gets and sets the list of people who authored the program. + A containing the list of people who authored the program. + Each string may contain email addresses and URLs, which will be displayed as links. See the remarks on for more details. @@ -344,9 +451,9 @@ To make constructing a as convenient as possibl System.String[] - The people who contributed artwork to the program. - a . - Each string may contain email addresses and URLs, which will be displayed as links, see the introduction for more details. + Gets and sets the list of people who contributed artwork to the program. + A containing the list of people who contributed artwork to the program. + Each string may contain email addresses and URLs, which will be displayed as links. See the remarks on for more details. @@ -361,12 +468,11 @@ To make constructing a as convenient as possibl System.Boolean - Indicates if the License text is automatically wrapped. - - if the text is auto-wrapped. - + Gets and sets whether the text in the is to be automatically wrapped. + If , the text is auto-wrapped. Otherwise long lines of text will extend past the edge of the frame and a horizontal scroll bar will appear. + By default, this option is set to . Most standard licenses, as will be found in the LICENSE file of a package, are already manually wrapped and auto-wrapping is unneccessary an unwanted. - + \ No newline at end of file diff --git a/doc/en/Gtk/AboutDialogActivateLinkFunc.xml b/doc/en/Gtk/AboutDialogActivateLinkFunc.xml index 6aad5090f..b0bc8b81f 100644 --- a/doc/en/Gtk/AboutDialogActivateLinkFunc.xml +++ b/doc/en/Gtk/AboutDialogActivateLinkFunc.xml @@ -8,9 +8,19 @@ Gtk# is thread aware, but not thread safe; See the Gtk# Thread Programming for details. The in which the link was activated. - The URL or email address to which the activated link points.. - The type of the method which is called when a URL or email link in an about dialog. - + A containing the URL or email address to which the activated link points. + The type of the method which is called when a URL or email link in an . + + + The following example uses the built in to open links: + void OpenLink (Gtk.AboutDialog dialog, string link) + { + Gnome.Url.Show(link); + } + + Gtk.AboutDialog.SetUrlHook (new Gtk.AboutDialogActivateLinkFunc (OpenLink)); + + @@ -24,4 +34,4 @@ - + \ No newline at end of file diff --git a/doc/en/Gtk/AccelActivateArgs.xml b/doc/en/Gtk/AccelActivateArgs.xml index b714cead6..93db2eb7a 100644 --- a/doc/en/Gtk/AccelActivateArgs.xml +++ b/doc/en/Gtk/AccelActivateArgs.xml @@ -7,7 +7,7 @@ Gtk# is thread aware, but not thread safe; See the Gtk# Thread Programming for details. - Event data. + This class extends with information about an activated accelerator. The event invokes delegates which pass event data via this class. @@ -24,8 +24,8 @@ - Public Constructor. - Create a new instance with this constructor if you need to invoke a delegate. + Constructs and initializes a new instance of with the default values. + When manually evoking an delegate, this constructor is used create the second argument. @@ -36,8 +36,8 @@ - The object on which the accelerator was activated - a + Gets the object on which the accelerator was activated. + A containing the object on which the accelerator was activated. @@ -50,9 +50,11 @@ - The accelerator keyval - a + Gets the key value that was used to activate the accelerator. + A containing the key value that was used to activate the accelerator. + This value represents a specific non-modifier key on the keyboard. + A key combination may include a standard key and modifier keys, for example Ctrl-S. Check for the modifiers that were applied. @@ -64,11 +66,10 @@ - The modifier combination of the accelerator - a - - + Gets the mouse and keyboard modifier combination that was used to activate the accelerator. + A bitwise combined containing the mouse and keyboard modifier combination that was used to activate the accelerator. + Modifiers can include Ctrl, Shift, Alt, Meta keys (Windows, Apple), and mouse buttons. These are items that by themselves my perform no task, but when combined, often with , represent an accelerator. For example, Ctrl-S, Ctrl-Alt-Del, Ctrl-Left Mouse Button, or Apple-Control-Reset. - + \ No newline at end of file diff --git a/doc/en/Gtk/AccelActivateHandler.xml b/doc/en/Gtk/AccelActivateHandler.xml index 05d70fbad..8accdf3d0 100644 --- a/doc/en/Gtk/AccelActivateHandler.xml +++ b/doc/en/Gtk/AccelActivateHandler.xml @@ -7,14 +7,10 @@ Gtk# is thread aware, but not thread safe; See the Gtk# Thread Programming for details. - Event sender. - Event arguments. - Event handler. - - The event utilizes this delegate: - Event data is passed via the parameter. - To attach a to an event, add the AccelActivateHandler instance to the event. The methods referenced by the AccelActivateHandler instance are invoked whenever the event is raised, until the AccelActivateHandler is removed from the event. - + A containing the object that sent the event. + A object containing information about the accelerator that was activated, including the key value and modifiiers. + This type of method is used for handling events. + A delegate of this type can be attached to a to monitor the activation of events via , however this is typically unneccessary, as most accelerators are bound directly to a widget and signal. @@ -28,4 +24,4 @@ - + \ No newline at end of file diff --git a/doc/en/Gtk/FontButton.xml b/doc/en/Gtk/FontButton.xml index 5acd70fa2..58bf95351 100644 --- a/doc/en/Gtk/FontButton.xml +++ b/doc/en/Gtk/FontButton.xml @@ -7,8 +7,52 @@ Gtk# is thread aware, but not thread safe; See the Gtk# Thread Programming for details. - A button to launch a font selection dialog. + This class extends , providing an simple button for font selection. + When clicked, a shows a and when the dialog closes with a change, is evoked. + + In the following example, a is used to modify the font of a . + using System; +using Gtk; +using Pango; + +public class FontButtonExample +{ + static Label label; + static FontButton button; + + public static void Main () + { + Application.Init (); + + Window myWindow = new Window ("FontButton Example"); + myWindow.DeleteEvent += OnDelete; + + button = new FontButton (); + button.FontSet += OnFontSet; + + label = new Label ("Sample text"); + + VBox box = new VBox (); + box.Add (button); + box.Add (label); + + myWindow.Add (box); + myWindow.ShowAll (); + Application.Run (); + } + + static void OnFontSet (object o, EventArgs e) + { + label.ModifyFont (FontDescription.FromString (button.FontName)); + } + + static void OnDelete (object o, DeleteEventArgs e) + { + Application.Quit (); + } +} + @@ -38,8 +82,8 @@ - Protected Constructor. - a + Constructs and initializes a new instance of for a specified native GLib type. + A object containing the native GLib type for the new instance. Chain to this constructor if you have manually registered a native value for your subclass. @@ -56,9 +100,9 @@ - Internal constructor - a - This is not typically used by C# code. + Constructs and initializes a new instance of using an existing unmanaged object as its base. + A pointing to the raw object to be managed by the new instance. + This is not typically used by managed code. It is primarily used for enclosing an existing object, created by unmanaged code, in a managed wrapper. @@ -67,9 +111,8 @@ - Public constructor. - - + Constructs and initializes a new instance of with the default font. + To specify the default font on creation, use . @@ -80,10 +123,9 @@ - Public constructor with a font name. - a , name of font to display in font selection dialog. - - + Constructs and initializes a new instance of with a specified initial font. + A object containing the name of the initial font to use in the new instance. + The value of is in the same format as described in the remarks on . @@ -94,9 +136,9 @@ - GType Property. - a - Returns the native value for . + Gets the GLib type of the current instance. + A value representing the native GLib type of . + The value is used internally by the GLib type management system. @@ -107,10 +149,11 @@ - If this property is , the font size will be displayed along with the name of the selected font. - a - - + Gets and sets whether or not to show the font size in the button. + + A . If , the font size will be displayed in the button. + + Default Value: @@ -126,11 +169,11 @@ - - If this property is set to , the selected font size will be shown in the label. - - a - For a more WYSIWYG way to show the selected size, see the property. + Gets and sets whether or not button label should be displayed using the selected font size. + + A . If , the button label will be displayed using the selected font size. Otherwise in the default system font size. + + For a more WYSIWYG way to show the selected size, see the property. @@ -146,9 +189,11 @@ - Retrieves the name of the currently selected font. - a + Gets and sets the name of the currently selected font, including the style and size. + A object containing the name of the currently selected font, including the style and font. + The font name contains the name, style, and size. For example, "Bistream Vera Serif Bold Italic 24". If the style is not specified, "Regular" is assumed, and if the size is not specified, "0" is assumed. + Default Value: "Sans 12". This value is identical to the one that would be used by and . @@ -165,10 +210,11 @@ - Whether the label is drawn in the selected font. - a - - + Gets and sets whether or not button label should be displayed using the selected font. + + A . If , the button label will be displayed using the selected font. Otherwise in the default system font. + + Default Value: @@ -184,10 +230,9 @@ - The title of the font dialog. - a - - + Gets and sets the title used for the created by the currrent instance. + A object containing the title used for the created by the currrent instance. + Default Value: "Pick a Font" or a translated version. @@ -203,10 +248,11 @@ - Returns whether the name of the font style will be shown in the label. - a - - + Gets and sets whether or not the font style will be shown with the font name in the button. + + A . If , the font style will be displayed along with the name of the selected font, unless the style is "Regular". + + Default Value: @@ -222,9 +268,8 @@ - Event raised when the font is set. - - + This event is raised when the user closes the child after making a change. + Child classes should override instead of adding a handler to this event. @@ -242,13 +287,12 @@ - Sets or updates the currently-displayed font in font picker dialog. - a , name of font to display in font selection dialog - A string containing the font name if the - font selection dialog exists, otherwise . + Sets or updates the font displayed in the child . + A object containing the name of the font to display in the child . + The result of if the child dialog exists. Otherwise . - + \ No newline at end of file