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

Revise documentation for DropDown #2432

Merged
merged 1 commit into from
Mar 5, 2023
Merged

Revise documentation for DropDown #2432

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
97 changes: 40 additions & 57 deletions src/Eto/Forms/Controls/DropDown.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,14 +5,14 @@
namespace Eto.Forms;

/// <summary>
/// Arguments for formatting items in a DropDown using the <see cref="DropDown.FormatItem"/> event.
/// Arguments for formatting items in a drop down using the <see cref="DropDown.FormatItem"/> event.
/// </summary>
public class DropDownFormatEventArgs : EventArgs
{
Font _font;

/// <summary>
/// Gets or sets the font to use for this item
/// Gets or sets the font to use for this item.
/// </summary>
public virtual Font Font
{
Expand All @@ -33,21 +33,21 @@ public virtual Font Font
public bool IsFontSet { get; private set; }

/// <summary>
/// Item to specify the format for
/// Item to specify the format for.
/// </summary>
public object Item { get; }

/// <summary>
/// Row number in the list of items to format for
/// Row number in the list of items to format for.
/// </summary>
public int Row { get; }

/// <summary>
/// Initializes a new instance of the DropDownFormatEventArgs class
/// Initializes a new instance of the DropDownFormatEventArgs class.
/// </summary>
/// <param name="item">Item to format</param>
/// <param name="row">Row of the item to format</param>
/// <param name="font">Font to use if no other is specified</param>
/// <param name="item">Item to format.</param>
/// <param name="row">Row of the item to format.</param>
/// <param name="font">Font to use if no other is specified.</param>
public DropDownFormatEventArgs(object item, int row, Font font)
{
Item = item;
Expand All @@ -57,8 +57,15 @@ public DropDownFormatEventArgs(object item, int row, Font font)
}

/// <summary>
/// Presents a drop down to select from a list of items
/// Presents a drop down to select from a list of items.
/// </summary>
/// <example>
/// Here is a short example on how to create a drop down with its items being based off a list:
/// <code>
/// var list = new List&lt;string&gt;() { "First item", "Second item", "Third item" };
/// var dropdown = new DropDown() { DataStore = list };
/// </code>
/// </example>
[Handler(typeof(DropDown.IHandler))]
public class DropDown : ListControl
{
Expand All @@ -83,7 +90,7 @@ public DropDown()
/// Gets or sets the binding to get the image for each item.
/// </summary>
/// <remarks>
/// By default this looks for the "Image" property of the item, and also works if you use <see cref="ImageListItem"/>.
/// By default this looks for the <code>Image</code> property of the item, and also works if you use <see cref="ImageListItem"/>.
///
/// This will be ignored when creating a <see cref="ComboBox"/>, and is only supported with the <see cref="DropDown"/> directly.
/// </remarks>
Expand All @@ -95,10 +102,9 @@ public DropDown()
/// </summary>
/// <remarks>
/// This is a hint to omit the border of the control and show it as plainly as possible.
///
/// Typically used when you want to show the control within a cell of the <see cref="GridView"/>.
/// </remarks>
/// <value><c>true</c> to show the control border; otherwise, <c>false</c>.</value>
/// <value><see langword="true"/> to show the control border; otherwise, <see langword="false"/>.</value>
[DefaultValue(true)]
public bool ShowBorder
{
Expand All @@ -107,7 +113,7 @@ public bool ShowBorder
}

/// <summary>
/// Event identifier for handlers when attaching the <see cref="DropDownOpening"/> event
/// Event identifier for handlers when attaching the <see cref="DropDownOpening"/> event.
/// </summary>
public const string DropDownOpeningEvent = "DropDown.DropDownOpening";

Expand All @@ -126,7 +132,7 @@ public event EventHandler<EventArgs> DropDownOpening
/// <summary>
/// Raises the <see cref="DropDownOpening"/> event.
/// </summary>
/// <param name="e">Event arguments</param>
/// <param name="e">Event arguments.</param>
protected virtual void OnDropDownOpening(EventArgs e)
{
Properties.TriggerEvent(DropDownOpeningEvent, this, e);
Expand All @@ -147,9 +153,9 @@ public event EventHandler<EventArgs> DropDownClosed
}

/// <summary>
/// Raises the <see cref="DropDownClosed"/> event
/// Raises the <see cref="DropDownClosed"/> event.
/// </summary>
/// <param name="e">Event arguments</param>
/// <param name="e">Event arguments.</param>
protected virtual void OnDropDownClosed(EventArgs e)
{
Properties.TriggerEvent(DropDownClosedEvent, this, e);
Expand All @@ -172,74 +178,59 @@ public event EventHandler<DropDownFormatEventArgs> FormatItem
/// <summary>
/// Raises the <see cref="FormatItem"/> event.
/// </summary>
/// <param name="e">Event Arguments</param>
/// <param name="e">Event Arguments.</param>
protected virtual void OnFormatItem(DropDownFormatEventArgs e) => Properties.TriggerEvent(FormatItemEvent, this, e);

/// <summary>
/// Gets the callback.
/// </summary>
/// <returns>The callback.</returns>
/// <inheritdoc/>
protected override object GetCallback() => new Callback();

/// <summary>
/// Callback interface for the DropDown
/// Callback interface for the <see cref="DropDown"/> control.
/// </summary>
public new interface ICallback : ListControl.ICallback
{
/// <summary>
/// Raises the <see cref="DropDownOpening"/> event.
/// <inheritdoc cref="DropDown.OnDropDownOpening"/>
/// </summary>
/// <param name="widget">Widget to raise the event</param>
/// <param name="e">Event arguments</param>
/// <param name="widget">Widget to raise the event.</param>
/// <param name="e">Event arguments.</param>
void OnDropDownOpening(DropDown widget, EventArgs e);

/// <summary>
/// Raises the <see cref="DropDownClosed"/> event
/// <inheritdoc cref="DropDown.OnDropDownClosed"/>
/// </summary>
/// <param name="widget">Widget to raise the event</param>
/// <param name="e">Event arguments</param>
/// <param name="widget">Widget to raise the event.</param>
/// <param name="e">Event arguments.</param>
void OnDropDownClosed(DropDown widget, EventArgs e);

/// <summary>
/// Raises the <see cref="FormatItem"/> event.
/// <inheritdoc cref="DropDown.FormatItem"/>
/// </summary>
/// <param name="widget">Widget to raise the event</param>
/// <param name="e">Event Arguments</param>
/// <param name="widget">Widget to raise the event.</param>
/// <param name="e">Event Arguments.</param>
void OnFormatItem(DropDown widget, DropDownFormatEventArgs e);
}

/// <summary>
/// Callback implementation for the DropDown
/// Callback implementation for the <see cref="DropDown"/> control.
/// </summary>
protected new class Callback : ListControl.Callback, ICallback
{
/// <summary>
/// Raises the <see cref="DropDownOpening"/> event.
/// </summary>
/// <param name="widget">Widget to raise the event</param>
/// <param name="e">Event arguments</param>
/// <inheritdoc cref="ICallback.OnDropDownOpening"/>
public void OnDropDownOpening(DropDown widget, EventArgs e)
{
using (widget.Platform.Context)
widget.OnDropDownOpening(e);
}

/// <summary>
/// Raises the <see cref="DropDownClosed"/> event
/// </summary>
/// <param name="widget">Widget to raise the event</param>
/// <param name="e">Event arguments</param>
/// <inheritdoc cref="ICallback.OnDropDownClosed"/>
public void OnDropDownClosed(DropDown widget, EventArgs e)
{
using (widget.Platform.Context)
widget.OnDropDownClosed(e);
}

/// <summary>
/// Raises the <see cref="FormatItem"/> event.
/// </summary>
/// <param name="widget">Widget to raise the event</param>
/// <param name="e">Event Arguments</param>
/// /// <inheritdoc cref="ICallback.OnFormatItem"/>
public void OnFormatItem(DropDown widget, DropDownFormatEventArgs e)
{
using (widget.Platform.Context)
Expand All @@ -248,19 +239,11 @@ public void OnFormatItem(DropDown widget, DropDownFormatEventArgs e)
}

/// <summary>
/// Handler interface for the <see cref="DropDown"/>
/// Handler interface for the <see cref="DropDown"/> control.
/// </summary>
public new interface IHandler : ListControl.IHandler
{
/// <summary>
/// Gets or sets a value indicating whether to show the control's border.
/// </summary>
/// <remarks>
/// This is a hint to omit the border of the control and show it as plainly as possible.
///
/// Typically used when you want to show the control within a cell of the <see cref="GridView"/>.
/// </remarks>
/// <value><c>true</c> to show the control border; otherwise, <c>false</c>.</value>
/// <inheritdoc cref="DropDown.ShowBorder"/>
bool ShowBorder { get; set; }
}
}