MUI_String

String.mui

Super class

Background

String class generates standard string gadgets with all editing facilities (clear, undo, etc.) enabled.

Common problems: You may need a string gadget to show at least x numbers of characterss. If you specify MUIA_FixWidthTxt,"00000000" you can be sure that the width is large enough to handle the number of chars.

Attributes

Attribute	Version	ISG	Type
MUIA_String_Accept	V4	ISG	`STRPTR`
MUIA_String_Acknowledge	V4	..G	`STRPTR`
MUIA_String_AdvanceOnCR	V11	ISG	`BOOL`
MUIA_String_AttachedList	V4	ISG	`Object *`
MUIA_String_BufferPos	V4	.SG	`LONG`
MUIA_String_Contents	V4	ISG	`STRPTR`
MUIA_String_DisplayPos	V4	.SG	`LONG`
MUIA_String_EditHook	V7	ISG	`struct Hook *`
MUIA_String_Format	V4	I.G	`LONG`
MUIA_String_InactiveContents	V20	ISG	`CONST_STRPTR`
MUIA_String_Integer	V4	ISG	`ULONG`
MUIA_String_Integer64	V20	ISG	`int64 *`
MUIA_String_LonelyEditHook	V11	ISG	`BOOL`
MUIA_String_MaxLen	V4	I.G	`LONG`
MUIA_String_Placeholder	V21	ISG	`CONST_STRPTR`
MUIA_String_Reject	V4	ISG	`STRPTR`
MUIA_String_Secret	V4	ISG	`BOOL`

MUIA_String_Accept

NAME

MUIA_String_Accept -- V4 [ISG], STRPTR, 0x8042e3e1

FUNCTION

A string containing characters allowed as input for the string gadget. Whenever the user hits a character not found in MUIA_String_Accept, he will hear a beep and gadget's contents won't be changed. The supplied string is NOT copied and must remain valid as long as the string object lives. Pass a NULL pointer to let String class accept all characters (the default). An empty string ("") is the worst choice as this will let String class accept NO characters at all.

EXAMPLE

StringObject,
  MUIA_String_Accept, "0123456789-",
  End,

MUIA_String_Acknowledge

NAME

MUIA_String_Acknowledge -- V4 [..G], STRPTR, 0x8042026c

FUNCTION

This attribute will be set to the contents of the string whenever the user hits return in the gadget. An application can listen with notification and take the appropriate action.

Using the TAB key or a mouse click to deactivate the gadget will not trigger MUIA_String_Acknowledge.

EXAMPLE

/* two string gadgets str1 and str2, the second should
/* become active after a return in the first: */

DoMethod(str1,MUIM_Notify,
  MUIA_String_Acknowledge, MUIV_EveryTime,
  windowobj, 3,
  MUIM_Set, MUIA_Window_ActiveObject, str2);

MUIA_String_AdvanceOnCR

NAME

MUIA_String_AdvanceOnCR -- V11 [ISG], BOOL, 0x804226de

FUNCTION

Set this if you want carriage returns in string gadgets behave like the TAB key, i.e. pressing CR will activate the next/previous gadget in the cycle chain.

MUIA_String_AttachedList

NAME

MUIA_String_AttachedList -- V4 [ISG], Object *, 0x80420fd2

FUNCTION

This special attribute can be set to point to a valid MUI object of List or Listview class. This enables controlling the lists cursor from within the string gadget, all cursor key events will be forwarded.

MUIA_String_BufferPos

NAME

MUIA_String_BufferPos -- V4 [.SG], LONG, 0x80428b6c

FUNCTION

MUIA_String_BufferPos can be used to get and set the position of the cursor in the string gadget. This attribute is probably not very interesting.

MUIA_String_Contents

NAME

MUIA_String_Contents -- V4 [ISG], STRPTR, 0x80428ffd

FUNCTION

Get and set a string gadgets contents. You may not modify the returned string.

MUIA_String_Contents gets updated every time when the contents of the string gadget change. When you set up a notification on this attribute, you will hear about every keystroke.

NOTES

If you try to set contents to something larger than MUIA_String_MaxLen (including the 0-byte!), MUI will silently strip the additional characters.

EXAMPLE

/* The given hook will be called after every change */
/* in the string gadget. It receives a pointer to   */
/* a pointer to the current contents in register a1 */
/* (see MUIM_CallHook for details)                  */

DoMethod(str, MUIM_Notify,
  MUIA_String_Contents, MUIV_EveryTime,
  str, 3,
  MUIM_CallHook, &hook, MUIV_TriggerValue);

MUIA_String_DisplayPos

NAME

MUIA_String_DisplayPos -- V4 [.SG], LONG, 0x8042ccbf

FUNCTION

MUIA_String_DisplayPos can be used to get and set the number of the first character of the string to be displayed. This attribute is probably not very interesting.

MUIA_String_EditHook

NAME

MUIA_String_EditHook -- V7 [ISG], struct Hook *, 0x80424c33

FUNCTION

When specified, MUI calls this hook as if it was a real string edit hook in a real string gadget. It receives a pointer to itself in A0, a pointer to a SGWork structure in A2 and a pointer to the message in A1.

You MUST check the EditOp field in the passed SGWork structure and act appropriately according to Intuition's documentation (intuition/sghooks.h).

NOTES

