2.2.

20 editBox (Edit Box)

Article • 08/17/2021

This element specifies an edit box control that allows a user to enter a string of text.

For example, consider an edit box control, as follows:

Figure 11: An edit box control

This is specified using the following XML fragment:

<editBox id="editBox" label="Edit Box" />

The following table summarizes the elements that are parents of this element.

ﾉ Expand table

Parent Elements

box (section 2.2.1); group (section 2.2.23)

The following table summarizes the attributes of this element.

ﾉ Expand table

Attributes Description

enabled (Enabled State) Specifies the enabled state of the control.

The getEnabled and enabled attributes are mutually exclusive. If neither

attribute is specified, the control SHOULD default to being enabled.

This attribute cannot be used to enable a built-in control that would

otherwise be disabled by the application.

For example, consider the following XML fragment:

Attributes Description

<button id="button" label="Disabled Button"

enabled="false" />

This specifies a new button that is disabled. A permanently disabled

button is not very useful, thus the enabled attribute is not commonly
used.

The possible values for this attribute are defined by the XML schema
boolean datatype.

getEnabled (getEnabled Specifies the name of a callback function to be called to determine the
callback) enabled state of this control.

The getEnabled and enabled attributes are mutually exclusive. If neither

attribute is specified, the control SHOULD default to being enabled.

For example, consider the following XML fragment:

<button id="button"
getEnabled="IsButtonEnabled" />

In this example, the IsButtonEnabled callback function is called when the

application needs to determine the enabled state of the button.

The possible values for this attribute are defined by the ST_Delegate
simple type, as specified in section 2.3.2.

getImage (getImage Specifies the name of a callback function to be called to determine the
callback) icon of this control.

The getImage, image, and imageMso attributes are mutually exclusive. If

none of these attributes are specified, no icon SHOULD be displayed.

For example, consider the following XML fragment:

<button id="button" getImage="GetButtonImage"

/>

In this example, the GetButtonImage callback function is called when the

application needs to determine the icon of the button.

The possible values for this attribute are defined by the ST_Delegate
simple type, as specified in section 2.3.2.
Attributes Description

getKeytip (getKeytip Specifies the name of a callback function to be called to determine the
callback) suggested KeyTip of this control.

The getKeytip and keytip attributes are mutually exclusive. If neither

attribute is specified, the application SHOULD generate a KeyTip for the
control automatically.

For example, consider the following XML fragment:

<button id="button"
getKeytip="GetButtonKeytip" />

In this example, the GetButtonKeytip callback function is called when the

application needs to determine the KeyTip of the button.

The possible values for this attribute are defined by the ST_Delegate
simple type, as specified in section 2.3.2.

getLabel (getLabel Specifies the name of a callback function to be called to determine the
callback) label of this control.

The getLabel and label attributes are mutually exclusive. If neither

attribute is specified, no label SHOULD be displayed.

For example, consider the following XML fragment:

<button id="button" getLabel="GetButtonLabel"

/>

In this example, the GetButtonLabel callback function is called when the

application needs to determine the label of the button.

The possible values for this attribute are defined by the ST_Delegate
simple type, as specified in section 2.3.2.

getScreentip Specifies the name of a callback function to be called to determine the

(getScreentip callback) screentip of this control.

The getScreentip and screentip attributes are mutually exclusive. If

neither attribute is specified, the application SHOULD display the label of
the control as the screentip or display no screentip at all.

For example, consider the following XML fragment:

Attributes Description

<button id="button"
getScreentip="GetButtonScreentip" />

In this example, the GetButtonScreentip callback function is called when

the application needs to determine the screentip of the button.

The possible values for this attribute are defined by the ST_Delegate
simple type, as specified in section 2.3.2.

getShowImage Specifies the name of a callback function to be called to determine

(getShowImage whether the application SHOULD display the icon of this control.
callback)
The showImage and getShowImage attributes are mutually exclusive. If
neither attribute is specified, the control SHOULD display its icon.

For example, consider the following XML fragment:

<button id="button"
getShowImage="IsButtonImageVisible" />

In this example, the IsButtonImageVisible callback function is called

when the application needs to determine whether to display the icon of
the button.

The possible values for this attribute are defined by the ST_Delegate
simple type, as specified in section 2.3.2.

getShowLabel Specifies the name of a callback function to be called to determine

(getShowLabel callback) whether the application SHOULD display the label of this control.

The showLabel and getShowLabel attributes are mutually exclusive. If

neither attribute is specified, the control SHOULD default to showing its
label.

For example, consider the following XML fragment:

