Default constructor

Same as MUI_Layout, used to position objects within a -layout:top:width:height:flags: method implementation

see developer documentation. CAUTION: don't call supermethod when implementing this method in your custom class!

You can use this to read the current position and dimension of an object, if you e.g. need it to pop up some requester below.

Of course, this attribute is only valid when the parent window of the object is currently open.

see developer documentation. CAUTION: you MUST call super if you overload this method!

Closes a font object opened with MUIM_OpenCustomFont

Specifies a context sensitive popup menu for the current object. For MUI, popup menus are nothing else but standard menus, so you must specify a pointer to a MUI menustrip object (e.g. something returned from MUI_MakeObject(MUIO_MenustripNM,...)) here.

Whenever the user hits the RMB and the mouse is above the parent object, MUI will present the popup menu instead of the windows menu.

Note: MUI will *not* dispose the MUIA_ContextMenu object when the object is disposed. You must take care of the menustrip object yourself. This is because menustrip objects in MUIA_ContextMenu do not actually "belong" to their parent objects, they're just a "reference". You are allowed to use a single menustrip object as MUIA_ContextMenu for different objects of the same window. Do *not* share with objects in other windows or with the default menu of a window or an application!

If the user selects an item, the object will receive a MUIM_ContextMenuChoice method containing the selected menuitem object. If you build your menustrip tree with MUI_MakeObject(MUIO_MenustripNM,...), you will find the nm_UserData of your menu entry in muiUserData(msg->item). If you have control over methods because you are a subclass, you can immediately take approriate actions when receiving MUIM_ContextMenuChoice.

If you dont have a subclass or dont override MUIM_ContextMenuChoice, the method will finally reach area class and will set the attribute MUIA_ContextMenuTrigger to the appropriate menuitem object. This allows you to react on context menu selections by simple notification and eliminates the need of writing a subclass just for this purpose. Subclasses are always the better solution though!

There is also a possibility to dynamically create popup menus on the fly. See MUIM_ContextMenuBuild for details.

Add context menu items. In the subclass you override this method to add your own context menu item while your superclass can still insert its own items.

This method replaces old MUIM_ContextMenuBuild method.

Allows reacting on context menus in subclasses.

See MUIA_ContextMenu for details.

Allows reacting on context menus with notificaton. When the MUIM_ContextMenuChoice method reaches area class because you did not override it in a subclass, it sets MUIA_ContextMenuTrigger to the received paremeter which is a pointer to the user-selected menuitem object.

See MUIA_ContextMenu for details.

Pressing the control char will have the same effect as pressing return if the object was active.

This can be used to create old style key shortcuts.

Note: Using an uppercase control char will force the user to press shift.

Together with MUIM_DeleteBubble, this method provides an interface for MUIs bubble mechanism. Applications can use bubbles for their own purpose, e.g. for indicating error conditions on certain gadgets.

MUIM_CreateBubble creates a bubble at the specified coordinates with the specified (textual) contents. It returns a bubble "handle" that has to be passed to MUIM_DeleteBubble when the bubble shall disappear.

There's no limitation on the number of bubbles, you can create lots of them at a time if you wish. Also, these custom bubbles are completely independant of MUI's bubble help system and won't disappear automatically when the mouse is moved.

Note that bubbles will only show up when the object in question is visible. Otherwise MUIM_CreateBubble returns NULL. You are responsible for deleting the bubble *before* the object get's invisible. Good place to remove a custom bubble is e.g. the MUIM_Hide method of your object.

Allows dynamic creation of help bubble texts.

When MUI is about to show a help bubble, it does not simply use the MUIA_ShortHelp field of area class. Instead, it sends a MUIM_CreateShortHelp to the object in question and uses the return value as text for the bubble.

When MUIM_CreateShortHelp reaches area class, it just returns the contents of MUIA_ShortHelp, so you needn't care about this method if you only have static, non-changing help bubbles.

However, if your help bubble texts depend on some internal states of your objects or on the mouse position within your objects, you have to create a subclass which overrides MUIM_CreateShortHelp, creates a custom text string and returns it.

You can dynamically allocate memory here. MUI will call the method MUIM_DeleteShortHelp after the bubble has disappeared to give you a chance to free this memory again.

Allows overriding the user-configured MUI fonts. Takes a MUI font spec string as input. The string may contain just the styling information, for example

