Area.mui

MUIA_Background

Function

Duplicate a supported MUII background/pattern identifier or a readable
NUL-terminated image-specification string into owned storage. Omission
inherits background drawing through the parent or Window.

Inputs

IPTR image specification; initialize and set. An internal-pointer getter

is also implemented.

Notes

The setter copies before freeing the previous specification. Copy
failure preserves the old value. An equal copied specification
suppresses its notification by changing the tag to TAG_IGNORE. During
setup/show, replacement cleans up and recreates the display
specification and requests redraw. The getter returns the private
prepared image-spec pointer, not the original identifier or string; do
not free it or pass it as an input specification.

Bugs

Prepared-image allocation is not reported by the setter. Constructor
copy failure is tolerated. Getter storage is meaningful only within the
setup lifetime and is invalidated by replacement or cleanup.

MUIA_BottomEdge

Function

Return top + height - 1 from the object layout box. Coordinates are
relative to the native window origin, including border offsets
established by layout, not to the parent object.

Inputs

LONG geometry value; get only.

Notes

Values describe the full object rectangle including frame and inner
spacing. Right and bottom are inclusive. Meaningful geometry requires
completed layout; the getter does not force layout or test visibility.

MUIA_ContextMenu

Function

Store a borrowed context-menu object, initially NULL. During setup, a
non-NULL pointer requests mouse-button handling. A right-button press in
the object calls ContextMenuBuild; the returned menu is connected to
this object and used to open a temporary native menu.

Inputs

Object pointer; initialize, set, get.

Notes

The Area does not dispose the menu object. Keep it and its items alive
while used. Hide closes a live native context menu. Replacing the
pointer does not close an existing menu or update event registration. A
dynamic ContextMenuBuild override still needs a non-NULL ContextMenu
value to enter the default event path.

MUIA_ContextMenuTrigger

Function

ContextMenuChoice sets this tag to the chosen menu item for Notify

delivery.

Inputs

Object pointer notification event; no Area getter or storage.

Notes

Use the notification trigger value; the pointer is borrowed. Selection
also updates Menuitem_Checked when applicable and raises
Menuitem_Trigger before ContextMenuChoice. The native menu closes
afterward. The header get flag does not correspond to an Area getter.

MUIA_ControlChar

Function

Store a keyboard shortcut, initially zero. Setup registers the character
and input-mode action with the owning Window. Setting it during setup
removes and rebuilds that registration.

Inputs

Character value stored in TEXT; initialize, set, get.

Notes

The getter returns the stored character. RelVerify and Immediate
register MUIKEY_PRESS; Toggle registers MUIKEY_TOGGLE. None has no
action assignment in the helper. Character matching follows the Window
key-conversion path; this attribute does not define a new key map.

MUIA_CustomBackfill

Function

Declared in area.h but not implemented by Area.

Inputs

Declared initialize only.

Notes

There is no corresponding constructor, setter or getter case. Tags can
still participate in Notify delivery. The declaration does not establish
this capability.

MUIA_CycleChain

Function

Enable membership in the Window focus cycle chain, initially FALSE. The

getter returns a Boolean rather than an ordering value.

Inputs

LONG treated as Boolean; initialize, set, get.

Notes

Changes during setup remove and recreate the combined
control-character/cycle registration. Window appends a private cycle
node; nonzero values do not select a numeric position. InputMode None is
not rejected. Window cycle-node allocation failure is not reported to
this setter.

MUIA_Disabled

Function

Set or clear the independent high-bit disabled flag. The getter returns
TRUE when either that flag or the NestedDisabled count is nonzero.
Default FALSE.

Inputs

BOOL; initialize, set, get.

Notes

Clearing Disabled does not cancel nested disables. A change between
enabled and disabled requests redraw and, if set up, calls the release
helper with cancellation. Notify receives the requested tag value, which
need not equal the combined getter result. Area does not itself
propagate this state to children.

MUIA_DoubleBuffer

Function

Declared in area.h but not implemented by Area.

Inputs

BOOL; declared initialize, set, get.

Notes

There is no corresponding constructor, setter or getter case. Tags can
still participate in Notify delivery. The declaration does not establish
this capability.

MUIA_Draggable

Function

Enable the default motion handler to start dragging; default FALSE.
While the pointer remains inside and the left button is held, movement
of at least three pixels on either axis from the initial click starts
DoDrag.

Inputs

BOOL; initialize, set, get.

Notes

The flag alone does not register motion events. The default RelVerify
press path adds them; other input arrangements must provide appropriate
delivery. Starting a drag clears pressed state, stops the repeat timer
and restores the mouse-button event mask. Direct DoDrag does not check
this flag.

MUIA_Dropable

Function

Allow this object to be considered by the private drop-target query;

default TRUE.

Inputs

BOOL; initialize, set, get.

Notes

The query also requires coordinates inside the object and a DragQuery
result equal to Accept. Area's DragQuery default refuses every source,
so Dropable alone does not make a working drop target. The private query
does not independently test Disabled or ShowMe.

MUIA_ExportID

Function

Declared in area.h but not implemented by Area.

Inputs

ULONG; declared under MUI_OBSOLETE.

Notes

There is no corresponding constructor, setter or getter case. Tags can
still participate in Notify delivery. Export and Import use the
inherited ObjectID attribute instead; ExportID is not an alias here.

