Toolbar.mcc/Toolbar.mcc

The toolbar custom class supplies an easy way of implementing a
toolbar in your programs. It features a multitude of different
settings and the majority of these are configurable for the user via
the MUI preferences system.

The class is distributed as Polymorph-ware. Please read the docs
for more information about this concept.

GO TO CONTENTS

Toolbar.mcc/MUIA_Toolbar_Description

MUIA_Toolbar_Description -- [I..], struct MUIP_Toolbar_Description *

This attribute is used to describe the initial contents and the
initial state of the toolbar.

INPUTS
The argument is a pointer to a list of structures. The structure
is defined in 'mui/Toolbar_mcc.h'

Type = The type of field. It can be one of the following types:

TDT_BUTTON
TDT_SPACE
TDT_IGNORE // This will probably change
TDT_END

The size of the space can be set by the user in the preferences
program. The default is 20.
TDT_IGNORE only makes sense if your are working with some kind
of configurable toolbar.
The last entry in a descriptionlist must be TDT_END.

Key = This is the hotkey corresponding to a press on the button. If
the hotkey is a letter which is present in the tooltext then
this letter will be underlined. Always write this letter in
lowercase.

Flags = The flags reflect the state of the button. The following
special values are available:

TDF_TOGGLE Set this if you want the button to support an
on/off kind of nature.
TDF_RADIO Should it behave like a radio button. Only set
this if you have also set TDF_TOGGLE.
TDF_GHOSTED Guess!
TDF_GONE This flag makes the button disappear - useful for
a button like the 'Stop' button in Internet
browsers.
TDF_SELECTED If TDF_TOGGLE is set you can set this flag to make
the button selected/pressed/active or whatever you
like to call it :-).

ToolText = This is a pointer to the text beneath the icon. The width
of the icons will be adjusted to make room for the widest text.
It is not neccesary to specify tooltexts.

HelpString = You do not have to specify help strings either, but if
you do, they will be used for help-bubbles. It will also be used
in connection with MUIA_Toolbar_HelpString.

MutualExclude = This is a bit-field representing the toggle-buttons
which should be deactivated/unselected when this button is
pressed. Bit 0 (LSB) is the first field (spaces and 'ignores'
are also counted although it doesn't make sence to deactivate
these), bit 1 is the second field, ... .

EXAMPLE

See "Toolbar-Demo.c".

NOTES
The toolbar has a limit of 32 fields. This should probably not be
a serious limitation, but you are welcome to dispute this claim if
you like - then I might consider an alternative solution.

You MUST remember the following two points:

· Do not free the memory occupied by this structure unless you have
disposed the toolbar and do not need it any more. You can change
the contents though - see MUIM_Toolbar_Redraw.

· Do not reuse the structure for other toolbars. Every toolbar must
have its own structure.

BUGS
No known bugs.

SEE ALSO
MUIA_Toolbar_HelpString
MUIA_Toolbar_SpaceSize
MUIM_Toolbar_Redraw
MUIM_Toolbar_Redraw

GO TO CONTENTS

Toolbar.mcc/MUIA_Toolbar_HelpString

MUIA_Toolbar_HelpString -- [..G], STRPTR

The main purpose of this attribute is to use a notification event to
connect it with some kind of textobject (or anything that accepts
a string-pointer as argument).

EXAMPLE
A typical notification event could look like this:

DoMethod(toolbarobj, MUIM_Notify, MUIA_Toolbar_HelpString,
MUIV_EveryTime,
textobj, 3, MUIM_Set, MUIA_Text_Contents, MUIV_TriggerValue);

RESULT
First of all the result depends on the position of the mouse. If
the mouse is over a button then the HelpString of this button will
be used as the result. If the mouse is not over a button the
result will simply be an empty string.
Furthermore the result depends on whether or not there is a
HelpString available. If not then the ToolText will be returned
instead.

BUGS
No known bugs.

SEE ALSO

GO TO CONTENTS

Toolbar.mcc/MUIA_Toolbar_Horizontal

MUIA_Toolbar_Horizontal -- [I..], BOOL

This attribute simply tells the toolbarobject whether it should
render itself horizontally or vertically. Its default value is
TRUE.

BUGS
No known bugs.

NOTES

SEE ALSO

GO TO CONTENTS

Toolbar.mcc/MUIA_Toolbar_ImageGhost

