FieldView

View source
ceramic.Entity → ceramic.Visual → ceramic.Quad → ceramic.Layer → ceramic.View → ceramic.LinearLayout → elements.FieldView (Class) → BaseTextFieldView, BooleanFieldView, ColorFieldView, SelectFieldView
Implements: TabFocusable, tracker.Observable

Base class for interactive field views in the Elements UI framework.

FieldView provides a foundation for creating focusable input fields that integrate with the field focus system. It handles:

  • Focus management and visual feedback
  • Tab navigation support
  • Automatic scrolling to ensure visibility when focused
  • Integration with the global FieldSystem

Subclasses should override didLostFocus() to handle cleanup when focus is lost.

See: FieldSystem, TabFocusable

Instance Members

elements
observedDirty: Bool

Default is false, automatically set to true when any of this instance's observable variables has changed.

elements
focused: Bool

Whether this field currently has focus.

This is a computed property that checks with the global FieldSystem to determine if this field is the currently focused field.

elements
windowItem: WindowItem

If this field is managed by a WindowItem, this is the WindowItem. Used for window-specific field management and coordination.

elements
invalidateFocused(): Void
elements
focus(): Void

Gives focus to this field.

Sets this field as the screen's focused visual and ensures it's visible within any containing scrollable area.

elements
makeVisibleInForm(): Void

Ensures this field is visible within its containing scrollable form.

If the field is inside a ScrollingLayout, this method will automatically scroll the container to make the field fully visible. The method adds 8 pixels of padding above and below the field for better visual appearance.

If the field is not inside a scrollable container, this method does nothing.

elements
allowsTabFocus(): Bool

Whether this field can receive focus through tab navigation.

Fields are focusable by tab unless they have a 'disabled' property set to true.

Returns Description
Bool true if the field can be focused via tab, false if disabled
elements
tabFocus(): Void

Gives focus to this field via tab navigation.

Called by the tab focus system when this field is selected through keyboard navigation.

elements
escapeTabFocus(): Void

Removes focus from this field when escaping tab navigation.

Called when the user presses Escape to exit tab navigation mode. Only clears focus if this field currently has focus.

elements
hitsSelfOrDerived(x: Float, y: Float): Bool

Tests if the given coordinates hit this field.

Used by the tab focus system to determine if a pointer event occurred within this field's bounds.

Name Type Description
x Float The x coordinate to test
y Float The y coordinate to test
Returns Description
Bool true if the coordinates are within this field's bounds
elements
usesScanCode(scanCode: ceramic.ScanCode): Bool

Checks if this field uses the specified scan code.

Fields consume ESCAPE and ENTER keys when focused to handle field-specific actions like canceling or confirming input.

Name Type Description
scanCode ceramic.ScanCode The scan code to check
Returns Description
Bool true if this field uses the scan code when focused
elements
usesKeyCode(keyCode: ceramic.KeyCode): Bool

Checks if this field uses the specified key code.

Fields consume ESCAPE and ENTER keys when focused to handle field-specific actions like canceling or confirming input.

Name Type Description
keyCode ceramic.KeyCode The key code to check
Returns Description
Bool true if this field uses the key code when focused
elements
new(): Void

Creates a new FieldView instance.

Initializes the field with:

  • Transparent background
  • Horizontal layout direction
  • Pointer event handling for focus
  • Focus change tracking

Private Members

elements
unobservedFocused: Bool
elements
focusedThisFrame: Bool

Tracks whether this field had focus during the current frame. Used for keyboard input handling to prevent key conflicts.

elements
emitObservedDirty(instance: FieldView, fromSerializedField: Bool): Void

Event when any observable value as changed on this instance.

Name Type
instance FieldView
fromSerializedField Bool
elements
emitFocusedChange(current: Bool, previous: Bool): Void

Event when focused field changes.

Name Type
current Bool
previous Bool
elements
handleFocusedChange(focused: Bool, prevFocused: Bool): Void

Handles focus state changes. Updates the focusedThisFrame flag immediately when gaining focus, and defers the update until end of frame when losing focus.

Name Type Description
focused Bool The new focus state
prevFocused Bool The previous focus state
elements
updateFocusedThisFrame(): Void

Updates the focusedThisFrame flag at the end of the frame. Called when the field loses focus to ensure proper state tracking.

elements
getScrollingLayout(): ScrollingLayout<ceramic.View>

Finds the containing ScrollingLayout by traversing up the visual hierarchy.

Returns Description
ScrollingLayout<ceramic.View> The parent ScrollingLayout if found, null otherwise
elements
didLostFocus(): Void

Called when this field loses focus.

This method is called by the FieldSystem when focus moves to another field or when focus is cleared. Subclasses should override this method to perform any necessary cleanup, such as:

  • Hiding virtual keyboards
  • Committing pending changes
  • Updating visual state

@allow elements.FieldSystem

elements
bindPointerEvents(): Void

Sets up pointer event handling to make this field focusable.

By binding to the pointer down event, this field becomes eligible to receive focus when clicked or tapped.

Metadata

Name Parameters
:build tracker.macros.ObservableMacro.build()
:autoBuild tracker.macros.ObservableMacro.build()
:build tracker.macros.EventsMacro.build()
:autoBuild tracker.macros.EventsMacro.build()
:build ceramic.macros.EntityMacro.buildForCompletion()
:autoBuild ceramic.macros.EntityMacro.buildForCompletion()