MUIA_FillArea

Function

Choose whether Area drawing fills the content region as well as the
frame surroundings. Default TRUE. FALSE limits ordinary background
rectangles to the area outside the inner box.

Inputs

BOOL; initialize and set.

Notes

There is no getter and the setter does not itself request redraw.
Rounded-frame preparation can first paint the parent background over the
frame area even when FillArea is FALSE. This flag does not suppress the
frame/title.

MUIA_FixHeight

Function

Request a fixed content height. During final min/max processing, a
positive stored value plus frame/spacing is clamped to the limits
already computed and assigned to minimum, default and maximum.

Inputs

LONG stored in WORD; initialize only.

Notes

Nonpositive stored values do not take the fixed-size branch. The field
is shared with MaxHeight; supplying both tags leaves both flags set and
the last numeric value stored. Positive fixed size takes precedence over
text sizing, then maximum size. No setter or getter is implemented.

MUIA_FixHeightTxt

Function

Borrow a NUL-terminated text string whose measured height plus

frame/spacing is used as a fixed dimension, clamped to existing limits.

Inputs

STRPTR; initialize only.

Notes

The string is parsed and measured during final min/max processing. Keep
it alive while the object can be laid out. A positive FixHeight takes
precedence. Failure to create the temporary text object leaves that
dimension unchanged and is not reported; the MaxHeight branch is not
then retried.

MUIA_FixWidth

Function

Request a fixed content width. During final min/max processing, a
positive stored value plus frame/spacing is clamped to the limits
already computed and assigned to minimum, default and maximum.

Inputs

LONG stored in WORD; initialize only.

Notes

Nonpositive stored values do not take the fixed-size branch. The field
is shared with MaxWidth; supplying both tags leaves both flags set and
the last numeric value stored. Positive fixed size takes precedence over
text sizing, then maximum size. No setter or getter is implemented.

MUIA_FixWidthTxt

Function

Borrow a NUL-terminated text string whose measured width plus

frame/spacing is used as a fixed dimension, clamped to existing limits.

Inputs

STRPTR; initialize only.

Notes

The string is parsed and measured during final min/max processing. Keep
it alive while the object can be laid out. A positive FixWidth takes
precedence. Failure to create the temporary text object leaves that
dimension unchanged and is not reported; the MaxWidth branch is not then
retried.

MUIA_Font

Function

Store the font request, default MUIV_Font_Inherit (zero). Setup resolves
inherited parent font, or the normal window font for a root, or the
supplied preset/pointer.

Inputs

IPTR font preset or borrowed TextFont pointer; initialize, get; setter

also implemented.

Notes

The getter returns the request, not the resolved TextFont. Cached preset
fonts belong to Window RenderInfo. Supplied font pointers remain
borrowed. The setter only updates the request and does not re-resolve
the live drawing font or relayout.

MUIA_Frame

Function

Store the requested frame, initially MUIV_Frame_None. Values greater
than 100 are treated as pointers to frame-specification strings; other
values index the preference frame array. Failed string parsing falls
back to the None frame.

Inputs

IPTR frame preset or borrowed specification string; initialize; setter

and getter also implemented.

Notes

Keep a string alive while the object uses it. Setup removes a nonzero
frame and its title from the Window root object. The getter returns the
stored request. The setter recomputes inner/title sizes when global
information exists, but does not request layout or redraw.

Bugs

There is no numeric bounds check: use declared valid frame presets, not
arbitrary values up to 100. With a title, size recomputation uses
RenderInfo-dependent font lookup, so connection alone is not a
sufficient lifecycle guarantee for a runtime setter.

MUIA_FramePhantomHoriz

Function

The presence of this tag enables phantom-frame handling, even when its

value is FALSE. The flag is initially clear.

Inputs

BOOL tag; initialize only.

Notes

Horizontal frame/spacing contributions are forced to zero, and drawing
suppresses the entire frame and title. Vertical contributions remain.
There is no setter or getter; this implementation is broader than merely
hiding horizontal borders.

MUIA_FrameTitle

Function

Borrow a NUL-terminated frame-title string, initially NULL. Setup
computes title spacing from the title font and preferences; drawing
centers and fits the title.

Inputs

STRPTR; initialize only.

Notes

Keep it alive through setup and drawing. Setup clears the title when
removing a nonzero root-object frame. There is no setter or getter.
Font-derived title dimensions are stored in BYTE fields without general
overflow validation.

MUIA_Height

Function

Return height from the object layout box. Coordinates are relative to
the native window origin, including border offsets established by
layout, not to the parent object.

Inputs

LONG geometry value; get only.

Notes

Values describe the full object rectangle including frame and inner
spacing. Right and bottom are inclusive. Meaningful geometry requires
completed layout; the getter does not force layout or test visibility.

MUIA_HorizDisappear

Function

Declared in area.h but not implemented by Area.

Inputs

LONG; declared initialize, set, get.

Notes

There is no corresponding constructor, setter or getter case. Tags can
still participate in Notify delivery. The declaration does not establish
this capability.

MUIA_HorizWeight

Function

Store relative horizontal layout weight, default 100.

Inputs

WORD declaration, stored as UWORD; initialize, set, get.

Notes

