Button.SendToBack Method

Definition

Namespace:

Microsoft.Office.Tools.Excel.Controls

Assembly:

Microsoft.Office.Tools.Excel.v4.0.Utilities.dll

Sends the Button to the back of the z-order.

public:
 System::Object ^ SendToBack();

public object SendToBack ();

override this.SendToBack : unit -> obj

Public Function SendToBack () As Object

Returns

Object

This method returns a null reference (Nothing in Visual Basic); otherwise this method returns true.

Examples

The following code example uses the BringToFront and SendToBack methods to set the z-order of three Button controls on a worksheet. If the button currently at the front of the z-order is clicked, then the button is moved to the back of the collection by calling SendToBack. Otherwise, the button is moved to the front of the collection by calling BringToFront. Note that the z-order of the three buttons initially range from 2 to 4. The Runtime Storage Control on the worksheet initially has the z-order position of 1.

This example is for a document-level customization.

private void ToggleZOrder()
{
    Microsoft.Office.Tools.Excel.Controls.Button button1 =
        this.Controls.AddButton(this.Range["A1", "B2"],
        "button1");
    button1.BackColor = Color.Blue;

    Microsoft.Office.Tools.Excel.Controls.Button button2 =
        this.Controls.AddButton(this.Range["B2", "C3"],
        "button2");
    button2.BackColor = Color.Red;

    Microsoft.Office.Tools.Excel.Controls.Button button3 =
        this.Controls.AddButton(this.Range["C3", "D4"],
        "button3");
    button3.BackColor = Color.Green;

    button1.Click += new EventHandler(zOrderButton_Click);
    button2.Click += new EventHandler(zOrderButton_Click);
    button3.Click += new EventHandler(zOrderButton_Click);
}

void zOrderButton_Click(object sender, EventArgs e)
{
    Microsoft.Office.Tools.Excel.Controls.Button clickedButton =
        (Microsoft.Office.Tools.Excel.Controls.Button)sender;

    if (clickedButton.ZOrder == 4)
    {
        clickedButton.SendToBack();
    }
    else
    {
        clickedButton.BringToFront();
    }
}

Private Sub ToggleZOrder()
    Dim Button1 As Microsoft.Office.Tools.Excel.Controls.Button = _
        Me.Controls.AddButton(Me.Range("A1", "B2"), "Button1")
    Button1.BackColor = Color.Blue

    Dim Button2 As Microsoft.Office.Tools.Excel.Controls.Button = _
        Me.Controls.AddButton(Me.Range("B2", "C3"), "Button2")
    Button2.BackColor = Color.Red

    Dim Button3 As Microsoft.Office.Tools.Excel.Controls.Button = _
        Me.Controls.AddButton(Me.Range("C3", "D4"), "Button3")
    Button3.BackColor = Color.Green

    AddHandler Button1.Click, AddressOf ZOrderButton_Click
    AddHandler Button2.Click, AddressOf ZOrderButton_Click
    AddHandler Button3.Click, AddressOf ZOrderButton_Click
End Sub

Private Sub ZOrderButton_Click(ByVal sender As Object, ByVal e As EventArgs)
    Dim ClickedButton As Microsoft.Office.Tools.Excel.Controls.Button = _
        CType(sender, Microsoft.Office.Tools.Excel.Controls.Button)

    If ClickedButton.ZOrder = 4 Then
        ClickedButton.SendToBack()
    Else
        ClickedButton.BringToFront()
    End If
End Sub

Remarks

This method sets the z-order of the Button to the first index in the OLEObjects collection; the numbering of the z-order is the opposite of the numbering of the index in the OLEObjects collection. The higher the index in the OLEObjects collection, the lower the z-order of the Button.