Package ca.cgjennings.apps.arkham
Class ContextBar
- java.lang.Object
-
- ca.cgjennings.apps.arkham.ContextBar
-
public final class ContextBar extends java.lang.Object
A small floating tool bar that tracks the focused component and shows buttons relevant to that context. To create new buttons that the user can add to the context bar, implement theContextBar.Button
class (typically by subclassingContextBar.AbstractButton
orContextBar.CommandButton
), and register the new button withregisterButton(ca.cgjennings.apps.arkham.ContextBar.Button)
.- Since:
- 3.0
- Author:
- Chris Jennings
-
-
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 anAbstractCommand
.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 tojava.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 whenBUTTONS_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.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description static ContextBar.Button[]
fromButtonDescription(java.lang.String buttonDesc, boolean skipInvalidButtons)
Creates an array of buttons from a string description.static ContextBar.Button
getButton(java.lang.String id)
Returns the registered button with the given ID, ornull
if there is no such button.ContextBar.Button[]
getButtons()
Returns a copy of the installed buttons.ContextBar.Context
getContext()
Returns the context bar's current context information.static int
getPreferredContextBarIconSize()
Returns the ideal icon size for context bar icons.static ContextBar.Button[]
getRegisteredButtons()
Returns an array of the registered buttons.static ContextBar
getShared()
Returns the standard, shared instance.boolean
isCollapsed()
Returnstrue
if the tool bar is currently collapsed (only the button that expands the tool bar is visible).boolean
isEnabled()
Returnstrue
if the tool bar is currently enabled.boolean
isPointerOverBar()
Returnstrue
if the pointer is currently over the context bar.static void
registerButton(ContextBar.Button button)
Adds a new kind of button that can be displayed on the tool bar.void
setButtons(ContextBar.Button... buttons)
Sets the buttons included on the context bar.void
setCollapsed(boolean collapsed)
Sets whether the tool bar is collapsed so that only the expand button is visible.void
setEnabled(boolean enable)
Enables or disabled the tool bar.static java.lang.String
toButtonDescription(ContextBar.Button[] buttons)
Returns a string that describes the button layout defined by the specified buttons.static void
unregisterButton(ContextBar.Button button)
Removes a previously registered button.static void
unregisterButton(java.lang.String id)
Removes a previously registered button by its ID.
-
-
-
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
-
DEFAULT_BUTTON_LIST
public static final java.lang.String DEFAULT_BUTTON_LIST
The default value used whenBUTTONS_SETTING
has no value.- 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 tojava.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 tojava.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 tojava.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 tojava.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 aPoint
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 theContextBar.Locator
class.- See Also:
- Constant Field Values
-
-
Method Detail
-
setButtons
public void setButtons(ContextBar.Button... buttons)
Sets the buttons included on the context bar.- Parameters:
buttons
- an array of Button objects; usenull
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 aboveskipInvalidButtons
- iftrue
, 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 andskipInvalidButtons
isfalse
-
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
- iftrue
the tool bar will be created and shown; otherwise it will be hidden and associated resources will be freed
-
isEnabled
public boolean isEnabled()
Returnstrue
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
- iftrue
, collapse the tool bar
-
isCollapsed
public boolean isCollapsed()
Returnstrue
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()
Returnstrue
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 isnull
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
-
unregisterButton
public static void unregisterButton(ContextBar.Button button)
Removes a previously registered button.- Parameters:
button
- the button to remove from the registry- Throws:
java.lang.NullPointerException
- if the button or its ID isnull
- See Also:
registerButton(ca.cgjennings.apps.arkham.ContextBar.Button)
-
getButton
public static ContextBar.Button getButton(java.lang.String id)
Returns the registered button with the given ID, ornull
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
- ifid
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 differentTheme
is active.- Returns:
- the width and height of context bar icons
-
-