Area stores the value without range validation or immediate relayout.
The parent layout implementation determines how it distributes space.
Conversion to UWORD can wrap negative or oversized values.

MUIA_InnerBottom

Function

Set explicit bottom inner spacing, clamped to 0 through 32 during
construction. Otherwise setup obtains the value from the frame
preferences; Window can supply root spacing.

Inputs

LONG; initialize and get.

Notes

The getter returns the stored spacing, excluding the frame border and
title additions. There is no setter. Explicit zero differs from omitting
the tag because it prevents default spacing replacement.

MUIA_InnerLeft

Function

Set explicit left inner spacing, clamped to 0 through 32 during
construction. Otherwise setup obtains the value from the frame
preferences; Window can supply root spacing.

Inputs

LONG; initialize and get.

Notes

The getter returns the stored spacing, excluding the frame border and
title additions. There is no setter. Explicit zero differs from omitting
the tag because it prevents default spacing replacement.

MUIA_InnerRight

Function

Set explicit right inner spacing, clamped to 0 through 32 during
construction. Otherwise setup obtains the value from the frame
preferences; Window can supply root spacing.

Inputs

LONG; initialize and get.

Notes

The getter returns the stored spacing, excluding the frame border and
title additions. There is no setter. Explicit zero differs from omitting
the tag because it prevents default spacing replacement.

MUIA_InnerTop

Function

Set explicit top inner spacing, clamped to 0 through 32 during
construction. Otherwise setup obtains the value from the frame
preferences; Window can supply root spacing.

Inputs

LONG; initialize and get.

Notes

The getter returns the stored spacing, excluding the frame border and
title additions. There is no setter. Explicit zero differs from omitting
the tag because it prevents default spacing replacement.

MUIA_InputMode

Function

Select None, RelVerify, Immediate or Toggle; default None. RelVerify
sets Selected and Pressed on press, repeats Timer, and verifies release
while selected. Immediate forces a Selected notification on press.
Toggle flips Selected and Pressed on the default mouse-press path.

Inputs

LONG stored in BYTE; initialize; setter also implemented.

Notes

The MUIKEY_TOGGLE path changes only Selected. RelVerify construction
clears an initial Selected value. There is no getter. Changing mode
after setup does not rebuild handlers, shortcut action or
selected-background resources; configure the mode before setup.

Bugs

Cleanup tests the current mode when freeing selected-background
resources, so changing it after setup can bypass a required cleanup. The
BYTE value is not validated against the defined modes.

MUIA_LeftEdge

Function

Return left from the object layout box. Coordinates are relative to the
native window origin, including border offsets established by layout,
not to the parent object.

Inputs

LONG geometry value; get only.

Notes

Values describe the full object rectangle including frame and inner
spacing. Right and bottom are inclusive. Meaningful geometry requires
completed layout; the getter does not force layout or test visibility.

MUIA_MaxHeight

Function

Limit maximum content height by adding frame/spacing and clamping to the

previously computed min/max range.

Inputs

LONG stored in WORD; initialize only.

Notes

The fixed positive and text-size branches take precedence. The numeric
field is shared with FixHeight. No getter, setter or immediate resize is
implemented. This branch changes only the maximum, not the default
value.

MUIA_MaxWidth

Function

Limit maximum content width by adding frame/spacing and clamping to the

previously computed min/max range.

Inputs

LONG stored in WORD; initialize only.

Notes

The fixed positive and text-size branches take precedence. The numeric
field is shared with FixWidth. No getter, setter or immediate resize is
implemented. This branch changes only the maximum, not the default
value.

MUIA_NestedDisabled

Function

A nonzero setter increments the low 31-bit disable count; zero
decrements a positive count. The getter reports whether this count is
nonzero, excluding the independent Disabled flag.

Inputs

BOOL operation; initialize, set, get.

Notes

Initially zero. Construction treats any true initialization tag as
setting count bit zero, not as repeated increments. Balance runtime
increments and decrements. Combined zero/nonzero transitions release
input with cancellation and request redraw.

Bugs

The count wraps through masking at 31 bits; there is no overflow error.
A notification carries the requested Boolean, not the count or combined
Disabled state.

MUIA_Pressed

Function

Return or set the pressed flag, initially FALSE. The input handlers use

it for press/release notifications.

Inputs

BOOL; get; setter also implemented.

Notes

Construction ignores this tag. In RelVerify, a verified release clears
Pressed with notification only if Selected is still true. Cancellation
clears it without notification in that selected branch. If Selected was
cleared when the pointer left, the release helper can leave Pressed
true. Do not equate this field unconditionally with the physical button
state.

MUIA_RightEdge

Function

Return left + width - 1 from the object layout box. Coordinates are
relative to the native window origin, including border offsets
established by layout, not to the parent object.

Inputs

LONG geometry value; get only.

Notes

Values describe the full object rectangle including frame and inner
spacing. Right and bottom are inclusive. Meaningful geometry requires
completed layout; the getter does not force layout or test visibility.

MUIA_Selected

Function

Store selection state, initially FALSE. A changed setter requests
complete object redraw. An unchanged setter changes its TagItem to
TAG_IGNORE, suppressing that notification.

Inputs

BOOL; initialize, set, get.

Notes

