SettingsWindow.mcc/SettingsWindow.mcc

SettingsWindow.mcc is a subclass of Window.mui that allows you to easily
manage your programs settings. There is a notification mechanism similar to
that of MUI to react on changing settings. A row of buttons and a menu let
the user have the standard save, use, load functions.
The SettingsWindowObject can be created similar to an ordinary WindowObject,
but without menustrip. The object you supply as root object will be put in a
vertical group with a row of buttons (save, use [, test], cancel). The
objects in the SettingsWindow have nothing to do with the settings handling
directly - you must explicitly specify this using MUIM_SettingsWindow_Init.

GO TO CONTENTS

SettingsWindow.mcc/Types

Something about the types you can use with MUIM_SettingsWindow_Init:

SWIT_STANDARD:
Used for "4 bytes" attributes such as BOOL or ULONG, where you can get()
the value directly, not a pointer to it.

SWIT_STRING:
The attribute is a string pointer (e.g. MUIA_String_Contents).

SWIT_STRUCT:
The attribute can be a pointer to a structure or any data with a fixed
size (e.g. MUIA_Pendisplay_Spec).

SWIT_COMPLEX:
The attribute is a pointer to a well defined structure that can contain
pointers to further data that can contain pointers... and so on. Invoking
MUIM_SettungsWindow_Init you must supply a pointer to an array of UWORD
describing this data format for the size parameter.
This array contains exactly one type specified by the following BNF:

type := simple / array / pointer / struct / string

simple := "SWIS_BYTE" / "SWIS_WORD" / "SWIS_LONG" / "SWIS_EVEN"
/ "SWIS_EVEN4" /

array := "SWIS_ARRAY" "," "," type

pointer := "SWIS_POINTER" "," type

struct := "SWIS_STRUCT" "," types "SWIS_END"

string := "SWIS_STRING" "," count

count := "-1" /

types := type "," ftypes

ftypes := types / ""

type - a simple type, an array, a pointer, a structure or a string

simple - one of the simple types byte, word, longword, even address,
address divisible by four or a number of bytes

array - number of elements of the same type

pointer - pointer to a type

struct - structure of various types

string - chain of count (terminated by 0 if -1) characters

Example:

static UWORD testit_des[]=
{
SWIS_STRUCT,
SWIS_POINTER, SWIS_STRING,-1,
SWIS_LONG,
SWIS_LONG,
SWIS_POINTER, SWIS_STRING,-1,
SWIS_END
};

describes a structure like the following:

struct testit
{
STRPTR str1;
ULONG u1;
ULONG u2;
STRPTR str2;
};

SWIT_(N)LISTSTANDARD
The object is a (N)List of "4 byte"-entries.

SWIT_(N)LISTSTRING
The object is a (N)List of string pointers.

SWIT_(N)LISTSTRUCT
The object is a (N)List of pointers to a structure or any data with a
fixed size.

SWIT_(N)LISTCOMPLEX
The object is a (N)List of pointers to rather complex structures (take a
look at SWIT_COMPLEX). Invoking MUIM_SettungsWindow_Init you must supply
a pointer to an array of UWORD describing this data format for the size
parameter.

SWIT_(N)LISTCUSTOM
Similar to SWIT_(N)LISTCOMPLEX, but the lists construct hook doesn't
simply copies the supplied data. That's why instead of
MUIM_(N)List_Insert MUIM_SettingsWindow_CustomInsert is invoked.

GO TO CONTENTS

SettingsWindow.mcc/MUIA_SettingsWindow_Changed

MUIA_SettingsWindow_Changed -- [.SGN], BOOL

This attribute is set to TRUE, whenever the current settings have been
changed. This is quite useful, if you don't like to react on each
modified item, but on a group of items, e.g. dimensions and position
of an open window.

GO TO CONTENTS

SettingsWindow.mcc/MUIA_SettingsWindow_PortDirectly

MUIA_SettingsWindow_PortDirectly -- [.SGN], BOOL

This attribute affects the import/export behaviour.
Set to FALSE the stored settings item values are im-/exported, the
attributes of the objects you gave MUIM_SettingsWindow_Init are used
otherwise (e.g. in MUIM_SettingsWindow_Load and
MUIM_SettingsWindow_SaveAs).

I can't imagine any reason why you should need this attribute.

GO TO CONTENTS

SettingsWindow.mcc/MUIA_SettingsWindow_TestButton

MUIA_SettingsWindow_TestButton -- [I...], BOOL

Enable or disable the "Test" button. Defaults to FALSE.

GO TO CONTENTS

SettingsWindow.mcc/MUIA_SettingsWindow_TestMode

MUIA_SettingsWindow_TestMode -- [.SGN], BOOL

Setting this attribute to TRUE turns on the test mode, changes made
affect the application as long as the settings window stays open.
Setting it to FALSE has no further effect.

Your application does not have to care wether it's in test mode or
not. Since the MUIM_SettingsWindow_Store method is called when
MUIA_SettingsWindow_TestMode is set to TRUE (e.g. when the user hits
the "Test" button), all settings will affect the application the same
way using or saving would do. The only difference is that the
settings window stays open and the user has the ability to cancel
what he has done.