<button id="button"
getShowLabel="IsButtonLabelVisible" />

In this example, the IsButtonLabelVisible callback function is called when

the application needs to determine whether to display the label of the
button.
Attributes Description
The possible values for this attribute are defined by the ST_Delegate
simple type, as specified in section 2.3.2.

getSupertip Specifies the name of a callback function to be called to determine the

(getSupertip callback) supertip of this control.

The getSupertip and supertip attributes are mutually exclusive. If neither

attribute is specified, no supertip for this control SHOULD be shown.

For example, consider the following XML fragment:

<button id="button"
getSupertip="GetButtonSupertip" />

In this example, the GetButtonSupertip callback function is called when

the application needs to determine the supertip of the button.

The possible values for this attribute are defined by the ST_Delegate
simple type, as specified in section 2.3.2.

getText (getText Specifies the name of a callback function to be called to determine the
callback) text that SHOULD be displayed in the control.

For example, consider the following XML fragment:

<editBox id="editBox" getText="GetEditBoxText"

/>

In this example, the GetEditBoxText callback function is called when the

application needs to determine the text to display in the control.

The possible values for this attribute are defined by the ST_Delegate
simple type, as specified in section 2.3.2.

getVisible (getVisible Specifies the name of a callback function to be called to determine the
callback) visibility state of this control.

The getVisible and visible attributes are mutually exclusive. If neither

attribute is specified, the control SHOULD default to being visible.

For example, consider the following XML fragment:

<button id="button"
Attributes Description
getVisible="IsButtonVisible" />

In this example, the IsButtonVisible callback function is called when the

application needs to determine the visibility of the button.

The possible values for this attribute are defined by the ST_Delegate
simple type, as specified in section 2.3.2.

id (control identifier) Specifies the identifier for a custom control. All custom controls MUST
have unique identifiers. The identifier of a control SHOULD be passed to
callback functions to identify which control corresponds to the function
call.

The id, idQ, and idMso attributes are mutually exclusive. At least one of
these attributes MUST be specified.

For example, consider the following XML fragment:

<button id="MyButton" label="Button" />

This specifies a custom button control with an identifier of "MyButton".

The possible values for this attribute are defined by the ST_UniqueID
simple type, as specified in section 2.3.13.

idMso (built-in control Specifies the identifier of a built-in control.

identifier)
The contents of this attribute are application-defined.

The id, idQ, and idMso attributes are mutually exclusive. At least one of
these attributes MUST be specified.

For example, consider the following XML fragment:

<control idMso="Bold" />

This creates a clone of the control with an identifier of "Bold".

The possible values for this attribute are defined by the ST_ID simple
type, as specified in section 2.3.5.

idQ (qualified control Specifies a qualified identifier for a control.

identifier)
Attributes Description
The idQ attribute can be used to reference controls or containers created
by other Custom UI documents.

The id, idQ, and idMso attributes are mutually exclusive. At least one of
these attributes MUST be specified.

For example, consider the following XML fragment:

<customUI

xmlns="http://schemas.microsoft.com/office/2006/0
1/customui"
xmlns:ex="http://www.example.com">
<ribbon>
<tabs>
<tab idQ="ex:OtherTab" label="Shared
Tab">
<group id="MyGroup" label="My Group">
…
</group>
</tab>
</tabs>
</ribbon>
</customUI>

In this case, ex is an XML namespace prefix for the namespace

http://www.example.com. This XML fragment refers to a tab in that
namespace with an identifier of "OtherTab". If that tab cannot be found, it
is created. A new group belonging to this file is added to the tab.

The possible values for this attribute are defined by the ST_QID simple
type, as specified in section 2.3.9.

image (custom image Specifies the relationship identifier for an image which SHOULD be used
identifier) as the icon for this control. This attribute is used to specify an embedded
picture that resides locally within the containing file.

The getImage, image, and imageMso attributes are mutually exclusive. If

none of these attributes are specified, no icon SHOULD be displayed.

For example, consider the following XML fragment:

<button id="button" image="ForestPic" />

Attributes Description
This specifies a custom button whose icon SHOULD be the embedded
image file referenced by the relationship identifier of "ForestPic".

The possible values for this attribute are defined by the ST_Uri simple
type, as specified in section 2.3.14.

imageMso (built-in Specifies the identifier of a built-in image which SHOULD be used as the
image identifier) icon of this control.

The contents of this attribute are application-defined and SHOULD be

ignored if not understood.

The getImage, image, and imageMso attributes are mutually exclusive. If

none of these attributes are specified, no icon SHOULD be displayed.

For example, consider the following XML fragment:

<button id="button" imageMso="Bold" />

This specifies a custom button that SHOULD use the built-in image with
an identifier of "Bold".

The possible values for this attribute are defined by the ST_ID simple
type, as specified in section 2.3.5.

insertAfterMso Specifies the identifier of a built-in control that this control SHOULD be
(identifier of built-in inserted after. If the value of this attribute is not understood, it SHOULD
control to insert after) be ignored.

The insertAfterMso, insertAfterQ, insertBeforeMso, and insertBeforeQ

attributes are mutually exclusive. If none of these attributes are specified,
the controls SHOULD be appended to the existing set of controls, in the
order they are defined in the XML.

For example, consider the following XML fragment:

<tab id="MyTab" insertAfterMso="TabHome"

label="Custom Tab">
…
</tab>

In this example, a new custom tab with an identifier of "MyTab" is to be

inserted after the built-in tab with an identifier of "TabHome".
Attributes Description
The possible values for this attribute are defined by the ST_ID simple
type, as specified in section 2.3.5.

insertAfterQ (qualified Specifies the qualified identifier of a control that this control SHOULD be
identifier of control to inserted after. If the value of this attribute is not understood, it SHOULD
insert after) be ignored.

The insertAfterMso, insertAfterQ, insertBeforeMso, and insertBeforeQ

attributes are mutually exclusive. If none of these attributes are specified,
the controls SHOULD be appended to the existing set of controls, in the
order they are defined in the XML.

For example, consider the following XML fragment:

<tab id="MyTab" insertAfterQ="x:OtherTab"

label="Custom Tab">
…
</tab>

In this example, a new custom tab with an identifier of "MyTab" is to be

inserted after the custom tab with a qualified identifier of "x:OtherTab".

The possible values for this attribute are defined by the ST_QID simple
type, as specified in section 2.3.9.

insertBeforeMso Specifies the identifier of a built-in control that this control SHOULD be
(identifier of built-in inserted before. If the value of this attribute is not understood, it SHOULD
control to insert before) be ignored.

The insertAfterMso, insertAfterQ, insertBeforeMso, and insertBeforeQ

attributes are mutually exclusive. If none of these attributes are specified,
the controls SHOULD be appended to the existing set of controls, in the
order they are defined in the XML.

For example, consider the following XML fragment:

<tab id="MyTab" insertBeforeMso="TabHome"

label="Custom Tab">
…
</tab>

In this example, a new custom tab with an identifier of "MyTab" is to be

inserted before the built-in tab with an identifier of "TabHome".
Attributes Description
The possible values for this attribute are defined by the ST_ID simple
type, as specified in section 2.3.5.

insertBeforeQ (qualified Specifies the qualified identifier of a control that this control SHOULD be
identifier of control to inserted before. If the value of this attribute is not understood, it SHOULD
insert before) be ignored.

The insertAfterMso, insertAfterQ, insertBeforeMso, and insertBeforeQ

attributes are mutually exclusive. If none of these attributes are specified,
the controls SHOULD be appended to the existing set of controls, in the
order they are defined in the XML.

For example, consider the following XML fragment:

<tab id="MyTab" insertBeforeQ="x:OtherTab"

label="Custom Tab">
…
</tab>

In this example, a new custom tab with an identifier of "MyTab" is to be

inserted before the custom tab with a qualified identifier of "x:OtherTab".

The possible values for this attribute are defined by the ST_QID simple
type, as specified in section 2.3.9.

keytip (keytip) Specifies a string to be used as the suggested KeyTip for this control.

The keytip and getKeytip attributes are mutually exclusive. If neither

attribute is specified, the application SHOULD generate a KeyTip for the
control automatically.

For example, consider a button with KeyTip 'K', as follows:

This is specified using the following XML fragment:

<button id="button" imageMso="HappyFace"

keytip="K" />

The possible values for this attribute are defined by the ST_Keytip simple
type, as specified in section 2.3.7.
Attributes Description

label (label) Specifies a string to be used as the label for this control.

The label and getLabel attributes are mutually exclusive. If neither

attribute is specified, no label SHOULD be displayed.

For example, consider the following XML fragment:

<button id="button" label="Custom Button" />

This specifies a custom button with a label of "Custom Button".

The possible values for this attribute are defined by the ST_String simple
type, as specified in section 2.3.11.

maxLength (maximum Specifies an integer to be used as the maximum length of a string that
input string length) can be entered into the control.

If the maxLength attribute is omitted, the length of the input string

SHOULD NOT be limited except by application-specific constraints.

For example, consider the following XML fragment:

