Skip to content

Commit

Permalink
Merge pull request #2423 from Miepee/button-doc
Browse files Browse the repository at this point in the history 
Update Buttons documentation.
  • Loading branch information
@cwensley
cwensley authored Feb 21, 2023
2 parents 4ec1f02 + cf65f06 commit 7e2ccd8
Showing 1 changed file with 63 additions and 70 deletions.
133 changes: 63 additions & 70 deletions src/Eto/Forms/Controls/Button.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,43 +5,48 @@
namespace Eto.Forms
{
/// <summary>
/// Button image position
/// Possible values for how images can be positioned in <see cref="Button"/>s.
/// </summary>
/// <copyright>(c) 2012-2014 by Curtis Wensley</copyright>
/// <license type="BSD-3">See LICENSE for full terms</license>
public enum ButtonImagePosition
{
/// <summary>
/// Positions the image to the left of the text
/// Positions the image to the left of the text.
/// </summary>
Left,

/// <summary>
/// Positions the image to the right of the text
/// Positions the image to the right of the text.
/// </summary>
Right,

/// <summary>
/// Positions the image on top of the text
/// Positions the image above of the text.
/// </summary>
Above,

/// <summary>
/// Positions the image below the text
/// Positions the image below the text.
/// </summary>
Below,

/// <summary>
/// Positions the image behind the text
/// Positions the image behind the text.
/// </summary>
Overlay
}

/// <summary>
/// Button control
/// A standard button control.
/// </summary>
/// <copyright>(c) 2012-2014 by Curtis Wensley</copyright>
/// <license type="BSD-3">See LICENSE for full terms</license>
/// <example>
/// <code>
/// var myButton = new Button
/// {
/// Text = "This is my button!"
/// };
/// myButton.Clicked += (sender, e) => { Console.WriteLine("My button was clicked."); };
/// </code>
/// </example>
[Handler(typeof(Button.IHandler))]
public class Button : TextControl
{
Expand All @@ -50,7 +55,7 @@ public class Button : TextControl
static readonly object Click_Key = new object();

/// <summary>
/// Event to handle when the user clicks the button
/// Event to handle when the user clicks the button.
/// </summary>
public event EventHandler<EventArgs> Click
{
Expand All @@ -59,9 +64,9 @@ public event EventHandler<EventArgs> Click
}

/// <summary>
/// Raises the <see cref="Click"/> event
/// Raises the <see cref="Click"/> event.
/// </summary>
/// <param name="e">Event arguments</param>
/// <param name="e">Event arguments.</param>
protected virtual void OnClick(EventArgs e)
{
Properties.TriggerEvent(Click_Key, this, e);
Expand All @@ -74,7 +79,7 @@ protected virtual void OnClick(EventArgs e)
/// </summary>
/// <remarks>
/// This will invoke the specified command when the button is pressed.
/// The <see cref="ICommand.CanExecute"/> will also used to set the enabled/disabled state of the button.
/// The <see cref="ICommand.CanExecute"/> will also be used to set the <see cref="Control.Enabled"/> state of the button.
/// </remarks>
/// <value>The command to invoke.</value>
public ICommand Command
Expand All @@ -86,7 +91,7 @@ public ICommand Command
static readonly object CommandParameter_Key = new object();

/// <summary>
/// Gets or sets the parameter to pass to the <see cref="Command"/> when executing or determining its CanExecute state.
/// Gets or sets the parameter to pass to the <see cref="Command"/> when executing or determining its <see cref="ICommand.CanExecute"/> state.
/// </summary>
/// <value>The command parameter.</value>
public object CommandParameter
Expand All @@ -96,19 +101,19 @@ public object CommandParameter
}

/// <summary>
/// Gets or sets the image to display on the button
/// Gets or sets the image to display on the button.
/// </summary>
/// <value>The image to display</value>
/// <value>The image to display.</value>
public Image Image
{
get { return Handler.Image; }
set { Handler.Image = value; }
}

/// <summary>
/// Gets or sets the position of the image relative to the text
/// Gets or sets the position of the image relative to the text.
/// </summary>
/// <value>The image position</value>
/// <value>The image position on the <see cref="Button"/>.</value>
public ButtonImagePosition ImagePosition
{
get { return Handler.ImagePosition; }
Expand All @@ -120,7 +125,7 @@ public ButtonImagePosition ImagePosition
/// </summary>
/// <remarks>
/// Each platform may have a different initial minimum size set for buttons to match their standard sizes.
///
/// <br/>
/// Setting this to <see cref="Eto.Drawing.Size.Empty"/> is useful when you want the button to shrink to fit the size
/// of the specified <see cref="Image"/> and/or <see cref="TextControl.Text"/>.
/// </remarks>
Expand All @@ -141,23 +146,20 @@ public override Size Size
{
base.Size = value;
// Ensure minimum size is at least as small as the desired explicit size
if (value.Width != -1 || value.Height != -1)
{
var min = MinimumSize;
var size = Size.Min(value, min);
if (size.Width == -1)
size.Width = min.Width;
if (size.Height == -1)
size.Height = min.Height;
if (size != min)
MinimumSize = size;
}
if (value.Width == -1 && value.Height == -1) return;

var min = MinimumSize;
var size = Size.Min(value, min);
if (size.Width == -1)
size.Width = min.Width;
if (size.Height == -1)
size.Height = min.Height;
if (size != min)
MinimumSize = size;
}
}

/// <summary>
/// Gets or sets the width of the control size.
/// </summary>
/// <inheritdoc/>
public override int Width
{
get => base.Width;
Expand All @@ -171,9 +173,7 @@ public override int Width
}
}

/// <summary>
/// Gets or sets the height of the control size.
/// </summary>
/// <inheritdoc/>
public override int Height
{
get => base.Height;
Expand All @@ -198,9 +198,21 @@ public Button()
/// Initializes a new instance of the <see cref="Eto.Forms.Button"/> class with the specified <paramref name="click"/> handler.
/// </summary>
/// <remarks>
/// This is a convenience constructor to set up the click event.
/// This is a convenience constructor to set up the <see cref="Click"/> event.
/// </remarks>
/// <param name="click">Delegate to handle when the button is clicked.</param>
/// <param name="click">Delegate to invoke when the button is clicked.</param>
/// <example>
/// The following two snippets are identical.
/// Without convenience constructor:
/// <code>
/// var myButton = new Button() { Text = "This is my button!" };
/// myButton.Clicked += (sender, e) => { Console.WriteLine("My button was clicked."); };
/// </code>
/// With convenience constructor:
/// <code>
/// var myButton = new Button((sender, e) => Console.WriteLine("My button was clicked.") { Text = "This is my button!" };
/// </code>
/// </example>
public Button(EventHandler<EventArgs> click)
{
Click += click;
Expand All @@ -216,31 +228,28 @@ public virtual void PerformClick()
}

static readonly object callback = new Callback();
/// <summary>
/// Gets an instance of an object used to perform callbacks to the widget from handler implementations
/// </summary>
/// <returns>The callback instance to use for this widget</returns>

/// <inheritdoc/>
protected override object GetCallback() { return callback; }

/// <summary>
/// Callback interface for <see cref="Button"/>
/// Callback interface for <see cref="Button"/>.
/// </summary>
public new interface ICallback : TextControl.ICallback
{
/// <summary>
/// Raises the click event.
/// Raises the <see cref="Button.Click"/> event.
/// </summary>
// TODO: parameters are undocumented.
void OnClick(Button widget, EventArgs e);
}

/// <summary>
/// Callback implementation for handlers of <see cref="Button"/>
/// Callback implementation for handlers of <see cref="Button"/>.
/// </summary>
protected new class Callback : TextControl.Callback, ICallback
{
/// <summary>
/// Raises the click event.
/// </summary>
/// <inheritdoc cref="ICallback.OnClick"/>.
public void OnClick(Button widget, EventArgs e)
{
using (widget.Platform.Context)
Expand All @@ -249,33 +258,17 @@ public void OnClick(Button widget, EventArgs e)
}

/// <summary>
/// Handler interface for the <see cref="Button"/> control
/// Handler interface for the <see cref="Button"/> control.
/// </summary>
/// <copyright>(c) 2012-2014 by Curtis Wensley</copyright>
/// <license type="BSD-3">See LICENSE for full terms</license>
public new interface IHandler : TextControl.IHandler
{
/// <summary>
/// Gets or sets the image to display on the button
/// </summary>
/// <value>The image to display</value>
/// <inheritdoc cref="Button.Image"/>
Image Image { get; set; }

/// <summary>
/// Gets or sets the image position
/// </summary>
/// <value>The image position</value>
/// <inheritdoc cref="Button.ImagePosition"/>
ButtonImagePosition ImagePosition { get; set; }

/// <summary>
/// Gets or sets the minimum size for the button.
/// </summary>
/// <remarks>
/// Each platform may have a different initial minimum size set for buttons to match their standard sizes.
///
/// Setting this to <see cref="Eto.Drawing.Size.Empty"/> is useful when you want the button to shrink to fit the size
/// of the specified <see cref="Image"/> and/or <see cref="TextControl.Text"/>.
/// </remarks>
/// <inheritdoc cref="Button.MinimumSize"/>
Size MinimumSize { get; set;}
}
}
Expand Down

0 comments on commit 7e2ccd8

Please sign in to comment.