MUIA_Toolbar_ImageGhost -- [I..]

This is an optional attribute to specify a special image for the
ghosted buttons. If it is not specified then the normal image and
a ghosting effect will be used instead.

INPUTS
The argument depends on the choice of imagetype specified by
MUIA_Toolbar_ImageType.

NOTES
If MUIA_Toolbar_ImageType is set to MUIV_Toolbar_ImageType_File then
I strongly suggest that you always specify this attribute too. If
the file is not found then the toolbar will just use the normal
image instead. This gives the user the possibility of making these
special images even if you did not include any with your program
originally. Remember to write the filenames in your documentation.

SEE ALSO
MUIA_Toolbar_ImageType
MUIM_Toolbar_ImageNormal

GO TO CONTENTS

Toolbar.mcc/MUIA_Toolbar_ImageNormal

MUIA_Toolbar_ImageNormal -- [I..]

This image MUST be specified. It is mainly used for the normal
un-selected look of the tool-buttons, but it might also be used for
the ghosted look or the selected look if these images are not
specified or not found.

The image should be saved in the correct size. This size naturally
depends on the size of the icons. If you have six icons of width x
then the image should be 6*x+5. The extra five pixels are used for
vertical lines between the icons that should help you organizing
the icons. Please see the example images if this seems a little
hazy.

INPUTS
The argument depends on the choice of imagetype specified by
MUIA_Toolbar_ImageType. If you use MUIV_Toolbar_ImageType_File then
the format of the picture can be anything supported by datatypes.

NOTES

SEE ALSO
MUIA_Toolbar_ImageGhost
MUIM_Toolbar_ImageType

GO TO CONTENTS

Toolbar.mcc/MUIA_Toolbar_ImageSelect

MUIA_Toolbar_ImageSelect -- [I..]

This is an optional attribute to specify a special image for the
selected buttons. If it is not specified then the normal image will
be used instead (which in most cases look fine).

INPUTS
The argument depends on the choice of imagetype specified by
MUIA_Toolbar_ImageType.

NOTES
If MUIA_Toolbar_ImageType is set to MUIV_Toolbar_ImageType_File then
I strongly suggest that you always specify this attribute too. If
the file is not found then the toolbar will just use the normal
image instead. This gives the user the possibility of making these
special images even if you did not include any with your program
originally. Remember to write the filenames in your documentation.

SEE ALSO
MUIA_Toolbar_ImageGhost
MUIM_Toolbar_ImageNormal
MUIM_Toolbar_ImageNormal
MUIM_Toolbar_ImageNormal

GO TO CONTENTS

Toolbar.mcc/MUIA_Toolbar_ImageType

MUIA_Toolbar_ImageType -- [I..], ULONG

SPECIAL INPUTS
MUIV_Toolbar_ImageType_File
MUIV_Toolbar_ImageType_Memory (not implemented)
MUIV_Toolbar_ImageType_Object

This determines the image type used for MUIA_Toolbar_ImageGhost,
MUIA_Toolbar_ImageNormal and MUIA_Toolbar_ImageSelect.

MUIV_Toolbar_ImageType_File indicates that you will supply the
attributes with filenames (STRPTR) and MUIV_Toolbar_ImageType_Object
that you will supply them with datatypes objects (Object *).

NOTES

SEE ALSO
MUIA_Toolbar_ImageGhost
MUIM_Toolbar_ImageNormal

GO TO CONTENTS

Toolbar.mcc/MUIA_Toolbar_ParseUnderscore

MUIA_Toolbar_ParseUnderscore -- [I..], BOOL

If your tooltexts contain underscores then you can use this
attribute to make the toolbar class parse these underscores and
initialize the correct hotkeys.

The default value is FALSE.

EXAMPLES
The text "Co_py" would be changed to "Copy" and 'p' would be used
as hotkey.

NOTES

SEE ALSO

GO TO CONTENTS

Toolbar.mcc/MUIM_Toolbar_BottomEdge

DoMethod(obj, MUIM_Toolbar_BottomEdge, ULONG Button);

With this method you can get the position of the bottom edge of
any button in the toolbar. This value could e.g. be used to place
a popup-window below a toolbar button.

This value is also available as a notification event.

INPUTS
Button - the number of the button

EXAMPLE

RESULT
The result is naturally the position of bottom edge measured in
pixels.

NOTES

BUGS
No known bugs.

