Package io.guise.framework.component

Interface Component

All Superinterfaces:
DepictedObject, Displayable, InfoModel, LabelModel, Model, PresentationModel, com.globalmentor.beans.PropertyBindable, com.globalmentor.beans.PropertyConstrainable
All Known Subinterfaces:
ActionControl, ActionValueControl<V>, ApplicationFrame, ArrangeContainer, Box, ButtonControl, CardContainer, CardControl, CompositeComponent, Container, ContainerControl, ContentComponent, Control, DialogFrame<V>, EditComponent, FlyoverFrame, Frame, HeadingComponent, ImageComponent, InputFocusableComponent, InputFocusGroupComponent, LabelComponent, LabelDisplayableComponent, LayoutComponent, LayoutControl, LinkControl, ListSelectControl<V>, Menu, ModalComponent<M>, ModalFrame<R>, ModalNavigationPanel<R>, NavigationComponent, OptionDialogFrame<O>, Panel, PendingImageComponent, SectionComponent, SelectActionControl, SelectButtonControl, SelectControl<V>, SelectLinkControl, ToolButtonControl, ValueControl<V>, ValuedComponent<V>, Widget
All Known Implementing Classes:
AboutPanel, AbstractActionControl, AbstractActionValueControl, AbstractApplicationFrame, AbstractArrayCompositeComponent, AbstractBooleanSelectActionControl, AbstractBox, AbstractButtonControl, AbstractCardPanel, AbstractComponent, AbstractCompositeComponent, AbstractCompositeStateComponent, AbstractCompositeStateControl, AbstractContainer, AbstractContainerControl, AbstractContainerValueControl, AbstractControl, AbstractDialogFrame, AbstractEditComponentTextControl, AbstractEditValueControl, AbstractEditValuePanel, AbstractEnumCompositeComponent, AbstractFlyoverFrame, AbstractFrame, AbstractImageComponent, AbstractLabel, AbstractLayoutComponent, AbstractLayoutControl, AbstractLayoutValueControl, AbstractLinkControl, AbstractListCompositeComponent, AbstractListSelectContainerControl, AbstractListSelectControl, AbstractMenu, AbstractModalFrame, AbstractModalNavigationPanel, AbstractMultipleCompositeComponent, AbstractOptionDialogFrame, AbstractPanel, AbstractSelectActionControl, AbstractSelectActionValueControl, AbstractSequenceTaskPanel, AbstractSingleCompositeComponent, AbstractTextControl, AbstractValueControl, AbstractValuedPanel, AccordionMenu, ArrangePanel, AutoNavigationPathBreadcrumbLinkPanel, BooleanSelectButton, BooleanSelectLink, BooleanSelectToolButton, BooleanValueControlSelectControl, BusyPanel, Button, CalendarControl, CalendarDialogFrame, CardPanel, CardTabControl, CheckControl, DateTimeControl, DateTimeFieldsControl, DefaultApplicationFrame, DefaultDialogFrame, DefaultFlyoverFrame, DefaultFrame, DefaultModalFrame, DefaultModalNavigationPanel, DropMenu, EditComponentLabelControl, EditComponentTextControl, Flash, GroupPanel, Heading, HeadingLink, Image, ImageActionControl, ImageBooleanSelectActionControl, Label, LayoutPanel, LikeButton, Link, ListControl, Message, MessageOptionDialogFrame, NamePanel, NavigationPathBreadcrumbLinkPanel, NotificationOptionDialogFrame, PasswordAuthenticationPanel, PendingImage, PendingImageActionControl, Picture, PlatformFileUploadPanel, ResourceCollectControl, ResourceImportControl, ScrollControl, SectionPanel, SelectableLabel, SelectButton, SelectLink, SequenceCardPanel, SliderControl, SpinnerControl, TabbedPanel, TabContainerControl, TabControl, Table, Table.DefaultCellMessage, TaskStateSelectLink, TextBox, TextControl, Toolbar, ToolButton, TreeControl, ValueSelectButton, ValueSelectLink
public interface Component extends DepictedObject, PresentationModel, InfoModel
Base interface for all Guise components. Each component must provide either a Guise session constructor; or a Guise session and string ID constructor. Any component may contain other components, but only a Container allows for custom addition and removal of child components.