RelVerify construction forces FALSE despite an initialization tag. A
runtime setter is not restricted by InputMode. Immediate input silently
clears an already selected state before setting TRUE so a new press can
notify. Export/Import serializes this state under ObjectID.

MUIA_ShortHelp

Function

Store a borrowed NUL-terminated help string, initially NULL.

CreateShortHelp returns it unchanged.

Inputs

STRPTR; initialize, set, get.

Notes

Keep it alive until any bubble using it is deleted. The default Window
help search requires a non-NULL stored ShortHelp before selecting this
object, even with an overridden CreateShortHelp. Setting a new pointer
does not close an existing bubble.

MUIA_ShowMe

Function

Store whether the object should be shown; default TRUE. A changed FALSE
setter hides a drawable object. A changed TRUE setter shows it when its
parent is drawable. When this changes live display, request Window
relayout.

Inputs

BOOL; initialize, set, get.

Notes

This setter changes show/hide state, not setup/cleanup state: the
cleanup/setup code in that branch is disabled. Parent container layout
determines participation. An object without a parent has no implemented
immediate show branch. The getter is the requested flag, not proof of
CANDRAW or an open window.

MUIA_ShowSelState

Function

Enable selected background and frame-state inversion; default TRUE.

Inputs

BOOL; initialize only.

Notes

Selected background is prepared during setup only when InputMode is not
None. This flag changes presentation, not Selected or Pressed semantics.
No setter or getter is implemented.

MUIA_Timer

Function

Return the repeat counter used by RelVerify input. The press path
increments it immediately, requests a 300 ms first timer, then the timer
method re-registers at 50 ms and increments only while Selected.

Inputs

ULONG stored notification counter; get; setter also implemented.

Notes

This is not a configurable timer interval. A mouse press first resets
the counter without notification; the keyboard path does not perform
that reset. Release, drag start and cleanup remove an active timer.
Setting Timer only changes the counter and passes the tag to Notify;
construction ignores it. Timer registration failure is not reported
here.

MUIA_TopEdge

Function

Return top from the object layout box. Coordinates are relative to the
native window origin, including border offsets established by layout,
not to the parent object.

Inputs

LONG geometry value; get only.

Notes

Values describe the full object rectangle including frame and inner
spacing. Right and bottom are inclusive. Meaningful geometry requires
completed layout; the getter does not force layout or test visibility.

MUIA_VertDisappear

Function

Declared in area.h but not implemented by Area.

Inputs

LONG; declared initialize, set, get.

Notes

There is no corresponding constructor, setter or getter case. Tags can
still participate in Notify delivery. The declaration does not establish
this capability.

MUIA_VertWeight

Function

Store relative vertical layout weight, default 100.

Inputs

WORD declaration, stored as UWORD; initialize, set, get.

Notes

Area stores the value without range validation or immediate relayout.
The parent layout implementation determines how it distributes space.
Conversion to UWORD can wrap negative or oversized values.

MUIA_Weight

Function

Set both horizontal and vertical weights to the same value. Each

defaults to 100.

Inputs

WORD declaration, stored as UWORD; initialize only.

Notes

There is no combined getter or setter. Use HorizWeight and VertWeight
for runtime access. Initialization tag order determines the final values
when combined with those tags.

MUIA_Width

Function

Return width from the object layout box. Coordinates are relative to the
native window origin, including border offsets established by layout,
not to the parent object.

Inputs

LONG geometry value; get only.

Notes

Values describe the full object rectangle including frame and inner
spacing. Right and bottom are inclusive. Meaningful geometry requires
completed layout; the getter does not force layout or test visibility.

MUIA_Window

Function

Return the native window from RenderInfo, or NULL when RenderInfo is

absent.

Inputs

Intuition Window pointer; get only.

Notes

The pointer is borrowed. Setup establishes RenderInfo and Cleanup clears
it. The native window may still be NULL during setup and becomes invalid
at close; do not close it yourself.

MUIA_WindowObject

Function

Return the owning Window object from RenderInfo, or NULL when RenderInfo

is absent.

Inputs

Zune Window object pointer; get only.

Notes

The pointer is borrowed. Setup establishes RenderInfo and Cleanup clears

it. This does not transfer ownership or prove the native window is open.

MUIC_Area

Superclass

Notify.mui

Description

Provide the base visual-object implementation for layout limits,
frame/background drawing, input state, context menus, help and
drag-and-drop. Area itself does not own or traverse child objects and
contributes only frame/spacing dimensions. Subclasses add content and
container behavior.
Construction calls Notify, initializes weights to 100 and enables
FillArea, ShowMe, ShowSelState and Dropable. InputMode defaults to None.
A superclass construction failure returns NULL; local background-copy
failure does not fail construction.
The object owns its duplicated background specification and setup image
resources. It borrows frame/help/size strings, font pointers,
context-menu objects and Window RenderInfo. Keep borrowed resources
alive while used. Dispose only after hiding and cleanup have ended
drawing, timers and event registration. OM_DISPOSE frees the background
specification but does not perform Hide or Cleanup.

Methods

