HypernovaDesktop Components · docs
Binarymission
WPF › Ribbon › BinaryRibbonScreenTip

BinaryRibbonScreenTip

class.NET 6 / 8 / 10.NET Framework 4.8Binarymission.WPF.Controls.Office

A screen tip: the titled tool tip a ribbon shows for a command – its name in bold, a sentence on what it does, an optional picture, and a footer offering help.

public class BinaryRibbonScreenTip : ToolTip

Inherits from / implements: ToolTip

Remarks

Attach it with BinaryRibbonScreenTipService.SetScreenTip, which also gives it the timing and placement a ribbon command wants and shows it on a disabled command. It is an ordinary ToolTip, so it can also be assigned to any element's FrameworkElement.ToolTip.

Disabled commands

A disabled command can say why: DisabledDescription replaces Description while the element the tip belongs to is disabled – the moment a user most needs telling.

Help

F1 while the tip is on screen raises HelpRequestedEvent on the element the tip belongs to, carrying HelpTopic. The event bubbles, so one handler on the window or the ribbon can answer for every command.

Examples

<bm:BinaryRibbonButton Content="Send" LargeImage="Images/Send32.png" Click="OnSendInvoice"
                       IsEnabled="{Binding CanSend}">
    <bm:BinaryRibbonScreenTipService.ScreenTip>
        <bm:BinaryRibbonScreenTip Title="Send invoice"
                                  Description="Email this invoice to the customer as a PDF."
                                  DisabledDescription="Add the customer's email address to send the invoice."
                                  Image="Images/Send32.png"
                                  FooterText="Press F1 for more help."
                                  HelpTopic="invoices/sending" />
    </bm:BinaryRibbonScreenTipService.ScreenTip>
</bm:BinaryRibbonButton>

One handler in the window's constructor answers F1 on every screen tip in the window. HelpViewer stands for the application's own help.

BinaryRibbonScreenTip.AddHelpRequestedHandler(this, (sender, e) =>
{
    HelpViewer.Show(e.HelpTopic);
    e.Handled = true;
});

See also

Members at a glance

Properties
DescriptionGets or sets what the command does, in a sentence or two.
DisabledDescriptionGets or sets what to say in place of Description while the element the tip belongs to is disabled – usually why the command cannot be used.
FooterImageGets or sets the small picture shown in the footer, beside FooterText – usually a help icon.
FooterTextGets or sets the footer line, under a rule at the foot of the tip – usually the offer of further help, such as "Press F1 for more help."
HelpTopicGets or sets what the application's help should open when the user presses F1 on this tip.
ImageGets or sets the picture shown beside the description.
IsOwnerEnabledGets whether the element this tip belongs to was enabled when the tip opened.
MaximumContentWidthGets or sets how wide the tip's text may run before it wraps.
TitleGets or sets the command's name, shown in bold at the top of the tip.
Methods
AddHelpRequestedHandlerAdds a handler for the HelpRequested event (HelpRequestedEvent) to an element.
OnClosedStops listening for F1 when the tip closes.
OnOpenedRecords whether the tip's element is enabled, and starts listening for F1 on its window.
RemoveHelpRequestedHandlerRemoves a handler for the HelpRequested event (HelpRequestedEvent) from an element.
Fields
DescriptionPropertyIdentifies the Description dependency property.
DisabledDescriptionPropertyIdentifies the DisabledDescription dependency property.
FooterImagePropertyIdentifies the FooterImage dependency property.
FooterTextPropertyIdentifies the FooterText dependency property.
HelpRequestedEventIdentifies the HelpRequested attached event, raised when the user presses F1 while a screen tip is on screen.
HelpTopicPropertyIdentifies the HelpTopic dependency property.
ImagePropertyIdentifies the Image dependency property.
IsOwnerEnabledPropertyIdentifies the IsOwnerEnabled dependency property.
MaximumContentWidthPropertyIdentifies the MaximumContentWidth dependency property.
TitlePropertyIdentifies the Title dependency property.

Properties

Description

public string Description

Gets or sets what the command does, in a sentence or two.

Value
The default is null; a null or empty description hides the line. Long text wraps at MaximumContentWidth.

DisabledDescription

public string DisabledDescription

Gets or sets what to say in place of Description while the element the tip belongs to is disabled – usually why the command cannot be used.

Value
The default is null; while it is null or empty, Description shows whether the command is available or not.

FooterImage

public ImageSource FooterImage