Noto Sans UI/20 - use Noto Sans UI font, size 20 Noto Sans UI/+10 - use Noto Sans UI font, with size + 10 points from the height of the Normal font /+10 - will use the user-defined Normal font, but with a size + 10 points larger //s - use Normal font, enable shadow //o - enable outline //g - enable glow (caution: slow!) //n - reset styles //u - underline //b - bold //i - italic //crrggbb - set text color to a RGB value //Crrggbb - set text outline color Noto Sans UI/+10/o/Cff0000 - use Noto Sans UI font, with size + 10 points from the height of the Normal font, with a red colored outline

Setting MUIA_Font after MUIA_CustomFont overrides MUIA_CustomFont and vice versa

CAUTION It is not advised to use MUIA_CustomFont, unless the font may be configured by the user or this is used in a fully custom-drawn Area subclass where the background is also controlled by the programmer and won't collide with user settings (think dark background and black text).

MUI 3 introduces a new keyboard cycle chain system. All you have to do is to set MUIA_CycleChain to 1 for every object that you want to have in your chain, MUI does the rest automatically. The old MUIM_Window_SetCycleChain will continue to work but is considered obsolete.

Together with MUIM_CreateBubble, this method provides an interface for MUIs bubble mechanism. Applications can use bubbles for their own purpose, e.g. for indicating error conditions on certain gadgets.

MUIM_DeleteBubble deletes a bubble that was previously created with MUIM_CreateBubble. Not that bubbles have to be deleted before an object get's invisible!

Delete the string that MUIM_CreateShortHelp might have allocated.

MUI will call this method if you returned a custom text in MUIM_CreateShortHelp when the bubble has disappeared.

You can free memory that you allocated for the dynamic bubble text here.

Disable or enable a gadget. Setting this attribute causes a gadget to become disabled, it gets a ghost pattern and doesn't respond to user input any longer.

Disabled gadgets cannot be activated with the TAB key.

Using MUIA_Disable on a group of objects will disable all objects within that group.

This method invokes MUI's drag & drop handling. Normally, MUI takes care about this itself when objects are specified as draggable. However, if you e.g. have a whole group of objects that should be dragged (like a toolbar) and just a small "handle" button to start this operation, you must use this method.

Setting this to TRUE will enable a doublebuffer for this objects MUIM_Draw method.

When MUI is about draw an object with this attribute, it will maintain an extra struct MUI_RenderInfo which points to an offscreen bitmap. Just before calling MUIM_Draw, your objects normal muiRenderInfo(obj) pointer (which stores drawing attributes such as _rp(obj) for example) will be replaced by this buffered MUI_RenderInfo. Also, your object's coordinates (in _mleft(obj), _mtop(obj), etc) will be changed to point into the offscreen buffer.

Your MUIM_Draw method can then render as it would normally, no need to change anything for the doublebuffer. When it is completed, MUI will blit the contents of the offscreen-bitmap into view and then restore your objects coordinates and MUI_RenderInfo pointers to their standard values.

Inform an object that it has become the active destination of a drag&drop action. An object will only receive this if it has responded positively to a previous MUIM_DragQuery.

Indicate that the user dropped something on the current object.

Indicate that an object is no longer the active destination object of a drag&drop action.

MUI offers complete drag & drop capabilities for every object. If enabled, the user is able to grab an object, drag it around and drop it on another object. Currently, D&D is limited to single applications, i.e. you cannot take an object from one program and drop it into another one. D&D between different windows of the same application, however, is fine.

MUI controls the D&D actions with a set of five methods: MUIM_DragQuery, MUIM_DragBegin, MUIM_DragReport, MUIM_DragDrop and MUIM_DragFinish. Basically things work this way:

Lets assume the user has taken an object (called the source object) and is now starting to drag it around. During dragging, MUI will find out which object is currently under the mouse pointer and if it found one, send it the MUIM_DragQuery method. An object that receives MUIM_DragQuery can now determine it it wishes to accept drops from the source object or not. If it responds positively, the object will become the current destination object.

Due to the nature of MUIs layout system, a specific x,y pair of coordinates cannot be bound to a specific object immediately. Instead, the coordinates belong to a whole tree of objects, for example some cycle gadget, its parent group, the parent group of the parent group and so on until the tree reaches the windows root object. To allow complete groups of objects to participate in D&D business, the MUIM_DragQuery is first sent to the deepest nested object (the cycle gadget in the example above). If this one doesn't respond, MUI sends a MUIM_DragQuery to its parent group and so on until it either finds some object which accepts the drop or reaches the end of the tree. If there is an accepting object, it will become the current destination. if there isn't, no destination will be set.

Objects becoming active destinations of a drag process learn about their current state by receiving a MUIM_DragBegin method. This method, when reaching area class, e.g. draws a special frame around the object to indicate the current state to the user.