Setup establishes environment resources; AskMinMax establishes size
limits; layout precedes Show and drawing. Hide precedes Cleanup. Zune's
support wrappers install RenderInfo before Setup, set CANDRAW after
successful Show and clear CANDRAW before Hide. Calling Show or Hide
directly does not reproduce those wrapper state changes.
For custom subclasses, preserve superclass lifecycle calls and unwind
resources on failure. Process ordinary object operations in the
application's task. Notifications and methods are synchronous; keep the
object and callback targets alive throughout calls.
Export stores one byte for Selected under a nonzero ObjectID. Import
reads the first byte of the corresponding Dataspace entry and sets
Selected. Both return zero and ignore underlying failure; Import does
not check the entry length. No other Area state is exported.

Notes

Attribute access below describes actual implementation, including
implemented accesses absent from header comments. A setter may rewrite
its writable TagItems to TAG_IGNORE before forwarding to Notify. A
notification or setter return does not prove resource allocation or
layout success.
Five methods marked PRIV in area.h remain internal source contracts and
are excluded from the public index. Layout, DragQuery, DragDrop and
DragReport have explicit dispatcher defaults, not missing
implementations. CustomBackfill has no dispatcher case.

Bugs

InputMode and ContextMenu setters do not rebuild setup-time event
registration or selected-background resources. Do not assume that
changing them while set up produces the same state as constructing with
those values. QueryFrameCharacteristics has no defined success return;
CreateFrameClippingRegion writes its output into the method message
itself. See their individual contracts.

MUIM_AskMinMax

Synopsis

IPTR result = DoMethod(obj, MUIM_AskMinMax, (IPTR)MinMaxInfo);

Function

Recompute frame/title/inner offsets and overwrite all six

min/max/default fields with the frame-and-spacing contribution.

Inputs

MinMaxInfo - Non-NULL writable MUI_MinMax. Requires valid setup

environment and frame preferences.

Result

Always TRUE.

Notes

Custom classes call the superclass and add their content requirements.
Area itself has no flexible content dimensions. Fixed/text/maximum
constraints are applied afterward by the private finalization helper
used by layout callers; this method alone does not apply them.

MUIM_Cleanup

Synopsis

IPTR result = DoMethod(obj, MUIM_Cleanup);

Function

Unregister shortcuts, timer and event handlers, clear window focus if

this is active, clean prepared backgrounds and clear RenderInfo.

Inputs

No arguments beyond MethodID. Match successful Setup after Hide and

after dependent subclass resources have been released.

Result

Always TRUE.

Notes

The method does not dispose the object, its context-menu object,
borrowed strings or supplied fonts. It is not idempotent: registration
fields can remain nonzero after removal. Keep the owning
Window/application alive throughout cleanup.

Bugs

Selected-background cleanup depends on current InputMode, not on whether
it was allocated. Changing that mode during setup can leave a resource
unreleased.

MUIM_ContextMenuBuild

Synopsis

IPTR result = DoMethod(obj, MUIM_ContextMenuBuild, mx, my);

Function

Return the currently stored ContextMenu pointer unchanged.

Inputs

mx, my - LONG mouse coordinates in the window; ignored by the base

implementation.

Result

Borrowed menu object or NULL.

Notes

Custom classes can override this to choose a menu dynamically. Keep the
result and its items alive throughout display. The default event path
connects it to this Area but does not dispose or later explicitly
disconnect it.

MUIM_ContextMenuChoice

Synopsis

IPTR result = DoMethod(obj, MUIM_ContextMenuChoice, (IPTR)item);

Function

Set ContextMenuTrigger to the selected item for synchronous

notification.

Inputs

item - Borrowed selected menu-item object.

Result

Always zero; setter results are ignored.

Notes

No item pointer is stored by Area and there is no ContextMenuTrigger
getter. The native menu is still being processed by the caller; do not
destroy involved objects during the callback.

MUIM_CreateBubble

Synopsis

IPTR result = DoMethod(obj, MUIM_CreateBubble, x, y, (IPTR)txt, flags);

Function

Create and display a nonactivating borderless help window on the
object's screen. NULL text requests CreateShortHelp; other text is
borrowed directly.

Inputs

x, y - LONG coordinates relative to the native window origin. Intuition
may auto-adjust the bubble position.
txt - Readable NUL-terminated string or NULL.
flags - ULONG; currently ignored by the bubble engine, including
DontHidePointer.

Result

Opaque bubble handle, or NULL when not drawable, text is absent, or a

checked allocation/opening step fails.

Notes

Keep the source object, display environment and text alive until
DeleteBubble. Delete using the same source object. If CreateShortHelp
supplied text, deletion calls DeleteShortHelp; explicit text is not
freed. Later creation failures unwind acquired resources and can call
DeleteShortHelp before returning NULL.

MUIM_CreateDragImage

Synopsis

IPTR result = DoMethod(obj, MUIM_CreateDragImage, touchx, touchy,
flags);

Function

Allocate a MUI_DragImage and bitmap, copy the displayed object pixels,

and draw the configured drag frame around them.

Inputs

touchx, touchy - LONG click offsets, stored in WORD fields without
adding drag-frame borders.
flags - ULONG input, ignored; returned flags are zero. Requires live
display pixels, screen, RenderInfo and frame preferences.

Result

Owned MUI_DragImage pointer or NULL when the structure allocation fails.

The returned structure can have bm=NULL when bitmap allocation fails.

Notes

Release with DeleteDragImage on the same source. The image width/height
include drag-frame borders and are stored in WORD fields. The method
temporarily replaces the shared RenderInfo RastPort while drawing the
frame, then restores it.