Gets or sets the small picture shown in the footer, beside FooterText – usually a help icon.

Value
Drawn at 16 by 16 logical pixels. The default is null.

FooterText

public string FooterText

Gets or sets the footer line, under a rule at the foot of the tip – usually the offer of further help, such as "Press F1 for more help."

Value
The default is null. The footer and its rule are hidden while both this and FooterImage are null.

HelpTopic

public string HelpTopic

Gets or sets what the application's help should open when the user presses F1 on this tip.

Value
The topic, in whatever form the application's help understands – a page name, a URL, a context number as text. The default is null.
Remarks

The tip opens nothing itself: it raises HelpRequestedEvent carrying this value, and the application decides what it means.

Image

public ImageSource Image

Gets or sets the picture shown beside the description.

Value
Drawn at 32 by 32 logical pixels. The default is null, which hides the picture.

IsOwnerEnabled

public bool IsOwnerEnabled

Gets whether the element this tip belongs to was enabled when the tip opened.

Value
The default is true.
Remarks

Set each time the tip opens, so that the template can show DisabledDescription in place of Description; a tool tip is not in its element's visual tree, so a template trigger cannot reach the element's own UIElement.IsEnabled.

MaximumContentWidth

public double MaximumContentWidth

Gets or sets how wide the tip's text may run before it wraps.

Value
In logical pixels. The default is 300.

Title

public string Title

Gets or sets the command's name, shown in bold at the top of the tip.

Value
The default is null; a null or empty title hides the title line.

Methods

AddHelpRequestedHandler static

public static void AddHelpRequestedHandler( DependencyObject element, EventHandler<BinaryRibbonScreenTipHelpRequestedEventArgs> handler)

Adds a handler for the HelpRequested event (HelpRequestedEvent) to an element.

Parameters
element
The element – the window, the ribbon, a group or one command. Nothing happens unless it is a UIElement.
handler
The handler.
Example
BinaryRibbonScreenTip.AddHelpRequestedHandler(this, (sender, e) => HelpViewer.Show(e.HelpTopic));

OnClosed

protected override void OnClosed(RoutedEventArgs e)

Stops listening for F1 when the tip closes.

Parameters
e
The data for the event.

OnOpened

protected override void OnOpened(RoutedEventArgs e)

Records whether the tip's element is enabled, and starts listening for F1 on its window.

Parameters
e
The data for the event.

RemoveHelpRequestedHandler static

public static void RemoveHelpRequestedHandler( DependencyObject element, EventHandler<BinaryRibbonScreenTipHelpRequestedEventArgs> handler)

Removes a handler for the HelpRequested event (HelpRequestedEvent) from an element.

Parameters
element
The element the handler was added to. Nothing happens unless it is a UIElement.
handler
The handler.

Fields

DescriptionProperty static

public static readonly DependencyProperty DescriptionProperty

Identifies the Description dependency property.

DisabledDescriptionProperty static

public static readonly DependencyProperty DisabledDescriptionProperty

Identifies the DisabledDescription dependency property.

FooterImageProperty static

public static readonly DependencyProperty FooterImageProperty

Identifies the FooterImage dependency property.

FooterTextProperty static

public static readonly DependencyProperty FooterTextProperty

Identifies the FooterText dependency property.

HelpRequestedEvent static

public static readonly RoutedEvent HelpRequestedEvent

Identifies the HelpRequested attached event, raised when the user presses F1 while a screen tip is on screen.

Remarks

Raised on the element the tip belongs to and bubbling from there, with a BinaryRibbonScreenTipHelpRequestedEventArgs carrying the tip and its HelpTopic. Handle it anywhere above – in XAML as bm:BinaryRibbonScreenTip.HelpRequested="...", or with AddHelpRequestedHandler. Marking it handled stops the F1 key going any further.

HelpTopicProperty static

public static readonly DependencyProperty HelpTopicProperty

Identifies the HelpTopic dependency property.

ImageProperty static

public static readonly DependencyProperty ImageProperty

Identifies the Image dependency property.

IsOwnerEnabledProperty static

public static readonly DependencyProperty IsOwnerEnabledProperty

Identifies the IsOwnerEnabled dependency property.

MaximumContentWidthProperty static

public static readonly DependencyProperty MaximumContentWidthProperty

Identifies the MaximumContentWidth dependency property.

TitleProperty static

public static readonly DependencyProperty TitleProperty

Identifies the Title dependency property.