The opposite of MUIM_DragBegin is MUIM_DragFinish and will be sent as soon as the object stops being destination of the drag process, i.e. because the user aborted the drag or moved out of the bounding box. MUIM_DragFinish will also be sent after a successful drop, you can rely on receiving a MUIM_DragFinish if you received a MUIM_DragBegin before. Furthermore, only one object will be between MUIM_DragBegin and MUIM_DragFinish at any time.

Active destination objects (between MUIM_DragBegin and MUIM_DragFinish) receive MUIM_DragReport methods as long as the user moves the mouse within the object. MUIM_DragReport contains the mouse coordinates, so the object can update its display according to the position of the source object. A listview would e.g. indicate the insert position to give the user an idea where the source would be inserted in case of a drop.

All the methods mentioned above are just interim messages that help visualizing the drag process. When the user actually decides to drop its source object, the current destination object (if any) receives a MUIM_DragDrop method and can perform whatever operation it thinks is suited to handle a D&D action from the source object.

You probably have noticed that D&D is controlled by methods. This means that you need to write subclasses if you intend to use it. However, you needn't implement all the above mentioned things to reach your goal. In fact, MUIM_DragQuery and MUIM_DragDrop are enough for almost all D&D invocations. Here's a little example of how MUI implements D&D between objects of Pendisplay class. These few lines allow the user to take any Pendisplay (or subclasses from Pendisplay like e.g. Poppen class) and drop it onto another one:

ULONG mDragQuery(cl,obj,struct MUIP_DragQuery *msg) { char *spec;

/* refuse to be dropped on ourself */ if (msg->obj==obj) return(MUIV_DragQuery_Refuse);

/* if the source object offers the attribute */ /* we want, show that we would accept it. */ if (get(msg->obj,MUIA_Pendisplay_Spec,&spec)) return(MUIV_DragQuery_Accept);

/* refuse otherwise */ return(MUIV_DragQuery_Refuse); }

ULONG mDragDrop(cl,obj,struct MUIP_DragDrop *msg) { char *spec;

/* copy the attribute from the source object */ get(msg->obj,MUIA_Pendisplay_Spec,&spec); set(obj,MUIA_Pendisplay_Spec,spec);

return(0); }

Interim messages from MOUSEMOVEs and INTUITICKs sent as long as an object is active destination of a drag&drop action.

RESULT Behaviour of the current drag and drop operation can be altered by returning one of the following values:

- MUIV_DragReport_Abort Abort drag and drop operation.

- MUIV_DragReport_Continue Continue drag and drop operation. This is the default return value.

- MUIV_DragReport_Lock Lock the drag and drop operation over the actual target.

- MUIV_DragReport_Refresh Ask MUI to redraw the drag image. This can be usefull if the target object does a visual feedback of the drag and drop operation (ie: MUI_Redraw() is called in MUIM_DragReport)

Set this if you want the complete object to be dragable for D&D operations.

see developer documentation. CAUTION: don't call supermethod when implementing this method in your custom class!

If you decided to use MUIA_FillArea, FALSE for your custom class, i.e. if you care about background rendering yourself, you can use this method to draw a specific part of your objects background with the defined MUIA_Background.

The DrawInfo, associated with the Intuition Screen

Only objects with this attribute set to TRUE will be asked if they want to become an active Drag & Drop destination at all. Though this attribute defaults to TRUE, this doesnt mean that every object automatically aceppts D&D actions, because the MUIM_DragQuery method is answered FALSE when it arrives at area class.

Every MUI object can have its own font, just set it with this tag. Objects without an explicit font setting will inherit it from their parent group.

You normally won't need to open a font yourself, just use one of the predefined values to get a font from the users preferences.

You can also pass a struct TextFont * obtained by OpenFont(). You are responsible for freeing this font yourself after the object is disposed.

This method is invoked whenever one of an event handlers trigger signals arrives. It's described in area class context but does not really belong here.

You can use this to read the current position and dimension of an object, if you e.g. need it to pop up some requester below.

Of course, this attribute is only valid when the parent window of the object is currently open.

see developer documentation.

Objects with a disappear level disappear automatically when their parent window gets too small to display them. Use this for things that make your GUI look nicer (e.g. Imagery) but are not absolutely necessary.

By using disappearing objects, you can make nice GUIs which still work on crappy 640x200 screens.

You can give horizontal or vertical disappear levels to objects which are used for horizontal or vertical layout calculations respectively.

Objects with a small disappear level disappear before objects with a big disappear level.

Adjust the horizontal weight of an object. Usually you can simply use MUIA_Weight instead of this tag but in some two-dimensional groups it may become handy to have different horizontal and vertical weights.

