런타임에 Office 문서에 컨트롤 추가

아티클
08/10/2011

런타임에 Microsoft Office Word 문서 및 Microsoft Office Excel 통합 문서에서 컨트롤을 추가하거나 제거할 수 있습니다. 런타임에 문서에 추가하는 컨트롤을 동적 컨트롤이라고 합니다.

적용 대상: 이 항목의 정보는 Excel 2007 및 Excel 2010, Word 2007 및 Word 2010의 문서 수준 프로젝트 및 응용 프로그램 수준 프로젝트에 적용됩니다. 자세한 내용은 Office 응용 프로그램 및 프로젝트 형식에 따라 사용 가능한 기능을 참조하십시오.

이 항목에서는 다음 내용에 대해 설명합니다.

컨트롤 컬렉션을 사용하여 런타임에 컨트롤 관리
문서에 호스트 컨트롤 추가
문서에 Windows Forms 컨트롤 추가

비디오에 링크 관련 비디오 데모를 보려면 How Do I: Add Controls to a Document Surface at Runtime?을 참조하십시오.

컨트롤 컬렉션을 사용하여 런타임에 컨트롤 관리

런타임에 컨트롤을 추가하거나 가져오거나 제거하려면 Microsoft.Office.Tools.Excel.ControlCollection 및 Microsoft.Office.Tools.Word.ControlCollection 개체의 도우미 메서드를 사용합니다.

이러한 개체에 액세스하는 방법은 개발하는 프로젝트의 형식에 따라 달라집니다.

Excel용 문서 수준 프로젝트에서는 Sheet1, Sheet2 및 Sheet3 클래스의 Worksheet.Controls 속성을 사용합니다. 이러한 클래스에 대한 자세한 내용은 워크시트 호스트 항목를 참조하십시오.
Word용 문서 수준 프로젝트에서는 ThisDocument 클래스의 Document.Controls 속성을 사용합니다. 이 클래스에 대한 자세한 내용은 문서 호스트 항목을 참조하십시오.
Excel 또는 Word용 응용 프로그램 수준 프로젝트에서는 런타임에 생성하는 Microsoft.Office.Tools.Excel.Worksheet 또는 Microsoft.Office.Tools.Word.Document의 Controls 속성을 사용합니다. 런타임에 이러한 개체를 생성하는 방법에 대한 자세한 내용은 런타임에 응용 프로그램 수준 추가 기능의 Word 문서 및 Excel 통합 문서 확장을 참조하십시오.

컨트롤 추가

Microsoft.Office.Tools.Excel.ControlCollection 및 Microsoft.Office.Tools.Word.ControlCollection 형식에는 문서 및 워크시트에 호스트 컨트롤과 일반적인 Windows Forms 컨트롤을 추가하는 데 사용할 수 있는 도우미 메서드가 포함되어 있습니다. 각 메서드 이름은 Add<control class> 형식입니다. 여기서 control class는 추가할 컨트롤의 클래스 이름입니다. 예를 들어, NamedRange 컨트롤을 문서에 추가하려면 AddNamedRange 메서드를 사용합니다. 도우미 메서드의 전체 목록은 호스트 컨트롤의 도우미 메서드 및 Windows Forms 컨트롤의 도우미 메서드를 참조하십시오.

다음 코드 예제에서는 Excel용 문서 수준 프로젝트의 Sheet1에 NamedRange를 추가합니다.

Dim range1 As Excel.Range = Globals.Sheet1.Range("A1", "D5")
Dim namedRange1 As Microsoft.Office.Tools.Excel.NamedRange = _
    Globals.Sheet1.Controls.AddNamedRange(range1, "ChartSource")

Excel.Range range1 = Globals.Sheet1.Range["A1", "D5"];
Microsoft.Office.Tools.Excel.NamedRange namedRange1 =
    Globals.Sheet1.Controls.AddNamedRange(range1, "ChartSource");

컨트롤 액세스 및 삭제

Microsoft.Office.Tools.Excel.Worksheet 또는 Microsoft.Office.Tools.Word.Document의 Controls 속성을 사용하여 디자인 타임에 추가한 컨트롤을 비롯하여 문서의 모든 컨트롤을 반복할 수 있습니다. 디자인 타임에 추가하는 컨트롤은 정적 컨트롤이라고도 합니다.