GO TO CONTENTS

SettingsWindow.mcc/MUIM_SettingsWindow_Cancel

MUIM_SettingsWindow_Cancel

SYNOPSIS
DoMethod(obj,MUIM_SettingsWindow_Cancel);

Close the settings window and call MUIM_SettingsWindow_Reset to reset
all attributes concerned.

This method is called when the user hits the "Cancel" button or
selects the window close gadget or the "Quit" menu item. Usually
that's something you don't have to care for.

GO TO CONTENTS

SettingsWindow.mcc/MUIM_SettingsWindow_CustomInsert

MUIM_SettingsWindow_CustomInsert

SYNOPSIS
DoMethod(obj,MUIM_SettingsWindow_CustomInsert,APTR *Entries,
ULONG Count, ULONG Pos);

Within MUIM_SettingsWindow_Reset the settings window object invokes
this method on the concerned object of settings items of type
SWIT_(N)LISTCUSTOM.
You have to implement this method in a subclass, if your list
objects construct hook doesn't simply copies the supplied data.

INPUTS
The parameters are the same as used by MUIM_(N)List_Insert.

NOTE
This method has to return TRUE. This is not important in the current
version, but may become vital for future extensions.

SEE ALSO
MUIM_SettingsWindow_Init

GO TO CONTENTS

SettingsWindow.mcc/MUIM_SettingsWindow_GetItem

MUIM_SettingsWindow_GetItem

SYNOPSIS
DoMethod(obj,MUIM_SettingsWindow_GetItem,ULONG ID, ULONG *Storage);

The function is equivalent to that of OM_GET.

INPUTS
ID - ID of the settings item you want to get.

Storage - pointer to the space where MUIM_SettingsWindow_GetItem
shall store the data.

SEE ALSO
MUIM_SettingsWindow_Init
MUIM_SettingsWindow_Notify
m

GO TO CONTENTS

SettingsWindow.mcc/MUIM_SettingsWindow_KillNotify

MUIM_SettingsWindow_KillNotify

SYNOPSIS
DoMethod(obj,MUIM_SettingsWindow_KillNotify,ULONG TrigID);

The function is equivalent to that of MUIM_KillNotify.

INPUTS
TrigID - ID of the settings item you want to remove a notification
handler from.

SEE ALSO
MUIM_SettingsWindow_KillNotifyObj
MUIM_SettingsWindow_Notify
MUIM_SettingsWindow_Notify

GO TO CONTENTS

SettingsWindow.mcc/MUIM_SettingsWindow_KillNotifyObj

MUIM_SettingsWindow_KillNotifyObj

SYNOPSIS
DoMethod(obj,MUIM_SettingsWindow_KillNotifyObj,ULONG TrigID,
Object *DestObj);

The function is equivalent to that of MUIM_KillNotifyObj.

INPUTS
TrigID - ID of the settings item you want to remove a notification
handler from.

DestObj - the object the notification method should be performed at.

SEE ALSO
MUIM_SettingsWindow_KillNotify
MUIM_SettingsWindow_Notify
MUIM_SettingsWindow_Notify

GO TO CONTENTS

SettingsWindow.mcc/MUIM_SettingsWindow_Init

MUIM_SettingsWindow_Init

SYNOPSIS
DoMethod(obj,MUIM_SettingsWindow_Init,Object *Obj1, ULONG Attr1,
ULONG Type1, ULONG Size1, ULONG ID1, /* ... */);

Initialize the settings window object. You have to define which
attribute of which object of which type, size and id you want to
get managed by your settings window object.
The method calls MUIM_SettingsWindow_Store to get valid values and
after that it tries to load the current settings with
MUIM_SettingsWindow_Load.

INPUTS
Obj1 - pointer to an object that contains the attribute that shall
be managed by this settings window object.

Attr1 - TagID of the attribute, ignored for SWIT_(N)LISTxxx.

Type1 - type of the attribute/object, take a look at the type
section

Size1 - size of the attribute for SWIT_STRING and SWIT_STRUCT;
size of the list entries for SWIT_(N)LISTSTRING and
SWIT_(N)LISTSTRUCT;
pointer to a description array for SWIT_([N]LIST)COMPLEX and
SWIT_(N)LISTCUSTOM;
ignored for SWIT_STANDARD and SWIT_(N)LIST_STANDARD.

ID - ID of the settings item used to access the item via
MUIM_SettingsWindow_SetItem/GetItem/Notify, but it's used to
save the item, too. So don't give another object the same
MUIA_ObjectID.

The parameters for the next settings item follow. There can be as
many items as you want; a NULL object pointer indicates the end of the
array.

SEE ALSO
MUIM_SettingsWindow_GetItem
MUIM_SettingsWindow_Notify
MUIM_SettingsWindow_Notify

GO TO CONTENTS

SettingsWindow.mcc/MUIM_SettingsWindow_LastSaved

MUIM_SettingsWindow_LastSaved

SYNOPSIS
DoMethod(obj,MUIM_SettingsWindow_LastSaved);