Bugs

A non-NULL structure is not proof of a usable bitmap. No range/overflow
checks are made for dimensions or touch offsets; pointer offsets are not
adjusted for the newly added border. The source pixels are copied, not
rerendered.

MUIM_CreateFrameClippingRegion

Synopsis

IPTR result = DoMethodA(obj, (Msg)&message);

Function

For a set-up object with rounded frame corners, allocate a region for
the supplied rectangle and replace the message's clipinfo field with its
pointer. For a nonrounded frame, leave clipinfo unchanged.

Inputs

message - Writable MUIP_CreateFrameClippingRegion with MethodID, LONG
left/top/width/height and a non-NULL initial clipinfo pointer. The
initial pointer is tested but not read or freed. Nonpositive
rounded-region dimensions fail allocation in the helper.

Result

FALSE for NULL initial clipinfo, missing setup, failed characteristic

query or failed rounded-region creation; otherwise TRUE.

Notes

The output is the field in the caller's method message, not memory
addressed by the initial Region pointer. DoMethodA with a retained
message is needed to observe that replacement. A newly returned Region
is caller-owned and must be disposed when no longer used; the previous
region remains caller-owned too.

Bugs

Ordinary DoMethod arguments do not expose the replaced field to the
caller. NULL cannot be used as a normal output initializer because it is
rejected. TRUE for a nonrounded frame does not mean a region was created
or filled.

MUIM_CreateShortHelp

Synopsis

IPTR result = DoMethod(obj, MUIM_CreateShortHelp, mx, my);

Function

Return the stored ShortHelp string unchanged.

Inputs

mx, my - LONG window-relative pointer coordinates; ignored by Area.

Result

Borrowed STRPTR or NULL.

Notes

The base implementation allocates nothing. An overriding implementation
may provide text whose lifetime is paired with DeleteShortHelp. Default
Window bubble discovery requires a non-NULL ShortHelp attribute before
it calls the bubble path.

MUIM_CustomBackfill

Synopsis

IPTR result = DoMethod(obj, MUIM_CustomBackfill, left, top, right,
bottom, xoffset, yoffset);

Function

Declared but not implemented by the Area dispatcher or invoked by its

default drawing path.

Inputs

left, top, right, bottom, xoffset, yoffset - LONG fields declared by

MUIP_CustomBackfill; not consumed by Area.

Result

The inherited unhandled-method result is zero.

Notes

MUIA_CustomBackfill also has no Area implementation. The declaration

alone does not establish a custom-backfill capability.

MUIM_DeleteBubble

Synopsis

IPTR result = DoMethod(obj, MUIM_DeleteBubble, (IPTR)bubble);

Function

Close and release the bubble window, shape region and parsed text, then
release its handle. Call DeleteShortHelp only when creation obtained
text through that method.

Inputs

bubble - Handle returned by CreateBubble on this object, or NULL.

Result

Always TRUE; NULL is accepted.

Notes

A non-NULL handle must be deleted exactly once. Explicitly supplied text
remains caller-owned. Keep the source object alive for a possible
DeleteShortHelp callback.

MUIM_DeleteDragImage

Synopsis

IPTR result = DoMethod(obj, MUIM_DeleteDragImage, (IPTR)di);

Function

Free the drag image bitmap if present, then the MUI_DragImage

allocation.

Inputs

di - Owned result of this implementation's CreateDragImage, or NULL.

Result

Always zero.

Notes

Delete exactly once. A subclass with different image ownership must

provide a matching deletion implementation. A NULL bitmap is accepted.

MUIM_DeleteShortHelp

Synopsis

IPTR result = DoMethod(obj, MUIM_DeleteShortHelp, (IPTR)help);

Function

Perform no operation for Area's borrowed ShortHelp string.

Inputs

help - Text returned by CreateShortHelp; unused here.

Result

Always TRUE.

Notes

Override together with CreateShortHelp if the custom implementation
allocates text. Do not free caller-owned text merely because the base
deletion method was invoked.

MUIM_DoDrag

Synopsis

IPTR result = DoMethod(obj, MUIM_DoDrag, touchx, touchy, flags);

Function

Request Window's internal drag operation for this object.

Inputs

touchx, touchy - LONG click offsets from the object's left/top. The
value 0x80000000 independently selects current native mouse coordinate
minus the corresponding object edge.
flags - ULONG forwarded to drag-image creation.

Result

Always zero, ignoring whether Window started the drag.

Notes

Custom-class operation requiring a live open Window and render
environment. It does not check Draggable, start a new event loop or
provide a completion result. Do not start a second drag while one is
active.

MUIM_DragBegin

Synopsis

IPTR result = DoMethod(obj, MUIM_DragBegin, (IPTR)obj);

Function

Draw the drop-target outline using the object's current bounds.

Inputs

obj - Borrowed drag source; unused by the Area implementation. Requires

live display resources when drawable.

Result

Always zero.

Notes

This marks the target visually and does not transfer ownership or
perform a drop. The drawing helper skips undrawable objects and direct
Window children.

MUIM_DragDrop

Synopsis

IPTR result = DoMethod(obj, MUIM_DragDrop, (IPTR)obj, x, y);

Function

Perform no drop action in the Area dispatcher default.

Inputs