동적 컨트롤은 컨트롤의 Delete 메서드를 호출하거나 각 Controls 컬렉션의 Remove 메서드를 호출하여 제거할 수 있습니다. 다음 코드 예제에서는 Remove 메서드를 사용하여 Excel용 문서 수준 프로젝트의 Sheet1에서 NamedRange를 제거합니다.

Globals.Sheet1.Controls.Remove("ChartSource")

Globals.Sheet1.Controls.Remove("ChartSource");

런타임에 정적 컨트롤을 제거할 수는 없습니다. Delete 또는 Remove 메서드를 사용하여 정적 컨트롤을 제거하려고 하면 CannotRemoveControlException이 throw됩니다.

참고

문서의 Shutdown 이벤트 처리기에서 컨트롤을 프로그래밍 방식으로 제거하지 마십시오. Shutdown 이벤트가 발생할 경우 문서의 UI 요소를 더 이상 사용할 수 없습니다. 문서를 닫기 전에 컨트롤을 제거하려면 Document.BeforeClose 또는 Document.BeforeSave(Word의 경우), Workbook.BeforeClose 또는 Workbook.BeforeSave(Excel의 경우) 등의 다른 이벤트에 대한 이벤트 처리기에 코드를 추가합니다.

문서에 호스트 컨트롤 추가

프로그래밍 방식으로 문서에 호스트 컨트롤을 추가할 때는 컨트롤을 고유하게 식별하는 이름과 컨트롤을 추가할 문서 내의 위치를 지정해야 합니다. 구체적인 지침은 다음 항목을 참조하십시오.

호스트 컨트롤에 대한 자세한 내용은 호스트 항목 및 호스트 컨트롤 개요를 참조하십시오.

문서가 저장된 다음 닫힐 때 동적으로 만들어진 호스트 컨트롤은 모두 이벤트와의 연결이 끊어지고 데이터 바인딩 기능을 잃게 됩니다. 문서가 다시 열릴 때 호스트 컨트롤을 다시 만드는 코드를 솔루션에 추가할 수 있습니다. 자세한 내용은 Office 문서에서 동적 컨트롤 유지를 참조하십시오.

참고

XmlMappedRange, XMLNode 및 XMLNodes 호스트 컨트롤은 문서에 프로그래밍 방식으로 추가할 수 없으므로 이러한 컨트롤의 경우에는 도우미 메서드가 제공되지 않습니다.

문서에 Windows Forms 컨트롤 추가

문서에 Windows Forms 컨트롤을 프로그래밍 방식으로 추가하는 경우에는 컨트롤의 위치와 컨트롤을 고유하게 식별하는 이름을 지정해야 합니다. Microsoft Visual Studio Tools for Office Runtime에서는 각 컨트롤에 대한 도우미 메서드를 제공합니다. 이러한 메서드는 컨트롤의 위치에 대한 특정 좌표나 범위를 전달할 수 있도록 오버로드됩니다. 구체적인 지침은 방법: Office 문서에 Windows Forms 컨트롤 추가를 참조하십시오.

문서가 저장된 다음 닫힐 때 동적으로 만들어진 Windows Forms 컨트롤은 모두 문서에서 제거됩니다. 문서가 다시 열릴 때 컨트롤을 다시 만드는 코드를 솔루션에 추가할 수 있습니다. 응용 프로그램 수준 추가 기능을 사용하여 동적 Windows Forms 컨트롤을 만든 경우 해당 컨트롤에 대한 ActiveX 래퍼는 문서에 남아 있습니다. 자세한 내용은 Office 문서에서 동적 컨트롤 유지를 참조하십시오.

참고

Windows Forms 컨트롤을 보호되는 문서에 프로그래밍 방식으로 추가할 수 없습니다. 프로그래밍 방식으로 Word 문서나 Excel 워크시트의 보호를 해제하여 컨트롤을 추가하려면 문서를 닫을 때 컨트롤의 ActiveX 래퍼를 제거하는 추가 코드를 작성해야 합니다. 컨트롤의 ActiveX 래퍼는 보호된 문서에서 자동으로 삭제되지 않습니다.

사용자 지정 컨트롤 추가

사용자 정의 컨트롤과 같이 사용 가능한 도우미 메서드에서 지원되지 않는 System.Windows.Forms.Control을 추가하려면 다음과 같은 메서드를 사용합니다.