Load the last saved settings.

This method is called when the user selects the "Last Saved" menu
item. Usually that's something you don't have to care for.

GO TO CONTENTS

SettingsWindow.mcc/MUIM_SettingsWindow_Load

MUIM_SettingsWindow_Load

SYNOPSIS
DoMethod(obj,MUIM_SettingsWindow_Load);

Pop up an ASL requester where the user can select the settings he wants
to load.

This method is called when the user selects the "Load" menu item.
Usually that's something you don't have to care for.

GO TO CONTENTS

SettingsWindow.mcc/MUIM_SettingsWindow_NNSetItem

MUIM_SettingsWindow_NNSetItem

SYNOPSIS
DoMethod(obj,MUIM_SettingsWindow_NNSetItem,ULONG ID, ULONG Value);

The function is equivalent to that of MUIM_NoNotifySet.

INPUTS
ID - ID of the settings item you want to set.

Value - value to set the item to.

SEE ALSO
MUIM_SettingsWindow_GetItem
MUIM_SettingsWindow_Notify
MUIM_SettingsWindow_Notify

GO TO CONTENTS

SettingsWindow.mcc/MUIM_SettingsWindow_Notify

MUIM_SettingsWindow_Notify

SYNOPSIS
DoMethod(obj,MUIM_SettingsWindow_Notify,ULONG TrigID, ULONG TrigValue,
Object *DestObj, ULONG FollowParams, /* ... */);

The function is equivalent to that of MUIM_Notify.

INPUTS
TrigID - ID of the settings item that triggers the notification.

TrigValue - value that triggers the notification,
MUIV_EveryTime is supported.

DestObj - object on which to perform the notification method,
MUIV_Notify_Self, MUIV_Notify_Window and
MUIV_Notify_Application are supported.

FollowParams - number of the following parameters.

MUIV_TriggerValue and MUIV_NotTriggerValue are supported for the
following parameters.

RESULT
Since it needs to allocate memory, this method can fail. It returns
TRUE if successful, FALSE otherwise.

SEE ALSO
MUIM_SettingsWindow_GetItem
MUIM_SettingsWindow_NNSetItem
MUIM_SettingsWindow_NNSetItem

GO TO CONTENTS

SettingsWindow.mcc/MUIM_SettingsWindow_Reset

MUIM_SettingsWindow_Reset

SYNOPSIS
DoMethod(obj,MUIM_SettingsWindow_Reset);

Set all attributes to the values the settings window object has
stored. This method is called from MUIM_SettingsWindow_Cancel.

Usually you don't need to call it.

GO TO CONTENTS

SettingsWindow.mcc/MUIM_SettingsWindow_Restore

MUIM_SettingsWindow_Restore

SYNOPSIS
DoMethod(obj,MUIM_SettingsWindow_Restore);

Load the last used settings.

This method is called when the user selects the "Restore" menu
item. Usually that's something you don't have to care for.

GO TO CONTENTS

SettingsWindow.mcc/MUIM_SettingsWindow_Save

MUIM_SettingsWindow_Save

SYNOPSIS
DoMethod(obj,MUIM_SettingsWindow_Save);

Save the current settings to "ENVARC:" and call
MUIM_SettingsWindow_Use.

This method is called when the "Save" button was pressed. Usually
that's something you don't have to care for.

GO TO CONTENTS

SettingsWindow.mcc/MUIM_SettingsWindow_SaveAs

MUIM_SettingsWindow_SaveAs

SYNOPSIS
DoMethod(obj,MUIM_SettingsWindow_SaveAs);

Pop up an ASL requester where the user can select a file he wants to
save the current settings as.

This method is called when the user selects the "Save As" menu item.
Usually that's something you don't have to care for.

GO TO CONTENTS

SettingsWindow.mcc/MUIM_SettingsWindow_SetItem

MUIM_SettingsWindow_SetItem

SYNOPSIS
DoMethod(obj,MUIM_SettingsWindow_SetItem,ULONG ID, ULONG Value);

The function is equivalent to that of MUIM_Set.

INPUTS
ID - ID of the settings item you want to set.

Value - value to set the item to.

SEE ALSO
MUIM_SettingsWindow_GetItem
MUIM_SettingsWindow_NNSetItem
MUIM_SettingsWindow_NNSetItem

GO TO CONTENTS

SettingsWindow.mcc/MUIM_SettingsWindow_Store

MUIM_SettingsWindow_Store

SYNOPSIS
DoMethod(obj,MUIM_SettingsWindow_Store);

Get all attributes and store it. This method is called from
MUIM_SettingsWindow_Use.

Usually you don't need to call it.

GO TO CONTENTS

SettingsWindow.mcc/MUIM_SettingsWindow_Use

MUIM_SettingsWindow_Use

SYNOPSIS
DoMethod(obj,MUIM_SettingsWindow_Use);

Call MUIM_SettingsWindow_Store to store the changes, close the
settings window and save the current settings to "ENV:".

This method is called when the user hits the "Use" button. Usually
that's something you don't have to care for.

GO TO CONTENTS