SEE ALSO
MUIM_Toolbar_LeftEdge
MUIM_Toolbar_RightEdge
MUIM_Toolbar_TopEdge

GO TO CONTENTS

Toolbar.mcc/MUIM_Toolbar_KillNotify

DoMethod(obj, MUIM_Toolbar_KillNotify, ULONG TrigButton, ULONG TrigAttr);

This method kills a previously defined notification event. It will
only kill the first event that satisfies the arguments.

INPUTS
TrigButton The button number.
TrigAttr The notificationattribute.

EXAMPLE
/* This kills the notification event specified in the example above */

DoMethod(toolbarobj, MUIM_Toolbar_KillNotify, 3,
MUIV_Toolbar_Pressed);

RESULT
Returns TRUE if successful.

NOTES

BUGS
No known bugs.

SEE ALSO

GO TO CONTENTS

Toolbar.mcc/MUIM_Toolbar_KillNotifyObj

DoMethod(obj, MUIM_Toolbar_KillNotifyObj);

This method kills all previously defined notification events
associated with the object.

RESULT
Always return TRUE.

NOTES

BUGS
No known bugs.

SEE ALSO

GO TO CONTENTS

Toolbar.mcc/MUIM_Toolbar_LeftEdge

DoMethod(obj, MUIM_Toolbar_LeftEdge, ULONG Button);

See MUIM_Toolbar_BottomEdge.

INPUTS
Button - the number of the button

BUGS
No known bugs.

SEE ALSO
MUIM_Toolbar_BottomEdge
MUIM_Toolbar_RightEdge
MUIM_Toolbar_RightEdge

GO TO CONTENTS

Toolbar.mcc/MUIM_Toolbar_MultiSet

DoMethod(obj, MUIM_Toolbar_MultiSet, ULONG Flag, ULONG Value,
ULONG Button1, ULONG Button2, /* ... */);

This method can be used to set the state of several buttons
simultaneously. It is especially useful in notification events.

INPUTS
Flag You can set/unset one of the following flags:
MUIV_Toolbar_Set_Ghosted
MUIV_Toolbar_Set_Gone
MUIV_Toolbar_Set_Selected (only toggle-buttons)

Value TRUE or FALSE

ButtonX, ... A list of buttons terminated by -1 and NOT by NULL.

EXAMPLE
/* Ghost button number 2, 4 and 7 */
DoMethod(toolbarobj, MUIM_Toolbar_MultiSet,
MUIV_Toolbar_Set_Ghosted, TRUE, 2, 4, 7, -1);

NOTES
Please take a look at the notes of MUIM_Toolbar_Set.

BUGS
No known bugs.

SEE ALSO

GO TO CONTENTS

Toolbar.mcc/MUIM_Toolbar_Notify

DoMethod(obj, MUIM_Toolbar_Notify, ULONG TrigButton, ULONG TrigAttr,
ULONG TrigValue, APTR DestObj, ULONG FollowParams, /* ... */);

This is a method that works with the internal notificationsystem
for the toolbar class. It works just like the normal system of
notifications, but handles an extra argument - ULONG TrigButton.
This is neccesary if you want to be able to give each button its
own set of notification events.

INPUTS
TrigButton The button number
TrigAttr Attribute that triggers the notification. It can be one
of the following:

MUIV_Toolbar_Notify_Pressed
MUIV_Toolbar_Notify_Active (not yet implemented)
MUIV_Toolbar_Notify_Ghosted
MUIV_Toolbar_Notify_Gone
MUIV_Toolbar_Notify_LeftEdge
MUIV_Toolbar_Notify_RightEdge
MUIV_Toolbar_Notify_TopEdge
MUIV_Toolbar_Notify_BottomEdge

TrigValue The value that triggers the notification. Normally
TRUE/FALSE except MUIV_Toolbar_Notify_Active. When
using MUIV_Toolbar_Notify_Pressed you should be
aware that it reacts differently when the TDF_TOGGLE
flag is set. Normally it is TRUE when the user
presses the button and FALSE when he releases the
button. If it is a toggle-button it will be TRUE
when the user presses the button and the button goes
down and it will be FALSE when the user presses the
button and the button goes up. This means that a
toggle button never cause a notification when the
mousebutton is released.

The special values MUIV_EveryTime, MUIV_TriggerValue
and MUIV_NotTriggerValue are supported.

