doc/MCC_BetterString.doc
TABLE OF CONTENTS
BetterString.mcc/BetterString.mcc
BetterString.mcc/MUIA_BetterString_Columns
BetterString.mcc/MUIA_BetterString_InactiveContents
BetterString.mcc/MUIA_BetterString_KeyUpFocus
BetterString.mcc/MUIA_BetterString_KeyDownFocus
BetterString.mcc/MUIA_BetterString_NoInput
BetterString.mcc/MUIA_BetterString_NoNotify
BetterString.mcc/MUIA_BetterString_NoShortcuts
BetterString.mcc/MUIA_BetterString_SelectOnActive
BetterString.mcc/MUIA_BetterString_SelectSize
BetterString.mcc/MUIA_BetterString_StayActive
BetterString.mcc/MUIM_BetterString_ClearSelected
BetterString.mcc/MUIM_BetterString_DoAction
BetterString.mcc/MUIM_BetterString_FileNameStart
BetterString.mcc/MUIM_BetterString_Insert
BetterString.mcc/BetterString.mcc
*******************************************************************
Copyright (C) 2005-2021 BetterString.mcc Open Source Team
$Id$
BetterString is a stringgadget replacement. It is created for MUI,
so using it should eliminate the problems with the original BOOPSI
stringclass. The class offers the user to do number arithmetic, like
increase, decrease and bin<->hex conversion. It has filename
completion, ability to mark, cut, copy and paste text - Both via
mouse and keyboard. The length of the contents buffer will
dynamically be expanded to hold all of what the user type (unless
a maximum length is given)
The gadget was originally written in 1997 by Allan Odgaard. As of
version 11.7, released in July 2005, the gadget is maintained by
the BetterString.mcc Open Source team.
It is released and distributed under the terms of the GNU Lesser
General Public License (LGPL) and available free of charge.
Please visit http://www.sf.net/projects/bstring-mcc/ for
the very latest version and information regarding BetterString.mcc
*******************************************************************
BetterString.mcc/MUIA_BetterString_Columns
NAME
MUIA_BetterString_Columns -- [I..], ULONG
FUNCTION
Set the width of the stringgadget (in characters)
BetterString.mcc/MUIA_BetterString_InactiveContents
NAME
MUIA_BetterString_InactiveContents -- [ISG], STRPTR
FUNCTION
Set the text which will be displayed if no other text is to be displayed
and the string gadget is inactive. The text will be shown in an italic
style. The supplied text will NOT be copied by BetterString.mcc!! Upon
OM_GET the returned pointer is READ-ONLY!!
BetterString.mcc/MUIA_BetterString_KeyUpFocus
NAME
MUIA_BetterString_KeyUpFocus -- [ISG], Object *
FUNCTION
Allows to specify a specific object that will be set as the new
window's default object in case the user pressed the UP cursor key.
SEE ALSO
MUIA_BetterString_KeyDownFocus
BetterString.mcc/MUIA_BetterString_KeyDownFocus
NAME
MUIA_BetterString_KeyDownFocus -- [ISG], Object *
FUNCTION
Allows to specify a specific object that will be set as the new
window's default object in case the user pressed the DOWN cursor key.
SEE ALSO
MUIA_BetterString_KeyUpFocus
BetterString.mcc/MUIA_BetterString_NoInput
NAME
MUIA_BetterString_NoInput -- [ISG], BOOL
FUNCTION
Effectively turns the gadget into read-only mode.
BetterString.mcc/MUIA_BetterString_NoNotify
NAME
MUIA_BetterString_NoNotify -- [ISG], BOOL
FUNCTION
If set to TRUE, BetterString will omit to send out notifies for
MUIA_String_Contents changes. However, as soon as this flag is
set back to FALSE a notification will be triggered in case during
the lifetime of NoNotify a notification event was prevented.
NOTE
This could be particularly helpful if certain consecutive
operations need to be performed on a betterstring object and
the application wants to make sure that only one notification
will be triggered.
BetterString.mcc/MUIA_BetterString_NoShortcuts
NAME
MUIA_BetterString_NoShortcuts -- [ISG], BOOL
FUNCTION
Per default a BetterString object comes with certain enabled
shortcuts for operations like copy & paste. By setting this
attribute to FALSE, a developer can define that these default
shortcuts should not be enabled.
NOTE
The default shorcuts which can be disabled by this attribute
are:
Amiga + c = Copy, either what is selected or the complete string.
Amiga + x = Cut, either what is selected or the complete string.
Amiga + v = Paste from clipboard.
Amiga + z = Undo until the last deletion (only one level)
Amiga + Z = Redo the last undo.
Amiga + q = Revert to original string, press it again to go back
to the modified string.
Amiga + g = Toggle case on current character.
Amiga + G = Toggle case from cursor to start of next word.
Amiga + i = Increase the nearest number.
Amiga + d = Decrease the nearest number.
Amiga + # = Convert current hexadecimal number to decimal.
Amiga + $ = Convert nearest number to hexadecimal.
Amiga + Tab = Complete the current volume, assign or paths name.
You can step thru the various matches by pressing
Amiga+Tab again. Use Amiga+Shift+Tab to go backwards.
In addition, there are shortcuts which will always be available,
no matter if this attribute is set to TRUE or FALSE:
Ctrl + left = Navigate to start of line.
Ctrl + right = Navigate to end of line.
Alt + left = Navigate to start of next word.
Alt + right = Navigate to start of current or previous word.
Ctrl + Delete = Delete to start of line.
Ctrl + Backspace = Delete to end of line.
Alt + Delete = Delete to start of next word.
Alt + Backspace = Delete to start of current or previous word.
Delete = Delete the marked block, or current character.
Backspace = Delete the marked block, or the character to
the left.
SEE ALSO
MUIM_BetterString_DoAction
BetterString.mcc/MUIA_BetterString_SelectOnActive
NAME
MUIA_BetterString_SelectOnActive -- [ISG], BOOL
FUNCTION
Allows to override the default settings for the preference setting
to directly select all text in case a BetterString object will be
the new active object of a window (via Tab-key switching or via
using the mouse to make the object active.
NOTE
If this attribute is not explicitly set on object creation or later,
the default setting a user has configured is used. This attribute
should only be manually set if you are *absolutely* sure you require
it. Please don't force a user to use this type of functionality and
let him choose himself. However, there might be rare cases where
setting this attribute might be required and thus the reason for it
to be there.
SEE ALSO
BetterString.mcc/MUIA_BetterString_SelectSize
NAME
MUIA_BetterString_SelectSize -- [.SG], LONG
FUNCTION
Get or set the number of selected characters.
A negative value indicates that the marking has happend right to left.
A 0 means nothing is marked.
SEE ALSO
MUIA_String_BufferPos (MUIA_String.Doc)
BetterString.mcc/MUIA_BetterString_StayActive
NAME
MUIA_BetterString_StayActive -- [ISG], BOOL
FUNCTION
Setting this attribute to TRUE will let the stringgadget stay active,
even when the user hits return, or clicks outside the gadgets area.
BetterString.mcc/MUIM_BetterString_ClearSelected
NAME
MUIM_BetterString_ClearSelected
SYNOPSIS
DoMethod(obj, MUIM_BetterString_ClearSelected);
FUNCTION
Clears all currently marked text. This method is in fact doing
the very same like the MUIV_BetterString_DoAction_Delete action of
MUIM_BetterString_DoAction.
RESULT
NONE
SEE ALSO
MUIM_BetterString_DoAction
BetterString.mcc/MUIM_BetterString_DoAction
NAME
MUIM_BetterString_DoAction
SYNOPSIS
DoMethod(obj, MUIM_BetterString_DoAction, ULONG action);
FUNCTION
Allows to manually perform actions like copy, paste, etc. on a
BetterString object. This can be used in case you want to trigger an
action from your application with other shortcuts or if you want to
perform some batched processing on a BetterString object.
The allowed actions are:
MUIV_BetterString_DoAction_Cut
Cut out the currently selected text and put it into the
clipboard
MUIV_BetterString_DoAction_Copy
Copy the currently selected text into the clipboard and
deselect it accordingly.
MUIV_BetterString_DoAction_Paste
Paste text from the clipboard at the current cursor position
MUIV_BetterString_DoAction_Delete
Deletes the currently selected content in the gadget
MUIV_BetterString_DoAction_SelectAll
Select all available text in the string gadget
MUIV_BetterString_DoAction_SelectNone
Select no text at all
MUIV_BetterString_DoAction_Undo
Perform an undo operation and reset the text to what
was present at the last change.
MUIV_BetterString_DoAction_Redo
After having performed an undo operation
MUIV_BetterString_DoAction_Revert
Revert to original string, calling it again will revert
to the modified string again.
MUIV_BetterString_DoAction_ToggleCase
Toggle case on current character.
MUIV_BetterString_DoAction_ToggleCaseWord
Toggle case from cursor to start of next word.
MUIV_BetterString_DoAction_IncreaseNum
Increase the nearest number.
MUIV_BetterString_DoAction_DecreaseNum
Decrease the nearest number.
MUIV_BetterString_DoAction_HexToDec
Convert current hexadecimal number to decimal.
MUIV_BetterString_DoAction_DecToHex
Convert nearest number to hexadecimal.
MUIV_BetterString_DoAction_NextFileComp
Set the string gadget to the next file completion result
MUIV_BetterString_DoAction_PrevFileComp
Set the string gadget to the previous file completion result
NOTE
This functionality may become especially usefull in case you
want to have your own shortcuts in your application. In that case
you may disable the default shortcuts via MUIA_BetterString_NoShortcuts
and call the DoAction method accordingly.
RESULT
Returns TRUE if the action/request succeeded, or FALSE if the
action couldn't be executed or an error occurred.
SEE ALSO
MUIA_BetterString_NoShortcuts
BetterString.mcc/MUIM_BetterString_FileNameStart
NAME
MUIM_BetterString_FileNameStart
SYNOPSIS
DoMethod(obj, MUIM_BetterString_FileNameStart, STRPTR buffer, LONG pos);
FUNCTION
When the user press Amiga+TAB, then BetterString will call this
method, with a pointer to the current buffer, and a cursor position.
It expects the method to return the start position of the partial
file, which the cursor is currently at.
Generally BetterString's own implementation is clever enough to find
it, but if for example you use the stringgadget in a webbrowser, where
the file is prefixed with "file://", then it isn't.
RESULT
The start of the file or MUIR_BetterString_FileNameStart_Volume if no
file is found, this will make BetterString treat the string as the
beginning of a volumne, and make it do volume-completion instead.
BetterString.mcc/MUIM_BetterString_Insert
NAME
MUIM_BetterString_Insert
SYNOPSIS
DoMethod(obj, MUIM_BetterString_Insert, STRPTR text, LONG pos);
FUNCTION
This will insert the given text.
The position of the inserted text can either be a real position, or:
MUIV_BetterString_Insert_StartOfString
MUIV_BetterString_Insert_EndOfString
MUIV_BetterString_Insert_BufferPos
If there isn't enough room to fit the complete string, then it will be
truncated, and the user will get a DisplayBeep().
If the cursor is to the right if the insertion place, then it will be
moved.
RESULT
NONE
SEE ALSO
MUIA_String_Contents (MUIA_String.Doc)