Class ContextBar

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  ContextBar.AbstractButton
      An abstract base class for implementing a context bar button.
      static interface  ContextBar.Button
      This class represents a buttons that can appear on the context bar.
      static class  ContextBar.CommandButton
      A context bar button that delegates to an AbstractCommand.
      static class  ContextBar.Context
      Encapsulates information about the bar's current context.
      static interface  ContextBar.Locator
      This interface is implemented by objects that customize where a context bar appears over a component.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String BAR_BELOW_PROPERTY
      By default, the context bar appears above the control that it currently affects.
      static java.lang.String BAR_CUSTOM_LOCATION_PROPERTY
      Allows a component to have complete control over how the context bar is positioned relative to that component.
      static java.lang.String BAR_DISABLE_PROPERTY
      The context bar can be prevented from appearing over a particular control by setting a client property with this name to java.lang.Boolean.TRUE.
      static java.lang.String BAR_INSIDE_PROPERTY
      By default, the context bar appears outside of the control that it currently affects.
      static java.lang.String BAR_LEADING_SIDE_PROPERTY
      By default, the context bar appears on the trailing edge of the the control that it currently affects.
      static java.lang.String BAR_OFFSET_PROPERTY
      Adjusts the usual location of the context bar.
      static java.lang.String BUTTONS_SETTING
      Setting key that lists the buttons to appear on the context bar.
      static java.lang.String DEFAULT_BUTTON_LIST
      The default value used when BUTTONS_SETTING has no value.
      static java.lang.String ENABLE_BAR_SETTING
      Setting key that controls whether the default bar is enabled.
    • Constructor Summary

      Constructors 
      Constructor Description
      ContextBar()
      Creates a new context bar.
    • Field Detail

      • ENABLE_BAR_SETTING

        public static final java.lang.String ENABLE_BAR_SETTING
        Setting key that controls whether the default bar is enabled.
        See Also:
        Constant Field Values
      • BUTTONS_SETTING

        public static final java.lang.String BUTTONS_SETTING
        Setting key that lists the buttons to appear on the context bar.
        See Also:
        Constant Field Values
      • BAR_DISABLE_PROPERTY

        public static final java.lang.String BAR_DISABLE_PROPERTY
        The context bar can be prevented from appearing over a particular control by setting a client property with this name to java.lang.Boolean.TRUE.
        See Also:
        Constant Field Values
      • BAR_BELOW_PROPERTY

        public static final java.lang.String BAR_BELOW_PROPERTY
        By default, the context bar appears above the control that it currently affects. Setting a client property with this name to java.lang.Boolean.TRUE will cause the bar to appear below the control instead.
        See Also:
        Constant Field Values
      • BAR_INSIDE_PROPERTY

        public static final java.lang.String BAR_INSIDE_PROPERTY
        By default, the context bar appears outside of the control that it currently affects. Setting a client property with this name to java.lang.Boolean.TRUE will cause the bar to appear inside the control instead.
        See Also:
        Constant Field Values
      • BAR_LEADING_SIDE_PROPERTY

        public static final java.lang.String BAR_LEADING_SIDE_PROPERTY
        By default, the context bar appears on the trailing edge of the the control that it currently affects. Setting a client property with this name to java.lang.Boolean.TRUE will cause the bar to appear on the leading side instead.
        See Also:
        Constant Field Values
      • BAR_OFFSET_PROPERTY

        public static final java.lang.String BAR_OFFSET_PROPERTY
        Adjusts the usual location of the context bar. Setting a client property with this name and a Point value on a component will cause the context bar to shift the usual location of the bar by that many pixels. This allows you to fine tune the location of the bar for specific situations. It should only be used when necessary.
        See Also:
        Constant Field Values
      • BAR_CUSTOM_LOCATION_PROPERTY

        public static final java.lang.String BAR_CUSTOM_LOCATION_PROPERTY
        Allows a component to have complete control over how the context bar is positioned relative to that component. To define a custom location for a component, set a client property on the component with this name and a value that is an instance of the ContextBar.Locator class.
        See Also:
        Constant Field Values
    • Constructor Detail

      • ContextBar

        public ContextBar()
        Creates a new context bar.
    • Method Detail

      • setButtons

        public void setButtons​(ContextBar.Button... buttons)
        Sets the buttons included on the context bar.
        Parameters:
        buttons - an array of Button objects; use null to insert a separator
      • getButtons

        public ContextBar.Button[] getButtons()
        Returns a copy of the installed buttons.
        Returns:
        an array containing the buttons currently included on the context bar
      • fromButtonDescription

        public static ContextBar.Button[] fromButtonDescription​(java.lang.String buttonDesc,
                                                                boolean skipInvalidButtons)
        Creates an array of buttons from a string description. The description consist of button IDs separated by commas. A pipe character may be used instead of an ID to insert a separator.
        Parameters:
        buttonDesc - a string in the format described above
        skipInvalidButtons - if true, invalid IDs will be skipped
        Returns:
        an array of buttons; null will be used to indicate separators
        Throws:
        java.lang.IllegalArgumentException - if the format was invalid and skipInvalidButtons is false
      • toButtonDescription

        public static java.lang.String toButtonDescription​(ContextBar.Button[] buttons)
        Returns a string that describes the button layout defined by the specified buttons.
        Parameters:
        buttons - the array of buttons to convert to a string description
        Returns:
        a string of button IDs representing the current button layout
      • getContext

        public ContextBar.Context getContext()
        Returns the context bar's current context information.
        Returns:
        the bar's context
      • getShared

        public static ContextBar getShared()
        Returns the standard, shared instance.
        Returns:
        the standard tool bar
      • setEnabled

        public void setEnabled​(boolean enable)
        Enables or disabled the tool bar.
        Parameters:
        enable - if true the tool bar will be created and shown; otherwise it will be hidden and associated resources will be freed
      • isEnabled

        public boolean isEnabled()
        Returns true if the tool bar is currently enabled. When the tool bar is enabled, it will automatically pop up over the current markup target.
        Returns:
        true if the tool bar is enabled
      • setCollapsed

        public void setCollapsed​(boolean collapsed)
        Sets whether the tool bar is collapsed so that only the expand button is visible.
        Parameters:
        collapsed - if true, collapse the tool bar
      • isCollapsed

        public boolean isCollapsed()
        Returns true if the tool bar is currently collapsed (only the button that expands the tool bar is visible).
        Returns:
        true if the tool bar is collapsed
      • isPointerOverBar

        public boolean isPointerOverBar()
        Returns true if the pointer is currently over the context bar.
        Returns:
        true if there is a pointer on this platform and it is over the context bar
      • registerButton

        public static void registerButton​(ContextBar.Button button)
        Adds a new kind of button that can be displayed on the tool bar. Whether or not the button is actually shown will depend on whether the user adds it to the tool bar.
        Parameters:
        button - the button template to register
        Throws:
        java.lang.NullPointerException - if the button or its ID is null
        java.lang.IllegalArgumentException - if the ID contains any invalid characters
      • unregisterButton

        public static void unregisterButton​(java.lang.String id)
        Removes a previously registered button by its ID. Has no effect if no such button is registered.
        Parameters:
        id - the ID of the button to remove
      • getButton

        public static ContextBar.Button getButton​(java.lang.String id)
        Returns the registered button with the given ID, or null if there is no such button.
        Parameters:
        id - the button ID to match
        Returns:
        the button with the requested ID, if registered
        Throws:
        java.lang.NullPointerException - if id is null
      • getRegisteredButtons

        public static ContextBar.Button[] getRegisteredButtons()
        Returns an array of the registered buttons.
        Returns:
        the registered buttons
      • getPreferredContextBarIconSize

        public static int getPreferredContextBarIconSize()
        Returns the ideal icon size for context bar icons. Icons larger or smaller than this value (in either width or height) will be resized automatically. This preferred icon size is fixed for any given run of the application, but may change between runs. For example, the size may change if a different Theme is active.
        Returns:
        the width and height of context bar icons