Adjust the space between an object and its frame. Usually you shouldn't use this tag since you will override the users preferred default setting.

Adjust the space between an object and its frame. Usually you shouldn't use this tag since you will override the users preferred default setting.

Adjust the space between an object and its frame. Usually you shouldn't use this tag since you will override the users preferred default setting.

Adjust the space between an object and its frame. Usually you shouldn't use this tag since you will override the users preferred default setting.

Returns YES if the object is currently active (has keyboard focus)

Helper methods for handleEvent

Object's inner rectangle (without the frame)

You can use this to read the current position and dimension of an object, if you e.g. need it to pop up some requester below.

Of course, this attribute is only valid when the parent window of the object is currently open.

Relative to the object

Object's full rectangle (including the frame)

Makes it possible for a Custom Class to render text using other fonts

The font may be opened any time during object's life cycle, but may only be used after MUIM_Setup. Draw with MUIM_Text.

The returned font object is owned by the object and will be automatically released in DISPOSE, unless explicitly closed by MUIM_CloseCustomFont

Learn if a button is pressed (or released). The MUIA_Pressed attribute of a gadget is triggered by some user action, depending on the input mode:

MUIV_InputMode_RelVerify: - set when lmb is pressed. - cleared when lmb is released and the mouse is still over the gadget (otherwise it will be cleared too, but without triggering a notification event).

MUIV_InputMode_Immediate: - undefined, use MUIA_Selected for this.

MUIV_InputMode_Toggle: - undefined, use MUIA_Selected for this.

Waiting for MUIA_Pressed getting FALSE is the usual way to react on button gadgets.

Returns the graphics draw context (RastPort). Only call this from within the draw: method

Same as MUI_Redraw - triggers an object redraw

Returns a renderinfo pointer if the object between Setup & Cleanup or NULL

You can use this to read the current position and dimension of an object, if you e.g. need it to pop up some requester below.

Of course, this attribute is only valid when the parent window of the object is currently open.

Intuition Screen pointer or NULL

Get and set the selected state of a gadget. This attribute can be triggered by the user clicking on the gadget (or using the keyboard), depending on the input mode:

MUIV_InputMode_RelVerify: - set when lmb is pressed. - cleared when lmb is released. - cleared when the gadget is selected and the mouse leaves the gadget box. - set when the mouse reenters the gadget box.

MUIV_InputMode_Immediate: - set when lmb is pressed.

MUIV_InputMode_Toggle: - toggled when lmb is pressed.

Of course you may set this attribute yourself, e.g. to adjust the state of a checkmark gadget.

A selected gadget will display its border reverse and get the configured MUII_SelectedBack background. This can be avoided using the MUIA_ShowSelState tag.

Adjust the background for an object.

Every MUI object has its own background setting. The background is displayed "behind" the actual object contents, e.g. behind a the text of a text object or behind the image of an image object.

This attribute takes the same values as MUIA_Image_Spec, please refer to autodocs of image class for a complete description.

An object without a specific background setting will inherit the pattern from its parent group �. The default background for a window and many other background patterns are adjustable with the preferences program.

Only a few MUII_xxxxxxx tags make sense as background. Important are:

MUII_ButtonBack: You have to set this when you create a button gadget. Thus, your button will be displayed in the users preferred style.

MUII_TextBack: Set this when you create a text object with a TextFrame, e.g. some kind of status line. Do *not* use MUII_TextBack for simple text without frame (e.g. gadget labels).

MUII_BACKGROUND MUII_SHADOW MUII_SHINE MUII_FILL MUII_SHADOWBACK MUII_SHADOWFILL MUII_SHADOWSHINE MUII_FILLBACK MUII_FILLSHINE MUII_SHINEBACK MUII_SHINEBACK2: One of MUI's predefined pattern. These are not configurable by the user and will always look the same.

If set to YES, the object will receive MUIKEYs in handleEvent even if not active, use with caution only if for some reason you cannot use MUIWindows' defaultObject

In GuiMode, MUI will not call your handleEvent:muikey: method if the object is either disabled, invisible or if it's not currently visible while in a virtual group. The rule is not applied to IDCMP_ACTIVEWINDOW, IDCMP_INACTIVEWINDOW, IDCMP_CHANGEWINDOW. GuiMode is ON by DEFAULT !

Set this to FALSE if you are a custom class and dont want area class to clear your background during the DoSuperMethod() in your draw method. Note that if you set this, your draw method is responsible for filling every pixel of your objects rectangle, otherwise some display trash will remain there.

CAUTION: this is an initializer attribute, meaning it cannot be changed after the underlying MUI object is instantiated