DestObj Object to be notified.
The special values MUIV_Notify_Self, MUIV_Notify_Window and
MUIV_Notify_Application are supported.

FollowParams The number of following parameters.

... The following parameters.

EXAMPLE
/* Quit if button number 3 is pressed (and released) */
DoMethod(toolbarobj, MUIM_Toolbar_Notify,
3, /* Button number */
MUIV_Toolbar_Notify_Pressed, /* Attribute */
FALSE, /* Value that triggers the notify */
app, /* Destination object */
2, /* Number of following param. */
MUIM_Application_ReturnID, MUIV_Application_ReturnID_Quit);

See "Toolbar-Demo.c" for more examples.

RESULT
In most cases this method will return TRUE. It is only the lack of
memory that might cause a negative result.

NOTES

BUGS
No known bugs.

SEE ALSO
MUIM_Toolbar_KillNotify
MUIM_Toolbar_KillNotifyObj
MUIM_Toolbar_KillNotifyObj

GO TO CONTENTS

Toolbar.mcc/MUIM_Toolbar_Redraw

DoMethod(obj, MUIM_Toolbar_Redraw, ULONG Changes);

This method is very useful if you are going to make some major
changes to the toolbar. It simply tells the toolbar object to
redraw itself.

Before you call this method you can make a lot of changes in your
description list. You are allowed to change the following fields:

Key, Flags, HelpString and MutualExclude.

You can also change the ToolText, but if the new text is wider than
the widest of the existing tooltexts you will probably get some
graphical errors.

If you change anything else, you will have to 're-create' the
object (dispose and create).

INPUTS
Changes This value should have its bits set corresponding to the
changed buttons. If you have changed buttons number 2, 4
and 8 you would set this inputvalue to:
%10001010 = $8A
If you simply want to redraw the entire toolbar you can
use $FFFFFFFF (or -1) as argument (this is actually good
enough in most cases even if you haven't changed all
entries in the toolbar).

IMPORTANT:
Remember that spaces and 'ignores' also count when you
specify the button numbers. E.g. if your toolbar is
specified as [Button1, Space, Button2, Ignore, Button3,
End] then Button1 is bit number 0, Button2 is bit number
2 and Button3 is bit number 4 - corresponding to the bit
pattern %00010101 = $13.

EXAMPLE

RESULT
This method always return TRUE.

NOTES

BUGS
No known bugs.

SEE ALSO

GO TO CONTENTS

Toolbar.mcc/MUIM_Toolbar_RightEdge

DoMethod(obj, MUIM_Toolbar_RightEdge, ULONG Button);

See MUIM_Toolbar_BottomEdge.

INPUTS
Button - the number of the button

BUGS
No known bugs.

SEE ALSO
MUIM_Toolbar_BottomEdge
MUIM_Toolbar_LeftEdge
MUIM_Toolbar_LeftEdge

GO TO CONTENTS

Toolbar.mcc/MUIM_Toolbar_Set

DoMethod(obj, MUIM_Toolbar_Set, ULONG Button, ULONG Flag, ULONG Value);

This method can be used to set the state of a button. It is
especially useful in notification events.

INPUTS
Button The button that is going to change.

Flag You can set/unset one of the following flags:
MUIV_Toolbar_Set_Ghosted
MUIV_Toolbar_Set_Gone
MUIV_Toolbar_Set_Selected (only toggle-buttons)

Value TRUE or FALSE

EXAMPLE
/* Ghost button number 3 */
DoMethod(toolbarobj, MUIM_Toolbar_Set, 3, MUIV_Toolbar_Set_Ghosted, TRUE);

NOTES
Button numbers should not be taken too literally. Button number 3
would actually be the forth in a toolbar since button number 0
also counts. If there are any TDT_SPACE or TDT_IGNORE these will
count as well. This is done to make the number conform to the offset
in the descriptionlist.

BUGS
No known bugs.

SEE ALSO

GO TO CONTENTS

Toolbar.mcc/MUIM_Toolbar_TopEdge

DoMethod(obj, MUIM_Toolbar_TopEdge, ULONG Button);

See MUIM_Toolbar_BottomEdge.

INPUTS
Button - the number of the button

BUGS
No known bugs.

SEE ALSO
MUIM_Toolbar_BottomEdge
MUIM_Toolbar_LeftEdge
MUIM_Toolbar_LeftEdge