obj - Borrowed source object.
x, y - LONG destination-window coordinates. All arguments are unused by
Area.

Result

Always FALSE.

Notes

A target subclass must implement the transfer it accepts. No source

ownership, data copy or object deletion occurs here.

MUIM_DragFinish

Synopsis

IPTR result = DoMethod(obj, MUIM_DragFinish, (IPTR)obj);

Function

Erase the drop-target outline using the object's current bounds.

Inputs

obj - Borrowed drag source; unused by the Area implementation. Requires

live display resources when drawable.

Result

Always zero.

Notes

This marks the target visually and does not transfer ownership or
perform a drop. Erasure redraws the edge under a temporary clip region
when allocation succeeds; without it the redraw is broader.

MUIM_DragQuery

Synopsis

IPTR result = DoMethod(obj, MUIM_DragQuery, (IPTR)obj);

Function

Refuse a potential drag source in the Area dispatcher default.

Inputs

obj - Borrowed source object; not inspected by Area.

Result

Always MUIV_DragQuery_Refuse.

Notes

A drop-target subclass must override this to accept supported sources.
Dropable and hit testing are performed by the private extended query,
not by this default.

MUIM_DragReport

Synopsis

IPTR result = DoMethod(obj, MUIM_DragReport, (IPTR)obj, x, y, update);

Function

Continue tracking in the Area dispatcher default without examining the

source or pointer position.

Inputs

obj - Borrowed source.
x, y - LONG destination-window coordinates.
update - LONG redraw/update request; ignored by Area.

Result

Always MUIV_DragReport_Continue.

Notes

Custom targets may return Abort, Continue or Refresh as appropriate.
Window's drag loop currently treats Lock as unimplemented and makes no
locking guarantee. It may call DragReport twice in one mouse-move cycle.

MUIM_Draw

Synopsis

IPTR result = DoMethod(obj, MUIM_Draw, flags);

Function

Consume the instance drawing flags, promote DRAWALL to DRAWOBJECT, write
the resulting flags into the method message and clear the stored drawing
flags. If DRAWOBJECT is set, draw background, frame and title.

Inputs

flags - Writable message field; its incoming value is replaced with the
instance flags established by MUI_Redraw. Requires drawable setup state,
a valid RastPort and layout.

Result

Zero when DRAWOBJECT is absent; TRUE after background/frame processing.

Notes

Custom subclasses call the superclass and inspect the updated message
flags to draw content. DRAWUPDATE alone leaves background/frame drawing
to the subclass. Use MUI_Redraw to initiate drawing; a direct message
with flags alone does not establish the instance flags. Drawing can
change RastPort state. Area temporarily selects the title font, then
restores the object font.

Bugs

There is no CANDRAW guard in this method itself. The rounded-background
branch calls DisposeRegion after MUI_AddClipRegion reports failure,
although that function already frees the supplied region. This can free
the region twice. The return value is not a rendering-success guarantee.

MUIM_DrawBackground

Synopsis

IPTR result = DoMethod(obj, MUIM_DrawBackground, left, top, width,
height, xoffset, yoffset, flags);

Function

Draw a prepared background or delegate to DrawParentBackground when none
exists. With a custom frame, alpha characteristics control background
drawing and the frame is drawn for the requested region.

Inputs

left, top - Window coordinates of the requested rectangle.
width, height - Rectangle dimensions.
xoffset, yoffset - Background alignment coordinates passed to the
drawing helper.
flags - State flags passed by drawing callers; no ownership is
transferred.

Result

FALSE when not drawable; otherwise TRUE or the delegated result.

Notes

Requires live show/setup resources and usable geometry.
Selected-background choice tests the supplied flags and prepared
selected image; custom-frame state also uses the object's current
selection. These are not just the public DRAWOBJECT/DRAWUPDATE flags. No
image or frame ownership is returned.

MUIM_DrawParentBackground

Synopsis

IPTR result = DoMethod(obj, MUIM_DrawParentBackground, left, top, width,
height, xoffset, yoffset, flags);

Function

Forward the rectangle to the parent's DrawBackground, or to the owning

Window background when no parent exists.

Inputs

left, top - Window coordinates of the requested rectangle.
width, height - Rectangle dimensions.
xoffset, yoffset - Background alignment coordinates passed to the
drawing helper.
flags - State flags passed by drawing callers; no ownership is
transferred.

Result

FALSE when not drawable; otherwise TRUE, ignoring the delegated drawing

result.

Notes

The object must retain its live render environment. This draws

background only and does not change parentage or layout.

MUIM_GoActive

Synopsis

IPTR result = DoMethod(obj, MUIM_GoActive);

Function

Draw the keyboard-focus outline when drawable.

Inputs

No arguments beyond MethodID. Require valid display state when drawable.

Result

Always TRUE, including when no outline is drawn.

Notes

This changes visual focus only; Window_ActiveObject manages selection of
the active object. Root/direct-window objects have no default
keyboard-focus outline. Erasing uses parent background drawing.

MUIM_GoInactive

Synopsis

IPTR result = DoMethod(obj, MUIM_GoInactive);

Function

Erase the keyboard-focus outline when drawable.

Inputs

No arguments beyond MethodID. Require valid display state when drawable.

Result

Always TRUE, including when no outline is drawn.

Notes