Since the String class of MUI4 is no longer based on a string object created by Intuition's strgclass the supplied edit hook will be called with faked structures. Please note that these structures might not contain exactly the same values that one might expect for an object managed by Intuition. If something is missing here or definitely contradicts the way how Intuition handles a certain situation then please open an appropriate ticket in MUI's bugtracker at: https://github.com/amiga-mui/muidev/issues

MUIA_String_Format

NAME

MUIA_String_Format -- V4 [I.G], LONG, 0x80427484

SPECIAL INPUTS

MUIV_String_Format_Left
MUIV_String_Format_Center
MUIV_String_Format_Right

FUNCTION

Used to adjust the alignment of the input string.

MUIA_String_InactiveContents

NAME

MUIA_String_InactiveContents -- V20 [ISG], CONST_STRPTR, 0x80427ecf

FUNCTION

In case the string object is inactive and no text has been entered by the user or set by the application the text specified by this attribute is displayed instead. To improve the visual feedback the text will be displayed with italic style and shadow color. The supplied string is NOT copied and must remain valid as long as the string object lives.

MUIA_String_Integer

NAME

MUIA_String_Integer -- V4 [ISG], ULONG, 0x80426e8a

FUNCTION

Useful for turning a string gadget into an integer gadget. Setting this attribute puts the value with "%ld" into the gadget, getting it returns a longword containing the string gadgets contents as number.

You should set MUIA_String_Accept to "0123456789" or something like that to avoid wrong characters.

EXAMPLE

StringObject,
  MUIA_String_Accept, "0123456879",
  MUIA_String_Integer, 42,
  End;

MUIA_String_Integer64

NAME

MUIA_String_Integer64 -- V20 [ISG], int64 *, 0x80424820

FUNCTION

Useful for turning a string gadget into an integer gadget. Setting this attribute puts the value with "%lld" into the gadget, getting it returns a 64bit value containing the string gadgets contents as number.

You should set MUIA_String_Accept to "0123456789" or something like that to avoid wrong characters.

EXAMPLE

StringObject,
  MUIA_String_Accept, "0123456879",
  MUIA_String_Integer64, 42,
  End;

MUIA_String_LonelyEditHook

NAME

MUIA_String_LonelyEditHook -- V11 [ISG], BOOL, 0x80421569

FUNCTION

If your string object has an edit hook, you can set this to TRUE to skip MUI's private edit hook completely. Otherwise, your hook will be executed and the private one of MUI.

MUIA_String_MaxLen

NAME

MUIA_String_MaxLen -- V4 [I.G], LONG, 0x80424984

FUNCTION

Setup the maximum length for the string gadget. This attribute is only valid at object creation time.

Defaults to 80 characters.

NOTES

The maximum length includes the 0-byte at the end of the string. To let the user enter e.g. 10 characters, you would have to specify a maximum length len of 11.

MUIA_String_Placeholder

NAME

MUIA_String_Placeholder -- V21 [ISG], CONST_STRPTR, 0x8042ae65

FUNCTION

In case the string object is inactive and no text has been entered by the user or set by the application the text specified by this attribute is displayed instead. To improve the visual feedback the text will be displayed with italic style and shadow color. The supplied string is NOT copied and must remain valid as long as the string object lives.

MUIA_String_Reject

NAME

MUIA_String_Reject -- V4 [ISG], STRPTR, 0x8042179c

FUNCTION

A string containing characters that should not be accepted as input for the string gadget. Whenever the user hits such a char, he will hear a beep and the gadget's contents won't be changed. The supplied string is NOT copied and must remain valid as long as the string object lives. Pass a NULL pointer to let String class reject no characters (the default).

MUIA_String_Secret

NAME

MUIA_String_Secret -- V4 [ISG], BOOL, 0x80428769

FUNCTION

This attribute causes the string gadget to display only dots instead of the real contents. Useful for password requesters.

MUI_String

String.mui

Super class

Background

Attributes

MUIA_String_Accept

NAME

FUNCTION

EXAMPLE

SEE ALSO

MUIA_String_Acknowledge

NAME

FUNCTION

EXAMPLE

SEE ALSO

MUIA_String_AdvanceOnCR

NAME

FUNCTION

SEE ALSO

MUIA_String_AttachedList

NAME

FUNCTION

SEE ALSO

MUIA_String_BufferPos

NAME

FUNCTION

SEE ALSO

MUIA_String_Contents

NAME

FUNCTION

NOTES

EXAMPLE

SEE ALSO

MUIA_String_DisplayPos

NAME

FUNCTION

SEE ALSO

MUIA_String_EditHook

NAME

FUNCTION

NOTES

SEE ALSO

MUIA_String_Format

NAME

SPECIAL INPUTS

FUNCTION

SEE ALSO

MUIA_String_InactiveContents

NAME

FUNCTION

SEE ALSO

MUIA_String_Integer

NAME

FUNCTION

EXAMPLE

MUIA_String_Integer64

NAME

FUNCTION

EXAMPLE

MUIA_String_LonelyEditHook

NAME

FUNCTION

MUIA_String_MaxLen

NAME

FUNCTION

NOTES

SEE ALSO

MUIA_String_Placeholder

NAME

FUNCTION

SEE ALSO

MUIA_String_Reject

NAME

FUNCTION

SEE ALSO

MUIA_String_Secret

NAME

FUNCTION

SEE ALSO

Clone this wiki locally