workbench/classes/zune/betterstring/doc/MCC_BetterString.doc

   1 TABLE OF CONTENTS
   2
   3 BetterString.mcc/BetterString.mcc
   4 BetterString.mcc/MUIA_BetterString_Columns
   5 BetterString.mcc/MUIA_BetterString_InactiveContents
   6 BetterString.mcc/MUIA_BetterString_KeyUpFocus
   7 BetterString.mcc/MUIA_BetterString_KeyDownFocus
   8 BetterString.mcc/MUIA_BetterString_NoInput
   9 BetterString.mcc/MUIA_BetterString_NoNotify
  10 BetterString.mcc/MUIA_BetterString_NoShortcuts
  11 BetterString.mcc/MUIA_BetterString_SelectOnActive
  12 BetterString.mcc/MUIA_BetterString_SelectSize
  13 BetterString.mcc/MUIA_BetterString_StayActive
  14 BetterString.mcc/MUIM_BetterString_ClearSelected
  15 BetterString.mcc/MUIM_BetterString_DoAction
  16 BetterString.mcc/MUIM_BetterString_FileNameStart
  17 BetterString.mcc/MUIM_BetterString_Insert
  18 \fBetterString.mcc/BetterString.mcc
  19
  20     *******************************************************************
  21     Copyright (C) 2005-2012 by BetterString.mcc Open Source Team
  22     $Id: MCC_BetterString.doc 317 2012-05-10 17:44:55Z damato $
  23
  24     BetterString is a stringgadget replacement. It is created for MUI,
  25     so using it should eliminate the problems with the original BOOPSI
  26     stringclass. The class offers the user to do number arithmetic, like
  27     increase, decrease and bin<->hex conversion. It has filename
  28     completion, ability to mark, cut, copy and paste text - Both via
  29     mouse and keyboard. The length of the contents buffer will
  30     dynamically be expanded to hold all of what the user type (unless
  31     a maximum length is given)
  32
  33     The gadget was originally written in 1997 by Allan Odgaard. As of
  34     version 11.7, released in July 2005, the gadget is maintained by
  35     the BetterString.mcc Open Source team.
  36
  37     It is released and distributed under the terms of the GNU Lesser
  38     General Public License (LGPL) and available free of charge.
  39
  40     Please visit http://www.sf.net/projects/bstring-mcc/ for
  41     the very latest version and information regarding BetterString.mcc
  42     *******************************************************************
  43
  44 \fBetterString.mcc/MUIA_BetterString_Columns
  45
  46     NAME
  47         MUIA_BetterString_Columns -- [I..], ULONG
  48
  49     FUNCTION
  50         Set the width of the stringgadget (in characters)
  51
  52 \fBetterString.mcc/MUIA_BetterString_InactiveContents
  53
  54     NAME
  55         MUIA_BetterString_InactiveContents -- [ISG], STRPTR
  56
  57     FUNCTION
  58         Set the text which will be displayed if no other text is to be displayed
  59         and the string gadget is inactive. The text will be shown in an italic
  60         style. The supplied text will NOT be copied by BetterString.mcc!! Upon
  61         OM_GET the returned pointer is READ-ONLY!!
  62
  63 \fBetterString.mcc/MUIA_BetterString_KeyUpFocus
  64
  65     NAME
  66         MUIA_BetterString_KeyUpFocus -- [ISG], Object *
  67
  68     FUNCTION
  69         Allows to specify a specific object that will be set as the new
  70         window's default object in case the user pressed the UP cursor key.
  71
  72     SEE ALSO
  73         MUIA_BetterString_KeyDownFocus
  74
  75 \fBetterString.mcc/MUIA_BetterString_KeyDownFocus
  76
  77     NAME
  78         MUIA_BetterString_KeyDownFocus -- [ISG], Object *
  79
  80     FUNCTION
  81         Allows to specify a specific object that will be set as the new
  82         window's default object in case the user pressed the DOWN cursor key.
  83
  84     SEE ALSO
  85         MUIA_BetterString_KeyUpFocus
  86
  87 \fBetterString.mcc/MUIA_BetterString_NoInput
  88
  89     NAME
  90         MUIA_BetterString_NoInput -- [ISG], BOOL
  91
  92     FUNCTION
  93         Effectively turns the gadget into read-only mode.
  94
  95 \fBetterString.mcc/MUIA_BetterString_NoNotify
  96
  97     NAME
  98         MUIA_BetterString_NoNotify -- [ISG], BOOL
  99
 100     FUNCTION
 101         If set to TRUE, BetterString will omit to send out notifies for
 102         MUIA_String_Contents changes. However, as soon as this flag is
 103         set back to FALSE a notification will be triggered in case during
 104         the lifetime of NoNotify a notification event was prevented.
 105
 106     NOTE
 107         This could be particularly helpful if certain consecutive
 108         operations need to be performed on a betterstring object and
 109         the application wants to make sure that only one notification
 110         will be triggered.
 111
 112 \fBetterString.mcc/MUIA_BetterString_NoShortcuts
 113
 114     NAME
 115         MUIA_BetterString_NoShortcuts -- [ISG], BOOL
 116
 117     FUNCTION
 118         Per default a BetterString object comes with certain enabled
 119         shortcuts for operations like copy & paste. By setting this
 120         attribute to FALSE, a developer can define that these default
 121         shortcuts should not be enabled.
 122
 123     NOTE
 124         The default shorcuts which can be disabled by this attribute
 125         are:
 126
 127         Amiga + c   = Copy, either what is selected or the complete string.
 128         Amiga + x   = Cut, either what is selected or the complete string.
 129         Amiga + v   = Paste from clipboard.
 130         Amiga + z   = Undo until the last deletion (only one level)
 131         Amiga + Z   = Redo the last undo.
 132         Amiga + q   = Revert to original string, press it again to go back
 133                       to the modified string.
 134         Amiga + g   = Toggle case on current character.
 135         Amiga + G   = Toggle case from cursor to start of next word.
 136         Amiga + i   = Increase the nearest number.
 137         Amiga + d   = Decrease the nearest number.
 138         Amiga + #   = Convert current hexadecimal number to decimal.
 139         Amiga + $   = Convert nearest number to hexadecimal.
 140         Amiga + Tab = Complete the current volume, assign or paths name.
 141                       You can step thru the various matches by pressing
 142                       Amiga+Tab again. Use Amiga+Shift+Tab to go backwards.
 143
 144         In addition, there are shortcuts which will always be available,
 145         no matter if this attribute is set to TRUE or FALSE:
 146
 147         Ctrl + left      = Navigate to start of line.
 148         Ctrl + right     = Navigate to end of line.
 149         Alt  + left      = Navigate to start of next word.
 150         Alt  + right     = Navigate to start of current or previous word.
 151         Ctrl + Delete    = Delete to start of line.
 152         Ctrl + Backspace = Delete to end of line.
 153         Alt  + Delete    = Delete to start of next word.
 154         Alt  + Backspace = Delete to start of current or previous word.
 155         Delete           = Delete the marked block, or current character.
 156         Backspace        = Delete the marked block, or the character to
 157                            the left.
 158
 159     SEE ALSO
 160         MUIM_BetterString_DoAction
 161
 162 \fBetterString.mcc/MUIA_BetterString_SelectOnActive
 163
 164     NAME
 165         MUIA_BetterString_SelectOnActive -- [ISG], BOOL
 166
 167     FUNCTION
 168         Allows to override the default settings for the preference setting
 169         to directly select all text in case a BetterString object will be
 170         the new active object of a window (via Tab-key switching or via
 171         using the mouse to make the object active.
 172
 173     NOTE
 174         If this attribute is not explicitly set on object creation or later,
 175         the default setting a user has configured is used. This attribute
 176         should only be manually set if you are *absolutely* sure you require
 177         it. Please don't force a user to use this type of functionality and
 178         let him choose himself. However, there might be rare cases where
 179         setting this attribute might be required and thus the reason for it
 180         to be there.
 181
 182     SEE ALSO
 183
 184
 185 \fBetterString.mcc/MUIA_BetterString_SelectSize
 186
 187     NAME
 188         MUIA_BetterString_SelectSize -- [.SG], LONG
 189
 190     FUNCTION
 191         Get or set the number of selected characters.
 192         A negative value indicates that the marking has happend right to left.
 193         A 0 means nothing is marked.
 194
 195     SEE ALSO
 196         MUIA_String_BufferPos (MUIA_String.Doc)
 197
 198 \fBetterString.mcc/MUIA_BetterString_StayActive
 199
 200     NAME
 201         MUIA_BetterString_StayActive -- [ISG], BOOL
 202
 203     FUNCTION
 204         Setting this attribute to TRUE will let the stringgadget stay active,
 205         even when the user hits return, or clicks outside the gadgets area.
 206
 207 \fBetterString.mcc/MUIM_BetterString_ClearSelected
 208
 209     NAME
 210         MUIM_BetterString_ClearSelected
 211
 212     SYNOPSIS
 213         DoMethod(obj, MUIM_BetterString_ClearSelected);
 214
 215     FUNCTION
 216         Clears all currently marked text. This method is in fact doing
 217         the very same like the MUIV_BetterString_DoAction_Delete action of
 218         MUIM_BetterString_DoAction.
 219
 220     RESULT
 221         NONE
 222
 223     SEE ALSO
 224         MUIM_BetterString_DoAction
 225
 226 \fBetterString.mcc/MUIM_BetterString_DoAction
 227
 228     NAME
 229         MUIM_BetterString_DoAction
 230
 231     SYNOPSIS
 232         DoMethod(obj, MUIM_BetterString_DoAction, ULONG action);
 233
 234     FUNCTION
 235         Allows to manually perform actions like copy, paste, etc. on a
 236         BetterString object. This can be used in case you want to trigger an
 237         action from your application with other shortcuts or if you want to
 238         perform some batched processing on a BetterString object.
 239
 240         The allowed actions are:
 241
 242           MUIV_BetterString_DoAction_Cut
 243             Cut out the currently selected text and put it into the
 244             clipboard
 245
 246           MUIV_BetterString_DoAction_Copy
 247             Copy the currently selected text into the clipboard and
 248             deselect it accordingly.
 249
 250           MUIV_BetterString_DoAction_Paste
 251             Paste text from the clipboard at the current cursor position
 252
 253           MUIV_BetterString_DoAction_Delete
 254             Deletes the currently selected content in the gadget
 255
 256           MUIV_BetterString_DoAction_SelectAll
 257             Select all available text in the string gadget
 258
 259           MUIV_BetterString_DoAction_SelectNone
 260             Select no text at all
 261
 262           MUIV_BetterString_DoAction_Undo
 263             Perform an undo operation and reset the text to what
 264             was present at the last change.
 265
 266           MUIV_BetterString_DoAction_Redo
 267             After having performed an undo operation
 268
 269           MUIV_BetterString_DoAction_Revert
 270             Revert to original string, calling it again will revert
 271             to the modified string again.
 272
 273           MUIV_BetterString_DoAction_ToggleCase
 274             Toggle case on current character.
 275
 276           MUIV_BetterString_DoAction_ToggleCaseWord
 277             Toggle case from cursor to start of next word.
 278
 279           MUIV_BetterString_DoAction_IncreaseNum
 280             Increase the nearest number.
 281
 282           MUIV_BetterString_DoAction_DecreaseNum
 283             Decrease the nearest number.
 284
 285           MUIV_BetterString_DoAction_HexToDec
 286             Convert current hexadecimal number to decimal.
 287
 288           MUIV_BetterString_DoAction_DecToHex
 289             Convert nearest number to hexadecimal.
 290
 291           MUIV_BetterString_DoAction_NextFileComp
 292             Set the string gadget to the next file completion result
 293
 294           MUIV_BetterString_DoAction_PrevFileComp
 295             Set the string gadget to the previous file completion result
 296
 297     NOTE
 298         This functionality may become especially usefull in case you
 299         want to have your own shortcuts in your application. In that case
 300         you may disable the default shortcuts via MUIA_BetterString_NoShortcuts
 301         and call the DoAction method accordingly.
 302
 303     RESULT
 304         Returns TRUE if the action/request succeeded, or FALSE if the
 305         action couldn't be executed or an error occurred.
 306
 307     SEE ALSO
 308         MUIA_BetterString_NoShortcuts
 309
 310 \fBetterString.mcc/MUIM_BetterString_FileNameStart
 311
 312     NAME
 313         MUIM_BetterString_FileNameStart
 314
 315     SYNOPSIS
 316         DoMethod(obj, MUIM_BetterString_FileNameStart, STRPTR buffer, LONG pos);
 317
 318     FUNCTION
 319         When the user press Amiga+TAB, then BetterString will call this
 320         method, with a pointer to the current buffer, and a cursor position.
 321         It expects the method to return the start position of the partial
 322         file, which the cursor is currently at.
 323
 324         Generally BetterString's own implementation is clever enough to find
 325         it, but if for example you use the stringgadget in a webbrowser, where
 326         the file is prefixed with "file://", then it isn't.
 327
 328     RESULT
 329         The start of the file or MUIR_BetterString_FileNameStart_Volume if no
 330         file is found, this will make BetterString treat the string as the
 331         beginning of a volumne, and make it do volume-completion instead.
 332
 333 \fBetterString.mcc/MUIM_BetterString_Insert
 334
 335     NAME
 336         MUIM_BetterString_Insert
 337
 338     SYNOPSIS
 339         DoMethod(obj, MUIM_BetterString_Insert, STRPTR text, LONG pos);
 340
 341     FUNCTION
 342         This will insert the given text.
 343         The position of the inserted text can either be a real position, or:
 344
 345           MUIV_BetterString_Insert_StartOfString
 346           MUIV_BetterString_Insert_EndOfString
 347           MUIV_BetterString_Insert_BufferPos
 348
 349         If there isn't enough room to fit the complete string, then it will be
 350         truncated, and the user will get a DisplayBeep().
 351         If the cursor is to the right if the insertion place, then it will be
 352         moved.
 353
 354     RESULT
 355         NONE
 356
 357     SEE ALSO
 358         MUIA_String_Contents (MUIA_String.Doc)
 359 \f