WinForms

Upgrade Guide User Guide Demos Support Forums Download
  • Upgrade Guide
  • User Guide
  • Demos
  • Support
  • Forums
  • Download
Class SfButton - WindowsForms API Reference | Syncfusion

    Show / Hide Table of Contents

    Class SfButton

    Represents a button control with advanced customization options on background, text, border and image, etc.

    Inheritance
    System.Object
    SfButton
    SortButton
    Implements
    System.Windows.Forms.IMessageFilter
    ISupportUpdate
    IThemeProvider
    IVisualStyle
    Namespace: Syncfusion.WinForms.Controls
    Assembly: Syncfusion.Core.WinForms.dll
    Syntax
    public class SfButton : Button, IMessageFilter, ISupportUpdate, IThemeProvider, IVisualStyle
    Examples

    This example shows how to initialize the SfButton control.

           
    //Initializing new instance of the SfButton.
    SfButton sfButton1 = new SfButton();
    //Initialize the location for the SfButton.
    sfButton1.Location = new System.Drawing.Point(348, 71);
    //Initialize the name of the SfButton.
    sfButton1.Name = "sfButton1";
    //Initialize the size of the SfButton.
    sfButton1.Size = new System.Drawing.Size(94, 30);
    //Initialize the text value of the SfButton.
    sfButton1.Text = "sfButton1";

    Constructors

    SfButton()

    Initializes a new instance of the SfButton class.

    Declaration
    public SfButton()
    Remarks

    The constructor initializes the created button with default settings.

    Properties

    AccessibilityEnabled

    Gets or sets a value indicating whether the accessibility is enabled for the control or not.

    Declaration
    public bool AccessibilityEnabled { get; set; }
    Property Value
    Type Description
    System.Boolean

    AllowImageAnimation

    Gets or sets a value indicating whether the image has been animate in the button.

    Declaration
    public bool AllowImageAnimation { get; set; }
    Property Value
    Type Description
    System.Boolean

    If true, the button allows to animate the image, otherwise it does not allow the button animate the image. The default value is
    true
    .

    Remarks

    The SfButton allows to animate when set the animated GIF file to Image property.
    Other images like HoverImage, PressedImage, FocusedImage and DisabledImage images are not allow to animate.

    AllowRichText

    Gets or sets a value indicating whether the rich text has been displayed on the button.

    Declaration
    public bool AllowRichText { get; set; }
    Property Value
    Type Description
    System.Boolean

    True, if the current button caption can show the rich text, otherwise false. The default value is false.

    Remarks

    The button will display the rich text only when set the Text value as rich text.

    Examples
    //Initialize the AllowRichText property to true.
    sfButton1.AllowRichText = true;
    //Initialize the rich text value to button
    sfButton1.Text = "{\\rtf1\\ansi \\i This is boldText \\b Draw in the button}";

    AllowWrapText

    Gets or sets a value indicating whether the text has been wrapped on the button control.

    Declaration
    public bool AllowWrapText { get; set; }
    Property Value
    Type Description
    System.Boolean

    True if the text should wrap to the available layout rectangle otherwise, false. Default value is false.

    Remarks

    The text will be wrapped only when the AutoSize is false.

    AutoEllipsis

    Gets or sets a value indicating whether the ellipsis character (...) appears at the right edge of the control, denoting that the control text extends beyond the specified length of the control.

    Declaration
    public bool AutoEllipsis { get; set; }
    Property Value
    Type Description
    System.Boolean

    True if the additional label text is to be indicated by an ellipsis; otherwise, false. The default is true.

    AutoSize

    Gets or sets a value that indicates whether the button resizes based on its contents. The default value is false.

    Declaration
    public override bool AutoSize { get; set; }
    Property Value
    Type Description
    System.Boolean

    true if the control automatically resizes based on its contents; otherwise, false. The default is true.

    BackColor

    Gets or sets the background color of the button control.

    Declaration
    public override Color BackColor { get; set; }
    Property Value
    Type Description
    System.Drawing.Color
    Remarks

    This color has filled to background of the button only when set the property to GradientStyle.None or GradientBrush property to null.

    BaseThemeName

    Gets or sets the BaseThemeName of the control.

    Declaration
    protected string BaseThemeName { get; set; }
    Property Value
    Type Description
    System.String

    CanApplyTheme

    Gets or sets a value indicating whether a SfSkinManager theme style has been applied to the control.

    Declaration
    public bool CanApplyTheme { get; set; }
    Property Value
    Type Description
    System.Boolean

    The default value is true.

    CanOverrideStyle

    Gets or sets a value indicating whether control elements styles can be overridden by theme style settings.

    Declaration
    public bool CanOverrideStyle { get; set; }
    Property Value
    Type Description
    System.Boolean

    Default value is false.

    Remarks

    By default, the control's element styles will not be overridden by theme style settings if the style is set in sample level. If this property is enabled, element style will be overridden by theme style settings event if it is set in sample level. This property should be enabled or disabled before calling the ThemeName property of the control.

    ControlName

    Gets the name of the control.

    Declaration
    public string ControlName { get; }
    Property Value
    Type Description
    System.String

    DefaultSize

    Returns the default size of the control.

    Declaration
    protected override Size DefaultSize { get; }
    Property Value
    Type Description
    System.Drawing.Size

    Enabled

    Gets or sets a value indicating whether the control can respond to user interaction.

    Declaration
    public bool Enabled { get; set; }
    Property Value
    Type Description
    System.Boolean

    True if the control can respond to user interaction; otherwise, false. The default value is true.

    FlatAppearance

    Gets the appearance of the border and the colors used to indicate check state and mouse state.

    Declaration
    [Obsolete("FlatAppearance property is deprecated, please use Style property instead.")]
    public FlatButtonAppearance FlatAppearance { get; }
    Property Value
    Type Description
    System.Windows.Forms.FlatButtonAppearance

    FocusRectangleVisible

    Gets or sets a value indicating whether a dotted focus rectangle is displayed within the SfButton when it has focus. The default value is false.

    Declaration
    public bool FocusRectangleVisible { get; set; }
    Property Value
    Type Description
    System.Boolean

    The System.Boolean value that specifies whether the dotted focus rectangle is displayed within the SimpleButton when it has focus. The default value is true.

    Font

    Gets or sets the System.Drawing.Font value for the control.

    Declaration
    public override Font Font { get; set; }
    Property Value
    Type Description
    System.Drawing.Font

    ForeColor

    Gets or sets the foreground color of the button control.

    Declaration
    public override Color ForeColor { get; set; }
    Property Value
    Type Description
    System.Drawing.Color

    A System.Drawing.Color value representing the foreground color of the control.

    Image

    Gets or sets the image that is displayed on a button control. The default value is null.

    Declaration
    public Image Image { get; set; }
    Property Value
    Type Description
    System.Drawing.Image

    An System.Drawing.Image object representing the image to be displayed on the button. The default value is null.

    Remarks

    The SfButton allows to animate, when set the animated GIF file to Image property and enable the AllowImageAnimation property is true.

    The button's image can also be specified using the ImageList and ImageIndex properties. Assign an image collection to the button's ImageList property and then use the ImageIndex property to specify the index of the image to display.

    ImageLayout

    Gets or sets the image layout as defined in the System.Windows.Forms.ImageLayout enumeration used to draw the image within the button.

    Declaration
    public ImageLayout ImageLayout { get; set; }
    Property Value
    Type Description
    System.Windows.Forms.ImageLayout

    The default value is ImageLayout.None.

    ImageList

    Gets or sets the System.Windows.Forms.ImageList that contains the System.Drawing.Image displayed on a button control.

    Declaration
    public ImageList ImageList { get; set; }
    Property Value
    Type Description
    System.Windows.Forms.ImageList

    The default value is null.

    Remarks

    After assign an image source to the ImageList property, use the ImageIndex property to specify the image to be displayed within the button.

    ImageMargin

    Gets or sets the margin of the image on the button control.

    Declaration
    public Padding ImageMargin { get; set; }
    Property Value
    Type Description
    System.Windows.Forms.Padding
    Remarks

    A System.Windows.Forms.Padding representing the space between image and text or border of the control.

    ImageSize

    Gets or sets the size of the image that will be displayed on the control.

    Declaration
    public Size ImageSize { get; set; }
    Property Value
    Type Description
    System.Drawing.Size

    IsUpdating

    Gets a value indicating whether the BeginUpdate() has been called and the painting for a control is suspended.

    Declaration
    public bool IsUpdating { get; }
    Property Value
    Type Description
    System.Boolean

    True if the control is currently updating, otherwise false.

    IsVisualStyleEnabled

    Gets a value indicating whether the visual style based theme is applied to the control and also indicates whether the theme files are referred from external assemblies or not.

    Declaration
    public bool IsVisualStyleEnabled { get; }
    Property Value
    Type Description
    System.Boolean

    Return true, if the visual style based theme is applied to the control. Otherwise returns false.

    Padding

    Gets or sets the padding within the button control.

    Declaration
    public Padding Padding { get; set; }
    Property Value
    Type Description
    System.Windows.Forms.Padding

    A System.Windows.Forms.Padding representing the control's internal spacing characteristics.

    Style

    Gets or sets the ButtonVisualStyle value used to customize the appearance of the button.

    Declaration
    public ButtonVisualStyle Style { get; set; }
    Property Value
    Type Description
    ButtonVisualStyle

    Text

    Gets or sets the text to be displayed on the button.

    Declaration
    public override string Text { get; set; }
    Property Value
    Type Description
    System.String

    A string value representing the button's caption.

    Remarks

    Changing this property's value at runtime raises the TextChanged event. If the AllowRichText property is set to true, can use the rich text value to show the button caption.

    TextImageRelation

    Gets or sets the position of text and image relative to each other.

    Declaration
    public TextImageRelation TextImageRelation { get; set; }
    Property Value
    Type Description
    System.Windows.Forms.TextImageRelation

    The System.Windows.Forms.TextImageRelation enumeration that specifies how the button's image is aligned relative to the button's text. The default value is TextImageRelation.ImageBeforeText

    TextMargin

    Gets or sets the margin of the text on the button control.

    Declaration
    public Padding TextMargin { get; set; }
    Property Value
    Type Description
    System.Windows.Forms.Padding
    Remarks

    A System.Windows.Forms.Padding representing the space between text and image or border of the control.

    ThemeName

    Gets or sets the theme name of the button control.

    Declaration
    public string ThemeName { get; set; }
    Property Value
    Type Description
    System.String

    The default value is null.

    Remarks

    The theme will be applied only when the particular theme for this control has included the Themes assembly.

    UseCompatibleTextRendering

    Gets a value indicating whether to use the System.Drawing.Graphics class (GDI+) to rendering text. The SfButton control does not provide support the GDI drawing.

    Declaration
    public bool UseCompatibleTextRendering { get; }
    Property Value
    Type Description
    System.Boolean

    VisualTheme

    Gets or sets the visualTheme of the control, which holds the ThemeName applied from SkinManager

    Declaration
    protected string VisualTheme { get; set; }
    Property Value
    Type Description
    System.String

    Methods

    BeginUpdate()

    Suspends the painting of the control until the EndUpdate() method is called.

    Declaration
    public void BeginUpdate()
    Examples
    //Suspend updating the button.
    sfButton1.BeginUpdate();
    //Initialize styles changes to the button.
    sfButton1.Style.BackColor = Color.Gray;
    sfButton1.Style.ForeColor = Color.Black;
    //Resume updating the button and update the above changes.
    sfButton1.EndUpdate();

    CreateAccessibilityInstance()

    Overridden to update the accessibility object for the SfButton.

    Declaration
    protected override AccessibleObject CreateAccessibilityInstance()
    Returns
    Type Description
    System.Windows.Forms.AccessibleObject

    Returns the accessibility object for the SfButton.

    Dispose(Boolean)

    Cleans up any resources being used by the SfButton class.

    Declaration
    protected override void Dispose(bool disposing)
    Parameters
    Type Name Description
    System.Boolean disposing

    True to release both managed and unmanaged resources; false to release only unmanaged resources.

    EndUpdate()

    Resumes the painting of the control suspended by calling the BeginUpdate method.

    Declaration
    public void EndUpdate()
    Examples
    //Suspend updating the button.
    sfButton1.BeginUpdate();
    //Initialize styles changes to the button.
    sfButton1.Style.BackColor = Color.Gray;
    sfButton1.Style.ForeColor = Color.Black;
    //Resume updating the button and update the above changes.
    sfButton1.EndUpdate();

    GetActiveThemeName()

    Gets the active theme name of the button control.

    Declaration
    public string GetActiveThemeName()
    Returns
    Type Description
    System.String

    Returns the active theme name.

    OnKeyDown(KeyEventArgs)

    Raises the System.Windows.Forms.ButtonBase.OnKeyUp(System.Windows.Forms.KeyEventArgs) event.

    Declaration
    protected override void OnKeyDown(KeyEventArgs eventArgs)
    Parameters
    Type Name Description
    System.Windows.Forms.KeyEventArgs eventArgs

    A System.Windows.Forms.KeyEventArgs that contains the event data.

    OnKeyUp(KeyEventArgs)

    Raises the System.Windows.Forms.ButtonBase.OnKeyUp(System.Windows.Forms.KeyEventArgs) event.

    Declaration
    protected override void OnKeyUp(KeyEventArgs eventArgs)
    Parameters
    Type Name Description
    System.Windows.Forms.KeyEventArgs eventArgs

    A System.Windows.Forms.KeyEventArgs that contains the event data.

    OnMouseDown(MouseEventArgs)

    Raises the System.Windows.Forms.ButtonBase.OnMouseDown(System.Windows.Forms.MouseEventArgs) event.

    Declaration
    protected override void OnMouseDown(MouseEventArgs eventArgs)
    Parameters
    Type Name Description
    System.Windows.Forms.MouseEventArgs eventArgs

    An System.Windows.Form.MouseEventArgsthat contains the event data.

    OnMouseEnter(EventArgs)

    Raises the System.Windows.Forms.ButtonBase.OnMouseEnter(System.Windows.Forms.EventArgs) event.

    Declaration
    protected override void OnMouseEnter(EventArgs eventArgs)
    Parameters
    Type Name Description
    System.EventArgs eventArgs

    An System.Windows.Form.EventArgsthat contains the event data.

    OnMouseLeave(EventArgs)

    Raises the System.Windows.Forms.ButtonBase.OnMouseLeave(System.Windows.Forms.EventArgs) event.

    Declaration
    protected override void OnMouseLeave(EventArgs eventArgs)
    Parameters
    Type Name Description
    System.EventArgs eventArgs

    An System.Windows.Form.EventArgsthat contains the event data.

    OnMouseUp(MouseEventArgs)

    Raises the System.Windows.Forms.ButtonBase.OnMouseUp(System.Windows.Forms.MouseEventArgs) event.

    Declaration
    protected override void OnMouseUp(MouseEventArgs eventArgs)
    Parameters
    Type Name Description
    System.Windows.Forms.MouseEventArgs eventArgs

    An System.Windows.Form.MouseEventArgsthat contains the event data.

    OnPaint(PaintEventArgs)

    Override the method to draw the customized button. If the SfButton is not customized then raises the System.Windows.Forms.ButtonBase.OnPaint method.

    Declaration
    protected override void OnPaint(PaintEventArgs eventArgs)
    Parameters
    Type Name Description
    System.Windows.Forms.PaintEventArgs eventArgs

    A System.Windows.Forms.PaintEventArgs that contains the event data.

    Events

    ThemeChanged

    Occurs when theme name of the SfButton has changed.

    Declaration
    public event ThemeChangedEventHandler ThemeChanged
    Event Type
    Type Description
    ThemeChangedEventHandler

    ThemeNameChanged

    Occurs when theme name of the SfButton has changed.

    Declaration
    public event ThemeChangedEventHandler ThemeNameChanged
    Event Type
    Type Description
    ThemeChangedEventHandler

    Explicit Interface Implementations

    IVisualStyle.VisualTheme

    Gets or sets the VisualTheme of the SfListView control.

    Declaration
    string IVisualStyle.VisualTheme { get; set; }
    Returns
    Type Description
    System.String

    IThemeProvider.BaseThemeName

    Gets or sets the BaseThemeName of the theme

    Declaration
    string IThemeProvider.BaseThemeName { get; set; }
    Returns
    Type Description
    System.String

    Implements

    System.Windows.Forms.IMessageFilter
    ISupportUpdate
    IThemeProvider
    IVisualStyle
    Back to top Generated by DocFX
    Copyright © 2001 - 2022 Syncfusion Inc. All Rights Reserved