A component takes up space regardless of whether it is set to be visible using PresentationModel.setVisible(boolean). PresentationModel.setDisplayed(boolean) determines whether the component is displayed at all. If a component is not displayed, it takes up no space. If a component is not displayed, it is not visible regardless of whether it is set to be visible. If a developer must hide sensitive data, the developer should remove the component from its parent container altogether.

For widest platform support the general PresentationModel.ROUNDED_CORNER_ARC_SIZE constant should be used whenever possible when requesting rounded corners.

Author:
Garret Wilson

  • Field Details

    • BOOKMARK_ENABLED_PROPERTY

      static final String BOOKMARK_ENABLED_PROPERTY
      The bound property of whether the component has bookmarks enabled.

    • CONSTRAINTS_PROPERTY

      static final String CONSTRAINTS_PROPERTY
      The bound property of the layout constraints.

    • DRAG_ENABLED_PROPERTY

      static final String DRAG_ENABLED_PROPERTY
      The bound property of whether the component has dragging enabled.

    • DROP_ENABLED_PROPERTY

      static final String DROP_ENABLED_PROPERTY
      The bound property of whether the component has dropping enabled.

    • FLYOVER_ENABLED_PROPERTY

      static final String FLYOVER_ENABLED_PROPERTY
      The bound property of whether the component has flyovers enabled.

    • FLYOVER_STRATEGY_PROPERTY

      static final String FLYOVER_STRATEGY_PROPERTY
      The bound property of the strategy controlling flyovers.

    • INPUT_STRATEGY_PROPERTY

      static final String INPUT_STRATEGY_PROPERTY
      The input strategy bound property.

    • NAME_PROPERTY

      static final String NAME_PROPERTY
      The bound property of the component name.

    • NOTIFICATION_PROPERTY

      static final String NOTIFICATION_PROPERTY
      The bound property of the notification.

    • ORIENTATION_PROPERTY

      static final String ORIENTATION_PROPERTY
      The orientation bound property.

    • THEME_APPLIED_PROPERTY

      static final String THEME_APPLIED_PROPERTY
      The bound property of whether a theme has been applied to this object.

    • VALID_PROPERTY

      static final String VALID_PROPERTY
      The valid bound property.

  • Method Details

    • getDepictor

      Depictor<? extends Component> getDepictor()
      Specified by:
      getDepictor in interface DepictedObject
      Returns:
      The depictor for this component.

    • addPreferenceProperty

      void addPreferenceProperty(String propertyName)
      Adds a property to be saved and loaded as a preference.
      Parameters:
      propertyName - The property to store as a preference.
      See Also:

    • isPreferenceProperty

      boolean isPreferenceProperty(String propertyName)
      Determines whether the given property is saved and loaded as a preference.
      Parameters:
      propertyName - The property to determine if it is stored as a preference.
      Returns:
      true if the given property is saved and loaded as a preference.
      See Also:

    • getPreferenceProperties

      Iterable<String> getPreferenceProperties()
      Returns all properties stored as preferences.
      Returns:
      An iterable of all properties saved and loaded as preferences.
      See Also:

    • removePreferenceProperty

      void removePreferenceProperty(String propertyName)
      Removes a property from being saved and loaded as preferences.
      Parameters:
      propertyName - The property that should no longer be stored as a preference.
      See Also:

    • getName

      String getName()
      Returns:
      The name of the component, not guaranteed to be unique (but guaranteed not to be the empty string) and useful only for searching for components within a component sub-hierarchy, or null if the component has no name.

    • setName

      void setName(String newName)
      Sets the name of the component. This is a bound property.
      Parameters:
      newName - The new name of the component, or null if the component should have no name.
      Throws:
      IllegalArgumentException - if the given name is the empty string.
      See Also:

    • getConstraints

      Constraints getConstraints()
      Returns:
      The layout constraints describing individual component layout information, or null if no constraints have been specified for this component.

    • setConstraints

      void setConstraints(Constraints newConstraints)
      Sets the layout constraints of this component. This is a bound property.
      Parameters:
      newConstraints - The layout constraints describing individual component layout information, or null if no constraints have been specified for this component.
      See Also:

    • getInputStrategy

      InputStrategy getInputStrategy()
      Returns:
      The strategy for processing input, or null if this component has no input strategy.

    • setInputStrategy

      void setInputStrategy(InputStrategy newInputStrategy)
      Sets the strategy for processing input. This is a bound property.
      Parameters:
      newInputStrategy - The new strategy for processing input, or null if this component is to have no input strategy.
      See Also:

    • getNotification

      Notification getNotification()
      Returns:
      The notification associated with the component, or null if no notification is associated with this component.

    • setNotification

      void setNotification(Notification newNotification)
      Sets the component notification. This is a bound property. The notification is also fired as a NotificationEvent on this component if a new notification is given. Parents are expected to refire the notification event up the hierarchy.
      Parameters:
      newNotification - The notification for the component, or null if no notification is associated with this component.
      See Also:

    • getOrientation

      Orientation getOrientation()
      Returns this component's requested orientation. To resolve the orientation up the hierarchy, getComponentOrientation() should be used.
      Returns:
      The internationalization orientation of the component's contents, or null if the default orientation should be used.
      See Also:

    • getComponentOrientation

      Orientation getComponentOrientation()
      Determines the internationalization orientation of the component's contents. This method returns the local orientation value, if there is one. If there is no orientation specified for this component, the request is deferred to this component's parent. If there is no parent component, a default orientation is retrieved from the current session.
      Returns:
      The internationalization orientation of the component's contents.
      See Also:

    • setOrientation

      void setOrientation(Orientation newOrientation)
      Sets the orientation. This is a bound property
      Parameters:
      newOrientation - The new internationalization orientation of the component's contents, or null if default orientation should be determined based upon the session's locale.
      See Also:

    • getParent

      CompositeComponent getParent()
      Returns:
      The parent of this component, or null if this component does not have a parent.

    • getAncestor

      <A extends CompositeComponent> A getAncestor(Class<A> ancestorClass)
      Retrieves the first ancestor of the given type.
      Type Parameters:
      A - The type of ancestor component requested.
      Parameters:
      ancestorClass - The class of ancestor component requested.
      Returns:
      The first ancestor component of the given type, or null if this component has no such ancestor.

    • setParent

      void setParent(CompositeComponent newParent)
      Sets the parent of this component. This method is managed by containers, and normally should not be called by applications. A component cannot be given a parent if it already has a parent. A component's parent cannot be removed if that parent is a container and this component is still a child of that container. A container's parent cannot be set to a container unless that container already recognizes this component as one of its children. If a component is given the same parent it already has, no action occurs.
      Parameters:
      newParent - The new parent for this component, or null if this component is being removed from a parent.
      Throws:
      IllegalStateException - if a parent is provided and this component already has a parent.
      IllegalStateException - if no parent is provided and this component's old parent is a container that still recognizes this component as its child.
      IllegalArgumentException - if a parent container is provided and the given parent container does not already recognize this component as its child.
      See Also:

    • isDragEnabled

      boolean isDragEnabled()
      Returns:
      Whether the component has dragging enabled.

    • setDragEnabled

      void setDragEnabled(boolean newDragEnabled)
      Sets whether the component has dragging enabled. This is a bound property of type Boolean.
      Parameters:
      newDragEnabled - true if the component should allow dragging, else false.
      See Also:

    • isDropEnabled

      boolean isDropEnabled()
      Returns:
      Whether the component has dropping enabled.

    • setDropEnabled

      void setDropEnabled(boolean newDropEnabled)
      Sets whether the component has dropping enabled. This is a bound property of type Boolean.
      Parameters:
      newDropEnabled - true if the component should allow dropping, else false.
      See Also:

    • isFlyoverEnabled

      boolean isFlyoverEnabled()
      Returns:
      Whether flyovers are enabled for this component.

    • setFlyoverEnabled

      void setFlyoverEnabled(boolean newFlyoverEnabled)
      Sets whether flyovers are enabled for this component. Flyovers contain information from the component model's "description" property. This is a bound property of type Boolean.
      Parameters:
      newFlyoverEnabled - true if the component should display flyovers, else false.
      See Also:

    • getFlyoverStrategy

      Component.FlyoverStrategy<?> getFlyoverStrategy()
      Returns:
      The installed flyover strategy, or null if there is no flyover strategy installed.

    • setFlyoverStrategy

      void setFlyoverStrategy(Component.FlyoverStrategy<?> newFlyoverStrategy)
      Sets the strategy for controlling flyovers. The flyover strategy will be registered as a mouse listener for this component. This is a bound property.
      Parameters:
      newFlyoverStrategy - The new flyover strategy, or null if there is no flyover strategy installed.
      See Also:

    • isThemeApplied

      boolean isThemeApplied()
      Returns:
      Whether a theme has been applied to this component.

    • setThemeApplied

      void setThemeApplied(boolean newThemeApplied)
      Sets whether a theme has been applied to this component. This is a bound property of type Boolean.
      Parameters:
      newThemeApplied - true if a theme has been applied to this component, else false.
      See Also:

    • addExportStrategy

      void addExportStrategy(ExportStrategy<?> exportStrategy)
      Adds an export strategy to the component. The export strategy will take precedence over any compatible export strategy previously added.
      Parameters:
      exportStrategy - The export strategy to add.

    • removeExportStrategy

      void removeExportStrategy(ExportStrategy<?> exportStrategy)
      Removes an export strategy from the component.
      Parameters:
      exportStrategy - The export strategy to remove.

    • exportTransfer

      Transferable<?> exportTransfer()
      Exports data from the component. Each export strategy, from last to first added, will be asked to export data, until one is successful.
      Specified by:
      exportTransfer in interface DepictedObject
      Returns:
      The object to be transferred, or null if no data can be transferred.

    • addImportStrategy

      void addImportStrategy(ImportStrategy<?> importStrategy)
      Adds an import strategy to the component. The import strategy will take precedence over any compatible import strategy previously added.
      Parameters:
      importStrategy - The import strategy to add.

    • removeImportStrategy

      void removeImportStrategy(ImportStrategy<?> importStrategy)
      Removes an import strategy from the component.
      Parameters:
      importStrategy - The import strategy to remove.

    • importTransfer

      boolean importTransfer(Transferable<?> transferable)
      Imports data to the component. Each import strategy, from last to first added, will be asked to import data, until one is successful.
      Parameters:
      transferable - The object to be transferred.
      Returns:
      true if the given object was be imported.

    • initialize

      void initialize()
      Initializes the component after construction. This method can only be called once during the life of a component. Subclasses should call this version.
      Throws:
      IllegalStateException - if this method has already been called.

    • isValid

      boolean isValid()
      Returns:
      Whether the state of the component and all child components represents valid user input.

    • validate

      boolean validate()
      Validates the user input of this component and all child components. The component will be updated with error information.
      Returns:
      The current state of isValid() as a convenience.

    • getTheme

      Theme getTheme() throws IOException
      Returns the theme to apply to this component. If there is no theme to this component, the parent theme will be returned.
      Returns:
      The theme to apply to this component.
      Throws:
      IOException - if there is an error loading the theme.

    • resetTheme

      void resetTheme()
      Resets this object's theme. This method sets to false the state of whether a theme has been applied to this object. This method is called for any child components resetting its own theme. No new theme is actually loaded. There is normally no need to override this method or to call this method directly by applications.
      See Also:

    • updateTheme

      void updateTheme() throws IOException
      Updates this object's theme. This method checks whether a theme has been applied to this object. If a theme has not been applied to this object this method calls applyTheme(). This method is called for any child components before applying the theme to the component itself, to assure that child theme updates have already occurred before theme updates occur for this component. There is normally no need to override this method or to call this method directly by applications.
      Throws:
      IOException - if there was an error loading or applying a theme.
      See Also:

    • applyTheme

      void applyTheme() throws IOException
      Applies the theme to this object. Themes are only applied of the application is themed. This method may be overridden to effectively override theme settings by ensuring the state of important properties after the theme has been set. If the theme is successfully applied, this method updates the theme applied status.
      Throws:
      IOException - if there was an error loading or applying a theme.
      See Also:

    • applyTheme

      void applyTheme(Theme theme)
      Applies a theme and its parents to this object. The theme's rules will be applied to this object and any related objects. Theme application occurs unconditionally, regardless of whether themes have been applied to this component before. There is normally no need to call this method directly by applications.
      Parameters:
      theme - The theme to apply to the object.

    • loadPreferences

      void loadPreferences(boolean includeDescendants) throws IOException
      Loads the preferences for this component and optionally any descendant components. Any preferences returned from getPreferenceProperties() will be loaded automatically.
      Parameters:
      includeDescendants - true if preferences of any descendant components should also be loaded, else false.
      Throws:
      IOException - if there is an error loading preferences.

    • savePreferences

      void savePreferences(boolean includeDescendants) throws IOException
      Saves the preferences for this component and optionally any descendant components. Any preferences returned from getPreferenceProperties() will be saved automatically.
      Parameters:
      includeDescendants - true if preferences of any descendant components should also be saved, else false.
      Throws:
      IOException - if there is an error saving preferences.

    • dispatchInputEvent

      void dispatchInputEvent(InputEvent inputEvent)
      Dispatches an input event to this component and all child components, if any. If this is a FocusedInputEvent, the event will be directed towards the branch in which lies the focused component of any InputFocusGroupComponent ancestor of this component (or this component, if it is a focus group). If this is instead a TargetedEvent, the event will be directed towards the branch in which lies the target component of the event. Otherwise, the event will be dispatched to all child components. Only after the event has been dispatched to any children will the event be fired to any event listeners and then passed to the installed input strategy, if any. Once the event is consumed, no further processing takes place.
      Parameters:
      inputEvent - The input event to dispatch.
      Throws:
      NullPointerException - if the given event is null.
      See Also:

    • fireInputEvent

      void fireInputEvent(InputEvent inputEvent)
      Fire the given even to all registered listeners, if any. If the event is consumed further processing should cease.
      Parameters:
      inputEvent - The input event to fire.
      Throws:
      NullPointerException - if the given event is null.
      See Also:

    • addCommandListener

      void addCommandListener(CommandListener commandListener)
      Adds a command listener.
      Parameters:
      commandListener - The command listener to add.

    • removeCommandListener

      void removeCommandListener(CommandListener commandListener)
      Removes a command listener.
      Parameters:
      commandListener - The command listener to remove.

    • hasCommandListeners

      boolean hasCommandListeners()
      Returns:
      true if there is one or more command listeners registered.

    • addKeyListener

      void addKeyListener(KeyboardListener keyListener)
      Adds a key listener.
      Parameters:
      keyListener - The key listener to add.

    • removeKeyListener

      void removeKeyListener(KeyboardListener keyListener)
      Removes a key listener.
      Parameters:
      keyListener - The key listener to remove.

    • hasKeyListeners

      boolean hasKeyListeners()
      Returns:
      true if there is one or more key listeners registered.

    • addMouseListener

      void addMouseListener(MouseListener mouseListener)
      Adds a mouse listener.
      Parameters:
      mouseListener - The mouse listener to add.

    • removeMouseListener

      void removeMouseListener(MouseListener mouseListener)
      Removes a mouse listener.
      Parameters:
      mouseListener - The mouse listener to remove.

    • hasMouseListeners

      boolean hasMouseListeners()
      Returns:
      true if there is one or more mouse listeners registered.

    • addNotificationListener

      void addNotificationListener(NotificationListener notificationListener)
      Adds a notification listener.
      Parameters:
      notificationListener - The notification listener to add.

    • removeNotificationListener

      void removeNotificationListener(NotificationListener notificationListener)
      Removes a notification listener.
      Parameters:
      notificationListener - The notification listener to remove.

    • notify

      void notify(Notification notification)
      Notifies the user of the given notification information. The notification is stored in this component using setNotification(Notification), which fires appropriate notification events. This method calls GuiseSession.notify(Notification...).
      Parameters:
      notification - The notification information to relay.