Excel의 경우 Microsoft.Office.Tools.Excel.ControlCollection 개체의 AddControl() 메서드 중 하나를 사용합니다.
Word의 경우 Microsoft.Office.Tools.Word.ControlCollection 개체의 AddControl() 메서드 중 하나를 사용합니다.

컨트롤을 추가하려면 System.Windows.Forms.Control, 컨트롤의 위치 및 컨트롤을 고유하게 식별하는 이름을 AddControl 메서드에 전달합니다. AddControl 메서드는 컨트롤과 워크시트 또는 문서 간의 상호 작용 방식을 정의하는 개체를 반환합니다. 반환되는 개체의 형식은 프로젝트에 따라 달라집니다.

.NET Framework 4를 대상으로 하는 프로젝트의 경우 이 메서드는 Microsoft.Office.Tools.Excel.ControlSite(Excel) 또는 Microsoft.Office.Tools.Word.ControlSite(Word) 개체를 반환합니다.
.NET Framework 3.5를 대상으로 하는 프로젝트의 경우 이 메서드는 Microsoft.Office.Tools.Excel.OLEObject(Excel) 또는 Microsoft.Office.Tools.Word.OLEControl(Word) 개체를 반환합니다.

다음 코드 예제에서는 AddControl(Control, Range, String) 메서드를 사용하여 .NET Framework 4를 대상으로 하는 문서 수준 Excel 프로젝트의 워크시트에 사용자 지정 사용자 정의 컨트롤을 동적으로 추가하는 방법을 보여 줍니다. 이 예제에서 사용자 정의 컨트롤의 이름은 UserControl1이고 Range의 이름은 range1입니다. 이 예제를 사용하려면 프로젝트의 Sheetn 클래스에서 이 예제를 실행합니다.

Dim customControl As New UserControl1()

Dim dynamicControl As Microsoft.Office.Tools.Excel.ControlSite = _
    Me.Controls.AddControl(customControl, range1, "dynamic")

UserControl1 customControl = new UserControl1();

Microsoft.Office.Tools.Excel.ControlSite dynamicControl =
    this.Controls.AddControl(customControl, range1, "dynamic");

사용자 지정 컨트롤의 멤버 사용

AddControl 메서드 중 하나를 사용하여 워크시트나 문서에 컨트롤을 추가한 후에는 다음과 같은 두 가지 컨트롤 개체가 추가됩니다.

사용자 지정 컨트롤을 나타내는 System.Windows.Forms.Control
컨트롤이 워크시트나 문서에 추가된 후 해당 컨트롤을 나타내는 ControlSite, OLEObject 또는 OLEControl 개체

많은 속성과 메서드는 이러한 컨트롤 사이에서 공유됩니다. 이러한 멤버에는 적절한 컨트롤을 통해 액세스하는 것이 중요합니다.

사용자 지정 컨트롤에만 속하는 멤버에 액세스하려면 System.Windows.Forms.Control을 사용합니다.
컨트롤이 공유하는 멤버에 액세스하려면 ControlSite, OLEObject 또는 OLEControl 개체를 사용합니다.

System.Windows.Forms.Control에서 공유 멤버에 액세스하면 경고나 알림 없이 작업에 실패합니다. 또는 잘못된 결과가 생성될 수 있습니다. 필요한 메서드나 속성을 사용할 수 없는 경우가 아니라면 항상 ControlSite, OLEObject 또는 OLEControl 개체의 메서드 또는 속성을 사용합니다. 필요한 메서드나 속성을 사용할 수 없는 경우에만 System.Windows.Forms.Control을 참조해야 합니다.

예를 들어, ControlSite 클래스와 System.Windows.Forms.Control 클래스는 모두 Top 속성을 사용합니다. 컨트롤의 맨 위와 문서의 맨 위 사이의 거리를 가져오거나 설정하려면 System.Windows.Forms.Control의 Top 속성이 아니라 ControlSite의 Top 속성을 사용합니다.

' Property is set in relation to the document.
dynamicControl.Top = 100

' Property is set in relation to the container control.
customControl.Top = 100

// Property is set in relation to the document.
dynamicControl.Top = 100;

// Property is set in relation to the container control.
customControl.Top = 100;

참고 항목