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
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
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
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
System.String

DefaultSize

Returns the default size of the control.

Declaration

protected override Size DefaultSize { get; }

Property Value

Type
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
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
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
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
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
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
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
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
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
ThemeChangedEventHandler

ThemeNameChanged

Occurs when theme name of the SfButton has changed.

Declaration

public event ThemeChangedEventHandler ThemeNameChanged

Event Type

Type
ThemeChangedEventHandler

Explicit Interface Implementations

IVisualStyle.VisualTheme

Gets or sets the VisualTheme of the SfListView control.

Declaration

string IVisualStyle.VisualTheme { get; set; }

Returns

Type
System.String

IThemeProvider.BaseThemeName

Gets or sets the BaseThemeName of the theme

Declaration

string IThemeProvider.BaseThemeName { get; set; }

Returns

Type
System.String

Implements

System.Windows.Forms.IMessageFilter

ISupportUpdate

IThemeProvider

IVisualStyle