DTFreeImages()
Synopsis
void DTFreeImages(
struct DecorImages *di)
Function
Dispose the images in an independently owned set and free the set.
Notes
Every image field is disposed through decorator.library, then the set
is freed. NULL image fields are accepted; a NULL set pointer is not.
Stop all rendering and release users of its images before calling.
There is no reference count, alias detection or synchronization.
Do not pass the borrowed result of DTGetImages() or a screen instance's
dts_Images. Their owning theme or screen instance releases those sets.
Call once, in task context with decortheme.library open.
DTFreeTheme()
Synopsis
void DTFreeTheme(
struct DecorTheme *theme)
Function
Release a loaded theme and its owned configuration and source images.
Notes
Release every screen instance with DTReleaseScreenTheme() and stop
all rendering and other access before freeing the source theme.
Pointers returned by DTGetConfig(), DTGetImages() and DTGetElement()
become invalid. There is no reference count or synchronization.
Do not separately free the theme's image set or configuration. Call
once for each successful load, in task context with decortheme.library
open. The function does not close a screen or change the system theme.
DTGetConfig()
Synopsis
struct DecorConfig * DTGetConfig(
struct DecorTheme *theme)
Function
Return the configuration owned by a loaded theme.
Result
Borrowed DecorConfig pointer, or NULL when theme is NULL.
Notes
No copy or reference is acquired. Do not free the configuration or its
ThemePath string; both remain owned by the theme. Keep the theme alive
and serialize access with any mutation or destruction.
Changing configuration fields does not rebuild existing images or
element descriptors. The pointer describes the loaded configuration,
not necessarily the currently installed system decoration.
DTGetElement()
Synopsis
struct DecoratorElement * DTGetElement(
struct DecorTheme *theme, ULONG elemid)
Function
Return a source-theme element descriptor by identifier.
Result
Borrowed DecoratorElement pointer, or NULL when theme is NULL or the
identifier is out of range. A valid descriptor may have no usable image.
Notes
The descriptor is stored inside the theme and refers to its source
images. Do not free it. Keep the theme alive and prevent concurrent
mutation or destruction while accessing it.
For screen-matched rendering, use the corresponding dts_Elements entry
of a live DecorThemeScreen instead. Descriptor lookup does not allocate,
render, validate image geometry or acquire a reference.
DTGetImages()
Synopsis
struct DecorImages * DTGetImages(
struct DecorTheme *theme)
Function
Return the source-image set owned by a loaded theme.
Result
Borrowed DecorImages pointer, or NULL when theme is NULL.
Notes
The set contains source images, not screen-matched copies. Individual
image pointers may be NULL; a non-NULL image also has an ok flag.
Neither this call nor the pointer retains the theme.
Do not pass this set to DTFreeImages() or dispose its images separately.
Keep the theme alive while using it and serialize access with changes.
Use DTObtainScreenTheme() for images matched to a target screen.
DTLoadTheme()
Synopsis
struct DecorTheme * DTLoadTheme(
STRPTR path)
Function
Load an independent decoration theme from a directory.
Result
Owned DecorTheme, or NULL if allocation of the theme or image-set
structure fails. A non-NULL result does not establish that all files
were present or that every image is usable.
Notes
The loader reads Menu/Config and System/Config beneath path, then
loads the screen, window and menu images named by the theme layout.
Missing configuration files leave defaults in place; unknown settings
are ignored. Failed image loads leave NULL entries in dt_Images.
Check each required image and its ok flag before relying on it.
The returned theme contains configuration, source images and element
descriptors. It is not installed as the system theme. Independent
loads create independent instances. Free it with DTFreeTheme() after
all screen instances and users of borrowed pointers have finished.
Call from a DOS process with decortheme.library open. File access and
picture decoding are synchronous and have no caller timeout. Relative
paths use the process's current directory. Use a valid, nonzero current
directory lock; configuration loading temporarily changes that state.
Coordinate calls with any other code sharing the same process state.
Configuration values and image dimensions are not comprehensively
validated. Use trusted theme files with valid geometry and image grids.
Bugs
Some configuration and image-loader allocations are unchecked;
out-of-memory conditions can cause invalid memory access instead
of returning NULL. If the original current-directory lock is zero,
the loader can leave the process using a lock it has released.
DTNewDecorImages()
Synopsis
struct DecorImages * DTNewDecorImages(
)
Function
Allocate an empty, independently owned decoration-image set.
Result
Owned DecorImages with all image pointers NULL, or NULL on allocation failure.
Notes
No image data is loaded or allocated. Populate image fields only with
containers owned exclusively by this set and suitable for disposal
through decorator.library/DDisposeImageContainer(). Each non-NULL
container must appear in at most one field and have no other owner.
Free the set with DTFreeImages() when no renderer or element descriptor
uses it. Do not insert borrowed images from a theme or screen instance.
Call in task context with decortheme.library open.
DTObtainScreenTheme()
Synopsis
struct DecorThemeScreen * DTObtainScreenTheme(
struct DecorTheme *theme, struct Screen *scr, BOOL truecolor)
Function
Create a theme instance with image copies matched to a target screen.
Result
Owned DecorThemeScreen, or NULL for a NULL theme or failure to allocate
its outer structure or image set. Individual images can be unusable
even when the instance is returned.
Notes
The instance owns dts_Images and contains descriptors in dts_Elements.
Inspect the required image pointers and their ok flags before use.
The source theme and screen are borrowed, not retained; both must
outlive the instance. Release it with DTReleaseScreenTheme().
Each call creates a separate instance. It does not cache, install or
activate a theme, lock the screen, or update existing instances after
the source configuration changes. Do not replace the theme's image
containers with arbitrary containers lacking their source filenames.
The palette path first tries the image filename with _LUT appended,
then the original file remapped for the screen. The true-color path
copies source pixel data and may create screen-compatible bitmaps.
Relative source filenames still depend on the current directory;
use an absolute path when loading a theme for later remapping.
Call from a DOS process with decortheme.library open. Conversion,
file access and picture decoding are synchronous, with no caller
timeout. Serialize access with theme mutation and screen closure.
Bugs
The image conversion helper has unchecked allocations and can fail
with invalid memory access rather than NULL. On the palette path,
a loaded datatype object can lose its owning pointer when source
pixel data is also present, leaking that object and its resources.
DTReleaseScreenTheme()
Synopsis
void DTReleaseScreenTheme(
struct DecorThemeScreen *dts)
Function
Release a screen-specific theme instance and its owned image copies.
Notes
Stop all rendering and other access first. The image set and every
pointer into dts_Elements become invalid. Do not free dts_Images or
its containers separately.
The source theme is not freed and the screen is not closed. Release
all instances before freeing their source theme or closing their
screens. No reference count, synchronization or display detachment
is performed. Call in task context with decortheme.library open.