Difference between revisions of "DesktopButton"

From Xojo Documentation

(Created page with "N/A")
 
 
(One intermediate revision by the same user not shown)
Line 1: Line 1:
N/A
+
{{ClassBox
 +
| super=[[DesktopUIControl]]
 +
| platform=all
 +
| scope=global
 +
| newinversion=2021r3
 +
}}
 +
{{Description
 +
| text=A Button is the standard button used in desktop apps. Examples are a Default button, a Cancel button or a standard button.
 +
}}
 +
 
 +
<dynamictable id="Events" super="DesktopUIControl" class="eventTable" title="Events" columns="3">
 +
{{Event | name=Pressed | description=Pressed()&#x0A;The button has been pressed. A right- or middle-click does not trigger this event. }}
 +
</dynamictable>
 +
 
 +
<dynamictable id="Properties" super="DesktopUIControl" class="propertyTable" title="Properties" columns="3">
 +
{{Property | name=Bold | type=Boolean | platform=all | description=( Boolean)&nbsp;&nbsp; Applies the bold style to the button caption. }}
 +
{{Property | name=Cancel | type=Boolean | platform=all | description=( Boolean)&nbsp;&nbsp;If True, the Escape key and Command-Period key sequence are mapped to the button }}
 +
{{Property | name=Caption | type=String | platform=all | description=( String)&nbsp;&nbsp;The button's text. }}
 +
{{Property | name=Default | type=Boolean | platform=all | description=( Boolean)&nbsp;&nbsp;If True, the default button indicator is added to the button and the Return and Enter keys are mapped to the button }}
 +
{{Property | name=FontName | type=String | platform=all | description=( String)&nbsp;&nbsp;Name of the font used to display the button caption.  }}
 +
{{Property | name=FontSize | type=Single | platform=all | description=( Single)&nbsp;&nbsp;Size of the font used to display the button caption }}
 +
{{Property | name=FontUnit | description=( FontUnits)&nbsp;&nbsp;The units to use for the text size of the font used to display the button caption }}
 +
{{Property | name=Italic | type=Boolean | platform=all | description=( Boolean)&nbsp;&nbsp;Applies the italic style to the button caption. }}
 +
{{Property | name=MacButtonStyle | type=DesktopButton.MacButtonStyles | platform=all | description=(MacButtonStyles)&nbsp;&nbsp; Applies one of 10 styles to the button. }}
 +
{{Property | name=Underline | type=Boolean | platform=all | description=( Boolean)&nbsp;&nbsp;Applies the underline style to the button caption. }}
 +
</dynamictable>
 +
 
 +
<dynamictable id="Methods" super="DesktopUIControl" class="methodTable" interface="ActionSource" title="Methods" columns="3">
 +
{{Method | name=Press | description=Press()&#x0A;Causes the button to be visually pressed, as well as triggering the Pressed event.  }}
 +
</dynamictable>
 +
 
 +
<dynamicTable id="Enumerations" class="methodTable" title="Enumerations" columns="3">
 +
{{Enum | name=MacButtonStyles | description=Specifies the various styles that can be used with the MacButtonStyle property which is only supported for macOS.}}
 +
</dynamicTable>
 +
 
 +
==Notes==
 +
To set an accelerator character, precede the character in the Caption with an ampersand.  In order to show an ampersand in the Caption, use two ampersands in a row. The sets the accelerator to the "D" character:
 +
<rbcode>Calculate &Data</rbcode>
 +
 
 +
The '''DesktopButton's''' Caption property can show a caption that uses an encoding that doesn't match the application&rsquo;s region code (or while running within the IDE, the IDE's region code). For example, an English application can set a Japanese caption, as long as it first sets the button's FontName to Osaka.
 +
 
 +
If your button has a height greater than 22 pixels, on macOS it will not have the standard rounded appearance and will instead be drawn as a square button. This is a restriction of macOS.
 +
 
 +
=== Linux and Pi Button Height ===
 +
On Linux and Pi you may find that the button height is not large enough to fit the text. This is because some themes will drastically increase the default font size for buttons causing it to exceed the size of the button. There are a couple things you can do to fix this. In the Opening event of the Button you can choose to make the button larger:
 +
 
 +
<rbcode>Me.Height = 32</rbcode>
 +
 
 +
Or you can choose to make its font smaller:
 +
 
 +
<rbcode>Me.FontSize = 10</rbcode>
 +
 
 +
The above numbers are for example. You will want to adjust them as appropriate for the theme being used.
 +
 
 +
You can also look up the best size to use based on the theme by using Declares. Refer to this example project to see how it is done:
 +
 
 +
Examples/Platform-Specific/Linux/GetDefaultControlSize
 +
 
 +
==See Also==
 +
[[DesktopBevelButton]], [[DesktopSegmentedButton]] controls; [[DesktopUIControl]] class.
 +
 
 +
[[Category:Desktop]]
 +
[[Category:Desktop Controls]]

Latest revision as of 19:59, 2 August 2021

Class (inherits from DesktopUIControl)


New in 2021r3

A Button is the standard button used in desktop apps. Examples are a Default button, a Cancel button or a standard button.

Events
Closing FocusLost MouseExit
ConstructContextualMenu FocusReceived MouseMove
ContextualMenuItemSelected KeyDown MouseUp
DragEnter KeyUp MouseWheel
DragExit MouseDown Opening
DragOver MouseDrag Pressed
DropObject MouseEnter
Properties
Active fa-lock-32.png Height Parent
AllowAutoDeactivate Index fa-lock-32.png Scope fa-lock-32.png
AllowTabStop Italic TabIndex
Bold Left Tooltip
Cancel LockBottom Top
Caption LockLeft Transparent
Default LockRight Underline
Enabled LockTop Visible
FontName MacButtonStyle Width
FontSize MouseCursor Window fa-lock-32.png
FontUnit Name fa-lock-32.png
Handle fa-lock-32.png PanelIndex
Methods
AcceptFileDrop AddActionNotificationReceiver Refresh
AcceptPictureDrop Close RemoveActionNotificationReceiver
AcceptRawDataDrop DrawInto SetFocus
AcceptTextDrop Press
Enumerations
MacButtonStyles

Notes

To set an accelerator character, precede the character in the Caption with an ampersand. In order to show an ampersand in the Caption, use two ampersands in a row. The sets the accelerator to the "D" character:

Calculate &Data

The DesktopButton's Caption property can show a caption that uses an encoding that doesn't match the application’s region code (or while running within the IDE, the IDE's region code). For example, an English application can set a Japanese caption, as long as it first sets the button's FontName to Osaka.

If your button has a height greater than 22 pixels, on macOS it will not have the standard rounded appearance and will instead be drawn as a square button. This is a restriction of macOS.

Linux and Pi Button Height

On Linux and Pi you may find that the button height is not large enough to fit the text. This is because some themes will drastically increase the default font size for buttons causing it to exceed the size of the button. There are a couple things you can do to fix this. In the Opening event of the Button you can choose to make the button larger:

Me.Height = 32

Or you can choose to make its font smaller:

Me.FontSize = 10

The above numbers are for example. You will want to adjust them as appropriate for the theme being used.

You can also look up the best size to use based on the theme by using Declares. Refer to this example project to see how it is done:

Examples/Platform-Specific/Linux/GetDefaultControlSize

See Also

DesktopBevelButton, DesktopSegmentedButton controls; DesktopUIControl class.