Pendisplay.mui

MUIA_Pendisplay_Pen

Function

Retrieve the graphics pen index.

Inputs

Get only. The result is an integer in IPTR storage, not an object

pointer as annotated in the header.

Notes

Without Reference, Get returns the low 16 bits of the local pen and
reports success. An unavailable pen (-1), including before Setup or
after Cleanup, therefore reads as 65535. It is not a resource handle to
release. With Reference the query is forwarded unchanged. Use only a
valid acquired index with its matching color map; this getter does not
validate availability.

MUIA_Pendisplay_RGBcolor

Function

Copy RGB components into the local specification or retrieve a color

structure.

Inputs

Initialize, set and get, pointer to struct MUI_RGBcolor. Supply a

non-NULL readable structure; each component is a full 32-bit ULONG.

Notes

Input components are formatted as hexadecimal RGB in the local
specification; the input pointer is not retained. With no reference, Get
parses that specification. For an explicit RGB specification it returns
the requested components, even before Setup, not the approximated screen
color. For MUI, color-map or system pens it calls GetRGB32 using the
local pen and render context before checking availability. Do not query
those forms without valid setup and an acquired pen. The parser return
is ignored; malformed specifications have no reliable getter contract. A
successful Get returns a borrowed pointer to internal scratch RGB
storage, overwritten by later queries or color updates and invalid at
disposal. Reference redirects the query.

MUIA_Pendisplay_Reference

Function

Borrow an object as the source of getter values and displayed pen.

Inputs

Initialize, set and get, Object pointer. Default NULL. Use a live

compatible object, without self-reference or reference cycles.

Notes

All getters except Reference itself are forwarded, including inherited
Area getters. The pointer is borrowed and must stay valid. Registration
listens to the referenced Spec and sets this object's local Spec on
every notification; registration failure is ignored, and registration
does not copy the initial value. Constructor tags attempt registration
even for NULL and do not remove earlier registrations when repeated;
supply at most one non-NULL Reference tag at construction. Set removes
the old Spec notifications targeting this object and registers the new
non-NULL reference. Set to NULL while both objects remain alive to
detach. Disposal does not detach automatically. Get returns the
immediate reference, not the end of a chain.

MUIA_Pendisplay_Spec

Function

Copy or retrieve the pen specification.

Inputs

Initialize, set and get, pointer to struct MUI_PenSpec. The structure

contains a 32-byte buffer. Default selects MPEN_TEXT.

Notes

Initialization copies the whole structure and requires non-NULL input.
Set copies a non-NULL structure; NULL leaves the local specification
unchanged and does not alone request a color update. Supply 32 readable
bytes containing a valid terminated AROS pen specification, such as m5,
p3, s3 or rffffffff,00000000,00000000. Set does not validate it. Without
Reference, Get returns a borrowed pointer to the embedded structure,
valid until disposal with contents mutable on later writes; it may be
passed back to Set. With Reference, Get is redirected. RGBcolor and Spec
tags overwrite the same local specification in tag order. No ownership
transfer occurs.

MUIC_Pendisplay

Superclass

Area.mui

Description

Display a color selected by a copied pen specification or by a borrowed
reference object. The default local specification selects MPEN_TEXT; the
local pen starts at -1 and Reference at NULL. Construction returns NULL
on superclass failure. RGBcolor and Spec initialization inputs are
dereferenced and must not be NULL. No local heap allocation holds these
values.
Setup first calls Area and then obtains a local pen only without
Reference. It returns one even if pen acquisition fails, zero on Area
setup failure. Cleanup releases an acquired pen, resets it to -1 and
returns the superclass result. Complete Cleanup before disposal. Dispose
delegates to Area but does not remove reference notifications;
explicitly detach Reference while both objects are alive before either
is disposed.

Methods

AskMinMax adds 3 to both minimum dimensions and 16 to both default
dimensions, assigns both maxima MUI_MAXMAX and returns zero. Draw calls
Area, handles full/update flags, fills the content rectangle and returns
zero. A local -1 pen draws a shadow/background pattern. A referenced pen
is read as an index; Get status is ignored with index initially zero,
and a Pendisplay getter's 65535 failure value does not select the local
-1 pattern path. Use references with compatible screen/color-map
resources.
DragQuery refuses self and accepts a successful Pendisplay_Spec getter,
or an Imagedisplay_Spec string longer than two bytes starting with "2:".
DragDrop prefers Pendisplay_Spec, otherwise passes the image string
after its two-byte prefix to the Spec setter. It returns zero and does
not repeat the query checks. The setter copies a complete MUI_PenSpec,
so the source must provide 32 readable bytes at that address, not just a
short NUL-terminated pen string.

Notes

Local Spec and RGB writes do not modify Reference. With a reference
present they update hidden local state while getters continue to use the
reference. Clearing Reference resumes use of the stored local
specification.
When a recognized color change occurs during setup, Set releases the
local pen, obtains another only without Reference, requests update
drawing and prepends affected-attribute notifications to the original
tags. Pen uses local pen & 0xffff, Spec points to the local structure,
and RGBcolor points to sampled local color only if a local pen was
obtained. Consequently these notifications need not equal redirected
getters. Before setup only the original tags reach the superclass. No
equality suppression, relayout, or separate setter error result is
provided.

MUIM_Pendisplay_SetColormap

Synopsis

IPTR result = DoMethod(obj, MUIM_Pendisplay_SetColormap, colormap);

Function

Select a color-map entry by setting a temporary pen specification.

Inputs

colormap - LONG color-map index valid for the current screen.

Result

Zero in all cases. This is not an acquisition or setter-success

indicator.

Notes

The method formats a stack-local specification and calls the normal Spec
setter, which copies it synchronously. Inputs are not range-checked.
Setup-time pen replacement, redraw and notifications follow Spec
setting. Reference remains attached; these methods change local state,
not the referenced object.

MUIM_Pendisplay_SetMUIPen

Synopsis

IPTR result = DoMethod(obj, MUIM_Pendisplay_SetMUIPen, muipen);

Function

Select a MUI pen by setting a temporary pen specification.

Inputs

muipen - LONG MUI pen selector, such as MPEN_TEXT.

Result

Zero in all cases. This is not an acquisition or setter-success

indicator.

Notes

The method formats a stack-local specification and calls the normal Spec
setter, which copies it synchronously. Inputs are not range-checked.
Setup-time pen replacement, redraw and notifications follow Spec
setting. Reference remains attached; these methods change local state,
not the referenced object.

MUIM_Pendisplay_SetRGB

Synopsis

IPTR result = DoMethod(obj, MUIM_Pendisplay_SetRGB, r, g, b);

Function

Select an explicit RGB color by setting a temporary pen specification.

Inputs

r, g, b - ULONG red, green and blue components, each using the full

32-bit range.

Result

Zero in all cases. This is not an acquisition or setter-success

indicator.

Notes

The method formats a stack-local specification and calls the normal Spec
setter, which copies it synchronously. Inputs are not range-checked.
Setup-time pen replacement, redraw and notifications follow Spec
setting. Reference remains attached; these methods change local state,
not the referenced object.