Skip to content

Commit

Permalink
Merge pull request #2432 from Miepee/dropdown-doc
Browse files Browse the repository at this point in the history 
Revise documentation for DropDown
  • Loading branch information
@cwensley
cwensley authored Mar 5, 2023
2 parents d210b50 + 087a7af commit 61a0ed3
Showing 1 changed file with 39 additions and 53 deletions.
92 changes: 39 additions & 53 deletions src/Eto/Forms/Controls/DropDown.cs
View file
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,71 +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);

/// <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 @@ -245,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; }
}
}

0 comments on commit 61a0ed3

Please sign in to comment.