public abstract class CustomControl : PlugIn, System.ComponentModel.INotifyPropertyChanged
Public MustInherit Class CustomControl Inherits PlugIn Implements System.ComponentModel.INotifyPropertyChanged
public abstract class CustomControl : PlugIn, System.ComponentModel.INotifyPropertyChanged
Public MustInherit Class CustomControl Inherits PlugIn Implements System.ComponentModel.INotifyPropertyChanged
Even though DAML supports a rich set of pre-defined ribbon controls, occasionally it may be necessary to author a custom control. The CustomControl class is the base class for these rare occasions.
There are two types of custom controls. The first type is a custom UIElement hosted directly in the ribbon control much like an in-line gallery. The second is a Framework drop down button that presents the custom control in a popup control. The later is very similar to a drop down gallery except in this case the control author has complete control of the drop down.
For in-ribbon custom controls the control must be 22 pixels tall if the representation is small or middle, and 68 pixels if large.
All ribbon control elements share several attributes. The loadOnClick attribute determines when the control should be created by the framework. By default, controls appear enabled, but are not actually instantiated until they are clicked. This simple just-in-time (JIT) strategy improves resource utilization and startup time by deferring the instantiation of controls until they are initiated by the end user. Note that non-visible controls are never loaded until they become visible (or are executed programmatically), regardless of the value assigned to loadOnClick.
Tooltips are defined using the tooltip sub-element and may span as many lines as necessary. The image attribute is used to supply an image that will appear next to the tip text. Command tooltips also support a disabledText element, this string is additional displayed when the command is disabled.
Most controls support multiple sizes in the ribbon. For example, a button can render small (small icon only), medium (small icon with text), and large (large icon over text). Use the smallImage and largeImage attributes to specify unique images for the different sizes. Images don’t have to be graphics, you can also use XAML. You can also use overlayLargeImage and overlaySmallImage to draw a graphic or XAML overtop of the corresponding images. If the image should flip when running right-to-left, e.g. arrow buttons, set the flipImageRTL attribute to true.
The disableIfBusy element is used to signal that the control should be disabled whenever the primary worker thread is busy. This prevents work from queuing up. This element is true by default. Controls that always need to be enabled such as the close application button should set this to false.
All control declarations support a condition attribute allowing the assignment of a condition. If the specified condition isn’t met, the control will be automatically disabled by the framework. In addition, controls remain unloaded until their is met. If no condition is specified, the control is assumed to be always relevant.
Declaring Custom Controls in DAML: <customControl id="acme_customControl"
caption="My custom control"
extendedCaption="Extended caption"
className="CustomControls.CustomControlVM"
smallImage="pack://application:,,,/Acme;component/Images/AcmeImage16.png"
largeImage="pack://application:,,,/Acme;component/Images/AcmeImage32.png"
condition="acme"
isDropDown="false">
<content className="CustomControls.CustomControlView" />
<tooltip heading="My Heading" image="pack://application:,,,/Acme;component/Images/Acme16.png">My custom control's tooltip</tooltip>
</customControl>
| DAML attributes | |
|---|---|
| id | Required identifier. |
| caption | The heading. |
| extendedCaption | A more descriptive title. |
| isDropDown | Is the custom control directly in the ribbon or is it in a popup. Default is false. |
| staysOpenOnClick | Should the popup stay open when an inner element is clicked. Default is false. |
| smallImage | Image (16x16) used when button is small and middle size. |
| largeImage | Image (32x32) used when button is large size. |
| overlaySmallImage | Optional image overlay. |
| overlayLargeImage | Optional image overlay. |
| flipImageRTL | Option to flip the image when running right-to-left. Default is false. |
| keytip | The key that selects the button in keytip mode (Alt navigation). |
| loadOnClick | Delay creating the actual control until it has been clicked. Default is true. |
| categoryRefID | Adds control to a specific component category. |
| condition | Automatically disable the button if the condition is not satisfied. |
| disableIfBusy | Automatically disable the button if the application is busy. Default true. |
| helpContextID | The help topic to show. |
| className | Required class identifier. Optionally include namespace if not in default namespace. |
| assembly | Assembly name if not in the default assembly. |
| publicKeyToken | The necessary public key token if the assembly is strongly named. |
| version | The version of the dll if the assembly is strongly named. |
| DAML Child Elements | |
|---|---|
| tooltip | Description of the control. |
| content | Optional custom XML data when registered in a component category. |
System.Object
ArcGIS.Desktop.Framework.Contracts.PropertyChangedBase
ArcGIS.Desktop.Framework.Contracts.PlugIn
ArcGIS.Desktop.Framework.Contracts.CustomControl
Target Platforms: Windows 11, Windows 10