CAUTION: this is an initializer attribute, meaning it cannot be changed after the underlying MUI object is instantiated

CAUTION: this is an initializer attribute, meaning it cannot be changed after the underlying MUI object is instantiated

CAUTION: this is an initializer attribute, meaning it cannot be changed after the underlying MUI object is instantiated

CAUTION: this is an initializer attribute, meaning it cannot be changed after the underlying MUI object is instantiated

CAUTION: this is an initializer attribute, meaning it cannot be changed after the underlying MUI object is instantiated

CAUTION: this is an initializer attribute, meaning it cannot be changed after the underlying MUI object is instantiated

Setting this property will make your custom class register for events from the MUIWindow the object belongs to. The property can be set at any time during the object's life cycle, the rest is handled under the hood. You must overload handleEvent:muikey: if you set this attribute to a non-zero value.

CAUTION: this is an initializer attribute, meaning it cannot be changed after the underlying MUI object is instantiated

CAUTION: this is an initializer attribute, meaning it cannot be changed after the underlying MUI object is instantiated

CAUTION: this is an initializer attribute, meaning it cannot be changed after the underlying MUI object is instantiated

CAUTION: this is an initializer attribute, meaning it cannot be changed after the underlying MUI object is instantiated

CAUTION: this is an initializer attribute, meaning it cannot be changed after the underlying MUI object is instantiated

Layouts the object - effectively calls MUI_LayoutObj, only to be used from within a overloaded -layout:top:width:height:flags: method

CAUTION: this is an initializer attribute, meaning it cannot be changed after the underlying MUI object is instantiated

CAUTION: this is an initializer attribute, meaning it cannot be changed after the underlying MUI object is instantiated

CAUTION: this is an initializer attribute, meaning it cannot be changed after the underlying MUI object is instantiated

CAUTION: this is an initializer attribute, meaning it cannot be changed after the underlying MUI object is instantiated

CAUTION: this is an initializer attribute, meaning it cannot be changed after the underlying MUI object is instantiated

see developer documentation. CAUTION: you MUST call super if you overload this method!

Specify a string that is to be used as bubble help for this object.

see developer documentation.

Objects with this attribute set are not displayed. You can set MUIA_ShowMe at any time, causing objects to appear and to disappear immediately. A new layout is calculated whenever some objects are shown or hidden. When necessary, MUI will resize the parent window to make room for the new objects.

This function is a preffered way to render text inside the object. It uses object's font and it's color (if not specified in the string itself).

Expects the string to be UTF-8 if MUIA_Unicode is set.

Returns the 00RRGBB color of the text associated with the object. Valid between MUIM_Setup and MUIM_Cleanup, otherwise returns 0.

To account for prefs changes, it's best not to cache this value and to read it once per MUIM_Draw call.

Use this function to messure area which will be affected by text rendered with MUIM_Text method. It's return value contains two 16bit values: width and height:

width = returnvalue & 0xffff; height = returnvalue >> 16;

Expects the string to be UTF-8 if MUIA_Unicode is set.

MUIA_Timer gets triggered when a relverify button is pressed and (after a little delay) increases every INTUITICK as long as the mouse remains over the gadget.

This makes it possible to have buttons repeatedly cause some actions, just like the arrow gadgets of a scrollbar.

You can use this to read the current position and dimension of an object, if you e.g. need it to pop up some requester below.

Of course, this attribute is only valid when the parent window of the object is currently open.

Setting this to TRUE will treat strings displayed and/or edited by the class as UTF-8.

Depending on user settings, the text will be rendered either using ttengine.library or by converting it back to system codepage at runtime.

The strings returned by MUIA_String_Contents, etc will remain UTF-8 no matter which text rendering is used.

This attribute can only be set at object's creation.

Objects with a disappear level disappear automatically when their parent window gets too small to display them. Use this for things that make your GUI look nicer (e.g. Imagery) but are not absolutely necessary.

By using disappearing objects, you can make nice GUIs which still work on crappy 640x200 screens.

You can give horizontal or vertical disappear levels to objects which are used for horizontal or vertical layout calculations respectively.

Objects with a small disappear level disappear before objects with a big disappear level.

Adjust the vertical weight of an object. Usually you can simply use MUIA_Weight instead of this tag but in some two-dimensional groups it may become handy to have different horizontal and vertical weights.

You can use this to read the current position and dimension of an object, if you e.g. need it to pop up some requester below.

Of course, this attribute is only valid when the parent window of the object is currently open.

This attribute can be used to get a pointer to the intuition window structure of the parent window ot the object. This pointer could e.g. be used in calls to asl.library.

The result is only valid when the window is opened.