Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update Buttons documentation. #2423

Merged
merged 1 commit into from
Feb 21, 2023
Merged

Update Buttons documentation. #2423

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
133 changes: 63 additions & 70 deletions src/Eto/Forms/Controls/Button.cs
View file
Open in desktop
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