This changes visual focus only; Window_ActiveObject manages selection of
the active object. Root/direct-window objects have no default
keyboard-focus outline. Erasing uses parent background drawing.

MUIM_HandleEvent

Synopsis

IPTR result = DoMethod(obj, MUIM_HandleEvent, (IPTR)imsg, muikey);

Function

Process input-mode keys, mouse presses/motion, context menus and
matching raw control characters. Return immediately when disabled, or
when InputMode is None and no context menu exists.

Inputs

imsg - Borrowed writable IntuiMessage or NULL for MUI-key delivery.
muikey - LONG MUIKEY value; non-NONE values take precedence over imsg.
Requires a live set-up object and owning Window/application.

Result

MUI_EventHandlerRC_Eat when consumed by the selected path; zero

otherwise.

Notes

Never reply to or retain imsg. Window usually supplies a temporary copy.
The raw-key path temporarily changes Code and restores it; a matched
control key rewrites the method message to imsg=NULL and a press/release
muikey before recursion. Handlers can synchronously send notifications.
The default motion handler returns Eat even when it performs no action.
The raw-key path leaves wheel up/down unconsumed but otherwise can
consume unrelated keys. Shift can cancel a current press.

Bugs

The built-in handlers remove and re-add their own event node while
handling input. This is not a general guarantee that custom callbacks
may change arbitrary registrations safely. Keep objects and application
state alive across all nested notifications.

MUIM_HandleInput

Synopsis

IPTR result = DoMethod(obj, MUIM_HandleInput, (IPTR)imsg, muikey);

Function

Provide a legacy input-handler stub. Area performs no action here; its

default input behavior is in HandleEvent.

Inputs

imsg - Borrowed IntuiMessage pointer, unused by this implementation.

muikey - LONG key value, unused.

Result

Always zero.

Notes

Custom classes can override this method for MUI_RequestIDCMP delivery.
Window's private HandleInput dispatch discards the method result, so
returning Eat here does not stop that Window traversal. Prefer the
registered HandleEvent model for new handlers.

MUIM_Hide

Synopsis

IPTR result = DoMethod(obj, MUIM_Hide);

Function

Hide prepared backgrounds and close a live native context menu.

Inputs

No arguments beyond MethodID. Match Show before Cleanup; display

resources must still exist.

Result

Always TRUE.

Notes

The framework wrapper clears CANDRAW before calling this method. This
method does not clear RenderInfo or free setup resources; Cleanup does
that. The borrowed menu object is not disposed.

MUIM_Layout

Synopsis

IPTR result = DoMethod(obj, MUIM_Layout);

Function

Return the Area dispatcher default without laying out children or

changing geometry.

Inputs

No arguments beyond MethodID.

Result

Always 1.

Notes

Area is not a container. Parents set its box; container subclasses

override Layout for their own children.

MUIM_QueryFrameCharacteristics

Synopsis

IPTR result = DoMethod(obj, MUIM_QueryFrameCharacteristics,
(IPTR)characteristics);

Function

Write border_width, border_radius and has_rounded_corners from the

resolved frame specification.

Inputs

characteristics - Non-NULL writable MUI_FrameCharacteristics. Requires

completed Setup and live preferences.

Result

FALSE when characteristics is NULL or the object is not set up. The

success path has no return statement and therefore no defined result.

Notes

The output describes the specification, not a measurement of rendered

pixels. Keep output storage valid through the synchronous call.

Bugs

Do not branch on a success return from this implementation. This

documented source defect is not repaired by the AutoDoc change.

MUIM_Setup

Synopsis

IPTR result = DoMethod(obj, MUIM_Setup, (IPTR)RenderInfo);

Function

Store the borrowed render environment, resolve frame spacing/font,
prepare backgrounds and register input/shortcut handlers. Mark the
object set up and initialize its repeat-handler descriptor.

Inputs

RenderInfo - Non-NULL live Window render environment with screen,
DrawInfo and application preferences available. Call once for each setup
interval.

Result

Always TRUE in this implementation.

Notes

This custom-class lifecycle method runs before the native window is
shown. The framework wrapper installs RenderInfo before entering
subclass Setup. Call the superclass before using its resources; if later
subclass setup fails, unwind completed work. No geometry-dependent
initialization belongs here.

Bugs

Background/font/handler acquisition is not comprehensively checked. TRUE
is not proof that every optional resource exists. Root objects lose
nonzero frame and title settings during this method.

MUIM_Show

Synopsis

IPTR result = DoMethod(obj, MUIM_Show);

Function

Show prepared background images after the native window is open and

layout is known.

Inputs

No arguments beyond MethodID. Requires completed Setup and valid native

display resources.

Result

Always TRUE.

Notes

This custom-class lifecycle method does not itself set CANDRAW. The
framework wrapper sets that flag after a successful return. Initialize
subclass resources that depend on size/position in this phase.

MUIM_UnknownDropDestination

Synopsis

IPTR result = DoMethod(obj, MUIM_UnknownDropDestination, (IPTR)imsg);

Function

Do nothing when Window reports a released drag without an accepted

target.

Inputs

imsg - Borrowed live IntuiMessage for the release. Area does not inspect

it.

Result

Always zero.

Notes

Override to handle this condition if needed. Do not retain or reply to

the message; the Window drag/event path owns reply handling.