<editBox id="editBox" maxLength="10" />

This specifies an edit box control that can only accept strings up to 10
characters in length.

The possible values for this attribute are defined by the ST_StringLength
simple type, as specified in section 2.3.12.

onChange (onChange Specifies the name of a callback function to be called when the text in the
callback) control has been changed by the user.

For example, consider the following XML fragment:

<editBox id="editBox"
onChange="EditBoxTextChanged" />

This specifies an edit box control that calls the EditBoxTextChanged

callback function when the user inputs a text string.

The possible values for this attribute are defined by the ST_Delegate
simple type, as specified in section 2.3.2.
Attributes Description

screentip (screentip) Specifies a string to be shown as the screentip for this control.

The screentip and getScreentip attributes are mutually exclusive. If

neither attribute is specified, the application SHOULD display the label of
the control as the screentip or display no screentip at all.

For example, consider a button with a screentip, as follows:

This is specified using the following XML fragment:

<button id="button" imageMso="HappyFace"

label="Button"
size="large" screentip="This is the screen-
tip" />

The possible values for this attribute are defined by the ST_String simple
type, as specified in section 2.3.11.

showImage (show Specifies whether this control displays an icon.

image)
The showImage and getShowImage attributes are mutually exclusive. If
neither attribute is specified, the control SHOULD display its icon.

For example, consider a button that does not display an icon, as follows:

This is specified using the following XML fragment:

<button id="button" showImage="false"

label="Button with no icon" />
Attributes Description
The possible values for this attribute are defined by the XML schema
boolean datatype.

showLabel (Show Label) Specifies whether this control displays its label.

The showLabel and getShowLabel attributes are mutually exclusive. If

neither attribute is specified, the control SHOULD default to showing its
label.

For example, consider the following XML fragment:

<button id="button" label="Label"

showLabel="false"
imageMso="HappyFace" />

This specifies a button that has a label, but does not show it. Even
though the label is hidden, it is provided to accessibility tools.

The possible values for this attribute are defined by the XML schema
boolean datatype.

sizeString (size string) Specifies a string whose size is used to determine the width of the text
input area of this control.

If this attribute is omitted, the application SHOULD determine the width

of the text input area of the control automatically.

For example, consider the following XML fragment:

<editBox id="editBox"
sizeString="WWWWWWWWWWWWW" />

This specifies an edit box control that is wide enough to display the
string "WWWWWWWWWWWWW".

The possible values for this attribute are defined by the ST_String simple
type, as specified in section 2.3.11.

supertip (supertip) Specifies a string to be shown as the supertip of the control.

The supertip and getSupertip attributes are mutually exclusive. If neither

attribute is specified no supertip for this control SHOULD be shown.

For example, consider a control with a supertip, as follows:

Attributes Description

This is specified using the following XML fragment:

<button id="button" imageMso="HappyFace"

label="Button"
size="large" screentip="Screentip"
supertip="This is the supertip string" />

The possible values for this attribute are defined by the ST_String simple
type, as specified in section 2.3.11.

tag (tag) Specifies an arbitrary string that can be used to hold data or identify the
control. The contents of this attribute SHOULD be passed to any callback
functions specified on this control.

If this attribute is omitted, the control's tag value SHOULD default to an

empty string.

For example, consider the following XML fragment:

<button id="button" label="Button"

tag="123456"
onAction="ButtonClicked" />

This specifies a button with a tag value of "123456", which is passed to

the ButtonClicked callback function.

The possible values for this attribute are defined by the ST_String simple
type, as specified in section 2.3.11.

visible (control visibility) Specifies the visibility state of the control.

The getVisible and visible attributes are mutually exclusive. If these

attributes are omitted, the control SHOULD default to being visible.
 Attributes Description
For example, consider the following XML fragment:

<tab idMso="TabHome" visible="false" />

In this example, the built-in tab with an identifier of "TabHome" is hidden.

The possible values for this attribute are defined by the XML schema
boolean datatype.

The following XML schema fragment defines the contents of this element:

<xsd:complexType name="CT_EditBox">
<xsd:complexContent>
<xsd:extension base="CT_Control">
<xsd:attributeGroup ref="AG_Enabled"/>
<xsd:attributeGroup ref="AG_Image"/>
<xsd:attribute name="maxLength" type="ST_StringLength"
use="optional"/>
<xsd:attribute name="getText" type="ST_Delegate" use="optional"/>
<xsd:attribute name="onChange" type="ST_Delegate" use="optional"/>
<xsd:attribute name="sizeString" type="ST_String" use="optional"/>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>