From be103da07eabc3ac114fd469c7f5a5c93b5b68d2 Mon Sep 17 00:00:00 2001 From: "Andy (Steve) De George" <67293991+adegeo@users.noreply.github.com> Date: Wed, 16 Mar 2022 09:14:11 -0700 Subject: [PATCH] Replace various WPF include files with content (#1335) * net-current-v30plus-md.md * net-current-v40plus-md.md * tla2sharptla-ui-md.md * tla2sharptla-uiautomation-md.md * tla2sharptla-winclient-md.md * tla2sharptla-xaml-md.md * tlasharptla-ui-md.md * tlasharptla-uiautomation-md.md * tlasharptla-winclient-md.md * tlasharptla-xaml-md.md * fix warnings --- ...te-function-wpf-unmanaged-api-reference.md | 2 +- .../wpf/advanced/advanced-ink-handling.md | 2 +- .../wpf/advanced/advanced-text-formatting.md | 4 +- .../alignment-margins-and-padding-overview.md | 12 +-- .../wpf/advanced/annotations-overview.md | 2 +- .../framework/wpf/advanced/annotations.md | 2 +- .../advanced/attached-properties-overview.md | 8 +- .../wpf/advanced/base-elements-overview.md | 14 ++-- .../bidirectional-features-in-wpf-overview.md | 30 +++---- .../wpf/advanced/binding-markup-extension.md | 2 +- .../wpf/advanced/cleartype-overview.md | 16 ++-- .../advanced/cleartype-registry-settings.md | 10 +-- .../advanced/code-behind-and-xaml-in-wpf.md | 10 +-- .../colorconvertedbitmap-markup-extension.md | 2 +- .../wpf/advanced/commanding-overview.md | 28 +++---- .../componentresourcekey-markup-extension.md | 4 +- ...er-function-wpf-unmanaged-api-reference.md | 2 +- .../advanced/custom-dependency-properties.md | 32 ++++---- .../wpf/advanced/custom-rendering-ink.md | 2 +- .../wpf/advanced/data-and-data-objects.md | 4 +- ...te-function-wpf-unmanaged-api-reference.md | 2 +- .../dependency-properties-overview.md | 4 +- .../advanced/dependency-property-metadata.md | 12 +-- .../advanced/dependency-property-security.md | 2 +- .../dependency-property-value-precedence.md | 18 ++--- .../framework/wpf/advanced/digital-ink.md | 2 +- .../wpf/advanced/documents-in-wpf.md | 24 +++--- .../framework/wpf/advanced/documents.md | 2 +- .../advanced/drag-and-drop-how-to-topics.md | 2 +- .../wpf/advanced/drag-and-drop-overview.md | 10 +-- .../framework/wpf/advanced/drag-and-drop.md | 2 +- .../wpf/advanced/draw-text-using-glyphs.md | 6 +- .../wpf/advanced/drawing-formatted-text.md | 12 +-- .../dynamicresource-markup-extension.md | 8 +- .../framework/wpf/advanced/events-wpf.md | 2 +- .../framework/wpf/advanced/focus-overview.md | 10 +-- .../wpf/advanced/fonts-how-to-topics.md | 2 +- .../framework/wpf/advanced/fonts-wpf.md | 2 +- ...or-function-wpf-unmanaged-api-reference.md | 2 +- .../advanced/framework-property-metadata.md | 12 +-- .../advanced/freezable-objects-overview.md | 4 +- .../globalization-and-localization.md | 2 +- .../wpf/advanced/globalization-for-wpf.md | 30 +++---- .../framework/wpf/advanced/glyphs.md | 2 +- .../wpf/advanced/graphics-rendering-tiers.md | 28 +++---- .../advanced/hosting-win32-content-in-wpf.md | 18 ++--- .../how-to-add-an-event-handler-using-code.md | 6 +- ...an-owner-type-for-a-dependency-property.md | 4 +- ...o-apply-a-focusvisualstyle-to-a-control.md | 2 +- .../how-to-build-a-table-programmatically.md | 2 +- ...-color-of-an-element-using-focus-events.md | 2 +- .../advanced/how-to-change-the-cursor-type.md | 2 +- ...-textwrapping-property-programmatically.md | 2 +- .../how-to-create-a-custom-routed-event.md | 4 +- ...o-create-a-rollover-effect-using-events.md | 2 +- .../advanced/how-to-create-outlined-text.md | 2 +- .../how-to-create-text-with-a-shadow.md | 4 +- .../how-to-define-a-table-with-xaml.md | 2 +- .../how-to-define-and-reference-a-resource.md | 4 +- ...ow-to-detect-when-the-enter-key-pressed.md | 4 +- .../wpf/advanced/how-to-enable-a-command.md | 4 +- ...e-visual-styles-in-a-hybrid-application.md | 4 +- .../advanced/how-to-enumerate-system-fonts.md | 2 +- .../how-to-find-an-element-by-its-name.md | 2 +- .../advanced/how-to-handle-a-loaded-event.md | 2 +- .../advanced/how-to-handle-a-routed-event.md | 4 +- ...mmand-to-a-control-with-command-support.md | 4 +- ...nd-to-a-control-with-no-command-support.md | 4 +- .../how-to-implement-a-dependency-property.md | 2 +- .../advanced/how-to-invoke-a-print-dialog.md | 2 +- ...make-an-object-follow-the-mouse-pointer.md | 4 +- ...hat-is-dropped-on-a-richtextbox-control.md | 2 +- ...ride-metadata-for-a-dependency-property.md | 2 +- ...how-to-programmatically-print-xps-files.md | 4 +- .../how-to-register-an-attached-property.md | 4 +- .../wpf/advanced/how-to-rotate-ink.md | 2 +- ...to-set-margins-of-elements-and-controls.md | 2 +- .../how-to-use-a-grid-for-automatic-layout.md | 4 +- ...-to-manage-localizable-string-resources.md | 2 +- .../how-to-use-a-thicknessconverter-object.md | 2 +- .../how-to-use-application-resources.md | 2 +- ...use-automatic-layout-to-create-a-button.md | 4 +- .../advanced/how-to-use-system-fonts-keys.md | 2 +- .../how-to-use-system-parameters-keys.md | 2 +- .../wpf/advanced/how-to-use-systemfonts.md | 4 +- .../advanced/how-to-use-systemparameters.md | 4 +- .../how-to-use-the-fontsizeconverter-class.md | 2 +- ...r-object-elements-not-in-an-object-tree.md | 8 +- .../advanced/inline-styles-and-templates.md | 6 +- .../framework/wpf/advanced/input-overview.md | 50 ++++++------ ...-the-glyphrun-object-and-glyphs-element.md | 12 +-- ...ations-for-the-windowsformshost-element.md | 30 +++---- .../framework/wpf/advanced/layout.md | 4 +- ...ry-function-wpf-unmanaged-api-reference.md | 2 +- .../localization-attributes-and-comments.md | 2 +- ...ed-events-as-handled-and-class-handling.md | 14 ++-- .../wpf/advanced/mc-ignorable-attribute.md | 12 +-- .../advanced/mc-processcontent-attribute.md | 6 +- .../advanced/merged-resource-dictionaries.md | 14 ++-- .../migration-and-interoperability.md | 12 +-- .../wpf/advanced/object-lifetime-events.md | 6 +- .../wpf/advanced/opentype-font-features.md | 6 +- ...ing-performance-2d-graphics-and-imaging.md | 18 ++--- ...izing-performance-application-resources.md | 4 +- .../optimizing-performance-data-binding.md | 12 +-- ...ptimizing-performance-layout-and-design.md | 2 +- .../optimizing-performance-object-behavior.md | 10 +-- ...izing-performance-other-recommendations.md | 4 +- ...erformance-taking-advantage-of-hardware.md | 14 ++-- .../advanced/optimizing-performance-text.md | 20 ++--- .../optimizing-wpf-application-performance.md | 4 +- .../packaging-fonts-with-applications.md | 16 ++-- .../framework/wpf/advanced/performance.md | 2 +- .../planning-for-application-performance.md | 4 +- .../presentationoptions-freeze-attribute.md | 4 +- .../framework/wpf/advanced/preview-events.md | 4 +- .../wpf/advanced/printing-how-to-topics.md | 4 +- .../wpf/advanced/printing-overview.md | 6 +- ...on-function-wpf-unmanaged-api-reference.md | 2 +- .../framework/wpf/advanced/properties-wpf.md | 2 +- .../wpf/advanced/property-change-events.md | 4 +- .../advanced/property-value-inheritance.md | 6 +- .../wpf/advanced/propertypath-xaml-syntax.md | 16 ++-- .../read-only-dependency-properties.md | 2 +- .../relativesource-markupextension.md | 2 +- .../wpf/advanced/resources-and-code.md | 10 +-- .../wpf/advanced/routed-events-overview.md | 54 ++++++------- ...structor-patterns-for-dependencyobjects.md | 4 +- .../wpf/advanced/sample-opentype-font-pack.md | 4 +- ...ry-function-wpf-unmanaged-api-reference.md | 2 +- ...lization-limitations-of-xamlwriter-save.md | 12 +-- ...ow-function-wpf-unmanaged-api-reference.md | 2 +- ...ing-message-loops-between-win32-and-wpf.md | 6 +- .../staticresource-markup-extension.md | 8 +- .../framework/wpf/advanced/storing-ink.md | 2 +- ...-focus-in-controls-and-focusvisualstyle.md | 2 +- .../framework/wpf/advanced/table-overview.md | 2 +- .../advanced/technology-regions-overview.md | 16 ++-- .../templatebinding-markup-extension.md | 2 +- ...-model-windows-forms-and-com-versus-wpf.md | 2 +- .../wpf/advanced/the-ink-threading-model.md | 2 +- .../themedictionary-markup-extension.md | 4 +- .../framework/wpf/advanced/threading-model.md | 66 ++++++++-------- .../framework/wpf/advanced/trees-in-wpf.md | 14 ++-- .../troubleshooting-hybrid-applications.md | 22 +++--- .../wpf/advanced/typography-how-to-topics.md | 2 +- .../wpf/advanced/typography-in-wpf.md | 24 +++--- .../framework/wpf/advanced/typography.md | 2 +- .../advanced/use-automatic-layout-overview.md | 4 +- .../visual-basic-and-wpf-event-handling.md | 10 +-- ...arranging-windows-forms-controls-in-wpf.md | 14 ++-- ...-binding-to-data-in-hybrid-applications.md | 2 +- ...g-application-data-in-a-wpf-application.md | 2 +- ...h-creating-your-first-touch-application.md | 6 +- ...nabling-drag-and-drop-on-a-user-control.md | 2 +- ...-wpf-composite-control-in-windows-forms.md | 10 +-- ...kthrough-hosting-a-win32-control-in-wpf.md | 2 +- ...-windows-forms-composite-control-in-wpf.md | 22 +++--- ...dows-forms-control-in-wpf-by-using-xaml.md | 4 +- ...-hosting-a-windows-forms-control-in-wpf.md | 4 +- ...alkthrough-hosting-a-wpf-clock-in-win32.md | 38 ++++----- ...-wpf-composite-control-in-windows-forms.md | 36 ++++----- ...rough-hosting-an-activex-control-in-wpf.md | 4 +- ...alkthrough-hosting-wpf-content-in-win32.md | 78 +++++++++---------- ...through-localizing-a-hybrid-application.md | 10 +-- ...roperties-using-the-elementhost-control.md | 12 +-- ...ties-using-the-windowsformshost-element.md | 6 +- .../wpf/advanced/weak-event-patterns.md | 4 +- ...wpf-interoperability-input-architecture.md | 30 +++---- .../windows-forms-and-wpf-property-mapping.md | 16 ++-- ...ms-controls-and-equivalent-wpf-controls.md | 10 +-- .../advanced/wpf-and-win32-interoperation.md | 68 ++++++++-------- .../wpf-and-windows-forms-interoperation.md | 72 ++++++++--------- .../wpf/advanced/wpf-architecture.md | 2 +- ...globalization-and-localization-overview.md | 64 +++++++-------- .../wpf/advanced/wpf-xaml-namescopes.md | 12 +-- .../xaml-and-custom-classes-for-wpf.md | 18 ++--- .../framework/wpf/advanced/xaml-in-wpf.md | 2 +- .../xaml-loading-and-dependency-properties.md | 10 +-- ...aces-and-namespace-mapping-for-wpf-xaml.md | 2 +- .../build-and-deploy-how-to-topics.md | 2 +- .../building-a-wpf-application-wpf.md | 32 ++++---- .../deploying-a-wpf-application-wpf.md | 8 +- .../app-development/dialog-boxes-overview.md | 2 +- ...s-to-support-net-application-deployment.md | 4 +- .../how-to-call-a-page-function.md | 2 +- ...-and-iis-6-0-to-deploy-wpf-applications.md | 4 +- .../framework/wpf/app-development/index.md | 2 +- .../wpf/app-development/iwpfhostsupport.md | 2 +- .../navigation-how-to-topics.md | 2 +- .../app-development/navigation-overview.md | 46 +++++------ .../navigation-topologies-overview.md | 8 +- .../wpf/app-development/pack-uris-in-wpf.md | 26 +++---- .../structured-navigation-overview.md | 2 +- .../window-management-how-to-topics.md | 2 +- ...ication-resource-content-and-data-files.md | 6 +- .../wpf-host-presentationhost-exe.md | 2 +- .../app-development/wpf-windows-overview.md | 18 ++--- .../framework/wpf/class-library-wpf.md | 2 +- .../wpf/controls/adorners-how-to-topics.md | 2 +- .../wpf/controls/adorners-overview.md | 6 +- .../framework/wpf/controls/adorners.md | 2 +- .../framework/wpf/controls/button.md | 2 +- ...ction-in-a-richtextbox-programmatically.md | 2 +- .../framework/wpf/controls/checkbox.md | 2 +- .../wpf/controls/contextmenu-overview.md | 2 +- .../framework/wpf/controls/contextmenu.md | 2 +- .../controls/control-authoring-overview.md | 36 ++++----- .../wpf/controls/control-customization.md | 2 +- ...trol-that-has-a-customizable-appearance.md | 4 +- .../wpf/controls/expander-overview.md | 2 +- ...delines-for-designing-stylable-controls.md | 6 +- .../how-to-adorn-the-children-of-a-panel.md | 2 +- ...properties-to-the-contents-of-a-viewbox.md | 4 +- .../how-to-bind-an-adorner-to-an-element.md | 2 +- ...-a-standard-ui-dialog-box-by-using-grid.md | 2 +- .../controls/how-to-create-a-grid-element.md | 2 +- ...w-to-create-a-multiline-textbox-control.md | 2 +- .../how-to-create-and-use-a-canvas.md | 2 +- ...te-and-use-a-gridlengthconverter-object.md | 2 +- .../wpf/controls/how-to-crop-an-image.md | 2 +- ...tect-when-text-in-a-textbox-has-changed.md | 6 +- ...act-the-text-content-from-a-richtextbox.md | 2 +- .../how-to-handle-the-scrollchanged-event.md | 2 +- ...ertically-align-content-in-a-stackpanel.md | 2 +- ...how-to-make-a-textbox-control-read-only.md | 2 +- ...on-space-by-using-the-dockpanel-element.md | 2 +- .../wpf/controls/how-to-position-a-tooltip.md | 2 +- .../how-to-retrieve-a-text-selection.md | 4 +- ...tent-by-using-the-iscrollinfo-interface.md | 4 +- .../how-to-set-focus-in-a-textbox-control.md | 2 +- ...set-the-height-properties-of-an-element.md | 4 +- ...t-the-text-content-of-a-textbox-control.md | 2 +- ...-set-the-width-properties-of-an-element.md | 4 +- ...ridview-column-when-a-header-is-clicked.md | 2 +- ...se-a-custom-context-menu-with-a-textbox.md | 2 +- ...-use-spell-checking-with-a-context-menu.md | 2 +- ...ntent-scrolling-methods-of-scrollviewer.md | 2 +- .../controls/how-to-use-the-image-element.md | 2 +- .../framework/wpf/controls/image.md | 2 +- .../framework/wpf/controls/index.md | 16 ++-- .../framework/wpf/controls/label.md | 2 +- .../wpf/controls/listview-overview.md | 2 +- ...s-by-using-columndefinitionscollections.md | 2 +- .../framework/wpf/controls/panel.md | 2 +- .../framework/wpf/controls/panels-overview.md | 52 ++++++------- ...-cursor-at-the-beginning-or-end-of-text.md | 2 +- .../wpf/controls/richtextbox-overview.md | 2 +- .../wpf/controls/scrollviewer-overview.md | 6 +- .../wpf/controls/textblock-overview.md | 4 +- .../framework/wpf/controls/textblock.md | 2 +- .../wpf/controls/textbox-overview.md | 4 +- .../wpf/controls/toolbar-overview.md | 2 +- .../wpf/controls/tooltip-overview.md | 2 +- .../wpf/controls/treeview-overview.md | 2 +- .../ui-automation-of-a-wpf-custom-control.md | 12 +-- ...ton-by-using-microsoft-expression-blend.md | 2 +- ...lkthrough-create-a-button-by-using-xaml.md | 6 +- ...hroughs-create-a-custom-animated-button.md | 4 +- .../wpf/controls/wpf-content-model.md | 8 +- .../wpf/data/binding-declarations-overview.md | 2 +- .../wpf/data/binding-sources-overview.md | 8 +- .../how-to-bind-to-an-ado-net-data-source.md | 2 +- ...ng-an-xmldataprovider-and-xpath-queries.md | 6 +- .../wpf/data/how-to-convert-bound-data.md | 2 +- ...ate-and-bind-to-an-observablecollection.md | 4 +- .../how-to-implement-binding-validation.md | 2 +- .../data/how-to-implement-prioritybinding.md | 2 +- ...make-data-available-for-binding-in-xaml.md | 6 +- ...-set-up-notification-of-binding-updates.md | 2 +- ...ort-and-group-data-using-a-view-in-xaml.md | 2 +- .../wpf/data/how-to-sort-data-in-a-view.md | 2 +- .../framework/wpf/data/index.md | 2 +- .../wpf/getting-started/whats-new.md | 2 +- .../wpf/getting-started/wpf-walkthroughs.md | 2 +- .../3-d-graphics-how-to-topics.md | 2 +- .../3-d-graphics-overview.md | 22 +++--- .../3-d-transformations-overview.md | 16 ++-- .../animation-and-timing-how-to-topics.md | 2 +- .../animation-and-timing-system-overview.md | 10 +-- .../graphics-multimedia/animation-overview.md | 28 +++---- .../bitmap-effects-overview.md | 4 +- .../wpf/graphics-multimedia/bitmap-effects.md | 2 +- .../brushes-how-to-topics.md | 2 +- .../wpf/graphics-multimedia/brushes.md | 2 +- .../custom-animations-overview.md | 20 ++--- .../drawing-objects-overview.md | 2 +- .../from-to-by-animations-overview.md | 8 +- .../graphics-multimedia/geometry-overview.md | 8 +- .../graphics-how-to-topics.md | 2 +- .../graphics-rendering-registry-settings.md | 22 +++--- .../wpf/graphics-multimedia/graphics.md | 2 +- .../hit-testing-in-the-visual-layer.md | 2 +- ...nimate-a-property-by-using-a-storyboard.md | 2 +- ...e-a-property-without-using-a-storyboard.md | 2 +- ...ol-a-mediaelement-by-using-a-storyboard.md | 2 +- ...to-control-a-storyboard-after-it-starts.md | 4 +- .../how-to-create-a-cubic-bezier-curve.md | 4 +- ...-create-a-linesegment-in-a-pathgeometry.md | 4 +- .../how-to-create-a-quadratic-bezier-curve.md | 4 +- ...o-create-a-shape-using-a-streamgeometry.md | 2 +- .../how-to-create-an-elliptical-arc.md | 4 +- ...multiple-subpaths-within-a-pathgeometry.md | 2 +- ...osed-shape-by-using-the-polygon-element.md | 2 +- ...-polyline-by-using-the-polyline-element.md | 2 +- ...o-hit-test-using-a-win32-host-container.md | 2 +- .../how-to-load-an-image-as-a-thumbnail.md | 2 +- ...-frame-interval-using-compositiontarget.md | 8 +- .../how-to-use-a-bitmapimage.md | 2 +- ...to-control-a-storyboard-after-it-starts.md | 2 +- .../wpf/graphics-multimedia/images.md | 2 +- .../imaging-how-to-topics.md | 2 +- .../graphics-multimedia/imaging-overview.md | 8 +- .../wpf/graphics-multimedia/index.md | 10 +-- .../key-frame-animations-overview.md | 8 +- .../maximize-wpf-3d-performance.md | 16 ++-- .../multimedia-overview.md | 12 +-- .../opacity-masks-overview.md | 2 +- ...inting-with-images-drawings-and-visuals.md | 8 +- ...ith-solid-colors-and-gradients-overview.md | 12 +-- .../path-animations-overview.md | 12 +-- .../graphics-multimedia/path-markup-syntax.md | 8 +- .../property-animation-techniques-overview.md | 12 +-- ...hapes-and-basic-drawing-in-wpf-overview.md | 8 +- .../wpf/graphics-multimedia/shapes.md | 2 +- .../storyboards-overview.md | 16 ++-- .../timing-behaviors-overview.md | 4 +- .../timing-events-overview.md | 6 +- .../transforms-overview.md | 4 +- ...g-visual-objects-in-a-win32-application.md | 8 +- .../using-drawingvisual-objects.md | 2 +- .../visual-layer-programming.md | 2 +- .../wpf-brushes-overview.md | 2 +- .../wpf-graphics-rendering-overview.md | 42 +++++----- .../framework/wpf/security-wpf.md | 12 +-- .../wpf/wpf-partial-trust-security.md | 2 +- ...wpf-security-strategy-platform-security.md | 2 +- ...-security-strategy-security-engineering.md | 16 ++-- .../includes/net-current-v30plus-md.md | 1 - .../includes/net-current-v40plus-md.md | 1 - .../includes/tla2sharptla-ui-md.md | 1 - .../includes/tla2sharptla-uiautomation-md.md | 1 - .../includes/tla2sharptla-winclient-md.md | 1 - .../includes/tla2sharptla-xaml-md.md | 1 - .../includes/tlasharptla-ui-md.md | 1 - .../includes/tlasharptla-uiautomation-md.md | 1 - .../includes/tlasharptla-winclient-md.md | 1 - .../includes/tlasharptla-xaml-md.md | 1 - .../xaml-services/white-space-processing.md | 14 ++-- .../xaml-services/xarray-markup-extension.md | 2 +- .../xaml-services/xml-language-handling.md | 2 +- .../xaml-services/xname-directive.md | 6 +- .../xaml-services/xshared-attribute.md | 2 +- 353 files changed, 1339 insertions(+), 1349 deletions(-) delete mode 100644 dotnet-desktop-guide/includes/net-current-v30plus-md.md delete mode 100644 dotnet-desktop-guide/includes/net-current-v40plus-md.md delete mode 100644 dotnet-desktop-guide/includes/tla2sharptla-ui-md.md delete mode 100644 dotnet-desktop-guide/includes/tla2sharptla-uiautomation-md.md delete mode 100644 dotnet-desktop-guide/includes/tla2sharptla-winclient-md.md delete mode 100644 dotnet-desktop-guide/includes/tla2sharptla-xaml-md.md delete mode 100644 dotnet-desktop-guide/includes/tlasharptla-ui-md.md delete mode 100644 dotnet-desktop-guide/includes/tlasharptla-uiautomation-md.md delete mode 100644 dotnet-desktop-guide/includes/tlasharptla-winclient-md.md delete mode 100644 dotnet-desktop-guide/includes/tlasharptla-xaml-md.md diff --git a/dotnet-desktop-guide/framework/wpf/advanced/activate-function-wpf-unmanaged-api-reference.md b/dotnet-desktop-guide/framework/wpf/advanced/activate-function-wpf-unmanaged-api-reference.md index de59c7d..e8b5c32 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/activate-function-wpf-unmanaged-api-reference.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/activate-function-wpf-unmanaged-api-reference.md @@ -44,7 +44,7 @@ In the .NET Framework 3.0 and 3.5: PresentationHostDLL.dll In the .NET Framework 4 and later: PresentationHost_v0400.dll -**.NET Framework Version:** [!INCLUDE[net_current_v30plus](../../../includes/net-current-v30plus-md.md)] +**.NET Framework Version:** Available since 3.0 ## See also diff --git a/dotnet-desktop-guide/framework/wpf/advanced/advanced-ink-handling.md b/dotnet-desktop-guide/framework/wpf/advanced/advanced-ink-handling.md index c70a7fc..e35564f 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/advanced-ink-handling.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/advanced-ink-handling.md @@ -10,7 +10,7 @@ helpviewer_keywords: ms.assetid: abc8481a-f983-416f-b051-9168ac8b2ba3 --- # Advanced Ink Handling -The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] ships with the , and is an element you can put in your application to immediately start collecting and displaying ink. However, if the control does not provide a fine enough level of control, you can maintain control at a higher level by customizing your own ink collection and ink rendering classes using . +The WPF ships with the , and is an element you can put in your application to immediately start collecting and displaying ink. However, if the control does not provide a fine enough level of control, you can maintain control at a higher level by customizing your own ink collection and ink rendering classes using . The classes provide a mechanism for implementing low-level control over input and dynamically rendering ink. The class provides a mechanism for you to implement custom behavior and apply it to the stream of data coming from the stylus device for optimal performance. The , a specialized , allows you to customize dynamically rendering ink data in real-time which means that the draws digital ink immediately as data is generated, so it appears to "flow" from the stylus device. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/advanced-text-formatting.md b/dotnet-desktop-guide/framework/wpf/advanced/advanced-text-formatting.md index 15d4fe1..2e61af0 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/advanced-text-formatting.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/advanced-text-formatting.md @@ -11,7 +11,7 @@ helpviewer_keywords: ms.assetid: f0a7986e-f5b2-485c-a27d-f8e922022212 --- # Advanced Text Formatting -Windows Presentation Foundation (WPF) provides a robust set of APIs for including text in your application. Layout and [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] APIs, such as , provide the most common and general-use elements for text presentation. Drawing APIs, such as and , provide a means for including formatted text in drawings. At the most advanced level, WPF provides an extensible text formatting engine to control every aspect of text presentation, such as text store management, text run formatting management, and embedded object management. +Windows Presentation Foundation (WPF) provides a robust set of APIs for including text in your application. Layout and user interface (UI) APIs, such as , provide the most common and general-use elements for text presentation. Drawing APIs, such as and , provide a means for including formatted text in drawings. At the most advanced level, WPF provides an extensible text formatting engine to control every aspect of text presentation, such as text store management, text run formatting management, and embedded object management. This topic provides an introduction to WPF text formatting. It focuses on client implementation and use of the WPF text formatting engine. @@ -24,7 +24,7 @@ Windows Presentation Foundation (WPF) provides a robust set of APIs for includin ## Advanced Text Formatting - The text layout and [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] controls in WPF provide formatting properties that allow you to easily include formatted text in your application. These controls expose a number of properties to handle the presentation of text, which includes its typeface, size, and color. Under ordinary circumstances, these controls can handle the majority of text presentation in your application. However, some advanced scenarios require the control of text storage as well as text presentation. WPF provides an extensible text formatting engine for this purpose. + The text layout and UI controls in WPF provide formatting properties that allow you to easily include formatted text in your application. These controls expose a number of properties to handle the presentation of text, which includes its typeface, size, and color. Under ordinary circumstances, these controls can handle the majority of text presentation in your application. However, some advanced scenarios require the control of text storage as well as text presentation. WPF provides an extensible text formatting engine for this purpose. The advanced text formatting features found in WPF consist of a text formatting engine, a text store, text runs, and formatting properties. The text formatting engine, , creates lines of text to be used for presentation. This is achieved by initiating the line formatting process and calling the text formatter's . The text formatter retrieves text runs from your text store by calling the store's method. The objects are then formed into objects by the text formatter and given to your application for inspection or display. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/alignment-margins-and-padding-overview.md b/dotnet-desktop-guide/framework/wpf/advanced/alignment-margins-and-padding-overview.md index 02c6165..b80f8f9 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/alignment-margins-and-padding-overview.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/alignment-margins-and-padding-overview.md @@ -15,13 +15,13 @@ ms.assetid: 9c6a2009-9b86-4e40-8605-0a2664dc3973 --- # Alignment, Margins, and Padding Overview -The class exposes several properties that are used to precisely position child elements. This topic discusses four of the most important properties: , , , and . The effects of these properties are important to understand, because they provide the basis for controlling the position of elements in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] applications. +The class exposes several properties that are used to precisely position child elements. This topic discusses four of the most important properties: , , , and . The effects of these properties are important to understand, because they provide the basis for controlling the position of elements in Windows Presentation Foundation (WPF) applications. ## Introduction to Element Positioning - There are numerous ways to position elements using [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. However, achieving ideal layout goes beyond simply choosing the right element. Fine control of positioning requires an understanding of the , , , and properties. + There are numerous ways to position elements using WPF. However, achieving ideal layout goes beyond simply choosing the right element. Fine control of positioning requires an understanding of the , , , and properties. The following illustration shows a layout scenario that utilizes several positioning properties. @@ -132,7 +132,7 @@ The class exposes several properties that ## Using Alignment, Margins, and Padding in an Application - , , , and provide the positioning control necessary to create a complex [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)]. You can use the effects of each property to change child-element positioning, enabling flexibility in creating dynamic applications and user experiences. + , , , and provide the positioning control necessary to create a complex user interface (UI). You can use the effects of each property to change child-element positioning, enabling flexibility in creating dynamic applications and user experiences. The following example demonstrates each of the concepts that are detailed in this topic. Building on the infrastructure found in the first sample in this topic, this example adds a element as a child of the in the first sample. is applied to the parent element. The is used to partition space between three child elements. elements are again used to show the various effects of and . elements are added to each to better define the various properties applied to the elements in each column. @@ -141,7 +141,7 @@ The class exposes several properties that [!code-vb[MarginPaddingAlignmentSample#4](~/samples/snippets/visualbasic/VS_Snippets_Wpf/MarginPaddingAlignmentSample/VisualBasic/MarginPaddingAlignment.vb#4)] [!code-xaml[MarginPaddingAlignmentSample#4](~/samples/snippets/xaml/VS_Snippets_Wpf/MarginPaddingAlignmentSample/XAML/default.xaml#4)] - When compiled, the preceding application yields a [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] that looks like the following illustration. The effects of the various property values are evident in the spacing between elements, and significant property values for elements in each column are shown within elements. + When compiled, the preceding application yields a UI that looks like the following illustration. The effects of the various property values are evident in the spacing between elements, and significant property values for elements in each column are shown within elements. ![Several positioning properties in one application](./media/layout-margins-padding-aligment-graphic3.PNG "layout_margins_padding_aligment_graphic3") @@ -149,9 +149,9 @@ The class exposes several properties that ## What's Next - Positioning properties defined by the class enable fine control of element placement within [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications. You now have several techniques you can use to better position elements using [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. + Positioning properties defined by the class enable fine control of element placement within WPF applications. You now have several techniques you can use to better position elements using WPF. - Additional resources are available that explain [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] layout in greater detail. The [Panels Overview](../controls/panels-overview.md) topic contains more detail about the various elements. The topic [Walkthrough: My first WPF desktop application](../getting-started/walkthrough-my-first-wpf-desktop-application.md) introduces advanced techniques that use layout elements to position components and bind their actions to data sources. + Additional resources are available that explain WPF layout in greater detail. The [Panels Overview](../controls/panels-overview.md) topic contains more detail about the various elements. The topic [Walkthrough: My first WPF desktop application](../getting-started/walkthrough-my-first-wpf-desktop-application.md) introduces advanced techniques that use layout elements to position components and bind their actions to data sources. ## See also diff --git a/dotnet-desktop-guide/framework/wpf/advanced/annotations-overview.md b/dotnet-desktop-guide/framework/wpf/advanced/annotations-overview.md index 72772d2..235499b 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/annotations-overview.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/annotations-overview.md @@ -42,7 +42,7 @@ Writing notes or comments on paper documents is such a commonplace activity that ![Highlight Annotation](./media/caf-callouts.png "CAF_Callouts") - Users typically create annotations by first selecting some text or an item of interest, and then right-clicking to display a of annotation options. The following example shows the [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] you can use to declare a with routed commands that users can access to create and manage annotations. + Users typically create annotations by first selecting some text or an item of interest, and then right-clicking to display a of annotation options. The following example shows the Extensible Application Markup Language (XAML) you can use to declare a with routed commands that users can access to create and manage annotations. [!code-xaml[DocViewerAnnotationsXps#CreateDeleteAnnotations](~/samples/snippets/csharp/VS_Snippets_Wpf/DocViewerAnnotationsXps/CSharp/Window1.xaml#createdeleteannotations)] diff --git a/dotnet-desktop-guide/framework/wpf/advanced/annotations.md b/dotnet-desktop-guide/framework/wpf/advanced/annotations.md index aedf61b..880ec40 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/annotations.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/annotations.md @@ -8,7 +8,7 @@ helpviewer_keywords: ms.assetid: 232ad0d7-2264-4bed-aae3-10dfde116a9c --- # Annotations -[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides document viewing controls that support annotating document content. +Windows Presentation Foundation (WPF) provides document viewing controls that support annotating document content. ## In This Section [Annotations Overview](annotations-overview.md) diff --git a/dotnet-desktop-guide/framework/wpf/advanced/attached-properties-overview.md b/dotnet-desktop-guide/framework/wpf/advanced/attached-properties-overview.md index f208afd..278a4cb 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/attached-properties-overview.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/attached-properties-overview.md @@ -12,15 +12,15 @@ ms.assetid: 75928354-dc01-47e8-a018-8409aec1f32d --- # Attached Properties Overview -An attached property is a concept defined by XAML. An attached property is intended to be used as a type of global property that is settable on any dependency object. In [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)], attached properties are typically defined as a specialized form of dependency property that does not have the conventional property "wrapper". +An attached property is a concept defined by XAML. An attached property is intended to be used as a type of global property that is settable on any dependency object. In Windows Presentation Foundation (WPF), attached properties are typically defined as a specialized form of dependency property that does not have the conventional property "wrapper". ## Prerequisites -This article assumes that you understand dependency properties from the perspective of a consumer of existing dependency properties on [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] classes, and have read the [Dependency Properties Overview](dependency-properties-overview.md). To follow the examples in this article, you should also understand XAML and know how to write WPF applications. +This article assumes that you understand dependency properties from the perspective of a consumer of existing dependency properties on Windows Presentation Foundation (WPF) classes, and have read the [Dependency Properties Overview](dependency-properties-overview.md). To follow the examples in this article, you should also understand XAML and know how to write WPF applications. ## Why Use Attached Properties -One purpose of an attached property is to allow different child elements to specify unique values for a property that's defined in a parent element. A specific application of this scenario is having child elements inform the parent element of how they are to be presented in the [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)]. One example is the property. The property is created as an attached property because it is designed to be set on elements that are contained within a rather than on itself. The class defines the static field named , and then provides the and methods as public accessors for the attached property. +One purpose of an attached property is to allow different child elements to specify unique values for a property that's defined in a parent element. A specific application of this scenario is having child elements inform the parent element of how they are to be presented in the user interface (UI). One example is the property. The property is created as an attached property because it is designed to be set on elements that are contained within a rather than on itself. The class defines the static field named , and then provides the and methods as public accessors for the attached property. ## Attached Properties in XAML @@ -40,7 +40,7 @@ Also, because an attached property in XAML is an attribute that you set in marku ### Attached Property Implementation in WPF -In [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)], most of the UI-related attached properties on WPF types are implemented as dependency properties. Attached properties are a XAML concept, whereas dependency properties are a WPF concept. Because WPF attached properties are dependency properties, they support dependency property concepts such as property metadata, and default values from that property metadata. +In Windows Presentation Foundation (WPF), most of the UI-related attached properties on WPF types are implemented as dependency properties. Attached properties are a XAML concept, whereas dependency properties are a WPF concept. Because WPF attached properties are dependency properties, they support dependency property concepts such as property metadata, and default values from that property metadata. ## How Attached Properties Are Used by the Owning Type diff --git a/dotnet-desktop-guide/framework/wpf/advanced/base-elements-overview.md b/dotnet-desktop-guide/framework/wpf/advanced/base-elements-overview.md index 607d808..26160ad 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/base-elements-overview.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/base-elements-overview.md @@ -7,20 +7,20 @@ helpviewer_keywords: ms.assetid: 2c997092-72c6-4767-bc84-74267f4eee72 --- # Base Elements Overview -A high percentage of classes in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] are derived from four classes which are commonly referred to in the SDK documentation as the base element classes. These classes are , , , and . The class is also related, because it is a common base class of both and +A high percentage of classes in Windows Presentation Foundation (WPF) are derived from four classes which are commonly referred to in the SDK documentation as the base element classes. These classes are , , , and . The class is also related, because it is a common base class of both and ## Base Element APIs in WPF Classes - Both and are derived from , through somewhat different pathways. The split at this level deals with how a or are used in a user interface and what purpose they serve in an application. also has in its class hierarchy, which is a class that exposes the lower-level graphics support underlying the [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)]. provides a rendering framework by defining independent rectangular screen regions. In practice, is for elements that will support a larger object model, are intended to render and layout into regions that can be described as rectangular screen regions, and where the content model is deliberately more open, to allow different combinations of elements. does not derive from ; its model is that a would be consumed by something else, such as a reader or viewer that would then interpret the elements and produce the complete for [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] to consume. Certain classes are intended to be content hosts: they provide the hosting and rendering for one or more classes ( is an example of such a class). is used as base class for elements with somewhat smaller object models and that more address the text, information, or document content that might be hosted within a . + Both and are derived from , through somewhat different pathways. The split at this level deals with how a or are used in a user interface and what purpose they serve in an application. also has in its class hierarchy, which is a class that exposes the lower-level graphics support underlying the Windows Presentation Foundation (WPF). provides a rendering framework by defining independent rectangular screen regions. In practice, is for elements that will support a larger object model, are intended to render and layout into regions that can be described as rectangular screen regions, and where the content model is deliberately more open, to allow different combinations of elements. does not derive from ; its model is that a would be consumed by something else, such as a reader or viewer that would then interpret the elements and produce the complete for Windows Presentation Foundation (WPF) to consume. Certain classes are intended to be content hosts: they provide the hosting and rendering for one or more classes ( is an example of such a class). is used as base class for elements with somewhat smaller object models and that more address the text, information, or document content that might be hosted within a . ### Framework-Level and Core-Level - serves as the base class for , and serves as the base class for . The reason for this next level of classes is to support a WPF core level that is separate from a WPF framework level, with this division also existing in how the APIs are divided between the PresentationCore and PresentationFramework assemblies. The WPF framework level presents a more complete solution for basic application needs, including the implementation of the layout manager for presentation. The WPF core level provides a way to use much of [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] without taking the overhead of the additional assembly. The distinction between these levels very rarely matters for most typical application development scenarios, and in general you should think of the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] APIs as a whole and not concern yourself with the difference between WPF framework level and WPF core level. You might need to know about the level distinctions if your application design chooses to replace substantial quantities of WPF framework level functionality, for instance if your overall solution already has its own implementations of [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] composition and layout. + serves as the base class for , and serves as the base class for . The reason for this next level of classes is to support a WPF core level that is separate from a WPF framework level, with this division also existing in how the APIs are divided between the PresentationCore and PresentationFramework assemblies. The WPF framework level presents a more complete solution for basic application needs, including the implementation of the layout manager for presentation. The WPF core level provides a way to use much of WPF without taking the overhead of the additional assembly. The distinction between these levels very rarely matters for most typical application development scenarios, and in general you should think of the WPF APIs as a whole and not concern yourself with the difference between WPF framework level and WPF core level. You might need to know about the level distinctions if your application design chooses to replace substantial quantities of WPF framework level functionality, for instance if your overall solution already has its own implementations of user interface (UI) composition and layout. ## Choosing Which Element to Derive From - The most practical way to create a custom class that extends [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] is by deriving from one of the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] classes where you get as much as possible of your desired functionality through the existing class hierarchy. This section lists the functionality that comes with three of the most important element classes to help you decide which class to inherit from. + The most practical way to create a custom class that extends WPF is by deriving from one of the WPF classes where you get as much as possible of your desired functionality through the existing class hierarchy. This section lists the functionality that comes with three of the most important element classes to help you decide which class to inherit from. - If you are implementing a control, which is really one of the more common reasons for deriving from a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] class, you probably want to derive from a class that is a practical control, a control family base class, or at least from the base class. For some guidance and practical examples, see [Control Authoring Overview](../controls/control-authoring-overview.md). + If you are implementing a control, which is really one of the more common reasons for deriving from a WPF class, you probably want to derive from a class that is a practical control, a control family base class, or at least from the base class. For some guidance and practical examples, see [Control Authoring Overview](../controls/control-authoring-overview.md). If you are not creating a control and need to derive from a class that is higher in the hierarchy, the following sections are intended as a guide for what characteristics are defined in each base element class. @@ -76,7 +76,7 @@ A high percentage of classes in [!INCLUDE[TLA#tla_winclient](../../../includes/t ## Other Base Classes ### DispatcherObject - provides support for the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] threading model and enables all objects created for [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications to be associated with a . Even if you do not derive from , , or , you should consider deriving from in order to get this threading model support. For more information, see [Threading Model](threading-model.md). + provides support for the WPF threading model and enables all objects created for WPF applications to be associated with a . Even if you do not derive from , , or , you should consider deriving from in order to get this threading model support. For more information, see [Threading Model](threading-model.md). ### Visual implements the concept of a 2D object that generally requires visual presentation in a roughly rectangular region. The actual rendering of a happens in other classes (it is not self-contained), but the class provides a known type that is used by rendering processes at various levels. implements hit testing, but it does not expose events that report hit-testing positives (these are in ). For more information, see [Visual Layer Programming](../graphics-multimedia/visual-layer-programming.md). @@ -89,7 +89,7 @@ A high percentage of classes in [!INCLUDE[TLA#tla_winclient](../../../includes/t is a derived class that specifically adds the animation control layer and some utility members so that currently animated properties can be distinguished from nonanimated properties. ### Control - is the intended base class for the type of object that is variously termed a control or component, depending on the technology. In general, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] control classes are classes that either directly represent a UI control or participate closely in control composition. The primary functionality that enables is control templating. + is the intended base class for the type of object that is variously termed a control or component, depending on the technology. In general, WPF control classes are classes that either directly represent a UI control or participate closely in control composition. The primary functionality that enables is control templating. ## See also diff --git a/dotnet-desktop-guide/framework/wpf/advanced/bidirectional-features-in-wpf-overview.md b/dotnet-desktop-guide/framework/wpf/advanced/bidirectional-features-in-wpf-overview.md index 4cc575b..755c924 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/bidirectional-features-in-wpf-overview.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/bidirectional-features-in-wpf-overview.md @@ -8,7 +8,7 @@ ms.assetid: fd850e25-7dba-408c-b521-8873e51dc968 --- # Bidirectional Features in WPF Overview -Unlike any other development platform, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] has many features that support rapid development of bidirectional content, for example, mixed left to right and right to left data in the same document. At the same time, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] creates an excellent experience for users who require bidirectional features such as Arabic and Hebrew speaking users. +Unlike any other development platform, WPF has many features that support rapid development of bidirectional content, for example, mixed left to right and right to left data in the same document. At the same time, WPF creates an excellent experience for users who require bidirectional features such as Arabic and Hebrew speaking users. The following sections explain many bidirectional features together with examples illustrating how to achieve the best display of bidirectional content. Most of the samples use XAML, though you can easily apply the concepts to C# or Microsoft Visual Basic code. @@ -16,7 +16,7 @@ The following sections explain many bidirectional features together with example ## FlowDirection -The basic property that defines the content flow direction in a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application is . This property can be set to one of two enumeration values, or . The property is available to all [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] elements that inherit from . +The basic property that defines the content flow direction in a WPF application is . This property can be set to one of two enumeration values, or . The property is available to all WPF elements that inherit from . The following examples set the flow direction of a element. @@ -32,7 +32,7 @@ The following graphic shows how the previous code renders. ![Graphic that illustrates the different flow directions.](./media/bidirectional-features-in-wpf-overview/left-right-right-left.png) -An element within a [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] tree will inherit the from its container. In the following example, the is inside a , which resides in a . Setting the for the implies setting it for the and as well. +An element within a user interface (UI) tree will inherit the from its container. In the following example, the is inside a , which resides in a . Setting the for the implies setting it for the and as well. The following example demonstrates setting . @@ -50,7 +50,7 @@ The following graphic shows the output of the previous example: Many development platforms such as HTML, Win32 and Java provide special support for bidirectional content development. Markup languages such as HTML give content writers the necessary markup to display text in any required direction, for example the HTML 4.0 tag, "dir" that takes "rtl" or "ltr" as values. This tag is similar to the property, but the property works in a more advanced way to layout textual content and can be used for content other than text. -In [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], a is a versatile [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] element that can host a combination of text, tables, images and other elements. The samples in the following sections use this element. +In UI element that can host a combination of text, tables, images and other elements. The samples in the following sections use this element. Adding text to a can be done in more that one way. A simple way to do so is through a which is a block-level element used to group content such as text. To add text to inline-level elements the samples use and . is an inline-level flow content element used for grouping other inline elements, while a is an inline-level flow content element intended to contain a run of unformatted text. A can contain multiple elements. @@ -92,7 +92,7 @@ The following graphic shows another example that uses numbers and arithmetic exp Users of this application will be disappointed by the output, even though the is correct the numbers are not shaped as Arabic numbers should be shaped. -XAML elements can include an XML attribute (`xml:lang`) that defines the language of each element. XAML also supports a XML language principle whereby `xml:lang` values applied to parent elements in the tree are used by child elements. In the previous example, because a language was not defined for the element or any of its top level elements, the default `xml:lang` was used, which is `en-US` for XAML. The internal number shaping algorithm of [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] selects numbers in the corresponding language – in this case English. To make the Arabic numbers render correctly `xml:lang` needs to be set. +XAML elements can include an XML attribute (`xml:lang`) that defines the language of each element. XAML also supports a XML language principle whereby `xml:lang` values applied to parent elements in the tree are used by child elements. In the previous example, because a language was not defined for the element or any of its top level elements, the default `xml:lang` was used, which is `en-US` for XAML. The internal number shaping algorithm of Windows Presentation Foundation (WPF) selects numbers in the corresponding language – in this case English. To make the Arabic numbers render correctly `xml:lang` needs to be set. The following graphic shows the example with `xml:lang` added. @@ -108,7 +108,7 @@ Be aware that many languages have different `xml:lang` values depending on the t ## FlowDirection with Non-text Elements - defines not only how text flows in a textual element but also the flow direction of almost every other [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] element. The following graphic shows a that uses a horizontal to draw its background with a left to right gradient. + defines not only how text flows in a textual element but also the flow direction of almost every other UI element. The following graphic shows a that uses a horizontal to draw its background with a left to right gradient. ![Graphic that shows a toolbar with a left to right gradient.](./media/bidirectional-features-in-wpf-overview/toolbar-left-right-gradient.png) @@ -132,7 +132,7 @@ There are a few cases where does not behave An represents a control that displays an image. In XAML it can be used with a property that defines the uniform resource identifier (URI) of the to display. -Unlike other [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] elements, an does not inherit the from the container. However, if the is set explicitly to , an is displayed flipped horizontally. This is implemented as a convenient feature for developers of bidirectional content; because in some cases, horizontally flipping the image produces the desired effect. +Unlike other UI elements, an does not inherit the from the container. However, if the is set explicitly to , an is displayed flipped horizontally. This is implemented as a convenient feature for developers of bidirectional content; because in some cases, horizontally flipping the image produces the desired effect. The following graphic shows a flipped . @@ -160,7 +160,7 @@ The following graphic shows the output of the previous example with arrows drawn ![Graphic that illustrates arrows drawn using the Path element.](./media/bidirectional-features-in-wpf-overview/arrows-drawn-path-element.png) -The and are two examples of a how [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] uses . Beside laying out [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] elements in a specific direction within a container, can be used with elements such as which renders ink on a surface, , . Whenever you need a right to left behavior for your content that mimics a left to right behavior, or vice versa, [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides that capability. +The and are two examples of a how UI elements in a specific direction within a container, can be used with elements such as which renders ink on a surface, , . Whenever you need a right to left behavior for your content that mimics a left to right behavior, or vice versa, Windows Presentation Foundation (WPF) provides that capability. @@ -170,9 +170,9 @@ Historically, Windows has supported number substitution by allowing the represen This has allowed applications to process numerical values without the need to convert them from one language to another, for example a user can open an Microsoft Excel spreadsheet in a localized Arabic Windows and see the numbers shaped in Arabic, but open it in a European version of Windows and see European representation of the same numbers. This is also necessary for other symbols such as comma separators and percentage symbol because they usually accompany numbers in the same document. -[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] continues the same tradition, and adds further support for this feature that allows more user control over when and how substitution is used. While this feature is designed for any language, it is particularly useful in bidirectional content where shaping digits for a specific language is usually a challenge for application developers because of the various cultures an application might run on. +Windows Presentation Foundation (WPF) continues the same tradition, and adds further support for this feature that allows more user control over when and how substitution is used. While this feature is designed for any language, it is particularly useful in bidirectional content where shaping digits for a specific language is usually a challenge for application developers because of the various cultures an application might run on. -The core property controlling how number substitution works in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] is the dependency property. The class specifies how numbers in text are to be displayed. It has three public properties that define its behavior. The following is a summary of each of the properties: +The core property controlling how number substitution works in Windows Presentation Foundation (WPF) is the dependency property. The class specifies how numbers in text are to be displayed. It has three public properties that define its behavior. The following is a summary of each of the properties: **CultureSource:** @@ -202,7 +202,7 @@ This property specifies the type of number substitution to perform. It takes one - : Numbers are rendered using the traditional digits for the number culture. For most cultures, this is the same as . However, results in Latin digits for some Arabic cultures, whereas this value results in Arabic digits for all Arabic cultures. -What do those values mean for a bidirectional content developer? In most cases, the developer might need only to define and the language of each textual [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] element, for example `Language="ar-SA"` and the logic takes care of displaying the numbers according to the correct [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)]. The following example demonstrates using Arabic and English numbers in a [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] application running in an Arabic version of Windows. +What do those values mean for a bidirectional content developer? In most cases, the developer might need only to define and the language of each textual UI element, for example `Language="ar-SA"` and the logic takes care of displaying the numbers according to the correct UI. The following example demonstrates using Arabic and English numbers in a Windows Presentation Foundation (WPF) application running in an Arabic version of Windows. [!code-xaml[Numbers#Numbers](~/samples/snippets/csharp/VS_Snippets_Wpf/Numbers/CS/Window1.xaml#numbers)] @@ -214,11 +214,11 @@ The was important in this case because setti **Defining Substitution Rules** -In a real application you might need to set the Language programmatically. For example, you want to set the `xml:lang` attribute to be the same as the one used by the system’s [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)], or maybe change the language depending on the application state. +In a real application you might need to set the Language programmatically. For example, you want to set the `xml:lang` attribute to be the same as the one used by the system’s UI, or maybe change the language depending on the application state. -If you want to make changes based on the application's state, make use of other features provided by [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)]. +If you want to make changes based on the application's state, make use of other features provided by Windows Presentation Foundation (WPF). -First, set the application component’s `NumberSubstitution.CultureSource="Text"`. Using this setting makes sure that the settings do not come from the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] for text elements that have "User" as the default, such as . +First, set the application component’s `NumberSubstitution.CultureSource="Text"`. Using this setting makes sure that the settings do not come from the UI for text elements that have "User" as the default, such as . For example: @@ -257,7 +257,7 @@ The following graphic shows what the window looks like for either programming la **Using the Substitution Property** -The way number substitution works in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] depends on both the Language of the text element and its . If the is left to right, then European digits are rendered. However if it is preceded by Arabic text, or has the language set to "ar" and the is , Arabic digits are rendered instead. +The way number substitution works in Windows Presentation Foundation (WPF) depends on both the Language of the text element and its . If the is left to right, then European digits are rendered. However if it is preceded by Arabic text, or has the language set to "ar" and the is , Arabic digits are rendered instead. In some cases, however, you might want to create a unified application, for example European digits for all users. Or Arabic digits in cells with a specific . One easy way to do that is using the property. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/binding-markup-extension.md b/dotnet-desktop-guide/framework/wpf/advanced/binding-markup-extension.md index 5a7c7b5..14ebbf0 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/binding-markup-extension.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/binding-markup-extension.md @@ -107,7 +107,7 @@ Defers a property value to be a data-bound value, creating an intermediate expre Describing data binding at a basic level is not covered in this topic. See [Data Binding Overview](../data/data-binding-overview.md). > [!NOTE] -> and do not support a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] extension syntax. You would instead use property elements. See reference topics for and . +> and do not support a XAML extension syntax. You would instead use property elements. See reference topics for and . Boolean values for XAML are case insensitive. For example you could specify either `{Binding NotifyOnValidationError=true}` or `{Binding NotifyOnValidationError=True}`. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/cleartype-overview.md b/dotnet-desktop-guide/framework/wpf/advanced/cleartype-overview.md index 81db869..378bdc8 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/cleartype-overview.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/cleartype-overview.md @@ -7,17 +7,17 @@ helpviewer_keywords: ms.assetid: 7e2392e0-75dc-463d-a716-908772782431 --- # ClearType Overview -This topic provides an overview of the Microsoft ClearType technology found in the [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)]. +This topic provides an overview of the Microsoft ClearType technology found in the Windows Presentation Foundation (WPF). ## Technology Overview ClearType is a software technology developed by Microsoft that improves the readability of text on existing LCDs (Liquid Crystal Displays), such as laptop screens, Pocket PC screens and flat panel monitors. ClearType works by accessing the individual vertical color stripe elements in every pixel of an LCD screen. Before ClearType, the smallest level of detail that a computer could display was a single pixel, but with ClearType running on an LCD monitor, we can now display features of text as small as a fraction of a pixel in width. The extra resolution increases the sharpness of the tiny details in text display, making it much easier to read over long durations. - The ClearType available in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] is the latest generation of ClearType which has several improvements over version found in Microsoft Windows Graphics Device Interface (GDI). + The ClearType available in Windows Presentation Foundation (WPF) is the latest generation of ClearType which has several improvements over version found in Microsoft Windows Graphics Device Interface (GDI). ## Sub-pixel Positioning - A significant improvement over the previous version of ClearType is the use of sub-pixel positioning. Unlike the ClearType implementation found in GDI, the ClearType found in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] allows glyphs to start within the pixel and not just the beginning boundary of the pixel. Because of this extra resolution in positioning glyphs, the spacing and proportions of the glyphs is more precise and consistent. + A significant improvement over the previous version of ClearType is the use of sub-pixel positioning. Unlike the ClearType implementation found in GDI, the ClearType found in Windows Presentation Foundation (WPF) allows glyphs to start within the pixel and not just the beginning boundary of the pixel. Because of this extra resolution in positioning glyphs, the spacing and proportions of the glyphs is more precise and consistent. The following two examples show how glyphs may begin on any sub-pixel boundary when sub-pixel positioning is used. The example on the left is rendered using the earlier version of the ClearType renderer, which did not employ sub-pixel positioning. The example on the right is rendered using the new version of the ClearType renderer, using sub-pixel positioning. Note how each **e** and **l** in the right-hand image is rendered slightly differently because each starts on a different sub-pixel. When viewing the text at its normal size on the screen, this difference is not noticeable because of the high contrast of the glyph image. This is only possible because of sophisticated color filtering that is incorporated in ClearType. @@ -31,14 +31,14 @@ Text with earlier and later versions of ClearType ## Y-Direction Antialiasing - Another improvement of ClearType in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] is y-direction anti-aliasing. The ClearType in GDI without y-direction anti-aliasing provides better resolution on the x-axis but not the y-axis. On the tops and bottoms of shallow curves, the jagged edges detract from its readability. + Another improvement of ClearType in Windows Presentation Foundation (WPF) is y-direction anti-aliasing. The ClearType in GDI without y-direction anti-aliasing provides better resolution on the x-axis but not the y-axis. On the tops and bottoms of shallow curves, the jagged edges detract from its readability. The following example shows the effect of having no y-direction antialiasing. In this case, the jagged edges on the top and bottom of the letter are apparent. ![Text with jagged edges on shallow curves](./media/wcpsdk-mmgraphics-text-cleartype-overview-03.png "wcpsdk_mmgraphics_text_cleartype_overview_03") Text with jagged edges on shallow curves - ClearType in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides antialiasing on the y-direction level to smooth out any jagged edges. This is particularly important for improving the readability of East Asian languages where ideographs have an almost equal amount of horizontal and vertical shallow curves. + ClearType in Windows Presentation Foundation (WPF) provides antialiasing on the y-direction level to smooth out any jagged edges. This is particularly important for improving the readability of East Asian languages where ideographs have an almost equal amount of horizontal and vertical shallow curves. The following example shows the effect of y-direction antialiasing. In this case, the top and bottom of the letter show a smooth curve. @@ -47,11 +47,11 @@ Text with ClearType y-direction antialiasing ## Hardware Acceleration - ClearType in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] can take advantage of hardware acceleration for better performance and to reduce CPU load and system memory requirements. By using the pixel shaders and video memory of a graphics card, ClearType provides faster rendering of text, particularly when animation is used. + ClearType in Windows Presentation Foundation (WPF) can take advantage of hardware acceleration for better performance and to reduce CPU load and system memory requirements. By using the pixel shaders and video memory of a graphics card, ClearType provides faster rendering of text, particularly when animation is used. - ClearType in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] does not modify the system-wide ClearType settings. Disabling ClearType in Windows sets [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] antialiasing to grayscale mode. In addition, ClearType in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] does not modify the settings of the [ClearType Tuner PowerToy](https://www.microsoft.com/typography/ClearTypePowerToy.mspx). + ClearType in Windows Presentation Foundation (WPF) does not modify the system-wide ClearType settings. Disabling ClearType in Windows sets Windows Presentation Foundation (WPF) antialiasing to grayscale mode. In addition, ClearType in Windows Presentation Foundation (WPF) does not modify the settings of the [ClearType Tuner PowerToy](https://www.microsoft.com/typography/ClearTypePowerToy.mspx). - One of the [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] architectural design decisions is to have resolution independent layout better support higher resolution DPI monitors, which are becoming more widespread. This has the consequence of [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] not supporting aliased text rendering or the bitmaps in some East Asian fonts because they are both resolution dependent. + One of the Windows Presentation Foundation (WPF) architectural design decisions is to have resolution independent layout better support higher resolution DPI monitors, which are becoming more widespread. This has the consequence of Windows Presentation Foundation (WPF) not supporting aliased text rendering or the bitmaps in some East Asian fonts because they are both resolution dependent. ## Further Information diff --git a/dotnet-desktop-guide/framework/wpf/advanced/cleartype-registry-settings.md b/dotnet-desktop-guide/framework/wpf/advanced/cleartype-registry-settings.md index ed68ea5..e7fd35d 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/cleartype-registry-settings.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/cleartype-registry-settings.md @@ -11,7 +11,7 @@ This topic provides an overview of the Microsoft ClearType registry settings tha ## Technology Overview - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications that render text to a display device use ClearType features to provide an enhanced reading experience. ClearType is a software technology developed by Microsoft that improves the readability of text on existing LCDs (Liquid Crystal Displays), such as laptop screens, Pocket PC screens and flat panel monitors. ClearType works by accessing the individual vertical color stripe elements in every pixel of an LCD screen. For more information on ClearType, see [ClearType Overview](cleartype-overview.md). + WPF applications that render text to a display device use ClearType features to provide an enhanced reading experience. ClearType is a software technology developed by Microsoft that improves the readability of text on existing LCDs (Liquid Crystal Displays), such as laptop screens, Pocket PC screens and flat panel monitors. ClearType works by accessing the individual vertical color stripe elements in every pixel of an LCD screen. For more information on ClearType, see [ClearType Overview](cleartype-overview.md). Text that is rendered with ClearType can appear significantly different when viewed on various display devices. For example, a small number of monitors implement the color stripe elements in blue, green, red order rather than the more common red, green, blue (RGB) order. @@ -21,7 +21,7 @@ This topic provides an overview of the Microsoft ClearType registry settings tha ## Registry Settings - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] specifies four registry settings for controlling ClearType features: + WPF specifies four registry settings for controlling ClearType features: |Setting|Description| |-------------|-----------------| @@ -30,9 +30,9 @@ This topic provides an overview of the Microsoft ClearType registry settings tha |Pixel structure|Describes the arrangement of pixels for a display device.| |Text contrast level|Describes the level of contrast for displayed text.| - These settings can be accessed by an external configuration utility that knows how to reference the identified [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] ClearType registry settings. These settings can also be created or modified by accessing the values directly by using the Windows Registry Editor. + These settings can be accessed by an external configuration utility that knows how to reference the identified WPF ClearType registry settings. These settings can also be created or modified by accessing the values directly by using the Windows Registry Editor. - If the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] ClearType registry settings are not set (which is the default state), the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application queries the Windows system parameters information for font smoothing settings. + If the WPF ClearType registry settings are not set (which is the default state), the WPF application queries the Windows system parameters information for font smoothing settings. > [!NOTE] > For information on enumerating display device names, see the `SystemParametersInfo`Win32 function. @@ -53,7 +53,7 @@ This topic provides an overview of the Microsoft ClearType registry settings tha ![ClearType settings in the Registry Editor.](./media/cleartype-registry-settings/cleartype-settings-registry-editor.png) > [!NOTE] -> [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications render text in one of either two modes, with and without ClearType. When text is rendered without ClearType, it is referred to as gray scale rendering. +> WPF applications render text in one of either two modes, with and without ClearType. When text is rendered without ClearType, it is referred to as gray scale rendering. ## Gamma Level diff --git a/dotnet-desktop-guide/framework/wpf/advanced/code-behind-and-xaml-in-wpf.md b/dotnet-desktop-guide/framework/wpf/advanced/code-behind-and-xaml-in-wpf.md index afd0c73..c8f68f4 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/code-behind-and-xaml-in-wpf.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/code-behind-and-xaml-in-wpf.md @@ -7,7 +7,7 @@ helpviewer_keywords: ms.assetid: 9df6d3c9-aed3-471c-af36-6859b19d999f --- # Code-Behind and XAML in WPF - Code-behind is a term used to describe the code that is joined with markup-defined objects, when a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] page is markup-compiled. This topic describes requirements for code-behind as well as an alternative inline code mechanism for code in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]. + Code-behind is a term used to describe the code that is joined with markup-defined objects, when a XAML page is markup-compiled. This topic describes requirements for code-behind as well as an alternative inline code mechanism for code in XAML. This topic contains the following sections: @@ -36,21 +36,21 @@ ms.assetid: 9df6d3c9-aed3-471c-af36-6859b19d999f - Note that under the default behavior of the markup compile build actions, you can leave the derivation blank in the partial class definition on the code-behind side. The compiled result will assume the page root's backing type to be the basis for the partial class, even if it not specified. However, relying on this behavior is not a best practice. -- The event handlers you write in the code-behind must be instance methods and cannot be static methods. These methods must be defined by the partial class within the CLR namespace identified by `x:Class`. You cannot qualify the name of an event handler to instruct a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor to look for an event handler for event wiring in a different class scope. +- The event handlers you write in the code-behind must be instance methods and cannot be static methods. These methods must be defined by the partial class within the CLR namespace identified by `x:Class`. You cannot qualify the name of an event handler to instruct a XAML processor to look for an event handler for event wiring in a different class scope. - The handler must match the delegate for the appropriate event in the backing type system. -- For the Microsoft Visual Basic language specifically, you can use the language-specific `Handles` keyword to associate handlers with instances and events in the handler declaration, instead of attaching handlers with attributes in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]. However, this technique does have some limitations because the `Handles` keyword cannot support all of the specific features of the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] event system, such as certain routed event scenarios or attached events. For details, see [Visual Basic and WPF Event Handling](visual-basic-and-wpf-event-handling.md). +- For the Microsoft Visual Basic language specifically, you can use the language-specific `Handles` keyword to associate handlers with instances and events in the handler declaration, instead of attaching handlers with attributes in WPF event system, such as certain routed event scenarios or attached events. For details, see [Visual Basic and WPF Event Handling](visual-basic-and-wpf-event-handling.md). ## x:Code - [x:Code](/dotnet/desktop/xaml-services/xcode-intrinsic-xaml-type) is a directive element defined in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]. An `x:Code` directive element can contain inline programming code. The code that is defined inline can interact with the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] on the same page. The following example illustrates inline C# code. Notice that the code is inside the `x:Code` element and that the code must be surrounded by `` to escape the contents for XML, so that a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor (interpreting either the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] schema or the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] schema) will not try to interpret the contents literally as XML. + [x:Code](/dotnet/desktop/xaml-services/xcode-intrinsic-xaml-type) is a directive element defined in WPF schema) will not try to interpret the contents literally as XML. [!code-xaml[XAMLOvwSupport#ButtonWithInlineCode](~/samples/snippets/csharp/VS_Snippets_Wpf/XAMLOvwSupport/CSharp/page4.xaml#buttonwithinlinecode)] ## Inline Code Limitations - You should consider avoiding or limiting the use of inline code. In terms of architecture and coding philosophy, maintaining a separation between markup and code-behind keeps the designer and developer roles much more distinct. On a more technical level, the code that you write for inline code can be awkward to write, because you are always writing into the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] generated partial class, and can only use the default XML namespace mappings. Because you cannot add `using` statements, you must fully qualify many of the API calls that you make. The default [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] mappings include most but not all CLR namespaces that are present in the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] assemblies; you will have to fully qualify calls to types and members contained within the other CLR namespaces. You also cannot define anything beyond the partial class in the inline code, and all user code entities you reference must exist as a member or variable within the generated partial class. Other language specific programming features, such as macros or `#ifdef` against global variables or build variables, are also not available. For more information, see [x:Code Intrinsic XAML Type](/dotnet/desktop/xaml-services/xcode-intrinsic-xaml-type). + You should consider avoiding or limiting the use of inline code. In terms of architecture and coding philosophy, maintaining a separation between markup and code-behind keeps the designer and developer roles much more distinct. On a more technical level, the code that you write for inline code can be awkward to write, because you are always writing into the WPF mappings include most but not all CLR namespaces that are present in the WPF assemblies; you will have to fully qualify calls to types and members contained within the other CLR namespaces. You also cannot define anything beyond the partial class in the inline code, and all user code entities you reference must exist as a member or variable within the generated partial class. Other language specific programming features, such as macros or `#ifdef` against global variables or build variables, are also not available. For more information, see [x:Code Intrinsic XAML Type](/dotnet/desktop/xaml-services/xcode-intrinsic-xaml-type). ## See also diff --git a/dotnet-desktop-guide/framework/wpf/advanced/colorconvertedbitmap-markup-extension.md b/dotnet-desktop-guide/framework/wpf/advanced/colorconvertedbitmap-markup-extension.md index 5004e1e..a3e1f69 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/colorconvertedbitmap-markup-extension.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/colorconvertedbitmap-markup-extension.md @@ -29,7 +29,7 @@ Provides a way to specify a bitmap source that does not have an embedded profile Attribute syntax is the most common syntax used with this markup extension. `ColorConvertedBitmap` (or `ColorConvertedBitmapExtension`) cannot be used in property element syntax, because the values can only be set as values on the initial constructor, which is the string following the extension identifier. - `ColorConvertedBitmap` is a markup extension. Markup extensions are typically implemented when there is a requirement to escape attribute values to be other than literal values or handler names, and the requirement is more global than just putting type converters on certain types or properties. All markup extensions in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] use the { and } characters in their attribute syntax, which is the convention by which a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor recognizes that a markup extension must process the attribute. For more information, see [Markup Extensions and WPF XAML](markup-extensions-and-wpf-xaml.md). + `ColorConvertedBitmap` is a markup extension. Markup extensions are typically implemented when there is a requirement to escape attribute values to be other than literal values or handler names, and the requirement is more global than just putting type converters on certain types or properties. All markup extensions in XAML use the { and } characters in their attribute syntax, which is the convention by which a XAML processor recognizes that a markup extension must process the attribute. For more information, see [Markup Extensions and WPF XAML](markup-extensions-and-wpf-xaml.md). ## See also diff --git a/dotnet-desktop-guide/framework/wpf/advanced/commanding-overview.md b/dotnet-desktop-guide/framework/wpf/advanced/commanding-overview.md index af87565..509e2a4 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/commanding-overview.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/commanding-overview.md @@ -18,9 +18,9 @@ ms.assetid: bc208dfe-367d-426a-99de-52b7e7511e81 --- # Commanding Overview - Commanding is an input mechanism in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] which provides input handling at a more semantic level than device input. Examples of commands are the **Copy**, **Cut**, and **Paste** operations found on many applications. + Commanding is an input mechanism in Windows Presentation Foundation (WPF) which provides input handling at a more semantic level than device input. Examples of commands are the **Copy**, **Cut**, and **Paste** operations found on many applications. - This overview defines what commands are in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], which classes are part of the commanding model, and how to use and create commands in your applications. + This overview defines what commands are in WPF, which classes are part of the commanding model, and how to use and create commands in your applications. This topic contains the following sections: @@ -48,7 +48,7 @@ ms.assetid: bc208dfe-367d-426a-99de-52b7e7511e81 ## Simple Command Example in WPF - The simplest way to use a command in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] is to use a predefined from one of the command library classes; use a control that has native support for handling the command; and use a control that has native support for invoking a command. The command is one of the predefined commands in the class. The control has built in logic for handling the command. And the class has native support for invoking commands. + The simplest way to use a command in WPF is to use a predefined from one of the command library classes; use a control that has native support for handling the command; and use a control that has native support for invoking a command. The command is one of the predefined commands in the class. The control has built in logic for handling the command. And the class has native support for invoking commands. The following example shows how to set up a so that when it is clicked it will invoke the command on a , assuming the has keyboard focus. @@ -61,7 +61,7 @@ ms.assetid: bc208dfe-367d-426a-99de-52b7e7511e81 ## Four Main Concepts in WPF Commanding - The routed command model in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] can be broken up into four main concepts: the command, the command source, the command target, and the command binding: + The routed command model in WPF can be broken up into four main concepts: the command, the command source, the command target, and the command binding: - The *command* is the action to be executed. @@ -77,13 +77,13 @@ ms.assetid: bc208dfe-367d-426a-99de-52b7e7511e81 ### Commands - Commands in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] are created by implementing the interface. exposes two methods, , and , and an event, . performs the actions that are associated with the command. determines whether the command can execute on the current command target. is raised if the command manager that centralizes the commanding operations detects a change in the command source that might invalidate a command that has been raised but not yet executed by the command binding. The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] implementation of is the class and is the focus of this overview. + Commands in WPF are created by implementing the interface. exposes two methods, , and , and an event, . performs the actions that are associated with the command. determines whether the command can execute on the current command target. is raised if the command manager that centralizes the commanding operations detects a change in the command source that might invalidate a command that has been raised but not yet executed by the command binding. The WPF implementation of is the class and is the focus of this overview. - The main sources of input in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] are the mouse, the keyboard, ink, and routed commands. The more device-oriented inputs use a to notify objects in an application page that an input event has occurred. A is no different. The and methods of a do not contain the application logic for the command, but rather they raise routed events that tunnel and bubble through the element tree until they encounter an object with a . The contains the handlers for these events and it is the handlers that perform the command. For more information on event routing in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], see [Routed Events Overview](routed-events-overview.md). + The main sources of input in WPF are the mouse, the keyboard, ink, and routed commands. The more device-oriented inputs use a to notify objects in an application page that an input event has occurred. A is no different. The and methods of a do not contain the application logic for the command, but rather they raise routed events that tunnel and bubble through the element tree until they encounter an object with a . The contains the handlers for these events and it is the handlers that perform the command. For more information on event routing in WPF, see [Routed Events Overview](routed-events-overview.md). The method on a raises the and the events on the command target. The method on a raises the and events on the command target. These events tunnel and bubble through the element tree until they encounter an object which has a for that particular command. - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] supplies a set of common routed commands spread across several classes: , , , , and . These classes consist only of the objects and not the implementation logic of the command. The implementation logic is the responsibility of the object on which the command is being executed on. + WPF supplies a set of common routed commands spread across several classes: , , , , and . These classes consist only of the objects and not the implementation logic of the command. The implementation logic is the responsibility of the object on which the command is being executed on. @@ -91,17 +91,17 @@ ms.assetid: bc208dfe-367d-426a-99de-52b7e7511e81 A command source is the object which invokes the command. Examples of command sources are , , and . - Command sources in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] generally implement the interface. + Command sources in WPF generally implement the interface. exposes three properties: , , and : - is the command to execute when the command source is invoked. -- is the object on which to execute the command. It is worth noting that in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] the property on is only applicable when the is a . If the is set on an and the corresponding command is not a , the command target is ignored. If the is not set, the element with keyboard focus will be the command target. +- is the object on which to execute the command. It is worth noting that in WPF the property on is only applicable when the is a . If the is set on an and the corresponding command is not a , the command target is ignored. If the is not set, the element with keyboard focus will be the command target. - is a user-defined data type used to pass information to the handlers implementing the command. - The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] classes that implement are , , , and . , , and invoke a command when they are clicked, and an invokes a command when the associated with it is performed. + The WPF classes that implement are , , , and . , , and invoke a command when they are clicked, and an invokes a command when the associated with it is performed. The following example shows how to use a in a as a command source for the command. @@ -112,7 +112,7 @@ ms.assetid: bc208dfe-367d-426a-99de-52b7e7511e81 Typically, a command source will listen to the event. This event informs the command source that the ability of the command to execute on the current command target may have changed. The command source can query the current status of the by using the method. The command source can then disable itself if the command cannot execute. An example of this is a graying itself out when a command cannot execute. - An can be used as a command source. Two types of input gestures in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] are the and . You can think of a as a keyboard shortcut, such as CTRL+C. A is comprised of a and a set of . A is comprised of a and an optional set of . + An can be used as a command source. Two types of input gestures in WPF are the and . You can think of a as a keyboard shortcut, such as CTRL+C. A is comprised of a and a set of . A is comprised of a and an optional set of . In order for an to act as a command source, it must be associated with a command. There are a few ways to accomplish this. One way is to use an . @@ -163,7 +163,7 @@ ms.assetid: bc208dfe-367d-426a-99de-52b7e7511e81 ### Command Target - The command target is the element on which the command is executed. With regards to a , the command target is the element at which routing of the and starts. As noted previously, in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] the property on is only applicable when the is a . If the is set on an and the corresponding command is not a , the command target is ignored. + The command target is the element on which the command is executed. With regards to a , the command target is the element at which routing of the and starts. As noted previously, in WPF the property on is only applicable when the is a . If the is set on an and the corresponding command is not a , the command target is ignored. The command source can explicitly set the command target. If the command target is not defined, the element with keyboard focus will be used as the command target. One of the benefits of using the element with keyboard focus as the command target is that it allows the application developer to use the same command source to invoke a command on multiple targets without having to keep track of the command target. For example, if a invokes the **Paste** command in an application that has a control and a control, the target can be either the or depending on which control has keyboard focus. @@ -186,11 +186,11 @@ ms.assetid: bc208dfe-367d-426a-99de-52b7e7511e81 ## Command Library - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides a set of predefined commands. The command library consists of the following classes: , , , , and the . These classes provide commands such as , and , , , and . + WPF provides a set of predefined commands. The command library consists of the following classes: , , , , and the . These classes provide commands such as , and , , , and . Many of these commands include a set of default input bindings. For example, if you specify that your application handles the copy command, you automatically get the keyboard binding "CTRL+C" You also get bindings for other input devices, such as Tablet PC pen gestures and speech information. - When you reference commands in the various command libraries using [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], you can usually omit the class name of the library class that exposes the static command property. Generally, the command names are unambiguous as strings, and the owning types exist to provide a logical grouping of commands but are not necessary for disambiguation. For instance, you can specify `Command="Cut"` rather than the more verbose `Command="ApplicationCommands.Cut"`. This is a convenience mechanism that is built in to the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor for commands (more precisely, it is a type converter behavior of , which the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor references at load time). + When you reference commands in the various command libraries using WPF WPF XAML processor references at load time). diff --git a/dotnet-desktop-guide/framework/wpf/advanced/componentresourcekey-markup-extension.md b/dotnet-desktop-guide/framework/wpf/advanced/componentresourcekey-markup-extension.md index 99c9295..7194037 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/componentresourcekey-markup-extension.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/componentresourcekey-markup-extension.md @@ -65,9 +65,9 @@ Defines and references keys for resources that are loaded from external assembli `ComponentResourceKey` can be used in object element syntax. In this case, specifying the value of both the and properties is required to properly initialize the extension. - In the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] reader implementation, the handling for this markup extension is defined by the class. + In the WPF XAML reader implementation, the handling for this markup extension is defined by the class. - `ComponentResourceKey` is a markup extension. Markup extensions are typically implemented when there is a requirement to escape attribute values to be other than literal values or handler names, and the requirement is more global than just putting type converters on certain types or properties. All markup extensions in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] use the { and } characters in their attribute syntax, which is the convention by which a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor recognizes that a markup extension must process the attribute. For more information, see [Markup Extensions and WPF XAML](markup-extensions-and-wpf-xaml.md). + `ComponentResourceKey` is a markup extension. Markup extensions are typically implemented when there is a requirement to escape attribute values to be other than literal values or handler names, and the requirement is more global than just putting type converters on certain types or properties. All markup extensions in XAML use the { and } characters in their attribute syntax, which is the convention by which a XAML processor recognizes that a markup extension must process the attribute. For more information, see [Markup Extensions and WPF XAML](markup-extensions-and-wpf-xaml.md). ## See also diff --git a/dotnet-desktop-guide/framework/wpf/advanced/createidispatchstaforwarder-function-wpf-unmanaged-api-reference.md b/dotnet-desktop-guide/framework/wpf/advanced/createidispatchstaforwarder-function-wpf-unmanaged-api-reference.md index a302d4e..3554236 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/createidispatchstaforwarder-function-wpf-unmanaged-api-reference.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/createidispatchstaforwarder-function-wpf-unmanaged-api-reference.md @@ -42,7 +42,7 @@ HRESULT CreateIDispatchSTAForwarder( In the .NET Framework 4 and later: PresentationHost_v0400.dll - **.NET Framework Version:** [!INCLUDE[net_current_v30plus](../../../includes/net-current-v30plus-md.md)] + **.NET Framework Version:** Available since 3.0 ## See also diff --git a/dotnet-desktop-guide/framework/wpf/advanced/custom-dependency-properties.md b/dotnet-desktop-guide/framework/wpf/advanced/custom-dependency-properties.md index 486a820..f682c37 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/custom-dependency-properties.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/custom-dependency-properties.md @@ -19,33 +19,33 @@ ms.assetid: e6bfcfac-b10d-4f58-9f77-a864c2a2938f --- # Custom Dependency Properties -This topic describes the reasons that [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] application developers and component authors might want to create custom dependency property, and describes the implementation steps as well as some implementation options that can improve performance, usability, or versatility of the property. +This topic describes the reasons that Windows Presentation Foundation (WPF) application developers and component authors might want to create custom dependency property, and describes the implementation steps as well as some implementation options that can improve performance, usability, or versatility of the property. ## Prerequisites -This topic assumes that you understand dependency properties from the perspective of a consumer of existing dependency properties on [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] classes, and have read the [Dependency Properties Overview](dependency-properties-overview.md) topic. In order to follow the examples in this topic, you should also understand [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] and know how to write [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications. +This topic assumes that you understand dependency properties from the perspective of a consumer of existing dependency properties on WPF classes, and have read the [Dependency Properties Overview](dependency-properties-overview.md) topic. In order to follow the examples in this topic, you should also understand WPF applications. ## What Is a Dependency Property? -You can enable what would otherwise be a common language runtime (CLR) property to support styling, data binding, inheritance, animations, and default values by implementing it as a dependency property. Dependency properties are properties that are registered with the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] property system by calling the method (or ), and that are backed by a identifier field. Dependency properties can be used only by types, but is quite high in the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] class hierarchy, so the majority of classes available in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] can support dependency properties. For more information about dependency properties and some of the terminology and conventions used for describing them in this SDK, see [Dependency Properties Overview](dependency-properties-overview.md). +You can enable what would otherwise be a common language runtime (CLR) property to support styling, data binding, inheritance, animations, and default values by implementing it as a dependency property. Dependency properties are properties that are registered with the WPF property system by calling the method (or ), and that are backed by a identifier field. Dependency properties can be used only by types, but is quite high in the WPF class hierarchy, so the majority of classes available in WPF can support dependency properties. For more information about dependency properties and some of the terminology and conventions used for describing them in this SDK, see [Dependency Properties Overview](dependency-properties-overview.md). ## Examples of Dependency Properties -Examples of dependency properties that are implemented on [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] classes include the property, the property, and the property, among many others. Each dependency property exposed by a class has a corresponding public static field of type exposed on that same class. This is the identifier for the dependency property. The identifier is named using a convention: the name of the dependency property with the string `Property` appended to it. For example, the corresponding identifier field for the property is . The identifier stores the information about the dependency property as it was registered, and the identifier is then used later for other operations involving the dependency property, such as calling . +Examples of dependency properties that are implemented on WPF classes include the property, the property, and the property, among many others. Each dependency property exposed by a class has a corresponding public static field of type exposed on that same class. This is the identifier for the dependency property. The identifier is named using a convention: the name of the dependency property with the string `Property` appended to it. For example, the corresponding identifier field for the property is . The identifier stores the information about the dependency property as it was registered, and the identifier is then used later for other operations involving the dependency property, such as calling . -As mentioned in the [Dependency Properties Overview](dependency-properties-overview.md), all dependency properties in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] (except most attached properties) are also CLR properties because of the "wrapper" implementation. Therefore, from code, you can get or set dependency properties by calling CLR accessors that define the wrappers in the same manner that you would use other CLR properties. As a consumer of established dependency properties, you do not typically use the methods and , which are the connection point to the underlying property system. Rather, the existing implementation of the CLR properties will have already called and within the `get` and `set` wrapper implementations of the property, using the identifier field appropriately. If you are implementing a custom dependency property yourself, then you will be defining the wrapper in a similar way. +As mentioned in the [Dependency Properties Overview](dependency-properties-overview.md), all dependency properties in WPF (except most attached properties) are also CLR properties because of the "wrapper" implementation. Therefore, from code, you can get or set dependency properties by calling CLR accessors that define the wrappers in the same manner that you would use other CLR properties. As a consumer of established dependency properties, you do not typically use the methods and , which are the connection point to the underlying property system. Rather, the existing implementation of the CLR properties will have already called and within the `get` and `set` wrapper implementations of the property, using the identifier field appropriately. If you are implementing a custom dependency property yourself, then you will be defining the wrapper in a similar way. ## When Should You Implement a Dependency Property? -When you implement a property on a class, so long as your class derives from , you have the option to back your property with a identifier and thus to make it a dependency property. Having your property be a dependency property is not always necessary or appropriate, and will depend on your scenario needs. Sometimes, the typical technique of backing your property with a private field is adequate. However, you should implement your property as a dependency property whenever you want your property to support one or more of the following [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] capabilities: +When you implement a property on a class, so long as your class derives from , you have the option to back your property with a identifier and thus to make it a dependency property. Having your property be a dependency property is not always necessary or appropriate, and will depend on your scenario needs. Sometimes, the typical technique of backing your property with a private field is adequate. However, you should implement your property as a dependency property whenever you want your property to support one or more of the following WPF capabilities: - You want your property to be settable in a style. For more information, see [Styling and Templating](../controls/styles-templates-overview.md). @@ -59,11 +59,11 @@ When you implement a property on a class, so long as your class derives from @@ -96,7 +96,7 @@ There are established naming conventions regarding dependency properties that yo The dependency property itself will have a basic name, "AquariumGraphic" as in this example, which is given as the first parameter of . That name must be unique within each registering type. Dependency properties inherited through base types are considered to be already part of the registering type; names of inherited properties cannot be registered again. However, there is a technique for adding a class as owner of a dependency property even when that dependency property is not inherited; for details, see [Dependency Property Metadata](dependency-property-metadata.md). -When you create the identifier field, name this field by the name of the property as you registered it, plus the suffix `Property`. This field is your identifier for the dependency property, and it will be used later as an input for the and calls you will make in the wrappers, by any other code access to the property by your own code, by any external code access you allow, by the property system, and potentially by [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processors. +When you create the identifier field, name this field by the name of the property as you registered it, plus the suffix `Property`. This field is your identifier for the dependency property, and it will be used later as an input for the and calls you will make in the wrappers, by any other code access to the property by your own code, by any external code access you allow, by the property system, and potentially by XAML processors. > [!NOTE] > Defining the dependency property in the class body is the typical implementation, but it is also possible to define a dependency property in the class static constructor. This approach might make sense if you need more than one line of code to initialize the dependency property. @@ -109,7 +109,7 @@ Your wrapper implementation should call and actions, respectively. The reason for this is discussed in the topic [XAML Loading and Dependency Properties](xaml-loading-and-dependency-properties.md). -All existing public dependency properties that are provided on the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] classes use this simple wrapper implementation model; most of the complexity of how dependency properties work is either inherently a behavior of the property system, or is implemented through other concepts such as coercion or property change callbacks through property metadata. +All existing public dependency properties that are provided on the WPF classes use this simple wrapper implementation model; most of the complexity of how dependency properties work is either inherently a behavior of the property system, or is implemented through other concepts such as coercion or property change callbacks through property metadata. [!code-csharp[WPFAquariumSln#AGWithWrapper](~/samples/snippets/csharp/VS_Snippets_Wpf/WPFAquariumSln/CSharp/WPFAquariumObjects/Class1.cs#agwithwrapper)] [!code-vb[WPFAquariumSln#AGWithWrapper](~/samples/snippets/visualbasic/VS_Snippets_Wpf/WPFAquariumSln/visualbasic/wpfaquariumobjects/class1.vb#agwithwrapper)] @@ -118,9 +118,9 @@ Again, by convention, the name of the wrapper property must be the same as the n - Certain aspects of styles and templates will not work. -- Most tools and designers must rely on the naming conventions to properly serialize [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], or to provide designer environment assistance at a per-property level. +- Most tools and designers must rely on the naming conventions to properly serialize XAML, or to provide designer environment assistance at a per-property level. -- The current implementation of the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] loader bypasses the wrappers entirely, and relies on the naming convention when processing attribute values. For more information, see [XAML Loading and Dependency Properties](xaml-loading-and-dependency-properties.md). +- The current implementation of the WPF XAML loader bypasses the wrappers entirely, and relies on the naming convention when processing attribute values. For more information, see [XAML Loading and Dependency Properties](xaml-loading-and-dependency-properties.md). @@ -134,11 +134,11 @@ For , you can also specify metada #### Setting Appropriate Metadata Flags -- If your property (or changes in its value) affects the [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)], and in particular affects how the layout system should size or render your element in a page, set one or more of the following flags: , , . +- If your property (or changes in its value) affects the user interface (UI), and in particular affects how the layout system should size or render your element in a page, set one or more of the following flags: , , . - - indicates that a change to this property requires a change to [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] rendering where the containing object might require more or less space within the parent. For example, a "Width" property should have this flag set. + - indicates that a change to this property requires a change to UI rendering where the containing object might require more or less space within the parent. For example, a "Width" property should have this flag set. - - indicates that a change to this property requires a change to [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] rendering that typically does not require a change in the dedicated space, but does indicate that the positioning within the space has changed. For example, an "Alignment" property should have this flag set. + - indicates that a change to this property requires a change to UI rendering that typically does not require a change in the dedicated space, but does indicate that the positioning within the space has changed. For example, an "Alignment" property should have this flag set. - indicates that some other change has occurred that will not affect layout and measure, but does require another render. An example would be a property that changes a color of an existing element, such as "Background". @@ -176,7 +176,7 @@ Dependency properties should be declared as public properties. Dependency proper ## Dependency Properties and Class Constructors -There is a general principle in managed code programming (often enforced by code analysis tools such as FxCop) that class constructors should not call virtual methods. This is because constructors can be called as base initialization of a derived class constructor, and entering the virtual method through the constructor might occur at an incomplete initialization state of the object instance being constructed. When you derive from any class that already derives from , you should be aware that the property system itself calls and exposes virtual methods internally. These virtual methods are part of the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] property system services. Overriding the methods enables derived classes to participate in value determination. To avoid potential issues with runtime initialization, you should not set dependency property values within constructors of classes, unless you follow a very specific constructor pattern. For details, see [Safe Constructor Patterns for DependencyObjects](safe-constructor-patterns-for-dependencyobjects.md). +There is a general principle in managed code programming (often enforced by code analysis tools such as FxCop) that class constructors should not call virtual methods. This is because constructors can be called as base initialization of a derived class constructor, and entering the virtual method through the constructor might occur at an incomplete initialization state of the object instance being constructed. When you derive from any class that already derives from , you should be aware that the property system itself calls and exposes virtual methods internally. These virtual methods are part of the WPF property system services. Overriding the methods enables derived classes to participate in value determination. To avoid potential issues with runtime initialization, you should not set dependency property values within constructors of classes, unless you follow a very specific constructor pattern. For details, see [Safe Constructor Patterns for DependencyObjects](safe-constructor-patterns-for-dependencyobjects.md). ## See also diff --git a/dotnet-desktop-guide/framework/wpf/advanced/custom-rendering-ink.md b/dotnet-desktop-guide/framework/wpf/advanced/custom-rendering-ink.md index 4d52806..fe803ec 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/custom-rendering-ink.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/custom-rendering-ink.md @@ -39,7 +39,7 @@ The property of a stroke a ## Implementing a Dynamic Renderer - Although the class is a standard part of [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], to perform more specialized rendering, you must create a customized dynamic renderer that derives from the and override the method. + Although the class is a standard part of WPF, to perform more specialized rendering, you must create a customized dynamic renderer that derives from the and override the method. The following example demonstrates a customized that draws ink with a linear gradient brush effect. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/data-and-data-objects.md b/dotnet-desktop-guide/framework/wpf/advanced/data-and-data-objects.md index 94c0bf1..c97f90c 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/data-and-data-objects.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/data-and-data-objects.md @@ -30,9 +30,9 @@ Data that is transferred as part of a drag-and-drop operation is stored in a dat ||Returns a list of formats that the data in this data object is stored in, or can be converted to.| ||Stores the specified data in this data object.| - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides a basic implementation of in the class. The stock class is sufficient for many common data transfer scenarios. + WPF provides a basic implementation of in the class. The stock class is sufficient for many common data transfer scenarios. - There are several pre-defined formats, such as bitmap, CSV, file, HTML, RTF, string, text, and audio. For information about pre-defined data formats provided with [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], see the class reference topic. + There are several pre-defined formats, such as bitmap, CSV, file, HTML, RTF, string, text, and audio. For information about pre-defined data formats provided with WPF, see the class reference topic. Data objects commonly include a facility for automatically converting data stored in one format to a different format while extracting data; this facility is referred to as auto-convert. When querying for the data formats available in a data object, auto-convertible data formats can be filtered from native data formats by calling the or method and specifying the `autoConvert` parameter as `false`. When adding data to a data object with the method, auto-conversion of data can be prohibited by setting the `autoConvert` parameter to `false`. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/deactivate-function-wpf-unmanaged-api-reference.md b/dotnet-desktop-guide/framework/wpf/advanced/deactivate-function-wpf-unmanaged-api-reference.md index 9dce8e3..6ffa947 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/deactivate-function-wpf-unmanaged-api-reference.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/deactivate-function-wpf-unmanaged-api-reference.md @@ -30,7 +30,7 @@ void Deactivate() In the .NET Framework 4 and later: PresentationHost_v0400.dll - **.NET Framework Version:** [!INCLUDE[net_current_v30plus](../../../includes/net-current-v30plus-md.md)] + **.NET Framework Version:** Available since 3.0 ## See also diff --git a/dotnet-desktop-guide/framework/wpf/advanced/dependency-properties-overview.md b/dotnet-desktop-guide/framework/wpf/advanced/dependency-properties-overview.md index a678748..9f894d7 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/dependency-properties-overview.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/dependency-properties-overview.md @@ -121,7 +121,7 @@ The following example sets the class, do not natively support for purposes of producing notifications of changes in source property value for data binding operations. For more information on how to create properties for use in data binding that can report changes to a data binding target, see [Data Binding Overview](../data/data-binding-overview.md). ### Styles -Styles and templates are two of the chief motivating scenarios for using dependency properties. Styles are particularly useful for setting properties that define application [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)]. Styles are typically defined as resources in XAML. Styles interact with the property system because they typically contain "setters" for particular properties, as well as "triggers" that change a property value based on the real-time value for another property. +Styles and templates are two of the chief motivating scenarios for using dependency properties. Styles are particularly useful for setting properties that define application user interface (UI). Styles are typically defined as resources in XAML. Styles interact with the property system because they typically contain "setters" for particular properties, as well as "triggers" that change a property value based on the real-time value for another property. The following example creates a simple style (which would be defined inside a dictionary, not shown), then applies that style directly to the property for a . The setter within the style sets the property for a styled to green. @@ -185,7 +185,7 @@ Typically, you would not want styles to always apply and to obscure even a local ## Learning more about dependency properties -- An attached property is a type of property that supports a specialized syntax in XAML. An attached property often does not have a 1:1 correspondence with a common language runtime (CLR) property, and is not necessarily a dependency property. The typical purpose of an attached property is to allow child elements to report property values to a parent element, even if the parent element and child element do not both possess that property as part of the class members listings. One primary scenario is to enable child elements to inform the parent how they should be presented in [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)]; for an example, see or . For details, see [Attached Properties Overview](attached-properties-overview.md). +- An attached property is a type of property that supports a specialized syntax in XAML. An attached property often does not have a 1:1 correspondence with a common language runtime (CLR) property, and is not necessarily a dependency property. The typical purpose of an attached property is to allow child elements to report property values to a parent element, even if the parent element and child element do not both possess that property as part of the class members listings. One primary scenario is to enable child elements to inform the parent how they should be presented in UI; for an example, see or . For details, see [Attached Properties Overview](attached-properties-overview.md). - Component developers or application developers may wish to create their own dependency property, in order to enable capabilities such as data binding or styles support, or for invalidation and value coercion support. For details, see [Custom Dependency Properties](custom-dependency-properties.md). diff --git a/dotnet-desktop-guide/framework/wpf/advanced/dependency-property-metadata.md b/dotnet-desktop-guide/framework/wpf/advanced/dependency-property-metadata.md index 82bbdcf..f00d86a 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/dependency-property-metadata.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/dependency-property-metadata.md @@ -9,11 +9,11 @@ helpviewer_keywords: ms.assetid: d01ed009-b722-41bf-b82f-fe1a8cdc50dd --- # Dependency Property Metadata -The [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] property system includes a metadata reporting system that goes beyond what can be reported about a property through reflection or general common language runtime (CLR) characteristics. Metadata for a dependency property can also be assigned uniquely by the class that defines a dependency property, can be changed when the dependency property is added to a different class, and can be specifically overridden by all derived classes that inherit the dependency property from the defining base class. +The Windows Presentation Foundation (WPF) property system includes a metadata reporting system that goes beyond what can be reported about a property through reflection or general common language runtime (CLR) characteristics. Metadata for a dependency property can also be assigned uniquely by the class that defines a dependency property, can be changed when the dependency property is added to a different class, and can be specifically overridden by all derived classes that inherit the dependency property from the defining base class. ## Prerequisites - This topic assumes that you understand dependency properties from the perspective of a consumer of existing dependency properties on [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] classes, and have read the [Dependency Properties Overview](dependency-properties-overview.md). In order to follow the examples in this topic, you should also understand [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] and know how to write [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications. + This topic assumes that you understand dependency properties from the perspective of a consumer of existing dependency properties on WPF applications. ## How Dependency Property Metadata is Used @@ -36,9 +36,9 @@ The [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] ## When to Override Metadata, When to Derive a Class - The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] property system has established capabilities for changing some characteristics of dependency properties without requiring them to be entirely re-implemented. This is accomplished by constructing a different instance of property metadata for the dependency property as it exists on a particular type. Note that most existing dependency properties are not virtual properties, so strictly speaking "re-implementing" them on inherited classes could only be accomplished by shadowing the existing member. + The WPF property system has established capabilities for changing some characteristics of dependency properties without requiring them to be entirely re-implemented. This is accomplished by constructing a different instance of property metadata for the dependency property as it exists on a particular type. Note that most existing dependency properties are not virtual properties, so strictly speaking "re-implementing" them on inherited classes could only be accomplished by shadowing the existing member. - If the scenario you are trying to enable for a dependency property on a type cannot be accomplished by modifying characteristics of existing dependency properties, it might then be necessary to create a derived class, and then to declare a custom dependency property on your derived class. A custom dependency property behaves identically to dependency properties defined by the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] APIs. For more details about custom dependency properties, see [Custom Dependency Properties](custom-dependency-properties.md). + If the scenario you are trying to enable for a dependency property on a type cannot be accomplished by modifying characteristics of existing dependency properties, it might then be necessary to create a derived class, and then to declare a custom dependency property on your derived class. A custom dependency property behaves identically to dependency properties defined by the WPF APIs. For more details about custom dependency properties, see [Custom Dependency Properties](custom-dependency-properties.md). One notable characteristic of a dependency property that you cannot override is its value type. If you are inheriting a dependency property that has the approximate behavior you require, but you require a different type for it, you will have to implement a custom dependency property and perhaps link the properties through type conversion or other implementation on your custom class. Also, you cannot replace an existing , because this callback exists in the registration field itself and not within its metadata. @@ -52,7 +52,7 @@ The [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] ### Overriding Metadata The purpose of overriding metadata is primarily so that you have the opportunity to change the various metadata-derived behaviors that are applied to the dependency property as it exists on your type. The reasons for this are explained in more detail in the [Metadata](#dp_metadata_contents) section. For more information including some code examples, see [Override Metadata for a Dependency Property](how-to-override-metadata-for-a-dependency-property.md). - Property metadata can be supplied for a dependency property during the registration call (). However, in many cases, you might want to provide type-specific metadata for your class when it inherits that dependency property. You can do this by calling the method. For an example from the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] APIs, the class is the type that first registers the dependency property. But the class overrides metadata for the dependency property to provide its own initial default value, changing it from `false` to `true`, and otherwise re-uses the original implementation. + Property metadata can be supplied for a dependency property during the registration call (). However, in many cases, you might want to provide type-specific metadata for your class when it inherits that dependency property. You can do this by calling the method. For an example from the WPF APIs, the class is the type that first registers the dependency property. But the class overrides metadata for the dependency property to provide its own initial default value, changing it from `false` to `true`, and otherwise re-uses the original implementation. When you override metadata, the different metadata characteristics are either merged or replaced. @@ -69,7 +69,7 @@ The [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] This behavior is implemented by , and can be overridden on derived metadata classes. #### Overriding Attached Property Metadata - In [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], attached properties are implemented as dependency properties. This means that they also have property metadata, which individual classes can override. The scoping considerations for an attached property in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] are generally that any can have an attached property set on them. Therefore, any derived class can override the metadata for any attached property, as it might be set on an instance of the class. You can override default values, callbacks, or WPF framework-level characteristic-reporting properties. If the attached property is set on an instance of your class, those override property metadata characteristics apply. For instance, you can override the default value, such that your override value is reported as the value of the attached property on instances of your class, whenever the property is not otherwise set. + In WPF, attached properties are implemented as dependency properties. This means that they also have property metadata, which individual classes can override. The scoping considerations for an attached property in WPF are generally that any can have an attached property set on them. Therefore, any derived class can override the metadata for any attached property, as it might be set on an instance of the class. You can override default values, callbacks, or WPF framework-level characteristic-reporting properties. If the attached property is set on an instance of your class, those override property metadata characteristics apply. For instance, you can override the default value, such that your override value is reported as the value of the attached property on instances of your class, whenever the property is not otherwise set. > [!NOTE] > The property is not relevant for attached properties. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/dependency-property-security.md b/dotnet-desktop-guide/framework/wpf/advanced/dependency-property-security.md index 2194c67..0b1577c 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/dependency-property-security.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/dependency-property-security.md @@ -12,7 +12,7 @@ helpviewer_keywords: ms.assetid: d10150ec-90c5-4571-8d35-84bafa2429a4 --- # Dependency Property Security -Dependency properties should generally be considered to be public properties. The nature of the [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] property system prevents the ability to make security guarantees about a dependency property value. +Dependency properties should generally be considered to be public properties. The nature of the Windows Presentation Foundation (WPF) property system prevents the ability to make security guarantees about a dependency property value. ## Access and Security of Wrappers and Dependency Properties diff --git a/dotnet-desktop-guide/framework/wpf/advanced/dependency-property-value-precedence.md b/dotnet-desktop-guide/framework/wpf/advanced/dependency-property-value-precedence.md index d383be4..b92fdac 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/dependency-property-value-precedence.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/dependency-property-value-precedence.md @@ -9,19 +9,19 @@ helpviewer_keywords: ms.assetid: 1fbada8e-4867-4ed1-8d97-62c07dad7ebc --- # Dependency Property Value Precedence - This topic explains how the workings of the [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] property system can affect the value of a dependency property, and describes the precedence by which aspects of the property system apply to the effective value of a property. + This topic explains how the workings of the Windows Presentation Foundation (WPF) property system can affect the value of a dependency property, and describes the precedence by which aspects of the property system apply to the effective value of a property. ## Prerequisites - This topic assumes that you understand dependency properties from the perspective of a consumer of existing dependency properties on [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] classes, and have read [Dependency Properties Overview](dependency-properties-overview.md). To follow the examples in this topic, you should also understand [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] and know how to write [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications. + This topic assumes that you understand dependency properties from the perspective of a consumer of existing dependency properties on WPF classes, and have read [Dependency Properties Overview](dependency-properties-overview.md). To follow the examples in this topic, you should also understand WPF applications. ## The WPF Property System - The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] property system offers a powerful way to have the value of dependency properties be determined by a variety of factors, enabling features such as real-time property validation, late binding, and notifying related properties of changes to values for other properties. The exact order and logic that is used to determine dependency property values is reasonably complex. Knowing this order will help you avoid unnecessary property setting, and might also clear up confusion over exactly why some attempt to influence or anticipate a dependency property value did not end up resulting in the value you expected. + The WPF property system offers a powerful way to have the value of dependency properties be determined by a variety of factors, enabling features such as real-time property validation, late binding, and notifying related properties of changes to values for other properties. The exact order and logic that is used to determine dependency property values is reasonably complex. Knowing this order will help you avoid unnecessary property setting, and might also clear up confusion over exactly why some attempt to influence or anticipate a dependency property value did not end up resulting in the value you expected. ## Dependency Properties Might Be "Set" in Multiple Places - The following is example [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] where the same property () has three different "set" operations that might influence the value. + The following is example XAML where the same property () has three different "set" operations that might influence the value. :::code language="xaml" source="./snippets/dependency-property-value-precedence/xaml/MainWindow.xaml" id="DependencyPropertyValuePrecedence"::: @@ -37,13 +37,13 @@ ms.assetid: 1fbada8e-4867-4ed1-8d97-62c07dad7ebc 2. **Active animations, or animations with a Hold behavior.** In order to have any practical effect, an animation of a property must be able to have precedence over the base (unanimated) value, even if that value was set locally. For details, see [Coercion, Animation, and Base Value](#animations) later in this topic. -3. **Local value.** A local value might be set through the convenience of the "wrapper" property, which also equates to setting as an attribute or property element in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], or by a call to the API using a property of a specific instance. If you set a local value by using a binding or a resource, these each act in the precedence as if a direct value was set. +3. **Local value.** A local value might be set through the convenience of the "wrapper" property, which also equates to setting as an attribute or property element in XAML, or by a call to the API using a property of a specific instance. If you set a local value by using a binding or a resource, these each act in the precedence as if a direct value was set. 4. **TemplatedParent template properties.** An element has a if it was created as part of a template (a or ). For details on when this applies, see [TemplatedParent](#templatedparent) later in this topic. Within the template, the following precedence applies: 1. Triggers from the template. - 2. Property sets (typically through [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] attributes) in the template. + 2. Property sets (typically through XAML attributes) in the template. 5. **Implicit style.** Applies only to the `Style` property. The `Style` property is filled by any style resource with a key that matches the type of that element. That style resource must exist either in the page or the application; lookup for an implicit style resource does not proceed into the themes. @@ -75,13 +75,13 @@ ms.assetid: 1fbada8e-4867-4ed1-8d97-62c07dad7ebc - **Implicit style.** The property is not set directly. However, the exists at some level in the resource lookup sequence (page, application) and is keyed using a resource key that matches the type the style is to be applied to. In this case, the property itself acts by a precedence identified in the sequence as item 5. This condition can be detected by using against the property and looking for in the results. -- **Default style**, also known as **theme style.** The property is not set directly, and in fact will read as `null` up until run time. In this case, the style comes from the run-time theme evaluation that is part of the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] presentation engine. +- **Default style**, also known as **theme style.** The property is not set directly, and in fact will read as `null` up until run time. In this case, the style comes from the run-time theme evaluation that is part of the WPF presentation engine. For implicit styles not in themes, the type must match exactly - a `MyButton` `Button`-derived class will not implicitly use a style for `Button`. ## Default (Theme) Styles - Every control that ships with [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] has a default style. That default style potentially varies by theme, which is why this default style is sometimes referred to as a theme style. + Every control that ships with WPF has a default style. That default style potentially varies by theme, which is why this default style is sometimes referred to as a theme style. The most important information that is found within a default style for a control is its control template, which exists in the theme style as a setter for its property. If there were no template from default styles, a control without a custom template as part of a custom style would have no visual appearance at all. The template from the default style gives the visual appearance of each control a basic structure, and also defines the connections between properties defined in the visual tree of the template and the corresponding control class. Each control exposes a set of properties that can influence the visual appearance of the control without completely replacing the template. For example, consider the default visual appearance of a control, which is a component of a . @@ -109,7 +109,7 @@ ms.assetid: 1fbada8e-4867-4ed1-8d97-62c07dad7ebc Multiple animations might be applied to a single property, with each of these animations possibly having been defined from different points in the value precedence. However, these animations will potentially composite their values, rather than just applying the animation from the higher precedence. This depends on exactly how the animations are defined, and the type of the value that is being animated. For more information about animating properties, see [Animation Overview](../graphics-multimedia/animation-overview.md). - Coercion applies at the highest level of all. Even an already running animation is subject to value coercion. Certain existing dependency properties in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] have built-in coercion. For a custom dependency property, you define the coercion behavior for a custom dependency property by writing a and passing the callback as part of metadata when you create the property. You can also override coercion behavior of existing properties by overriding the metadata on that property in a derived class. Coercion interacts with the base value in such a way that the constraints on coercion are applied as those constraints exist at the time, but the base value is still retained. Therefore, if constraints in coercion are later lifted, the coercion will return the closest value possible to that base value, and potentially the coercion influence on a property will cease as soon as all constraints are lifted. For more information about coercion behavior, see [Dependency Property Callbacks and Validation](dependency-property-callbacks-and-validation.md). + Coercion applies at the highest level of all. Even an already running animation is subject to value coercion. Certain existing dependency properties in WPF have built-in coercion. For a custom dependency property, you define the coercion behavior for a custom dependency property by writing a and passing the callback as part of metadata when you create the property. You can also override coercion behavior of existing properties by overriding the metadata on that property in a derived class. Coercion interacts with the base value in such a way that the constraints on coercion are applied as those constraints exist at the time, but the base value is still retained. Therefore, if constraints in coercion are later lifted, the coercion will return the closest value possible to that base value, and potentially the coercion influence on a property will cease as soon as all constraints are lifted. For more information about coercion behavior, see [Dependency Property Callbacks and Validation](dependency-property-callbacks-and-validation.md). ## Trigger Behaviors diff --git a/dotnet-desktop-guide/framework/wpf/advanced/digital-ink.md b/dotnet-desktop-guide/framework/wpf/advanced/digital-ink.md index f014b2c..0106f80 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/digital-ink.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/digital-ink.md @@ -9,7 +9,7 @@ helpviewer_keywords: ms.assetid: d0d6df69-daf9-4cf3-b7f9-ffee588037a3 --- # Digital Ink -This section discusses the use of digital ink in the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. Traditionally found only in the Tablet PC SDK, digital ink is now available in the core Windows Presentation Foundation. This means you can now develop full-fledged Tablet PC applications by using the power of Windows Presentation Foundation. +This section discusses the use of digital ink in the WPF. Traditionally found only in the Tablet PC SDK, digital ink is now available in the core Windows Presentation Foundation. This means you can now develop full-fledged Tablet PC applications by using the power of Windows Presentation Foundation. ## In This Section [Overviews](digital-ink-overviews.md) diff --git a/dotnet-desktop-guide/framework/wpf/advanced/documents-in-wpf.md b/dotnet-desktop-guide/framework/wpf/advanced/documents-in-wpf.md index 9f13a74..5a260ae 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/documents-in-wpf.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/documents-in-wpf.md @@ -14,11 +14,11 @@ helpviewer_keywords: ms.assetid: 6e8db7bc-050a-4070-aa72-bb8c46e87ff8 --- # Documents in WPF -[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] offers a wide range of document features that enable the creation of high-fidelity content that is designed to be more easily accessed and read than in previous generations of Windows. In addition to enhanced capabilities and quality, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] also provides integrated services for document display, packaging, and security. This topic provides an introduction to [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] document types and document packaging. +WPF also provides integrated services for document display, packaging, and security. This topic provides an introduction to WPF document types and document packaging. ## Types of Documents - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] divides documents into two broad categories based on their intended use; these document categories are termed "fixed documents" and "flow documents." + WPF divides documents into two broad categories based on their intended use; these document categories are termed "fixed documents" and "flow documents." Fixed documents are intended for applications that require a precise "what you see is what you get" (WYSIWYG) presentation, independent of the display or printer hardware used. Typical uses for fixed documents include desktop publishing, word processing, and form layout, where adherence to the original page design is critical. As part of its layout, a fixed document maintains the precise positional placement of content elements independent of the display or print device in use. For example, a fixed document page viewed on 96 dpi display will appear exactly the same when it is output to a 600 dpi laser printer as when it is output to a 4800 dpi phototypesetter. The page layout remains the same in all cases, while the document quality maximizes to the capabilities of each device. @@ -26,10 +26,10 @@ ms.assetid: 6e8db7bc-050a-4070-aa72-bb8c46e87ff8 ## Document Controls and Text Layout - The .NET Framework provides a set of pre-built controls that simplify using fixed documents, flow documents, and general text within your application. The display of fixed document content is supported using the control. Display of flow document content is supported by three different controls: , , and which map to different user scenarios (see sections below). Other [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] controls provide simplified layout to support general text uses (see [Text in the User Interface](#text_in_the_user_interface), below). + The .NET Framework provides a set of pre-built controls that simplify using fixed documents, flow documents, and general text within your application. The display of fixed document content is supported using the control. Display of flow document content is supported by three different controls: , , and which map to different user scenarios (see sections below). Other WPF controls provide simplified layout to support general text uses (see [Text in the User Interface](#text_in_the_user_interface), below). ### Fixed Document Control - DocumentViewer - The control is designed to display content. The control provides an intuitive user interface that provides built-in support for common operations including print output, copy to clipboard, zoom, and text search features. The control provides access to pages of content through a familiar scrolling mechanism. Like all [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] controls, supports complete or partial restyling, which enables the control to be visually integrated into virtually any application or environment. + The control is designed to display content. The control provides an intuitive user interface that provides built-in support for common operations including print output, copy to clipboard, zoom, and text search features. The control provides access to pages of content through a familiar scrolling mechanism. Like all WPF controls, supports complete or partial restyling, which enables the control to be visually integrated into virtually any application or environment. is designed to display content in a read-only manner; editing or modification of content is not available and is not supported. @@ -47,17 +47,17 @@ ms.assetid: 6e8db7bc-050a-4070-aa72-bb8c46e87ff8 #### FlowDocumentPageViewer and FlowDocumentScrollViewer shows content in page-at-a-time viewing mode, while shows content in continuous scrolling mode. Both and are fixed to a particular viewing mode. Compare to , which includes features that enable the user to dynamically choose between various viewing modes (as provided by the enumeration), at the cost of being more resource intensive than or . - By default, a vertical scrollbar is always shown, and a horizontal scrollbar becomes visible if needed. The default [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] for does not include a toolbar; however, the property can be used to enable a built-in toolbar. + By default, a vertical scrollbar is always shown, and a horizontal scrollbar becomes visible if needed. The default UI for does not include a toolbar; however, the property can be used to enable a built-in toolbar. ### Text in the User Interface - Besides adding text to documents, text can obviously be used in application UI such as forms. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] includes multiple controls for drawing text to the screen. Each control is targeted to a different scenario and has its own list of features and limitations. In general, the element should be used when limited text support is required, such as a brief sentence in a [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)]. can be used when minimal text support is required. For more information, see [TextBlock Overview](../controls/textblock-overview.md). + Besides adding text to documents, text can obviously be used in application UI such as forms. WPF includes multiple controls for drawing text to the screen. Each control is targeted to a different scenario and has its own list of features and limitations. In general, the element should be used when limited text support is required, such as a brief sentence in a user interface (UI). can be used when minimal text support is required. For more information, see [TextBlock Overview](../controls/textblock-overview.md). ## Document Packaging - The APIs provide an efficient means to organize application data, document content, and related resources in a single container that is simple to access, portable, and easy to distribute. A ZIP file is an example of a type capable of holding multiple objects as a single unit. The packaging APIs provide a default implementation designed using an Open Packaging Conventions standard with XML and ZIP file architecture. The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] packaging APIs make it simple to create packages, and to store and access objects within them. An object stored in a is referred to as a ("part"). Packages can also include signed digital certificates that can be used to identify the originator of a part and to validate that the contents of a package have not been modified. Packages also include a feature that allows additional information to be added to a package or associated with specific parts without actually modifying the content of existing parts. Package services also support Microsoft Windows Rights Management (RM). + The APIs provide an efficient means to organize application data, document content, and related resources in a single container that is simple to access, portable, and easy to distribute. A ZIP file is an example of a type capable of holding multiple objects as a single unit. The packaging APIs provide a default implementation designed using an Open Packaging Conventions standard with XML and ZIP file architecture. The WPF packaging APIs make it simple to create packages, and to store and access objects within them. An object stored in a is referred to as a ("part"). Packages can also include signed digital certificates that can be used to identify the originator of a part and to validate that the contents of a package have not been modified. Packages also include a feature that allows additional information to be added to a package or associated with specific parts without actually modifying the content of existing parts. Package services also support Microsoft Windows Rights Management (RM). - The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] Package architecture serves as the foundation for a number of key technologies: + The WPF Package architecture serves as the foundation for a number of key technologies: - XPS documents conforming to the XML Paper Specification (XPS). @@ -65,13 +65,13 @@ ms.assetid: 6e8db7bc-050a-4070-aa72-bb8c46e87ff8 - Custom storage formats for your own application design. - Based on the packaging APIs, an is specifically designed for storing [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] fixed content documents. An is a self-contained document that can be opened in a viewer, displayed in a control, routed to a print spool, or output directly to an XPS-compatible printer. + Based on the packaging APIs, an is specifically designed for storing WPF fixed content documents. An is a self-contained document that can be opened in a viewer, displayed in a control, routed to a print spool, or output directly to an XPS-compatible printer. - The following sections provide additional information on the and APIs provided with [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. + The following sections provide additional information on the and APIs provided with WPF. ### Package Components - The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] packaging APIs allow application data and documents to be organized into a single portable unit. A ZIP file is one of the most common types of packages and is the default package type provided with [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. itself is an abstract class from which is implemented using an open standard XML and ZIP file architecture. The method uses to create and use ZIP files by default. A package can contain three basic types of items: + The WPF packaging APIs allow application data and documents to be organized into a single portable unit. A ZIP file is one of the most common types of packages and is the default package type provided with WPF. itself is an abstract class from which is implemented using an open standard XML and ZIP file architecture. The method uses to create and use ZIP files by default. A package can contain three basic types of items: | Item | Description | |------|-------------| @@ -81,7 +81,7 @@ ms.assetid: 6e8db7bc-050a-4070-aa72-bb8c46e87ff8 #### PackageParts - A ("part") is an abstract class that refers to an object stored in a . In a ZIP file, the package parts correspond to the individual files stored within the ZIP file. provides the default implementation for serializable objects stored in a . Like a file system, parts contained in the package are stored in hierarchical directory or "folder-style" organization. Using the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] packaging APIs, applications can write, store, and read multiple objects using a single ZIP file container. + A ("part") is an abstract class that refers to an object stored in a . In a ZIP file, the package parts correspond to the individual files stored within the ZIP file. provides the default implementation for serializable objects stored in a . Like a file system, parts contained in the package are stored in hierarchical directory or "folder-style" organization. Using the WPF packaging APIs, applications can write, store, and read multiple objects using a single ZIP file container. #### PackageDigitalSignatures diff --git a/dotnet-desktop-guide/framework/wpf/advanced/documents.md b/dotnet-desktop-guide/framework/wpf/advanced/documents.md index 24883d9..89e7bea 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/documents.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/documents.md @@ -10,7 +10,7 @@ ms.assetid: 7bf37ccb-5d09-4eae-9661-929582aeb259 --- # Documents -[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides a versatile set of components that enable developers to build applications with advanced document features and an improved reading experience. In addition to enhanced capabilities and quality, [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] also provides simplified management services for document packaging, security, and storage. +Windows Presentation Foundation (WPF) provides a versatile set of components that enable developers to build applications with advanced document features and an improved reading experience. In addition to enhanced capabilities and quality, Windows Presentation Foundation (WPF) also provides simplified management services for document packaging, security, and storage. ## In This Section diff --git a/dotnet-desktop-guide/framework/wpf/advanced/drag-and-drop-how-to-topics.md b/dotnet-desktop-guide/framework/wpf/advanced/drag-and-drop-how-to-topics.md index c403531..379055c 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/drag-and-drop-how-to-topics.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/drag-and-drop-how-to-topics.md @@ -8,7 +8,7 @@ helpviewer_keywords: ms.assetid: 559c0804-c62a-4640-b6b9-cbd2aa9fb99c --- # Drag and Drop How-to Topics -The following examples demonstrate how to accomplish common tasks using the [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] drag-and-drop framework. +The following examples demonstrate how to accomplish common tasks using the Windows Presentation Foundation (WPF) drag-and-drop framework. ## In This Section [Open a File That is Dropped on a RichTextBox Control](how-to-open-a-file-that-is-dropped-on-a-richtextbox-control.md) diff --git a/dotnet-desktop-guide/framework/wpf/advanced/drag-and-drop-overview.md b/dotnet-desktop-guide/framework/wpf/advanced/drag-and-drop-overview.md index 7cd6b36..920ad9c 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/drag-and-drop-overview.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/drag-and-drop-overview.md @@ -16,7 +16,7 @@ helpviewer_keywords: ms.assetid: 1a5b27b0-0ac5-4cdf-86c0-86ac0271fa64 --- # Drag and Drop Overview -This topic provides an overview of drag-and-drop support in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] applications. Drag-and-drop commonly refers to a method of data transfer that involves using a mouse (or some other pointing device) to select one or more objects, dragging these objects over some desired drop target in the [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)], and dropping them. +This topic provides an overview of drag-and-drop support in user interface (UI), and dropping them. ## Drag-and-Drop Support in WPF @@ -26,9 +26,9 @@ This topic provides an overview of drag-and-drop support in [!INCLUDE[TLA#tla_wi The particular actions performed during a drag-and-drop operation are application specific, and often determined by context. For example, dragging a selection of files from one folder to another on the same storage device moves the files by default, whereas dragging files from a Universal Naming Convention (UNC) share to a local folder copies the files by default. - The drag-and-drop facilities provided by [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] are designed to be highly flexible and customizable to support a wide variety of drag-and-drop scenarios. Drag-and-drop supports manipulating objects within a single application, or between different applications. Dragging-and-dropping between [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications and other Windows applications is also fully supported. + The drag-and-drop facilities provided by WPF are designed to be highly flexible and customizable to support a wide variety of drag-and-drop scenarios. Drag-and-drop supports manipulating objects within a single application, or between different applications. Dragging-and-dropping between WPF applications and other Windows applications is also fully supported. - In [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], any or can participate in drag-and-drop. The events and methods required for drag-and-drop operations are defined in the class. The and classes contain aliases for the attached events so that the events appear in the class members list when a or is inherited as a base element. Event handlers that are attached to these events are attached to the underlying attached event and receive the same event data instance. For more information, see the event. + In WPF, any or can participate in drag-and-drop. The events and methods required for drag-and-drop operations are defined in the class. The and classes contain aliases for the attached events so that the events appear in the class members list when a or is inherited as a base element. Event handlers that are attached to these events are attached to the underlying attached event and receive the same event data instance. For more information, see the event. > [!IMPORTANT] > OLE drag-and-drop does not work while in the Internet zone. @@ -50,9 +50,9 @@ This topic provides an overview of drag-and-drop support in [!INCLUDE[TLA#tla_wi The source and target of a drag-and-drop operation are UI elements; however, the data that is actually being transferred typically does not have a visual representation. You can write code to provide a visual representation of the data that is dragged, such as occurs when dragging files in Windows Explorer. By default, feedback is provided to the user by changing the cursor to represent the effect that the drag-and-drop operation will have on the data, such as whether the data will be moved or copied. ### Drag-and-Drop Effects - Drag-and-drop operations can have different effects on the transferred data. For example, you can copy the data or you can move the data. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] defines a enumeration that you can use to specify the effect of a drag-and-drop operation. In the drag source, you can specify the effects that the source will allow in the method. In the drop target, you can specify the effect that the target intends in the property of the class. When the drop target specifies its intended effect in the event, that information is passed back to the drag source in the event. The drag source uses this information to inform the user what effect the drop target intends to have on the data. When the data is dropped, the drop target specifies its actual effect in the event. That information is passed back to the drag source as the return value of the method. If the drop target returns an effect that is not in the drag sources list of `allowedEffects`, the drag-and-drop operation is cancelled without any data transfer occurring. + Drag-and-drop operations can have different effects on the transferred data. For example, you can copy the data or you can move the data. WPF defines a enumeration that you can use to specify the effect of a drag-and-drop operation. In the drag source, you can specify the effects that the source will allow in the method. In the drop target, you can specify the effect that the target intends in the property of the class. When the drop target specifies its intended effect in the event, that information is passed back to the drag source in the event. The drag source uses this information to inform the user what effect the drop target intends to have on the data. When the data is dropped, the drop target specifies its actual effect in the event. That information is passed back to the drag source as the return value of the method. If the drop target returns an effect that is not in the drag sources list of `allowedEffects`, the drag-and-drop operation is cancelled without any data transfer occurring. - It is important to remember that in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], the values are only used to provide communication between the drag source and the drop target regarding the effects of the drag-and-drop operation. The actual effect of the drag-and-drop operation depends on you to write the appropriate code in your application. + It is important to remember that in WPF, the values are only used to provide communication between the drag source and the drop target regarding the effects of the drag-and-drop operation. The actual effect of the drag-and-drop operation depends on you to write the appropriate code in your application. For example, the drop target might specify that the effect of dropping data on it is to move the data. However, to move the data, it must be both added to the target element and removed from the source element. The source element might indicate that it allows moving the data, but if you do not provide the code to remove the data from the source element, the end result will be that the data is copied, and not moved. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/drag-and-drop.md b/dotnet-desktop-guide/framework/wpf/advanced/drag-and-drop.md index 4ba1d44..b2015db 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/drag-and-drop.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/drag-and-drop.md @@ -10,7 +10,7 @@ helpviewer_keywords: ms.assetid: 77c48920-8c8b-41eb-8fe8-b411962c8623 --- # Drag and Drop -[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides a highly flexible drag and drop infrastructure which supports dragging and dropping of data within both [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications as well as other Windows applications. +WPF applications as well as other Windows applications. ## In This Section [Drag and Drop Overview](drag-and-drop-overview.md) diff --git a/dotnet-desktop-guide/framework/wpf/advanced/draw-text-using-glyphs.md b/dotnet-desktop-guide/framework/wpf/advanced/draw-text-using-glyphs.md index 54a6633..f08a31d 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/draw-text-using-glyphs.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/draw-text-using-glyphs.md @@ -8,14 +8,14 @@ helpviewer_keywords: ms.assetid: 587ab17e-a419-4ad5-b6da-8933a8e83d97 --- # Draw Text Using Glyphs -This topic explains how to use the low-level object to display text in [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)]. +This topic explains how to use the low-level object to display text in Extensible Application Markup Language (XAML). ## Example - The following examples show how to define properties for a object in [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)]. The object represents the output of a in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]. The examples assume that the Arial, Courier New, and Times New Roman fonts are installed in the C:\WINDOWS\Fonts folder on the local computer. + The following examples show how to define properties for a object in XAML. The examples assume that the Arial, Courier New, and Times New Roman fonts are installed in the C:\WINDOWS\Fonts folder on the local computer. [!code-xaml[GlyphsOvwSample1#1](~/samples/snippets/csharp/VS_Snippets_Wpf/GlyphsOvwSample1/CS/default.xaml#1)] - This example shows how to define other properties of objects in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]. + This example shows how to define other properties of objects in XAML. [!code-xaml[GlyphsOvwSamp2#1](~/samples/snippets/csharp/VS_Snippets_Wpf/GlyphsOvwSamp2/CS/default.xaml#1)] diff --git a/dotnet-desktop-guide/framework/wpf/advanced/drawing-formatted-text.md b/dotnet-desktop-guide/framework/wpf/advanced/drawing-formatted-text.md index 787cfb8..cc5916d 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/drawing-formatted-text.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/drawing-formatted-text.md @@ -13,7 +13,7 @@ ms.assetid: b1d851c1-331c-4814-9964-6fe769db6f1f --- # Drawing Formatted Text -This topic provides an overview of the features of the object. This object provides low-level control for drawing text in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] applications. +This topic provides an overview of the features of the object. This object provides low-level control for drawing text in Windows Presentation Foundation (WPF) applications. ## Technology Overview @@ -22,13 +22,13 @@ This topic provides an overview of the features of the [!NOTE] -> For those developers migrating from the Win32 API, the table in the [Win32 Migration](#win32_migration) section lists the Win32 DrawText flags and the approximate equivalent in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)]. +> For those developers migrating from the Win32 API, the table in the [Win32 Migration](#win32_migration) section lists the Win32 DrawText flags and the approximate equivalent in Windows Presentation Foundation (WPF). ### Reasons for Using Formatted Text - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] includes multiple controls for drawing text to the screen. Each control is targeted to a different scenario and has its own list of features and limitations. In general, the element should be used when limited text support is required, such as a brief sentence in a [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)]. can be used when minimal text support is required. For more information, see [Documents in WPF](documents-in-wpf.md). + WPF includes multiple controls for drawing text to the screen. Each control is targeted to a different scenario and has its own list of features and limitations. In general, the element should be used when limited text support is required, such as a brief sentence in a user interface (UI). can be used when minimal text support is required. For more information, see [Documents in WPF](documents-in-wpf.md). - The object provides greater text formatting features than [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] text controls, and can be useful in cases where you want to use text as a decorative element. For more information, see the following section [Converting Formatted Text to a Geometry](#converting_formatted_text). + The object provides greater text formatting features than Windows Presentation Foundation (WPF) text controls, and can be useful in cases where you want to use text as a decorative element. For more information, see the following section [Converting Formatted Text to a Geometry](#converting_formatted_text). In addition, the object is useful for creating text-oriented -derived objects. is a lightweight drawing class that is used to render shapes, images, or text. For more information, see [Hit Test Using DrawingVisuals Sample](https://github.com/Microsoft/WPF-Samples/tree/master/Visual%20Layer/DrawingVisual). @@ -49,7 +49,7 @@ This topic provides an overview of the features of the object uses device-independent pixels as the unit of measure. However, most Win32 applications use points as the unit of measure. If you want to use display text in units of points in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] applications, you need to convert device-independent units (1/96th inch per unit) to points. The following code example shows how to perform this conversion. + As with other text objects in Windows Presentation Foundation (WPF) applications, the object uses device-independent pixels as the unit of measure. However, most Win32 applications use points as the unit of measure. If you want to use display text in units of points in Windows Presentation Foundation (WPF) applications, you need to convert device-independent units (1/96th inch per unit) to points. The following code example shows how to perform this conversion. [!code-csharp[FormattedTextSnippets#FormattedTextSnippets2](~/samples/snippets/csharp/VS_Snippets_Wpf/FormattedTextSnippets/CSharp/Window1.xaml.cs#formattedtextsnippets2)] [!code-vb[FormattedTextSnippets#FormattedTextSnippets2](~/samples/snippets/visualbasic/VS_Snippets_Wpf/FormattedTextSnippets/visualbasic/window1.xaml.vb#formattedtextsnippets2)] @@ -89,7 +89,7 @@ Sphere following the path geometry of text ## Win32 Migration - The features of for drawing text are similar to the features of the Win32 DrawText function. For those developers migrating from the Win32 API, the following table lists the Win32 DrawText flags and the approximate equivalent in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)]. + The features of for drawing text are similar to the features of the Win32 DrawText function. For those developers migrating from the Win32 API, the following table lists the Win32 DrawText flags and the approximate equivalent in Windows Presentation Foundation (WPF). |DrawText flag|WPF equivalent|Notes| |-------------------|--------------------|-----------| diff --git a/dotnet-desktop-guide/framework/wpf/advanced/dynamicresource-markup-extension.md b/dotnet-desktop-guide/framework/wpf/advanced/dynamicresource-markup-extension.md index 01f27de..9803f51 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/dynamicresource-markup-extension.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/dynamicresource-markup-extension.md @@ -11,7 +11,7 @@ helpviewer_keywords: ms.assetid: 7324f243-03af-4c2b-b0db-26ac6cdfcbe4 --- # DynamicResource Markup Extension -Provides a value for any [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] property attribute by deferring that value to be a reference to a defined resource. Lookup behavior for that resource is analogous to run-time lookup. +Provides a value for any XAML property attribute by deferring that value to be a reference to a defined resource. Lookup behavior for that resource is analogous to run-time lookup. ## XAML Attribute Usage @@ -36,7 +36,7 @@ Provides a value for any [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla |`key`|The key for the requested resource. This key was initially assigned by the [x:Key Directive](/dotnet/desktop/xaml-services/xkey-directive) if a resource was created in markup, or was provided as the `key` parameter when calling if the resource was created in code.| ## Remarks - A `DynamicResource` will create a temporary expression during the initial compilation and thus defer lookup for resources until the requested resource value is actually required in order to construct an object. This may potentially be after the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] page is loaded. The resource value will be found based on key search against all active resource dictionaries starting from the current page scope, and is substituted for the placeholder expression from compilation. + A `DynamicResource` will create a temporary expression during the initial compilation and thus defer lookup for resources until the requested resource value is actually required in order to construct an object. This may potentially be after the XAML page is loaded. The resource value will be found based on key search against all active resource dictionaries starting from the current page scope, and is substituted for the placeholder expression from compilation. > [!IMPORTANT] > In terms of dependency property precedence, a `DynamicResource` expression is equivalent to the position where the dynamic resource reference is applied. If you set a local value for a property that previously had a `DynamicResource` expression as the local value, the `DynamicResource` is completely removed. For details, see [Dependency Property Value Precedence](dependency-property-value-precedence.md). @@ -63,9 +63,9 @@ Provides a value for any [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla The verbose usage is often useful for extensions that have more than one settable property, or if some properties are optional. Because `DynamicResource` has only one settable property, which is required, this verbose usage is not typical. - In the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor implementation, the handling for this markup extension is defined by the class. + In the WPF XAML processor implementation, the handling for this markup extension is defined by the class. - `DynamicResource` is a markup extension. Markup extensions are typically implemented when there is a requirement to escape attribute values to be other than literal values or handler names, and the requirement is more global than just putting type converters on certain types or properties. All markup extensions in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] use the { and } characters in their attribute syntax, which is the convention by which a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor recognizes that a markup extension must process the attribute. For more information, see [Markup Extensions and WPF XAML](markup-extensions-and-wpf-xaml.md). + `DynamicResource` is a markup extension. Markup extensions are typically implemented when there is a requirement to escape attribute values to be other than literal values or handler names, and the requirement is more global than just putting type converters on certain types or properties. All markup extensions in XAML use the { and } characters in their attribute syntax, which is the convention by which a XAML processor recognizes that a markup extension must process the attribute. For more information, see [Markup Extensions and WPF XAML](markup-extensions-and-wpf-xaml.md). ## See also diff --git a/dotnet-desktop-guide/framework/wpf/advanced/events-wpf.md b/dotnet-desktop-guide/framework/wpf/advanced/events-wpf.md index 2356b11..a4be080 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/events-wpf.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/events-wpf.md @@ -10,7 +10,7 @@ helpviewer_keywords: ms.assetid: d3b93c6f-aa6b-486d-a010-d097ea8a516b --- # Events (WPF) -[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] introduces routed events that can invoke handlers that exist on various listeners in the element tree of an application. +Windows Presentation Foundation (WPF) introduces routed events that can invoke handlers that exist on various listeners in the element tree of an application. ## In This Section [Routed Events Overview](routed-events-overview.md) diff --git a/dotnet-desktop-guide/framework/wpf/advanced/focus-overview.md b/dotnet-desktop-guide/framework/wpf/advanced/focus-overview.md index 53586d1..08df0a8 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/focus-overview.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/focus-overview.md @@ -12,7 +12,7 @@ helpviewer_keywords: ms.assetid: 0230c4eb-0c8a-462b-ac4b-ae3e511659f4 --- # Focus Overview -In [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] there are two main concepts that pertain to focus: keyboard focus and logical focus. Keyboard focus refers to the element that receives keyboard input and logical focus refers to the element in a focus scope that has focus. These concepts are discussed in detail in this overview. Understanding the difference in these concepts is important for creating complex applications that have multiple regions where focus can be obtained. +In WPF there are two main concepts that pertain to focus: keyboard focus and logical focus. Keyboard focus refers to the element that receives keyboard input and logical focus refers to the element in a focus scope that has focus. These concepts are discussed in detail in this overview. Understanding the difference in these concepts is important for creating complex applications that have multiple regions where focus can be obtained. The major classes that participate in focus management are the class, the class, and the base element classes, such as and . For more information about the base elements, see the [Base Elements Overview](base-elements-overview.md). @@ -20,11 +20,11 @@ In [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md) ## Keyboard Focus - Keyboard focus refers to the element that is currently receiving keyboard input. There can be only one element on the whole desktop that has keyboard focus. In [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], the element that has keyboard focus will have set to `true`. The static property on the class gets the element that currently has keyboard focus. + Keyboard focus refers to the element that is currently receiving keyboard input. There can be only one element on the whole desktop that has keyboard focus. In WPF, the element that has keyboard focus will have set to `true`. The static property on the class gets the element that currently has keyboard focus. In order for an element to obtain keyboard focus, the and the properties on the base elements must be set to `true`. Some classes, such as the base class, have set to `false` by default; therefore, you must set to `true` if you want such an element to be able to obtain keyboard focus. - Keyboard focus can be obtained through user interaction with the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)], such as tabbing to an element or clicking the mouse on certain elements. Keyboard focus can also be obtained programmatically by using the method on the class. The method attempts to give the specified element keyboard focus. The returned element is the element that has keyboard focus, which might be a different element than requested if either the old or new focus object block the request. + Keyboard focus can be obtained through user interaction with the UI, such as tabbing to an element or clicking the mouse on certain elements. Keyboard focus can also be obtained programmatically by using the method on the class. The method attempts to give the specified element keyboard focus. The returned element is the element that has keyboard focus, which might be a different element than requested if either the old or new focus object block the request. The following example uses the method to set keyboard focus on a . @@ -43,7 +43,7 @@ In [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md) An element that has keyboard focus has logical focus for the focus scope it belongs to. - An element can be turned into a focus scope in [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] by setting the attached property to `true`. In code, an element can be turned into a focus scope by calling . + An element can be turned into a focus scope in Extensible Application Markup Language (XAML) by setting the attached property to `true`. In code, an element can be turned into a focus scope by calling . The following example makes a into a focus scope by setting the attached property. @@ -54,7 +54,7 @@ In [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md) returns the focus scope for the specified element. - Classes in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] which are focus scopes by default are , , , and . + Classes in WPF which are focus scopes by default are , , , and . gets the focused element for the specified focus scope. sets the focused element in the specified focus scope. is typically used to set the initial focused element. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/fonts-how-to-topics.md b/dotnet-desktop-guide/framework/wpf/advanced/fonts-how-to-topics.md index f20ca25..bcbf9af 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/fonts-how-to-topics.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/fonts-how-to-topics.md @@ -8,7 +8,7 @@ helpviewer_keywords: ms.assetid: b4a97c97-7f88-4a89-b1d1-cf2c0d087955 --- # Fonts How-to Topics -The topics in this section demonstrate how to use the font features included with [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)]. +The topics in this section demonstrate how to use the font features included with Windows Presentation Foundation (WPF). ## In This Section [Enumerate System Fonts](how-to-enumerate-system-fonts.md) diff --git a/dotnet-desktop-guide/framework/wpf/advanced/fonts-wpf.md b/dotnet-desktop-guide/framework/wpf/advanced/fonts-wpf.md index 0951a65..dbe3204 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/fonts-wpf.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/fonts-wpf.md @@ -8,7 +8,7 @@ helpviewer_keywords: ms.assetid: 6c766a95-ad03-475e-a36f-2243e9495941 --- # Fonts (WPF) -[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] includes support for rich presentation of text using OpenType fonts. A sample pack of OpenType fonts is included with the Windows SDK. +Windows Presentation Foundation (WPF) includes support for rich presentation of text using OpenType fonts. A sample pack of OpenType fonts is included with the Windows SDK. ## In This Section [OpenType Font Features](opentype-font-features.md) diff --git a/dotnet-desktop-guide/framework/wpf/advanced/forwardtranslateaccelerator-function-wpf-unmanaged-api-reference.md b/dotnet-desktop-guide/framework/wpf/advanced/forwardtranslateaccelerator-function-wpf-unmanaged-api-reference.md index 455caff..add5de5 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/forwardtranslateaccelerator-function-wpf-unmanaged-api-reference.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/forwardtranslateaccelerator-function-wpf-unmanaged-api-reference.md @@ -40,7 +40,7 @@ HRESULT ForwardTranslateAccelerator( In the .NET Framework 4 and later: PresentationHost_v0400.dll - **.NET Framework Version:** [!INCLUDE[net_current_v30plus](../../../includes/net-current-v30plus-md.md)] + **.NET Framework Version:** Available since 3.0 ## See also diff --git a/dotnet-desktop-guide/framework/wpf/advanced/framework-property-metadata.md b/dotnet-desktop-guide/framework/wpf/advanced/framework-property-metadata.md index 7d2478e..2d48c1e 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/framework-property-metadata.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/framework-property-metadata.md @@ -7,11 +7,11 @@ helpviewer_keywords: ms.assetid: 9962f380-b885-4b61-a62e-457397083fea --- # Framework Property Metadata -Framework property metadata options are reported for the properties of object elements considered to be at the WPF framework level in the [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] architecture. In general the WPF framework-level designation entails that features such as rendering, data binding, and property system refinements are handled by the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] presentation APIs and executables. Framework property metadata is queried by these systems to determine feature-specific characteristics of particular element properties. +Framework property metadata options are reported for the properties of object elements considered to be at the WPF framework level in the WPF presentation APIs and executables. Framework property metadata is queried by these systems to determine feature-specific characteristics of particular element properties. ## Prerequisites - This topic assumes that you understand dependency properties from the perspective of a consumer of existing dependency properties on [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] classes, and have read the [Dependency Properties Overview](dependency-properties-overview.md). You should also have read [Dependency Property Metadata](dependency-property-metadata.md). + This topic assumes that you understand dependency properties from the perspective of a consumer of existing dependency properties on Windows Presentation Foundation (WPF) classes, and have read the [Dependency Properties Overview](dependency-properties-overview.md). You should also have read [Dependency Property Metadata](dependency-property-metadata.md). ## What Is Communicated by Framework Property Metadata @@ -24,11 +24,11 @@ Framework property metadata options are reported for the properties of object el - . By default, dependency properties do not inherit values. allows the pathway of inheritance to also travel into a visual tree, which is necessary for some control compositing scenarios. > [!NOTE] - > The term "inherits" in the context of property values means something specific for dependency properties; it means that child elements can inherit the actual dependency property value from parent elements because of a WPF framework-level capability of the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] property system. It has nothing to do directly with managed code type and members inheritance through derived types. For details, see [Property Value Inheritance](property-value-inheritance.md). + > The term "inherits" in the context of property values means something specific for dependency properties; it means that child elements can inherit the actual dependency property value from parent elements because of a WPF framework-level capability of the WPF property system. It has nothing to do directly with managed code type and members inheritance through derived types. For details, see [Property Value Inheritance](property-value-inheritance.md). -- Reporting data binding characteristics (, ). By default, dependency properties in the framework support data binding, with a one-way binding behavior. You might disable data binding if there were no scenario for it whatsoever (because they are intended to be flexible and extensible, there aren't many examples of such properties in the default [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] APIs). You might set binding to have a two-way default for properties that tie together a control's behaviors amongst its component pieces ( is an example) or where two-way binding is the common and expected scenario for users ( is an example). Changing the data binding–related metadata only influences the default; on a per-binding basis that default can always be changed. For details on the binding modes and binding in general, see [Data Binding Overview](../data/data-binding-overview.md). +- Reporting data binding characteristics (, ). By default, dependency properties in the framework support data binding, with a one-way binding behavior. You might disable data binding if there were no scenario for it whatsoever (because they are intended to be flexible and extensible, there aren't many examples of such properties in the default WPF APIs). You might set binding to have a two-way default for properties that tie together a control's behaviors amongst its component pieces ( is an example) or where two-way binding is the common and expected scenario for users ( is an example). Changing the data binding–related metadata only influences the default; on a per-binding basis that default can always be changed. For details on the binding modes and binding in general, see [Data Binding Overview](../data/data-binding-overview.md). -- Reporting whether properties should be journaled by applications or services that support journaling (). For general elements, journaling is not enabled by default, but it is selectively enabled for certain user input controls. This property is intended to be read by journaling services including the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] implementation of journaling, and is typically set on user controls such as user selections within lists that should be persisted across navigation steps. For information about the journal, see [Navigation Overview](../app-development/navigation-overview.md). +- Reporting whether properties should be journaled by applications or services that support journaling (). For general elements, journaling is not enabled by default, but it is selectively enabled for certain user input controls. This property is intended to be read by journaling services including the WPF implementation of journaling, and is typically set on user controls such as user selections within lists that should be persisted across navigation steps. For information about the journal, see [Navigation Overview](../app-development/navigation-overview.md). ## Reading FrameworkPropertyMetadata @@ -36,7 +36,7 @@ Framework property metadata options are reported for the properties of object el ## Specifying Metadata - When you create a new metadata instance for purposes of applying metadata to a new dependency property registration, you have the choice of which metadata class to use: the base or some derived class such as . In general, you should use , particularly if your property has any interaction with property system and [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] functions such as layout and data binding. Another option for more sophisticated scenarios is to derive from to create your own metadata reporting class with extra information carried in its members. Or you might use or to communicate the degree of support for features of your implementation. + When you create a new metadata instance for purposes of applying metadata to a new dependency property registration, you have the choice of which metadata class to use: the base or some derived class such as . In general, you should use , particularly if your property has any interaction with property system and WPF functions such as layout and data binding. Another option for more sophisticated scenarios is to derive from to create your own metadata reporting class with extra information carried in its members. Or you might use or to communicate the degree of support for features of your implementation. For existing properties ( or call), you should always override with the metadata type used by the original registration. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/freezable-objects-overview.md b/dotnet-desktop-guide/framework/wpf/advanced/freezable-objects-overview.md index 0999978..b01cd44 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/freezable-objects-overview.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/freezable-objects-overview.md @@ -23,7 +23,7 @@ A is a special type of object that has two state A provides a event to notify observers of any modifications to the object. Freezing a can improve its performance, because it no longer needs to spend resources on change notifications. A frozen can also be shared across threads, while an unfrozen cannot. -Although the class has many applications, most objects in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] are related to the graphics sub-system. +Although the class has many applications, most objects in Windows Presentation Foundation (WPF) are related to the graphics sub-system. The class makes it easier to use certain graphics system objects and can help improve application performance. Examples of types that inherit from include the , , and classes. Because they contain unmanaged resources, the system must monitor these objects for modifications, and then update their corresponding unmanaged resources when there is a change to the original object. Even if you don't actually modify a graphics system object, the system must still spend some of its resources monitoring the object, in case you do change it. @@ -32,7 +32,7 @@ For example, suppose you create a br [!code-csharp[freezablesample_procedural#FrozenExamplePart1](~/samples/snippets/csharp/VS_Snippets_Wpf/freezablesample_procedural/CSharp/freezablesample.cs#frozenexamplepart1)] [!code-vb[freezablesample_procedural#FrozenExamplePart1](~/samples/snippets/visualbasic/VS_Snippets_Wpf/freezablesample_procedural/visualbasic/freezablesample.vb#frozenexamplepart1)] -When the button is rendered, the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] graphics sub-system uses the information you provided to paint a group of pixels to create the appearance of a button. Although you used a solid color brush to describe how the button should be painted, your solid color brush doesn't actually do the painting. The graphics system generates fast, low-level objects for the button and the brush, and it is those objects that actually appear on the screen. +When the button is rendered, the WPF graphics sub-system uses the information you provided to paint a group of pixels to create the appearance of a button. Although you used a solid color brush to describe how the button should be painted, your solid color brush doesn't actually do the painting. The graphics system generates fast, low-level objects for the button and the brush, and it is those objects that actually appear on the screen. If you were to modify the brush, those low-level objects would have to be regenerated. The freezable class is what gives a brush the ability to find its corresponding generated, low-level objects and to update them when it changes. When this ability is enabled, the brush is said to be "unfrozen." diff --git a/dotnet-desktop-guide/framework/wpf/advanced/globalization-and-localization.md b/dotnet-desktop-guide/framework/wpf/advanced/globalization-and-localization.md index cb180cb..2ba4feb 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/globalization-and-localization.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/globalization-and-localization.md @@ -13,7 +13,7 @@ helpviewer_keywords: ms.assetid: e96f9764-4e3f-4d1c-bf20-3fb890118aae --- # Globalization and Localization -[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides extensive support for the development of world-ready applications. +Windows Presentation Foundation (WPF) provides extensive support for the development of world-ready applications. ## In This Section [WPF Globalization and Localization Overview](wpf-globalization-and-localization-overview.md) diff --git a/dotnet-desktop-guide/framework/wpf/advanced/globalization-for-wpf.md b/dotnet-desktop-guide/framework/wpf/advanced/globalization-for-wpf.md index 1927cd7..3d6455a 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/globalization-for-wpf.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/globalization-for-wpf.md @@ -9,11 +9,11 @@ helpviewer_keywords: ms.assetid: 4571ccfe-8a60-4f06-9b37-7ac0b1c2d10f --- # Globalization for WPF -This topic introduces issues that you should be aware of when writing [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] applications for the global market. The globalization programming elements are defined in .NET in the namespace. +This topic introduces issues that you should be aware of when writing Windows Presentation Foundation (WPF) applications for the global market. The globalization programming elements are defined in .NET in the namespace. ## XAML Globalization - Extensible Application Markup Language (XAML) is based on XML and takes advantage of the globalization support defined in the XML specification. The following sections describe some [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] features that you should be aware of. + Extensible Application Markup Language (XAML) is based on XML and takes advantage of the globalization support defined in the XML specification. The following sections describe some XAML features that you should be aware of. ### Character References @@ -31,7 +31,7 @@ The following example shows a hexadecimal character reference. Notice that it ha ### Encoding - The encoding supported by [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] are ASCII, Unicode UTF-16, and UTF-8. The encoding statement is at the beginning of [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] document. If no encoding attribute exists and there is no byte-order, the parser defaults to UTF-8. UTF-8 and UTF-16 are the preferred encodings. UTF-7 is not supported. The following example demonstrates how to specify a UTF-8 encoding in a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file. + The encoding supported by XAML are ASCII, Unicode UTF-16, and UTF-8. The encoding statement is at the beginning of XAML document. If no encoding attribute exists and there is no byte-order, the parser defaults to UTF-8. UTF-8 and UTF-16 are the preferred encodings. UTF-7 is not supported. The following example demonstrates how to specify a UTF-8 encoding in a XAML file. ```xaml ?xml encoding="UTF-8"? @@ -39,11 +39,11 @@ The following example shows a hexadecimal character reference. Notice that it ha ### Language Attribute - [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] uses [xml:lang](/dotnet/desktop/xaml-services/xml-language-handling) to represent the language attribute of an element. To take advantage of the class, the language attribute value needs to be one of the culture names predefined by . [xml:lang](/dotnet/desktop/xaml-services/xml-language-handling) is inheritable in the element tree (by XML rules, not necessarily because of dependency property inheritance) and its default value is an empty string if it is not assigned explicitly. + XAML uses [xml:lang](/dotnet/desktop/xaml-services/xml-language-handling) to represent the language attribute of an element. To take advantage of the class, the language attribute value needs to be one of the culture names predefined by . [xml:lang](/dotnet/desktop/xaml-services/xml-language-handling) is inheritable in the element tree (by XML rules, not necessarily because of dependency property inheritance) and its default value is an empty string if it is not assigned explicitly. The language attribute is very useful for specifying dialects. For example, French has different spelling, vocabulary, and pronunciation in France, Quebec, Belgium, and Switzerland. Also Chinese, Japanese, and Korean share code points in Unicode, but the ideographic shapes are different and they use totally different fonts. - The following [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] example uses the `fr-CA` language attribute to specify Canadian French. + The following Extensible Application Markup Language (XAML) example uses the `fr-CA` language attribute to specify Canadian French. ```xaml Découvrir la France @@ -51,15 +51,15 @@ The following example shows a hexadecimal character reference. Notice that it ha ### Unicode - [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] supports all Unicode features including surrogates. As long as the character set can be mapped to Unicode, it is supported. For example, GB18030 introduces some characters that are mapped to the Chinese, Japanese, and Korean (CFK) extension A and B and surrogate pairs, therefore it is fully supported. A [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application can use to manipulate strings without understanding whether they have surrogate pairs or combining characters. + WPF application can use to manipulate strings without understanding whether they have surrogate pairs or combining characters. ## Designing an International User Interface with XAML - This section describes [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] features that you should consider when writing an application. + This section describes user interface (UI) features that you should consider when writing an application. ### International Text - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] includes built-in processing for all Microsoft .NET Framework supported writing systems. + WPF includes built-in processing for all Microsoft .NET Framework supported writing systems. The following scripts are currently supported: @@ -121,11 +121,11 @@ The following example shows a hexadecimal character reference. Notice that it ha OpenType fonts allow the handling of large glyph sets using Unicode encoding. Such encoding enables broad international support as well as for typographic glyph variants. - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] text rendering is powered by Microsoft ClearType sub-pixel technology that supports resolution independence. This significantly improves legibility and provides the ability to support high quality magazine style documents for all scripts. + WPF text rendering is powered by Microsoft ClearType sub-pixel technology that supports resolution independence. This significantly improves legibility and provides the ability to support high quality magazine style documents for all scripts. ### International Layout - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides a very convenient way to support horizontal, bidirectional, and vertical layouts. In presentation framework the property can be used to define layout. The flow direction patterns are: + WPF provides a very convenient way to support horizontal, bidirectional, and vertical layouts. In presentation framework the property can be used to define layout. The flow direction patterns are: - *LeftToRight* - horizontal layout for Latin, East Asian and so forth. @@ -137,20 +137,20 @@ The following example shows a hexadecimal character reference. Notice that it ha ### Multilingual User Interface - Multilingual User Interfaces (MUI) is a Microsoft support for switching UIs from one language to another. A [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application uses the assembly model to support MUI. One application contains language-neutral assemblies as well as language-dependent satellite resource assemblies. The entry point is a managed .EXE in the main assembly. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] resource loader takes advantage of the Framework's resource manager to support resource lookup and fallback. Multiple language satellite assemblies work with the same main assembly. The resource assembly that is loaded depends on the of the current thread. + Multilingual User Interfaces (MUI) is a Microsoft support for switching UIs from one language to another. A WPF application uses the assembly model to support MUI. One application contains language-neutral assemblies as well as language-dependent satellite resource assemblies. The entry point is a managed .EXE in the main assembly. WPF resource loader takes advantage of the Framework's resource manager to support resource lookup and fallback. Multiple language satellite assemblies work with the same main assembly. The resource assembly that is loaded depends on the of the current thread. ### Localizable User Interface - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications use [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] to define their [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)]. [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] allows developers to specify a hierarchy of objects with a set of properties and logic. The primary use of [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] is to develop [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications but it can be used to specify a hierarchy of any common language runtime (CLR) objects. Most developers use [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] to specify their application's [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] and use a programming language such as C# to react to user interaction. + UI. UI and use a programming language such as C# to react to user interaction. - From a resource point of view, a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file designed to describe a language-dependent [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] is a resource element and therefore its final distribution format must be localizable to support international languages. Because [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] cannot handle events many [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] applications contain blocks of code to do this. For more information, see [XAML in WPF](xaml-in-wpf.md). Code is stripped out and compiled into different binaries when a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file is tokenized into the BAML form of XAML. The BAML form of XAML files, images, and other types of managed resource objects are embedded in the satellite resource assembly, which can be localized into other languages, or the main assembly when localization is not required. + From a resource point of view, a UI is a resource element and therefore its final distribution format must be localizable to support international languages. Because XAML cannot handle events many XAML applications contain blocks of code to do this. For more information, see [XAML in WPF](xaml-in-wpf.md). Code is stripped out and compiled into different binaries when a XAML file is tokenized into the BAML form of XAML. The BAML form of XAML files, images, and other types of managed resource objects are embedded in the satellite resource assembly, which can be localized into other languages, or the main assembly when localization is not required. > [!NOTE] -> [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications support all the FrameworkCLR resources including string tables, images, and so forth. +> WPF applications support all the FrameworkCLR resources including string tables, images, and so forth. ### Building Localizable Applications - Localization means to adapt a [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] to different cultures. To make a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application localizable, developers need to build all the localizable resources into a resource assembly. The resource assembly is localized into different languages, and the code-behind uses resource management API to load. One of the files required for a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application is a project file (.proj). All resources that you use in your application should be included in the project file. The following example from a .csproj file shows how to do this. + Localization means to adapt a UI to different cultures. To make a WPF application localizable, developers need to build all the localizable resources into a resource assembly. The resource assembly is localized into different languages, and the code-behind uses resource management API to load. One of the files required for a WPF application is a project file (.proj). All resources that you use in your application should be included in the project file. The following example from a .csproj file shows how to do this. ```xml diff --git a/dotnet-desktop-guide/framework/wpf/advanced/glyphs.md b/dotnet-desktop-guide/framework/wpf/advanced/glyphs.md index fd55680..5144e4c 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/glyphs.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/glyphs.md @@ -12,7 +12,7 @@ helpviewer_keywords: ms.assetid: d5d9274c-23b3-4859-8869-6e64403c9ca7 --- # Glyphs -Glyphs are a low-level depiction of a character to be drawn on-screen. [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides direct access to glyphs for customers who want to intercept and persist text after formatting. +Glyphs are a low-level depiction of a character to be drawn on-screen. Windows Presentation Foundation (WPF) provides direct access to glyphs for customers who want to intercept and persist text after formatting. ## In This Section [Introduction to the GlyphRun Object and Glyphs Element](introduction-to-the-glyphrun-object-and-glyphs-element.md) diff --git a/dotnet-desktop-guide/framework/wpf/advanced/graphics-rendering-tiers.md b/dotnet-desktop-guide/framework/wpf/advanced/graphics-rendering-tiers.md index bf917bc..8e5dcc6 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/graphics-rendering-tiers.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/graphics-rendering-tiers.md @@ -11,7 +11,7 @@ ms.assetid: 08dd1606-02a2-4122-9351-c0afd2ec3a70 --- # Graphics Rendering Tiers -A rendering tier defines a level of graphics hardware capability and performance for a device that runs a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application. +A rendering tier defines a level of graphics hardware capability and performance for a device that runs a WPF application. @@ -31,7 +31,7 @@ A rendering tier defines a level of graphics hardware capability and performance ## Rendering Tier Definitions - The features of the graphics hardware determine the rendering capability of a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application. The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] system defines three rendering tiers: + The features of the graphics hardware determine the rendering capability of a WPF application. The WPF system defines three rendering tiers: - **Rendering Tier 0** No graphics hardware acceleration. All graphics features use software acceleration. The DirectX version level is less than version 9.0. @@ -50,7 +50,7 @@ A rendering tier defines a level of graphics hardware capability and performance > [!NOTE] > Starting in the .NET Framework 4, rendering tier 1 has been redefined to only include graphics hardware that supports DirectX 9.0 or greater. Graphics hardware that supports DirectX 7 or 8 is now defined as rendering tier 0. - A rendering tier value of 1 or 2 means that most of the graphics features of [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] will use hardware acceleration if the necessary system resources are available and have not been exhausted. This corresponds to a DirectX version that is greater than or equal to 9.0. + A rendering tier value of 1 or 2 means that most of the graphics features of WPF will use hardware acceleration if the necessary system resources are available and have not been exhausted. This corresponds to a DirectX version that is greater than or equal to 9.0. The following table shows the differences in graphics hardware requirements for rendering tier 1 and rendering tier 2: @@ -68,10 +68,10 @@ A rendering tier defines a level of graphics hardware capability and performance |-------------|-----------| |2D rendering|Most 2D rendering is supported.| |3D rasterization|Most 3D rasterization is supported.| -|3D anisotropic filtering|[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] attempts to use anisotropic filtering when rendering 3D content. Anisotropic filtering refers to enhancing the image quality of textures on surfaces that are far away and steeply angled with respect to the camera.| -|3D MIP mapping|[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] attempts to use MIP mapping when rendering 3D content. MIP mapping improves the quality of texture rendering when a texture occupies a smaller field of view in a .| +|3D anisotropic filtering|WPF attempts to use anisotropic filtering when rendering 3D content. Anisotropic filtering refers to enhancing the image quality of textures on surfaces that are far away and steeply angled with respect to the camera.| +|3D MIP mapping|WPF attempts to use MIP mapping when rendering 3D content. MIP mapping improves the quality of texture rendering when a texture occupies a smaller field of view in a .| |Radial gradients|While supported, avoid the use of on large objects.| -|3D lighting calculations|[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] performs per-vertex lighting, which means that a light intensity must be calculated at each vertex for each material applied to a mesh.| +|3D lighting calculations|WPF performs per-vertex lighting, which means that a light intensity must be calculated at each vertex for each material applied to a mesh.| |Text rendering|Subpixel font rendering uses available pixel shaders on the graphics hardware.| The following features and capabilities are hardware accelerated only for rendering tier 2: @@ -84,40 +84,40 @@ A rendering tier defines a level of graphics hardware capability and performance |Feature|Notes| |-------------|-----------| -|Printed content|All printed content is rendered using the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] software pipeline.| +|Printed content|All printed content is rendered using the WPF software pipeline.| |Rasterized content that uses |Any content rendered by using the method of .| |Tiled content that uses |Any tiled content in which the property of the is set to .| |Surfaces that exceed the maximum texture size of the graphics hardware|For most graphics hardware, large surfaces are 2048x2048 or 4096x4096 pixels in size.| |Any operation whose video RAM requirement exceeds the memory of the graphics hardware|You can monitor application video RAM usage by using the Perforator tool that is included in the [WPF Performance Suite](/previous-versions/dotnet/netframework-4.0/aa969767(v=vs.100)) in the Windows SDK.| -|Layered windows|Layered windows allow [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications to render content to the screen in a non-rectangular window. On operating systems that support Windows Display Driver Model (WDDM), such as Windows Vista and Windows 7, layered windows are hardware accelerated. On other systems, such as Windows XP, layered windows are rendered by software with no hardware acceleration.

You can enable layered windows in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] by setting the following properties:

- =
- = `true`
- = | +|Layered windows|Layered windows allow WPF applications to render content to the screen in a non-rectangular window. On operating systems that support Windows Display Driver Model (WDDM), such as Windows Vista and Windows 7, layered windows are hardware accelerated. On other systems, such as Windows XP, layered windows are rendered by software with no hardware acceleration.

You can enable layered windows in WPF by setting the following properties:

- =
- = `true`
- = | ## Other Resources - The following resources can help you analyze the performance characteristics of your [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application. + The following resources can help you analyze the performance characteristics of your WPF application. ### Graphics Rendering Registry Settings - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides four registry settings for controlling [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] rendering: + WPF provides four registry settings for controlling WPF rendering: |Setting|Description| |-------------|-----------------| |**Disable Hardware Acceleration Option**|Specifies whether hardware acceleration should be enabled.| |**Maximum Multisample Value**|Specifies the degree of multisampling for antialiasing 3D content.| |**Required Video Driver Date Setting**|Specifies whether the system disables hardware acceleration for drivers released before November 2004.| -|**Use Reference Rasterizer Option**|Specifies whether [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] should use the reference rasterizer.| +|**Use Reference Rasterizer Option**|Specifies whether WPF should use the reference rasterizer.| - These settings can be accessed by any external configuration utility that knows how to reference the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] registry settings. These settings can also be created or modified by accessing the values directly by using the Windows Registry Editor. For more information, see [Graphics Rendering Registry Settings](../graphics-multimedia/graphics-rendering-registry-settings.md). + These settings can be accessed by any external configuration utility that knows how to reference the WPF registry settings. These settings can also be created or modified by accessing the values directly by using the Windows Registry Editor. For more information, see [Graphics Rendering Registry Settings](../graphics-multimedia/graphics-rendering-registry-settings.md). ### WPF Performance Profiling Tools - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides a suite of performance profiling tools that allow you to analyze the run-time behavior of your application and determine the types of performance optimizations you can apply. The following table lists the performance profiling tools that are included in the Windows SDK tool, WPF Performance Suite: + WPF provides a suite of performance profiling tools that allow you to analyze the run-time behavior of your application and determine the types of performance optimizations you can apply. The following table lists the performance profiling tools that are included in the Windows SDK tool, WPF Performance Suite: |Tool|Description| |----------|-----------------| |Perforator|Use for analyzing rendering behavior.| -|Visual Profiler|Use for profiling the use of [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] services, such as layout and event handling, by elements in the visual tree.| +|Visual Profiler|Use for profiling the use of WPF services, such as layout and event handling, by elements in the visual tree.| The WPF Performance Suite provides a rich, graphical view of performance data. For more information about WPF performance tools, see [WPF Performance Suite](/previous-versions/dotnet/netframework-4.0/aa969767(v=vs.100)). diff --git a/dotnet-desktop-guide/framework/wpf/advanced/hosting-win32-content-in-wpf.md b/dotnet-desktop-guide/framework/wpf/advanced/hosting-win32-content-in-wpf.md index 07fd1a3..a18e652 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/hosting-win32-content-in-wpf.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/hosting-win32-content-in-wpf.md @@ -16,7 +16,7 @@ See [WPF and Win32 Interoperation](wpf-and-win32-interoperation.md). ## A Walkthrough of Win32 Inside Windows Presentation Framework (HwndHost) -To reuse Win32 content inside [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications, use , which is a control that makes HWNDs look like [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content. Like , is straightforward to use: derive from and implement `BuildWindowCore` and `DestroyWindowCore` methods, then instantiate your derived class and place it inside your [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application. +To reuse Win32 content inside WPF applications, use , which is a control that makes HWNDs look like WPF content. Like , is straightforward to use: derive from and implement `BuildWindowCore` and `DestroyWindowCore` methods, then instantiate your derived class and place it inside your WPF application. If your Win32 logic is already packaged as a control, then your `BuildWindowCore` implementation is little more than a call to `CreateWindow`. For example, to create a Win32 LISTBOX control in C++: @@ -41,11 +41,11 @@ virtual void DestroyWindowCore(HandleRef hwnd) override { } ``` -But suppose the Win32 code is not quite so self-contained? If so, you can create a Win32 dialog box and embed its contents into a larger [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application. The sample shows this in Visual Studio and C++, although it is also possible to do this in a different language or at the command line. +But suppose the Win32 code is not quite so self-contained? If so, you can create a Win32 dialog box and embed its contents into a larger WPF application. The sample shows this in Visual Studio and C++, although it is also possible to do this in a different language or at the command line. Start with a simple dialog, which is compiled into a C++ DLL project. -Next, introduce the dialog into the larger [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application: +Next, introduce the dialog into the larger WPF application: - Compile the DLL as managed (`/clr`) @@ -59,7 +59,7 @@ Next, introduce the dialog into the larger [!INCLUDE[TLA2#tla_winclient](../../. - Override `OnMnemonic` method to support mnemonics -- Instantiate the subclass and put it under the right [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] element +- Instantiate the subclass and put it under the right WPF element ### Turn the Dialog into a Control @@ -227,7 +227,7 @@ Both MSGs have the same data, but sometimes it is easier to work with the unmana } ``` -Back to `TranslateAccelerator`. The basic principle is to call the Win32 function `IsDialogMessage` to do as much work as possible, but `IsDialogMessage` does not have access to anything outside the dialog. As a user tab around the dialog, when tabbing runs past the last control in our dialog, you need to set focus to the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] portion by calling `IKeyboardInputSite::OnNoMoreStops`. +Back to `TranslateAccelerator`. The basic principle is to call the Win32 function `IsDialogMessage` to do as much work as possible, but `IsDialogMessage` does not have access to anything outside the dialog. As a user tab around the dialog, when tabbing runs past the last control in our dialog, you need to set focus to the WPF portion by calling `IKeyboardInputSite::OnNoMoreStops`. ```cpp // Win32's IsDialogMessage() will handle most of the tabbing, but doesn't know @@ -249,7 +249,7 @@ if (m.message == WM_KEYDOWN && m.wParam == VK_TAB) { } ``` -Finally, call `IsDialogMessage`. But one of the responsibilities of a `TranslateAccelerator` method is telling [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] whether you handled the keystroke or not. If you did not handle it, the input event can tunnel and bubble through the rest of the application. Here, you will expose a quirk of keyboard messange handling and the nature of the input architecture in Win32. Unfortunately, `IsDialogMessage` does not return in any way whether it handles a particular keystroke. Even worse, it will call `DispatchMessage()` on keystrokes it should not handle! So you will have to reverse-engineer `IsDialogMessage`, and only call it for the keys you know it will handle: +Finally, call `IsDialogMessage`. But one of the responsibilities of a `TranslateAccelerator` method is telling WPF whether you handled the keystroke or not. If you did not handle it, the input event can tunnel and bubble through the rest of the application. Here, you will expose a quirk of keyboard messange handling and the nature of the input architecture in Win32. Unfortunately, `IsDialogMessage` does not return in any way whether it handles a particular keystroke. Even worse, it will call `DispatchMessage()` on keystrokes it should not handle! So you will have to reverse-engineer `IsDialogMessage`, and only call it for the keys you know it will handle: ```cpp // Only call IsDialogMessage for keys it will do something with. @@ -274,7 +274,7 @@ if (msg.message == WM_SYSKEYDOWN || msg.message == WM_KEYDOWN) { ### Override TabInto Method to Support Tabbing -Now that you have implemented `TranslateAccelerator`, a user can tab around inside the dialog box and tab out of it into the greater [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application. But a user cannot tab back into the dialog box. To solve that, you override `TabInto`: +Now that you have implemented `TranslateAccelerator`, a user can tab around inside the dialog box and tab out of it into the greater WPF application. But a user cannot tab back into the dialog box. To solve that, you override `TabInto`: ```cpp public: @@ -325,11 +325,11 @@ virtual bool OnMnemonic(System::Windows::Interop::MSG% msg, ModifierKeys modifie }; ``` -Why not call `IsDialogMessage` here? You have the same issue as before--you need to be able to inform [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] code whether your code handled the keystroke or not, and `IsDialogMessage` cannot do that. There is also a second issue, because `IsDialogMessage` refuses to process the mnemonic if the focused HWND is not inside the dialog box. +Why not call `IsDialogMessage` here? You have the same issue as before--you need to be able to inform WPF code whether your code handled the keystroke or not, and `IsDialogMessage` cannot do that. There is also a second issue, because `IsDialogMessage` refuses to process the mnemonic if the focused HWND is not inside the dialog box. ### Instantiate the HwndHost Derived Class -Finally, now that all the key and tab support is in place, you can put your into the larger [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application. If the main application is written in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], the easiest way to put it in the right place is to leave an empty element where you want to put the . Here you create a named `insertHwndHostHere`: +Finally, now that all the key and tab support is in place, you can put your into the larger WPF application. If the main application is written in XAML, the easiest way to put it in the right place is to leave an empty element where you want to put the . Here you create a named `insertHwndHostHere`: ```xaml to an existing page that is initially defined in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]. A code-behind file implements an event handler method and then adds that method as a new event handler on the . + The following example adds a new to an existing page that is initially defined in XAML. A code-behind file implements an event handler method and then adds that method as a new event handler on the . The C# example uses the `+=` operator to assign a handler to an event. This is the same operator that is used to assign a handler in the common language runtime (CLR) event handling model. Microsoft Visual Basic does not support this operator as a means of adding event handlers. It instead requires one of two techniques: @@ -30,7 +30,7 @@ This example shows how to add an event handler to an element by using code. [!code-vb[RoutedEventAddRemoveHandler#Handler](~/samples/snippets/visualbasic/VS_Snippets_Wpf/RoutedEventAddRemoveHandler/VisualBasic/default.xaml.vb#handler)] > [!NOTE] -> Adding an event handler in the initially parsed [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] page is much simpler. Within the object element where you want to add the event handler, add an attribute that matches the name of the event that you want to handle. Then specify the value of that attribute as the name of the event handler method that you defined in the code-behind file of the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] page. For more information, see [XAML in WPF](xaml-in-wpf.md) or [Routed Events Overview](routed-events-overview.md). +> Adding an event handler in the initially parsed XAML page is much simpler. Within the object element where you want to add the event handler, add an attribute that matches the name of the event that you want to handle. Then specify the value of that attribute as the name of the event handler method that you defined in the code-behind file of the XAML page. For more information, see [XAML in WPF](xaml-in-wpf.md) or [Routed Events Overview](routed-events-overview.md). ## See also diff --git a/dotnet-desktop-guide/framework/wpf/advanced/how-to-add-an-owner-type-for-a-dependency-property.md b/dotnet-desktop-guide/framework/wpf/advanced/how-to-add-an-owner-type-for-a-dependency-property.md index 204dacd..b9d7839 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/how-to-add-an-owner-type-for-a-dependency-property.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/how-to-add-an-owner-type-for-a-dependency-property.md @@ -10,11 +10,11 @@ helpviewer_keywords: ms.assetid: edcce050-0576-4edb-a31a-3f909637b452 --- # How to: Add an Owner Type for a Dependency Property -This example shows how to add a class as an owner of a dependency property registered for a different type. By doing this, the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] reader and property system are both able to recognize the class as an additional owner of the property. Adding as owner optionally allows the adding class to provide type-specific metadata. +This example shows how to add a class as an owner of a dependency property registered for a different type. By doing this, the WPF XAML reader and property system are both able to recognize the class as an additional owner of the property. Adding as owner optionally allows the adding class to provide type-specific metadata. In the following example, `StateProperty` is a property registered by the `MyStateControl` class. The class `UnrelatedStateControl` adds itself as an owner of the `StateProperty` using the method, specifically using the signature that allows for new metadata for the dependency property as it exists on the adding type. Notice that you should provide common language runtime (CLR) accessors for the property similar to the example shown in the [Implement a Dependency Property](how-to-implement-a-dependency-property.md) example, as well as re-expose the dependency property identifier on the class being added as owner. - Without wrappers, the dependency property would still work from the perspective of programmatic access using or . But you typically want to parallel this property-system behavior with the CLR property wrappers. The wrappers make it easier to set the dependency property programmatically, and make it possible to set the properties as [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] attributes. + Without wrappers, the dependency property would still work from the perspective of programmatic access using or . But you typically want to parallel this property-system behavior with the CLR property wrappers. The wrappers make it easier to set the dependency property programmatically, and make it possible to set the properties as XAML attributes. To find out how to override default metadata, see [Override Metadata for a Dependency Property](how-to-override-metadata-for-a-dependency-property.md). diff --git a/dotnet-desktop-guide/framework/wpf/advanced/how-to-apply-a-focusvisualstyle-to-a-control.md b/dotnet-desktop-guide/framework/wpf/advanced/how-to-apply-a-focusvisualstyle-to-a-control.md index dbbf979..9e78bf9 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/how-to-apply-a-focusvisualstyle-to-a-control.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/how-to-apply-a-focusvisualstyle-to-a-control.md @@ -10,7 +10,7 @@ ms.assetid: 363de99e-8ecc-438c-ac4a-f9147432ebd6 This example shows you how to create a focus visual style in resources and apply the style to a control, using the property. ## Example - The following example defines a style that creates additional control compositing that only applies when that control is keyboard focused in the [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)]. This is accomplished by defining a style with a , then referencing that style as a resource when setting the property. + The following example defines a style that creates additional control compositing that only applies when that control is keyboard focused in the user interface (UI). This is accomplished by defining a style with a , then referencing that style as a resource when setting the property. An external rectangle resembling a border is placed outside of the rectangular area. Unless otherwise modified, the sizing of the style uses the and of the rectangular control where the focus visual style is applied. This example sets negative values for the to make the border appear slightly outside the focused control. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/how-to-build-a-table-programmatically.md b/dotnet-desktop-guide/framework/wpf/advanced/how-to-build-a-table-programmatically.md index 9cb2273..88be253 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/how-to-build-a-table-programmatically.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/how-to-build-a-table-programmatically.md @@ -11,7 +11,7 @@ helpviewer_keywords: ms.assetid: e3ca88f3-6e94-4b61-82fc-42104c10b761 --- # How to: Build a Table Programmatically -The following examples show how to programmatically create a and populate it with content. The contents of the table are apportioned into five rows (represented by objects contained in a object) and six columns (represented by objects). The rows are used for different presentation purposes, including a title row intended to title the entire table, a header row to describe the columns of data in the table, and a footer row with summary information. Note that the notion of "title", "header", and "footer" rows are not inherent to the table; these are simply rows with different characteristics. Table cells contain the actual content, which can be comprised of text, images, or nearly any other [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] element. +The following examples show how to programmatically create a and populate it with content. The contents of the table are apportioned into five rows (represented by objects contained in a object) and six columns (represented by objects). The rows are used for different presentation purposes, including a title row intended to title the entire table, a header row to describe the columns of data in the table, and a footer row with summary information. Note that the notion of "title", "header", and "footer" rows are not inherent to the table; these are simply rows with different characteristics. Table cells contain the actual content, which can be comprised of text, images, or nearly any other user interface (UI) element. ## Create a table First, a is created to host the , and a new is created and added to the contents of the . diff --git a/dotnet-desktop-guide/framework/wpf/advanced/how-to-change-the-color-of-an-element-using-focus-events.md b/dotnet-desktop-guide/framework/wpf/advanced/how-to-change-the-color-of-an-element-using-focus-events.md index 6fcdc20..d56a9e8 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/how-to-change-the-color-of-an-element-using-focus-events.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/how-to-change-the-color-of-an-element-using-focus-events.md @@ -13,7 +13,7 @@ ms.assetid: 7e246802-3625-47a7-ae9d-c8a2a40fd040 # How to: Change the Color of an Element Using Focus Events This example shows how to change the color of an element when it gains and loses focus by using the and events. - This example consists of a [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] file and a code-behind file. + This example consists of a Extensible Application Markup Language (XAML) file and a code-behind file. ## Example The following XAML creates the user interface, which consists of two objects, and attaches event handlers for the and events to the objects. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/how-to-change-the-cursor-type.md b/dotnet-desktop-guide/framework/wpf/advanced/how-to-change-the-cursor-type.md index e0ead98..557efc7 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/how-to-change-the-cursor-type.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/how-to-change-the-cursor-type.md @@ -13,7 +13,7 @@ ms.assetid: 08c945a7-8ab0-4320-acf3-0b4955a344c2 # How to: Change the Cursor Type This example shows how to change the of the mouse pointer for a specific element and for the application. - This example consists of a [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] file and a code behind file. + This example consists of a Extensible Application Markup Language (XAML) file and a code behind file. ## Example The user interface is created, which consists of a to select the desired , a pair of objects to determine if the cursor change applies to only a single element or applies to the entire application, and a which is the element that the new cursor is applied to. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/how-to-change-the-textwrapping-property-programmatically.md b/dotnet-desktop-guide/framework/wpf/advanced/how-to-change-the-textwrapping-property-programmatically.md index 8a8d251..88d4727 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/how-to-change-the-textwrapping-property-programmatically.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/how-to-change-the-textwrapping-property-programmatically.md @@ -13,7 +13,7 @@ ms.assetid: 30d25554-4c82-4df9-a8d6-35683a4a13bb ## Example The following code example shows how to change the value of the property programmatically. - Three elements are placed within a element in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]. Each event for a corresponds with an event handler in the code. The event handlers use the same name as the value they will apply to `txt2` when the button is clicked. Also, the text in `txt1` (a not shown in the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]) is updated to reflect the change in the property. + Three elements are placed within a element in XAML. Each event for a corresponds with an event handler in the code. The event handlers use the same name as the value they will apply to `txt2` when the button is clicked. Also, the text in `txt1` (a not shown in the XAML) is updated to reflect the change in the property. [!code-xaml[TextWrapProperty#1](~/samples/snippets/visualbasic/VS_Snippets_Wpf/TextWrapProperty/VisualBasic/Pane1.xaml#1)] diff --git a/dotnet-desktop-guide/framework/wpf/advanced/how-to-create-a-custom-routed-event.md b/dotnet-desktop-guide/framework/wpf/advanced/how-to-create-a-custom-routed-event.md index 1576a2b..81744a9 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/how-to-create-a-custom-routed-event.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/how-to-create-a-custom-routed-event.md @@ -17,14 +17,14 @@ For your custom event to support event routing, you need to register a ; that subclass is built as a separate assembly and then instantiated as a custom class on a separate [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] page. This is to illustrate the concept that subclassed controls can be inserted into trees composed of other controls, and that in this situation, custom events on these controls have the very same event routing capabilities as any native [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] element does. + Note also that this example basically implements an entire subclass of ; that subclass is built as a separate assembly and then instantiated as a custom class on a separate Windows Presentation Foundation (WPF) element does. [!code-csharp[RoutedEventCustom#CustomClass](~/samples/snippets/csharp/VS_Snippets_Wpf/RoutedEventCustom/CSharp/SDKSampleLibrary/class1.cs#customclass)] [!code-vb[RoutedEventCustom#CustomClass](~/samples/snippets/visualbasic/VS_Snippets_Wpf/RoutedEventCustom/VB/SDKSampleLibrary/Class1.vb#customclass)] [!code-xaml[RoutedEventCustom#Page](~/samples/snippets/csharp/VS_Snippets_Wpf/RoutedEventCustom/CSharp/RoutedEventCustomApp/default.xaml#page)] - Tunneling events are created the same way, but with set to in the registration call. By convention, tunneling events in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] are prefixed with the word "Preview". + Tunneling events are created the same way, but with set to in the registration call. By convention, tunneling events in WPF are prefixed with the word "Preview". To see an example of how bubbling events work, see [Handle a Routed Event](how-to-handle-a-routed-event.md). diff --git a/dotnet-desktop-guide/framework/wpf/advanced/how-to-create-a-rollover-effect-using-events.md b/dotnet-desktop-guide/framework/wpf/advanced/how-to-create-a-rollover-effect-using-events.md index e94f00a..5b1716d 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/how-to-create-a-rollover-effect-using-events.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/how-to-create-a-rollover-effect-using-events.md @@ -13,7 +13,7 @@ ms.assetid: 3b20d028-6f1c-4b25-95d2-fa68cefbdb4c # How to: Create a Rollover Effect Using Events This example shows how to change the color of an element as the mouse pointer enters and leaves the area occupied by the element. - This example consists of a [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] file and a code-behind file. + This example consists of a Extensible Application Markup Language (XAML) file and a code-behind file. > [!NOTE] > This example demonstrates how to use events, but the recommended way to achieve this same effect is to use a in a style. For more information, see [Styling and Templating](../controls/styles-templates-overview.md). diff --git a/dotnet-desktop-guide/framework/wpf/advanced/how-to-create-outlined-text.md b/dotnet-desktop-guide/framework/wpf/advanced/how-to-create-outlined-text.md index 80fc647..040e48c 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/how-to-create-outlined-text.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/how-to-create-outlined-text.md @@ -14,7 +14,7 @@ ms.assetid: 4aa3cf6e-1953-4f26-8230-7c1409e5f28d --- # How to: Create outlined text -In most cases, when you're adding ornamentation to text strings in your [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] application, you are using text in terms of a collection of discrete characters, or glyphs. For example, you could create a linear gradient brush and apply it to the property of a object. When you display or edit the text box, the linear gradient brush is automatically applied to the current set of characters in the text string. +In most cases, when you're adding ornamentation to text strings in your Windows Presentation Foundation (WPF) application, you are using text in terms of a collection of discrete characters, or glyphs. For example, you could create a linear gradient brush and apply it to the property of a object. When you display or edit the text box, the linear gradient brush is automatically applied to the current set of characters in the text string. ![Text displayed with a linear gradient brush](./media/how-to-create-outlined-text/text-linear-gradient.jpg) diff --git a/dotnet-desktop-guide/framework/wpf/advanced/how-to-create-text-with-a-shadow.md b/dotnet-desktop-guide/framework/wpf/advanced/how-to-create-text-with-a-shadow.md index 2bde024..2320cc9 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/how-to-create-text-with-a-shadow.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/how-to-create-text-with-a-shadow.md @@ -11,7 +11,7 @@ ms.assetid: 6ab9c754-6001-4708-b479-5367f2fd1a35 The examples in this section show how to create a shadow effect for displayed text. ## Example - The object allows you to create a variety of drop shadow effects for [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] objects. The following example shows a drop shadow effect applied to text. In this case, the shadow is a soft shadow, which means the shadow color blurs. + The object allows you to create a variety of drop shadow effects for Windows Presentation Foundation (WPF) objects. The following example shows a drop shadow effect applied to text. In this case, the shadow is a soft shadow, which means the shadow color blurs. ![Text shadow with Softness = 0.25](./media/how-to-create-text-with-a-shadow/drop-shadow-text-effect.jpg) @@ -20,7 +20,7 @@ The examples in this section show how to create a shadow effect for displayed te [!code-xaml[TextShadowSnippets#TextShadowSnippet1](~/samples/snippets/csharp/VS_Snippets_Wpf/TextShadowSnippets/CS/SingleShadows.xaml#textshadowsnippet1)] > [!NOTE] -> These shadow effects do not go through the [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] text rendering pipeline. As a result, ClearType is disabled when using these effects. +> These shadow effects do not go through the Windows Presentation Foundation (WPF) text rendering pipeline. As a result, ClearType is disabled when using these effects. The following example shows a hard drop shadow effect applied to text. In this case, the shadow is not blurred. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/how-to-define-a-table-with-xaml.md b/dotnet-desktop-guide/framework/wpf/advanced/how-to-define-a-table-with-xaml.md index 1c0283f..6c7376c 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/how-to-define-a-table-with-xaml.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/how-to-define-a-table-with-xaml.md @@ -8,7 +8,7 @@ helpviewer_keywords: ms.assetid: 83f2dc58-437e-4cdc-b5dd-0019810c7a85 --- # How to: Define a Table with XAML -The following example demonstrates how to define a using [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)]. The example table has four columns (represented by elements) and several rows (represented by elements) containing data as well as title, header, and footer information. Rows must be contained in a element. Each row in the table is comprised of one or more cells (represented by elements). Content in a table cell must be contained in a element; in this case elements are used. The table also hosts a hyperlink (represented by the element) in the footer row. +The following example demonstrates how to define a using Extensible Application Markup Language (XAML). The example table has four columns (represented by elements) and several rows (represented by elements) containing data as well as title, header, and footer information. Rows must be contained in a element. Each row in the table is comprised of one or more cells (represented by elements). Content in a table cell must be contained in a element; in this case elements are used. The table also hosts a hyperlink (represented by the element) in the footer row. ## Example [!code-xaml[TableSnippetsXAML#_TableXAML](~/samples/snippets/csharp/VS_Snippets_Wpf/TableSnippetsXAML/CS/Window1.xaml#_tablexaml)] diff --git a/dotnet-desktop-guide/framework/wpf/advanced/how-to-define-and-reference-a-resource.md b/dotnet-desktop-guide/framework/wpf/advanced/how-to-define-and-reference-a-resource.md index 418a168..7576621 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/how-to-define-and-reference-a-resource.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/how-to-define-and-reference-a-resource.md @@ -11,11 +11,11 @@ ms.assetid: b86b876b-0a10-489b-9a5d-581ea9b32406 # How to: Define and Reference a Resource -This example shows how to define a resource and reference it by using an attribute in [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)]. +This example shows how to define a resource and reference it by using an attribute in Extensible Application Markup Language (XAML). ## Example -The following example defines two types of resources: a resource, and several resources. The resource `MyBrush` is used to provide the value of several properties that each take a type value. The resources `PageBackground`, `TitleText` and `Label` each target a particular control type. The styles set a variety of different properties on the targeted controls, when that style resource is referenced by resource key and is used to set the property of several specific control elements defined in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]. +The following example defines two types of resources: a resource, and several resources. The resource `MyBrush` is used to provide the value of several properties that each take a type value. The resources `PageBackground`, `TitleText` and `Label` each target a particular control type. The styles set a variety of different properties on the targeted controls, when that style resource is referenced by resource key and is used to set the property of several specific control elements defined in XAML. Note that one of the properties within the setters of the `Label` style also references the `MyBrush` resource defined earlier. This is a common technique, but it is important to remember that resources are parsed and entered into a resource dictionary in the order that they are given. Resources are also requested by the order found within the dictionary if you use the [StaticResource Markup Extension](staticresource-markup-extension.md) to reference them from within another resource. Make sure that any resource that you reference is defined earlier within the resources collection than where that resource is then requested. If necessary, you can work around the strict creation order of resource references by using a [DynamicResource Markup Extension](dynamicresource-markup-extension.md) to reference the resource at runtime instead, but you should be aware that this DynamicResource technique has performance consequences. For details, see [XAML Resources](/dotnet/desktop-wpf/fundamentals/xaml-resources-define). diff --git a/dotnet-desktop-guide/framework/wpf/advanced/how-to-detect-when-the-enter-key-pressed.md b/dotnet-desktop-guide/framework/wpf/advanced/how-to-detect-when-the-enter-key-pressed.md index dc0944e..7001b49 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/how-to-detect-when-the-enter-key-pressed.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/how-to-detect-when-the-enter-key-pressed.md @@ -13,10 +13,10 @@ ms.assetid: a66f39d2-ef4a-43a5-b454-a4ea0fe88655 # How to: Detect When the Enter Key Pressed This example shows how to detect when the key is pressed on the keyboard. - This example consists of a [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] file and a code-behind file. + This example consists of a Extensible Application Markup Language (XAML) file and a code-behind file. ## Example - When the user presses the key in the , the input in the text box appears in another area of the [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)]. + When the user presses the key in the , the input in the text box appears in another area of the user interface (UI). The following XAML creates the user interface, which consists of a , a , and a . diff --git a/dotnet-desktop-guide/framework/wpf/advanced/how-to-enable-a-command.md b/dotnet-desktop-guide/framework/wpf/advanced/how-to-enable-a-command.md index 471a602..b4bdeef 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/how-to-enable-a-command.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/how-to-enable-a-command.md @@ -10,10 +10,10 @@ helpviewer_keywords: ms.assetid: d8016266-58d9-48f7-8298-a86b7ed49fbd --- # How to: Enable a Command -The following example demonstrates how to use commanding in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)]. The example shows how to associate a to a , create a , and create the event handlers which implement the . For more information on commanding, see the [Commanding Overview](commanding-overview.md). +The following example demonstrates how to use commanding in Windows Presentation Foundation (WPF). The example shows how to associate a to a , create a , and create the event handlers which implement the . For more information on commanding, see the [Commanding Overview](commanding-overview.md). ## Example - The first section of code creates the [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)], which consists of a and a , and creates a that associates the command handlers with the . + The first section of code creates the user interface (UI), which consists of a and a , and creates a that associates the command handlers with the . The property of the is associated with the command. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/how-to-enable-visual-styles-in-a-hybrid-application.md b/dotnet-desktop-guide/framework/wpf/advanced/how-to-enable-visual-styles-in-a-hybrid-application.md index 65f5574..eba90d2 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/how-to-enable-visual-styles-in-a-hybrid-application.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/how-to-enable-visual-styles-in-a-hybrid-application.md @@ -11,7 +11,7 @@ ms.assetid: 95de9b9c-d804-405c-b2d1-49a88c1e0fe1 --- # How to: Enable Visual Styles in a Hybrid Application -This topic shows how to enable visual styles on a Windows Forms control hosted in a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]-based application. +This topic shows how to enable visual styles on a Windows Forms control hosted in a WPF-based application. If your application calls the method, most of your Windows Forms controls will automatically use visual styles. For more information, see [Rendering Controls with Visual Styles](/dotnet/framework/winforms/controls/rendering-controls-with-visual-styles). @@ -21,7 +21,7 @@ This topic shows how to enable visual styles on a Windows Forms control hosted i #### To enable Windows Forms visual styles -1. Create a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] Application project named `HostingWfWithVisualStyles`. +1. Create a WPF Application project named `HostingWfWithVisualStyles`. 2. In Solution Explorer, add references to the following assemblies. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/how-to-enumerate-system-fonts.md b/dotnet-desktop-guide/framework/wpf/advanced/how-to-enumerate-system-fonts.md index 3e439f9..23c037e 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/how-to-enumerate-system-fonts.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/how-to-enumerate-system-fonts.md @@ -18,4 +18,4 @@ ms.assetid: 36e37791-55b9-4f01-a496-5cc10335e6a6 [!code-csharp[TextOverview#100](~/samples/snippets/csharp/VS_Snippets_Wpf/TextOverview/CSharp/Window1.xaml.cs#100)] [!code-vb[TextOverview#100](~/samples/snippets/visualbasic/VS_Snippets_Wpf/TextOverview/visualbasic/window1.xaml.vb#100)] - If multiple versions of the same font family reside in the same directory, the [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] font enumeration returns the most recent version of the font. If the version information does not provide resolution, the font with latest timestamp is returned. If the timestamp information is equivalent, the font file that is first in alphabetical order is returned. + If multiple versions of the same font family reside in the same directory, the Windows Presentation Foundation (WPF) font enumeration returns the most recent version of the font. If the version information does not provide resolution, the font with latest timestamp is returned. If the timestamp information is equivalent, the font file that is first in alphabetical order is returned. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/how-to-find-an-element-by-its-name.md b/dotnet-desktop-guide/framework/wpf/advanced/how-to-find-an-element-by-its-name.md index 1e9891d..487a593 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/how-to-find-an-element-by-its-name.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/how-to-find-an-element-by-its-name.md @@ -12,7 +12,7 @@ ms.assetid: cfa7cf35-8aa2-4060-9454-872ed4af3f0e This example describes how to use the method to find an element by its value. ## Example - In this example, the method to find a particular element by its name is written as the event handler of a button. `stackPanel` is the of the root being searched, and the example method then visually indicates the found element by casting it as and changing one of the visible [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] properties. + In this example, the method to find a particular element by its name is written as the event handler of a button. `stackPanel` is the of the root being searched, and the example method then visually indicates the found element by casting it as and changing one of the visible UI properties. [!code-csharp[FEFindName#Find](~/samples/snippets/csharp/VS_Snippets_Wpf/FEFindName/CSharp/default.xaml.cs#find)] [!code-vb[FEFindName#Find](~/samples/snippets/visualbasic/VS_Snippets_Wpf/FEFindName/VisualBasic/default.xaml.vb#find)] diff --git a/dotnet-desktop-guide/framework/wpf/advanced/how-to-handle-a-loaded-event.md b/dotnet-desktop-guide/framework/wpf/advanced/how-to-handle-a-loaded-event.md index c31f880..1e025e0 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/how-to-handle-a-loaded-event.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/how-to-handle-a-loaded-event.md @@ -14,7 +14,7 @@ ms.assetid: 0cf8d003-8441-4df4-807a-6db09347e829 This example shows how to handle the event, and an appropriate scenario for handling that event. The handler creates a when the page loads. ## Example - The following example uses [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] together with a code-behind file. + The following example uses Extensible Application Markup Language (XAML) together with a code-behind file. [!code-xaml[FELoaded#XAML](~/samples/snippets/csharp/VS_Snippets_Wpf/FELoaded/CSharp/default.xaml#xaml)] diff --git a/dotnet-desktop-guide/framework/wpf/advanced/how-to-handle-a-routed-event.md b/dotnet-desktop-guide/framework/wpf/advanced/how-to-handle-a-routed-event.md index c5406a0..c2602d9 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/how-to-handle-a-routed-event.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/how-to-handle-a-routed-event.md @@ -13,11 +13,11 @@ ms.assetid: 157787b4-f469-4047-8777-5b034145f32e This example shows how bubbling events work and how to write a handler that can process the routed event data. ## Example - In [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)], elements are arranged in an element tree structure. The parent element can participate in the handling of events that are initially raised by child elements in the element tree. This is possible because of event routing. + In Windows Presentation Foundation (WPF), elements are arranged in an element tree structure. The parent element can participate in the handling of events that are initially raised by child elements in the element tree. This is possible because of event routing. Routed events typically follow one of two routing strategies, bubbling or tunneling. This example focuses on the bubbling event and uses the event to show how routing works. - The following example creates two controls and uses [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] attribute syntax to attach an event handler to a common parent element, which in this example is . Instead of attaching individual event handlers for each child element, the example uses attribute syntax to attach the event handler to the parent element. This event-handling pattern shows how to use event routing as a technique for reducing the number of elements where a handler is attached. All the bubbling events for each route through the parent element. + The following example creates two controls and uses XAML attribute syntax to attach an event handler to a common parent element, which in this example is . Instead of attaching individual event handlers for each child element, the example uses attribute syntax to attach the event handler to the parent element. This event-handling pattern shows how to use event routing as a technique for reducing the number of elements where a handler is attached. All the bubbling events for each route through the parent element. Note that on the parent element, the event name specified as the attribute is partially qualified by naming the class. The class is a derived class that has the event in its members listing. This partial qualification technique for attaching an event handler is necessary if the event that is being handled does not exist in the members listing of the element where the routed event handler is attached. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/how-to-hook-up-a-command-to-a-control-with-command-support.md b/dotnet-desktop-guide/framework/wpf/advanced/how-to-hook-up-a-command-to-a-control-with-command-support.md index 1595007..769bf69 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/how-to-hook-up-a-command-to-a-control-with-command-support.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/how-to-hook-up-a-command-to-a-control-with-command-support.md @@ -15,11 +15,11 @@ ms.assetid: 8d8592ae-0c91-469e-a1cd-d179c4544548 The following example shows how to hook up a to a which has built in support for the command. For a complete sample which hooks up commands to multiple sources, see the [Create a Custom RoutedCommand Sample](https://github.com/Microsoft/WPF-Samples/tree/master/Input%20and%20Commands/CustomRoutedCommand) sample. ## Example - [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides a library of common commands which application programmers encounter regularly. The classes which comprise the command library are: , , , , and . + Windows Presentation Foundation (WPF) provides a library of common commands which application programmers encounter regularly. The classes which comprise the command library are: , , , , and . The static objects which make up these classes do not supply command logic. The logic for the command is associated with the command with a . Some controls have built in CommandBindings for some commands. This mechanism allows the semantics of a command to stay the same, while the actual implementation is can change. A , for example, handles the command differently than a control designed to support images, but the basic idea of what it means to paste something stays the same. The command logic cannot be supplied by the command, but rather must be supplied by the control or the application. - Many controls in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] do have built in support for some of the commands in the command library. , for example, supports many of the application edit commands such as , , , , and . The application developer does not have to do anything special to get these commands to work with these controls. If the is the command target when the command is executed, it will handle the command using the that is built into the control. + Many controls in WPF do have built in support for some of the commands in the command library. , for example, supports many of the application edit commands such as , , , , and . The application developer does not have to do anything special to get these commands to work with these controls. If the is the command target when the command is executed, it will handle the command using the that is built into the control. The following shows how to use a as the command source for the command, where a is the target of the command. All the logic that defines how the performs the paste is built into the control. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/how-to-hook-up-a-command-to-a-control-with-no-command-support.md b/dotnet-desktop-guide/framework/wpf/advanced/how-to-hook-up-a-command-to-a-control-with-no-command-support.md index 087efb0..63c7458 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/how-to-hook-up-a-command-to-a-control-with-no-command-support.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/how-to-hook-up-a-command-to-a-control-with-no-command-support.md @@ -15,9 +15,9 @@ ms.assetid: dad08f64-700b-46fb-ad3f-fbfee95f0dfe The following example shows how to hook up a to a which does not have built in support for the command. For a complete sample which hooks up commands to multiple sources, see the [Create a Custom RoutedCommand Sample](https://github.com/Microsoft/WPF-Samples/tree/master/Input%20and%20Commands/CustomRoutedCommand) sample. ## Example - [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides a library of common commands which application programmers encounter regularly. The classes which comprise the command library are: , , , , and . + Windows Presentation Foundation (WPF) provides a library of common commands which application programmers encounter regularly. The classes which comprise the command library are: , , , , and . - The static objects which make up these classes do not supply command logic. The logic for the command is associated with the command with a . Many controls in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] have built in support for some of the commands in the command library. , for example, supports many of the application edit commands such as , , , , and . The application developer does not have to do anything special to get these commands to work with these controls. If the is the command target when the command is executed, it will handle the command using the that is built into the control. + The static objects which make up these classes do not supply command logic. The logic for the command is associated with the command with a . Many controls in WPF have built in support for some of the commands in the command library. , for example, supports many of the application edit commands such as , , , , and . The application developer does not have to do anything special to get these commands to work with these controls. If the is the command target when the command is executed, it will handle the command using the that is built into the control. The following shows how to use a as the command source for the command. A is created that associates the specified and the with the . diff --git a/dotnet-desktop-guide/framework/wpf/advanced/how-to-implement-a-dependency-property.md b/dotnet-desktop-guide/framework/wpf/advanced/how-to-implement-a-dependency-property.md index f42214c..4c7b336 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/how-to-implement-a-dependency-property.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/how-to-implement-a-dependency-property.md @@ -11,7 +11,7 @@ helpviewer_keywords: ms.assetid: 855fd6d7-19ac-493c-bf5e-2f40b57cdc92 --- # How to: Implement a Dependency Property -This example shows how to back a common language runtime (CLR) property with a field, thus defining a dependency property. When you define your own properties and want them to support many aspects of [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] functionality, including styles, data binding, inheritance, animation, and default values, you should implement them as a dependency property. +This example shows how to back a common language runtime (CLR) property with a field, thus defining a dependency property. When you define your own properties and want them to support many aspects of Windows Presentation Foundation (WPF) functionality, including styles, data binding, inheritance, animation, and default values, you should implement them as a dependency property. ## Example The following example first registers a dependency property by calling the method. The name of the identifier field that you use to store the name and characteristics of the dependency property must be the you chose for the dependency property as part of the call, appended by the literal string `Property`. For instance, if you register a dependency property with a of `Location`, then the identifier field that you define for the dependency property must be named `LocationProperty`. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/how-to-invoke-a-print-dialog.md b/dotnet-desktop-guide/framework/wpf/advanced/how-to-invoke-a-print-dialog.md index e4a2e40..a8b3dbb 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/how-to-invoke-a-print-dialog.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/how-to-invoke-a-print-dialog.md @@ -13,7 +13,7 @@ ms.assetid: e3a2c84c-74fe-45a4-8501-5813f9dbfed2 To provide the ability to print from you application, you can simply create and open a object. ## Example - The control provides a single entry point for [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)], configuration, and XPS job submission. The control is easy to use and can be instantiated by using [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] markup or code. The following example demonstrates how to instantiate and open the control in code and how to print from it. It also shows how to ensure that the dialog will give the user the option of setting a specific range of pages. The example code assumes that there is a file FixedDocumentSequence.xps in the root of the C: drive. + The control provides a single entry point for UI, configuration, and XPS job submission. The control is easy to use and can be instantiated by using Extensible Application Markup Language (XAML) markup or code. The following example demonstrates how to instantiate and open the control in code and how to print from it. It also shows how to ensure that the dialog will give the user the option of setting a specific range of pages. The example code assumes that there is a file FixedDocumentSequence.xps in the root of the C: drive. [!code-csharp[printdialog#1](~/samples/snippets/csharp/VS_Snippets_Wpf/PrintDialog/CSharp/Window1.xaml.cs#1)] [!code-vb[printdialog#1](~/samples/snippets/visualbasic/VS_Snippets_Wpf/PrintDialog/visualbasic/window1.xaml.vb#1)] diff --git a/dotnet-desktop-guide/framework/wpf/advanced/how-to-make-an-object-follow-the-mouse-pointer.md b/dotnet-desktop-guide/framework/wpf/advanced/how-to-make-an-object-follow-the-mouse-pointer.md index 0e2167a..9d95f84 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/how-to-make-an-object-follow-the-mouse-pointer.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/how-to-make-an-object-follow-the-mouse-pointer.md @@ -13,10 +13,10 @@ ms.assetid: 50b20415-14bc-405c-baf3-2fb254fffde3 # How to: Make an Object Follow the Mouse Pointer This example shows how to change the dimensions of an object when the mouse pointer moves on the screen. - The example includes an [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] file that creates the [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] and a code-behind file that creates the event handler. + The example includes an user interface (UI) and a code-behind file that creates the event handler. ## Example - The following XAML creates the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)], which consists of an inside of a , and attaches the event handler for the event. + The following XAML creates the UI, which consists of an inside of a , and attaches the event handler for the event. [!code-xaml[mouseMoveWithPointer#MouseMoveWithPointerXAML](~/samples/snippets/csharp/VS_Snippets_Wpf/mouseMoveWithPointer/CSharp/Window1.xaml#mousemovewithpointerxaml)] diff --git a/dotnet-desktop-guide/framework/wpf/advanced/how-to-open-a-file-that-is-dropped-on-a-richtextbox-control.md b/dotnet-desktop-guide/framework/wpf/advanced/how-to-open-a-file-that-is-dropped-on-a-richtextbox-control.md index 011654c..bcab704 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/how-to-open-a-file-that-is-dropped-on-a-richtextbox-control.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/how-to-open-a-file-that-is-dropped-on-a-richtextbox-control.md @@ -12,7 +12,7 @@ ms.assetid: 6bb8bb54-f576-41db-a9a7-24102ddeb490 --- # How to: Open a File That is Dropped on a RichTextBox Control -In [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)], the , , and controls all have built-in drag-and-drop functionality. The built-in functionality enables drag-and-drop of text within and between the controls. However, it does not enable opening a file by dropping the file on the control. These controls also mark the drag-and-drop events as handled. As a result, by default, you cannot add your own event handlers to provide functionality to open dropped files. +In Windows Presentation Foundation (WPF), the , , and controls all have built-in drag-and-drop functionality. The built-in functionality enables drag-and-drop of text within and between the controls. However, it does not enable opening a file by dropping the file on the control. These controls also mark the drag-and-drop events as handled. As a result, by default, you cannot add your own event handlers to provide functionality to open dropped files. To add additional handling for drag-and-drop events in these controls, use the method to add your event handlers for the drag-and-drop events. Set the `handledEventsToo` parameter to `true` to have the specified handler be invoked for a routed event that has already been marked as handled by another element along the event route. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/how-to-override-metadata-for-a-dependency-property.md b/dotnet-desktop-guide/framework/wpf/advanced/how-to-override-metadata-for-a-dependency-property.md index 81b2505..10bf175 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/how-to-override-metadata-for-a-dependency-property.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/how-to-override-metadata-for-a-dependency-property.md @@ -14,7 +14,7 @@ ms.assetid: f90f026e-60d8-428a-933d-edf0dba4441f This example shows how to override default dependency property metadata that comes from an inherited class, by calling the method and providing type-specific metadata. ## Example - By defining its , a class can define the dependency property's behaviors, such as its default value and property system callbacks. Many dependency property classes already have default metadata established as part of their registration process. This includes the dependency properties that are part of the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] API. A class that inherits the dependency property through its class inheritance can override the original metadata so that the characteristics of the property that can be altered through metadata will match any subclass-specific requirements. + By defining its , a class can define the dependency property's behaviors, such as its default value and property system callbacks. Many dependency property classes already have default metadata established as part of their registration process. This includes the dependency properties that are part of the WPF API. A class that inherits the dependency property through its class inheritance can override the original metadata so that the characteristics of the property that can be altered through metadata will match any subclass-specific requirements. Overriding metadata on a dependency property must be done prior to that property being placed in use by the property system (this equates to the time that specific instances of objects that register the property are instantiated). Calls to must be performed within the static constructors of the type that provides itself as the `forType` parameter of . If you attempt to change metadata once instances of the owner type exist, this will not raise exceptions, but will result in inconsistent behaviors in the property system. Also, metadata can only be overridden once per type. Subsequent attempts to override metadata on the same type will raise an exception. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/how-to-programmatically-print-xps-files.md b/dotnet-desktop-guide/framework/wpf/advanced/how-to-programmatically-print-xps-files.md index e302274..cd15a03 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/how-to-programmatically-print-xps-files.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/how-to-programmatically-print-xps-files.md @@ -11,7 +11,7 @@ ms.assetid: 0b1c0a3f-b19e-43d6-bcc9-eb3ec4e555ad --- # How to: Programmatically Print XPS Files -You can use one overload of the method to print XML Paper Specification (XPS) files without opening a or, in principle, any [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] at all. +You can use one overload of the method to print XML Paper Specification (XPS) files without opening a or, in principle, any user interface (UI) at all. You can also print XPS files using the many and methods. For more information, see [Printing an XPS Document](/previous-versions/dotnet/netframework-3.5/ms771525(v=vs.90)). @@ -29,7 +29,7 @@ The main steps to using the three-parameter flag indicating whether or not the printer is an XPSDrv printer. -The example below shows how to batch print all XPS files in a directory. Although the application prompts the user to specify the directory, the three-parameter method does not require a [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)]. It can be used in any code path where you have an XPS file name and path that you can pass to it. +The example below shows how to batch print all XPS files in a directory. Although the application prompts the user to specify the directory, the three-parameter method does not require a user interface (UI). It can be used in any code path where you have an XPS file name and path that you can pass to it. The three-parameter overload of must run in a single thread apartment whenever the parameter is `false`, which it must be when a non-XPSDrv printer is being used. However, the default apartment state for .NET is multiple thread. This default must be reversed since the example assumes a non-XPSDrv printer. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/how-to-register-an-attached-property.md b/dotnet-desktop-guide/framework/wpf/advanced/how-to-register-an-attached-property.md index 3f0df2c..80402b1 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/how-to-register-an-attached-property.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/how-to-register-an-attached-property.md @@ -10,12 +10,12 @@ helpviewer_keywords: ms.assetid: eb47bd94-0451-4f8d-8fb6-95f7812ac05b --- # How to: Register an Attached Property -This example shows how to register an attached property and provide public accessors so that you can use the property in both [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] and code. Attached properties are a syntax concept defined by [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)]. Most attached properties for [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] types are also implemented as dependency properties. You can use dependency properties on any types. +This example shows how to register an attached property and provide public accessors so that you can use the property in both WPF types are also implemented as dependency properties. You can use dependency properties on any types. ## Example The following example shows how to register an attached property as a dependency property, by using the method. The provider class has the option of providing default metadata for the property that is applicable when the property is used on another class, unless that class overrides the metadata. In this example, the default value of the `IsBubbleSource` property is set to `false`. - The provider class for an attached property (even if it is not registered as a dependency property) must provide static get and set accessors that follow the naming convention `Set`*[AttachedPropertyName]* and `Get`*[AttachedPropertyName]*. These accessors are required so that the acting [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] reader can recognize the property as an attribute in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] and resolve the appropriate types. + The provider class for an attached property (even if it is not registered as a dependency property) must provide static get and set accessors that follow the naming convention `Set`*[AttachedPropertyName]* and `Get`*[AttachedPropertyName]*. These accessors are required so that the acting XAML reader can recognize the property as an attribute in XAML and resolve the appropriate types. [!code-csharp[WPFAquariumSln#RegisterAttachedBubbler](~/samples/snippets/csharp/VS_Snippets_Wpf/WPFAquariumSln/CSharp/WPFAquariumObjects/Class1.cs#registerattachedbubbler)] [!code-vb[WPFAquariumSln#RegisterAttachedBubbler](~/samples/snippets/visualbasic/VS_Snippets_Wpf/WPFAquariumSln/visualbasic/wpfaquariumobjects/class1.vb#registerattachedbubbler)] diff --git a/dotnet-desktop-guide/framework/wpf/advanced/how-to-rotate-ink.md b/dotnet-desktop-guide/framework/wpf/advanced/how-to-rotate-ink.md index 54b209f..02b59fc 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/how-to-rotate-ink.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/how-to-rotate-ink.md @@ -25,7 +25,7 @@ ms.assetid: fac36cc9-dd01-41ca-9bde-9d33e3790bbe [!code-csharp[AdornerForStrokes#1](~/samples/snippets/csharp/VS_Snippets_Wpf/AdornerForStrokes/CSharp/RotatingAdornerForStrokes.cs#1)] [!code-vb[AdornerForStrokes#1](~/samples/snippets/visualbasic/VS_Snippets_Wpf/AdornerForStrokes/VisualBasic/RotatingAdornerForStrokes.vb#1)] - The following example is a [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] file that defines an and populates it with ink. The `Window_Loaded` event handler adds the custom adorner to the . + The following example is a Extensible Application Markup Language (XAML) file that defines an and populates it with ink. The `Window_Loaded` event handler adds the custom adorner to the . [!code-xaml[AdornerForStrokes#2](~/samples/snippets/csharp/VS_Snippets_Wpf/AdornerForStrokes/CSharp/Window1.xaml#2)] diff --git a/dotnet-desktop-guide/framework/wpf/advanced/how-to-set-margins-of-elements-and-controls.md b/dotnet-desktop-guide/framework/wpf/advanced/how-to-set-margins-of-elements-and-controls.md index ad7de8b..0ef3172 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/how-to-set-margins-of-elements-and-controls.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/how-to-set-margins-of-elements-and-controls.md @@ -13,7 +13,7 @@ ms.assetid: 70ebee01-6f87-4352-8dd4-402c65eaaed6 # How to: Set Margins of Elements and Controls This example describes how to set the property, by changing any existing property value for the margin in code-behind. The property is a property of the base element, and is thus inherited by a variety of controls and other elements. - This example is written in [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)], with a code-behind file that the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] refers to. The code-behind is shown in both a C# and a Microsoft Visual Basic version. + This example is written in XAML refers to. The code-behind is shown in both a C# and a Microsoft Visual Basic version. ## Example [!code-xaml[FEMarginProgrammatic#XAML](~/samples/snippets/csharp/VS_Snippets_Wpf/FEMarginProgrammatic/CSharp/default.xaml#xaml)] diff --git a/dotnet-desktop-guide/framework/wpf/advanced/how-to-use-a-grid-for-automatic-layout.md b/dotnet-desktop-guide/framework/wpf/advanced/how-to-use-a-grid-for-automatic-layout.md index 7607fd5..6df0b5a 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/how-to-use-a-grid-for-automatic-layout.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/how-to-use-a-grid-for-automatic-layout.md @@ -9,9 +9,9 @@ ms.assetid: ab9de407-e0c1-4047-bdf0-24951bf73879 # How to: Use a Grid for Automatic Layout This example describes how to use a grid in the automatic layout approach to creating a localizable application. - Localization of a [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] can be a time consuming process. Often localizers need to re-size and reposition elements in addition to translating text. In the past each language that a [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] was adapted for required adjustment. Now with the capabilities of [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] you can design elements that reduce the need for adjustment. The approach to writing applications that can be more easily re-sized and repositioned is called `auto layout`. + Localization of a UI was adapted for required adjustment. Now with the capabilities of Windows Presentation Foundation (WPF) you can design elements that reduce the need for adjustment. The approach to writing applications that can be more easily re-sized and repositioned is called `auto layout`. - The following [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] example demonstrates using a grid to position some buttons and text. Notice that the height and width of the cells are set to `Auto`; therefore the cell that contains the button with an image adjusts to fit the image. Because the element can adjust to its content it can be useful when taking the automatic layout approach to designing applications that can be localized. + The following Extensible Application Markup Language (XAML) example demonstrates using a grid to position some buttons and text. Notice that the height and width of the cells are set to `Auto`; therefore the cell that contains the button with an image adjusts to fit the image. Because the element can adjust to its content it can be useful when taking the automatic layout approach to designing applications that can be localized. ## Example The following example shows how to use a grid. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/how-to-use-a-resourcedictionary-to-manage-localizable-string-resources.md b/dotnet-desktop-guide/framework/wpf/advanced/how-to-use-a-resourcedictionary-to-manage-localizable-string-resources.md index 8ede0d1..e2939c2 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/how-to-use-a-resourcedictionary-to-manage-localizable-string-resources.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/how-to-use-a-resourcedictionary-to-manage-localizable-string-resources.md @@ -26,7 +26,7 @@ This example shows how to use a to pack [!code-xaml[StringLocalizationSample#ReferencingStringResourceDictionary](~/samples/snippets/csharp/VS_Snippets_Wpf/StringLocalizationSample/CSharp/App.xaml#referencingstringresourcedictionary)] -3. Use the string resource from markup, using [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] like the following. +3. Use the string resource from markup, using Extensible Application Markup Language (XAML) like the following. [!code-xaml[StringLocalizationSample#GetLocalizedResourceFromMarkup](~/samples/snippets/csharp/VS_Snippets_Wpf/StringLocalizationSample/CSharp/MainWindow.xaml#getlocalizedresourcefrommarkup)] diff --git a/dotnet-desktop-guide/framework/wpf/advanced/how-to-use-a-thicknessconverter-object.md b/dotnet-desktop-guide/framework/wpf/advanced/how-to-use-a-thicknessconverter-object.md index 14c033b..e771e7b 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/how-to-use-a-thicknessconverter-object.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/how-to-use-a-thicknessconverter-object.md @@ -15,7 +15,7 @@ ms.assetid: 52682194-d7fd-499c-8005-73fcc84e7b2c This example shows how to create an instance of and use it to change the thickness of a border. - The example defines a custom method called `changeThickness`; this method first converts the contents of a , as defined in a separate [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] file, to an instance of , and later converts the content into a . This method passes the to a object, which converts the of a to an instance of . This value is then passed back as the value of the property of the . + The example defines a custom method called `changeThickness`; this method first converts the contents of a , as defined in a separate Extensible Application Markup Language (XAML) file, to an instance of , and later converts the content into a . This method passes the to a object, which converts the of a to an instance of . This value is then passed back as the value of the property of the . This example does not run. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/how-to-use-application-resources.md b/dotnet-desktop-guide/framework/wpf/advanced/how-to-use-application-resources.md index 2d63c9f..c1a8d0a 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/how-to-use-application-resources.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/how-to-use-application-resources.md @@ -15,7 +15,7 @@ This example shows how to use application resources. [!code-xaml[ResourcesApplication#PreTemplateResource](~/samples/snippets/csharp/VS_Snippets_Wpf/ResourcesApplication/CS/app.xaml#pretemplateresource)] [!code-xaml[ResourcesApplication#PostTemplateResource](~/samples/snippets/csharp/VS_Snippets_Wpf/ResourcesApplication/CS/app.xaml#posttemplateresource)] - The following example shows a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] page that references the application-level resource that the previous example defined. The resource is referenced by using a [StaticResource Markup Extension](staticresource-markup-extension.md) that specifies the unique resource key for the requested resource. No resource with key of "GelButton" is found in the current page, so the resource lookup scope for the requested resource continues beyond the current page and into the defined application-level resources. + The following example shows a XAML page that references the application-level resource that the previous example defined. The resource is referenced by using a [StaticResource Markup Extension](staticresource-markup-extension.md) that specifies the unique resource key for the requested resource. No resource with key of "GelButton" is found in the current page, so the resource lookup scope for the requested resource continues beyond the current page and into the defined application-level resources. [!code-xaml[ResourcesApplication#ConsumingPage](~/samples/snippets/csharp/VS_Snippets_Wpf/ResourcesApplication/CS/page1.xaml#consumingpage)] diff --git a/dotnet-desktop-guide/framework/wpf/advanced/how-to-use-automatic-layout-to-create-a-button.md b/dotnet-desktop-guide/framework/wpf/advanced/how-to-use-automatic-layout-to-create-a-button.md index 8021835..066828b 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/how-to-use-automatic-layout-to-create-a-button.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/how-to-use-automatic-layout-to-create-a-button.md @@ -9,11 +9,11 @@ ms.assetid: 96c206d0-9e77-4784-9d2d-5045aed2021c # How to: Use Automatic Layout to Create a Button This example describes how to use the automatic layout approach to create a button in a localizable application. - Localization of a [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] can be a time consuming process. Often localizers need to resize and reposition elements in addition to translating text. In the past each language that a [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] was adapted for required adjustment. Now with the capabilities of [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] you can design elements that reduce the need for adjustment. The approach to writing applications that can be more easily resized and repositioned is called `automatic layout`. + Localization of a UI was adapted for required adjustment. Now with the capabilities of Windows Presentation Foundation (WPF) you can design elements that reduce the need for adjustment. The approach to writing applications that can be more easily resized and repositioned is called `automatic layout`. ## Example -The following two [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] examples create applications that instantiate a button; one with English text and one with Spanish text. Notice that the code is the same except for the text; the button adjusts to fit the text. +The following two Extensible Application Markup Language (XAML) examples create applications that instantiate a button; one with English text and one with Spanish text. Notice that the code is the same except for the text; the button adjusts to fit the text. [!code-xaml[LocalizationBtn_snip#1](~/samples/snippets/csharp/VS_Snippets_Wpf/LocalizationBtn_snip/CS/Pane1.xaml#1)] diff --git a/dotnet-desktop-guide/framework/wpf/advanced/how-to-use-system-fonts-keys.md b/dotnet-desktop-guide/framework/wpf/advanced/how-to-use-system-fonts-keys.md index 8c42e02..0af9b78 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/how-to-use-system-fonts-keys.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/how-to-use-system-fonts-keys.md @@ -13,7 +13,7 @@ System resources expose a number of system metrics as resources to help develope > [!NOTE] > Dynamic resources have the keyword *Key* appended to the property name. - The following example shows how to access and use system font dynamic resources to style or customize a button. This [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] example creates a button style that assigns values to a button. + The following example shows how to access and use system font dynamic resources to style or customize a button. This XAML example creates a button style that assigns values to a button. ## Example [!code-xaml[SystemRes_snip#FontDynamicResources](~/samples/snippets/csharp/VS_Snippets_Wpf/SystemRes_snip/CSharp/MyApp.xaml#fontdynamicresources)] diff --git a/dotnet-desktop-guide/framework/wpf/advanced/how-to-use-system-parameters-keys.md b/dotnet-desktop-guide/framework/wpf/advanced/how-to-use-system-parameters-keys.md index f685e16..0b89133 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/how-to-use-system-parameters-keys.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/how-to-use-system-parameters-keys.md @@ -12,7 +12,7 @@ System resources expose a number of system metrics as resources to help develope > [!NOTE] > Dynamic resources have the keyword *Key* appended to the property name. - The following example shows how to access and use system parameter dynamic resources to style or customize a button. This [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] example sizes a button by assigning values to the button's width and height. + The following example shows how to access and use system parameter dynamic resources to style or customize a button. This XAML example sizes a button by assigning values to the button's width and height. ## Example [!code-xaml[SystemRes_snip#ParameterDynamicResources](~/samples/snippets/csharp/VS_Snippets_Wpf/SystemRes_snip/CSharp/MyApp.xaml#parameterdynamicresources)] diff --git a/dotnet-desktop-guide/framework/wpf/advanced/how-to-use-systemfonts.md b/dotnet-desktop-guide/framework/wpf/advanced/how-to-use-systemfonts.md index 25511b3..fd999e7 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/how-to-use-systemfonts.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/how-to-use-systemfonts.md @@ -16,7 +16,7 @@ This example shows how to use the static resources of the is a class that contains both system font values as static properties, and properties that reference resource keys that can be used to access those values dynamically at run time. For example, is a value, and is a corresponding resource key. - In [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], you can use the members of as either static properties or dynamic resource references (with the static property value as the key). Use a dynamic resource reference if you want the font metric to automatically update while the application runs; otherwise, use a static value reference. + In XAML, you can use the members of as either static properties or dynamic resource references (with the static property value as the key). Use a dynamic resource reference if you want the font metric to automatically update while the application runs; otherwise, use a static value reference. > [!NOTE] > The resource keys have the suffix "Key" appended to the property name. @@ -25,7 +25,7 @@ This example shows how to use the static resources of the in code, you do not have to use either a static value or a dynamic resource reference. Instead, use the non-key properties of the class. Although the non-key properties are apparently defined as static properties, the run-time behavior of [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] as hosted by the system will reevaluate the properties in real time and will properly account for user-driven changes to system values. The following example shows how to specify the font settings of a button. + To use the values of in code, you do not have to use either a static value or a dynamic resource reference. Instead, use the non-key properties of the class. Although the non-key properties are apparently defined as static properties, the run-time behavior of WPF as hosted by the system will reevaluate the properties in real time and will properly account for user-driven changes to system values. The following example shows how to specify the font settings of a button. [!code-csharp[SystemRes_snip#FontResourcesCode](~/samples/snippets/csharp/VS_Snippets_Wpf/SystemRes_snip/CSharp/Pane1.xaml.cs#fontresourcescode)] [!code-vb[SystemRes_snip#FontResourcesCode](~/samples/snippets/visualbasic/VS_Snippets_Wpf/SystemRes_snip/VisualBasic/Pane1.xaml.vb#fontresourcescode)] diff --git a/dotnet-desktop-guide/framework/wpf/advanced/how-to-use-systemparameters.md b/dotnet-desktop-guide/framework/wpf/advanced/how-to-use-systemparameters.md index e6c83b6..171a779 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/how-to-use-systemparameters.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/how-to-use-systemparameters.md @@ -14,13 +14,13 @@ This example shows how to access and use the properties of is a class that contains both system parameter value properties, and resource keys that bind to the values. For example, is a property value and is the corresponding resource key. - In [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], you can use the members of as either a static property usage, or a dynamic resource references (with the static property value as the key). Use a dynamic resource reference if you want the system based value to update automatically while the application runs; otherwise, use a static reference. Resource keys have the suffix `Key` appended to the property name. + In XAML, you can use the members of as either a static property usage, or a dynamic resource references (with the static property value as the key). Use a dynamic resource reference if you want the system based value to update automatically while the application runs; otherwise, use a static reference. Resource keys have the suffix `Key` appended to the property name. The following example shows how to access and use the static values of to style or customize a button. This markup example sizes a button by applying values to a button. [!code-xaml[SystemRes_snip#ParameterStaticResources](~/samples/snippets/csharp/VS_Snippets_Wpf/SystemRes_snip/CSharp/Pane1.xaml#parameterstaticresources)] - To use the values of in code, you do not have to use either static references or dynamic resource references. Instead, use the values of the class. Although the non-key properties are apparently defined as static properties, the runtime behavior of [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] as hosted by the system will reevaluate the properties in realtime, and will properly account for user-driven changes to system values. The following example shows how to set the width and height of a button by using values. + To use the values of in code, you do not have to use either static references or dynamic resource references. Instead, use the values of the class. Although the non-key properties are apparently defined as static properties, the runtime behavior of WPF as hosted by the system will reevaluate the properties in realtime, and will properly account for user-driven changes to system values. The following example shows how to set the width and height of a button by using values. [!code-csharp[SystemRes_snip#ParameterResourcesCode](~/samples/snippets/csharp/VS_Snippets_Wpf/SystemRes_snip/CSharp/Pane1.xaml.cs#parameterresourcescode)] [!code-vb[SystemRes_snip#ParameterResourcesCode](~/samples/snippets/visualbasic/VS_Snippets_Wpf/SystemRes_snip/VisualBasic/Pane1.xaml.vb#parameterresourcescode)] diff --git a/dotnet-desktop-guide/framework/wpf/advanced/how-to-use-the-fontsizeconverter-class.md b/dotnet-desktop-guide/framework/wpf/advanced/how-to-use-the-fontsizeconverter-class.md index abcdaee..6a3c4d7 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/how-to-use-the-fontsizeconverter-class.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/how-to-use-the-fontsizeconverter-class.md @@ -10,7 +10,7 @@ ms.assetid: 3b0592bd-7223-4860-a108-a5d72f3a9178 ## Example This example shows how to create an instance of and use it to change a font size. - The example defines a custom method called `changeSize` that converts the contents of a , as defined in a separate [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] file, to an instance of , and later into a . This method passes the to a object, which converts the of a to an instance of . This value is then passed back as the value of the property of the element. + The example defines a custom method called `changeSize` that converts the contents of a , as defined in a separate Extensible Application Markup Language (XAML) file, to an instance of , and later into a . This method passes the to a object, which converts the of a to an instance of . This value is then passed back as the value of the property of the element. This example also defines a second custom method that is called `changeFamily`. This method converts the of the to a , and then passes that value to the property of the element. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/initialization-for-object-elements-not-in-an-object-tree.md b/dotnet-desktop-guide/framework/wpf/advanced/initialization-for-object-elements-not-in-an-object-tree.md index 79644b3..48525a5 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/initialization-for-object-elements-not-in-an-object-tree.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/initialization-for-object-elements-not-in-an-object-tree.md @@ -12,22 +12,22 @@ helpviewer_keywords: ms.assetid: 7b8dfc9b-46ac-4ce8-b7bb-035734d688b7 --- # Initialization for Object Elements Not in an Object Tree -Some aspects of [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] initialization are deferred to processes that typically rely on that element being connected to either the logical tree or visual tree. This topic describes the steps that may be necessary in order to initialize an element that is not connected to either tree. +Some aspects of Windows Presentation Foundation (WPF) initialization are deferred to processes that typically rely on that element being connected to either the logical tree or visual tree. This topic describes the steps that may be necessary in order to initialize an element that is not connected to either tree. ## Elements and the Logical Tree - When you create an instance of a [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] class in code, you should be aware that several aspects of object initialization for a [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] class are deliberately not a part of the code that is executed when calling the class constructor. Particularly for a control class, most of the visual representation of that control is not defined by the constructor. Instead, the visual representation is defined by the control's template. The template potentially comes from a variety of sources, but most often the template is obtained from theme styles. Templates are effectively late-binding; the necessary template is not attached to the control in question until the control is ready for layout. And the control is not ready for layout until it is attached to a logical tree that connects to a rendering surface at the root. It is that root-level element that initiates the rendering of all of its child elements as defined in the logical tree. + When you create an instance of a Windows Presentation Foundation (WPF) class in code, you should be aware that several aspects of object initialization for a Windows Presentation Foundation (WPF) class are deliberately not a part of the code that is executed when calling the class constructor. Particularly for a control class, most of the visual representation of that control is not defined by the constructor. Instead, the visual representation is defined by the control's template. The template potentially comes from a variety of sources, but most often the template is obtained from theme styles. Templates are effectively late-binding; the necessary template is not attached to the control in question until the control is ready for layout. And the control is not ready for layout until it is attached to a logical tree that connects to a rendering surface at the root. It is that root-level element that initiates the rendering of all of its child elements as defined in the logical tree. The visual tree also participates in this process. Elements that are part of the visual tree through the templates are also not fully instantiated until connected. The consequences of this behavior are that certain operations that rely on the completed visual characteristics of an element require additional steps. An example is if you are attempting to get the visual characteristics of a class that was constructed but not yet attached to a tree. For instance, if you want to call on a and the visual you are passing is an element not connected to a tree, that element is not visually complete until additional initialization steps are completed. ### Using BeginInit and EndInit to Initialize the Element - Various classes in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] implement the interface. You use the and methods of the interface to denote a region in your code that contains initialization steps (such as setting property values that affect rendering). After is called in the sequence, the layout system can process the element and start looking for an implicit style. + Various classes in WPF implement the interface. You use the and methods of the interface to denote a region in your code that contains initialization steps (such as setting property values that affect rendering). After is called in the sequence, the layout system can process the element and start looking for an implicit style. If the element you are setting properties on is a or derived class, then you can call the class versions of and rather than casting to . ### Sample Code - The following example is sample code for a console application that uses rendering APIs and of a loose [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file to illustrate the proper placement of and around other API calls that adjust properties that affect rendering. + The following example is sample code for a console application that uses rendering APIs and of a loose XAML file to illustrate the proper placement of and around other API calls that adjust properties that affect rendering. The example illustrates the main function only. The functions `Rasterize` and `Save` (not shown) are utility functions that take care of image processing and IO. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/inline-styles-and-templates.md b/dotnet-desktop-guide/framework/wpf/advanced/inline-styles-and-templates.md index c11a6c3..c593cf3 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/inline-styles-and-templates.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/inline-styles-and-templates.md @@ -9,10 +9,10 @@ helpviewer_keywords: ms.assetid: 69a1a3f9-acb5-4e2c-9c43-2e376c055ac4 --- # Inline Styles and Templates -[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides objects and template objects ( subclasses) as a way to define the visual appearance of an element in resources, so that they can be used multiple times. For this reason, attributes in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] that take the types and almost always make resource references to existing styles and templates rather than define new ones inline. +XAML that take the types and almost always make resource references to existing styles and templates rather than define new ones inline. ## Limitations of Inline Styles and Templates - In [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)], style and template properties can technically be set in one of two ways. You can use attribute syntax to reference a style that was defined within a resource, for example `<`*object*`Style="{StaticResource`*myResourceKey*`}" .../>`. Or you can use property element syntax to define a style inline, for instance: + In Extensible Application Markup Language (XAML), style and template properties can technically be set in one of two ways. You can use attribute syntax to reference a style that was defined within a resource, for example `<`*object*`Style="{StaticResource`*myResourceKey*`}" .../>`. Or you can use property element syntax to define a style inline, for instance: `<` *object* `>` @@ -24,7 +24,7 @@ ms.assetid: 69a1a3f9-acb5-4e2c-9c43-2e376c055ac4 `` - The attribute usage is much more common. A style that is defined inline and not defined in resources is necessarily scoped to the containing element only, and cannot be re-used as easily because it has no resource key. In general a resource-defined style is more versatile and useful, and is more in keeping with the general [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] programming model principle of separating program logic in code from design in markup. + The attribute usage is much more common. A style that is defined inline and not defined in resources is necessarily scoped to the containing element only, and cannot be re-used as easily because it has no resource key. In general a resource-defined style is more versatile and useful, and is more in keeping with the general Windows Presentation Foundation (WPF) programming model principle of separating program logic in code from design in markup. Usually there is no reason to set a style or template inline, even if you only intend to use that style or template in that location. Most elements that can take a style or template also support a content property and a content model. If you are only using whatever logical tree you create through styling or templating once, it would be even easier to just fill that content property with the equivalent child elements in direct markup. This would bypass the style and template mechanisms altogether. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/input-overview.md b/dotnet-desktop-guide/framework/wpf/advanced/input-overview.md index 37da979..0d6922a 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/input-overview.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/input-overview.md @@ -27,11 +27,11 @@ helpviewer_keywords: ms.assetid: ee5258b7-6567-415a-9b1c-c0cbe46e79ef --- # Input Overview - The [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] subsystem provides a powerful API for obtaining input from a variety of devices, including the mouse, keyboard, touch, and stylus. This topic describes the services provided by [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] and explains the architecture of the input systems. + The WPF and explains the architecture of the input systems. ## Input API - The primary input API exposure is found on the base element classes: , , , and . For more information about the base elements, see [Base Elements Overview](base-elements-overview.md). These classes provide functionality for input events related to key presses, mouse buttons, mouse wheel, mouse movement, focus management, and mouse capture, to name a few. By placing the input API on the base elements, rather than treating all input events as a service, the input architecture enables the input events to be sourced by a particular object in the UI, and to support an event routing scheme whereby more than one element has an opportunity to handle an input event. Many input events have a pair of events associated with them. For example, the key down event is associated with the and events. The difference in these events is in how they are routed to the target element. Preview events tunnel down the element tree from the root element to the target element. Bubbling events bubble up from the target element to the root element. Event routing in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] is discussed in more detail later in this overview and in the [Routed Events Overview](routed-events-overview.md). + The primary input API exposure is found on the base element classes: , , , and . For more information about the base elements, see [Base Elements Overview](base-elements-overview.md). These classes provide functionality for input events related to key presses, mouse buttons, mouse wheel, mouse movement, focus management, and mouse capture, to name a few. By placing the input API on the base elements, rather than treating all input events as a service, the input architecture enables the input events to be sourced by a particular object in the UI, and to support an event routing scheme whereby more than one element has an opportunity to handle an input event. Many input events have a pair of events associated with them. For example, the key down event is associated with the and events. The difference in these events is in how they are routed to the target element. Preview events tunnel down the element tree from the root element to the target element. Bubbling events bubble up from the target element to the root element. Event routing in WPF is discussed in more detail later in this overview and in the [Routed Events Overview](routed-events-overview.md). ### Keyboard and Mouse Classes In addition to the input API on the base element classes, the class and classes provide additional API for working with keyboard and mouse input. @@ -53,21 +53,21 @@ ms.assetid: ee5258b7-6567-415a-9b1c-c0cbe46e79ef The and classes are covered in more detail throughout this overview. ### Stylus Input - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] has integrated support for the . The is a pen input made popular by the Tablet PC. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications can treat the stylus as a mouse by using the mouse API, but [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] also exposes a stylus device abstraction that use a model similar to the keyboard and mouse. All stylus-related APIs contain the word "Stylus". + WPF has integrated support for the . The is a pen input made popular by the Tablet PC. WPF applications can treat the stylus as a mouse by using the mouse API, but WPF also exposes a stylus device abstraction that use a model similar to the keyboard and mouse. All stylus-related APIs contain the word "Stylus". Because the stylus can act as a mouse, applications that support only mouse input can still obtain some level of stylus support automatically. When the stylus is used in such a manner, the application is given the opportunity to handle the appropriate stylus event and then handles the corresponding mouse event. In addition, higher-level services such as ink input are also available through the stylus device abstraction. For more information about ink as input, see [Getting Started with Ink](getting-started-with-ink.md). ## Event Routing - A can contain other elements as child elements in its content model, forming a tree of elements. In [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], the parent element can participate in input directed to its child elements or other descendants by handing events. This is especially useful for building controls out of smaller controls, a process known as "control composition" or "compositing." For more information about element trees and how element trees relate to event routes, see [Trees in WPF](trees-in-wpf.md). + A can contain other elements as child elements in its content model, forming a tree of elements. In WPF, the parent element can participate in input directed to its child elements or other descendants by handing events. This is especially useful for building controls out of smaller controls, a process known as "control composition" or "compositing." For more information about element trees and how element trees relate to event routes, see [Trees in WPF](trees-in-wpf.md). Event routing is the process of forwarding events to multiple elements, so that a particular object or element along the route can choose to offer a significant response (through handling) to an event that might have been sourced by a different element. Routed events use one of three routing mechanisms: direct, bubbling, and tunneling. In direct routing, the source element is the only element notified, and the event is not routed to any other elements. However, the direct routed event still offers some additional capabilities that are only present for routed events as opposed to standard CLR events. Bubbling works up the element tree by first notifying the element that sourced the event, then the parent element, and so on. Tunneling starts at the root of the element tree and works down, ending with the original source element. For more information about routed events, see [Routed Events Overview](routed-events-overview.md). - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] input events generally come in pairs that consists of a tunneling event and a bubbling event. Tunneling events are distinguished from bubbling events with the "Preview" prefix. For instance, is the tunneling version of a mouse move event and is the bubbling version of this event. This event pairing is a convention that is implemented at the element level and is not an inherent capability of the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] event system. For details, see the WPF Input Events section in [Routed Events Overview](routed-events-overview.md). + WPF input events generally come in pairs that consists of a tunneling event and a bubbling event. Tunneling events are distinguished from bubbling events with the "Preview" prefix. For instance, is the tunneling version of a mouse move event and is the bubbling version of this event. This event pairing is a convention that is implemented at the element level and is not an inherent capability of the WPF event system. For details, see the WPF Input Events section in [Routed Events Overview](routed-events-overview.md). ## Handling Input Events - To receive input on an element, an event handler must be associated with that particular event. In [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] this is straightforward: you reference the name of the event as an attribute of the element that will be listening for this event. Then, you set the value of the attribute to the name of the event handler that you define, based on a delegate. The event handler must be written in code such as C# and can be included in a code-behind file. + To receive input on an element, an event handler must be associated with that particular event. In XAML this is straightforward: you reference the name of the event as an attribute of the element that will be listening for this event. Then, you set the value of the attribute to the name of the event handler that you define, based on a delegate. The event handler must be written in code such as C# and can be included in a code-behind file. Keyboard events occur when the operating system reports key actions that occur while keyboard focus is on an element. Mouse and stylus events each fall into two categories: events that report changes in pointer position relative to the element, and events that report changes in the state of device buttons. @@ -108,9 +108,9 @@ ms.assetid: ee5258b7-6567-415a-9b1c-c0cbe46e79ef ## Text Input The event enables you to listen for text input in a device-independent manner. The keyboard is the primary means of text input, but speech, handwriting, and other input devices can generate text input also. - For keyboard input, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] first sends the appropriate / events. If those events are not handled and the key is textual (rather than a control key such as directional arrows or function keys), then a event is raised. There is not always a simple one-to-one mapping between / and events because multiple keystrokes can generate a single character of text input and single keystrokes can generate multi-character strings. This is especially true for languages such as Chinese, Japanese, and Korean which use Input Method Editors (IMEs) to generate the thousands of possible characters in their corresponding alphabets. + For keyboard input, WPF first sends the appropriate / events. If those events are not handled and the key is textual (rather than a control key such as directional arrows or function keys), then a event is raised. There is not always a simple one-to-one mapping between / and events because multiple keystrokes can generate a single character of text input and single keystrokes can generate multi-character strings. This is especially true for languages such as Chinese, Japanese, and Korean which use Input Method Editors (IMEs) to generate the thousands of possible characters in their corresponding alphabets. - When [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] sends a / event, is set to if the keystrokes could become part of a event (if ALT+S is pressed, for example). This allows code in a event handler to check for and, if found, leave processing for the handler of the subsequently raised event. In these cases, the various properties of the argument can be used to determine the original keystrokes. Similarly, if an IME is active, has the value of , and gives the original keystroke or keystrokes. + When WPF sends a / event, is set to if the keystrokes could become part of a event (if ALT+S is pressed, for example). This allows code in a event handler to check for and, if found, leave processing for the handler of the subsequently raised event. In these cases, the various properties of the argument can be used to determine the original keystrokes. Similarly, if an IME is active, has the value of , and gives the original keystroke or keystrokes. The following example defines a handler for the event and a handler for the event. @@ -132,9 +132,9 @@ ms.assetid: ee5258b7-6567-415a-9b1c-c0cbe46e79ef ## Touch and Manipulation - New hardware and API in the Windows 7 operating system provide applications the ability to receive input from multiple touches simultaneously. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] enables applications to detect and respond to touch in a manner similar to responding to other input, such as the mouse or keyboard, by raising events when touch occurs. + New hardware and API in the Windows 7 operating system provide applications the ability to receive input from multiple touches simultaneously. WPF enables applications to detect and respond to touch in a manner similar to responding to other input, such as the mouse or keyboard, by raising events when touch occurs. - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] exposes two types of events when touch occurs: touch events and manipulation events. Touch events provide raw data about each finger on a touchscreen and its movement. Manipulation events interpret the input as certain actions. Both types of events are discussed in this section. + WPF exposes two types of events when touch occurs: touch events and manipulation events. Touch events provide raw data about each finger on a touchscreen and its movement. Manipulation events interpret the input as certain actions. Both types of events are discussed in this section. ### Prerequisites You need the following components to develop an application that responds to touch. @@ -150,9 +150,9 @@ ms.assetid: ee5258b7-6567-415a-9b1c-c0cbe46e79ef - **Touch** is a type of user input that is recognized by Windows 7. Usually, touch is initiated by putting fingers on a touch-sensitive screen. Note that devices such as a touchpad that is common on laptop computers do not support touch if the device merely converts the finger's position and movement as mouse input. -- **Multitouch** is touch that occurs from more than one point simultaneously. Windows 7 and [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] supports multitouch. Whenever touch is discussed in the documentation for [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], the concepts apply to multitouch. +- **Multitouch** is touch that occurs from more than one point simultaneously. Windows 7 and WPF supports multitouch. Whenever touch is discussed in the documentation for WPF, the concepts apply to multitouch. -- A **manipulation** occurs when touch is interpreted as a physical action that is applied to an object. In [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], manipulation events interpret input as a translation, expansion, or rotation manipulation. +- A **manipulation** occurs when touch is interpreted as a physical action that is applied to an object. In WPF, manipulation events interpret input as a translation, expansion, or rotation manipulation. - A `touch device` represents a device that produces touch input, such as a single finger on a touchscreen. @@ -236,7 +236,7 @@ Touch events More than one type of manipulation can occur simultaneously. - When you cause objects to respond to manipulations, you can have the object appear to have inertia. This can make your objects simulate the physical world. For example, when you push a book across a table, if you push hard enough the book will continue to move after you release it. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] enables you to simulate this behavior by raising manipulation events after the user's fingers releases the object. + When you cause objects to respond to manipulations, you can have the object appear to have inertia. This can make your objects simulate the physical world. For example, when you push a book across a table, if you push hard enough the book will continue to move after you release it. WPF enables you to simulate this behavior by raising manipulation events after the user's fingers releases the object. For information about how to create an application that enables the user to move, resize, and rotate an object, see [Walkthrough: Creating Your First Touch Application](walkthrough-creating-your-first-touch-application.md). @@ -274,7 +274,7 @@ Manipulation events 4. The event occurs when the user's fingers lose contact with the object. This event enables you to specify the deceleration of the manipulations during inertia. This is so your object can emulate different physical spaces or attributes if you choose. For example, suppose your application has two objects that represent items in the physical world, and one is heavier than the other. You can make the heavier object decelerate faster than the lighter object. -5. The event occurs multiple times as inertia occurs. Note that this event occurs when the user's fingers move across the touchscreen and when [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] simulates inertia. In other words, occurs before and after the event. The property reports whether the event occurs during inertia, so you can check that property and perform different actions, depending on its value. +5. The event occurs multiple times as inertia occurs. Note that this event occurs when the user's fingers move across the touchscreen and when WPF simulates inertia. In other words, occurs before and after the event. The property reports whether the event occurs during inertia, so you can check that property and perform different actions, depending on its value. 6. The event occurs when the manipulation and any inertia ends. That is, after all the events occur, the event occurs to signal that the manipulation is complete. @@ -308,10 +308,10 @@ Touch and manipulation events ## Focus - There are two main concepts that pertain to focus in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]: keyboard focus and logical focus. + There are two main concepts that pertain to focus in WPF: keyboard focus and logical focus. ### Keyboard Focus - Keyboard focus refers to the element that is receiving keyboard input. There can be only one element on the whole desktop that has keyboard focus. In [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], the element that has keyboard focus will have set to `true`. The static method returns the element that currently has keyboard focus. + Keyboard focus refers to the element that is receiving keyboard input. There can be only one element on the whole desktop that has keyboard focus. In WPF, the element that has keyboard focus will have set to `true`. The static method returns the element that currently has keyboard focus. Keyboard focus can be obtained by tabbing to an element or by clicking the mouse on certain elements, such as a . Keyboard focus can also be obtained programmatically by using the method on the class. attempts to give the specified element keyboard focus. The element returned by is the element that currently has keyboard focus. @@ -329,7 +329,7 @@ Touch and manipulation events A focus scope is a container element that keeps track of the within its scope. When focus leaves a focus scope, the focused element will lose keyboard focus but will retain logical focus. When focus returns to the focus scope, the focused element will obtain keyboard focus. This allows for keyboard focus to be changed between multiple focus scopes but insures that the focused element within the focus scope remains the focused element when focus returns. - An element can be turned into a focus scope in [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] by setting the attached property to `true`, or in code by setting the attached property by using the method. + An element can be turned into a focus scope in Extensible Application Markup Language (XAML) by setting the attached property to `true`, or in code by setting the attached property by using the method. The following example makes a into a focus scope by setting the attached property. @@ -338,7 +338,7 @@ Touch and manipulation events [!code-csharp[FocusSnippets#FocusSetIsFocusScope](~/samples/snippets/csharp/VS_Snippets_Wpf/FocusSnippets/CSharp/Window1.xaml.cs#focussetisfocusscope)] [!code-vb[FocusSnippets#FocusSetIsFocusScope](~/samples/snippets/visualbasic/VS_Snippets_Wpf/FocusSnippets/visualbasic/window1.xaml.vb#focussetisfocusscope)] - Classes in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] which are focus scopes by default are , , , and . + Classes in WPF which are focus scopes by default are , , , and . An element that has keyboard focus will also have logical focus for the focus scope it belongs to; therefore, setting focus on an element with the method on the class or the base element classes will attempt to give the element keyboard focus and logical focus. @@ -348,7 +348,7 @@ Touch and manipulation events ## Mouse Position - The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] input API provides helpful information with regard to coordinate spaces. For example, coordinate `(0,0)` is the upper-left coordinate, but the upper-left of which element in the tree? The element that is the input target? The element you attached your event handler to? Or something else? To avoid confusion, the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] input API requires that you specify your frame of reference when you work with coordinates obtained through the mouse. The method returns the coordinate of the mouse pointer relative to the specified element. + The WPF input API provides helpful information with regard to coordinate spaces. For example, coordinate `(0,0)` is the upper-left coordinate, but the upper-left of which element in the tree? The element that is the input target? The element you attached your event handler to? Or something else? To avoid confusion, the WPF input API requires that you specify your frame of reference when you work with coordinates obtained through the mouse. The method returns the coordinate of the mouse pointer relative to the specified element. ## Mouse Capture @@ -358,11 +358,11 @@ Touch and manipulation events ## Commands Commands enable input handling at a more semantic level than device input. Commands are simple directives, such as `Cut`, `Copy`, `Paste`, or `Open`. Commands are useful for centralizing your command logic. The same command might be accessed from a , on a , or through a keyboard shortcut. Commands also provide a mechanism for disabling controls when the command becomes unavailable. - is the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] implementation of . When a is executed, a and an event are raised on the command target, which tunnel and bubble through the element tree like other input. If a command target is not set, the element with keyboard focus will be the command target. The logic that performs the command is attached to a . When an event reaches a for that specific command, the on the is called. This handler performs the action of the command. + is the WPF implementation of . When a is executed, a and an event are raised on the command target, which tunnel and bubble through the element tree like other input. If a command target is not set, the element with keyboard focus will be the command target. The logic that performs the command is attached to a . When an event reaches a for that specific command, the on the is called. This handler performs the action of the command. For more information on commanding, see [Commanding Overview](commanding-overview.md). - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides a library of common commands which consists of , , , , and , or you can define your own. + WPF provides a library of common commands which consists of , , , , and , or you can define your own. The following example shows how to set up a so that when it is clicked it will invoke the command on the , assuming the has keyboard focus. @@ -371,7 +371,7 @@ Touch and manipulation events [!code-csharp[CommandingOverviewSnippets#CommandingOverviewCommandTargetCodeBehind](~/samples/snippets/csharp/VS_Snippets_Wpf/CommandingOverviewSnippets/CSharp/Window1.xaml.cs#commandingoverviewcommandtargetcodebehind)] [!code-vb[CommandingOverviewSnippets#CommandingOverviewCommandTargetCodeBehind](~/samples/snippets/visualbasic/VS_Snippets_Wpf/CommandingOverviewSnippets/visualbasic/window1.xaml.vb#commandingoverviewcommandtargetcodebehind)] - For more information about commands in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], see [Commanding Overview](commanding-overview.md). + For more information about commands in WPF, see [Commanding Overview](commanding-overview.md). ## The Input System and Base Elements @@ -379,13 +379,13 @@ Touch and manipulation events Each of the events that , , and define as an attached event is also re-exposed by the base element classes and as a new routed event. The base element routed events are generated by classes handling the original attached event and reusing the event data. - When the input event becomes associated with a particular source element through its base element input event implementation, it can be routed through the remainder of an event route that is based on a combination of logical and visual tree objects, and be handled by application code. Generally, it is more convenient to handle these device-related input events using the routed events on and , because you can use more intuitive event handler syntax both in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] and in code. You could choose to handle the attached event that initiated the process instead, but you would face several issues: the attached event may be marked handled by the base element class handling, and you need to use accessor methods rather than true event syntax in order to attach handlers for attached events. + When the input event becomes associated with a particular source element through its base element input event implementation, it can be routed through the remainder of an event route that is based on a combination of logical and visual tree objects, and be handled by application code. Generally, it is more convenient to handle these device-related input events using the routed events on and , because you can use more intuitive event handler syntax both in XAML and in code. You could choose to handle the attached event that initiated the process instead, but you would face several issues: the attached event may be marked handled by the base element class handling, and you need to use accessor methods rather than true event syntax in order to attach handlers for attached events. ## What's Next - You now have several techniques to handle input in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. You should also have an improved understanding of the various types of input events and the routed event mechanisms used by [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. + You now have several techniques to handle input in WPF. You should also have an improved understanding of the various types of input events and the routed event mechanisms used by WPF. - Additional resources are available that explain [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] framework elements and event routing in more detail. See the following overviews for more information, [Commanding Overview](commanding-overview.md), [Focus Overview](focus-overview.md), [Base Elements Overview](base-elements-overview.md), [Trees in WPF](trees-in-wpf.md), and [Routed Events Overview](routed-events-overview.md). + Additional resources are available that explain WPF framework elements and event routing in more detail. See the following overviews for more information, [Commanding Overview](commanding-overview.md), [Focus Overview](focus-overview.md), [Base Elements Overview](base-elements-overview.md), [Trees in WPF](trees-in-wpf.md), and [Routed Events Overview](routed-events-overview.md). ## See also diff --git a/dotnet-desktop-guide/framework/wpf/advanced/introduction-to-the-glyphrun-object-and-glyphs-element.md b/dotnet-desktop-guide/framework/wpf/advanced/introduction-to-the-glyphrun-object-and-glyphs-element.md index 69be425..7602325 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/introduction-to-the-glyphrun-object-and-glyphs-element.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/introduction-to-the-glyphrun-object-and-glyphs-element.md @@ -15,13 +15,13 @@ This topic describes the object and the ## Introduction to GlyphRun - [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides advanced text support including glyph-level markup with direct access to for customers who want to intercept and persist text after formatting. These features provide critical support for the different text rendering requirements in each of the following scenarios. + Windows Presentation Foundation (WPF) provides advanced text support including glyph-level markup with direct access to for customers who want to intercept and persist text after formatting. These features provide critical support for the different text rendering requirements in each of the following scenarios. 1. Screen display of fixed-format documents. 2. Print scenarios. - - [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] as a device printer language. + - Extensible Application Markup Language (XAML) as a device printer language. - Microsoft XPS Document Writer. @@ -32,7 +32,7 @@ This topic describes the object and the [!NOTE] -> and are designed for fixed-format document presentation and print scenarios. [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides several elements for general layout and [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] scenarios such as and . For more information on layout and [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] scenarios, see the [Typography in WPF](typography-in-wpf.md). +> and are designed for fixed-format document presentation and print scenarios. UI scenarios, see the [Typography in WPF](typography-in-wpf.md). ## The GlyphRun Object @@ -40,11 +40,11 @@ This topic describes the object and the includes both font details such as glyph and individual glyph positions. It also includes the original Unicode code points the run was generated from, character-to-glyph buffer offset mapping information, and per-character and per-glyph flags. - has a corresponding high-level , . can be used in the element tree and in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] markup to represent output. + has a corresponding high-level , . can be used in the element tree and in XAML markup to represent output. ## The Glyphs Element - The element represents the output of a in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]. The following markup syntax is used to describe the element. + The element represents the output of a in XAML. The following markup syntax is used to describe the element. [!code-xaml[GlyphsOvwSample1#1](~/samples/snippets/csharp/VS_Snippets_Wpf/GlyphsOvwSample1/CS/default.xaml#1)] @@ -83,7 +83,7 @@ This topic describes the object and the ## Glyphs Markup - The following code example shows how to use various properties of the element in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]. + The following code example shows how to use various properties of the element in XAML. [!code-xaml[GlyphsOvwSamp2#1](~/samples/snippets/csharp/VS_Snippets_Wpf/GlyphsOvwSamp2/CS/default.xaml#1)] diff --git a/dotnet-desktop-guide/framework/wpf/advanced/layout-considerations-for-the-windowsformshost-element.md b/dotnet-desktop-guide/framework/wpf/advanced/layout-considerations-for-the-windowsformshost-element.md index 4f3e456..35abfad 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/layout-considerations-for-the-windowsformshost-element.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/layout-considerations-for-the-windowsformshost-element.md @@ -11,14 +11,14 @@ helpviewer_keywords: ms.assetid: 3c574597-bbde-440f-95cc-01371f1a5d9d --- # Layout Considerations for the WindowsFormsHost Element -This topic describes how the element interacts with the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] layout system. +This topic describes how the element interacts with the WPF layout system. - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] and Windows Forms support different, but similar, logic for sizing and positioning elements on a form or page. When you create a hybrid user interface (UI) that hosts Windows Forms controls in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], the element integrates the two layout schemes. + WPF and Windows Forms support different, but similar, logic for sizing and positioning elements on a form or page. When you create a hybrid user interface (UI) that hosts Windows Forms controls in WPF, the element integrates the two layout schemes. ## Differences in Layout Between WPF and Windows Forms - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] uses resolution-independent layout. All [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] layout dimensions are specified using *device-independent pixels*. A device-independent pixel is one ninety-sixth of an inch in size and resolution-independent, so you get similar results regardless of whether you are rendering to a 72-dpi monitor or a 19,200-dpi printer. + WPF uses resolution-independent layout. All WPF layout dimensions are specified using *device-independent pixels*. A device-independent pixel is one ninety-sixth of an inch in size and resolution-independent, so you get similar results regardless of whether you are rendering to a 72-dpi monitor or a 19,200-dpi printer. - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] is also based on *dynamic layout*. This means that a UI element arranges itself on a form or page according to its content, its parent layout container, and the available screen size. Dynamic layout facilitates localization by automatically adjusting the size and position of UI elements when the strings they contain change length. + WPF is also based on *dynamic layout*. This means that a UI element arranges itself on a form or page according to its content, its parent layout container, and the available screen size. Dynamic layout facilitates localization by automatically adjusting the size and position of UI elements when the strings they contain change length. Layout in Windows Forms is device-dependent and more likely to be static. Typically, Windows Forms controls are positioned absolutely on a form using dimensions specified in hardware pixels. However, Windows Forms does support some dynamic layout features, as summarized in the following table. @@ -30,26 +30,26 @@ This topic describes how the and controls arrange their child controls and size themselves according to their contents.| ## Layout Limitations - In general, Windows Forms controls cannot be scaled and transformed to the extent possible in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. The following list describes the known limitations when the element attempts to integrate its hosted Windows Forms control into the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] layout system. + In general, Windows Forms controls cannot be scaled and transformed to the extent possible in WPF. The following list describes the known limitations when the element attempts to integrate its hosted Windows Forms control into the WPF layout system. -- In some cases, Windows Forms controls cannot be resized, or can be sized only to specific dimensions. For example, a Windows Forms control supports only a single height, which is defined by the control's font size. In a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] dynamic layout where elements can stretch vertically, a hosted control will not stretch as expected. +- In some cases, Windows Forms controls cannot be resized, or can be sized only to specific dimensions. For example, a Windows Forms control supports only a single height, which is defined by the control's font size. In a WPF dynamic layout where elements can stretch vertically, a hosted control will not stretch as expected. - Windows Forms controls cannot be rotated or skewed. The element raises the event if you apply a skew or rotation transformation. If you do not handle the event, an is raised. - In most cases, Windows Forms controls do not support proportional scaling. Although the overall dimensions of the control will scale, child controls and component elements of the control may not resize as expected. This limitation depends on how well each Windows Forms control supports scaling. In addition, you cannot scale Windows Forms controls down to a size of 0 pixels. -- Windows Forms controls support autoscaling, in which the form will automatically resize itself and its controls based on the font size. In a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] user interface, changing the font size does not resize the entire layout, although individual elements may dynamically resize. +- Windows Forms controls support autoscaling, in which the form will automatically resize itself and its controls based on the font size. In a WPF user interface, changing the font size does not resize the entire layout, although individual elements may dynamically resize. ### Z-order - In a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] user interface, you can change the z-order of elements to control overlapping behavior. A hosted Windows Forms control is drawn in a separate HWND, so it is always drawn on top of [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] elements. + In a WPF user interface, you can change the z-order of elements to control overlapping behavior. A hosted Windows Forms control is drawn in a separate HWND, so it is always drawn on top of WPF elements. A hosted Windows Forms control is also drawn on top of any elements. ## Layout Behavior - The following sections describe specific aspects of layout behavior when hosting Windows Forms controls in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. + The following sections describe specific aspects of layout behavior when hosting Windows Forms controls in WPF. ### Scaling, Unit Conversion, and Device Independence - Whenever the element performs operations involving [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] and Windows Forms dimensions, two coordinate systems are involved: device-independent pixels for [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] and hardware pixels for Windows Forms. Therefore, you must apply proper unit and scaling conversions to achieve a consistent layout. + Whenever the element performs operations involving WPF and Windows Forms dimensions, two coordinate systems are involved: device-independent pixels for WPF and hardware pixels for Windows Forms. Therefore, you must apply proper unit and scaling conversions to achieve a consistent layout. Conversion between the coordinate systems depends on the current device resolution and any layout or rendering transforms applied to the element or to its ancestors. @@ -63,17 +63,17 @@ This topic describes how the element uses standard rounding, so that fractional values less than 0.5 are rounded down to 0.| +|Rounding|WPF device-independent pixel dimensions are specified as `double`, and Windows Forms hardware pixel dimensions are specified as `int`. In cases where `double`-based dimensions are converted to `int`-based dimensions, the element uses standard rounding, so that fractional values less than 0.5 are rounded down to 0.| |Overflow|When the element converts from `double` values to `int` values, overflow is possible. Values that are larger than are set to .| ### Layout-related Properties - Properties that control layout behavior in Windows Forms controls and [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] elements are mapped appropriately by the element. For more information, see [Windows Forms and WPF Property Mapping](windows-forms-and-wpf-property-mapping.md). + Properties that control layout behavior in Windows Forms controls and WPF elements are mapped appropriately by the element. For more information, see [Windows Forms and WPF Property Mapping](windows-forms-and-wpf-property-mapping.md). ### Layout Changes in the Hosted Control - Layout changes in the hosted Windows Forms control are propagated to [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] to trigger layout updates. The method on ensures that layout changes in the hosted control cause the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] layout engine to run. + Layout changes in the hosted Windows Forms control are propagated to WPF to trigger layout updates. The method on ensures that layout changes in the hosted control cause the WPF layout engine to run. ### Continuously Sized Windows Forms Controls - Windows Forms controls that support continuous scaling fully interact with the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] layout system. The element uses the and methods as usual to size and arrange the hosted Windows Forms control. + Windows Forms controls that support continuous scaling fully interact with the WPF layout system. The element uses the and methods as usual to size and arrange the hosted Windows Forms control. ### Sizing Algorithm The element uses the following procedure to size the hosted control: @@ -90,7 +90,7 @@ This topic describes how the property returns a larger size than the specified constraint, the element clips the hosted control. Height and width are handled separately, so the hosted control may be clipped in either direction. -- If the property returns a smaller size than the specified constraint, accepts this size value and returns the value to the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] layout system. +- If the property returns a smaller size than the specified constraint, accepts this size value and returns the value to the WPF layout system. ## See also diff --git a/dotnet-desktop-guide/framework/wpf/advanced/layout.md b/dotnet-desktop-guide/framework/wpf/advanced/layout.md index 5b0f53f..e76deee 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/layout.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/layout.md @@ -42,7 +42,7 @@ The following illustration shows a simple layout. ![Screenshot that shows a typical grid, no bounding box superimposed.](./media/layout/grid-no-bounding-box-superimpose.png) -This layout can be achieved by using the following [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]. +This layout can be achieved by using the following XAML. [!code-xaml[LayoutInformation#1](~/samples/snippets/csharp/VS_Snippets_Wpf/LayoutInformation/CSharp/Window1.xaml#1)] @@ -133,7 +133,7 @@ Layout is a recursive process. Each child element in a instead of a . - A can be a very useful way to affect the content of a [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)]. However, if the effect of the transform does not have to impact the position of other elements, it is best to use a instead, because does not invoke the layout system. applies its transformation and forces a recursive layout update to account for the new position of the affected element. + A can be a very useful way to affect the content of a user interface (UI). However, if the effect of the transform does not have to impact the position of other elements, it is best to use a instead, because does not invoke the layout system. applies its transformation and forces a recursive layout update to account for the new position of the affected element. - Avoid unnecessary calls to . diff --git a/dotnet-desktop-guide/framework/wpf/advanced/loadfromhistory-function-wpf-unmanaged-api-reference.md b/dotnet-desktop-guide/framework/wpf/advanced/loadfromhistory-function-wpf-unmanaged-api-reference.md index c9dae26..40dd574 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/loadfromhistory-function-wpf-unmanaged-api-reference.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/loadfromhistory-function-wpf-unmanaged-api-reference.md @@ -40,7 +40,7 @@ HRESULT LoadFromHistory_export( In the .NET Framework 4 and later: PresentationHost_v0400.dll - **.NET Framework Version:** [!INCLUDE[net_current_v30plus](../../../includes/net-current-v30plus-md.md)] + **.NET Framework Version:** Available since 3.0 ## See also diff --git a/dotnet-desktop-guide/framework/wpf/advanced/localization-attributes-and-comments.md b/dotnet-desktop-guide/framework/wpf/advanced/localization-attributes-and-comments.md index f6991e6..d9dcf9c 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/localization-attributes-and-comments.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/localization-attributes-and-comments.md @@ -9,7 +9,7 @@ helpviewer_keywords: ms.assetid: ead2d9ac-b709-4ec1-a924-39927a29d02f --- # Localization Attributes and Comments -[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] localization comments are properties, inside XAML source code, supplied by developers to provide rules and hints for localization. [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] localization comments contain two sets of information: localizability attributes and free-form localization comments. Localizability attributes are used by the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] Localization API to indicate which resources are to be localized. Free-form comments are any information that the application author wants to include. +WPF Localization API to indicate which resources are to be localized. Free-form comments are any information that the application author wants to include. ## Add Localization Comments diff --git a/dotnet-desktop-guide/framework/wpf/advanced/marking-routed-events-as-handled-and-class-handling.md b/dotnet-desktop-guide/framework/wpf/advanced/marking-routed-events-as-handled-and-class-handling.md index 8391ef1..c522996 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/marking-routed-events-as-handled-and-class-handling.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/marking-routed-events-as-handled-and-class-handling.md @@ -27,23 +27,23 @@ Handlers for a routed event can mark the event handled within the event data. Ha ## When to Mark Events as Handled - When you set the value of the property to `true` in the event data for a routed event, this is referred to as "marking the event handled". There is no absolute rule for when you should mark routed events as handled, either as an application author, or as a control author who responds to existing routed events or implements new routed events. For the most part, the concept of "handled" as carried in the routed event's event data should be used as a limited protocol for your own application's responses to the various routed events exposed in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] APIs as well as for any custom routed events. Another way to consider the "handled" issue is that you should generally mark a routed event handled if your code responded to the routed event in a significant and relatively complete way. Typically, there should not be more than one significant response that requires separate handler implementations for any single routed event occurrence. If more responses are needed, then the necessary code should be implemented through application logic that is chained within a single handler rather than by using the routed event system for forwarding. The concept of what is "significant" is also subjective, and depends on your application or code. As general guidance, some "significant response" examples include: setting focus, modifying public state, setting properties that affect the visual representation, and raising other new events. Examples of nonsignificant responses include: modifying private state (with no visual impact, or programmatic representation), logging of events, or looking at arguments of an event and choosing not to respond to it. + When you set the value of the property to `true` in the event data for a routed event, this is referred to as "marking the event handled". There is no absolute rule for when you should mark routed events as handled, either as an application author, or as a control author who responds to existing routed events or implements new routed events. For the most part, the concept of "handled" as carried in the routed event's event data should be used as a limited protocol for your own application's responses to the various routed events exposed in WPF APIs as well as for any custom routed events. Another way to consider the "handled" issue is that you should generally mark a routed event handled if your code responded to the routed event in a significant and relatively complete way. Typically, there should not be more than one significant response that requires separate handler implementations for any single routed event occurrence. If more responses are needed, then the necessary code should be implemented through application logic that is chained within a single handler rather than by using the routed event system for forwarding. The concept of what is "significant" is also subjective, and depends on your application or code. As general guidance, some "significant response" examples include: setting focus, modifying public state, setting properties that affect the visual representation, and raising other new events. Examples of nonsignificant responses include: modifying private state (with no visual impact, or programmatic representation), logging of events, or looking at arguments of an event and choosing not to respond to it. - The routed event system behavior reinforces this "significant response" model for using handled state of a routed event, because handlers added in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] or the common signature of are not invoked in response to a routed event where the event data is already marked handled. You must go through the extra effort of adding a handler with the `handledEventsToo` parameter version () in order to handle routed events that are marked handled by earlier participants in the event route. + The routed event system behavior reinforces this "significant response" model for using handled state of a routed event, because handlers added in XAML or the common signature of are not invoked in response to a routed event where the event data is already marked handled. You must go through the extra effort of adding a handler with the `handledEventsToo` parameter version () in order to handle routed events that are marked handled by earlier participants in the event route. - In some circumstances, controls themselves mark certain routed events as handled. A handled routed event represents a decision by [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] control authors that the control's actions in response to the routed event are significant or complete as part of the control implementation, and the event needs no further handling. Usually this is done by adding a class handler for an event, or by overriding one of the class handler virtuals that exist on a base class. You can still work around this event handling if necessary; see [Working Around Event Suppression by Controls](#WorkingAroundEventSuppressionByControls) later in this topic. + In some circumstances, controls themselves mark certain routed events as handled. A handled routed event represents a decision by WPF control authors that the control's actions in response to the routed event are significant or complete as part of the control implementation, and the event needs no further handling. Usually this is done by adding a class handler for an event, or by overriding one of the class handler virtuals that exist on a base class. You can still work around this event handling if necessary; see [Working Around Event Suppression by Controls](#WorkingAroundEventSuppressionByControls) later in this topic. ## "Preview" (Tunneling) Events vs. Bubbling Events, and Event Handling Preview routed events are events that follow a tunneling route through the element tree. The "Preview" expressed in the naming convention is indicative of the general principle for input events that preview (tunneling) routed events are raised prior to the equivalent bubbling routed event. Also, input routed events that have a tunneling and bubbling pair have a distinct handling logic. If the tunneling/preview routed event is marked as handled by an event listener, then the bubbling routed event will be marked handled even before any listeners of the bubbling routed event receive it. The tunneling and bubbling routed events are technically separate events, but they deliberately share the same instance of event data to enable this behavior. - The connection between the tunneling and bubbling routed events is accomplished by the internal implementation of how any given [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] class raises its own declared routed events, and this is true of the paired input routed events. But unless this class-level implementation exists, there is no connection between a tunneling routed event and a bubbling routed event that share the naming scheme: without such implementation they would be two entirely separate routed events and would not be raised in sequence or share event data. + The connection between the tunneling and bubbling routed events is accomplished by the internal implementation of how any given WPF class raises its own declared routed events, and this is true of the paired input routed events. But unless this class-level implementation exists, there is no connection between a tunneling routed event and a bubbling routed event that share the naming scheme: without such implementation they would be two entirely separate routed events and would not be raised in sequence or share event data. For more information about how to implement tunnel/bubble input routed event pairs in a custom class, see [Create a Custom Routed Event](how-to-create-a-custom-routed-event.md). ## Class Handlers and Instance Handlers - Routed events consider two different types of listeners to the event: class listeners and instance listeners. Class listeners exist because types have called a particular API ,, in their static constructor, or have overridden a class handler virtual method from an element base class. Instance listeners are particular class instances/elements where one or more handlers have been attached for that routed event by a call to . Existing [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] routed events make calls to as part of the common language runtime (CLR) event wrapper add{} and remove{} implementations of the event, which is also how the simple [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] mechanism of attaching event handlers via an attribute syntax is enabled. Therefore even the simple [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] usage ultimately equates to an call. + Routed events consider two different types of listeners to the event: class listeners and instance listeners. Class listeners exist because types have called a particular API ,, in their static constructor, or have overridden a class handler virtual method from an element base class. Instance listeners are particular class instances/elements where one or more handlers have been attached for that routed event by a call to . Existing WPF routed events make calls to as part of the common language runtime (CLR) event wrapper add{} and remove{} implementations of the event, which is also how the simple XAML mechanism of attaching event handlers via an attribute syntax is enabled. Therefore even the simple XAML usage ultimately equates to an call. Elements within the visual tree are checked for registered handler implementations. Handlers are potentially invoked throughout the route, in the order that is inherent in the type of the routing strategy for that routed event. For instance, bubbling routed events will first invoke those handlers that are attached to the same element that raised the routed event. Then the routed event "bubbles" to the next parent element and so on until the application root element is reached. @@ -78,7 +78,7 @@ Handlers for a routed event can mark the event handled within the event data. Ha ## Deliberately Suppressing Input Events for Control Compositing - The main scenario where class handling of routed events is used is for input events and composited controls. A composited control is by definition composed of multiple practical controls or control base classes. Often the author of the control wishes to amalgamate all of the possible input events that each of the subcomponents might raise, in order to report the entire control as the singular event source. In some cases the control author might wish to suppress the events from components entirely, or substitute a component-defined event that carries more information or implies a more specific behavior. The canonical example that is immediately visible to any component author is how a [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] handles any mouse event that will eventually resolve to the intuitive event that all buttons have: a event. + The main scenario where class handling of routed events is used is for input events and composited controls. A composited control is by definition composed of multiple practical controls or control base classes. Often the author of the control wishes to amalgamate all of the possible input events that each of the subcomponents might raise, in order to report the entire control as the singular event source. In some cases the control author might wish to suppress the events from components entirely, or substitute a component-defined event that carries more information or implies a more specific behavior. The canonical example that is immediately visible to any component author is how a Windows Presentation Foundation (WPF) handles any mouse event that will eventually resolve to the intuitive event that all buttons have: a event. The base class () derives from which in turn derives from and , and much of the event infrastructure needed for control input processing is available at the level. In particular, processes general events that handle hit testing for the mouse cursor within its bounds, and provides distinct events for the most common button actions, such as . also provides an empty virtual as the preregistered class handler for , and overrides it. Similarly, uses class handlers for . In the overrides, which are passed the event data, the implementations mark that instance as handled by setting to `true`, and that same event data is what continues along the remainder of the route to other class handlers and also to instance handlers or event setters. Also, the override will next raise the event. The end result for most listeners will be that the and events "disappear" and are replaced instead by , an event that holds more meaning because it is known that this event originated from a true button and not some composite piece of the button or from some other element entirely. @@ -86,7 +86,7 @@ Handlers for a routed event can mark the event handled within the event data. Ha ### Working Around Event Suppression by Controls Sometimes this event suppression behavior within individual controls can interfere with some more general intentions of event handling logic for your application. For instance, if for some reason your application had a handler for located at the application root element, you would notice that any mouse click on a button would not invoke or handlers at the root level. The event itself actually did bubble up (again, event routes are not truly ended, but the routed event system changes their handler invocation behavior after being marked handled). When the routed event reached the button, the class handling marked the handled because it wished to substitute the event with more meaning. Therefore, any standard handler further up the route would not be invoked. There are two techniques you can use to ensure that your handlers would be invoked in this circumstance. - The first technique is to deliberately add the handler using the `handledEventsToo` signature of . A limitation of this approach is that this technique for attaching an event handler is only possible from code, not from markup. The simple syntax of specifying the event handler name as an event attribute value via [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] does not enable that behavior. + The first technique is to deliberately add the handler using the `handledEventsToo` signature of . A limitation of this approach is that this technique for attaching an event handler is only possible from code, not from markup. The simple syntax of specifying the event handler name as an event attribute value via Extensible Application Markup Language (XAML) does not enable that behavior. The second technique works only for input events, where the tunneling and bubbling versions of the routed event are paired. For these routed events, you can add handlers to the preview/tunneling equivalent routed event instead. That routed event will tunnel through the route starting from the root, so the button class handling code would not intercept it, presuming that you attached the Preview handler at some ancestor element level in the application's element tree. If you use this approach, be cautious about marking any Preview event handled. For the example given with being handled at the root element, if you marked the event as in the handler implementation, you would actually suppress the event. That is typically not desirable behavior. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/mc-ignorable-attribute.md b/dotnet-desktop-guide/framework/wpf/advanced/mc-ignorable-attribute.md index ffd4aed..49b518f 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/mc-ignorable-attribute.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/mc-ignorable-attribute.md @@ -13,7 +13,7 @@ helpviewer_keywords: ms.assetid: acd9a6ef-b7ca-4146-abb6-60f3b366e9ec --- # mc:Ignorable Attribute -Specifies which XML namespace prefixes encountered in a markup file may be ignored by a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor. The `mc:Ignorable` attribute supports markup compatibility both for custom namespace mapping and for [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] versioning. +Specifies which XML namespace prefixes encountered in a markup file may be ignored by a XAML processor. The `mc:Ignorable` attribute supports markup compatibility both for custom namespace mapping and for XAML versioning. ## XAML Attribute Usage (Single Prefix) @@ -44,18 +44,18 @@ Specifies which XML namespace prefixes encountered in a markup file may be ignor |-------|-------------| |*ignorablePrefix, ignorablePrefix1, etc.*|Any valid prefix string, per the XML 1.0 specification.| |*ignorableUri*|Any valid URI for designating a namespace, per the XML 1.0 specification.| -|*ThisElementCanBeIgnored*|An element that can be ignored by [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] processor implementations, if the underlying type cannot be resolved.| +|*ThisElementCanBeIgnored*|An element that can be ignored by Extensible Application Markup Language (XAML) processor implementations, if the underlying type cannot be resolved.| ## Remarks - The `mc` XML namespace prefix is the recommended prefix convention to use when mapping the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] compatibility namespace `http://schemas.openxmlformats.org/markup-compatibility/2006`. + The `mc` XML namespace prefix is the recommended prefix convention to use when mapping the XAML compatibility namespace `http://schemas.openxmlformats.org/markup-compatibility/2006`. - Elements or attributes where the prefix portion of the element name are identified as `mc:Ignorable` will not raise errors when processed by a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor. If that attribute could not be resolved to an underlying type or programming construct, then that element is ignored. Note however that ignored elements might still generate additional parsing errors for additional element requirements that are side effects of that element not being processed. For instance, a particular element content model might require exactly one child element, but if the specified child element was in an `mc:Ignorable` prefix, and the specified child element could not be resolved to a type, then the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor might raise an error. + Elements or attributes where the prefix portion of the element name are identified as `mc:Ignorable` will not raise errors when processed by a XAML processor. If that attribute could not be resolved to an underlying type or programming construct, then that element is ignored. Note however that ignored elements might still generate additional parsing errors for additional element requirements that are side effects of that element not being processed. For instance, a particular element content model might require exactly one child element, but if the specified child element was in an `mc:Ignorable` prefix, and the specified child element could not be resolved to a type, then the XAML processor might raise an error. `mc:Ignorable` only applies to namespace mappings to identifier strings. `mc:Ignorable` does not apply to namespace mappings into assemblies, which specify a CLR namespace and an assembly (or default to the current executable as the assembly). - If you are implementing a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor, your processor implementation must not raise parsing or processing errors on type resolution for any element or attribute that is qualified by a prefix that is identified as `mc:Ignorable`. But your processor implementation can still raise exceptions that are a secondary result of an element failing to load or be processed, such as the one-child element example given earlier. + If you are implementing a XAML processor, your processor implementation must not raise parsing or processing errors on type resolution for any element or attribute that is qualified by a prefix that is identified as `mc:Ignorable`. But your processor implementation can still raise exceptions that are a secondary result of an element failing to load or be processed, such as the one-child element example given earlier. - By default, a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor will ignore content within an ignored element. However, you can specify an additional attribute, [mc:ProcessContent Attribute](mc-processcontent-attribute.md), to require continued processing of content within an ignored element by the next available parent element. + By default, a XAML processor will ignore content within an ignored element. However, you can specify an additional attribute, [mc:ProcessContent Attribute](mc-processcontent-attribute.md), to require continued processing of content within an ignored element by the next available parent element. Multiple prefixes can be specified in the attribute, using one or more white-space characters as the separator, for example: `mc:Ignorable="ignore1 ignore2"`. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/mc-processcontent-attribute.md b/dotnet-desktop-guide/framework/wpf/advanced/mc-processcontent-attribute.md index 3649c61..e31b7b6 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/mc-processcontent-attribute.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/mc-processcontent-attribute.md @@ -10,7 +10,7 @@ ms.assetid: 2689b2c8-b4dc-4b71-b9bd-f95e619122d7 --- # mc:ProcessContent Attribute -Specifies which [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] elements should still have content processed by relevant parent elements, even if the immediate parent element may be ignored by a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor due to specifying [mc:Ignorable Attribute](mc-ignorable-attribute.md). The `mc:ProcessContent` attribute supports markup compatibility both for custom namespace mapping and for [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] versioning. +Specifies which XAML elements should still have content processed by relevant parent elements, even if the immediate parent element may be ignored by a XAML processor due to specifying [mc:Ignorable Attribute](mc-ignorable-attribute.md). The `mc:ProcessContent` attribute supports markup compatibility both for custom namespace mapping and for XAML versioning. ## XAML Attribute Usage @@ -33,12 +33,12 @@ Specifies which [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md. |-------|-------------| |*ignorablePrefix*|Any valid prefix string, per the XML 1.0 specification.| |*ignorableUri*|Any valid URI for designating a namespace, per the XML 1.0 specification.| -|*ThisElementCanBeIgnored*|An element that can be ignored by [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] processor implementations, if the underlying type cannot be resolved.| +|*ThisElementCanBeIgnored*|An element that can be ignored by Extensible Application Markup Language (XAML) processor implementations, if the underlying type cannot be resolved.| |*[content]*|*ThisElementCanBeIgnored* is marked ignorable. If the processor ignores that element, *[content]* is processed by *object*.| ## Remarks - By default, a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor will ignore content within an ignored element. You can specify a specific element by `mc:ProcessContent`, and a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor will continue to process the content within the ignored element. This would typically be used if the content is nested within several tags, at least one of which is ignorable and at least one of which is not ignorable. + By default, a XAML processor will ignore content within an ignored element. You can specify a specific element by `mc:ProcessContent`, and a XAML processor will continue to process the content within the ignored element. This would typically be used if the content is nested within several tags, at least one of which is ignorable and at least one of which is not ignorable. Multiple prefixes may be specified in the attribute, using a space separator, for example: `mc:ProcessContent="ignore:Element1 ignore:Element2"`. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/merged-resource-dictionaries.md b/dotnet-desktop-guide/framework/wpf/advanced/merged-resource-dictionaries.md index b1d5a9a..e10a389 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/merged-resource-dictionaries.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/merged-resource-dictionaries.md @@ -7,23 +7,23 @@ helpviewer_keywords: ms.assetid: d159531f-05d4-49fd-b951-c332de51e5bc --- # Merged Resource Dictionaries -[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] resources support a merged resource dictionary feature. This feature provides a way to define the resources portion of a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application outside of the compiled [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] application. Resources can then be shared across applications and are also more conveniently isolated for localization. +WPF application outside of the compiled XAML application. Resources can then be shared across applications and are also more conveniently isolated for localization. ## Introducing a Merged Resource Dictionary In markup, you use the following syntax to introduce a merged resource dictionary into a page: [!code-xaml[ResourceMergeDictionary#MergedXAML](~/samples/snippets/csharp/VS_Snippets_Wpf/ResourceMergeDictionary/CS/default.xaml#mergedxaml)] - Note that the element does not have an [x:Key Directive](/dotnet/desktop/xaml-services/xkey-directive), which is generally required for all items in a resource collection. But another reference within the collection is a special case, reserved for this merged resource dictionary scenario. The that introduces a merged resource dictionary cannot have an [x:Key Directive](/dotnet/desktop/xaml-services/xkey-directive). Typically, each within the collection specifies a attribute. The value of should be a uniform resource identifier (URI) that resolves to the location of the resources file to be merged. The destination of that URI must be another [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file, with as its root element. + Note that the element does not have an [x:Key Directive](/dotnet/desktop/xaml-services/xkey-directive), which is generally required for all items in a resource collection. But another reference within the collection is a special case, reserved for this merged resource dictionary scenario. The that introduces a merged resource dictionary cannot have an [x:Key Directive](/dotnet/desktop/xaml-services/xkey-directive). Typically, each within the collection specifies a attribute. The value of should be a uniform resource identifier (URI) that resolves to the location of the resources file to be merged. The destination of that URI must be another XAML file, with as its root element. > [!NOTE] > It is legal to define resources within a that is specified as a merged dictionary, either as an alternative to specifying , or in addition to whatever resources are included from the specified source. However, this is not a common scenario; the main scenario for merged dictionaries is to merge resources from external file locations. If you want to specify resources within the markup for a page, you should typically define these in the main and not in the merged dictionaries. ## Merged Dictionary Behavior - Resources in a merged dictionary occupy a location in the resource lookup scope that is just after the scope of the main resource dictionary they are merged into. Although a resource key must be unique within any individual dictionary, a key can exist multiple times in a set of merged dictionaries. In this case, the resource that is returned will come from the last dictionary found sequentially in the collection. If the collection was defined in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], then the order of the merged dictionaries in the collection is the order of the elements as provided in the markup. If a key is defined in the primary dictionary and also in a dictionary that was merged, then the resource that is returned will come from the primary dictionary. These scoping rules apply equally for both static resource references and dynamic resource references. + Resources in a merged dictionary occupy a location in the resource lookup scope that is just after the scope of the main resource dictionary they are merged into. Although a resource key must be unique within any individual dictionary, a key can exist multiple times in a set of merged dictionaries. In this case, the resource that is returned will come from the last dictionary found sequentially in the collection. If the collection was defined in XAML, then the order of the merged dictionaries in the collection is the order of the elements as provided in the markup. If a key is defined in the primary dictionary and also in a dictionary that was merged, then the resource that is returned will come from the primary dictionary. These scoping rules apply equally for both static resource references and dynamic resource references. ### Merged Dictionaries and Code - Merged dictionaries can be added to a `Resources` dictionary through code. The default, initially empty that exists for any `Resources` property also has a default, initially empty collection property. To add a merged dictionary through code, you obtain a reference to the desired primary , get its property value, and call `Add` on the generic `Collection` that is contained in . The object you add must be a new . In code, you do not set the property. Instead, you must obtain a object by either creating one or loading one. One way to load an existing to call on an existing [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file stream that has a root, then casting the return value to . + Merged dictionaries can be added to a `Resources` dictionary through code. The default, initially empty that exists for any `Resources` property also has a default, initially empty collection property. To add a merged dictionary through code, you obtain a reference to the desired primary , get its property value, and call `Add` on the generic `Collection` that is contained in . The object you add must be a new . In code, you do not set the property. Instead, you must obtain a object by either creating one or loading one. One way to load an existing to call on an existing XAML file stream that has a root, then casting the return value to . ### Merged Resource Dictionary URIs There are several techniques for how to include a merged resource dictionary, which are indicated by the uniform resource identifier (URI) format that you will use. Broadly speaking, these techniques can be divided into two categories: resources that are compiled as part of the project, and resources that are not compiled as part of the project. @@ -31,9 +31,9 @@ ms.assetid: d159531f-05d4-49fd-b951-c332de51e5bc For resources that are compiled as part of the project, you can use a relative path that refers to the resource location. The relative path is evaluated during compilation. Your resource must be defined as part of the project as a Resource build action. If you include a resource .xaml file in the project as Resource, you do not need to copy the resource file to the output directory, the resource is already included within the compiled application. You can also use Content build action, but you must then copy the files to the output directory and also deploy the resource files in the same path relationship to the executable. > [!NOTE] -> Do not use the Embedded Resource build action. The build action itself is supported for [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications, but the resolution of does not incorporate , and thus cannot separate the individual resource out of the stream. You could still use Embedded Resource for other purposes so long as you also used to access the resources. +> Do not use the Embedded Resource build action. The build action itself is supported for WPF applications, but the resolution of does not incorporate , and thus cannot separate the individual resource out of the stream. You could still use Embedded Resource for other purposes so long as you also used to access the resources. - A related technique is to use a Pack URI to a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file, and refer to it as Source. Pack URI enables references to components of referenced assemblies and other techniques. For more information on Pack URIs, see [WPF Application Resource, Content, and Data Files](../app-development/wpf-application-resource-content-and-data-files.md). + A related technique is to use a Pack URI to a XAML file, and refer to it as Source. Pack URI enables references to components of referenced assemblies and other techniques. For more information on Pack URIs, see [WPF Application Resource, Content, and Data Files](../app-development/wpf-application-resource-content-and-data-files.md). For resources that are not compiled as part of the project, the URI is evaluated at run time. You can use a common URI transport such as file: or http: to refer to the resource file. The disadvantage of using the noncompiled resource approach is that file: access requires additional deployment steps, and http: access implies the Internet security zone. @@ -43,7 +43,7 @@ ms.assetid: d159531f-05d4-49fd-b951-c332de51e5bc Writing merged dictionaries as local application files or to local shared storage is another possible merged dictionary / application deployment scenario. ### Localization - If resources that need to be localized are isolated to dictionaries that are merged into primary dictionaries, and kept as loose [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], these files can be localized separately. This technique is a lightweight alternative to localizing the satellite resource assemblies. For details, see [WPF Globalization and Localization Overview](wpf-globalization-and-localization-overview.md). + If resources that need to be localized are isolated to dictionaries that are merged into primary dictionaries, and kept as loose XAML, these files can be localized separately. This technique is a lightweight alternative to localizing the satellite resource assemblies. For details, see [WPF Globalization and Localization Overview](wpf-globalization-and-localization-overview.md). ## See also diff --git a/dotnet-desktop-guide/framework/wpf/advanced/migration-and-interoperability.md b/dotnet-desktop-guide/framework/wpf/advanced/migration-and-interoperability.md index 5b5cb15..1335a74 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/migration-and-interoperability.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/migration-and-interoperability.md @@ -16,7 +16,7 @@ ms.assetid: d655de05-bf63-4814-bc64-6b3be01c70a2 --- # Migration and Interoperability -This page contains links to documents that discuss how to implement interoperation between [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] applications and other types of Microsoft Windows applications. +This page contains links to documents that discuss how to implement interoperation between Windows Presentation Foundation (WPF) applications and other types of Microsoft Windows applications. ## In This Section @@ -29,10 +29,10 @@ This page contains links to documents that discuss how to implement interoperati | Term | Definition | |----------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| | An element that you can use to host a Windows Forms control as an element of a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] page. | -| | A Windows Forms control that you can use to host a [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] control. | -| | Hosts a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] region within a Win32 application. | -| | Base class for , defines some basic functionality that all HWND-based technologies use when hosted by a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application. Subclass this to host a Win32 window within a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application. | -| | A helper class for reporting conditions of the browser environment for a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application that is hosted by a browser. | +| | An element that you can use to host a Windows Forms control as an element of a WPF page. | +| | A Windows Forms control that you can use to host a Windows Presentation Foundation (WPF) control. | +| | Hosts a WPF region within a Win32 application. | +| | Base class for , defines some basic functionality that all HWND-based technologies use when hosted by a WPF application. Subclass this to host a Win32 window within a WPF application. | +| | A helper class for reporting conditions of the browser environment for a WPF application that is hosted by a browser. | ## Related Sections diff --git a/dotnet-desktop-guide/framework/wpf/advanced/object-lifetime-events.md b/dotnet-desktop-guide/framework/wpf/advanced/object-lifetime-events.md index b64341b..1a0314b 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/object-lifetime-events.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/object-lifetime-events.md @@ -26,15 +26,15 @@ helpviewer_keywords: ms.assetid: face6fc7-465b-4502-bfe5-e88d2e729a78 --- # Object Lifetime Events -This topic describes the specific [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] events that signify stages in an object lifetime of creation, use, and destruction. +This topic describes the specific WPF events that signify stages in an object lifetime of creation, use, and destruction. ## Prerequisites - This topic assumes that you understand dependency properties from the perspective of a consumer of existing dependency properties on [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] classes, and have read the [Dependency Properties Overview](dependency-properties-overview.md) topic. In order to follow the examples in this topic, you should also understand [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] (see [XAML in WPF](xaml-in-wpf.md)) and know how to write [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications. + This topic assumes that you understand dependency properties from the perspective of a consumer of existing dependency properties on WPF applications. ## Object Lifetime Events - All objects in Microsoft .NET Framework managed code go through a similar set of stages of life, creation, use, and destruction. Many objects also have a finalization stage of life that occurs as part of the destruction phase. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] objects, more specifically the visual objects that [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] identifies as elements, also have a set of common stages of object life. The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] programming and application models expose these stages as a series of events. There are four main types of objects in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] with respect to lifetime events; elements in general, window elements, navigation hosts, and application objects. Windows and navigation hosts are also within the larger grouping of visual objects (elements). This topic describes the lifetime events that are common to all elements and then introduces the more specific ones that apply to application definitions, windows or navigation hosts. + All objects in Microsoft .NET Framework managed code go through a similar set of stages of life, creation, use, and destruction. Many objects also have a finalization stage of life that occurs as part of the destruction phase. WPF objects, more specifically the visual objects that WPF identifies as elements, also have a set of common stages of object life. The WPF programming and application models expose these stages as a series of events. There are four main types of objects in WPF with respect to lifetime events; elements in general, window elements, navigation hosts, and application objects. Windows and navigation hosts are also within the larger grouping of visual objects (elements). This topic describes the lifetime events that are common to all elements and then introduces the more specific ones that apply to application definitions, windows or navigation hosts. ## Common Lifetime Events for Elements diff --git a/dotnet-desktop-guide/framework/wpf/advanced/opentype-font-features.md b/dotnet-desktop-guide/framework/wpf/advanced/opentype-font-features.md index fd46c54..482a121 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/opentype-font-features.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/opentype-font-features.md @@ -12,7 +12,7 @@ ms.assetid: 4061a9d1-fe8b-4921-9e17-18ec7d2e3ea2 --- # OpenType Font Features -This topic provides an overview of some of the key features of OpenType font technology in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)]. +This topic provides an overview of some of the key features of OpenType font technology in Windows Presentation Foundation (WPF). @@ -33,7 +33,7 @@ This topic provides an overview of some of the key features of OpenType font tec - Broader support for advanced typographic control. > [!NOTE] -> The Windows SDK contains a set of sample OpenType fonts that you can use with [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] applications. These fonts provide most of the features illustrated in the rest of this topic. For more information, see [Sample OpenType Font Pack](sample-opentype-font-pack.md). +> The Windows SDK contains a set of sample OpenType fonts that you can use with Windows Presentation Foundation (WPF) applications. These fonts provide most of the features illustrated in the rest of this topic. For more information, see [Sample OpenType Font Pack](sample-opentype-font-pack.md). For details of the OpenType font format, see the [OpenType specification](/typography/opentype/spec/). @@ -151,7 +151,7 @@ For details of the OpenType font format, see the [OpenType specification](/typog [!code-xaml[OpenTypeFontSamples#5](~/samples/snippets/csharp/VS_Snippets_Wpf/OpenTypeFontSamples/CS/PageOne.xaml#5)] - By default, OpenType fonts in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] enable standard ligatures. For example, if you use the Palatino Linotype font, the standard ligatures "fi", "ff", and "fl" appear as a combined character glyph. Notice that the pair of characters for each standard ligature touch each other. + By default, OpenType fonts in Windows Presentation Foundation (WPF) enable standard ligatures. For example, if you use the Palatino Linotype font, the standard ligatures "fi", "ff", and "fl" appear as a combined character glyph. Notice that the pair of characters for each standard ligature touch each other. ![Text using OpenType standard ligatures with Palatino Linotype](./media/opentype-font-features/opentype-standard-ligatures-palatino.gif "Text using OpenType standard ligatures with Palatino Linotype") diff --git a/dotnet-desktop-guide/framework/wpf/advanced/optimizing-performance-2d-graphics-and-imaging.md b/dotnet-desktop-guide/framework/wpf/advanced/optimizing-performance-2d-graphics-and-imaging.md index d3f94cf..065f9a3 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/optimizing-performance-2d-graphics-and-imaging.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/optimizing-performance-2d-graphics-and-imaging.md @@ -14,15 +14,15 @@ helpviewer_keywords: ms.assetid: e335601e-28c8-4d64-ba27-778fffd55f72 --- # Optimizing Performance: 2D Graphics and Imaging -[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides a wide range of 2D graphics and imaging functionality that can be optimized for your application requirements. This topic provides information about performance optimization in those areas. +WPF provides a wide range of 2D graphics and imaging functionality that can be optimized for your application requirements. This topic provides information about performance optimization in those areas. ## Drawing and Shapes - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides both and objects to represent graphical drawing content. However, objects are simpler constructs than objects and provide better performance characteristics. + WPF provides both and objects to represent graphical drawing content. However, objects are simpler constructs than objects and provide better performance characteristics. A allows you to draw a graphical shape to the screen. Because they are derived from the class, objects can be used inside panels and most controls. - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] offers several layers of access to graphics and rendering services. At the top layer, objects are easy to use and provide many useful features, such as layout and event handling. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides a number of ready-to-use shape objects. All shape objects inherit from the class. Available shape objects include , , , , , and . + WPF offers several layers of access to graphics and rendering services. At the top layer, objects are easy to use and provide many useful features, such as layout and event handling. WPF provides a number of ready-to-use shape objects. All shape objects inherit from the class. Available shape objects include , , , , , and . objects, on the other hand, do not derive from the class and provide a lighter-weight implementation for rendering shapes, images, and text. @@ -48,7 +48,7 @@ ms.assetid: e335601e-28c8-4d64-ba27-778fffd55f72 ## StreamGeometry Objects The object is a lightweight alternative to for creating geometric shapes. Use a when you need to describe a complex geometry. is optimized for handling many objects and performs better when compared to using many individual objects. - The following example uses attribute syntax to create a triangular in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]. + The following example uses attribute syntax to create a triangular in XAML. [!code-xaml[GeometriesMiscSnippets_snip#StreamGeometryTriangleExampleWholePage](~/samples/snippets/xaml/VS_Snippets_Wpf/GeometriesMiscSnippets_snip/XAML/StreamGeometryExample.xaml#streamgeometrytriangleexamplewholepage)] @@ -60,20 +60,20 @@ ms.assetid: e335601e-28c8-4d64-ba27-778fffd55f72 ## Images - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] imaging provides a significant improvement over the imaging capabilities in previous versions of Windows. Imaging capabilities, such as displaying a bitmap or using an image on a common control, were primarily handled by the Microsoft Windows Graphics Device Interface (GDI) or Microsoft Windows GDI+ application programming interface (API). These APIs provided baseline imaging functionality but lacked features such as support for codec extensibility and high fidelity image support. WPF Imaging APIs have been redesigned to overcome the shortcomings of GDI and GDI+ and provide a new set of APIs to display and use images within your applications. + WPF imaging provides a significant improvement over the imaging capabilities in previous versions of Windows. Imaging capabilities, such as displaying a bitmap or using an image on a common control, were primarily handled by the Microsoft Windows Graphics Device Interface (GDI) or Microsoft Windows GDI+ application programming interface (API). These APIs provided baseline imaging functionality but lacked features such as support for codec extensibility and high fidelity image support. WPF Imaging APIs have been redesigned to overcome the shortcomings of GDI and GDI+ and provide a new set of APIs to display and use images within your applications. When using images, consider the following recommendations for gaining better performance: -- If your application requires you to display thumbnail images, consider creating a reduced-sized version of the image. By default, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] loads your image and decodes it to its full size. If you only want a thumbnail version of the image, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] unnecessary decodes the image to its full-size and then scales it down to a thumbnail size. To avoid this unnecessary overhead, you can either request [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] to decode the image to a thumbnail size, or request [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] to load a thumbnail size image. +- If your application requires you to display thumbnail images, consider creating a reduced-sized version of the image. By default, WPF loads your image and decodes it to its full size. If you only want a thumbnail version of the image, WPF unnecessary decodes the image to its full-size and then scales it down to a thumbnail size. To avoid this unnecessary overhead, you can either request WPF to decode the image to a thumbnail size, or request WPF to load a thumbnail size image. -- Always decode the image to desired size and not to the default size. As mentioned above, request [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] to decode your image to a desired size and not the default full size. You will reduce not only your application's working set, but execution speed as well. +- Always decode the image to desired size and not to the default size. As mentioned above, request WPF to decode your image to a desired size and not the default full size. You will reduce not only your application's working set, but execution speed as well. - If possible, combine the images into a single image, such as a film strip composed of multiple images. - For more information, see [Imaging Overview](../graphics-multimedia/imaging-overview.md). ### BitmapScalingMode - When animating the scale of any bitmap, the default high-quality image resampling algorithm can sometimes consume sufficient system resources to cause frame rate degradation, effectively causing animations to stutter. By setting the property of the object to , you can create a smoother animation when scaling a bitmap. mode tells the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] rendering engine to switch from a quality-optimized algorithm to a speed-optimized algorithm when processing images. + When animating the scale of any bitmap, the default high-quality image resampling algorithm can sometimes consume sufficient system resources to cause frame rate degradation, effectively causing animations to stutter. By setting the property of the object to , you can create a smoother animation when scaling a bitmap. mode tells the WPF rendering engine to switch from a quality-optimized algorithm to a speed-optimized algorithm when processing images. The following example shows how to set the for an image object. @@ -81,7 +81,7 @@ ms.assetid: e335601e-28c8-4d64-ba27-778fffd55f72 [!code-vb[RenderOptions#RenderOptionsSnippet2](~/samples/snippets/visualbasic/VS_Snippets_Wpf/RenderOptions/visualbasic/window1.xaml.vb#renderoptionssnippet2)] ### CachingHint - By default, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] does not cache the rendered contents of objects, such as and . In static scenarios where the contents or use of the in the scene aren't changing, this makes sense, since it conserves video memory. It does not make as much sense when a with static content is used in a non-static way—for example, when a static or is mapped to the surface of a rotating 3D object. The default behavior of [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] is to re-render the entire content of the or for every frame, even though the content is unchanging. + By default, WPF does not cache the rendered contents of objects, such as and . In static scenarios where the contents or use of the in the scene aren't changing, this makes sense, since it conserves video memory. It does not make as much sense when a with static content is used in a non-static way—for example, when a static or is mapped to the surface of a rotating 3D object. The default behavior of WPF is to re-render the entire content of the or for every frame, even though the content is unchanging. By setting the property of the object to , you can increase performance by using cached versions of the tiled brush objects. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/optimizing-performance-application-resources.md b/dotnet-desktop-guide/framework/wpf/advanced/optimizing-performance-application-resources.md index 82f79c9..c234d3c 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/optimizing-performance-application-resources.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/optimizing-performance-application-resources.md @@ -11,14 +11,14 @@ helpviewer_keywords: ms.assetid: 62b88488-c08e-4804-b7de-a1c34fbe929c --- # Optimizing Performance: Application Resources -[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] allows you to share application resources so that you can support a consistent look or behavior across similar-typed elements. This topic provides a few recommendations in this area that can help you improve the performance of your applications. +WPF allows you to share application resources so that you can support a consistent look or behavior across similar-typed elements. This topic provides a few recommendations in this area that can help you improve the performance of your applications. For more information on resources, see [XAML Resources](/dotnet/desktop-wpf/fundamentals/xaml-resources-define). ## Sharing resources If your application uses custom controls and defines resources in a (or XAML Resources node), it is recommended that you either define the resources at the or object level, or define them in the default theme for the custom controls. Defining resources in a custom control's imposes a performance impact for every instance of that control. For example, if you have performance-intensive brush operations defined as part of the resource definition of a custom control and many instances of the custom control, the application's working set will increase significantly. - To illustrate this point, consider the following. Let's say you are developing a card game using [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. For most card games, you need 52 cards with 52 different faces. You decide to implement a card custom control and you define 52 brushes (each representing a card face) in the resources of your card custom control. In your main application, you initially create 52 instances of this card custom control. Each instance of the card custom control generates 52 instances of objects, which gives you a total of 52 * 52 objects in your application. By moving the brushes out of the card custom control resources to the or object level, or defining them in the default theme for the custom control, you reduce the working set of the application, since you are now sharing the 52 brushes among 52 instances of the card control. + To illustrate this point, consider the following. Let's say you are developing a card game using WPF. For most card games, you need 52 cards with 52 different faces. You decide to implement a card custom control and you define 52 brushes (each representing a card face) in the resources of your card custom control. In your main application, you initially create 52 instances of this card custom control. Each instance of the card custom control generates 52 instances of objects, which gives you a total of 52 * 52 objects in your application. By moving the brushes out of the card custom control resources to the or object level, or defining them in the default theme for the custom control, you reduce the working set of the application, since you are now sharing the 52 brushes among 52 instances of the card control. ## Sharing a Brush without Copying If you have multiple elements using the same object, define the brush as a resource and reference it, rather than defining the brush inline in XAML. This method will create one instance and reuse it, whereas defining brushes inline in XAML creates a new instance for each element. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/optimizing-performance-data-binding.md b/dotnet-desktop-guide/framework/wpf/advanced/optimizing-performance-data-binding.md index 02b6995..1b9a001 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/optimizing-performance-data-binding.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/optimizing-performance-data-binding.md @@ -7,21 +7,21 @@ helpviewer_keywords: ms.assetid: 1506a35d-c009-43db-9f1e-4e230ad5be73 --- # Optimizing Performance: Data Binding -[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] data binding provides a simple and consistent way for applications to present and interact with data. Elements can be bound to data from a variety of data sources in the form of CLR objects and XML. +Windows Presentation Foundation (WPF) data binding provides a simple and consistent way for applications to present and interact with data. Elements can be bound to data from a variety of data sources in the form of CLR objects and XML. This topic provides data binding performance recommendations. ## How Data Binding References are Resolved - Before discussing data binding performance issues, it is worthwhile to explore how the [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] data binding engine resolves object references for binding. + Before discussing data binding performance issues, it is worthwhile to explore how the Windows Presentation Foundation (WPF) data binding engine resolves object references for binding. - The source of a [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] data binding can be any CLR object. You can bind to properties, sub-properties, or indexers of a CLR object. The binding references are resolved by using either Microsoft .NET Framework reflection or an . Here are three methods for resolving object references for binding. + The source of a Windows Presentation Foundation (WPF) data binding can be any CLR object. You can bind to properties, sub-properties, or indexers of a CLR object. The binding references are resolved by using either Microsoft .NET Framework reflection or an . Here are three methods for resolving object references for binding. The first method involves using reflection. In this case, the object is used to discover the attributes of the property and provides access to property metadata. When using the interface, the data binding engine uses this interface to access the property values. The interface is especially useful in cases where the object does not have a static set of properties. Property change notifications can be provided either by implementing the interface or by using the change notifications associated with the . However, the preferred strategy for implementing property change notifications is to use . - If the source object is a CLR object and the source property is a CLR property, the [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] data binding engine has to first use reflection on the source object to get the , and then query for a . This sequence of reflection operations is potentially very time-consuming from a performance perspective. + If the source object is a CLR object and the source property is a CLR property, the Windows Presentation Foundation (WPF) data binding engine has to first use reflection on the source object to get the , and then query for a . This sequence of reflection operations is potentially very time-consuming from a performance perspective. The second method for resolving object references involves a CLR source object that implements the interface, and a source property that is a CLR property. In this case, the data binding engine uses reflection directly on the source type and gets the required property. This is still not the optimal method, but it will cost less in working set requirements than the first method. @@ -59,11 +59,11 @@ ms.assetid: 1506a35d-c009-43db-9f1e-4e230ad5be73 ## Bind IList to ItemsControl not IEnumerable - If you have a choice between binding an or an to an object, choose the object. Binding to an forces [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] to create a wrapper object, which means your performance is impacted by the unnecessary overhead of a second object. + If you have a choice between binding an or an to an object, choose the object. Binding to an forces WPF to create a wrapper object, which means your performance is impacted by the unnecessary overhead of a second object. ## Do not Convert CLR objects to XML Just for Data Binding. - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] allows you to data bind to XML content; however, data binding to XML content is slower than data binding to CLR objects. Do not convert CLR object data to XML if the only purpose is for data binding. + WPF allows you to data bind to XML content; however, data binding to XML content is slower than data binding to CLR objects. Do not convert CLR object data to XML if the only purpose is for data binding. ## See also diff --git a/dotnet-desktop-guide/framework/wpf/advanced/optimizing-performance-layout-and-design.md b/dotnet-desktop-guide/framework/wpf/advanced/optimizing-performance-layout-and-design.md index bc488a2..3719b3a 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/optimizing-performance-layout-and-design.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/optimizing-performance-layout-and-design.md @@ -11,7 +11,7 @@ helpviewer_keywords: ms.assetid: 005f4cda-a849-448b-916b-38d14d9a96fe --- # Optimizing Performance: Layout and Design -The design of your [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application can impact its performance by creating unnecessary overhead in calculating layout and validating object references. The construction of objects, particularly at run time, can affect the performance characteristics of your application. +The design of your WPF application can impact its performance by creating unnecessary overhead in calculating layout and validating object references. The construction of objects, particularly at run time, can affect the performance characteristics of your application. This topic provides performance recommendations in these areas. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/optimizing-performance-object-behavior.md b/dotnet-desktop-guide/framework/wpf/advanced/optimizing-performance-object-behavior.md index 5acbcc3..9d90852 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/optimizing-performance-object-behavior.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/optimizing-performance-object-behavior.md @@ -14,7 +14,7 @@ ms.assetid: 73aa2f47-1d73-439a-be1f-78dc4ba2b5bd --- # Optimizing Performance: Object Behavior -Understanding the intrinsic behavior of [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] objects will help you make the right tradeoffs between functionality and performance. +Understanding the intrinsic behavior of WPF objects will help you make the right tradeoffs between functionality and performance. @@ -22,7 +22,7 @@ Understanding the intrinsic behavior of [!INCLUDE[TLA2#tla_winclient](../../../i The delegate that an object passes to its event is effectively a reference to that object. Therefore, event handlers can keep objects alive longer than expected. When performing clean up of an object that has registered to listen to an object's event, it is essential to remove that delegate before releasing the object. Keeping unneeded objects alive increases the application's memory usage. This is especially true when the object is the root of a logical tree or a visual tree. - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] introduces a weak event listener pattern for events that can be useful in situations where the object lifetime relationships between source and listener are difficult to keep track of. Some existing [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] events use this pattern. If you are implementing objects with custom events, this pattern may be of use to you. For details, see [Weak Event Patterns](weak-event-patterns.md). + WPF introduces a weak event listener pattern for events that can be useful in situations where the object lifetime relationships between source and listener are difficult to keep track of. Some existing WPF events use this pattern. If you are implementing objects with custom events, this pattern may be of use to you. For details, see [Weak Event Patterns](weak-event-patterns.md). There are several tools, such as the CLR Profiler and the Working Set Viewer, that can provides information on the memory usage of a specified process. The CLR Profiler includes a number of very useful views of the allocation profile, including a histogram of allocated types, allocation and call graphs, a time line showing garbage collections of various generations and the resulting state of the managed heap after those collections, and a call tree showing per-method allocations and assembly loads. For more information, see [Performance](/previous-versions/aa497289(v=msdn.10)). @@ -67,7 +67,7 @@ Understanding the intrinsic behavior of [!INCLUDE[TLA2#tla_winclient](../../../i [!code-csharp[Performance#PerformanceSnippet2](~/samples/snippets/csharp/VS_Snippets_Wpf/Performance/CSharp/Window1.xaml.cs#performancesnippet2)] [!code-vb[Performance#PerformanceSnippet2](~/samples/snippets/visualbasic/VS_Snippets_Wpf/Performance/visualbasic/window1.xaml.vb#performancesnippet2)] - By default, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides an event handler for the object's event in order to invalidate the object's property. In this case, each time the has to fire its event it is required to invoke the callback function for each —the accumulation of these callback function invocations impose a significant performance penalty. In addition, it is very performance intensive to add and remove handlers at this point since the application would have to traverse the entire list to do so. If your application scenario never changes the , you will be paying the cost of maintaining event handlers unnecessarily. + By default, WPF provides an event handler for the object's event in order to invalidate the object's property. In this case, each time the has to fire its event it is required to invoke the callback function for each —the accumulation of these callback function invocations impose a significant performance penalty. In addition, it is very performance intensive to add and remove handlers at this point since the application would have to traverse the entire list to do so. If your application scenario never changes the , you will be paying the cost of maintaining event handlers unnecessarily. Freezing a can improve its performance, because it no longer needs to expend resources on maintaining change notifications. The table below shows the size of a simple when its property is set to `true`, compared to when it is not. This assumes applying one brush to the property of ten objects. @@ -85,7 +85,7 @@ Understanding the intrinsic behavior of [!INCLUDE[TLA2#tla_winclient](../../../i The delegate that an object passes to a object's event is effectively a reference to that object. Therefore, event handlers can keep objects alive longer than expected. When performing clean up of an object that has registered to listen to a object's event, it is essential to remove that delegate before releasing the object. - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] also hooks up events internally. For example, all dependency properties which take as a value will listen to events automatically. The property, which takes a , illustrates this concept. + WPF also hooks up events internally. For example, all dependency properties which take as a value will listen to events automatically. The property, which takes a , illustrates this concept. [!code-csharp[Performance#PerformanceSnippet4](~/samples/snippets/csharp/VS_Snippets_Wpf/Performance/CSharp/Window1.xaml.cs#performancesnippet4)] [!code-vb[Performance#PerformanceSnippet4](~/samples/snippets/visualbasic/VS_Snippets_Wpf/Performance/visualbasic/window1.xaml.vb#performancesnippet4)] @@ -106,7 +106,7 @@ Understanding the intrinsic behavior of [!INCLUDE[TLA2#tla_winclient](../../../i ## User Interface Virtualization - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] also provides a variation of the element that automatically "virtualizes" data-bound child content. In this context, the word virtualize refers to a technique by which a subset of objects are generated from a larger number of data items based upon which items are visible on-screen. It is intensive, both in terms of memory and processor, to generate a large number of UI elements when only a few may be on the screen at a given time. (through functionality provided by ) calculates visible items and works with the from an (such as or ) to only create elements for visible items. + WPF also provides a variation of the element that automatically "virtualizes" data-bound child content. In this context, the word virtualize refers to a technique by which a subset of objects are generated from a larger number of data items based upon which items are visible on-screen. It is intensive, both in terms of memory and processor, to generate a large number of UI elements when only a few may be on the screen at a given time. (through functionality provided by ) calculates visible items and works with the from an (such as or ) to only create elements for visible items. As a performance optimization, visual objects for these items are only generated or kept alive if they are visible on the screen. When they are no longer in the viewable area of the control, the visual objects may be removed. This is not to be confused with data virtualization, where data objects are not all present in the local collection- rather streamed in as needed. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/optimizing-performance-other-recommendations.md b/dotnet-desktop-guide/framework/wpf/advanced/optimizing-performance-other-recommendations.md index b419e62..b688f1b 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/optimizing-performance-other-recommendations.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/optimizing-performance-other-recommendations.md @@ -31,7 +31,7 @@ ms.assetid: d028cc65-7e97-4a4f-9859-929734eaf40d ## Opacity on Brushes Versus Opacity on Elements - When you use a to set the or of an element, it is better to set the value rather than the setting the element's property. Modifying an element's property can cause [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] to create a temporary surface. + When you use a to set the or of an element, it is better to set the value rather than the setting the element's property. Modifying an element's property can cause WPF to create a temporary surface. ## Navigation to Object @@ -54,7 +54,7 @@ ms.assetid: d028cc65-7e97-4a4f-9859-929734eaf40d ## CompositionTarget.Rendering Event - The event causes [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] to continuously animate. If you use this event, detach it at every opportunity. + The event causes WPF to continuously animate. If you use this event, detach it at every opportunity. ## Avoid Using ScrollBarVisibility=Auto diff --git a/dotnet-desktop-guide/framework/wpf/advanced/optimizing-performance-taking-advantage-of-hardware.md b/dotnet-desktop-guide/framework/wpf/advanced/optimizing-performance-taking-advantage-of-hardware.md index dfc00e9..de704cc 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/optimizing-performance-taking-advantage-of-hardware.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/optimizing-performance-taking-advantage-of-hardware.md @@ -11,20 +11,20 @@ helpviewer_keywords: ms.assetid: bfb89bae-7aab-4cac-a26c-a956eda8fce2 --- # Optimizing Performance: Taking Advantage of Hardware -The internal architecture of [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] has two rendering pipelines, hardware and software. This topic provides information about these rendering pipelines to help you make decisions about performance optimizations of your applications. +The internal architecture of WPF has two rendering pipelines, hardware and software. This topic provides information about these rendering pipelines to help you make decisions about performance optimizations of your applications. ## Hardware Rendering Pipeline - One of the most important factors in determining [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] performance is that it is render bound—the more pixels you have to render, the greater the performance cost. However, the more rendering that can be offloaded to the graphics processing unit (GPU), the more performance benefits you can gain. The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application hardware rendering pipeline takes full advantage of Microsoft DirectX features on hardware that supports a minimum of Microsoft DirectX version 7.0. Further optimizations can be gained by hardware that supports Microsoft DirectX version 7.0 and PixelShader 2.0+ features. + One of the most important factors in determining WPF performance is that it is render bound—the more pixels you have to render, the greater the performance cost. However, the more rendering that can be offloaded to the graphics processing unit (GPU), the more performance benefits you can gain. The WPF application hardware rendering pipeline takes full advantage of Microsoft DirectX features on hardware that supports a minimum of Microsoft DirectX version 7.0. Further optimizations can be gained by hardware that supports Microsoft DirectX version 7.0 and PixelShader 2.0+ features. ## Software Rendering Pipeline - The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] software rendering pipeline is entirely CPU bound. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] takes advantage of the SSE and SSE2 instruction sets in the CPU to implement an optimized, fully-featured software rasterizer. Fallback to software is seamless any time application functionality cannot be rendered using the hardware rendering pipeline. + The WPF software rendering pipeline is entirely CPU bound. WPF takes advantage of the SSE and SSE2 instruction sets in the CPU to implement an optimized, fully-featured software rasterizer. Fallback to software is seamless any time application functionality cannot be rendered using the hardware rendering pipeline. The biggest performance issue you will encounter when rendering in software mode is related to fill rate, which is defined as the number of pixels that you are rendering. If you are concerned about performance in software rendering mode, try to minimize the number of times a pixel is redrawn. For example, if you have an application with a blue background, which then renders a slightly transparent image over it, you will render all of the pixels in the application twice. As a result, it will take twice as long to render the application with the image than if you had only the blue background. ### Graphics Rendering Tiers It may be very difficult to predict the hardware configuration that your application will be running on. However, you might want to consider a design that allows your application to seamlessly switch features when running on different hardware, so that it can take full advantage of each different hardware configuration. - To achieve this, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides functionality to determine the graphics capability of a system at runtime. Graphics capability is determined by categorizing the video card as one of three rendering capability tiers. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] exposes an API that allows an application to query the rendering capability tier. Your application can then take different code paths at run time depending on the rendering tier supported by the hardware. + To achieve this, WPF provides functionality to determine the graphics capability of a system at runtime. Graphics capability is determined by categorizing the video card as one of three rendering capability tiers. WPF exposes an API that allows an application to query the rendering capability tier. Your application can then take different code paths at run time depending on the rendering tier supported by the hardware. The features of the graphics hardware that most impact the rendering tier levels are: @@ -36,9 +36,9 @@ The internal architecture of [!INCLUDE[TLA2#tla_winclient](../../../includes/tla - **Multitexture Support** Multitexture support refers to the ability to apply two or more distinct textures during a blending operation on a 3D graphics object. The degree of multitexture support is determined by the number of multitexture units on the graphics hardware. - The pixel shader, vertex shader, and multitexture features are used to define specific DirectX version levels, which, in turn, are used to define the different rendering tiers in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. + The pixel shader, vertex shader, and multitexture features are used to define specific DirectX version levels, which, in turn, are used to define the different rendering tiers in WPF. - The features of the graphics hardware determine the rendering capability of a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application. The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] system defines three rendering tiers: + The features of the graphics hardware determine the rendering capability of a WPF application. The WPF system defines three rendering tiers: - **Rendering Tier 0** No graphics hardware acceleration. The DirectX version level is less than version 7.0. @@ -46,7 +46,7 @@ The internal architecture of [!INCLUDE[TLA2#tla_winclient](../../../includes/tla - **Rendering Tier 2** Most graphics features use graphics hardware acceleration. The DirectX version level is greater than or equal to version 9.0. - For more information on [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] rendering tiers, see [Graphics Rendering Tiers](graphics-rendering-tiers.md). + For more information on WPF rendering tiers, see [Graphics Rendering Tiers](graphics-rendering-tiers.md). ## See also diff --git a/dotnet-desktop-guide/framework/wpf/advanced/optimizing-performance-text.md b/dotnet-desktop-guide/framework/wpf/advanced/optimizing-performance-text.md index 033bc7f..ba78cd4 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/optimizing-performance-text.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/optimizing-performance-text.md @@ -14,7 +14,7 @@ ms.assetid: 66b1b9a7-8618-48db-b616-c57ea4327b98 --- # Optimizing Performance: Text -[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] includes support for the presentation of text content through the use of feature-rich [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] controls. In general you can divide text rendering in three layers: +WPF includes support for the presentation of text content through the use of feature-rich user interface (UI) controls. In general you can divide text rendering in three layers: 1. Using the and objects directly. @@ -28,13 +28,13 @@ This topic provides text rendering performance recommendations. ## Rendering Text at the Glyph Level -[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides advanced text support including glyph-level markup with direct access to for customers who want to intercept and persist text after formatting. These features provide critical support for the different text rendering requirements in each of the following scenarios. +Windows Presentation Foundation (WPF) provides advanced text support including glyph-level markup with direct access to for customers who want to intercept and persist text after formatting. These features provide critical support for the different text rendering requirements in each of the following scenarios. - Screen display of fixed-format documents. - Print scenarios. - - [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] as a device printer language. + - Extensible Application Markup Language (XAML) as a device printer language. - Microsoft XPS Document Writer. @@ -45,9 +45,9 @@ This topic provides text rendering performance recommendations. - Fixed-format document representation, including clients for previous versions of Windows and other computing devices. > [!NOTE] -> and are designed for fixed-format document presentation and print scenarios. [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides several elements for general layout and [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] scenarios such as and . For more information on layout and [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] scenarios, see the [Typography in WPF](typography-in-wpf.md). +> and are designed for fixed-format document presentation and print scenarios. UI scenarios, see the [Typography in WPF](typography-in-wpf.md). -The following examples show how to define properties for a object in [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)]. The object represents the output of a in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]. The examples assume that the Arial, Courier New, and Times New Roman fonts are installed in the **C:\WINDOWS\Fonts** folder on the local computer. +The following examples show how to define properties for a object in XAML. The examples assume that the Arial, Courier New, and Times New Roman fonts are installed in the **C:\WINDOWS\Fonts** folder on the local computer. [!code-xaml[GlyphsOvwSample1#1](~/samples/snippets/csharp/VS_Snippets_Wpf/GlyphsOvwSample1/CS/default.xaml#1)] @@ -55,7 +55,7 @@ The following examples show how to define properties for a method. -[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] also provides lower-level services for custom text formatting through the use of the object. The most efficient way of rendering text in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] is by generating text content at the glyph level using and . However, the cost of this efficiency is the loss of easy to use rich text formatting, which are built-in features of [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] controls, such as and . +WPF also provides lower-level services for custom text formatting through the use of the object. The most efficient way of rendering text in Windows Presentation Foundation (WPF) is by generating text content at the glyph level using and . However, the cost of this efficiency is the loss of easy to use rich text formatting, which are built-in features of Windows Presentation Foundation (WPF) controls, such as and . @@ -76,11 +76,11 @@ The following code example creates a o ## FlowDocument, TextBlock, and Label Controls -[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] includes multiple controls for drawing text to the screen. Each control is targeted to a different scenario and has its own list of features and limitations. +WPF includes multiple controls for drawing text to the screen. Each control is targeted to a different scenario and has its own list of features and limitations. ### FlowDocument Impacts Performance More than TextBlock or Label -In general, the element should be used when limited text support is required, such as a brief sentence in a [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)]. can be used when minimal text support is required. The element is a container for re-flowable documents that support rich presentation of content, and therefore, has a greater performance impact than using the or controls. +In general, the element should be used when limited text support is required, such as a brief sentence in a user interface (UI). can be used when minimal text support is required. The element is a container for re-flowable documents that support rich presentation of content, and therefore, has a greater performance impact than using the or controls. For more information on , see [Flow Document Overview](flow-document-overview.md). @@ -161,11 +161,11 @@ The following table shows the performance cost of displaying 1000 and objects. By default, the automatic hyphenation feature is disabled in these objects. You can enable this feature by setting the object's IsHyphenationEnabled property to `true`. However, enabling this feature causes [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] to initiate Component Object Model (COM) interoperability, which can impact application performance. It is recommended that you do not use automatic hyphenation unless you need it. +Automatic hyphenation finds hyphen breakpoints for lines of text, and allows additional break positions for lines in and objects. By default, the automatic hyphenation feature is disabled in these objects. You can enable this feature by setting the object's IsHyphenationEnabled property to `true`. However, enabling this feature causes WPF to initiate Component Object Model (COM) interoperability, which can impact application performance. It is recommended that you do not use automatic hyphenation unless you need it. ### Use Figures Carefully diff --git a/dotnet-desktop-guide/framework/wpf/advanced/optimizing-wpf-application-performance.md b/dotnet-desktop-guide/framework/wpf/advanced/optimizing-wpf-application-performance.md index 15ab0af..b0b406e 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/optimizing-wpf-application-performance.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/optimizing-wpf-application-performance.md @@ -10,10 +10,10 @@ helpviewer_keywords: ms.assetid: ac8c6aa3-3c68-4a24-9827-3b6c829c1ebf --- # Optimizing WPF Application Performance -This section is intended as a reference for [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] application developers who are looking for ways to improve the performance of their applications. If you are a developer who is new to the Microsoft .NET Framework and [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], you should first familiarize yourself with both platforms. This section assumes working knowledge of both, and is written for programmers who already know enough to get their applications up and running. +This section is intended as a reference for WPF, you should first familiarize yourself with both platforms. This section assumes working knowledge of both, and is written for programmers who already know enough to get their applications up and running. > [!NOTE] -> The performance data provided in this section are based on [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications running on a 2.8 GHz PC with 512 RAM and an ATI Radeon 9700 graphics card. +> The performance data provided in this section are based on WPF applications running on a 2.8 GHz PC with 512 RAM and an ATI Radeon 9700 graphics card. ## In This Section [Planning for Application Performance](planning-for-application-performance.md) diff --git a/dotnet-desktop-guide/framework/wpf/advanced/packaging-fonts-with-applications.md b/dotnet-desktop-guide/framework/wpf/advanced/packaging-fonts-with-applications.md index 5ff1ff5..1c0ac04 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/packaging-fonts-with-applications.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/packaging-fonts-with-applications.md @@ -14,7 +14,7 @@ ms.assetid: db15ee48-4d24-49f5-8b9d-a64460865286 --- # Packaging Fonts with Applications -This topic provides an overview of how to package fonts with your [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] application. +This topic provides an overview of how to package fonts with your Windows Presentation Foundation (WPF) application. > [!NOTE] > As with most types of software, font files are licensed, rather than sold. Licenses that govern the use of fonts vary from vendor to vendor but in general most licenses, including those covering the fonts Microsoft supplies with applications and Windows, do not allow the fonts to be embedded within applications or otherwise redistributed. Therefore, as a developer it is your responsibility to ensure that you have the required license rights for any font you embed within an application or otherwise redistribute. @@ -23,7 +23,7 @@ This topic provides an overview of how to package fonts with your [!INCLUDE[TLA# ## Introduction to Packaging Fonts - You can easily package fonts as resources within your [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications to display user interface text and other types of text based content. The fonts can be separate from or embedded within the application's assembly files. You can also create a resource-only font library, which your application can reference. + You can easily package fonts as resources within your WPF applications to display user interface text and other types of text based content. The fonts can be separate from or embedded within the application's assembly files. You can also create a resource-only font library, which your application can reference. OpenType and TrueType® fonts contain a type flag, fsType, that indicates font embedding licensing rights for the font. However, this type flag only refers to embedded fonts stored in a document–it does not refer to fonts embedded in an application. You can retrieve the font embedding rights for a font by creating a object and referencing its property. Refer to the "OS/2 and Windows Metrics" section of the [OpenType Specification](https://www.microsoft.com/typography/otspec/os2.htm) for more information on the fsType flag. @@ -160,23 +160,23 @@ This topic provides an overview of how to package fonts with your [!INCLUDE[TLA# [!code-xaml[OpenTypeFontsSample#OpenTypeFontsSample1](~/samples/snippets/csharp/VS_Snippets_Wpf/OpenTypeFontsSample/CS/Kootenay.xaml#opentypefontssample1)] > [!NOTE] -> This SDK contains a set of sample OpenType fonts that you can use with [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications. The fonts are defined in a resource-only library. For more information, see [Sample OpenType Font Pack](sample-opentype-font-pack.md). +> This SDK contains a set of sample OpenType fonts that you can use with WPF applications. The fonts are defined in a resource-only library. For more information, see [Sample OpenType Font Pack](sample-opentype-font-pack.md). ## Limitations on Font Usage - The following list describes several limitations on the packaging and use of fonts in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications: + The following list describes several limitations on the packaging and use of fonts in WPF applications: -- **Font embedding permission bits:** [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications do not check or enforce any font embedding permission bits. See the [Introduction_to_Packing Fonts](#introduction_to_packaging_fonts) section for more information. +- **Font embedding permission bits:** WPF applications do not check or enforce any font embedding permission bits. See the [Introduction_to_Packing Fonts](#introduction_to_packaging_fonts) section for more information. -- **Site of origin fonts:** [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications do not allow a font reference to an http or ftp uniform resource identifier (URI). +- **Site of origin fonts:** WPF applications do not allow a font reference to an http or ftp uniform resource identifier (URI). -- **Absolute URI using the pack: notation:** [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications do not allow you to create a object programmatically using "pack:" as part of the absolute uniform resource identifier (URI) reference to a font. For example, `"pack://application:,,,/resources/#Pericles Light"` is an invalid font reference. +- **Absolute URI using the pack: notation:** WPF applications do not allow you to create a object programmatically using "pack:" as part of the absolute uniform resource identifier (URI) reference to a font. For example, `"pack://application:,,,/resources/#Pericles Light"` is an invalid font reference. - **Automatic font embedding:** During design time, there is no support for searching an application's use of fonts and automatically embedding the fonts in the application's resources. -- **Font subsets:** [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications do not support the creation of font subsets for non-fixed documents. +- **Font subsets:** WPF applications do not support the creation of font subsets for non-fixed documents. - In cases where there is an incorrect reference, the application falls back to using an available font. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/performance.md b/dotnet-desktop-guide/framework/wpf/advanced/performance.md index 1799b7b..72a05e6 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/performance.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/performance.md @@ -8,7 +8,7 @@ helpviewer_keywords: ms.assetid: c649a20f-8b7e-4a38-9b80-74839298d406 --- # Performance -Achieving optimal application performance requires forethought in application design and an understanding of best practices for [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] application development. The topics in this section provide additional information on building high performance [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications. +Achieving optimal application performance requires forethought in application design and an understanding of best practices for WPF applications. ## In This Section [Graphics Rendering Tiers](graphics-rendering-tiers.md) diff --git a/dotnet-desktop-guide/framework/wpf/advanced/planning-for-application-performance.md b/dotnet-desktop-guide/framework/wpf/advanced/planning-for-application-performance.md index d6a6e70..14f76e0 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/planning-for-application-performance.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/planning-for-application-performance.md @@ -22,9 +22,9 @@ The success of achieving your performance goals depends on how well you develop You should know the relative cost of each feature you will use. For example, the use of reflection in Microsoft .NET Framework is generally performance intensive in terms of computing resources, so you would want to use it judiciously. This does not mean to avoid the use of reflection, only that you should be careful to balance the performance requirements of your application with the performance demands of the features you use. ## Build Towards Graphical Richness - A key technique for creating a scalable approach towards achieving [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application performance is to build towards graphical richness and complexity. Always start with using the least performance intensive resources to achieve your scenario goals. Once you achieve these goals, build towards graphic richness by using more performance intensive features, always keeping your scenario goals in mind. Remember, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] is a very rich platform and provides very rich graphic features. Using performance intensive features without thinking can negatively impact your overall application performance. + A key technique for creating a scalable approach towards achieving WPF application performance is to build towards graphical richness and complexity. Always start with using the least performance intensive resources to achieve your scenario goals. Once you achieve these goals, build towards graphic richness by using more performance intensive features, always keeping your scenario goals in mind. Remember, WPF is a very rich platform and provides very rich graphic features. Using performance intensive features without thinking can negatively impact your overall application performance. - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] controls are inherently extensible by allowing for wide-spread customization of their appearance, while not altering their control behavior. By taking advantage of styles, data templates, and control templates, you can create and incrementally evolve a customizable [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] that adapts to your performance requirements. + WPF controls are inherently extensible by allowing for wide-spread customization of their appearance, while not altering their control behavior. By taking advantage of styles, data templates, and control templates, you can create and incrementally evolve a customizable user interface (UI) that adapts to your performance requirements. ## See also diff --git a/dotnet-desktop-guide/framework/wpf/advanced/presentationoptions-freeze-attribute.md b/dotnet-desktop-guide/framework/wpf/advanced/presentationoptions-freeze-attribute.md index 0f5ebda..3254167 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/presentationoptions-freeze-attribute.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/presentationoptions-freeze-attribute.md @@ -31,9 +31,9 @@ Sets the state to `true` on the cont |`freezableElement`|An element that instantiates any derived class of .| ## Remarks - The `Freeze` attribute is the only attribute or other programming element defined in the `http://schemas.microsoft.com/winfx/2006/xaml/presentation/options` XML namespace. The `Freeze` attribute exists in this special namespace specifically so that it can be designated as ignorable, using [mc:Ignorable Attribute](mc-ignorable-attribute.md) as part of the root element declarations. The reason that `Freeze` must be able to be ignorable is because not all [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor implementations are able to freeze a at load time; this capability is not part of the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] specification. + The `Freeze` attribute is the only attribute or other programming element defined in the `http://schemas.microsoft.com/winfx/2006/xaml/presentation/options` XML namespace. The `Freeze` attribute exists in this special namespace specifically so that it can be designated as ignorable, using [mc:Ignorable Attribute](mc-ignorable-attribute.md) as part of the root element declarations. The reason that `Freeze` must be able to be ignorable is because not all XAML processor implementations are able to freeze a at load time; this capability is not part of the XAML specification. - The ability to process the `Freeze` attribute is specifically built in to the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor that processes [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] for compiled applications. The attribute is not supported by any class, and the attribute syntax is not extensible or modifiable. If you are implementing your own [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor you can choose to parallel the freezing behavior of the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor when processing the `Freeze` attribute on elements at load time. + The ability to process the `Freeze` attribute is specifically built in to the WPF XAML processor when processing the `Freeze` attribute on elements at load time. Any value for the `Freeze` attribute other than `true` (not case sensitive) generates a load time error. (Specifying the `Freeze` attribute as `false` is not an error, but that is already the default, so setting to `false` does nothing). diff --git a/dotnet-desktop-guide/framework/wpf/advanced/preview-events.md b/dotnet-desktop-guide/framework/wpf/advanced/preview-events.md index 5e1b722..cd9b69b 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/preview-events.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/preview-events.md @@ -19,9 +19,9 @@ Preview events, also known as tunneling events, are routed events where the dire For more information about class handling and how it relates to Preview events see [Marking Routed Events as Handled, and Class Handling](marking-routed-events-as-handled-and-class-handling.md). ### Working Around Event Suppression by Controls - One scenario where Preview events are commonly used is for composited control handling of input events. Sometimes, the author of the control suppresses a certain event from originating from their control, perhaps in order to substitute a component-defined event that carries more information or implies a more specific behavior. For instance, a [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] suppresses and bubbling events raised by the or its composite elements in favor of capturing the mouse and raising a event that is always raised by the itself. The event and its data still continue along the route, but because the marks the event data as , only handlers for the event that specifically indicated they should act in the `handledEventsToo` case are invoked. If other elements towards the root of your application still wanted an opportunity to handle a control-suppressed event, one alternative is to attach handlers in code with `handledEventsToo` specified as `true`. But often a simpler technique is to change the routing direction you handle to be the Preview equivalent of an input event. For instance, if a control suppresses , try attaching a handler for instead. This technique only works for base element input events such as . These input events use tunnel/bubble pairs, raise both events, and share the event data. + One scenario where Preview events are commonly used is for composited control handling of input events. Sometimes, the author of the control suppresses a certain event from originating from their control, perhaps in order to substitute a component-defined event that carries more information or implies a more specific behavior. For instance, a Windows Presentation Foundation (WPF) suppresses and bubbling events raised by the or its composite elements in favor of capturing the mouse and raising a event that is always raised by the itself. The event and its data still continue along the route, but because the marks the event data as , only handlers for the event that specifically indicated they should act in the `handledEventsToo` case are invoked. If other elements towards the root of your application still wanted an opportunity to handle a control-suppressed event, one alternative is to attach handlers in code with `handledEventsToo` specified as `true`. But often a simpler technique is to change the routing direction you handle to be the Preview equivalent of an input event. For instance, if a control suppresses , try attaching a handler for instead. This technique only works for base element input events such as . These input events use tunnel/bubble pairs, raise both events, and share the event data. - Each of these techniques has either side effects or limitations. The side effect of handling the Preview event is that handling the event at that point might disable handlers that expect to handle the bubbling event, and therefore the limitation is that it is usually not a good idea to mark the event handled while it is still on the Preview part of the route. The limitation of the `handledEventsToo` technique is that you cannot specify a `handledEventsToo` handler in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] as an attribute, you must register the event handler in code after obtaining an object reference to the element where the handler is to be attached. + Each of these techniques has either side effects or limitations. The side effect of handling the Preview event is that handling the event at that point might disable handlers that expect to handle the bubbling event, and therefore the limitation is that it is usually not a good idea to mark the event handled while it is still on the Preview part of the route. The limitation of the `handledEventsToo` technique is that you cannot specify a `handledEventsToo` handler in XAML as an attribute, you must register the event handler in code after obtaining an object reference to the element where the handler is to be attached. ## See also diff --git a/dotnet-desktop-guide/framework/wpf/advanced/printing-how-to-topics.md b/dotnet-desktop-guide/framework/wpf/advanced/printing-how-to-topics.md index a7b3ba5..5eb2adc 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/printing-how-to-topics.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/printing-how-to-topics.md @@ -7,7 +7,7 @@ helpviewer_keywords: ms.assetid: 5f3d391a-4afd-49ee-ad99-ceb737c0c8a8 --- # Printing How-to Topics -The topics in this section demonstrate how to use the printing and print system management features included with [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] as well as the new XML Paper Specification (XPS) print path. +The topics in this section demonstrate how to use the printing and print system management features included with Windows Presentation Foundation (WPF) as well as the new XML Paper Specification (XPS) print path. ## In This Section [Invoke a Print Dialog](how-to-invoke-a-print-dialog.md) @@ -29,7 +29,7 @@ The topics in this section demonstrate how to use the printing and print system Instructions for how to discover at runtime print system object's properties and their types. [Programmatically Print XPS Files](how-to-programmatically-print-xps-files.md) - Instructions for rapid printing of XML Paper Specification (XPS) files without the need for a [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)]. + Instructions for rapid printing of XML Paper Specification (XPS) files without the need for a user interface (UI). [Remotely Survey the Status of Printers](how-to-remotely-survey-the-status-of-printers.md) Instructions for creating a utility that will survey printers to discover those experiencing a paper jam or other problem. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/printing-overview.md b/dotnet-desktop-guide/framework/wpf/advanced/printing-overview.md index 82faee1..447c057 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/printing-overview.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/printing-overview.md @@ -45,7 +45,7 @@ With Microsoft .NET Framework, application developers using Windows Presentation - Industry standard XPS format. - For basic print scenarios, a simple and intuitive API is available with a single entry point for user interface, configuration and job submission. For advanced scenarios, an additional support is added for [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] customization (or no [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] at all), synchronous or asynchronous printing, and batch printing capabilities. Both options provide print support in full or partial trust mode. + For basic print scenarios, a simple and intuitive API is available with a single entry point for user interface, configuration and job submission. For advanced scenarios, an additional support is added for UI at all), synchronous or asynchronous printing, and batch printing capabilities. Both options provide print support in full or partial trust mode. XPS was designed with extensibility in mind. By using the extensibility framework, features and capabilities can be added to XPS in a modular manner. Extensibility features include: @@ -63,10 +63,10 @@ With Microsoft .NET Framework, application developers using Windows Presentation ![Screenshot shows the XPS print system.](./media/printing-overview/xml-paper-specification-print-system.png) ### Basic XPS Printing - WPF defines both a basic and advanced API. For those applications that do not require extensive print customization or access to the complete XPS feature set, basic print support is available. Basic print support is exposed through a print dialog control that requires minimal configuration and features a familiar [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)]. Many XPS features are available using this simplified print model. + WPF defines both a basic and advanced API. For those applications that do not require extensive print customization or access to the complete XPS feature set, basic print support is available. Basic print support is exposed through a print dialog control that requires minimal configuration and features a familiar UI. Many XPS features are available using this simplified print model. #### PrintDialog - The control provides a single entry point for [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)], configuration, and XPS job submission. For information about how to instantiate and use the control, see [Invoke a Print Dialog](how-to-invoke-a-print-dialog.md). + The control provides a single entry point for UI, configuration, and XPS job submission. For information about how to instantiate and use the control, see [Invoke a Print Dialog](how-to-invoke-a-print-dialog.md). ### Advanced XPS Printing To access the complete set of XPS features, the advanced print API must be used. Several relevant API are described in greater detail below. For a complete list of XPS print path APIs, see the and namespace references. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/processunhandledexception-function-wpf-unmanaged-api-reference.md b/dotnet-desktop-guide/framework/wpf/advanced/processunhandledexception-function-wpf-unmanaged-api-reference.md index 8e3a889..3c51dd5 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/processunhandledexception-function-wpf-unmanaged-api-reference.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/processunhandledexception-function-wpf-unmanaged-api-reference.md @@ -36,7 +36,7 @@ void __stdcall ProcessUnhandledException( In the .NET Framework 4 and later: PresentationHost_v0400.dll - **.NET Framework Version:** [!INCLUDE[net_current_v30plus](../../../includes/net-current-v30plus-md.md)] + **.NET Framework Version:** Available since 3.0 ## See also diff --git a/dotnet-desktop-guide/framework/wpf/advanced/properties-wpf.md b/dotnet-desktop-guide/framework/wpf/advanced/properties-wpf.md index a171b7a..50db21e 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/properties-wpf.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/properties-wpf.md @@ -11,7 +11,7 @@ helpviewer_keywords: ms.assetid: d6e0197f-f2c4-48ed-b45b-b9cdb64aab1c --- # Properties (WPF) -[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides a set of services that can be used to extend the functionality of a common language runtime (CLR) property. Collectively, these services are typically referred to as the WPF property system. A property that is backed by the WPF property system is known as a dependency property. +Windows Presentation Foundation (WPF) provides a set of services that can be used to extend the functionality of a common language runtime (CLR) property. Collectively, these services are typically referred to as the WPF property system. A property that is backed by the WPF property system is known as a dependency property. ## In This Section diff --git a/dotnet-desktop-guide/framework/wpf/advanced/property-change-events.md b/dotnet-desktop-guide/framework/wpf/advanced/property-change-events.md index c61a0fa..cb8a662 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/property-change-events.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/property-change-events.md @@ -15,7 +15,7 @@ helpviewer_keywords: ms.assetid: 0a7989df-9674-4cc1-bc50-5d8ef5d9c055 --- # Property Change Events -[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] defines several events that are raised in response to a change in the value of a property. Often the property is a dependency property. The event itself is sometimes a routed event and is sometimes a standard common language runtime (CLR) event. The definition of the event varies depending on the scenario, because some property changes are more appropriately routed through an element tree, whereas other property changes are generally only of concern to the object where the property changed. +Windows Presentation Foundation (WPF) defines several events that are raised in response to a change in the value of a property. Often the property is a dependency property. The event itself is sometimes a routed event and is sometimes a standard common language runtime (CLR) event. The definition of the event varies depending on the scenario, because some property changes are more appropriately routed through an element tree, whereas other property changes are generally only of concern to the object where the property changed. ## Identifying a Property Change Event Not all events that report a property change are explicitly identified as a property changed event, either by virtue of a signature pattern or a naming pattern. Generally, the description of the event in the SDK documentation indicates whether the event is directly tied to a property value change and provides cross-references between the property and event. @@ -27,7 +27,7 @@ ms.assetid: 0a7989df-9674-4cc1-bc50-5d8ef5d9c055 Because you have an old value and a new value, it might be tempting to use this event handler as a validator for the property value. However, that is not the design intention of most property changed events. Generally, the values are provided so that you can act on those values in other logic areas of your code, but actually changing the values from within the event handler is not advisable, and may cause unintentional recursion depending on how your handler is implemented. - If your property is a custom dependency property, or if you are working with a derived class where you have defined the instantiation code, there is a much better mechanism for tracking property changes that is built in to the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] property system: the property system callbacks and . For more details about how you can use the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] property system for validation and coercion, see [Dependency Property Callbacks and Validation](dependency-property-callbacks-and-validation.md) and [Custom Dependency Properties](custom-dependency-properties.md). + If your property is a custom dependency property, or if you are working with a derived class where you have defined the instantiation code, there is a much better mechanism for tracking property changes that is built in to the WPF property system: the property system callbacks and . For more details about how you can use the WPF property system for validation and coercion, see [Dependency Property Callbacks and Validation](dependency-property-callbacks-and-validation.md) and [Custom Dependency Properties](custom-dependency-properties.md). ### DependencyPropertyChanged Events Another pair of types that are part of a property changed event scenario is and . Events for these property changes are not routed; they are standard CLR events. is an unusual event data reporting type because it does not derive from ; is a structure, not a class. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/property-value-inheritance.md b/dotnet-desktop-guide/framework/wpf/advanced/property-value-inheritance.md index c02f437..85ea923 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/property-value-inheritance.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/property-value-inheritance.md @@ -8,15 +8,15 @@ helpviewer_keywords: ms.assetid: d7c338f9-f2bf-48ed-832c-7be58ac390e4 --- # Property Value Inheritance -Property value inheritance is a feature of the [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] property system. Property value inheritance enables child elements in a tree of elements to obtain the value of a particular property from parent elements, inheriting that value as it was set anywhere in the nearest parent element. The parent element might also have obtained its value through property value inheritance, so the system potentially recurses all the way to the page root. Property value inheritance is not the default property system behavior; a property must be established with a particular metadata setting in order to cause that property to initiate property value inheritance on child elements. +Property value inheritance is a feature of the Windows Presentation Foundation (WPF) property system. Property value inheritance enables child elements in a tree of elements to obtain the value of a particular property from parent elements, inheriting that value as it was set anywhere in the nearest parent element. The parent element might also have obtained its value through property value inheritance, so the system potentially recurses all the way to the page root. Property value inheritance is not the default property system behavior; a property must be established with a particular metadata setting in order to cause that property to initiate property value inheritance on child elements. ## Property Value Inheritance Is Containment Inheritance - "Inheritance" as a term here is not quite the same concept as inheritance in the context of types and general object-oriented programming, where derived classes inherit member definitions from their base classes. That meaning of inheritance is also active in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]: properties defined in various base classes are exposed as attributes for derived [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] classes when used as elements, and exposed as members for code. Property value inheritance is particularly about how property values can inherit from one element to another on the basis of the parent-child relationships within a tree of elements. That tree of elements is most directly visible when nesting elements inside other elements as you define applications in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] markup. Trees of objects can also be created programmatically by adding objects to designated collections of other objects, and property value inheritance works the same way in the finished tree at run time. + "Inheritance" as a term here is not quite the same concept as inheritance in the context of types and general object-oriented programming, where derived classes inherit member definitions from their base classes. That meaning of inheritance is also active in WPF: properties defined in various base classes are exposed as attributes for derived XAML classes when used as elements, and exposed as members for code. Property value inheritance is particularly about how property values can inherit from one element to another on the basis of the parent-child relationships within a tree of elements. That tree of elements is most directly visible when nesting elements inside other elements as you define applications in XAML markup. Trees of objects can also be created programmatically by adding objects to designated collections of other objects, and property value inheritance works the same way in the finished tree at run time. ## Practical Applications of Property Value Inheritance - The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] APIs include several properties that have property inheritance enabled. Typically, the scenario for these is that they involve a property where it is appropriate that the property be set only once per page, but where that property is also a member of one of the base element classes and thus would also exist on most of the child elements. For example, the property controls which direction flowed content should be presented and arranged on the page. Typically, you want the text flow concept to be handled consistently throughout all child elements. If flow direction were for some reason reset in some level of the element tree by user or environment action, it should typically be reset throughout. When the property is made to inherit, the value need only be set or reset once at the level in the element tree that encompasses the presentation needs of each page in the application. Even the initial default value will inherit in this way. The property value inheritance model still enables individual elements to reset the value for the rare cases where having a mix of flow directions is intentional. + The WPF APIs include several properties that have property inheritance enabled. Typically, the scenario for these is that they involve a property where it is appropriate that the property be set only once per page, but where that property is also a member of one of the base element classes and thus would also exist on most of the child elements. For example, the property controls which direction flowed content should be presented and arranged on the page. Typically, you want the text flow concept to be handled consistently throughout all child elements. If flow direction were for some reason reset in some level of the element tree by user or environment action, it should typically be reset throughout. When the property is made to inherit, the value need only be set or reset once at the level in the element tree that encompasses the presentation needs of each page in the application. Even the initial default value will inherit in this way. The property value inheritance model still enables individual elements to reset the value for the rare cases where having a mix of flow directions is intentional. ## Making a Custom Property Inheritable diff --git a/dotnet-desktop-guide/framework/wpf/advanced/propertypath-xaml-syntax.md b/dotnet-desktop-guide/framework/wpf/advanced/propertypath-xaml-syntax.md index 9aa8f58..923c1f0 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/propertypath-xaml-syntax.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/propertypath-xaml-syntax.md @@ -8,23 +8,23 @@ ms.assetid: 0e3cdf07-abe6-460a-a9af-3764b4fd707f --- # PropertyPath XAML Syntax -The object supports a complex inline [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] syntax for setting various properties that take the type as their value. This topic documents the syntax as applied to binding and animation syntaxes. +The object supports a complex inline XAML syntax for setting various properties that take the type as their value. This topic documents the syntax as applied to binding and animation syntaxes. ## Where PropertyPath Is Used - is a common object that is used in several [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] features. Despite using the common to convey property path information, the usages for each feature area where is used as a type vary. Therefore, it is more practical to document the syntaxes on a per-feature basis. + is a common object that is used in several Windows Presentation Foundation (WPF) features. Despite using the common to convey property path information, the usages for each feature area where is used as a type vary. Therefore, it is more practical to document the syntaxes on a per-feature basis. -Primarily, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] uses to describe object-model paths for traversing the properties of an object data source, and to describe the target path for targeted animations. +Primarily, WPF uses to describe object-model paths for traversing the properties of an object data source, and to describe the target path for targeted animations. -Some style and template properties such as take a qualified property name that superficially resembles a . But this is not a true ; instead it is a qualified *owner.property* string format usage that is enabled by the WPF [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor in combination with the type converter for . +Some style and template properties such as take a qualified property name that superficially resembles a . But this is not a true ; instead it is a qualified *owner.property* string format usage that is enabled by the WPF XAML processor in combination with the type converter for . ## PropertyPath for Objects in Data Binding -Data binding is a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] feature whereby you can bind to the target value of any dependency property. However, the source of such a data binding need not be a dependency property; it can be any property type that is recognized by the applicable data provider. Property paths are particularly used for the , which is used for obtaining binding sources from common language runtime (CLR) objects and their properties. +Data binding is a WPF feature whereby you can bind to the target value of any dependency property. However, the source of such a data binding need not be a dependency property; it can be any property type that is recognized by the applicable data provider. Property paths are particularly used for the , which is used for obtaining binding sources from common language runtime (CLR) objects and their properties. Note that data binding to XML does not use , because it does not use in the . Instead, you use and specify valid XPath syntax into the XML Document Object Model (DOM) of the data. is also specified as a string, but is not documented here; see [Bind to XML Data Using an XMLDataProvider and XPath Queries](../data/how-to-bind-to-xml-data-using-an-xmldataprovider-and-xpath-queries.md). @@ -70,9 +70,9 @@ You can specify the type of the index if necessary. For details on this aspect o ``` -The parentheses indicate that this property in a should be constructed using a partial qualification. It can use an XML namespace to find the type with an appropriate mapping. The `ownerType` searches types that a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor has access to, through the declarations in each assembly. Most applications have the default XML namespace mapped to the `http://schemas.microsoft.com/winfx/2006/xaml/presentation` namespace, so a prefix is usually only necessary for custom types or types otherwise outside that namespace. `propertyName` must resolve to be the name of a property existing on the `ownerType`. This syntax is generally used for one of the following cases: +The parentheses indicate that this property in a should be constructed using a partial qualification. It can use an XML namespace to find the type with an appropriate mapping. The `ownerType` searches types that a XAML processor has access to, through the declarations in each assembly. Most applications have the default XML namespace mapped to the `http://schemas.microsoft.com/winfx/2006/xaml/presentation` namespace, so a prefix is usually only necessary for custom types or types otherwise outside that namespace. `propertyName` must resolve to be the name of a property existing on the `ownerType`. This syntax is generally used for one of the following cases: -- The path is specified in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] that is in a style or template that does not have a specified Target Type. A qualified usage is generally not valid for cases other than this, because in non-style, non-template cases, the property exists on an instance, not a type. +- The path is specified in XAML that is in a style or template that does not have a specified Target Type. A qualified usage is generally not valid for cases other than this, because in non-style, non-template cases, the property exists on an instance, not a type. - The property is an attached property. @@ -198,7 +198,7 @@ For instance, the property of ``` -The parentheses indicate that this property in a should be constructed using a partial qualification. It can use an XML namespace to find the type. The `ownerType` searches types that a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor has access to, through the declarations in each assembly. Most applications have the default XML namespace mapped to the `http://schemas.microsoft.com/winfx/2006/xaml/presentation` namespace, so a prefix is usually only necessary for custom types or types otherwise outside that namespace. `propertyName` must resolve to be the name of a property existing on the `ownerType`. The property specified as `propertyName` must be a . (All [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] attached properties are implemented as dependency properties, so this issue is only of concern for custom attached properties.) +The parentheses indicate that this property in a should be constructed using a partial qualification. It can use an XML namespace to find the type. The `ownerType` searches types that a WPF attached properties are implemented as dependency properties, so this issue is only of concern for custom attached properties.) diff --git a/dotnet-desktop-guide/framework/wpf/advanced/read-only-dependency-properties.md b/dotnet-desktop-guide/framework/wpf/advanced/read-only-dependency-properties.md index af906d9..f7e0936 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/read-only-dependency-properties.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/read-only-dependency-properties.md @@ -15,7 +15,7 @@ This topic describes read-only dependency properties, including existing read-on ## Existing Read-Only Dependency Properties - Some of the dependency properties defined in the [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] framework are read-only. The typical reason for specifying a read-only dependency property is that these are properties that should be used for state determination, but where that state is influenced by a multitude of factors, but just setting the property to that state isn't desirable from a user interface design perspective. For example, the property is really just surfacing state as determined from the mouse input. Any attempt to set this value programmatically by circumventing the true mouse input would be unpredictable and would cause inconsistency. + Some of the dependency properties defined in the Windows Presentation Foundation (WPF) framework are read-only. The typical reason for specifying a read-only dependency property is that these are properties that should be used for state determination, but where that state is influenced by a multitude of factors, but just setting the property to that state isn't desirable from a user interface design perspective. For example, the property is really just surfacing state as determined from the mouse input. Any attempt to set this value programmatically by circumventing the true mouse input would be unpredictable and would cause inconsistency. By virtue of not being settable, read-only dependency properties aren't appropriate for many of the scenarios for which dependency properties normally offer a solution (namely: data binding, directly stylable to a value, validation, animation, inheritance). Despite not being settable, read-only dependency properties still have some of the additional capabilities supported by dependency properties in the property system. The most important remaining capability is that the read-only dependency property can still be used as a property trigger in a style. You can't enable triggers with a normal common language runtime (CLR) property; it needs to be a dependency property. The aforementioned property is a perfect example of a scenario where it might be quite useful to define a style for a control, where some visible property such as a background, foreground, or similar properties of composited elements within the control will change when the user places a mouse over some defined region of your control. Changes in a read-only dependency property can also be detected and reported by the property system's inherent invalidation processes, and this in fact supports the property trigger functionality internally. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/relativesource-markupextension.md b/dotnet-desktop-guide/framework/wpf/advanced/relativesource-markupextension.md index e9f8c86..5c710f3 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/relativesource-markupextension.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/relativesource-markupextension.md @@ -103,7 +103,7 @@ In the following example, the first in Describing data binding as a concept is not covered here, see [Data Binding Overview](../data/data-binding-overview.md). -In the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] XAML processor implementation, the handling for this markup extension is defined by the class. +In the WPF XAML processor implementation, the handling for this markup extension is defined by the class. `RelativeSource` is a markup extension. Markup extensions are typically implemented when there is a requirement to escape attribute values to be other than literal values or handler names, and the requirement is more global than just putting type converters on certain types or properties. All markup extensions in XAML use the `{` and `}` characters in their attribute syntax, which is the convention by which a XAML processor recognizes that a markup extension must process the attribute. For more information, see [Markup Extensions and WPF XAML](markup-extensions-and-wpf-xaml.md). diff --git a/dotnet-desktop-guide/framework/wpf/advanced/resources-and-code.md b/dotnet-desktop-guide/framework/wpf/advanced/resources-and-code.md index 1c09215..9f4860e 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/resources-and-code.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/resources-and-code.md @@ -13,11 +13,11 @@ helpviewer_keywords: ms.assetid: c1cfcddb-e39c-41c8-a7f3-60984914dfae --- # Resources and Code -This overview concentrates on how [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] resources can be accessed or created using code rather than [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] syntax. For more information on general resource usage and resources from a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] syntax perspective, see [XAML Resources](/dotnet/desktop-wpf/fundamentals/xaml-resources-define). +This overview concentrates on how XAML syntax perspective, see [XAML Resources](/dotnet/desktop-wpf/fundamentals/xaml-resources-define). ## Accessing Resources from Code - The keys that identify resources if they are defined through [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] are also used to retrieve specific resources if you request the resource in code. The simplest way to retrieve a resource from code is to call either the or the method from framework-level objects in your application. The behavioral difference between these methods is what happens if the requested key is not found. raises an exception; will not raise an exception but returns `null`. Each method takes the resource key as an input parameter, and returns a loosely typed object. Typically, a resource key is a string, but there are occasional nonstring usages; see the [Using Objects as Keys](#objectaskey) section for details. Typically you would cast the returned object to the type required by the property that you are setting when requesting the resource. The lookup logic for code resource resolution is the same as the dynamic resource reference [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] case. The search for resources starts from the calling element, then continues to successive parent elements in the logical tree. The lookup continues onwards into application resources, themes, and system resources if necessary. A code request for a resource will properly account for runtime changes in resource dictionaries that might have been made subsequent to that resource dictionary being loaded from [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], and also for realtime system resource changes. + The keys that identify resources if they are defined through XAML are also used to retrieve specific resources if you request the resource in code. The simplest way to retrieve a resource from code is to call either the or the method from framework-level objects in your application. The behavioral difference between these methods is what happens if the requested key is not found. raises an exception; will not raise an exception but returns `null`. Each method takes the resource key as an input parameter, and returns a loosely typed object. Typically, a resource key is a string, but there are occasional nonstring usages; see the [Using Objects as Keys](#objectaskey) section for details. Typically you would cast the returned object to the type required by the property that you are setting when requesting the resource. The lookup logic for code resource resolution is the same as the dynamic resource reference XAML case. The search for resources starts from the calling element, then continues to successive parent elements in the logical tree. The lookup continues onwards into application resources, themes, and system resources if necessary. A code request for a resource will properly account for runtime changes in resource dictionaries that might have been made subsequent to that resource dictionary being loaded from XAML, and also for realtime system resource changes. The following is a brief code example that finds a resource by key and uses the returned value to set a property, implemented as a event handler. @@ -26,17 +26,17 @@ This overview concentrates on how [!INCLUDE[TLA#tla_winclient](../../../includes An alternative method for assigning a resource reference is . This method takes two parameters: the key of the resource, and the identifier for a particular dependency property that is present on the element instance to which the resource value should be assigned. Functionally, this method is the same and has the advantage of not requiring any casting of return values. - Still another way to access resources programmatically is to access the contents of the property as a dictionary. Accessing the dictionary contained by this property is also how you can add new resources to existing collections, check to see if a given key name is already taken in the collection, and other dictionary/collection operations. If you are writing a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application entirely in code, you can also create the entire collection in code, assign keys to it, and then assign the finished collection to the property of an established element. This will be described in the next section. + Still another way to access resources programmatically is to access the contents of the property as a dictionary. Accessing the dictionary contained by this property is also how you can add new resources to existing collections, check to see if a given key name is already taken in the collection, and other dictionary/collection operations. If you are writing a WPF application entirely in code, you can also create the entire collection in code, assign keys to it, and then assign the finished collection to the property of an established element. This will be described in the next section. You can index within any given collection, using a specific key as the index, but you should be aware that accessing the resource in this way does not follow the normal runtime rules of resource resolution. You are only accessing that particular collection. Resource lookup will not be traversing the scope to the root or the application if no valid object was found at the requested key. However, this approach may have performance advantages in some cases precisely because the scope of the search for the key is more constrained. See the class for more details on how to work with the resource dictionary directly. ## Creating Resources with Code - If you want to create an entire [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application in code, you might also want to create any resources in that application in code. To achieve this, create a new instance, and then add all the resources to the dictionary using successive calls to . Then, use the thus created to set the property on an element that is present in a page scope, or the . You could also maintain the as a standalone object without adding it to an element. However, if you do this, you must access the resources within it by item key, as if it were a generic dictionary. A that is not attached to an element `Resources` property would not exist as part of the element tree and has no scope in a lookup sequence that can be used by and related methods. + If you want to create an entire WPF application in code, you might also want to create any resources in that application in code. To achieve this, create a new instance, and then add all the resources to the dictionary using successive calls to . Then, use the thus created to set the property on an element that is present in a page scope, or the . You could also maintain the as a standalone object without adding it to an element. However, if you do this, you must access the resources within it by item key, as if it were a generic dictionary. A that is not attached to an element `Resources` property would not exist as part of the element tree and has no scope in a lookup sequence that can be used by and related methods. ## Using Objects as Keys - Most resource usages will set the key of the resource to be a string. However, various [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] features deliberately do not use a string type to specify keys, instead this parameter is an object. The capability of having the resource be keyed by an object is used by the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] style and theming support. The styles in themes which become the default style for an otherwise non-styled control are each keyed by the of the control that they should apply to. Being keyed by type provides a reliable lookup mechanism that works on default instances of each control type, and type can be detected by reflection and used for styling derived classes even though the derived type otherwise has no default style. You can specify a key for a resource defined in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] by using the [x:Type Markup Extension](/dotnet/desktop/xaml-services/xtype-markup-extension). Similar extensions exist for other nonstring key usages that support [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] features, such as [ComponentResourceKey Markup Extension](componentresourcekey-markup-extension.md). + Most resource usages will set the key of the resource to be a string. However, various WPF features deliberately do not use a string type to specify keys, instead this parameter is an object. The capability of having the resource be keyed by an object is used by the WPF style and theming support. The styles in themes which become the default style for an otherwise non-styled control are each keyed by the of the control that they should apply to. Being keyed by type provides a reliable lookup mechanism that works on default instances of each control type, and type can be detected by reflection and used for styling derived classes even though the derived type otherwise has no default style. You can specify a key for a resource defined in WPF features, such as [ComponentResourceKey Markup Extension](componentresourcekey-markup-extension.md). ## See also diff --git a/dotnet-desktop-guide/framework/wpf/advanced/routed-events-overview.md b/dotnet-desktop-guide/framework/wpf/advanced/routed-events-overview.md index 0adbec3..3e02690 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/routed-events-overview.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/routed-events-overview.md @@ -20,13 +20,13 @@ ms.assetid: 1a2189ae-13b4-45b0-b12c-8de2e49c29d2 --- # Routed Events Overview -This topic describes the concept of routed events in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)]. The topic defines routed events terminology, describes how routed events are routed through a tree of elements, summarizes how you handle routed events, and introduces how to create your own custom routed events. +This topic describes the concept of routed events in Windows Presentation Foundation (WPF). The topic defines routed events terminology, describes how routed events are routed through a tree of elements, summarizes how you handle routed events, and introduces how to create your own custom routed events. ## Prerequisites -This topic assumes that you have basic knowledge of the common language runtime (CLR) and object-oriented programming, as well as the concept of how the relationships between [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] elements can be conceptualized as a tree. In order to follow the examples in this topic, you should also understand [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] and know how to write very basic [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications or pages. For more information, see [Walkthrough: My first WPF desktop application](../getting-started/walkthrough-my-first-wpf-desktop-application.md) and [XAML in WPF](xaml-in-wpf.md). +This topic assumes that you have basic knowledge of the common language runtime (CLR) and object-oriented programming, as well as the concept of how the relationships between WPF elements can be conceptualized as a tree. In order to follow the examples in this topic, you should also understand WPF applications or pages. For more information, see [Walkthrough: My first WPF desktop application](../getting-started/walkthrough-my-first-wpf-desktop-application.md) and [XAML in WPF](xaml-in-wpf.md). @@ -36,9 +36,9 @@ You can think about routed events either from a functional or implementation per Functional definition: A routed event is a type of event that can invoke handlers on multiple listeners in an element tree, rather than just on the object that raised the event. -Implementation definition: A routed event is a CLR event that is backed by an instance of the class and is processed by the [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] event system. +Implementation definition: A routed event is a CLR event that is backed by an instance of the class and is processed by the Windows Presentation Foundation (WPF) event system. -A typical [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application contains many elements. Whether created in code or declared in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], these elements exist in an element tree relationship to each other. The event route can travel in one of two directions depending on the event definition, but generally the route travels from the source element and then "bubbles" upward through the element tree until it reaches the element tree root (typically a page or a window). This bubbling concept might be familiar to you if you have worked with the DHTML object model previously. +A typical WPF application contains many elements. Whether created in code or declared in XAML, these elements exist in an element tree relationship to each other. The event route can travel in one of two directions depending on the event definition, but generally the route travels from the source element and then "bubbles" upward through the element tree until it reaches the element tree root (typically a page or a window). This bubbling concept might be familiar to you if you have worked with the DHTML object model previously. Consider the following simple element tree: @@ -58,9 +58,9 @@ Button-->StackPanel-->Border-->... The following is a brief summary of the scenarios that motivated the routed event concept, and why a typical CLR event was not adequate for these scenarios: -**Control composition and encapsulation:** Various controls in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] have a rich content model. For example, you can place an image inside of a , which effectively extends the visual tree of the button. However, the added image must not break the hit-testing behavior that causes a button to respond to a of its content, even if the user clicks on pixels that are technically part of the image. +**Control composition and encapsulation:** Various controls in WPF have a rich content model. For example, you can place an image inside of a , which effectively extends the visual tree of the button. However, the added image must not break the hit-testing behavior that causes a button to respond to a of its content, even if the user clicks on pixels that are technically part of the image. -**Singular handler attachment points:** In Windows Forms, you would have to attach the same handler multiple times to process events that could be raised from multiple elements. Routed events enable you to attach that handler only once, as was shown in the previous example, and use handler logic to determine where the event came from if necessary. For instance, this might be the handler for the previously shown [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]: +**Singular handler attachment points:** In Windows Forms, you would have to attach the same handler multiple times to process events that could be raised from multiple elements. Routed events enable you to attach that handler only once, as was shown in the previous example, and use handler logic to determine where the event came from if necessary. For instance, this might be the handler for the previously shown XAML: [!code-csharp[EventOvwSupport#GroupButtonCodeBehind](~/samples/snippets/csharp/VS_Snippets_Wpf/EventOvwSupport/CSharp/default.xaml.cs#groupbuttoncodebehind)] [!code-vb[EventOvwSupport#GroupButtonCodeBehind](~/samples/snippets/visualbasic/VS_Snippets_Wpf/EventOvwSupport/visualbasic/default.xaml.vb#groupbuttoncodebehind)] @@ -71,7 +71,7 @@ The following is a brief summary of the scenarios that motivated the routed even ### How Routed Events Are Implemented -A routed event is a CLR event that is backed by an instance of the class and registered with the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] event system. The instance obtained from registration is typically retained as a `public` `static` `readonly` field member of the class that registers and thus "owns" the routed event. The connection to the identically named CLR event (which is sometimes termed the "wrapper" event) is accomplished by overriding the `add` and `remove` implementations for the CLR event. Ordinarily, the `add` and `remove` are left as an implicit default that uses the appropriate language-specific event syntax for adding and removing handlers of that event. The routed event backing and connection mechanism is conceptually similar to how a dependency property is a CLR property that is backed by the class and registered with the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] property system. +A routed event is a CLR event that is backed by an instance of the class and registered with the WPF event system. The instance obtained from registration is typically retained as a `public` `static` `readonly` field member of the class that registers and thus "owns" the routed event. The connection to the identically named CLR event (which is sometimes termed the "wrapper" event) is accomplished by overriding the `add` and `remove` implementations for the CLR event. Ordinarily, the `add` and `remove` are left as an implicit default that uses the appropriate language-specific event syntax for adding and removing handlers of that event. The routed event backing and connection mechanism is conceptually similar to how a dependency property is a CLR property that is backed by the class and registered with the WPF property system. The following example shows the declaration for a custom `Tap` routed event, including the registration and exposure of the identifier field and the `add` and `remove` implementations for the `Tap` CLR event. @@ -80,11 +80,11 @@ The following example shows the declaration for a custom `Tap` routed event, inc ### Routed Event Handlers and XAML -To add a handler for an event using [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], you declare the event name as an attribute on the element that is an event listener. The value of the attribute is the name of your implemented handler method, which must exist in the partial class of the code-behind file. +To add a handler for an event using XAML, you declare the event name as an attribute on the element that is an event listener. The value of the attribute is the name of your implemented handler method, which must exist in the partial class of the code-behind file. [!code-xaml[EventOvwSupport#SimplestSyntax](~/samples/snippets/csharp/VS_Snippets_Wpf/EventOvwSupport/CSharp/default.xaml#simplestsyntax)] -The [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] syntax for adding standard CLR event handlers is the same for adding routed event handlers, because you are really adding handlers to the CLR event wrapper, which has a routed event implementation underneath. For more information about adding event handlers in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], see [XAML in WPF](xaml-in-wpf.md). +The XAML syntax for adding standard CLR event handlers is the same for adding routed event handlers, because you are really adding handlers to the CLR event wrapper, which has a routed event implementation underneath. For more information about adding event handlers in XAML, see [XAML in WPF](xaml-in-wpf.md). @@ -96,7 +96,7 @@ Routed events use one of three routing strategies: - **Direct:** Only the source element itself is given the opportunity to invoke handlers in response. This is analogous to the "routing" that Windows Forms uses for events. However, unlike a standard CLR event, direct routed events support class handling (class handling is explained in an upcoming section) and can be used by and . -- **Tunneling:** Initially, event handlers at the element tree root are invoked. The routed event then travels a route through successive child elements along the route, towards the node element that is the routed event source (the element that raised the routed event). Tunneling routed events are often used or handled as part of the compositing for a control, such that events from composite parts can be deliberately suppressed or replaced by events that are specific to the complete control. Input events provided in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] often come implemented as a tunneling/bubbling pair. Tunneling events are also sometimes referred to as Preview events, because of a naming convention that is used for the pairs. +- **Tunneling:** Initially, event handlers at the element tree root are invoked. The routed event then travels a route through successive child elements along the route, towards the node element that is the routed event source (the element that raised the routed event). Tunneling routed events are often used or handled as part of the compositing for a control, such that events from composite parts can be deliberately suppressed or replaced by events that are specific to the complete control. Input events provided in WPF often come implemented as a tunneling/bubbling pair. Tunneling events are also sometimes referred to as Preview events, because of a naming convention that is used for the pairs. @@ -110,9 +110,9 @@ Routed event listeners and routed event sources do not need to share a common ev Routed events can also be used to communicate through the element tree, because the event data for the event is perpetuated to each element in the route. One element could change something in the event data, and that change would be available to the next element in the route. -Other than the routing aspect, there are two other reasons that any given [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] event might be implemented as a routed event instead of a standard CLR event. If you are implementing your own events, you might also consider these principles: +Other than the routing aspect, there are two other reasons that any given WPF event might be implemented as a routed event instead of a standard CLR event. If you are implementing your own events, you might also consider these principles: -- Certain [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] styling and templating features such as and require the referenced event to be a routed event. This is the event identifier scenario mentioned earlier. +- Certain WPF styling and templating features such as and require the referenced event to be a routed event. This is the event identifier scenario mentioned earlier. - Routed events support a class handling mechanism whereby the class can specify static methods that have the opportunity to handle routed events before any registered instance handlers can access them. This is very useful in control design, because your class can enforce event-driven class behaviors that cannot be accidentally suppressed by handling an event on an instance. @@ -122,7 +122,7 @@ Each of the above considerations is discussed in a separate section of this topi ## Adding and Implementing an Event Handler for a Routed Event -To add an event handler in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], you simply add the event name to an element as an attribute and set the attribute value as the name of the event handler that implements an appropriate delegate, as in the following example. +To add an event handler in XAML, you simply add the event name to an element as an attribute and set the attribute value as the name of the event handler that implements an appropriate delegate, as in the following example. [!code-xaml[EventOvwSupport#SimplestSyntax](~/samples/snippets/csharp/VS_Snippets_Wpf/EventOvwSupport/CSharp/default.xaml#simplestsyntax)] @@ -133,9 +133,9 @@ To add an event handler in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharpt is the basic routed event handler delegate. For routed events that are specialized for certain controls or scenarios, the delegates to use for the routed event handlers also might become more specialized, so that they can transmit specialized event data. For instance, in a common input scenario, you might handle a routed event. Your handler should implement the delegate. By using the most specific delegate, you can process the in the handler and read the property, which contains the clipboard payload of the drag operation. -For a complete example of how to add an event handler to an element using [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], see [Handle a Routed Event](how-to-handle-a-routed-event.md). +For a complete example of how to add an event handler to an element using XAML, see [Handle a Routed Event](how-to-handle-a-routed-event.md). -Adding a handler for a routed event in an application that is created in code is straightforward. Routed event handlers can always be added through a helper method (which is the same method that the existing backing calls for `add`.) However, existing [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] routed events generally have backing implementations of `add` and `remove` logic that allow the handlers for routed events to be added by a language-specific event syntax, which is more intuitive syntax than the helper method. The following is an example usage of the helper method: +Adding a handler for a routed event in an application that is created in code is straightforward. Routed event handlers can always be added through a helper method (which is the same method that the existing backing calls for `add`.) However, existing WPF routed events generally have backing implementations of `add` and `remove` logic that allow the handlers for routed events to be added by a language-specific event syntax, which is more intuitive syntax than the helper method. The following is an example usage of the helper method: [!code-csharp[EventOvwSupport#AddHandlerCode](~/samples/snippets/csharp/VS_Snippets_Wpf/EventOvwSupport/CSharp/default.xaml.cs#addhandlercode)] [!code-vb[EventOvwSupport#AddHandlerCode](~/samples/snippets/visualbasic/VS_Snippets_Wpf/EventOvwSupport/visualbasic/default.xaml.vb#addhandlercode)] @@ -155,11 +155,11 @@ If you are using Visual Basic, you can also use the `Handles` keyword to add han All routed events share a common event data base class, . defines the property, which takes a Boolean value. The purpose of the property is to enable any event handler along the route to mark the routed event as *handled*, by setting the value of to `true`. After being processed by the handler at one element along the route, the shared event data is again reported to each listener along the route. -The value of affects how a routed event is reported or processed as it travels further along the route. If is `true` in the event data for a routed event, then handlers that listen for that routed event on other elements are generally no longer invoked for that particular event instance. This is true both for handlers attached in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] and for handlers added by language-specific event handler attachment syntaxes such as `+=` or `Handles`. For most common handler scenarios, marking an event as handled by setting to `true` will "stop" routing for either a tunneling route or a bubbling route, and also for any event that is handled at a point in the route by a class handler. +The value of affects how a routed event is reported or processed as it travels further along the route. If is `true` in the event data for a routed event, then handlers that listen for that routed event on other elements are generally no longer invoked for that particular event instance. This is true both for handlers attached in XAML and for handlers added by language-specific event handler attachment syntaxes such as `+=` or `Handles`. For most common handler scenarios, marking an event as handled by setting to `true` will "stop" routing for either a tunneling route or a bubbling route, and also for any event that is handled at a point in the route by a class handler. However, there is a "handledEventsToo" mechanism whereby listeners can still run handlers in response to routed events where is `true` in the event data. In other words, the event route is not truly stopped by marking the event data as handled. You can only use the handledEventsToo mechanism in code, or in an : -- In code, instead of using a language-specific event syntax that works for general CLR events, call the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] method to add your handler. Specify the value of `handledEventsToo` as `true`. +- In code, instead of using a language-specific event syntax that works for general CLR events, call the WPF method to add your handler. Specify the value of `handledEventsToo` as `true`. - In an , set the attribute to be `true`. @@ -187,17 +187,17 @@ In applications, it is quite common to just handle a bubbling routed event on th If you are defining a class that derives in some way from , you can also define and attach a class handler for a routed event that is a declared or inherited event member of your class. Class handlers are invoked before any instance listener handlers that are attached to an instance of that class, whenever a routed event reaches an element instance in its route. -Some [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] controls have inherent class handling for certain routed events. This might give the outward appearance that the routed event is not ever raised, but in reality it is being class handled, and the routed event can potentially still be handled by your instance handlers if you use certain techniques. Also, many base classes and controls expose virtual methods that can be used to override class handling behavior. For more information both on how to work around undesired class handling and on defining your own class handling in a custom class, see [Marking Routed Events as Handled, and Class Handling](marking-routed-events-as-handled-and-class-handling.md). +Some WPF controls have inherent class handling for certain routed events. This might give the outward appearance that the routed event is not ever raised, but in reality it is being class handled, and the routed event can potentially still be handled by your instance handlers if you use certain techniques. Also, many base classes and controls expose virtual methods that can be used to override class handling behavior. For more information both on how to work around undesired class handling and on defining your own class handling in a custom class, see [Marking Routed Events as Handled, and Class Handling](marking-routed-events-as-handled-and-class-handling.md). ## Attached Events in WPF -The [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] language also defines a special type of event called an *attached event*. An attached event enables you to add a handler for a particular event to an arbitrary element. The element handling the event need not define or inherit the attached event, and neither the object potentially raising the event nor the destination handling instance must define or otherwise "own" that event as a class member. +The XAML language also defines a special type of event called an *attached event*. An attached event enables you to add a handler for a particular event to an arbitrary element. The element handling the event need not define or inherit the attached event, and neither the object potentially raising the event nor the destination handling instance must define or otherwise "own" that event as a class member. -The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] input system uses attached events extensively. However, nearly all of these attached events are forwarded through base elements. The input events then appear as equivalent non-attached routed events that are members of the base element class. For instance, the underlying attached event can more easily be handled on any given by using on that rather than dealing with attached event syntax either in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] or code. +The WPF input system uses attached events extensively. However, nearly all of these attached events are forwarded through base elements. The input events then appear as equivalent non-attached routed events that are members of the base element class. For instance, the underlying attached event can more easily be handled on any given by using on that rather than dealing with attached event syntax either in XAML or code. -For more information about attached events in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], see [Attached Events Overview](attached-events-overview.md). +For more information about attached events in WPF, see [Attached Events Overview](attached-events-overview.md). @@ -207,15 +207,15 @@ Another syntax usage that resembles *typename*.*eventname* attached event syntax [!code-xaml[EventOvwSupport#GroupButton](~/samples/snippets/csharp/VS_Snippets_Wpf/EventOvwSupport/CSharp/default.xaml#groupbutton)] -Here, the parent element listener where the handler is added is a . However, it is adding a handler for a routed event that was declared and will be raised by the class ( actually, but available to through inheritance). "owns" the event, but the routed event system permits handlers for any routed event to be attached to any or instance listener that could otherwise attach listeners for a common language runtime (CLR) event. The default xmlns namespace for these qualified event attribute names is typically the default [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] xmlns namespace, but you can also specify prefixed namespaces for custom routed events. For more information about xmlns, see [XAML Namespaces and Namespace Mapping for WPF XAML](xaml-namespaces-and-namespace-mapping-for-wpf-xaml.md). +Here, the parent element listener where the handler is added is a . However, it is adding a handler for a routed event that was declared and will be raised by the class ( actually, but available to through inheritance). "owns" the event, but the routed event system permits handlers for any routed event to be attached to any or instance listener that could otherwise attach listeners for a common language runtime (CLR) event. The default xmlns namespace for these qualified event attribute names is typically the default WPF xmlns namespace, but you can also specify prefixed namespaces for custom routed events. For more information about xmlns, see [XAML Namespaces and Namespace Mapping for WPF XAML](xaml-namespaces-and-namespace-mapping-for-wpf-xaml.md). ## WPF Input Events -One frequent application of routed events within the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] platform is for input events. In [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], tunneling routed events names are prefixed with the word "Preview" by convention. Input events often come in pairs, with one being the bubbling event and the other being the tunneling event. For example, the event and the event have the same signature, with the former being the bubbling input event and the latter being the tunneling input event. Occasionally, input events only have a bubbling version, or perhaps only a direct routed version. In the documentation, routed event topics cross-reference similar routed events with alternative routing strategies if such routed events exist, and sections in the managed reference pages clarify the routing strategy of each routed event. +One frequent application of routed events within the WPF platform is for input events. In WPF, tunneling routed events names are prefixed with the word "Preview" by convention. Input events often come in pairs, with one being the bubbling event and the other being the tunneling event. For example, the event and the event have the same signature, with the former being the bubbling input event and the latter being the tunneling input event. Occasionally, input events only have a bubbling version, or perhaps only a direct routed version. In the documentation, routed event topics cross-reference similar routed events with alternative routing strategies if such routed events exist, and sections in the managed reference pages clarify the routing strategy of each routed event. -[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] input events that come in pairs are implemented so that a single user action from input, such as a mouse button press, will raise both routed events of the pair in sequence. First, the tunneling event is raised and travels its route. Then the bubbling event is raised and travels its route. The two events literally share the same event data instance, because the method call in the implementing class that raises the bubbling event listens for the event data from the tunneling event and reuses it in the new raised event. Listeners with handlers for the tunneling event have the first opportunity to mark the routed event handled (class handlers first, then instance handlers). If an element along the tunneling route marked the routed event as handled, the already-handled event data is sent on for the bubbling event, and typical handlers attached for the equivalent bubbling input events will not be invoked. To outward appearances it will be as if the handled bubbling event has not even been raised. This handling behavior is useful for control compositing, where you might want all hit-test based input events or focus-based input events to be reported by your final control, rather than its composite parts. The final control element is closer to the root in the compositing, and therefore has the opportunity to class handle the tunneling event first and perhaps to "replace" that routed event with a more control-specific event, as part of the code that backs the control class. +WPF input events that come in pairs are implemented so that a single user action from input, such as a mouse button press, will raise both routed events of the pair in sequence. First, the tunneling event is raised and travels its route. Then the bubbling event is raised and travels its route. The two events literally share the same event data instance, because the method call in the implementing class that raises the bubbling event listens for the event data from the tunneling event and reuses it in the new raised event. Listeners with handlers for the tunneling event have the first opportunity to mark the routed event handled (class handlers first, then instance handlers). If an element along the tunneling route marked the routed event as handled, the already-handled event data is sent on for the bubbling event, and typical handlers attached for the equivalent bubbling input events will not be invoked. To outward appearances it will be as if the handled bubbling event has not even been raised. This handling behavior is useful for control compositing, where you might want all hit-test based input events or focus-based input events to be reported by your final control, rather than its composite parts. The final control element is closer to the root in the compositing, and therefore has the opportunity to class handle the tunneling event first and perhaps to "replace" that routed event with a more control-specific event, as part of the code that backs the control class. As an illustration of how input event processing works, consider the following input event example. In the following tree illustration, `leaf element #2` is the source of both a `PreviewMouseDown` and then a `MouseDown` event: @@ -243,7 +243,7 @@ Usually, once the input event is marked state is that input event handlers that are registered to deliberately ignore state of the event data would still be invoked along either route. For more information, see [Preview Events](preview-events.md) or [Marking Routed Events as Handled, and Class Handling](marking-routed-events-as-handled-and-class-handling.md). -The shared event data model between tunneling and bubbling events, and the sequential raising of first tunneling then bubbling events, is not a concept that is generally true for all routed events. That behavior is specifically implemented by how [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] input devices choose to raise and connect the input event pairs. Implementing your own input events is an advanced scenario, but you might choose to follow that model for your own input events also. +The shared event data model between tunneling and bubbling events, and the sequential raising of first tunneling then bubbling events, is not a concept that is generally true for all routed events. That behavior is specifically implemented by how WPF input devices choose to raise and connect the input event pairs. Implementing your own input events is an advanced scenario, but you might choose to follow that model for your own input events also. Certain classes choose to class-handle certain input events, usually with the intent of redefining what a particular user-driven input event means within that control and raising a new event. For more information, see [Marking Routed Events as Handled, and Class Handling](marking-routed-events-as-handled-and-class-handling.md). @@ -253,13 +253,13 @@ For more information on input and how input and events interact in typical appli ## EventSetters and EventTriggers -In styles, you can include some pre-declared [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] event handling syntax in the markup by using an . When the style is applied, the referenced handler is added to the styled instance. You can declare an only for a routed event. The following is an example. Note that the `b1SetColor` method referenced here is in a code-behind file. +In styles, you can include some pre-declared XAML event handling syntax in the markup by using an . When the style is applied, the referenced handler is added to the styled instance. You can declare an only for a routed event. The following is an example. Note that the `b1SetColor` method referenced here is in a code-behind file. [!code-xaml[EventOvwSupport#XAML2](~/samples/snippets/csharp/VS_Snippets_Wpf/EventOvwSupport/CSharp/page2.xaml#xaml2)] The advantage gained here is that the style is likely to contain a great deal of other information that could apply to any button in your application, and having the be part of that style promotes code reuse even at the markup level. Also, an abstracts method names for handlers one step further away from the general application and page markup. -Another specialized syntax that combines the routed event and animation features of [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] is an . As with , only routed events may be used for an . Typically, an is declared as part of a style, but an can also be declared on page-level elements as part of the collection, or in a . An enables you to specify a that runs whenever a routed event reaches an element in its route that declares an for that event. The advantage of an over just handling the event and causing it to start an existing storyboard is that an provides better control over the storyboard and its run-time behavior. For more information, see [Use Event Triggers to Control a Storyboard After It Starts](../graphics-multimedia/how-to-use-event-triggers-to-control-a-storyboard-after-it-starts.md). +Another specialized syntax that combines the routed event and animation features of WPF is an . As with , only routed events may be used for an . Typically, an is declared as part of a style, but an can also be declared on page-level elements as part of the collection, or in a . An enables you to specify a that runs whenever a routed event reaches an element in its route that declares an for that event. The advantage of an over just handling the event and causing it to start an existing storyboard is that an provides better control over the storyboard and its run-time behavior. For more information, see [Use Event Triggers to Control a Storyboard After It Starts](../graphics-multimedia/how-to-use-event-triggers-to-control-a-storyboard-after-it-starts.md). diff --git a/dotnet-desktop-guide/framework/wpf/advanced/safe-constructor-patterns-for-dependencyobjects.md b/dotnet-desktop-guide/framework/wpf/advanced/safe-constructor-patterns-for-dependencyobjects.md index be25417..3a94b2c 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/safe-constructor-patterns-for-dependencyobjects.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/safe-constructor-patterns-for-dependencyobjects.md @@ -12,10 +12,10 @@ Generally, class constructors should not call callbacks such as virtual methods ## Property System Virtual Methods - The following virtual methods or callbacks are potentially called during the computations of the call that sets a dependency property value: , , , . Each of these virtual methods or callbacks serves a particular purpose in expanding the versatility of the [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] property system and dependency properties. For more information on how to use these virtuals to customize property value determination, see [Dependency Property Callbacks and Validation](dependency-property-callbacks-and-validation.md). + The following virtual methods or callbacks are potentially called during the computations of the call that sets a dependency property value: , , , . Each of these virtual methods or callbacks serves a particular purpose in expanding the versatility of the Windows Presentation Foundation (WPF) property system and dependency properties. For more information on how to use these virtuals to customize property value determination, see [Dependency Property Callbacks and Validation](dependency-property-callbacks-and-validation.md). ### FXCop Rule Enforcement vs. Property System Virtuals - If you use the Microsoft tool FXCop as part of your build process, and you either derive from certain [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] framework classes calling the base constructor, or implement your own dependency properties on derived classes, you might encounter a particular FXCop rule violation. The name string for this violation is: + If you use the Microsoft tool FXCop as part of your build process, and you either derive from certain WPF framework classes calling the base constructor, or implement your own dependency properties on derived classes, you might encounter a particular FXCop rule violation. The name string for this violation is: `DoNotCallOverridableMethodsInConstructors` diff --git a/dotnet-desktop-guide/framework/wpf/advanced/sample-opentype-font-pack.md b/dotnet-desktop-guide/framework/wpf/advanced/sample-opentype-font-pack.md index 7391275..d7daed4 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/sample-opentype-font-pack.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/sample-opentype-font-pack.md @@ -8,11 +8,11 @@ helpviewer_keywords: ms.assetid: 56b46fa1-a44e-419b-8f14-25ad51c715c3 --- # Sample OpenType Font Pack -This topic provides an overview of the sample OpenType fonts that are distributed with the Windows SDK. The sample fonts support extended OpenType features that can be used by [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] applications. +This topic provides an overview of the sample OpenType fonts that are distributed with the Windows SDK. The sample fonts support extended OpenType features that can be used by Windows Presentation Foundation (WPF) applications. ## Fonts in the OpenType Font Pack - The Windows SDK provides a set of sample OpenType fonts that you can use in creating [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] applications. The sample fonts are supplied under license from Ascender Corporation. These fonts implement only a subset of the total features defined by the OpenType format. The following table lists the names of the sample OpenType fonts. + The Windows SDK provides a set of sample OpenType fonts that you can use in creating Windows Presentation Foundation (WPF) applications. The sample fonts are supplied under license from Ascender Corporation. These fonts implement only a subset of the total features defined by the OpenType format. The following table lists the names of the sample OpenType fonts. |**Name**|**File**| |--------------|--------------| diff --git a/dotnet-desktop-guide/framework/wpf/advanced/savetohistory-function-wpf-unmanaged-api-reference.md b/dotnet-desktop-guide/framework/wpf/advanced/savetohistory-function-wpf-unmanaged-api-reference.md index 694366e..f7404ab 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/savetohistory-function-wpf-unmanaged-api-reference.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/savetohistory-function-wpf-unmanaged-api-reference.md @@ -38,7 +38,7 @@ HRESULT SaveToHistory( In the .NET Framework 4 and later: PresentationHost_v0400.dll - **.NET Framework Version:** [!INCLUDE[net_current_v30plus](../../../includes/net-current-v30plus-md.md)] + **.NET Framework Version:** Available since 3.0 ## See also diff --git a/dotnet-desktop-guide/framework/wpf/advanced/serialization-limitations-of-xamlwriter-save.md b/dotnet-desktop-guide/framework/wpf/advanced/serialization-limitations-of-xamlwriter-save.md index c9d14ec..9b7dee3 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/serialization-limitations-of-xamlwriter-save.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/serialization-limitations-of-xamlwriter-save.md @@ -8,23 +8,23 @@ helpviewer_keywords: ms.assetid: f86acc91-2b67-4039-8555-505734491d36 --- # Serialization Limitations of XamlWriter.Save -The API can be used to serialize the contents of a [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] application as a [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] file. However, there are some notable limitations in exactly what is serialized. These limitations and some general considerations are documented in this topic. +The API can be used to serialize the contents of a Windows Presentation Foundation (WPF) application as a Extensible Application Markup Language (XAML) file. However, there are some notable limitations in exactly what is serialized. These limitations and some general considerations are documented in this topic. ## Run-Time, Not Design-Time Representation - The basic philosophy of what is serialized by a call to is that the result will be a representation of the object being serialized, at run-time. Many design-time properties of the original [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file may already be optimized or lost by the time that the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] is loaded as in-memory objects, and are not preserved when you call to serialize. The serialized result is an effective representation of the constructed logical tree of the application, but not necessarily of the original [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] that produced it. These issues make it extremely difficult to use the serialization as part of an extensive [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] design surface. + The basic philosophy of what is serialized by a call to is that the result will be a representation of the object being serialized, at run-time. Many design-time properties of the original XAML file may already be optimized or lost by the time that the XAML is loaded as in-memory objects, and are not preserved when you call to serialize. The serialized result is an effective representation of the constructed logical tree of the application, but not necessarily of the original XAML that produced it. These issues make it extremely difficult to use the serialization as part of an extensive XAML design surface. ## Serialization is Self-Contained - The serialized output of is self-contained; everything that is serialized is contained inside a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] single page, with a single root element, and no external references other than URIs. For instance, if your page referenced resources from application resources, these will appear as if they were a component of the page being serialized. + The serialized output of is self-contained; everything that is serialized is contained inside a XAML single page, with a single root element, and no external references other than URIs. For instance, if your page referenced resources from application resources, these will appear as if they were a component of the page being serialized. ## Extension References are Dereferenced - Common references to objects made by various markup extension formats, such as `StaticResource` or `Binding`, will be dereferenced by the serialization process. These were already dereferenced at the time that in-memory objects were created by the application runtime, and the logic does not revisit the original [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] to restore such references to the serialized output. This potentially freezes any databound or resource obtained value to be the value last used by the run-time representation, with only limited or indirect ability to distinguish such a value from any other value set locally. Images are also serialized as object references to images as they exist in the project, rather than as original source references, losing whatever filename or URI was originally referenced. Even resources declared within the same page are seen serialized into the point where they were referenced, rather than being preserved as a key of a resource collection. + Common references to objects made by various markup extension formats, such as `StaticResource` or `Binding`, will be dereferenced by the serialization process. These were already dereferenced at the time that in-memory objects were created by the application runtime, and the logic does not revisit the original XAML to restore such references to the serialized output. This potentially freezes any databound or resource obtained value to be the value last used by the run-time representation, with only limited or indirect ability to distinguish such a value from any other value set locally. Images are also serialized as object references to images as they exist in the project, rather than as original source references, losing whatever filename or URI was originally referenced. Even resources declared within the same page are seen serialized into the point where they were referenced, rather than being preserved as a key of a resource collection. ## Event Handling is Not Preserved - When event handlers that are added through [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] are serialized, they are not preserved. [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] without code-behind (and also without the related x:Code mechanism) has no way of serializing runtime procedural logic. Because serialization is self-contained and limited to the logical tree, there is no facility for storing the event handlers. As a result, event handler attributes, both the attribute itself and the string value that names the handler, are removed from the output [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]. + When event handlers that are added through XAML are serialized, they are not preserved. XAML without code-behind (and also without the related x:Code mechanism) has no way of serializing runtime procedural logic. Because serialization is self-contained and limited to the logical tree, there is no facility for storing the event handlers. As a result, event handler attributes, both the attribute itself and the string value that names the handler, are removed from the output XAML. ## Realistic Scenarios for Use of XAMLWriter.Save @@ -34,4 +34,4 @@ The API can be used to serialize - Rich text and flow documents: Text and all element formatting and element containment within it is preserved in the output. This can be useful for mechanisms that approximate a clipboard functionality. -- Preserving business object data: If you have stored data in custom elements, such as XML data, so long as your business objects follow basic [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] rules such as providing custom constructors and conversion for by-reference property values, these business objects can be perpetuated through serialization. +- Preserving business object data: If you have stored data in custom elements, such as XML data, so long as your business objects follow basic XAML rules such as providing custom constructors and conversion for by-reference property values, these business objects can be perpetuated through serialization. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/setfakeactivewindow-function-wpf-unmanaged-api-reference.md b/dotnet-desktop-guide/framework/wpf/advanced/setfakeactivewindow-function-wpf-unmanaged-api-reference.md index cf07865..5480891 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/setfakeactivewindow-function-wpf-unmanaged-api-reference.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/setfakeactivewindow-function-wpf-unmanaged-api-reference.md @@ -32,7 +32,7 @@ void __stdcall SetFakeActiveWindow( **DLL:** PresentationHost_v0400.dll - **.NET Framework Version:** [!INCLUDE[net_current_v40plus](../../../includes/net-current-v40plus-md.md)] + **.NET Framework Version:** Available since 4 ## See also diff --git a/dotnet-desktop-guide/framework/wpf/advanced/sharing-message-loops-between-win32-and-wpf.md b/dotnet-desktop-guide/framework/wpf/advanced/sharing-message-loops-between-win32-and-wpf.md index 7e11308..28f181a 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/sharing-message-loops-between-win32-and-wpf.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/sharing-message-loops-between-win32-and-wpf.md @@ -10,10 +10,10 @@ helpviewer_keywords: ms.assetid: 39ee888c-e5ec-41c8-b11f-7b851a554442 --- # Sharing Message Loops Between Win32 and WPF -This topic describes how to implement a message loop for interoperation with [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)], either by using existing message loop exposure in or by creating a separate message loop on the Win32 side of your interoperation code. +This topic describes how to implement a message loop for interoperation with Windows Presentation Foundation (WPF), either by using existing message loop exposure in or by creating a separate message loop on the Win32 side of your interoperation code. ## ComponentDispatcher and the Message Loop - A normal scenario for interoperation and keyboard event support is to implement , or to subclass from classes that already implement , such as or . However, keyboard sink support does not address all possible message loop needs you might have when sending and receiving messages across your interoperation boundaries. To help formalize an application message loop architecture, [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides the class, which defines a simple protocol for a message loop to follow. + A normal scenario for interoperation and keyboard event support is to implement , or to subclass from classes that already implement , such as or . However, keyboard sink support does not address all possible message loop needs you might have when sending and receiving messages across your interoperation boundaries. To help formalize an application message loop architecture, Windows Presentation Foundation (WPF) provides the class, which defines a simple protocol for a message loop to follow. is a static class that exposes several members. The scope of each method is implicitly tied to the calling thread. A message loop must call some of those APIs at critical times (as defined in the next section). @@ -33,7 +33,7 @@ This topic describes how to implement a message loop for interoperation with [!I - : your message loop should call this to indicate that a new message is available. The return value indicates whether a listener to a event handled the message. If returns `true` (handled), the dispatcher should do nothing further with the message. If the return value is `false`, the dispatcher is expected to call the Win32 function `TranslateMessage`, then call `DispatchMessage`. ## Using ComponentDispatcher and Existing Message Handling - The following is a checklist of members you will use if you rely on the inherent [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] message loop. + The following is a checklist of members you will use if you rely on the inherent WPF message loop. - : returns whether the application has gone modal (e.g., a modal message loop has been pushed). can track this state because the class maintains a count of and calls from the message loop. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/staticresource-markup-extension.md b/dotnet-desktop-guide/framework/wpf/advanced/staticresource-markup-extension.md index 26830dc..1935c88 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/staticresource-markup-extension.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/staticresource-markup-extension.md @@ -12,7 +12,7 @@ helpviewer_keywords: ms.assetid: 97af044c-71f1-4617-9a94-9064b68185d2 --- # StaticResource Markup Extension -Provides a value for any [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] property attribute by looking up a reference to an already defined resource. Lookup behavior for that resource is analogous to load-time lookup, which will look for resources that were previously loaded from the markup of the current [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] page as well as other application sources, and will generate that resource value as the property value in the run-time objects. +Provides a value for any XAML property attribute by looking up a reference to an already defined resource. Lookup behavior for that resource is analogous to load-time lookup, which will look for resources that were previously loaded from the markup of the current XAML page as well as other application sources, and will generate that resource value as the property value in the run-time objects. ## XAML Attribute Usage @@ -39,7 +39,7 @@ Provides a value for any [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla ## Remarks > [!IMPORTANT] -> A `StaticResource` must not attempt to make a forward reference to a resource that is defined lexically further within the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file. Attempting to do so is not supported, and even if such a reference does not fail, attempting the forward reference will incur a load time performance penalty when the internal hash tables representing a are searched. For best results, adjust the composition of your resource dictionaries such that forward references can be avoided. If you cannot avoid a forward reference, use [DynamicResource Markup Extension](dynamicresource-markup-extension.md) instead. +> A `StaticResource` must not attempt to make a forward reference to a resource that is defined lexically further within the XAML file. Attempting to do so is not supported, and even if such a reference does not fail, attempting the forward reference will incur a load time performance penalty when the internal hash tables representing a are searched. For best results, adjust the composition of your resource dictionaries such that forward references can be avoided. If you cannot avoid a forward reference, use [DynamicResource Markup Extension](dynamicresource-markup-extension.md) instead. The specified should correspond to an existing resource, identified with an [x:Key Directive](/dotnet/desktop/xaml-services/xkey-directive) at some level in your page, application, the available control themes and external resources, or system resources. The resource lookup occurs in that order. For more information about resource lookup behavior for static and dynamic resources, see [XAML Resources](/dotnet/desktop-wpf/fundamentals/xaml-resources-define). @@ -59,9 +59,9 @@ Provides a value for any [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla The verbose usage is often useful for extensions that have more than one settable property, or if some properties are optional. Because `StaticResource` has only one settable property, which is required, this verbose usage is not typical. - In the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor implementation, the handling for this markup extension is defined by the class. + In the WPF XAML processor implementation, the handling for this markup extension is defined by the class. - `StaticResource` is a markup extension. Markup extensions are typically implemented when there is a requirement to escape attribute values to be other than literal values or handler names, and the requirement is more global than just putting type converters on certain types or properties. All markup extensions in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] use the { and } characters in their attribute syntax, which is the convention by which a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor recognizes that a markup extension must process the attribute. For more information, see [Markup Extensions and WPF XAML](markup-extensions-and-wpf-xaml.md). + `StaticResource` is a markup extension. Markup extensions are typically implemented when there is a requirement to escape attribute values to be other than literal values or handler names, and the requirement is more global than just putting type converters on certain types or properties. All markup extensions in XAML use the { and } characters in their attribute syntax, which is the convention by which a XAML processor recognizes that a markup extension must process the attribute. For more information, see [Markup Extensions and WPF XAML](markup-extensions-and-wpf-xaml.md). ## See also diff --git a/dotnet-desktop-guide/framework/wpf/advanced/storing-ink.md b/dotnet-desktop-guide/framework/wpf/advanced/storing-ink.md index 3b2eea5..cdd58a0 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/storing-ink.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/storing-ink.md @@ -16,7 +16,7 @@ ms.assetid: a3f6d16b-d682-4680-9965-907332b4d2b8 The methods provide support for storing ink as Ink Serialized Format (ISF). Constructors for the class provide support for reading ink data. ## Ink Storage and Retrieval - This section discusses how to store and retrieve ink in the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] platform. + This section discusses how to store and retrieve ink in the WPF platform. The following example implements a button-click event handler that presents the user with a File Save dialog box and saves the ink from an out to a file. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/styling-for-focus-in-controls-and-focusvisualstyle.md b/dotnet-desktop-guide/framework/wpf/advanced/styling-for-focus-in-controls-and-focusvisualstyle.md index eefb4b0..b938f94 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/styling-for-focus-in-controls-and-focusvisualstyle.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/styling-for-focus-in-controls-and-focusvisualstyle.md @@ -8,7 +8,7 @@ helpviewer_keywords: ms.assetid: 786ac576-011b-4d72-913b-558deccb9b35 --- # Styling for Focus in Controls, and FocusVisualStyle -[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides two parallel mechanisms for changing the visual appearance of a control when it receives keyboard focus. The first mechanism is to use property setters for properties such as within the style or template that is applied to the control. The second mechanism is to provide a separate style as the value of the property; the "focus visual style" creates a separate visual tree for an adorner that draws on top of the control, rather than changing the visual tree of the control or other UI element by replacing it. This topic discusses the scenarios where each of these mechanisms is appropriate. +Windows Presentation Foundation (WPF) provides two parallel mechanisms for changing the visual appearance of a control when it receives keyboard focus. The first mechanism is to use property setters for properties such as within the style or template that is applied to the control. The second mechanism is to provide a separate style as the value of the property; the "focus visual style" creates a separate visual tree for an adorner that draws on top of the control, rather than changing the visual tree of the control or other UI element by replacing it. This topic discusses the scenarios where each of these mechanisms is appropriate. ## The Purpose of Focus Visual Style diff --git a/dotnet-desktop-guide/framework/wpf/advanced/table-overview.md b/dotnet-desktop-guide/framework/wpf/advanced/table-overview.md index 905f3d1..ba0b3b6 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/table-overview.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/table-overview.md @@ -134,7 +134,7 @@ ms.assetid: 5e1105f4-8fc4-473a-ba55-88c8e71386e6 ## Building a Table With Code - The following examples show how to programmatically create a and populate it with content. The contents of the table are apportioned into five rows (represented by objects contained in a object) and six columns (represented by objects). The rows are used for different presentation purposes, including a title row intended to title the entire table, a header row to describe the columns of data in the table, and a footer row with summary information. Note that the notion of "title", "header", and "footer" rows are not inherent to the table; these are simply rows with different characteristics. Table cells contain the actual content, which can be comprised of text, images, or nearly any other [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] element. + The following examples show how to programmatically create a and populate it with content. The contents of the table are apportioned into five rows (represented by objects contained in a object) and six columns (represented by objects). The rows are used for different presentation purposes, including a title row intended to title the entire table, a header row to describe the columns of data in the table, and a footer row with summary information. Note that the notion of "title", "header", and "footer" rows are not inherent to the table; these are simply rows with different characteristics. Table cells contain the actual content, which can be comprised of text, images, or nearly any other user interface (UI) element. First, a is created to host the , and a new is created and added to the contents of the . diff --git a/dotnet-desktop-guide/framework/wpf/advanced/technology-regions-overview.md b/dotnet-desktop-guide/framework/wpf/advanced/technology-regions-overview.md index 8d07938..857e101 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/technology-regions-overview.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/technology-regions-overview.md @@ -14,10 +14,10 @@ ms.assetid: b7cc350f-b9e2-48b1-be14-60f3d853222e If multiple presentation technologies are used in an application, such as WPF, Win32, or DirectX, they must share the rendering areas within a common top-level window. This topic describes issues that might influence the presentation and input for your WPF interoperation application. ## Regions - Within a top-level window, you can conceptualize that each HWND that comprises one of the technologies of an interoperation application has its own region (also called "airspace"). Each pixel within the window belongs to exactly one HWND, which constitutes the region of that HWND. (Strictly speaking, there is more than one [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] region if there is more than one [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] HWND, but for purposes of this discussion, you can assume there is only one). The region implies that all layers or other windows that attempt to render above that pixel during application lifetime must be part of the same render-level technology. Attempting to render [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] pixels over Win32 leads to undesirable results, and is disallowed as much as possible through the interoperation APIs. + Within a top-level window, you can conceptualize that each HWND that comprises one of the technologies of an interoperation application has its own region (also called "airspace"). Each pixel within the window belongs to exactly one HWND, which constitutes the region of that HWND. (Strictly speaking, there is more than one WPF region if there is more than one WPF HWND, but for purposes of this discussion, you can assume there is only one). The region implies that all layers or other windows that attempt to render above that pixel during application lifetime must be part of the same render-level technology. Attempting to render WPF pixels over Win32 leads to undesirable results, and is disallowed as much as possible through the interoperation APIs. ### Region Examples - The following illustration shows an application that mixes Win32, DirectX, and [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. Each technology uses its own separate, non-overlapping set of pixels, and there are no region issues. + The following illustration shows an application that mixes Win32, DirectX, and WPF. Each technology uses its own separate, non-overlapping set of pixels, and there are no region issues. ![An example of an application that mixes Win32, DirectX, and WPF.](./media/technology-regions-overview/win32-directx-windows-presentation-foundation-application.png) @@ -25,11 +25,11 @@ If multiple presentation technologies are used in an application, such as WPF, W ![An attempt to render a WPF circle over a Win32 region.](./media/technology-regions-overview/render-windows-presentation-foundation-circle-over-win32-region.png) - Another violation is if you try to use transparency/alpha blending between different technologies. In the following illustration, the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] box violates the Win32 and DirectX regions. Because pixels in that [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] box are semi-transparent, they would have to be owned jointly by both DirectX and [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], which is not possible. So this is another violation and cannot be built. + Another violation is if you try to use transparency/alpha blending between different technologies. In the following illustration, the WPF box violates the Win32 and DirectX regions. Because pixels in that WPF box are semi-transparent, they would have to be owned jointly by both DirectX and WPF, which is not possible. So this is another violation and cannot be built. ![Diagram showing a WPF box violating the Win32 and DirectX regions.](./media/technology-regions-overview/windows-foundation-presentation-box-violate-win32-directx-region.png) - The previous three examples used rectangular regions, but different shapes are possible. For example, a region can have a hole. The following illustration shows a Win32 region with a rectangular hole this is the size of the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] and DirectX regions combined. + The previous three examples used rectangular regions, but different shapes are possible. For example, a region can have a hole. The following illustration shows a Win32 region with a rectangular hole this is the size of the WPF and DirectX regions combined. ![Diagram that shows a Win32 region with a rectangular hole.](./media/technology-regions-overview/win32-region-rectangular-hole.png) @@ -38,19 +38,19 @@ If multiple presentation technologies are used in an application, such as WPF, W ![Diagram that shows a nonrectangular region.](./media/technology-regions-overview/nonrectangular-win32-region.png) ## Transparency and Top-Level Windows - The window manager in Windows only really processes Win32 HWNDs. Therefore, every [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] is an HWND. The HWND must abide by the general rules for any HWND. Within that HWND, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] code can do whatever the overall [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] APIs support. But for interactions with other HWNDs on the desktop, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] must abide by Win32 processing and rendering rules. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] supports non-rectangular windows by using Win32 APIs—HRGNs for non-rectangular windows, and layered windows for a per-pixel alpha. + The window manager in Windows only really processes Win32 HWNDs. Therefore, every WPF is an HWND. The HWND must abide by the general rules for any HWND. Within that HWND, WPF code can do whatever the overall WPF APIs support. But for interactions with other HWNDs on the desktop, WPF must abide by Win32 processing and rendering rules. WPF supports non-rectangular windows by using Win32 APIs—HRGNs for non-rectangular windows, and layered windows for a per-pixel alpha. Constant alpha and color keys are not supported. Win32 layered window capabilities vary by platform. Layered windows can make the entire window translucent (semi-transparent) by specifying an alpha value to apply to every pixel in the window. (Win32 in fact supports per-pixel alpha, but this is very difficult to use in practical programs because in this mode you would need to draw any child HWND yourself, including dialogs and dropdowns). - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] supports HRGNs; however, there are no managed APIs for this functionality. You can use platform invoke and to call the relevant Win32 APIs. For more information, see [Calling Native Functions from Managed Code](/cpp/dotnet/calling-native-functions-from-managed-code). + WPF supports HRGNs; however, there are no managed APIs for this functionality. You can use platform invoke and to call the relevant Win32 APIs. For more information, see [Calling Native Functions from Managed Code](/cpp/dotnet/calling-native-functions-from-managed-code). - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] layered windows have different capabilities on different operating systems. This is because [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] uses DirectX to render, and layered windows were primarily designed for GDI rendering, not DirectX rendering. + WPF layered windows have different capabilities on different operating systems. This is because WPF uses DirectX to render, and layered windows were primarily designed for GDI rendering, not DirectX rendering. - WPF supports hardware accelerated layered windows. -- [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] does not support transparency color keys, because [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] cannot guarantee to render the exact color you requested, particularly when rendering is hardware-accelerated. +- WPF does not support transparency color keys, because WPF cannot guarantee to render the exact color you requested, particularly when rendering is hardware-accelerated. ## See also diff --git a/dotnet-desktop-guide/framework/wpf/advanced/templatebinding-markup-extension.md b/dotnet-desktop-guide/framework/wpf/advanced/templatebinding-markup-extension.md index d765b41..c5584c4 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/templatebinding-markup-extension.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/templatebinding-markup-extension.md @@ -53,7 +53,7 @@ Links the value of a property in a control template to be the value of another p The verbose usage is often useful for extensions that have more than one settable property, or if some properties are optional. Because `TemplateBinding` has only one settable property, which is required, this verbose usage is not typical. - In the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] XAML processor implementation, the handling for this markup extension is defined by the class. + In the WPF XAML processor implementation, the handling for this markup extension is defined by the class. `TemplateBinding` is a markup extension. Markup extensions are typically implemented when there is a requirement to escape attribute values to be other than literal values or handler names, and the requirement is more global than just putting type converters on certain types or properties. All markup extensions in XAML use the `{` and `}` characters in their attribute syntax, which is the convention by which a XAML processor recognizes that a markup extension must process the attribute. For more information, see [Markup Extensions and WPF XAML](markup-extensions-and-wpf-xaml.md). diff --git a/dotnet-desktop-guide/framework/wpf/advanced/the-ink-object-model-windows-forms-and-com-versus-wpf.md b/dotnet-desktop-guide/framework/wpf/advanced/the-ink-object-model-windows-forms-and-com-versus-wpf.md index 4ea5850..7b6030a 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/the-ink-object-model-windows-forms-and-com-versus-wpf.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/the-ink-object-model-windows-forms-and-com-versus-wpf.md @@ -41,7 +41,7 @@ There are essentially three platforms that support digital ink: the Tablet PC Wi ![Diagram of the Ink Object Model for COM/Winforms.](./media/ink-inkownsstrokes.png "Ink_InkOwnsStrokes") - On the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], each is a common language runtime object that exists as long as something has a reference to it. Each references a and object, which are also common language runtime objects. + On the WPF, each is a common language runtime object that exists as long as something has a reference to it. Each references a and object, which are also common language runtime objects. ![Diagram of the Ink Object Model for WPF.](./media/ink-wpfinkobjectmodel.png "Ink_WPFInkObjectModel") diff --git a/dotnet-desktop-guide/framework/wpf/advanced/the-ink-threading-model.md b/dotnet-desktop-guide/framework/wpf/advanced/the-ink-threading-model.md index 75f0bc1..99aab3b 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/the-ink-threading-model.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/the-ink-threading-model.md @@ -15,7 +15,7 @@ helpviewer_keywords: ms.assetid: c85fcad1-cb50-4431-847c-ac4145a35c89 --- # The Ink Threading Model -One of the benefits of ink on a Tablet PC is that it feels a lot like writing with a regular pen and paper. To accomplish this, the tablet pen collects input data at a much higher rate than a mouse does and renders the ink as the user writes. The application's user interface (UI) thread is not sufficient for collecting pen data and rendering ink, because it can become blocked. To solve this, a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application uses two additional threads when a user writes ink. +One of the benefits of ink on a Tablet PC is that it feels a lot like writing with a regular pen and paper. To accomplish this, the tablet pen collects input data at a much higher rate than a mouse does and renders the ink as the user writes. The application's user interface (UI) thread is not sufficient for collecting pen data and rendering ink, because it can become blocked. To solve this, a WPF application uses two additional threads when a user writes ink. The following list describes the threads that take part in collecting and rendering digital ink: diff --git a/dotnet-desktop-guide/framework/wpf/advanced/themedictionary-markup-extension.md b/dotnet-desktop-guide/framework/wpf/advanced/themedictionary-markup-extension.md index ddb00c2..379db9f 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/themedictionary-markup-extension.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/themedictionary-markup-extension.md @@ -55,9 +55,9 @@ Provides a way for custom control authors or applications that integrate third-p The verbose usage is often useful for extensions that have more than one settable property, or if some properties are optional. Because `ThemeDictionary` has only one settable property, which is required, this verbose usage is not typical. - In the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor implementation, the handling for this markup extension is defined by the class. + In the WPF XAML processor implementation, the handling for this markup extension is defined by the class. - `ThemeDictionary` is a markup extension. Markup extensions are typically implemented when there is a requirement to escape attribute values to be other than literal values or handler names, and the requirement is more global than just putting type converters on certain types or properties. All markup extensions in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] use the { and } characters in their attribute syntax, which is the convention by which a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor recognizes that a markup extension must process the attribute. For more information, see [Markup Extensions and WPF XAML](markup-extensions-and-wpf-xaml.md). + `ThemeDictionary` is a markup extension. Markup extensions are typically implemented when there is a requirement to escape attribute values to be other than literal values or handler names, and the requirement is more global than just putting type converters on certain types or properties. All markup extensions in XAML use the { and } characters in their attribute syntax, which is the convention by which a XAML processor recognizes that a markup extension must process the attribute. For more information, see [Markup Extensions and WPF XAML](markup-extensions-and-wpf-xaml.md). ## See also diff --git a/dotnet-desktop-guide/framework/wpf/advanced/threading-model.md b/dotnet-desktop-guide/framework/wpf/advanced/threading-model.md index 6b2b655..7977069 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/threading-model.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/threading-model.md @@ -22,28 +22,28 @@ helpviewer_keywords: ms.assetid: 02d8fd00-8d7c-4604-874c-58e40786770b --- # Threading Model -[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] is designed to save developers from the difficulties of threading. As a result, the majority of [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] developers won't have to write an interface that uses more than one thread. Because multithreaded programs are complex and difficult to debug, they should be avoided when single-threaded solutions exist. +WPF developers won't have to write an interface that uses more than one thread. Because multithreaded programs are complex and difficult to debug, they should be avoided when single-threaded solutions exist. - No matter how well architected, however, no [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] framework will ever be able to provide a single-threaded solution for every sort of problem. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] comes close, but there are still situations where multiple threads improve [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] responsiveness or application performance. After discussing some background material, this paper explores some of these situations and then concludes with a discussion of some lower-level details. + No matter how well architected, however, no UI framework will ever be able to provide a single-threaded solution for every sort of problem. WPF comes close, but there are still situations where multiple threads improve user interface (UI) responsiveness or application performance. After discussing some background material, this paper explores some of these situations and then concludes with a discussion of some lower-level details. > [!NOTE] > This topic discusses threading by using the method for asynchronous calls. You can also make asynchronous calls by calling the method, which take an or as a parameter. The method returns a or , which has a property. You can use the `await` keyword with either the or the associated . If you need to wait synchronously for the that is returned by a or , call the extension method. Calling will result in a deadlock. For more information about using a to perform asynchronous operations, see [Task-based asynchronous programming](/dotnet/standard/parallel-programming/task-based-asynchronous-programming). The method also has overloads that take an or as a parameter. You can use the method to make synchronous calls by passing in a delegate, or . ## Overview and the Dispatcher - Typically, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications start with two threads: one for handling rendering and another for managing the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)]. The rendering thread effectively runs hidden in the background while the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] thread receives input, handles events, paints the screen, and runs application code. Most applications use a single [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] thread, although in some situations it is best to use several. We’ll discuss this with an example later. + Typically, UI. The rendering thread effectively runs hidden in the background while the UI thread receives input, handles events, paints the screen, and runs application code. Most applications use a single UI thread, although in some situations it is best to use several. We’ll discuss this with an example later. - The [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] thread queues work items inside an object called a . The selects work items on a priority basis and runs each one to completion. Every [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] thread must have at least one , and each can execute work items in exactly one thread. + The UI thread queues work items inside an object called a . The selects work items on a priority basis and runs each one to completion. Every UI thread must have at least one , and each can execute work items in exactly one thread. The trick to building responsive, user-friendly applications is to maximize the throughput by keeping the work items small. This way items never get stale sitting in the queue waiting for processing. Any perceivable delay between input and response can frustrate a user. - How then are [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications supposed to handle big operations? What if your code involves a large calculation or needs to query a database on some remote server? Usually, the answer is to handle the big operation in a separate thread, leaving the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] thread free to tend to items in the queue. When the big operation is complete, it can report its result back to the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] thread for display. + How then are UI thread free to tend to items in the queue. When the big operation is complete, it can report its result back to the UI thread for display. - Historically, Windows allows [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] elements to be accessed only by the thread that created them. This means that a background thread in charge of some long-running task cannot update a text box when it is finished. Windows does this to ensure the integrity of [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] components. A list box could look strange if its contents were updated by a background thread during painting. + Historically, Windows allows UI elements to be accessed only by the thread that created them. This means that a background thread in charge of some long-running task cannot update a text box when it is finished. Windows does this to ensure the integrity of UI components. A list box could look strange if its contents were updated by a background thread during painting. - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] has a built-in mutual exclusion mechanism that enforces this coordination. Most classes in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] derive from . At construction, a stores a reference to the linked to the currently running thread. In effect, the associates with the thread that creates it. During program execution, a can call its public method. examines the associated with the current thread and compares it to the reference stored during construction. If they don’t match, throws an exception. is intended to be called at the beginning of every method belonging to a . + WPF has a built-in mutual exclusion mechanism that enforces this coordination. Most classes in WPF derive from . At construction, a stores a reference to the linked to the currently running thread. In effect, the associates with the thread that creates it. During program execution, a can call its public method. examines the associated with the current thread and compares it to the reference stored during construction. If they don’t match, throws an exception. is intended to be called at the beginning of every method belonging to a . - If only one thread can modify the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)], how do background threads interact with the user? A background thread can ask the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] thread to perform an operation on its behalf. It does this by registering a work item with the of the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] thread. The class provides two methods for registering work items: and . Both methods schedule a delegate for execution. is a synchronous call – that is, it doesn’t return until the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] thread actually finishes executing the delegate. is asynchronous and returns immediately. + If only one thread can modify the UI, how do background threads interact with the user? A background thread can ask the UI thread to perform an operation on its behalf. It does this by registering a work item with the of the UI thread. The class provides two methods for registering work items: and . Both methods schedule a delegate for execution. is a synchronous call – that is, it doesn’t return until the UI thread actually finishes executing the delegate. is asynchronous and returns immediately. The orders the elements in its queue by priority. There are ten levels that may be specified when adding an element to the queue. These priorities are maintained in the enumeration. Detailed information about levels can be found in the Windows SDK documentation. @@ -52,7 +52,7 @@ ms.assetid: 02d8fd00-8d7c-4604-874c-58e40786770b ### A Single-Threaded Application with a Long-Running Calculation - Most graphical user interfaces (GUIs) spend a large portion of their time idle while waiting for events that are generated in response to user interactions. With careful programming this idle time can be used constructively, without affecting the responsiveness of the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)]. The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] threading model doesn’t allow input to interrupt an operation happening in the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] thread. This means you must be sure to return to the periodically to process pending input events before they get stale. + Most graphical user interfaces (GUIs) spend a large portion of their time idle while waiting for events that are generated in response to user interactions. With careful programming this idle time can be used constructively, without affecting the responsiveness of the UI. The UI thread. This means you must be sure to return to the periodically to process pending input events before they get stale. Consider the following example: @@ -60,17 +60,17 @@ ms.assetid: 02d8fd00-8d7c-4604-874c-58e40786770b This simple application counts upwards from three, searching for prime numbers. When the user clicks the **Start** button, the search begins. When the program finds a prime, it updates the user interface with its discovery. At any point, the user can stop the search. - Although simple enough, the prime number search could go on forever, which presents some difficulties. If we handled the entire search inside of the click event handler of the button, we would never give the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] thread a chance to handle other events. The [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] would be unable to respond to input or process messages. It would never repaint and never respond to button clicks. + Although simple enough, the prime number search could go on forever, which presents some difficulties. If we handled the entire search inside of the click event handler of the button, we would never give the UI thread a chance to handle other events. The UI would be unable to respond to input or process messages. It would never repaint and never respond to button clicks. We could conduct the prime number search in a separate thread, but then we would need to deal with synchronization issues. With a single-threaded approach, we can directly update the label that lists the largest prime found. - If we break up the task of calculation into manageable chunks, we can periodically return to the and process events. We can give [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] an opportunity to repaint and process input. + If we break up the task of calculation into manageable chunks, we can periodically return to the and process events. We can give WPF an opportunity to repaint and process input. - The best way to split processing time between calculation and event handling is to manage calculation from the . By using the method, we can schedule prime number checks in the same queue that [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] events are drawn from. In our example, we schedule only a single prime number check at a time. After the prime number check is complete, we schedule the next check immediately. This check proceeds only after pending [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] events have been handled. + The best way to split processing time between calculation and event handling is to manage calculation from the . By using the method, we can schedule prime number checks in the same queue that UI events are drawn from. In our example, we schedule only a single prime number check at a time. After the prime number check is complete, we schedule the next check immediately. This check proceeds only after pending UI events have been handled. ![Screenshot that shows the dispatcher queue.](./media/threading-model/threading-dispatcher-queue.png) - Microsoft Word accomplishes spell checking using this mechanism. Spell checking is done in the background using the idle time of the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] thread. Let's take a look at the code. + Microsoft Word accomplishes spell checking using this mechanism. Spell checking is done in the background using the idle time of the UI thread. Let's take a look at the code. The following example shows the XAML that creates the user interface. @@ -88,20 +88,20 @@ ms.assetid: 02d8fd00-8d7c-4604-874c-58e40786770b Besides updating the text on the , this handler is responsible for scheduling the first prime number check by adding a delegate to the queue. Sometime after this event handler has completed its work, the will select this delegate for execution. - As we mentioned earlier, is the member used to schedule a delegate for execution. In this case, we choose the priority. The will execute this delegate only when there are no important events to process. [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] responsiveness is more important than number checking. We also pass a new delegate representing the number-checking routine. + As we mentioned earlier, is the member used to schedule a delegate for execution. In this case, we choose the priority. The will execute this delegate only when there are no important events to process. UI responsiveness is more important than number checking. We also pass a new delegate representing the number-checking routine. [!code-csharp[ThreadingPrimeNumbers#ThreadingPrimeNumberCheckNextNumber](~/samples/snippets/csharp/VS_Snippets_Wpf/ThreadingPrimeNumbers/CSharp/Window1.xaml.cs#threadingprimenumberchecknextnumber)] [!code-vb[ThreadingPrimeNumbers#ThreadingPrimeNumberCheckNextNumber](~/samples/snippets/visualbasic/VS_Snippets_Wpf/ThreadingPrimeNumbers/visualbasic/mainwindow.xaml.vb#threadingprimenumberchecknextnumber)] - This method checks if the next odd number is prime. If it is prime, the method directly updates the `bigPrime` to reflect its discovery. We can do this because the calculation is occurring in the same thread that was used to create the component. Had we chosen to use a separate thread for the calculation, we would have to use a more complicated synchronization mechanism and execute the update in the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] thread. We’ll demonstrate this situation next. + This method checks if the next odd number is prime. If it is prime, the method directly updates the `bigPrime` to reflect its discovery. We can do this because the calculation is occurring in the same thread that was used to create the component. Had we chosen to use a separate thread for the calculation, we would have to use a more complicated synchronization mechanism and execute the update in the UI thread. We’ll demonstrate this situation next. For the complete source code for this sample, see the [Single-Threaded Application with Long-Running Calculation Sample](https://github.com/Microsoft/WPF-Samples/tree/master/Threading/SingleThreadedApplication) ### Handling a Blocking Operation with a Background Thread - Handling blocking operations in a graphical application can be difficult. We don’t want to call blocking methods from event handlers because the application will appear to freeze up. We can use a separate thread to handle these operations, but when we’re done, we have to synchronize with the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] thread because we can’t directly modify the GUI from our worker thread. We can use or to insert delegates into the of the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] thread. Eventually, these delegates will be executed with permission to modify [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] elements. + Handling blocking operations in a graphical application can be difficult. We don’t want to call blocking methods from event handlers because the application will appear to freeze up. We can use a separate thread to handle these operations, but when we’re done, we have to synchronize with the UI thread because we can’t directly modify the GUI from our worker thread. We can use or to insert delegates into the of the UI thread. Eventually, these delegates will be executed with permission to modify UI elements. - In this example, we mimic a remote procedure call that retrieves a weather forecast. We use a separate worker thread to execute this call, and we schedule an update method in the of the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] thread when we’re finished. + In this example, we mimic a remote procedure call that retrieves a weather forecast. We use a separate worker thread to execute this call, and we schedule an update method in the of the UI thread when we’re finished. ![Screenshot that shows the weather UI.](./media/threading-model/threading-weather-ui.png) @@ -122,24 +122,24 @@ ms.assetid: 02d8fd00-8d7c-4604-874c-58e40786770b [!code-csharp[ThreadingWeatherForecast#ThreadingWeatherFetchWeather](~/samples/snippets/csharp/VS_Snippets_Wpf/ThreadingWeatherForecast/CSharp/Window1.xaml.cs#threadingweatherfetchweather)] [!code-vb[ThreadingWeatherForecast#ThreadingWeatherFetchWeather](~/samples/snippets/visualbasic/VS_Snippets_Wpf/ThreadingWeatherForecast/visualbasic/window1.xaml.vb#threadingweatherfetchweather)] - To keep things simple, we don’t actually have any networking code in this example. Instead, we simulate the delay of network access by putting our new thread to sleep for four seconds. In this time, the original [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] thread is still running and responding to events. To show this, we’ve left an animation running, and the minimize and maximize buttons also continue to work. + To keep things simple, we don’t actually have any networking code in this example. Instead, we simulate the delay of network access by putting our new thread to sleep for four seconds. In this time, the original UI thread is still running and responding to events. To show this, we’ve left an animation running, and the minimize and maximize buttons also continue to work. - When the delay is finished, and we’ve randomly selected our weather forecast, it’s time to report back to the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] thread. We do this by scheduling a call to `UpdateUserInterface` in the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] thread using that thread’s . We pass a string describing the weather to this scheduled method call. + When the delay is finished, and we’ve randomly selected our weather forecast, it’s time to report back to the UI thread. We do this by scheduling a call to `UpdateUserInterface` in the UI thread using that thread’s . We pass a string describing the weather to this scheduled method call. -- Updating the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] +- Updating the UI [!code-csharp[ThreadingWeatherForecast#ThreadingWeatherUpdateUI](~/samples/snippets/csharp/VS_Snippets_Wpf/ThreadingWeatherForecast/CSharp/Window1.xaml.cs#threadingweatherupdateui)] [!code-vb[ThreadingWeatherForecast#ThreadingWeatherUpdateUI](~/samples/snippets/visualbasic/VS_Snippets_Wpf/ThreadingWeatherForecast/visualbasic/window1.xaml.vb#threadingweatherupdateui)] - When the in the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] thread has time, it executes the scheduled call to `UpdateUserInterface`. This method stops the clock animation and chooses an image to describe the weather. It displays this image and restores the "fetch forecast" button. + When the in the UI thread has time, it executes the scheduled call to `UpdateUserInterface`. This method stops the clock animation and chooses an image to describe the weather. It displays this image and restores the "fetch forecast" button. ### Multiple Windows, Multiple Threads - Some [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications require multiple top-level windows. It is perfectly acceptable for one Thread/ combination to manage multiple windows, but sometimes several threads do a better job. This is especially true if there is any chance that one of the windows will monopolize the thread. + Some WPF applications require multiple top-level windows. It is perfectly acceptable for one Thread/ combination to manage multiple windows, but sometimes several threads do a better job. This is especially true if there is any chance that one of the windows will monopolize the thread. Windows Explorer works in this fashion. Each new Explorer window belongs to the original process, but it is created under the control of an independent thread. - By using a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] control, we can display Web pages. We can easily create a simple Internet Explorer substitute. We start with an important feature: the ability to open a new explorer window. When the user clicks the "new window" button, we launch a copy of our window in a separate thread. This way, long-running or blocking operations in one of the windows won’t lock all the other windows. + By using a WPF control, we can display Web pages. We can easily create a simple Internet Explorer substitute. We start with an important feature: the ability to open a new explorer window. When the user clicks the "new window" button, we launch a copy of our window in a separate thread. This way, long-running or blocking operations in one of the windows won’t lock all the other windows. In reality, the Web browser model has its own complicated threading model. We’ve chosen it because it should be familiar to most readers. @@ -160,7 +160,7 @@ ms.assetid: 02d8fd00-8d7c-4604-874c-58e40786770b [!code-csharp[ThreadingMultipleBrowsers#ThreadingMultiBrowserThreadStart](~/samples/snippets/csharp/VS_Snippets_Wpf/ThreadingMultipleBrowsers/CSharp/Window1.xaml.cs#threadingmultibrowserthreadstart)] [!code-vb[ThreadingMultipleBrowsers#ThreadingMultiBrowserThreadStart](~/samples/snippets/visualbasic/VS_Snippets_Wpf/ThreadingMultipleBrowsers/VisualBasic/Window1.xaml.vb#threadingmultibrowserthreadstart)] - This method is the starting point for the new thread. We create a new window under the control of this thread. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] automatically creates a new to manage the new thread. All we have to do to make the window functional is to start the . + This method is the starting point for the new thread. We create a new window under the control of this thread. WPF automatically creates a new to manage the new thread. All we have to do to make the window functional is to start the . ## Technical Details and Stumbling Points @@ -173,24 +173,24 @@ ms.assetid: 02d8fd00-8d7c-4604-874c-58e40786770b `GetWeatherAsync` would use one of the techniques described earlier, such as creating a background thread, to do the work asynchronously, not blocking the calling thread. - One of the most important parts of this pattern is calling the *MethodName*`Completed` method on the same thread that called the *MethodName*`Async` method to begin with. You could do this using [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] fairly easily, by storing —but then the nongraphical component could only be used in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications, not in Windows Forms or ASP.NET programs. + One of the most important parts of this pattern is calling the *MethodName*`Completed` method on the same thread that called the *MethodName*`Async` method to begin with. You could do this using WPF fairly easily, by storing —but then the nongraphical component could only be used in WPF applications, not in Windows Forms or ASP.NET programs. - The class addresses this need—think of it as a simplified version of that works with other [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] frameworks as well. + The class addresses this need—think of it as a simplified version of that works with other UI frameworks as well. [!code-csharp[CommandingOverviewSnippets#ThreadingArticleWeatherComponent2](~/samples/snippets/csharp/VS_Snippets_Wpf/CommandingOverviewSnippets/CSharp/Window1.xaml.cs#threadingarticleweathercomponent2)] [!code-vb[CommandingOverviewSnippets#ThreadingArticleWeatherComponent2](~/samples/snippets/visualbasic/VS_Snippets_Wpf/CommandingOverviewSnippets/visualbasic/window1.xaml.vb#threadingarticleweathercomponent2)] ### Nested Pumping - Sometimes it is not feasible to completely lock up the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] thread. Let’s consider the method of the class. doesn’t return until the user clicks the OK button. It does, however, create a window that must have a message loop in order to be interactive. While we are waiting for the user to click OK, the original application window does not respond to user input. It does, however, continue to process paint messages. The original window redraws itself when covered and revealed. + Sometimes it is not feasible to completely lock up the UI thread. Let’s consider the method of the class. doesn’t return until the user clicks the OK button. It does, however, create a window that must have a message loop in order to be interactive. While we are waiting for the user to click OK, the original application window does not respond to user input. It does, however, continue to process paint messages. The original window redraws itself when covered and revealed. ![Screenshot that shows a MessageBox with an OK button](./media/threading-model/threading-message-loop.png) - Some thread must be in charge of the message box window. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] could create a new thread just for the message box window, but this thread would be unable to paint the disabled elements in the original window (remember the earlier discussion of mutual exclusion). Instead, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] uses a nested message processing system. The class includes a special method called , which stores an application’s current execution point then begins a new message loop. When the nested message loop finishes, execution resumes after the original call. + Some thread must be in charge of the message box window. WPF could create a new thread just for the message box window, but this thread would be unable to paint the disabled elements in the original window (remember the earlier discussion of mutual exclusion). Instead, WPF uses a nested message processing system. The class includes a special method called , which stores an application’s current execution point then begins a new message loop. When the nested message loop finishes, execution resumes after the original call. In this case, maintains the program context at the call to , and it starts a new message loop to repaint the background window and handle input to the message box window. When the user clicks OK and clears the pop-up window, the nested loop exits and control resumes after the call to . ### Stale Routed Events - The routed event system in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] notifies entire trees when events are raised. + The routed event system in WPF notifies entire trees when events are raised. [!code-xaml[InputOvw#ThreadingArticleStaticRoutedEvent](~/samples/snippets/csharp/VS_Snippets_Wpf/InputOvw/CSharp/Page1.xaml#threadingarticlestaticroutedevent)] @@ -201,15 +201,15 @@ ms.assetid: 02d8fd00-8d7c-4604-874c-58e40786770b ### Reentrancy and Locking The locking mechanism of the common language runtime (CLR) doesn’t behave exactly as one might imagine; one might expect a thread to cease operation completely when requesting a lock. In actuality, the thread continues to receive and process high-priority messages. This helps prevent deadlocks and make interfaces minimally responsive, but it introduces the possibility for subtle bugs. The vast majority of the time you don’t need to know anything about this, but under rare circumstances (usually involving Win32 window messages or COM STA components) this can be worth knowing. - Most interfaces are not built with thread safety in mind because developers work under the assumption that a [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] is never accessed by more than one thread. In this case, that single thread may make environmental changes at unexpected times, causing those ill effects that the mutual exclusion mechanism is supposed to solve. Consider the following pseudocode: + Most interfaces are not built with thread safety in mind because developers work under the assumption that a UI is never accessed by more than one thread. In this case, that single thread may make environmental changes at unexpected times, causing those ill effects that the mutual exclusion mechanism is supposed to solve. Consider the following pseudocode: ![Diagram that shows threading reentrancy.](./media/threading-model/threading-reentrancy.png "ThreadingReentrancy") - Most of the time that’s the right thing, but there are times in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] where such unexpected reentrancy can really cause problems. So, at certain key times, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] calls , which changes the lock instruction for that thread to use the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] reentrancy-free lock, instead of the usual CLR lock. + Most of the time that’s the right thing, but there are times in WPF where such unexpected reentrancy can really cause problems. So, at certain key times, WPF calls , which changes the lock instruction for that thread to use the WPF reentrancy-free lock, instead of the usual CLR lock. - So why did the CLR team choose this behavior? It had to do with COM STA objects and the finalization thread. When an object is garbage collected, its `Finalize` method is run on the dedicated finalizer thread, not the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] thread. And therein lies the problem, because a COM STA object that was created on the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] thread can only be disposed on the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] thread. The CLR does the equivalent of a (in this case using Win32’s `SendMessage`). But if the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] thread is busy, the finalizer thread is stalled and the COM STA object can’t be disposed, which creates a serious memory leak. So the CLR team made the tough call to make locks work the way they do. + So why did the CLR team choose this behavior? It had to do with COM STA objects and the finalization thread. When an object is garbage collected, its `Finalize` method is run on the dedicated finalizer thread, not the UI thread. And therein lies the problem, because a COM STA object that was created on the UI thread can only be disposed on the UI thread. The CLR does the equivalent of a (in this case using Win32’s `SendMessage`). But if the UI thread is busy, the finalizer thread is stalled and the COM STA object can’t be disposed, which creates a serious memory leak. So the CLR team made the tough call to make locks work the way they do. - The task for [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] is to avoid unexpected reentrancy without reintroducing the memory leak, which is why we don’t block reentrancy everywhere. + The task for WPF is to avoid unexpected reentrancy without reintroducing the memory leak, which is why we don’t block reentrancy everywhere. ## See also diff --git a/dotnet-desktop-guide/framework/wpf/advanced/trees-in-wpf.md b/dotnet-desktop-guide/framework/wpf/advanced/trees-in-wpf.md index fbdeb50..711326b 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/trees-in-wpf.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/trees-in-wpf.md @@ -10,15 +10,15 @@ ms.assetid: e83f25e5-d66b-4fc7-92d2-50130c9a6649 --- # Trees in WPF -In many technologies, elements and components are organized in a tree structure where developers directly manipulate the object nodes in the tree to affect the rendering or behavior of an application. [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] also uses several tree structure metaphors to define relationships between program elements. For the most part WPF developers can create an application in code or define portions of the application in XAML while thinking conceptually about the object tree metaphor, but will be calling specific API or using specific markup to do so rather than some general object tree manipulation API such as you might use in XML DOM. WPF exposes two helper classes that provide a tree metaphor view, and . The terms visual tree and logical tree are also used in the WPF documentation because these same trees are useful for understanding the behavior of certain key WPF features. This topic defines what the visual tree and logical tree represent, discusses how such trees relate to an overall object tree concept, and introduces and s. +In many technologies, elements and components are organized in a tree structure where developers directly manipulate the object nodes in the tree to affect the rendering or behavior of an application. Windows Presentation Foundation (WPF) also uses several tree structure metaphors to define relationships between program elements. For the most part WPF developers can create an application in code or define portions of the application in XAML while thinking conceptually about the object tree metaphor, but will be calling specific API or using specific markup to do so rather than some general object tree manipulation API such as you might use in XML DOM. WPF exposes two helper classes that provide a tree metaphor view, and . The terms visual tree and logical tree are also used in the WPF documentation because these same trees are useful for understanding the behavior of certain key WPF features. This topic defines what the visual tree and logical tree represent, discusses how such trees relate to an overall object tree concept, and introduces and s. ## Trees in WPF - The most complete tree structure in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] is the object tree. If you define an application page in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] and then load the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], the tree structure is created based on the nesting relationships of the elements in the markup. If you define an application or a portion of the application in code, then the tree structure is created based on how you assign property values for properties that implement the content model for a given object. In [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)], there are two ways that the complete object tree is conceptualized and can be reported to its public API: as the logical tree and as the visual tree. The distinctions between logical tree and visual tree are not always necessarily important, but they can occasionally cause issues with certain [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] subsystems and affect choices you make in markup or code. + The most complete tree structure in WPF is the object tree. If you define an application page in WPF subsystems and affect choices you make in markup or code. - Even though you do not always manipulate either the logical tree or the visual tree directly, understanding the concepts of how the trees interact is useful for understanding WPF as a technology. Thinking of WPF as a tree metaphor of some kind is also crucial to understanding how property inheritance and event routing work in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. + Even though you do not always manipulate either the logical tree or the visual tree directly, understanding the concepts of how the trees interact is useful for understanding WPF as a technology. Thinking of WPF as a tree metaphor of some kind is also crucial to understanding how property inheritance and event routing work in WPF. > [!NOTE] > Because the object tree is more of a concept than an actual API, another way to think of the concept is as an object graph. In practice, there are relationships between objects at run time where the tree metaphor will break down. Nevertheless, particularly with XAML-defined UI, the tree metaphor is relevant enough that most WPF documentation will use the term object tree when referencing this general concept. @@ -27,9 +27,9 @@ In many technologies, elements and components are organized in a tree structure ## The Logical Tree - In [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], you add content to UI elements by setting properties of the objects that back those elements. For example, you add items to a control by manipulating its property. By doing this, you are placing items into the that is the property value. Similarly, to add objects to a , you manipulate its property value. Here, you are adding objects to the . For a code example, see [How to: Add an Element Dynamically](/previous-versions/dotnet/netframework-4.0/ms752374(v=vs.100)). + In WPF, you add content to UI elements by setting properties of the objects that back those elements. For example, you add items to a control by manipulating its property. By doing this, you are placing items into the that is the property value. Similarly, to add objects to a , you manipulate its property value. Here, you are adding objects to the . For a code example, see [How to: Add an Element Dynamically](/previous-versions/dotnet/netframework-4.0/ms752374(v=vs.100)). - In [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)], when you place list items in a or controls or other UI elements in a , you also use the and properties, either explicitly or implicitly, as in the following example. + In Extensible Application Markup Language (XAML), when you place list items in a or controls or other UI elements in a , you also use the and properties, either explicitly or implicitly, as in the following example. [!code-xaml[TreeOvwsSupport#AllCode](~/samples/snippets/csharp/VS_Snippets_Wpf/TreeOvwsSupport/CS/page1.xaml#allcode)] @@ -37,7 +37,7 @@ In many technologies, elements and components are organized in a tree structure However, the logical tree is not the entire object graph that exists for your application UI at run time, even with the XAML implicit syntax items factored out. The main reason for this is visuals and templates. For example, consider the . The logical tree reports the object and also its string `Content`. But there is more to this button in the run-time object tree. In particular, the button only appears on screen the way it does because a specific control template was applied. The visuals that come from an applied template (such as the template-defined of dark gray around the visual button) are not reported in the logical tree, even if you are looking at the logical tree during run time (such as handling an input event from the visible UI and then reading the logical tree). To find the template visuals, you would instead need to examine the visual tree. - For more information about how [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] syntax maps to the created object graph, and implicit syntax in XAML, see [XAML Syntax In Detail](xaml-syntax-in-detail.md) or [XAML in WPF](xaml-in-wpf.md). + For more information about how XAML syntax maps to the created object graph, and implicit syntax in XAML, see [XAML Syntax In Detail](xaml-syntax-in-detail.md) or [XAML in WPF](xaml-in-wpf.md). @@ -69,7 +69,7 @@ In many technologies, elements and components are organized in a tree structure ## The Visual Tree - In addition to the concept of the logical tree, there is also the concept of the visual tree in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. The visual tree describes the structure of visual objects, as represented by the base class. When you write a template for a control, you are defining or redefining the visual tree that applies for that control. The visual tree is also of interest to developers who want lower-level control over drawing for performance and optimization reasons. One exposure of the visual tree as part of conventional [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application programming is that event routes for a routed event mostly travel along the visual tree, not the logical tree. This subtlety of routed event behavior might not be immediately apparent unless you are a control author. Routing events through the visual tree enables controls that implement composition at the visual level to handle events or create event setters. + In addition to the concept of the logical tree, there is also the concept of the visual tree in WPF. The visual tree describes the structure of visual objects, as represented by the base class. When you write a template for a control, you are defining or redefining the visual tree that applies for that control. The visual tree is also of interest to developers who want lower-level control over drawing for performance and optimization reasons. One exposure of the visual tree as part of conventional WPF application programming is that event routes for a routed event mostly travel along the visual tree, not the logical tree. This subtlety of routed event behavior might not be immediately apparent unless you are a control author. Routing events through the visual tree enables controls that implement composition at the visual level to handle events or create event setters. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/troubleshooting-hybrid-applications.md b/dotnet-desktop-guide/framework/wpf/advanced/troubleshooting-hybrid-applications.md index e3cad11..43a0b1d 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/troubleshooting-hybrid-applications.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/troubleshooting-hybrid-applications.md @@ -12,17 +12,17 @@ ms.assetid: f440c23f-fa5d-4d5a-852f-ba61150e6405 --- # Troubleshooting Hybrid Applications - This topic lists some common problems that can occur when authoring hybrid applications, which use both [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] and Windows Forms technologies. + This topic lists some common problems that can occur when authoring hybrid applications, which use both WPF and Windows Forms technologies. ## Overlapping Controls - Controls may not overlap as you would expect. Windows Forms uses a separate HWND for each control. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] uses one HWND for all content on a page. This implementation difference causes unexpected overlapping behaviors. + Controls may not overlap as you would expect. Windows Forms uses a separate HWND for each control. WPF uses one HWND for all content on a page. This implementation difference causes unexpected overlapping behaviors. - A Windows Forms control hosted in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] always appears on top of the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content. + A Windows Forms control hosted in WPF always appears on top of the WPF content. - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content hosted in an control appears at the z-order of the control. It is possible to overlap controls, but the hosted [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content does not combine or interact. + WPF content hosted in an control appears at the z-order of the control. It is possible to overlap controls, but the hosted WPF content does not combine or interact. @@ -34,7 +34,7 @@ ms.assetid: f440c23f-fa5d-4d5a-852f-ba61150e6405 ## Scaling - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] and Windows Forms have different scaling models. Some [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] scaling transformations are meaningful to Windows Forms controls, but others are not. For example, scaling a Windows Forms control to 0 will work, but if you try to scale the same control back to a non-zero value, the control's size remains 0. For more information, see [Layout Considerations for the WindowsFormsHost Element](layout-considerations-for-the-windowsformshost-element.md). + WPF and Windows Forms have different scaling models. Some WPF scaling transformations are meaningful to Windows Forms controls, but others are not. For example, scaling a Windows Forms control to 0 will work, but if you try to scale the same control back to a non-zero value, the control's size remains 0. For more information, see [Layout Considerations for the WindowsFormsHost Element](layout-considerations-for-the-windowsformshost-element.md). @@ -52,7 +52,7 @@ ms.assetid: f440c23f-fa5d-4d5a-852f-ba61150e6405 ## Focus - Focus works differently in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] and Windows Forms, which means that focus issues may occur in a hybrid application. For example, if you have focus inside a element, and you either minimize and restore the page or show a modal dialog box, focus inside the element may be lost. The element still has focus, but the control inside it may not. + Focus works differently in WPF and Windows Forms, which means that focus issues may occur in a hybrid application. For example, if you have focus inside a element, and you either minimize and restore the page or show a modal dialog box, focus inside the element may be lost. The element still has focus, but the control inside it may not. Data validation is also affected by focus. Validation works in a element, but it does not work as you tab out of the element, or between two different elements. @@ -60,7 +60,7 @@ ms.assetid: f440c23f-fa5d-4d5a-852f-ba61150e6405 ## Property Mapping - Some property mappings require extensive interpretation to bridge dissimilar implementations between the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] and Windows Forms technologies. Property mappings enable your code to react to changes in fonts, colors, and other properties. In general, property mappings work by listening for either *Property*Changed events or On*Property*Changed calls, and setting appropriate properties on either the child control or its adapter. For more information, see [Windows Forms and WPF Property Mapping](windows-forms-and-wpf-property-mapping.md). + Some property mappings require extensive interpretation to bridge dissimilar implementations between the WPF and Windows Forms technologies. Property mappings enable your code to react to changes in fonts, colors, and other properties. In general, property mappings work by listening for either *Property*Changed events or On*Property*Changed calls, and setting appropriate properties on either the child control or its adapter. For more information, see [Windows Forms and WPF Property Mapping](windows-forms-and-wpf-property-mapping.md). @@ -87,21 +87,21 @@ ms.assetid: f440c23f-fa5d-4d5a-852f-ba61150e6405 ## Message Loop Interoperation - When working with Windows Forms message loops, messages may not be processed as expected. The method is called by the constructor. This method adds a message filter to the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] message loop. This filter calls the method if a was the target of the message and translates/dispatches the message. + When working with Windows Forms message loops, messages may not be processed as expected. The method is called by the constructor. This method adds a message filter to the WPF message loop. This filter calls the method if a was the target of the message and translates/dispatches the message. - If you show a in a Windows Forms message loop with , you cannot type anything unless you call the method. The method takes a and adds a , which reroutes key-related messages to the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] message loop. For more information, see [Windows Forms and WPF Interoperability Input Architecture](windows-forms-and-wpf-interoperability-input-architecture.md). + If you show a in a Windows Forms message loop with , you cannot type anything unless you call the method. The method takes a and adds a , which reroutes key-related messages to the WPF message loop. For more information, see [Windows Forms and WPF Interoperability Input Architecture](windows-forms-and-wpf-interoperability-input-architecture.md). ## Opacity and Layering - The class does not support layering. This means that setting the property on the element has no effect, and no blending will occur with other [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] windows which have set to `true`. + The class does not support layering. This means that setting the property on the element has no effect, and no blending will occur with other WPF windows which have set to `true`. ## Dispose - Not disposing classes properly can leak resources. In your hybrid applications, make sure that the and classes are disposed, or you could leak resources. Windows Forms disposes controls when its non-modal parent closes. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] disposes elements when your application shuts down. It is possible to show a element in a in a Windows Forms message loop. In this case, your code may not receive notification that your application is shutting down. + Not disposing classes properly can leak resources. In your hybrid applications, make sure that the and classes are disposed, or you could leak resources. Windows Forms disposes controls when its non-modal parent closes. WPF disposes elements when your application shuts down. It is possible to show a element in a in a Windows Forms message loop. In this case, your code may not receive notification that your application is shutting down. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/typography-how-to-topics.md b/dotnet-desktop-guide/framework/wpf/advanced/typography-how-to-topics.md index 7978816..08b3ca1 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/typography-how-to-topics.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/typography-how-to-topics.md @@ -8,7 +8,7 @@ helpviewer_keywords: ms.assetid: 82d50325-7cb2-4975-aea3-027c00e6bbfc --- # Typography How-to Topics -The topics in this section describe how to use [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] support for rich presentation of text in your applications. +The topics in this section describe how to use Windows Presentation Foundation (WPF) support for rich presentation of text in your applications. ## In This Section [Create a Text Decoration](how-to-create-a-text-decoration.md) diff --git a/dotnet-desktop-guide/framework/wpf/advanced/typography-in-wpf.md b/dotnet-desktop-guide/framework/wpf/advanced/typography-in-wpf.md index 5d536ec..93f32ca 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/typography-in-wpf.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/typography-in-wpf.md @@ -9,22 +9,22 @@ ms.assetid: 06cbf17b-6eff-4fe5-949d-2dd533e4e1f4 --- # Typography in WPF -This topic introduces the major typographic features of [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. These features include improved quality and performance of text rendering, OpenType typography support, enhanced international text, enhanced font support, and new text application programming interfaces (APIs). +This topic introduces the major typographic features of WPF. These features include improved quality and performance of text rendering, OpenType typography support, enhanced international text, enhanced font support, and new text application programming interfaces (APIs). ## Improved Quality and Performance of Text - Text in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] is rendered using Microsoft ClearType, which enhances the clarity and readability of text. ClearType is a software technology developed by Microsoft that improves the readability of text on existing LCDs (Liquid Crystal Displays), such as laptop screens, Pocket PC screens and flat panel monitors. ClearType uses sub-pixel rendering which allows text to be displayed with a greater fidelity to its true shape by aligning characters on a fractional part of a pixel. The extra resolution increases the sharpness of the tiny details in text display, making it much easier to read over long durations. Another improvement of ClearType in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] is y-direction anti-aliasing, which smoothes the tops and bottoms of shallow curves in text characters. For more details on ClearType features, see [ClearType Overview](cleartype-overview.md). + Text in WPF is rendered using Microsoft ClearType, which enhances the clarity and readability of text. ClearType is a software technology developed by Microsoft that improves the readability of text on existing LCDs (Liquid Crystal Displays), such as laptop screens, Pocket PC screens and flat panel monitors. ClearType uses sub-pixel rendering which allows text to be displayed with a greater fidelity to its true shape by aligning characters on a fractional part of a pixel. The extra resolution increases the sharpness of the tiny details in text display, making it much easier to read over long durations. Another improvement of ClearType in WPF is y-direction anti-aliasing, which smoothes the tops and bottoms of shallow curves in text characters. For more details on ClearType features, see [ClearType Overview](cleartype-overview.md). ![Text with ClearType y-direction anti-aliasing](./media/typography-in-wpf/text-y-direction-antialiasing.gif) Text with ClearType y-direction antialiasing - The entire text rendering pipeline can be hardware-accelerated in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provided your machine meets the minimum level of hardware required. Rendering that cannot be performed using hardware falls back to software rendering. Hardware-acceleration affects all phases of the text rendering pipeline—from storing individual glyphs, compositing glyphs into glyph runs, applying effects, to applying the ClearType blending algorithm to the final displayed output. For more information on hardware acceleration, see [Graphics Rendering Tiers](graphics-rendering-tiers.md). + The entire text rendering pipeline can be hardware-accelerated in WPF provided your machine meets the minimum level of hardware required. Rendering that cannot be performed using hardware falls back to software rendering. Hardware-acceleration affects all phases of the text rendering pipeline—from storing individual glyphs, compositing glyphs into glyph runs, applying effects, to applying the ClearType blending algorithm to the final displayed output. For more information on hardware acceleration, see [Graphics Rendering Tiers](graphics-rendering-tiers.md). ![Diagram of the text rendering pipeline](./media/typography-in-wpf/text-rendering-pipeline.png) - In addition, animated text, whether by character or glyph, takes full advantage of the graphics hardware capability enabled by [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. This results in smooth text animation. + In addition, animated text, whether by character or glyph, takes full advantage of the graphics hardware capability enabled by WPF. This results in smooth text animation. @@ -46,7 +46,7 @@ Text with ClearType y-direction antialiasing ## Enhanced International Text Support - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides enhanced international text support by providing the following features: + WPF provides enhanced international text support by providing the following features: - Automatic line-spacing in all writing systems, using adaptive measurement. @@ -58,7 +58,7 @@ Text with ClearType y-direction antialiasing ## Enhanced Font Support - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides enhanced font support by providing the following features: + WPF provides enhanced font support by providing the following features: - Unicode for all text. Font behavior and selection no longer require charset or codepage. @@ -78,7 +78,7 @@ Text with ClearType y-direction antialiasing ## New Text Application Programming Interfaces (APIs) - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides several text APIs for developers to use when including text in their applications. These APIs are grouped into three categories: + WPF provides several text APIs for developers to use when including text in their applications. These APIs are grouped into three categories: - **Layout and user interface**. The common text controls for the graphical user interface (GUI). @@ -88,11 +88,11 @@ Text with ClearType y-direction antialiasing ### Layout and User Interface - At the highest level of functionality, the text APIs provide common [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] controls such as , , and . These controls provide the basic [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] elements within an application, and offer an easy way to present and interact with text. Controls such as and enable more advanced or specialized text-handling. And classes such as , , and enable useful text manipulation. These [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] controls provide properties such as , , and , which enable you to control the font that is used to render the text. + At the highest level of functionality, the text APIs provide common UI elements within an application, and offer an easy way to present and interact with text. Controls such as and enable more advanced or specialized text-handling. And classes such as , , and enable useful text manipulation. These UI controls provide properties such as , , and , which enable you to control the font that is used to render the text. #### Using Bitmap Effects, Transforms, and Text Effects - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] allows you to create visually interesting uses of text by uses features such as bitmap effects, transforms, and text effects. The following example shows a typical type of a drop shadow effect applied to text. + WPF allows you to create visually interesting uses of text by uses features such as bitmap effects, transforms, and text effects. The following example shows a typical type of a drop shadow effect applied to text. ![Text shadow with Softness = 0.25](./media/typography-in-wpf/drop-shadow-text-effect.jpg) @@ -122,7 +122,7 @@ Text with ClearType y-direction antialiasing #### Using Flow Documents - In addition to the common [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] controls, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] offers a layout control for text presentation—the element. The element, in conjunction with the element, provides a control for large amounts of text with varying layout requirements. Layout controls provide access to advanced typography through the object and font-related properties of other [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] controls. + In addition to the common UI controls, UI controls. The following example shows text content hosted in a , which provides search, navigation, pagination, and content scaling support. @@ -132,7 +132,7 @@ Text with ClearType y-direction antialiasing ### Lightweight Text Drawing - You can draw text directly to [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] objects by using the method of the object. To use this method, you create a object. This object allows you to draw multi-line text, in which each character in the text can be individually formatted. The functionality of the object contains much of the functionality of the DrawText flags in the Windows API. In addition, the object contains functionality such as ellipsis support, in which an ellipsis is displayed when text exceeds its bounds. The following example shows text that has several formats applied to it, including a linear gradient on the second and third words. + You can draw text directly to WPF objects by using the method of the object. To use this method, you create a object. This object allows you to draw multi-line text, in which each character in the text can be individually formatted. The functionality of the object contains much of the functionality of the DrawText flags in the Windows API. In addition, the object contains functionality such as ellipsis support, in which an ellipsis is displayed when text exceeds its bounds. The following example shows text that has several formats applied to it, including a linear gradient on the second and third words. ![Text displayed using FormattedText object](./media/typography-in-wpf/text-formatted-linear-gradient.jpg) @@ -152,7 +152,7 @@ Text with ClearType y-direction antialiasing ### Advanced Text Formatting - At the most advanced level of the text APIs, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] offers you the ability to create custom text layout by using the object and other types in the namespace. The and associated classes allow you to implement custom text layout that supports your own definition of character formats, paragraph styles, line breaking rules, and other layout features for international text. There are very few cases in which you would want to override the default implementation of the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] text layout support. However, if you were creating a text editing control or application, you might require a different implementation than the default [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] implementation. + At the most advanced level of the text APIs, WPF offers you the ability to create custom text layout by using the object and other types in the namespace. The and associated classes allow you to implement custom text layout that supports your own definition of character formats, paragraph styles, line breaking rules, and other layout features for international text. There are very few cases in which you would want to override the default implementation of the WPF text layout support. However, if you were creating a text editing control or application, you might require a different implementation than the default WPF implementation. Unlike a traditional text API, the interacts with a text layout client through a set of callback methods. It requires the client to provide these methods in an implementation of the class. The following diagram illustrates the text layout interaction between the client application and . diff --git a/dotnet-desktop-guide/framework/wpf/advanced/typography.md b/dotnet-desktop-guide/framework/wpf/advanced/typography.md index 5603587..f51be03 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/typography.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/typography.md @@ -12,7 +12,7 @@ helpviewer_keywords: ms.assetid: e4ef38db-b7d1-4bda-87ab-8bb738440ddc --- # Typography -[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] includes support for rich presentation of text content. Text in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] is rendered using Microsoft ClearType, which enhances the clarity and readability of text. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] also supports OpenType fonts, which provide additional capabilities beyond those defined by the TrueType® format. +WPF is rendered using Microsoft ClearType, which enhances the clarity and readability of text. WPF also supports OpenType fonts, which provide additional capabilities beyond those defined by the TrueType® format. ## In This Section [Typography in WPF](typography-in-wpf.md) diff --git a/dotnet-desktop-guide/framework/wpf/advanced/use-automatic-layout-overview.md b/dotnet-desktop-guide/framework/wpf/advanced/use-automatic-layout-overview.md index 3e353a7..0265038 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/use-automatic-layout-overview.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/use-automatic-layout-overview.md @@ -8,13 +8,13 @@ ms.assetid: 6fed9264-18bb-4d05-8867-1fe356c6f687 --- # Use Automatic Layout Overview -This topic introduces guidelines for developers on how to write [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] applications with localizable user interfaces (UIs). In the past, localization of a UI was a time consuming process. Each language that the UI was adapted for required a pixel by pixel adjustment. Today with the right design and right coding standards, UIs can be constructed so that localizers have less resizing and repositioning to do. The approach to writing applications that can be more easily resized and repositioned is called automatic layout, and can be achieved by using [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application design. +This topic introduces guidelines for developers on how to write WPF application design. ## Advantages of Using Automatic Layout -Because the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] presentation system is powerful and flexible, it provides the ability to layout elements in an application that can be adjusted to fit the requirements of different languages. The following list points out some of the advantages of automatic layout. +Because the WPF presentation system is powerful and flexible, it provides the ability to layout elements in an application that can be adjusted to fit the requirements of different languages. The following list points out some of the advantages of automatic layout. - UI displays well in any language. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/visual-basic-and-wpf-event-handling.md b/dotnet-desktop-guide/framework/wpf/advanced/visual-basic-and-wpf-event-handling.md index 95de032..d80c04f 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/visual-basic-and-wpf-event-handling.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/visual-basic-and-wpf-event-handling.md @@ -7,10 +7,10 @@ helpviewer_keywords: ms.assetid: ad4eb9aa-3afc-4a71-8cf6-add3fbea54a1 --- # Visual Basic and WPF Event Handling -For the Microsoft Visual Basic .NET language specifically, you can use the language-specific `Handles` keyword to associate event handlers with instances, instead of attaching event handlers with attributes or using the method. However, the `Handles` technique for attaching handlers to instances does have some limitations, because the `Handles` syntax cannot support some of the specific routed event features of the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] event system. +For the Microsoft Visual Basic .NET language specifically, you can use the language-specific `Handles` keyword to associate event handlers with instances, instead of attaching event handlers with attributes or using the method. However, the `Handles` technique for attaching handlers to instances does have some limitations, because the `Handles` syntax cannot support some of the specific routed event features of the WPF event system. ## Using "Handles" in a WPF Application - The event handlers that are connected to instances and events with `Handles` must all be defined within the partial class declaration of the instance, which is also a requirement for event handlers that are assigned through attribute values on elements. You can only specify `Handles` for an element on the page that has a property value (or [x:Name Directive](/dotnet/desktop/xaml-services/xname-directive) declared). This is because the in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] creates the instance reference that is necessary to support the *Instance.Event* reference format required by the `Handles` syntax. The only element that can be used for `Handles` without a reference is the root-element instance that defines the partial class. + The event handlers that are connected to instances and events with `Handles` must all be defined within the partial class declaration of the instance, which is also a requirement for event handlers that are assigned through attribute values on elements. You can only specify `Handles` for an element on the page that has a property value (or [x:Name Directive](/dotnet/desktop/xaml-services/xname-directive) declared). This is because the in XAML creates the instance reference that is necessary to support the *Instance.Event* reference format required by the `Handles` syntax. The only element that can be used for `Handles` without a reference is the root-element instance that defines the partial class. You can assign the same handler to multiple elements by separating *Instance.Event* references after `Handles` with commas. @@ -18,10 +18,10 @@ For the Microsoft Visual Basic .NET language specifically, you can use the langu To remove a handler that was added with `Handles` in the declaration, you can call . - You can use `Handles` to attach handlers for routed events, so long as you attach handlers to instances that define the event being handled in their members tables. For routed events, handlers that are attached with `Handles` follow the same routing rules as do handlers that are attached as [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] attributes, or with the common signature of . This means that if the event is already marked handled (the property in the event data is `True`), then handlers attached with `Handles` are not invoked in response to that event instance. The event could be marked handled by instance handlers on another element in the route, or by class handling either on the current element or earlier elements along the route. For input events that support paired tunnel/bubble events, the tunneling route may have marked the event pair handled. For more information about routed events, see [Routed Events Overview](routed-events-overview.md). + You can use `Handles` to attach handlers for routed events, so long as you attach handlers to instances that define the event being handled in their members tables. For routed events, handlers that are attached with `Handles` follow the same routing rules as do handlers that are attached as XAML attributes, or with the common signature of . This means that if the event is already marked handled (the property in the event data is `True`), then handlers attached with `Handles` are not invoked in response to that event instance. The event could be marked handled by instance handlers on another element in the route, or by class handling either on the current element or earlier elements along the route. For input events that support paired tunnel/bubble events, the tunneling route may have marked the event pair handled. For more information about routed events, see [Routed Events Overview](routed-events-overview.md). ## Limitations of "Handles" for Adding Handlers - `Handles` cannot reference handlers for attached events. You must use the `add` accessor method for that attached event, or *typename.eventname* event attributes in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]. For details, see [Routed Events Overview](routed-events-overview.md). + `Handles` cannot reference handlers for attached events. You must use the `add` accessor method for that attached event, or *typename.eventname* event attributes in XAML. For details, see [Routed Events Overview](routed-events-overview.md). For routed events, you can only use `Handles` to assign handlers for instances where that event exists in the instance members table. However, with routed events in general, a parent element can be a listener for an event from child elements, even if the parent element does not have that event in its members table. In attribute syntax, you can specify this through a *typename.membername* attribute form that qualifies which type actually defines the event you want to handle. For instance, a parent `Page` (with no `Click` event defined) can listen for button-click events by assigning an attribute handler in the form `Button.Click`. But `Handles` does not support the *typename.membername* form, because it must support a conflicting *Instance.Event* form. For details, see [Routed Events Overview](routed-events-overview.md). @@ -31,7 +31,7 @@ For the Microsoft Visual Basic .NET language specifically, you can use the langu > Do not use the `Handles` syntax in Visual Basic code when you specify an event handler for the same event in XAML. In this case, the event handler is called twice. ## How WPF Implements "Handles" Functionality - When a [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] page is compiled, the intermediate file declares `Friend` `WithEvents` references to every element on the page that has a property set (or [x:Name Directive](/dotnet/desktop/xaml-services/xname-directive) declared). Each named instance is potentially an element that can be assigned to a handler through `Handles`. + When a Extensible Application Markup Language (XAML) page is compiled, the intermediate file declares `Friend` `WithEvents` references to every element on the page that has a property set (or [x:Name Directive](/dotnet/desktop/xaml-services/xname-directive) declared). Each named instance is potentially an element that can be assigned to a handler through `Handles`. > [!NOTE] > Within Visual Studio, IntelliSense can show you completion for which elements are available for a `Handles` reference in a page. However, this might take one compile pass so that the intermediate file can populate all the `Friends` references. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-arranging-windows-forms-controls-in-wpf.md b/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-arranging-windows-forms-controls-in-wpf.md index 2c811cb..54d4160 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-arranging-windows-forms-controls-in-wpf.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-arranging-windows-forms-controls-in-wpf.md @@ -12,7 +12,7 @@ ms.assetid: a1db8049-15c7-45d6-ae3d-36a6735cb848 --- # Walkthrough: Arranging Windows Forms Controls in WPF -This walkthrough shows you how to use [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] layout features to arrange Windows Forms controls in a hybrid application. +This walkthrough shows you how to use WPF layout features to arrange Windows Forms controls in a hybrid application. Tasks illustrated in this walkthrough include: @@ -33,7 +33,7 @@ Tasks illustrated in this walkthrough include: For a complete code listing of the tasks illustrated in this walkthrough, see [Arranging Windows Forms Controls in WPF Sample](https://github.com/microsoft/WPF-Samples/tree/master/Migration%20and%20Interoperability/WpfLayoutHostingWfWithXaml). -When you are finished, you will have an understanding of Windows Forms layout features in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]-based applications. +When you are finished, you will have an understanding of Windows Forms layout features in WPF-based applications. ## Prerequisites @@ -115,7 +115,7 @@ To specify size explicitly, follow these steps: Always set layout-related properties on the hosted control by using the properties of the element. Setting layout properties directly on the hosted control will yield unintended results. - Setting layout-related properties on the hosted control in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] has no effect. + Setting layout-related properties on the hosted control in XAML has no effect. To see the effects of setting properties on the hosted control, follow these steps: @@ -146,7 +146,7 @@ Visible elements are al ## Docking - element supports [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] docking. Set the attached property to dock the hosted control in a element. + element supports WPF docking. Set the attached property to dock the hosted control in a element. To dock a hosted control, follow these steps: @@ -187,7 +187,7 @@ To host a control that does not stretch, follow these steps: [!code-xaml[WpfLayoutHostingWfWithXaml#11](~/samples/snippets/csharp/VS_Snippets_Wpf/WpfLayoutHostingWfWithXaml/CSharp/Window1.xaml#11)] -2. Press F5 to build and run the application. The element is centered in the grid row, but it is not stretched to fill the available space. If the window is large enough, you may see two or more months displayed by the hosted control, but these are centered in the row. The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] layout engine centers elements that cannot be sized to fill the available space. +2. Press F5 to build and run the application. The element is centered in the grid row, but it is not stretched to fill the available space. If the window is large enough, you may see two or more months displayed by the hosted control, but these are centered in the row. The WPF layout engine centers elements that cannot be sized to fill the available space. ## Scaling @@ -217,7 +217,7 @@ To see the effect of rotation in a hybrid application, follow these steps: ## Setting Padding and Margins -Padding and margins in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] layout are similar to padding and margins in Windows Forms. Simply set the and properties on the element. +Padding and margins in WPF layout are similar to padding and margins in Windows Forms. Simply set the and properties on the element. To set padding and margins for a hosted control, follow these steps: @@ -230,7 +230,7 @@ To set padding and margins for a hosted control, follow these steps: ## Using Dynamic Layout Containers -Windows Forms provides two dynamic layout containers, and . You can also use these containers in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] layouts. +Windows Forms provides two dynamic layout containers, and . You can also use these containers in WPF layouts. To use a dynamic layout container, follow these steps: diff --git a/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-binding-to-data-in-hybrid-applications.md b/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-binding-to-data-in-hybrid-applications.md index f5b97cd..24f0b3b 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-binding-to-data-in-hybrid-applications.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-binding-to-data-in-hybrid-applications.md @@ -11,7 +11,7 @@ ms.assetid: 18997e71-745a-4425-9c69-2cbce1d8669e --- # Walkthrough: Binding to Data in Hybrid Applications -Binding a data source to a control is essential for providing users with access to underlying data, whether you are using Windows Forms or [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. This walkthrough shows how you can use data binding in hybrid applications that include both Windows Forms and [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] controls. +Binding a data source to a control is essential for providing users with access to underlying data, whether you are using Windows Forms or WPF. This walkthrough shows how you can use data binding in hybrid applications that include both Windows Forms and WPF controls. Tasks illustrated in this walkthrough include: diff --git a/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-caching-application-data-in-a-wpf-application.md b/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-caching-application-data-in-a-wpf-application.md index 97586ef..af93a86 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-caching-application-data-in-a-wpf-application.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-caching-application-data-in-a-wpf-application.md @@ -18,7 +18,7 @@ Caching enables you to store data in memory for rapid access. When the data is a > [!NOTE] > The namespace is new in the .NET Framework 4. This namespace makes caching is available to all .NET Framework applications. In previous versions of the .NET Framework, caching was available only in the namespace and therefore required a dependency on ASP.NET classes. - This walkthrough shows you how to use the caching functionality that is available in the .NET Framework as part of a [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] application. In the walkthrough, you cache the contents of a text file. + This walkthrough shows you how to use the caching functionality that is available in the .NET Framework as part of a Windows Presentation Foundation (WPF) application. In the walkthrough, you cache the contents of a text file. Tasks illustrated in this walkthrough include the following: diff --git a/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-creating-your-first-touch-application.md b/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-creating-your-first-touch-application.md index aef8b74..66014e7 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-creating-your-first-touch-application.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-creating-your-first-touch-application.md @@ -12,7 +12,7 @@ helpviewer_keywords: ms.assetid: d69e602e-9a25-4e24-950b-e89eaa2a906b --- # Walkthrough: Creating Your First Touch Application -[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] enables applications to respond to touch. For example, you can interact with an application by using one or more fingers on a touch-sensitive device, such as a touchscreen This walkthrough creates an application that enables the user to move, resize, or rotate a single object by using touch. +WPF enables applications to respond to touch. For example, you can interact with an application by using one or more fingers on a touch-sensitive device, such as a touchscreen This walkthrough creates an application that enables the user to move, resize, or rotate a single object by using touch. ## Prerequisites You need the following components to complete this walkthrough: @@ -21,7 +21,7 @@ ms.assetid: d69e602e-9a25-4e24-950b-e89eaa2a906b - A device that accepts touch input, such as a touchscreen, that supports Windows Touch. - Additionally, you should have a basic understanding of how to create an application in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], especially how to subscribe to and handle an event. For more information, see [Walkthrough: My first WPF desktop application](../getting-started/walkthrough-my-first-wpf-desktop-application.md). + Additionally, you should have a basic understanding of how to create an application in WPF, especially how to subscribe to and handle an event. For more information, see [Walkthrough: My first WPF desktop application](../getting-started/walkthrough-my-first-wpf-desktop-application.md). ## Creating the Application @@ -39,7 +39,7 @@ ms.assetid: d69e602e-9a25-4e24-950b-e89eaa2a906b 4. In the `MainWindow` class, add the following event handler. - The event occurs when [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] detects that touch input begins to manipulate an object. The code specifies that the position of the manipulation should be relative to the by setting the property. + The event occurs when WPF detects that touch input begins to manipulate an object. The code specifies that the position of the manipulation should be relative to the by setting the property. [!code-csharp[BasicManipulation#ManipulationStarting](~/samples/snippets/csharp/VS_Snippets_Wpf/basicmanipulation/csharp/mainwindow.xaml.cs#manipulationstarting)] [!code-vb[BasicManipulation#ManipulationStarting](~/samples/snippets/visualbasic/VS_Snippets_Wpf/basicmanipulation/visualbasic/mainwindow.xaml.vb#manipulationstarting)] diff --git a/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-enabling-drag-and-drop-on-a-user-control.md b/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-enabling-drag-and-drop-on-a-user-control.md index 4aacea3..a89eddd 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-enabling-drag-and-drop-on-a-user-control.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-enabling-drag-and-drop-on-a-user-control.md @@ -12,7 +12,7 @@ ms.assetid: cc844419-1a77-4906-95d9-060d79107fc7 --- # Walkthrough: Enabling Drag and Drop on a User Control -This walkthrough demonstrates how to create a custom user control that can participate in drag-and-drop data transfer in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)]. +This walkthrough demonstrates how to create a custom user control that can participate in drag-and-drop data transfer in Windows Presentation Foundation (WPF). In this walkthrough, you will create a custom WPF that represents a circle shape. You will implement functionality on the control to enable data transfer through drag-and-drop. For example, if you drag from one Circle control to another, the Fill color data is copied from the source Circle to the target. If you drag from a Circle control to a , the string representation of the Fill color is copied to the . You will also create a small application that contains two panel controls and a to test the drag-and-drop functionality. You will write code that enables the panels to process dropped Circle data, which will enable you to move or copy Circles from the Children collection of one panel to the other. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-hosting-a-3-d-wpf-composite-control-in-windows-forms.md b/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-hosting-a-3-d-wpf-composite-control-in-windows-forms.md index 4c9f0d7..e248b61 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-hosting-a-3-d-wpf-composite-control-in-windows-forms.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-hosting-a-3-d-wpf-composite-control-in-windows-forms.md @@ -12,17 +12,17 @@ ms.assetid: 486369a9-606a-4a3b-b086-a06f2119c7b0 --- # Walkthrough: Host a 3D WPF Composite Control in Windows Forms -This walkthrough demonstrates how you can create a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] composite control and host it in Windows Forms controls and forms by using the control. +This walkthrough demonstrates how you can create a WPF composite control and host it in Windows Forms controls and forms by using the control. -In this walkthrough, you will implement a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] that contains two child controls. The displays a three-dimensional (3D) cone. Rendering 3D objects is much easier with the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] than with Windows Forms. Therefore, it makes sense to host a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] class to create 3D graphics in Windows Forms. +In this walkthrough, you will implement a WPF that contains two child controls. The displays a three-dimensional (3D) cone. Rendering 3D objects is much easier with the WPF than with Windows Forms. Therefore, it makes sense to host a WPF class to create 3D graphics in Windows Forms. Tasks illustrated in this walkthrough include: -- Creating the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] . +- Creating the WPF . - Creating the Windows Forms host project. -- Hosting the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] . +- Hosting the WPF . ## Prerequisites @@ -52,7 +52,7 @@ You need the following components to complete this walkthrough: 2. In **Solution Explorer**, add a reference to the WindowsFormsIntegration assembly, which is named WindowsFormsIntegration.dll. -3. Add references to the following [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] assemblies: +3. Add references to the following WPF assemblies: - PresentationCore diff --git a/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-hosting-a-win32-control-in-wpf.md b/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-hosting-a-win32-control-in-wpf.md index 6429fd2..ca5529a 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-hosting-a-win32-control-in-wpf.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-hosting-a-win32-control-in-wpf.md @@ -54,7 +54,7 @@ Windows Presentation Foundation (WPF) provides a rich environment for creating a ## Implement the Page Layout - The layout for the WPF page that hosts the ListBox Control consists of two regions. The left side of the page hosts several WPF controls that provide a [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] that allows you to manipulate the Win32 control. The upper right corner of the page has a square region for the hosted ListBox Control. + The layout for the WPF page that hosts the ListBox Control consists of two regions. The left side of the page hosts several WPF controls that provide a user interface (UI) that allows you to manipulate the Win32 control. The upper right corner of the page has a square region for the hosted ListBox Control. The code to implement this layout is quite simple. The root element is a that has two child elements. The first is a element that hosts the ListBox Control. It occupies a 200x200 square in the upper right corner of the page. The second is a element that contains a set of WPF controls that display information and allow you to manipulate the ListBox Control by setting exposed interoperation properties. For each of the elements that are children of the , see the reference material for the various elements used for details on what these elements are or what they do, these are listed in the example code below but will not be explained here (the basic interoperation model does not require any of them, they are provided to add some interactivity to the sample). diff --git a/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-hosting-a-windows-forms-composite-control-in-wpf.md b/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-hosting-a-windows-forms-composite-control-in-wpf.md index a7ed465..17e8d75 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-hosting-a-windows-forms-composite-control-in-wpf.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-hosting-a-windows-forms-composite-control-in-wpf.md @@ -12,11 +12,11 @@ ms.assetid: 96fcd78d-1c77-4206-8928-3a0579476ef4 --- # Walkthrough: Hosting a Windows Forms Composite Control in WPF -[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides a rich environment for creating applications. However, when you have a substantial investment in Windows Forms code, it can be more effective to reuse at least some of that code in your [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application rather than to rewrite it from scratch. The most common scenario is when you have existing Windows Forms controls. In some cases, you might not even have access to the source code for these controls. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides a straightforward procedure for hosting such controls in a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application. For example, you can use [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] for most of your programming while hosting your specialized controls. +WPF application rather than to rewrite it from scratch. The most common scenario is when you have existing Windows Forms controls. In some cases, you might not even have access to the source code for these controls. WPF provides a straightforward procedure for hosting such controls in a WPF application. For example, you can use WPF for most of your programming while hosting your specialized controls. - This walkthrough steps you through an application that hosts a Windows Forms composite control to perform data entry in a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application. The composite control is packaged in a DLL. This general procedure can be extended to more complex applications and controls. This walkthrough is designed to be nearly identical in appearance and functionality to [Walkthrough: Hosting a WPF Composite Control in Windows Forms](walkthrough-hosting-a-wpf-composite-control-in-windows-forms.md). The primary difference is that the hosting scenario is reversed. + This walkthrough steps you through an application that hosts a Windows Forms composite control to perform data entry in a WPF application. The composite control is packaged in a DLL. This general procedure can be extended to more complex applications and controls. This walkthrough is designed to be nearly identical in appearance and functionality to [Walkthrough: Hosting a WPF Composite Control in Windows Forms](walkthrough-hosting-a-wpf-composite-control-in-windows-forms.md). The primary difference is that the hosting scenario is reversed. - The walkthrough is divided into two sections. The first section briefly describes the implementation of the Windows Forms composite control. The second section discusses in detail how to host the composite control in a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application, receive events from the control, and access some of the control's properties. + The walkthrough is divided into two sections. The first section briefly describes the implementation of the Windows Forms composite control. The second section discusses in detail how to host the composite control in a WPF application, receive events from the control, and access some of the control's properties. Tasks illustrated in this walkthrough include: @@ -111,7 +111,7 @@ You need Visual Studio to complete this walkthrough. ### Giving the Assembly a Strong Name and Building the Assembly - For this assembly to be referenced by a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application, it must have a strong name. To create a strong name, create a key file with Sn.exe and add it to your project. + For this assembly to be referenced by a WPF application, it must have a strong name. To create a strong name, create a key file with Sn.exe and add it to your project. 1. Open a Visual Studio command prompt. To do so, click the **Start** menu, and then select **All Programs/Microsoft Visual Studio 2010/Visual Studio Tools/Visual Studio Command Prompt**. This launches a console window with customized environment variables. @@ -129,7 +129,7 @@ You need Visual Studio to complete this walkthrough. ## Implementing the WPF Host Application - The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] host application uses the control to host `MyControl1`. The application handles the `OnButtonClick` event to receive the data from the control. It also has a collection of option buttons that enable you to change some of the control's properties from the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application. The following illustration shows the finished application. + The WPF host application uses the control to host `MyControl1`. The application handles the `OnButtonClick` event to receive the data from the control. It also has a collection of option buttons that enable you to change some of the control's properties from the WPF application. The following illustration shows the finished application. The following image shows the complete application, including the control embedded in the WPF application: @@ -161,7 +161,7 @@ The following image shows the complete application, including the control embedd ### Implementing the Basic Layout - The [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] of the host application is implemented in MainWindow.xaml. This file contains [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] markup that defines the layout, and hosts the Windows Forms control. The application is divided into three regions: + The user interface (UI) of the host application is implemented in MainWindow.xaml. This file contains Extensible Application Markup Language (XAML) markup that defines the layout, and hosts the Windows Forms control. The application is divided into three regions: - The **Control Properties** panel, which contains a collection of option buttons that you can use to modify various properties of the hosted control. @@ -184,17 +184,17 @@ The following image shows the complete application, including the control embedd [!code-xaml[WpfHostingWindowsFormsControl#101](~/samples/snippets/csharp/VS_Snippets_Wpf/WpfHostingWindowsFormsControl/CSharp/WpfHost/Page1.xaml#101)] [!code-xaml[WpfHostingWindowsFormsControl#102](~/samples/snippets/csharp/VS_Snippets_Wpf/WpfHostingWindowsFormsControl/CSharp/WpfHost/Page1.xaml#102)] - The `xmlns` namespace mapping attribute creates a reference to the `MyControls` namespace that contains the hosted control. This mapping enables you to represent `MyControl1` in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] as ``. + The `xmlns` namespace mapping attribute creates a reference to the `MyControls` namespace that contains the hosted control. This mapping enables you to represent `MyControl1` in XAML as ``. Two elements in the XAML handle the hosting: -- `WindowsFormsHost` represents the element that enables you to host a Windows Forms control in a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application. +- `WindowsFormsHost` represents the element that enables you to host a Windows Forms control in a WPF application. -- `mcl:MyControl1`, which represents `MyControl1`, is added to the element's child collection. As a result, this Windows Forms control is rendered as part of the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] window, and you can communicate with the control from the application. +- `mcl:MyControl1`, which represents `MyControl1`, is added to the element's child collection. As a result, this Windows Forms control is rendered as part of the WPF window, and you can communicate with the control from the application. ### Implementing the Code-Behind File - The code-behind file, MainWindow.xaml.vb or MainWindow.xaml.cs, contains the procedural code that implements the functionality of the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] discussed in the preceding section. The primary tasks are: + The code-behind file, MainWindow.xaml.vb or MainWindow.xaml.cs, contains the procedural code that implements the functionality of the UI discussed in the preceding section. The primary tasks are: - Attaching an event handler to `MyControl1`'s `OnButtonClick` event. @@ -211,7 +211,7 @@ The following image shows the complete application, including the control embedd [!code-csharp[WpfHostingWindowsFormsControl#11](~/samples/snippets/csharp/VS_Snippets_Wpf/WpfHostingWindowsFormsControl/CSharp/WpfHost/Page1.xaml.cs#11)] [!code-vb[WpfHostingWindowsFormsControl#11](~/samples/snippets/visualbasic/VS_Snippets_Wpf/WpfHostingWindowsFormsControl/VisualBasic/WpfHost/Page1.xaml.vb#11)] - Because the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] discussed previously added `MyControl1` to the element's child element collection, you can cast the element's to get the reference to `MyControl1`. You can then use that reference to attach an event handler to `OnButtonClick`. + Because the XAML discussed previously added `MyControl1` to the element's child element collection, you can cast the element's to get the reference to `MyControl1`. You can then use that reference to attach an event handler to `OnButtonClick`. In addition to providing a reference to the control itself, exposes a number of the control's properties, which you can manipulate from the application. The initialization code assigns those values to private global variables for later use in the application. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-hosting-a-windows-forms-control-in-wpf-by-using-xaml.md b/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-hosting-a-windows-forms-control-in-wpf-by-using-xaml.md index 2146f17..7e07cfa 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-hosting-a-windows-forms-control-in-wpf-by-using-xaml.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-hosting-a-windows-forms-control-in-wpf-by-using-xaml.md @@ -7,9 +7,9 @@ helpviewer_keywords: ms.assetid: 1aef42cb-4cfb-44b4-9a7a-c02632d3d9c7 --- # Walkthrough: Hosting a Windows Forms Control in WPF by Using XAML -[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides many controls with a rich feature set. However, you may sometimes want to use Windows Forms controls on your [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] pages. For example, you may have a substantial investment in existing Windows Forms controls, or you may have a Windows Forms control that provides unique functionality. +WPF provides many controls with a rich feature set. However, you may sometimes want to use Windows Forms controls on your WPF pages. For example, you may have a substantial investment in existing Windows Forms controls, or you may have a Windows Forms control that provides unique functionality. - This walkthrough shows you how to host a Windows Forms control on a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] page by using [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]. + This walkthrough shows you how to host a Windows Forms control on a WPF page by using XAML. For a complete code listing of the tasks shown in this walkthrough, see [Hosting a Windows Forms Control in WPF by Using XAML Sample](https://github.com/Microsoft/WPF-Samples/tree/master/Migration%20and%20Interoperability/HostingWfInWpfWithXaml). diff --git a/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-hosting-a-windows-forms-control-in-wpf.md b/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-hosting-a-windows-forms-control-in-wpf.md index e3c9884..b5b1270 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-hosting-a-windows-forms-control-in-wpf.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-hosting-a-windows-forms-control-in-wpf.md @@ -12,9 +12,9 @@ ms.assetid: 9cb88415-39b0-4c46-80c4-ff325b674286 --- # Walkthrough: Hosting a Windows Forms Control in WPF -[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides many controls with a rich feature set. However, you may sometimes want to use Windows Forms controls on your [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] pages. For example, you may have a substantial investment in existing Windows Forms controls, or you may have a Windows Forms control that provides unique functionality. +WPF provides many controls with a rich feature set. However, you may sometimes want to use Windows Forms controls on your WPF pages. For example, you may have a substantial investment in existing Windows Forms controls, or you may have a Windows Forms control that provides unique functionality. -This walkthrough shows you how to host a Windows Forms control on a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] page by using code. +This walkthrough shows you how to host a Windows Forms control on a WPF page by using code. For a complete code listing of the tasks shown in this walkthrough, see [Hosting a Windows Forms Control in WPF Sample](https://github.com/Microsoft/WPF-Samples/tree/master/Migration%20and%20Interoperability/HostingWfInWPF). diff --git a/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-hosting-a-wpf-clock-in-win32.md b/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-hosting-a-wpf-clock-in-win32.md index b6c4508..3641299 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-hosting-a-wpf-clock-in-win32.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-hosting-a-wpf-clock-in-win32.md @@ -10,7 +10,7 @@ ms.assetid: 555e55a7-0851-4ec8-b1c6-0acba7e9b648 --- # Walkthrough: Host a WPF Clock in Win32 -To put [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] inside Win32 applications, use , which provides the HWND that contains your [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content. First you create the , giving it parameters similar to CreateWindow. Then you tell the about the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content you want inside it. Finally, you get the HWND out of the . This walkthrough illustrates how to create a mixed [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] inside Win32 application that reimplements the operating system **Date and Time Properties** dialog. +To put WPF inside Win32 applications, use , which provides the HWND that contains your WPF content. First you create the , giving it parameters similar to CreateWindow. Then you tell the about the WPF content you want inside it. Finally, you get the HWND out of the . This walkthrough illustrates how to create a mixed WPF inside Win32 application that reimplements the operating system **Date and Time Properties** dialog. ## Prerequisites @@ -18,7 +18,7 @@ See [WPF and Win32 Interoperation](wpf-and-win32-interoperation.md). ## How to Use This Tutorial -This tutorial concentrates on the important steps of producing an interoperation application. The tutorial is backed by a sample, [Win32 Clock Interoperation Sample](https://github.com/Microsoft/WPF-Samples/tree/master/Migration%20and%20Interoperability/Win32Clock), but that sample is reflective of the end product. This tutorial documents the steps as if you were starting with an existing Win32 project of your own, perhaps a pre-existing project, and you were adding a hosted [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] to your application. You can compare your end product with [Win32 Clock Interoperation Sample](https://github.com/Microsoft/WPF-Samples/tree/master/Migration%20and%20Interoperability/Win32Clock). +This tutorial concentrates on the important steps of producing an interoperation application. The tutorial is backed by a sample, [Win32 Clock Interoperation Sample](https://github.com/Microsoft/WPF-Samples/tree/master/Migration%20and%20Interoperability/Win32Clock), but that sample is reflective of the end product. This tutorial documents the steps as if you were starting with an existing Win32 project of your own, perhaps a pre-existing project, and you were adding a hosted WPF to your application. You can compare your end product with [Win32 Clock Interoperation Sample](https://github.com/Microsoft/WPF-Samples/tree/master/Migration%20and%20Interoperability/Win32Clock). ## A Walkthrough of Windows Presentation Framework Inside Win32 (HwndSource) @@ -32,13 +32,13 @@ You can recreate this dialog by creating a C++ Win32 project in Visual Studio, a (You do not need to use Visual Studio to use , and you do not need to use C++ to write Win32 programs, but this is a fairly typical way to do it, and lends itself well to a stepwise tutorial explanation). -You need to accomplish five particular substeps in order to put a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] clock into the dialog: +You need to accomplish five particular substeps in order to put a WPF clock into the dialog: 1. Enable your Win32 project to call managed code (**/clr**) by changing project settings in Visual Studio. -2. Create a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] in a separate DLL. +2. Create a WPF in a separate DLL. -3. Put that [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] inside an . +3. Put that WPF inside an . 4. Get an HWND for that using the property. @@ -46,11 +46,11 @@ You need to accomplish five particular substeps in order to put a [!INCLUDE[TLA2 ## /clr -The first step is to turn this unmanaged Win32 project into one that can call managed code. You use the /clr compiler option, which will link to the necessary DLLs you want to use, and adjust the Main method for use with [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. +The first step is to turn this unmanaged Win32 project into one that can call managed code. You use the /clr compiler option, which will link to the necessary DLLs you want to use, and adjust the Main method for use with WPF. To enable the use of managed code inside the C++ project: Right-click on win32clock project and select **Properties**. On the **General** property page (the default), change Common Language Runtime support to `/clr`. -Next, add references to DLLs necessary for [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]: PresentationCore.dll, PresentationFramework.dll, System.dll, WindowsBase.dll, UIAutomationProvider.dll, and UIAutomationTypes.dll. (Following instructions assume the operating system is installed on C: drive.) +Next, add references to DLLs necessary for WPF: PresentationCore.dll, PresentationFramework.dll, System.dll, WindowsBase.dll, UIAutomationProvider.dll, and UIAutomationTypes.dll. (Following instructions assume the operating system is installed on C: drive.) 1. Right-click win32clock project and select **References...**, and inside that dialog: @@ -70,7 +70,7 @@ Next, add references to DLLs necessary for [!INCLUDE[TLA2#tla_winclient](../../. 9. Click **OK** to exit the win32clock Property Pages for adding references. - Finally, add the `STAThreadAttribute` to the `_tWinMain` method for use with [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]: + Finally, add the `STAThreadAttribute` to the `_tWinMain` method for use with WPF: ```cpp [System::STAThreadAttribute] @@ -80,15 +80,15 @@ int APIENTRY _tWinMain(HINSTANCE hInstance, int nCmdShow) ``` -This attribute tells the common language runtime (CLR) that when it initializes Component Object Model (COM), it should use a single threaded apartment model (STA), which is necessary for [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] (and Windows Forms). +This attribute tells the common language runtime (CLR) that when it initializes Component Object Model (COM), it should use a single threaded apartment model (STA), which is necessary for WPF (and Windows Forms). ## Create a Windows Presentation Framework Page -Next, you create a DLL that defines a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. It’s often easiest to create the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] as a standalone application, and write and debug the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] portion that way. Once done, that project can be turned into a DLL by right-clicking the project, clicking on **Properties**, going to the Application, and changing Output type to Windows Class Library. +Next, you create a DLL that defines a WPF. It’s often easiest to create the WPF as a standalone application, and write and debug the WPF portion that way. Once done, that project can be turned into a DLL by right-clicking the project, clicking on **Properties**, going to the Application, and changing Output type to Windows Class Library. -The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] dll project can then be combined with the Win32 project (one solution that contains two projects) – right-click on the solution, select **Add\Existing Project**. +The WPF dll project can then be combined with the Win32 project (one solution that contains two projects) – right-click on the solution, select **Add\Existing Project**. -To use that [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] dll from the Win32 project, you need to add a reference: +To use that WPF dll from the Win32 project, you need to add a reference: 1. Right-click win32clock project and select **References...**. @@ -100,7 +100,7 @@ To use that [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclie ## HwndSource -Next, you use to make the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] look like an HWND. You add this block of code to a C++ file: +Next, you use to make the WPF look like an HWND. You add this block of code to a C++ file: ```cpp namespace ManagedCode @@ -139,7 +139,7 @@ namespace ManagedCode using namespace System::Windows::Media; ``` - Then you define a function that creates the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content, puts an around it, and returns the HWND: + Then you define a function that creates the WPF content, puts an around it, and returns the HWND: ```cpp HWND GetHwnd(HWND parent, int x, int y, int width, int height) { @@ -158,7 +158,7 @@ HwndSource^ source = gcnew HwndSource( ); ``` -Then you create the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content class by calling its constructor: +Then you create the WPF content class by calling its constructor: ```cpp UIElement^ page = gcnew WPFClock::Clock(); @@ -178,7 +178,7 @@ return (HWND) source->Handle.ToPointer(); ## Positioning the Hwnd -Now that you have an HWND that contains the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] clock, you need to put that HWND inside the Win32 dialog. If you knew just where to put the HWND, you would just pass that size and location to the `GetHwnd` function you defined earlier. But you used a resource file to define the dialog, so you are not exactly sure where any of the HWNDs are positioned. You can use the Visual Studio dialog editor to put a Win32 STATIC control where you want the clock to go ("Insert clock here"), and use that to position the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] clock. +Now that you have an HWND that contains the WPF clock, you need to put that HWND inside the Win32 dialog. If you knew just where to put the HWND, you would just pass that size and location to the `GetHwnd` function you defined earlier. But you used a resource file to define the dialog, so you are not exactly sure where any of the HWNDs are positioned. You can use the Visual Studio dialog editor to put a Win32 STATIC control where you want the clock to go ("Insert clock here"), and use that to position the WPF clock. Where you handle WM_INITDIALOG, you use `GetDlgItem` to retrieve the HWND for the placeholder STATIC: @@ -186,7 +186,7 @@ Where you handle WM_INITDIALOG, you use `GetDlgItem` to retrieve the HWND for th HWND placeholder = GetDlgItem(hDlg, IDC_CLOCK); ``` -You then calculate the size and position of that placeholder STATIC, so you can put the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] clock in that place: +You then calculate the size and position of that placeholder STATIC, so you can put the WPF clock in that place: RECT rectangle; @@ -206,13 +206,13 @@ Then you hide the placeholder STATIC: ShowWindow(placeholder, SW_HIDE); ``` -And create the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] clock HWND in that location: +And create the WPF clock HWND in that location: ```cpp HWND clock = ManagedCode::GetHwnd(hDlg, point.x, point.y, width, height); ``` -To make the tutorial interesting, and to produce a real [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] clock, you will need to create a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] clock control at this point. You can do so mostly in markup, with just a few event handlers in code-behind. Since this tutorial is about interoperation and not about control design, complete code for the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] clock is provided here as a code block, without discrete instructions for building it up or what each part means. Feel free to experiment with this code to change the look and feel or functionality of the control. +To make the tutorial interesting, and to produce a real WPF clock, you will need to create a WPF clock control at this point. You can do so mostly in markup, with just a few event handlers in code-behind. Since this tutorial is about interoperation and not about control design, complete code for the WPF clock is provided here as a code block, without discrete instructions for building it up or what each part means. Feel free to experiment with this code to change the look and feel or functionality of the control. Here is the markup: diff --git a/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-hosting-a-wpf-composite-control-in-windows-forms.md b/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-hosting-a-wpf-composite-control-in-windows-forms.md index d461245..843016c 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-hosting-a-wpf-composite-control-in-windows-forms.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-hosting-a-wpf-composite-control-in-windows-forms.md @@ -7,11 +7,11 @@ helpviewer_keywords: ms.assetid: 0ac41286-4c1b-4b17-9196-d985cb844ce1 --- # Walkthrough: Hosting a WPF Composite Control in Windows Forms -[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides a rich environment for creating applications. However, when you have a substantial investment in Windows Forms code, it can be more effective to extend your existing Windows Forms application with [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] rather than to rewrite it from scratch. A common scenario is when you want to embed one or more controls implemented with [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] within your Windows Forms application. For more information about customizing WPF controls, see [Control Customization](../controls/control-customization.md). +WPF rather than to rewrite it from scratch. A common scenario is when you want to embed one or more controls implemented with WPF within your Windows Forms application. For more information about customizing WPF controls, see [Control Customization](../controls/control-customization.md). - This walkthrough steps you through an application that hosts a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] composite control to perform data-entry in a Windows Forms application. The composite control is packaged in a DLL. This general procedure can be extended to more complex applications and controls. This walkthrough is designed to be nearly identical in appearance and functionality to [Walkthrough: Hosting a Windows Forms Composite Control in WPF](walkthrough-hosting-a-windows-forms-composite-control-in-wpf.md). The primary difference is that the hosting scenario is reversed. + This walkthrough steps you through an application that hosts a WPF composite control to perform data-entry in a Windows Forms application. The composite control is packaged in a DLL. This general procedure can be extended to more complex applications and controls. This walkthrough is designed to be nearly identical in appearance and functionality to [Walkthrough: Hosting a Windows Forms Composite Control in WPF](walkthrough-hosting-a-windows-forms-composite-control-in-wpf.md). The primary difference is that the hosting scenario is reversed. - The walkthrough is divided into two sections. The first section briefly describes the implementation of the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] composite control. The second section discusses in detail how to host the composite control in a Windows Forms application, receive events from the control, and access some of the control's properties. + The walkthrough is divided into two sections. The first section briefly describes the implementation of the WPF composite control. The second section discusses in detail how to host the composite control in a Windows Forms application, receive events from the control, and access some of the control's properties. Tasks illustrated in this walkthrough include: @@ -26,7 +26,7 @@ ms.assetid: 0ac41286-4c1b-4b17-9196-d985cb844ce1 You need Visual Studio to complete this walkthrough. ## Implementing the WPF Composite Control - The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] composite control used in this example is a simple data-entry form that takes the user's name and address. When the user clicks one of two buttons to indicate that the task is finished, the control raises a custom event to return that information to the host. The following illustration shows the rendered control. + The WPF composite control used in this example is a simple data-entry form that takes the user's name and address. When the user clicks one of two buttons to indicate that the task is finished, the control raises a custom event to return that information to the host. The following illustration shows the rendered control. The following image shows a WPF composite control: @@ -58,10 +58,10 @@ You need Visual Studio to complete this walkthrough. - WindowsBase ### Creating the User Interface - The [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] for the composite control is implemented with [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)]. The composite control [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] consists of five elements. Each element has an associated element that serves as a label. There are two elements at the bottom, **OK** and **Cancel**. When the user clicks either button, the control raises a custom event to return the information to the host. + The UI consists of five elements. Each element has an associated element that serves as a label. There are two elements at the bottom, **OK** and **Cancel**. When the user clicks either button, the control raises a custom event to return the information to the host. #### Basic Layout - The various [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] elements are contained in a element. You can use to arrange the contents of the composite control in much the same way you would use a `Table` element in HTML. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] also has a element, but is more lightweight and better suited for simple layout tasks. + The various UI elements are contained in a element. You can use to arrange the contents of the composite control in much the same way you would use a `Table` element in HTML. WPF also has a element, but is more lightweight and better suited for simple layout tasks. The following XAML shows the basic layout. This XAML defines the overall structure of the control by specifying the number of columns and rows in the element. @@ -71,7 +71,7 @@ You need Visual Studio to complete this walkthrough. [!code-xaml[WindowsFormsHostingWpfControl#102](~/samples/snippets/csharp/VS_Snippets_Wpf/WindowsFormsHostingWpfControl/CSharp/MyControls/Page1.xaml#102)] #### Adding TextBlock and TextBox Elements to the Grid - You place a [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] element in the grid by setting the element's and attributes to the appropriate row and column number. Remember that row and column numbering are zero-based. You can have an element span multiple columns by setting its attribute. For more information about elements, see [Create a Grid Element](../controls/how-to-create-a-grid-element.md). + You place a UI element in the grid by setting the element's and attributes to the appropriate row and column number. Remember that row and column numbering are zero-based. You can have an element span multiple columns by setting its attribute. For more information about elements, see [Create a Grid Element](../controls/how-to-create-a-grid-element.md). The following XAML shows the composite control's and elements with their and attributes, which are set to place the elements properly in the grid. @@ -82,7 +82,7 @@ You need Visual Studio to complete this walkthrough. #### Styling the UI Elements Many of the elements on the data-entry form have a similar appearance, which means that they have identical settings for several of their properties. Rather than setting each element's attributes separately, the previous XAML uses elements to define standard property settings for classes of elements. This approach reduces the complexity of the control and enables you to change the appearance of multiple elements through a single style attribute. - The elements are contained in the element's property, so they can be used by all elements in the control. If a style is named, you apply it to an element by adding a element set to the style's name. Styles that are not named become the default style for the element. For more information about [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] styles, see [Styling and Templating](../controls/styles-templates-overview.md). + The elements are contained in the element's property, so they can be used by all elements in the control. If a style is named, you apply it to an element by adding a element set to the style's name. Styles that are not named become the default style for the element. For more information about WPF styles, see [Styling and Templating](../controls/styles-templates-overview.md). The following XAML shows the elements for the composite control. To see how the styles are applied to elements, see the previous XAML. For example, the last element has the `inlineText` style, and the last element uses the default style. @@ -93,7 +93,7 @@ You need Visual Studio to complete this walkthrough. #### Adding the OK and Cancel Buttons The final elements on the composite control are the **OK** and **Cancel** elements, which occupy the first two columns of the last row of the . These elements use a common event handler, `ButtonClicked`, and the default style defined in the previous XAML. - In MyControl1.xaml, add the following XAML after the last element. The [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] part of the composite control is now complete. + In MyControl1.xaml, add the following XAML after the last element. The XAML part of the composite control is now complete. [!code-xaml[WindowsFormsHostingWpfControl#105](~/samples/snippets/csharp/VS_Snippets_Wpf/WindowsFormsHostingWpfControl/CSharp/MyControls/Page1.xaml#105)] @@ -125,7 +125,7 @@ namespace MyControls } ``` - The first class, `MyControl1`, is a partial class containing the code that implements the functionality of the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] defined in MyControl1.xaml. When MyControl1.xaml is parsed, the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] is converted to the same partial class, and the two partial classes are merged to form the compiled control. For this reason, the class name in the code-behind file must match the class name assigned to MyControl1.xaml, and it must inherit from the root element of the control. The second class, `MyControlEventArgs`, is an event arguments class that is used to send the data back to the host. + The first class, `MyControl1`, is a partial class containing the code that implements the functionality of the UI defined in MyControl1.xaml. When MyControl1.xaml is parsed, the XAML is converted to the same partial class, and the two partial classes are merged to form the compiled control. For this reason, the class name in the code-behind file must match the class name assigned to MyControl1.xaml, and it must inherit from the root element of the control. The second class, `MyControlEventArgs`, is an event arguments class that is used to send the data back to the host. Open MyControl1.xaml.cs. Change the existing class declaration so that it has the following name and inherits from . @@ -175,7 +175,7 @@ namespace MyControls ## Implementing the Windows Forms Host Application - The Windows Forms host application uses an object to host the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] composite control. The application handles the `OnButtonClick` event to receive the data from the composite control. The application also has a set of option buttons that you can use to modify the control's appearance. The following illustration shows the application. + The Windows Forms host application uses an object to host the WPF composite control. The application handles the `OnButtonClick` event to receive the data from the composite control. The application also has a set of option buttons that you can use to modify the control's appearance. The following illustration shows the application. The following image shows a WPF composite control hosted in a Windows Forms application @@ -221,7 +221,7 @@ The following image shows a WPF composite control hosted in a Windows Forms appl 2. Enlarge the form to accommodate the controls. -3. In the upper-right corner of the form, add a control to hold the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] composite control. +3. In the upper-right corner of the form, add a control to hold the WPF composite control. 4. Add the following controls to the form. @@ -256,7 +256,7 @@ The following image shows a WPF composite control hosted in a Windows Forms appl |groupBox6|radioWeightOriginal|Original| |groupBox6|radioWeightBold|Bold| -6. Add the following controls to the last . These controls display the data returned by the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] composite control. +6. Add the following controls to the last . These controls display the data returned by the WPF composite control. |GroupBox|Name|Text| |--------------|----------|----------| @@ -267,7 +267,7 @@ The following image shows a WPF composite control hosted in a Windows Forms appl |groupBox7|lblZip|Zip:| ### Initializing the Form - You generally implement the hosting code in the form's event handler. The following code shows the event handler, a handler for the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] composite control's event, and declarations for several global variables that are used later. + You generally implement the hosting code in the form's event handler. The following code shows the event handler, a handler for the WPF composite control's event, and declarations for several global variables that are used later. In the Windows Forms Designer, double-click the form to create a event handler. At the top of Form1.cs, add the following `using` statements. @@ -277,7 +277,7 @@ The following image shows a WPF composite control hosted in a Windows Forms appl [!code-csharp[WindowsFormsHostingWpfControl#2](~/samples/snippets/csharp/VS_Snippets_Wpf/WindowsFormsHostingWpfControl/CSharp/WFHost/Form1.cs#2)] - The `Form1_Load` method in the preceding code shows the general procedure for hosting a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] control: + The `Form1_Load` method in the preceding code shows the general procedure for hosting a WPF control: 1. Create a new object. @@ -285,7 +285,7 @@ The following image shows a WPF composite control hosted in a Windows Forms appl 3. Add the control to the control's collection. -4. Create an instance of the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] control. +4. Create an instance of the WPF control. 5. Host the composite control on the form by assigning the control to the control's property. @@ -293,7 +293,7 @@ The following image shows a WPF composite control hosted in a Windows Forms appl - `OnButtonClick` is a custom event that is fired by the composite control when the user clicks the **OK** or **Cancel** button. You handle the event to get the user's response and to collect any data that the user specified. -- is a standard event that is raised by a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] control when it is fully loaded. The event is used here because the example needs to initialize several global variables using properties from the control. At the time of the form's event, the control is not fully loaded and those values are still set to `null`. You need to wait until the control's event occurs before you can access those properties. +- is a standard event that is raised by a WPF control when it is fully loaded. The event is used here because the example needs to initialize several global variables using properties from the control. At the time of the form's event, the control is not fully loaded and those values are still set to `null`. You need to wait until the control's event occurs before you can access those properties. The event handler is shown in the preceding code. The `OnButtonClick` handler is discussed in the next section. @@ -309,7 +309,7 @@ The following image shows a WPF composite control hosted in a Windows Forms appl Build and run the application. Add some text in the WPF composite control and then click **OK**. The text appears in the labels. At this point, code has not been added to handle the radio buttons. ### Modifying the Appearance of the Control - The controls on the form will enable the user to change the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] composite control's foreground and background colors as well as several font properties. The background color is exposed by the object. The remaining properties are exposed as custom properties of the control. + The controls on the form will enable the user to change the WPF composite control's foreground and background colors as well as several font properties. The background color is exposed by the object. The remaining properties are exposed as custom properties of the control. Double-click each control on the form to create event handlers. Replace the event handlers with the following code. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-hosting-an-activex-control-in-wpf.md b/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-hosting-an-activex-control-in-wpf.md index b40601b..9adb3f3 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-hosting-an-activex-control-in-wpf.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-hosting-an-activex-control-in-wpf.md @@ -11,7 +11,7 @@ helpviewer_keywords: ms.assetid: 1931d292-0dd1-434f-963c-dcda7638d75a --- # Walkthrough: Hosting an ActiveX Control in WPF -To enable improved interaction with browsers, you can use Microsoft ActiveX controls in your [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]-based application. This walkthrough demonstrates how you can host the Microsoft Windows Media Player as a control on a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] page. +To enable improved interaction with browsers, you can use Microsoft ActiveX controls in your WPF-based application. This walkthrough demonstrates how you can host the Microsoft Windows Media Player as a control on a WPF page. Tasks illustrated in this walkthrough include: @@ -21,7 +21,7 @@ To enable improved interaction with browsers, you can use Microsoft ActiveX cont - Hosting the ActiveX control on a WPF Page. - When you have completed this walkthrough, you will understand how to use Microsoft ActiveX controls in your [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]-based application. + When you have completed this walkthrough, you will understand how to use Microsoft ActiveX controls in your WPF-based application. ## Prerequisites You need the following components to complete this walkthrough: diff --git a/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-hosting-wpf-content-in-win32.md b/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-hosting-wpf-content-in-win32.md index a423b6f..b5445b8 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-hosting-wpf-content-in-win32.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-hosting-wpf-content-in-win32.md @@ -9,13 +9,13 @@ helpviewer_keywords: ms.assetid: 38ce284a-4303-46dd-b699-c9365b22a7dc --- # Walkthrough: Hosting WPF Content in Win32 -[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides a rich environment for creating applications. However, when you have a substantial investment in Win32 code, it might be more effective to add [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] functionality to your application rather than rewriting your original code. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides a straightforward mechanism for hosting [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content in a Win32 window. +WPF functionality to your application rather than rewriting your original code. WPF provides a straightforward mechanism for hosting WPF content in a Win32 window. - This tutorial describes how to write a sample application, [Hosting WPF Content in a Win32 Window Sample](https://github.com/Microsoft/WPF-Samples/tree/master/Migration%20and%20Interoperability/Win32HostingWPFPage), that hosts [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content in a Win32 window. You can extend this sample to host any Win32 window. Because it involves mixing managed and unmanaged code, the application is written in C++/CLI. + This tutorial describes how to write a sample application, [Hosting WPF Content in a Win32 Window Sample](https://github.com/Microsoft/WPF-Samples/tree/master/Migration%20and%20Interoperability/Win32HostingWPFPage), that hosts WPF content in a Win32 window. You can extend this sample to host any Win32 window. Because it involves mixing managed and unmanaged code, the application is written in C++/CLI. ## Requirements - This tutorial assumes a basic familiarity with both [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] and Win32 programming. For a basic introduction to [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] programming, see [Getting Started](../getting-started/index.md). For an introduction to Win32 programming, you should reference any of the numerous books on the subject, in particular *Programming Windows* by Charles Petzold. + This tutorial assumes a basic familiarity with both WPF and Win32 programming. For a basic introduction to WPF programming, see [Getting Started](../getting-started/index.md). For an introduction to Win32 programming, you should reference any of the numerous books on the subject, in particular *Programming Windows* by Charles Petzold. Because the sample that accompanies this tutorial is implemented in C++/CLI, this tutorial assumes familiarity with the use of C++ to program the Windows API plus an understanding of managed code programming. Familiarity with C++/CLI is helpful but not essential. @@ -24,11 +24,11 @@ ms.assetid: 38ce284a-4303-46dd-b699-c9365b22a7dc ## The Basic Procedure - This section outlines the basic procedure you use to host [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content in a Win32 window. The remaining sections explain the details of each step. + This section outlines the basic procedure you use to host WPF content in a Win32 window. The remaining sections explain the details of each step. - The key to hosting [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content on a Win32 window is the class. This class wraps the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content in a Win32 window, allowing it to be incorporated into your [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] as a child window. The following approach combines the Win32 and [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] in a single application. + The key to hosting WPF content on a Win32 window is the class. This class wraps the WPF content in a Win32 window, allowing it to be incorporated into your WPF in a single application. -1. Implement your [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content as a managed class. +1. Implement your WPF content as a managed class. 2. Implement a Windows application with C++/CLI. If you are starting with an existing application and unmanaged C++ code, you can usually enable it to call managed code by changing your project settings to include the `/clr` compiler flag. @@ -38,26 +38,26 @@ ms.assetid: 38ce284a-4303-46dd-b699-c9365b22a7dc 1. Create a new object with the parent window as its `parent` parameter. - 2. Create an instance of your [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content class. + 2. Create an instance of your WPF content class. - 3. Assign a reference to the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content object to the property of the . + 3. Assign a reference to the WPF content object to the property of the . 4. Get the HWND for the content. The property of the object contains the window handle (HWND). To get an HWND that you can use in the unmanaged part of your application, cast `Handle.ToPointer()` to an HWND. -5. Implement a managed class that contains a static field to hold a reference to your [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content. This class allows you to get a reference to the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content from your Win32 code. +5. Implement a managed class that contains a static field to hold a reference to your WPF content. This class allows you to get a reference to the WPF content from your Win32 code. -6. Assign the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content to the static field. +6. Assign the WPF content to the static field. -7. Receive notifications from the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content by attaching a handler to one or more of the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] events. +7. Receive notifications from the WPF content by attaching a handler to one or more of the WPF events. -8. Communicate with the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content by using the reference that you stored in the static field to set properties, and so on. +8. Communicate with the WPF content by using the reference that you stored in the static field to set properties, and so on. > [!NOTE] -> You can also use [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] to implement your [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content. However, you will have to compile it separately as a dynamic-link library (DLL) and reference that DLL from your Win32 application. The remainder of the procedure is similar to that outlined above. +> You can also use WPF content. However, you will have to compile it separately as a dynamic-link library (DLL) and reference that DLL from your Win32 application. The remainder of the procedure is similar to that outlined above. ## Implementing the Host Application - This section describes how to host [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content in a basic Win32 application. The content itself is implemented in C++/CLI as a managed class. For the most part, it is straightforward [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] programming. The key aspects of the content implementation are discussed in [Implementing the WPF Content](#implementing_the_wpf_page). + This section describes how to host WPF content in a basic Win32 application. The content itself is implemented in C++/CLI as a managed class. For the most part, it is straightforward WPF programming. The key aspects of the content implementation are discussed in [Implementing the WPF Content](#implementing_the_wpf_page). - [The Basic Application](#the_basic_application) @@ -87,9 +87,9 @@ ms.assetid: 38ce284a-4303-46dd-b699-c9365b22a7dc - A menu with **File** and **Help** headings. The **File** menu has an **Exit** item that closes the application. The **Help** menu has an **About** item that launches a simple dialog box. - Before you start writing code to host the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content, you need to make two modifications to the basic template. + Before you start writing code to host the WPF content, you need to make two modifications to the basic template. - The first is to compile the project as managed code. By default, the project compiles as unmanaged code. However, because [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] is implemented in managed code, the project must be compiled accordingly. + The first is to compile the project as managed code. By default, the project compiles as unmanaged code. However, because WPF is implemented in managed code, the project must be compiled accordingly. 1. Right-click the project name in **Solution Explorer** and select **Properties** from the context menu to launch the **Property Pages** dialog box. @@ -102,40 +102,40 @@ ms.assetid: 38ce284a-4303-46dd-b699-c9365b22a7dc > [!NOTE] > This compiler flag allows you to use managed code in your application, but your unmanaged code will still compile as before. - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] uses the single-threaded apartment (STA) threading model. In order to work properly with the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content code, you must set the application's threading model to STA by applying an attribute to the entry point. + WPF uses the single-threaded apartment (STA) threading model. In order to work properly with the WPF content code, you must set the application's threading model to STA by applying an attribute to the entry point. [!code-cpp[Win32HostingWPFPage#WinMain](~/samples/snippets/cpp/VS_Snippets_Wpf/Win32HostingWPFPage/CPP/Win32HostingWPFPage.cpp#winmain)] ### Hosting the WPF Content - The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content is a simple address entry application. It consists of several controls to take user name, address, and so on. There are also two controls, **OK** and **Cancel**. When the user clicks **OK**, the button's event handler collects the data from the controls, assigns it to corresponding properties, and raises a custom event, `OnButtonClicked`. When the user clicks **Cancel**, the handler simply raises `OnButtonClicked`. The event argument object for `OnButtonClicked` contains a Boolean field that indicates which button was clicked. + The WPF content is a simple address entry application. It consists of several controls to take user name, address, and so on. There are also two controls, **OK** and **Cancel**. When the user clicks **OK**, the button's event handler collects the data from the controls, assigns it to corresponding properties, and raises a custom event, `OnButtonClicked`. When the user clicks **Cancel**, the handler simply raises `OnButtonClicked`. The event argument object for `OnButtonClicked` contains a Boolean field that indicates which button was clicked. - The code to host the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content is implemented in a handler for the [WM_CREATE](/windows/desktop/winmsg/wm-create) notification on the host window. + The code to host the WPF content is implemented in a handler for the [WM_CREATE](/windows/desktop/winmsg/wm-create) notification on the host window. [!code-cpp[Win32HostingWPFPage#WMCreate](~/samples/snippets/cpp/VS_Snippets_Wpf/Win32HostingWPFPage/CPP/Win32HostingWPFPage.cpp#wmcreate)] - The `GetHwnd` method takes size and position information plus the parent window handle and returns the window handle of the hosted [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content. + The `GetHwnd` method takes size and position information plus the parent window handle and returns the window handle of the hosted WPF content. > [!NOTE] > You cannot use a `#using` directive for the `System::Windows::Interop` namespace. Doing so creates a name collision between the structure in that namespace and the MSG structure declared in winuser.h. You must instead use fully-qualified names to access the contents of that namespace. [!code-cpp[Win32HostingWPFPage#GetHwnd](~/samples/snippets/cpp/VS_Snippets_Wpf/Win32HostingWPFPage/CPP/Win32HostingWPFPage.cpp#gethwnd)] - You cannot host the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content directly in your application window. Instead, you first create an object to wrap the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content. This object is basically a window that is designed to host a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content. You host the object in the parent window by creating it as a child of a Win32 window that is part of your application. The constructor parameters contain much the same information that you would pass to CreateWindow when you create a Win32 child window. + You cannot host the WPF content directly in your application window. Instead, you first create an object to wrap the WPF content. This object is basically a window that is designed to host a WPF content. You host the object in the parent window by creating it as a child of a Win32 window that is part of your application. The constructor parameters contain much the same information that you would pass to CreateWindow when you create a Win32 child window. - You next create an instance of the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content object. In this case, the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content is implemented as a separate class, `WPFPage`, using C++/CLI. You could also implement the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content with [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]. However, to do so you need to set up a separate project and build the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content as a DLL. You can add a reference to that DLL to your project, and use that reference to create an instance of the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content. + You next create an instance of the WPF content object. In this case, the WPF content is implemented as a separate class, `WPFPage`, using C++/CLI. You could also implement the WPF content with WPF content as a DLL. You can add a reference to that DLL to your project, and use that reference to create an instance of the WPF content. - You display the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content in your child window by assigning a reference to the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content to the property of the . + You display the WPF content in your child window by assigning a reference to the WPF content to the property of the . - The next line of code attaches an event handler, `WPFButtonClicked`, to the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content `OnButtonClicked` event. This handler is called when the user clicks the **OK** or **Cancel** button. See [communicating_with_the_WPF content](#communicating_with_the_page) for further discussion of this event handler. + The next line of code attaches an event handler, `WPFButtonClicked`, to the WPF content `OnButtonClicked` event. This handler is called when the user clicks the **OK** or **Cancel** button. See [communicating_with_the_WPF content](#communicating_with_the_page) for further discussion of this event handler. The final line of code shown returns the window handle (HWND) that is associated with the object. You can use this handle from your Win32 code to send messages to the hosted window, although the sample does not do so. The object raises an event every time it receives a message. To process the messages, call the method to attach a message handler and then process the messages in that handler. ### Holding a Reference to the WPF Content - For many applications, you will want to communicate with the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content later. For example, you might want to modify the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content properties, or perhaps have the object host different [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content. To do this, you need a reference to the object or the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content. The object and its associated [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content remain in memory until you destroy the window handle. However, the variable you assign to the object will go out of scope as soon as you return from the window procedure. The customary way to handle this issue with Win32 applications is to use a static or global variable. Unfortunately, you cannot assign a managed object to those types of variables. You can assign the window handle associated with object to a global or static variable, but that doe not provide access to the object itself. + For many applications, you will want to communicate with the WPF content later. For example, you might want to modify the WPF content properties, or perhaps have the object host different WPF content. To do this, you need a reference to the object or the WPF content. The object and its associated WPF content remain in memory until you destroy the window handle. However, the variable you assign to the object will go out of scope as soon as you return from the window procedure. The customary way to handle this issue with Win32 applications is to use a static or global variable. Unfortunately, you cannot assign a managed object to those types of variables. You can assign the window handle associated with object to a global or static variable, but that doe not provide access to the object itself. - The simplest solution to this issue is to implement a managed class that contains a set of static fields to hold references to any managed objects that you need access to. The sample uses the `WPFPageHost` class to hold a reference to the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content, plus the initial values of a number of its properties that might be changed later by the user. This is defined in the header. + The simplest solution to this issue is to implement a managed class that contains a set of static fields to hold references to any managed objects that you need access to. The sample uses the `WPFPageHost` class to hold a reference to the WPF content, plus the initial values of a number of its properties that might be changed later by the user. This is defined in the header. [!code-cpp[Win32HostingWPFPage#WPFPageHost](~/samples/snippets/cpp/VS_Snippets_Wpf/Win32HostingWPFPage/CPP/Win32HostingWPFPage.h#wpfpagehost)] @@ -143,25 +143,25 @@ ms.assetid: 38ce284a-4303-46dd-b699-c9365b22a7dc ### Communicating with the WPF Content - There are two types of communication with the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content. The application receives information from the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content when the user clicks the **OK** or **Cancel** buttons. The application also has a [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] that allows the user to change various [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content properties, such as the background color or default font size. + There are two types of communication with the UI that allows the user to change various WPF content properties, such as the background color or default font size. - As mentioned above, when the user clicks either button the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content raises an `OnButtonClicked` event. The application attaches a handler to this event to receive these notifications. If the **OK** button was clicked, the handler gets the user information from the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content and displays it in a set of static controls. + As mentioned above, when the user clicks either button the WPF content raises an `OnButtonClicked` event. The application attaches a handler to this event to receive these notifications. If the **OK** button was clicked, the handler gets the user information from the WPF content and displays it in a set of static controls. [!code-cpp[Win32HostingWPFPage#WPFButtonClicked](~/samples/snippets/cpp/VS_Snippets_Wpf/Win32HostingWPFPage/CPP/Win32HostingWPFPage.cpp#wpfbuttonclicked)] - The handler receives a custom event argument object from the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content, `MyPageEventArgs`. The object's `IsOK` property is set to `true` if the **OK** button was clicked, and `false` if the **Cancel** button was clicked. + The handler receives a custom event argument object from the WPF content, `MyPageEventArgs`. The object's `IsOK` property is set to `true` if the **OK** button was clicked, and `false` if the **Cancel** button was clicked. - If the **OK** button was clicked, the handler gets a reference to the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content from the container class. It then collects the user information that is held by the associated [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content properties and uses the static controls to display the information on the parent window. Because the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content data is in the form of a managed string, it has to be marshaled for use by a Win32 control. If the **Cancel** button was clicked, the handler clears the data from the static controls. + If the **OK** button was clicked, the handler gets a reference to the WPF content from the container class. It then collects the user information that is held by the associated WPF content properties and uses the static controls to display the information on the parent window. Because the WPF content data is in the form of a managed string, it has to be marshaled for use by a Win32 control. If the **Cancel** button was clicked, the handler clears the data from the static controls. - The application [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] provides a set of radio buttons that allow the user to modify the background color of the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content, and several font-related properties. The following example is an excerpt from the application's window procedure (WndProc) and its message handling that sets various properties on different messages, including the background color. The others are similar, and are not shown. See the complete sample for details and context. + The application UI provides a set of radio buttons that allow the user to modify the background color of the WPF content, and several font-related properties. The following example is an excerpt from the application's window procedure (WndProc) and its message handling that sets various properties on different messages, including the background color. The others are similar, and are not shown. See the complete sample for details and context. [!code-cpp[Win32HostingWPFPage#WMCommandToBG](~/samples/snippets/cpp/VS_Snippets_Wpf/Win32HostingWPFPage/CPP/Win32HostingWPFPage.cpp#wmcommandtobg)] - To set the background color, get a reference to the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content (`hostedPage`) from `WPFPageHost` and set the background color property to the appropriate color. The sample uses three color options: the original color, light green, or light salmon. The original background color is stored as a static field in the `WPFPageHost` class. To set the other two, you create a new object and pass the constructor a static colors value from the object. + To set the background color, get a reference to the WPF content (`hostedPage`) from `WPFPageHost` and set the background color property to the appropriate color. The sample uses three color options: the original color, light green, or light salmon. The original background color is stored as a static field in the `WPFPageHost` class. To set the other two, you create a new object and pass the constructor a static colors value from the object. ## Implementing the WPF Page - You can host and use the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content without any knowledge of the actual implementation. If the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content had been packaged in a separate DLL, it could have been built in any common language runtime (CLR) language. Following is a brief walkthrough of the C++/CLI implementation that is used in the sample. This section contains the following subsections. + You can host and use the WPF content without any knowledge of the actual implementation. If the WPF content had been packaged in a separate DLL, it could have been built in any common language runtime (CLR) language. Following is a brief walkthrough of the C++/CLI implementation that is used in the sample. This section contains the following subsections. - [Layout](#page_layout) @@ -171,15 +171,15 @@ ms.assetid: 38ce284a-4303-46dd-b699-c9365b22a7dc ### Layout - The [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] elements in the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content consist of five controls, with associated controls: Name, Address, City, State, and Zip. There are also two controls, **OK** and **Cancel** + The UI elements in the WPF content consist of five controls, with associated controls: Name, Address, City, State, and Zip. There are also two controls, **OK** and **Cancel** - The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content is implemented in the `WPFPage` class. Layout is handled with a layout element. The class inherits from , which effectively makes it the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content root element. + The WPF content is implemented in the `WPFPage` class. Layout is handled with a layout element. The class inherits from , which effectively makes it the WPF content root element. - The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content constructor takes the required width and height, and sizes the accordingly. It then defines the basic layout by creating a set of and objects and adding them to the object base and collections, respectively. This defines a grid of five rows and seven columns, with the dimensions determined by the contents of the cells. + The WPF content constructor takes the required width and height, and sizes the accordingly. It then defines the basic layout by creating a set of and objects and adding them to the object base and collections, respectively. This defines a grid of five rows and seven columns, with the dimensions determined by the contents of the cells. [!code-cpp[Win32HostingWPFPage#WPFPageCtorToGridDef](~/samples/snippets/cpp/VS_Snippets_Wpf/Win32HostingWPFPage/CPP/WPFPage.cpp#wpfpagectortogriddef)] - Next, the constructor adds the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] elements to the . The first element is the title text, which is a control that is centered in the first row of the grid. + Next, the constructor adds the UI elements to the . The first element is the title text, which is a control that is centered in the first row of the grid. [!code-cpp[Win32HostingWPFPage#WPFPageCtorTitle](~/samples/snippets/cpp/VS_Snippets_Wpf/Win32HostingWPFPage/CPP/WPFPage.cpp#wpfpagectortitle)] @@ -197,7 +197,7 @@ ms.assetid: 38ce284a-4303-46dd-b699-c9365b22a7dc ### Returning the Data to the Host Window - When either button is clicked, its event is raised. The host window could simply attach handlers to these events and get the data directly from the controls. The sample uses a somewhat less direct approach. It handles the within the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content, and then raises a custom event `OnButtonClicked`, to notify the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content. This allows the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content to do some parameter validation before notifying the host. The handler gets the text from the controls and assigns it to public properties, from which the host can retrieve the information. + When either button is clicked, its event is raised. The host window could simply attach handlers to these events and get the data directly from the controls. The sample uses a somewhat less direct approach. It handles the within the WPF content, and then raises a custom event `OnButtonClicked`, to notify the WPF content. This allows the WPF content to do some parameter validation before notifying the host. The handler gets the text from the controls and assigns it to public properties, from which the host can retrieve the information. The event declaration, in WPFPage.h: @@ -209,7 +209,7 @@ ms.assetid: 38ce284a-4303-46dd-b699-c9365b22a7dc ### Setting the WPF Properties - The Win32 host allows the user to change several [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content properties. From the Win32 side, it is simply a matter of changing the properties. The implementation in the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content class is somewhat more complicated, because there is no single global property that controls the fonts for all controls. Instead, the appropriate property for each control is changed in the properties' set accessors. The following example shows the code for the `DefaultFontFamily` property. Setting the property calls a private method that in turn sets the properties for the various controls. + The Win32 host allows the user to change several WPF content properties. From the Win32 side, it is simply a matter of changing the properties. The implementation in the WPF content class is somewhat more complicated, because there is no single global property that controls the fonts for all controls. Instead, the appropriate property for each control is changed in the properties' set accessors. The following example shows the code for the `DefaultFontFamily` property. Setting the property calls a private method that in turn sets the properties for the various controls. From WPFPage.h: diff --git a/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-localizing-a-hybrid-application.md b/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-localizing-a-hybrid-application.md index 3d9f210..e407023 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-localizing-a-hybrid-application.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-localizing-a-hybrid-application.md @@ -8,7 +8,7 @@ ms.assetid: fbc0c54e-930a-4c13-8e9c-27b83665010a --- # Walkthrough: Localizing a Hybrid Application -This walkthrough shows you how to localize [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] elements in a Windows Forms-based hybrid application. +This walkthrough shows you how to localize WPF elements in a Windows Forms-based hybrid application. Tasks illustrated in this walkthrough include: @@ -34,19 +34,19 @@ You need the following components to complete this walkthrough: ## Creating the Windows Forms Host Project -The first step is to create the Windows Forms application project and add a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] element with content that you will localize. +The first step is to create the Windows Forms application project and add a WPF element with content that you will localize. ### To create the host project 1. Create a **WPF App** project named `LocalizingWpfInWf`. (**File** > **New** > **Project** > **Visual C#** or **Visual Basic** > **Classic Desktop** > **WPF Application**). -2. Add a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] element called `SimpleControl` to the project. +2. Add a WPF element called `SimpleControl` to the project. 3. Use the control to place a `SimpleControl` element on the form. For more information, see [Walkthrough: Hosting a 3D WPF Composite Control in Windows Forms](walkthrough-hosting-a-3-d-wpf-composite-control-in-windows-forms.md). ## Adding Localizable Content -Next, you will add a Windows Forms label control and set the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] element's content to a localizable string. +Next, you will add a Windows Forms label control and set the WPF element's content to a localizable string. ### To add localizable content @@ -128,7 +128,7 @@ You can map your localizable content to resource assemblies by using resource id ## Using LocBaml to Produce a Satellite Assembly -Your localized content is stored in a resource-only *satellite assembly*. Use the command-line tool LocBaml.exe to produce a localized assembly for your [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content. +Your localized content is stored in a resource-only *satellite assembly*. Use the command-line tool LocBaml.exe to produce a localized assembly for your WPF content. ### To produce a satellite assembly diff --git a/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-mapping-properties-using-the-elementhost-control.md b/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-mapping-properties-using-the-elementhost-control.md index c38a67c..b3be656 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-mapping-properties-using-the-elementhost-control.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-mapping-properties-using-the-elementhost-control.md @@ -11,7 +11,7 @@ ms.assetid: bccd6e0d-2272-4924-9107-ff8ed58b88aa --- # Walkthrough: Mapping Properties Using the ElementHost Control -This walkthrough shows you how to use the property to map Windows Forms properties to corresponding properties on a hosted [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] element. +This walkthrough shows you how to use the property to map Windows Forms properties to corresponding properties on a hosted WPF element. Tasks illustrated in this walkthrough include: @@ -23,7 +23,7 @@ Tasks illustrated in this walkthrough include: - Extending a default property mapping. -When you are finished, you will be able to map Windows Forms properties to corresponding [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] properties on a hosted element. +When you are finished, you will be able to map Windows Forms properties to corresponding WPF properties on a hosted element. ## Prerequisites @@ -37,7 +37,7 @@ You need the following components to complete this walkthrough: 1. Create a **Windows Forms App** project named `PropertyMappingWithElementHost`. -2. In **Solution Explorer**, add references to the following [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] assemblies. +2. In **Solution Explorer**, add references to the following WPF assemblies. - PresentationCore @@ -74,7 +74,7 @@ The control provides several The `AddMarginMapping` method adds a new mapping for the property. - The `OnMarginChange` method translates the property to the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] property. + The `OnMarginChange` method translates the property to the WPF property. 2. Copy the following code into the definition for the `Form1` class. @@ -83,7 +83,7 @@ The control provides several The `AddRegionMapping` method adds a new mapping for the property. - The `OnRegionChange` method translates the property to the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] property. + The `OnRegionChange` method translates the property to the WPF property. The `Form1_Resize` method handles the form's event and sizes the clipping region to fit the hosted element. @@ -124,7 +124,7 @@ You can use a default property mapping and also extend it with your own mapping. The `Form1_Load` method handles the event and performs the following initialization. - - Creates a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] element. + - Creates a WPF element. - Calls the methods you defined earlier in the walkthrough to set up the property mappings. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-mapping-properties-using-the-windowsformshost-element.md b/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-mapping-properties-using-the-windowsformshost-element.md index b756121..f08a0d4 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-mapping-properties-using-the-windowsformshost-element.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/walkthrough-mapping-properties-using-the-windowsformshost-element.md @@ -11,7 +11,7 @@ ms.assetid: 74809167-bf8e-48b7-a2e7-b4ea08bc7d8c --- # Walkthrough: Mapping Properties Using the WindowsFormsHost Element -This walkthrough shows you how to use the property to map [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] properties to corresponding properties on a hosted Windows Forms control. +This walkthrough shows you how to use the property to map WPF properties to corresponding properties on a hosted Windows Forms control. Tasks illustrated in this walkthrough include: @@ -27,7 +27,7 @@ Tasks illustrated in this walkthrough include: - Extending a default property mapping. -When you are finished, you will be able to map [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] properties to corresponding properties on a hosted Windows Forms control. +When you are finished, you will be able to map WPF properties to corresponding properties on a hosted Windows Forms control. ## Prerequisites @@ -45,7 +45,7 @@ You need the following components to complete this walkthrough: ## Defining the Application Layout -The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]-based application uses the element to host a Windows Forms control. +The WPF-based application uses the element to host a Windows Forms control. ### To define the application layout diff --git a/dotnet-desktop-guide/framework/wpf/advanced/weak-event-patterns.md b/dotnet-desktop-guide/framework/wpf/advanced/weak-event-patterns.md index 18278c6..7111b35 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/weak-event-patterns.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/weak-event-patterns.md @@ -9,7 +9,7 @@ helpviewer_keywords: ms.assetid: e7c62920-4812-4811-94d8-050a65c856f6 --- # Weak Event Patterns -In applications, it is possible that handlers that are attached to event sources will not be destroyed in coordination with the listener object that attached the handler to the source. This situation can lead to memory leaks. [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] introduces a design pattern that can be used to address this issue, by providing a dedicated manager class for particular events and implementing an interface on listeners for that event. This design pattern is known as the *weak event pattern*. +In applications, it is possible that handlers that are attached to event sources will not be destroyed in coordination with the listener object that attached the handler to the source. This situation can lead to memory leaks. Windows Presentation Foundation (WPF) introduces a design pattern that can be used to address this issue, by providing a dedicated manager class for particular events and implementing an interface on listeners for that event. This design pattern is known as the *weak event pattern*. ## Why Implement the Weak Event Pattern? Listening for events can lead to memory leaks. The typical technique for listening to an event is to use the language-specific syntax that attaches a handler to an event on a source. For example, in C#, that syntax is: `source.SomeEvent += new SomeEventHandler(MyEventHandler)`. @@ -21,7 +21,7 @@ In applications, it is possible that handlers that are attached to event sources ## Who Should Implement the Weak Event Pattern? Implementing the weak event pattern is interesting primarily for control authors. As a control author, you are largely responsible for the behavior and containment of your control and the impact it has on applications in which it is inserted. This includes the control object lifetime behavior, in particular the handling of the described memory leak problem. - Certain scenarios inherently lend themselves to the application of the weak event pattern. One such scenario is data binding. In data binding, it is common for the source object to be completely independent of the listener object, which is a target of a binding. Many aspects of [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] data binding already have the weak event pattern applied in how the events are implemented. + Certain scenarios inherently lend themselves to the application of the weak event pattern. One such scenario is data binding. In data binding, it is common for the source object to be completely independent of the listener object, which is a target of a binding. Many aspects of WPF data binding already have the weak event pattern applied in how the events are implemented. ## How to Implement the Weak Event Pattern There are three ways to implement weak event pattern. The following table lists the three approaches and provides some guidance for when you should use each. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/windows-forms-and-wpf-interoperability-input-architecture.md b/dotnet-desktop-guide/framework/wpf/advanced/windows-forms-and-wpf-interoperability-input-architecture.md index 356ba8b..a749440 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/windows-forms-and-wpf-interoperability-input-architecture.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/windows-forms-and-wpf-interoperability-input-architecture.md @@ -16,7 +16,7 @@ helpviewer_keywords: ms.assetid: 0eb6f137-f088-4c5e-9e37-f96afd28f235 --- # Windows Forms and WPF Interoperability Input Architecture -Interoperation between the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] and Windows Forms requires that both technologies have the appropriate keyboard input processing. This topic describes how these technologies implement keyboard and message processing to enable smooth interoperation in hybrid applications. +Interoperation between the WPF and Windows Forms requires that both technologies have the appropriate keyboard input processing. This topic describes how these technologies implement keyboard and message processing to enable smooth interoperation in hybrid applications. This topic contains the following subsections: @@ -27,27 +27,27 @@ Interoperation between the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2s - ElementHost Keyboard and Message Processing ## Modeless Forms and Dialog Boxes - Call the method on the element to open a modeless form or dialog box from a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]-based application. + Call the method on the element to open a modeless form or dialog box from a WPF-based application. - Call the method on the control to open a modeless [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] page in a Windows Forms-based application. + Call the method on the control to open a modeless WPF page in a Windows Forms-based application. ## WindowsFormsHost Keyboard and Message Processing - When hosted by a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]-based application, Windows Forms keyboard and message processing consists of the following: + When hosted by a WPF-based application, Windows Forms keyboard and message processing consists of the following: -- The class acquires messages from the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] message loop, which is implemented by the class. +- The class acquires messages from the WPF message loop, which is implemented by the class. - The class creates a surrogate Windows Forms message loop to ensure that ordinary Windows Forms keyboard processing occurs. -- The class implements the interface to coordinate focus management with [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. +- The class implements the interface to coordinate focus management with WPF. - The controls register themselves and start their message loops. The following sections describe these parts of the process in more detail. ### Acquiring Messages from the WPF Message Loop - The class implements the message loop manager for [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. The class provides hooks to enable external clients to filter messages before [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] processes them. + The class implements the message loop manager for WPF. The class provides hooks to enable external clients to filter messages before WPF processes them. - The interoperation implementation handles the event, which enables Windows Forms controls to process messages before [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] controls. + The interoperation implementation handles the event, which enables Windows Forms controls to process messages before WPF controls. ### Surrogate Windows Forms Message Loop By default, the class contains the primary message loop for Windows Forms applications. During interoperation, the Windows Forms message loop does not process messages. Therefore, this logic must be reproduced. The handler for the event performs the following steps: @@ -63,7 +63,7 @@ Interoperation between the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2s ### IKeyboardInputSink Implementation The surrogate message loop handles keyboard management. Therefore, the method is the only member that requires an implementation in the class. - By default, the class returns `false` for its implementation. This prevents tabbing from a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] control to a Windows Forms control. + By default, the class returns `false` for its implementation. This prevents tabbing from a WPF control to a Windows Forms control. The implementation of the method performs the following steps: @@ -81,7 +81,7 @@ Interoperation between the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2s When the window handle is destroyed, the control removes itself from registration. ## ElementHost Keyboard and Message Processing - When hosted by a Windows Forms application, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] keyboard and message processing consists of the following: + When hosted by a Windows Forms application, WPF keyboard and message processing consists of the following: - , , and interface implementations. @@ -94,7 +94,7 @@ Interoperation between the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2s The following sections describe these parts in more detail. ### Interface Implementations - In Windows Forms, keyboard messages are routed to the window handle of the control that has focus. In the control, these messages are routed to the hosted element. To accomplish this, the control provides an instance. If the control has focus, the instance routes most keyboard input so that it can be processed by the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] class. + In Windows Forms, keyboard messages are routed to the window handle of the control that has focus. In the control, these messages are routed to the hosted element. To accomplish this, the control provides an instance. If the control has focus, the instance routes most keyboard input so that it can be processed by the WPF class. The class implements the and interfaces. @@ -104,20 +104,20 @@ Interoperation between the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2s The Windows Forms selection logic is mapped to the and methods to implement TAB and arrow key navigation. Overriding the method accomplishes this mapping. ### Command Keys and Dialog Box Keys - To give [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] the first opportunity to process command keys and dialog keys, Windows Forms command preprocessing is connected to the method. Overriding the method connects the two technologies. + To give WPF the first opportunity to process command keys and dialog keys, Windows Forms command preprocessing is connected to the method. Overriding the method connects the two technologies. With the method, the hosted elements can handle any key message, such as WM_KEYDOWN, WM_KEYUP, WM_SYSKEYDOWN, or WM_SYSKEYUP, including command keys, such as TAB, ENTER, ESC, and arrow keys. If a key message is not handled, it is sent up the Windows Forms ancestor hierarchy for handling. ### Accelerator Processing - To process accelerators correctly, Windows Forms accelerator processing must be connected to the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] class. Additionally, all WM_CHAR messages must be correctly routed to hosted elements. + To process accelerators correctly, Windows Forms accelerator processing must be connected to the WPF class. Additionally, all WM_CHAR messages must be correctly routed to hosted elements. Because the default implementation of the method returns `false`, WM_CHAR messages are processed using the following logic: - The method is overridden to ensure that all WM_CHAR messages are forwarded to hosted elements. -- If the ALT key is pressed, the message is WM_SYSCHAR. Windows Forms does not preprocess this message through the method. Therefore, the method is overridden to query the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] for a registered accelerator. If a registered accelerator is found, processes it. +- If the ALT key is pressed, the message is WM_SYSCHAR. Windows Forms does not preprocess this message through the method. Therefore, the method is overridden to query the WPF for a registered accelerator. If a registered accelerator is found, processes it. -- If the ALT key is not pressed, the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] class processes the unhandled input. If the input is an accelerator, the processes it. The event is handled for WM_CHAR messages that were not processed. +- If the ALT key is not pressed, the WPF class processes the unhandled input. If the input is an accelerator, the processes it. The event is handled for WM_CHAR messages that were not processed. When the user presses the ALT key, accelerator visual cues are shown on the whole form. To support this behavior, all controls on the active form receive WM_SYSKEYDOWN messages, regardless of which control has focus. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/windows-forms-and-wpf-property-mapping.md b/dotnet-desktop-guide/framework/wpf/advanced/windows-forms-and-wpf-property-mapping.md index d4fbc71..dc1ecf8 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/windows-forms-and-wpf-property-mapping.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/windows-forms-and-wpf-property-mapping.md @@ -11,7 +11,7 @@ helpviewer_keywords: ms.assetid: 999d8298-9c04-467d-a453-86e41002057d --- # Windows Forms and WPF Property Mapping -The Windows Forms and [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] technologies have two similar but different property models. *Property mapping* supports interoperation between the two architectures and provides the following capabilities: +The Windows Forms and WPF technologies have two similar but different property models. *Property mapping* supports interoperation between the two architectures and provides the following capabilities: - Makes it easy to map relevant property changes in the host environment to the hosted control or element. @@ -27,16 +27,16 @@ The Windows Forms and [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharpt Use the property on the element and the property on control to access property mapping. ## Property Mapping with the WindowsFormsHost Element - The element translates default [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] properties to their Windows Forms equivalents using the following translation table. + The element translates default WPF properties to their Windows Forms equivalents using the following translation table. |Windows Presentation Foundation hosting|Windows Forms|Interoperation behavior| |---------------------------------------------|-------------------|-----------------------------| |

()|

()|The element sets the property of the hosted control and the property of the hosted control. Mapping is performed by using the following rules:

- If is a solid color, it is converted and used to set the property of the hosted control. The property is not set on the hosted control, because the hosted control can inherit the value of the property. **Note:** The hosted control does not support transparency. Any color assigned to must be fully opaque, with an alpha value of 0xFF.

- If is not a solid color, the control creates a bitmap from the property. The control assigns this bitmap to the property of the hosted control. This provides an effect which is similar to transparency. **Note:** You can override this behavior or you can remove the property mapping.| |||If the default mapping has not been reassigned, control traverses its ancestor hierarchy until it finds an ancestor with its property set. This value is translated to the closest corresponding Windows Forms cursor.

If the default mapping for the property has not been reassigned, the traversal stops on the first ancestor with set to `true`.| |

()|

()| maps to .

maps to .

is not mapped.

maps to .| -|| on the hosted control's |The set of [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] properties is translated into a corresponding . When one of these properties changes, a new is created. For : is disabled. For or : is enabled.| -|| on the hosted control's |The set of [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] properties is translated into a corresponding . When one of these properties changes, a new is created. For , , , , , , , or : is enabled. For , , , , , or : is disabled.| -|







|

()|The set of [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] properties is translated into a corresponding . When one of these properties changes, a new is created. The hosted Windows Forms control resizes based on the font size.

Font size in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] is expressed as one ninety-sixth of an inch, and in Windows Forms as one seventy-second of an inch. The corresponding conversion is:

Windows Forms font size = [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] font size * 72.0 / 96.0.| +|| on the hosted control's |The set of WPF properties is translated into a corresponding . When one of these properties changes, a new is created. For : is disabled. For or : is enabled.| +|| on the hosted control's |The set of WPF properties is translated into a corresponding . When one of these properties changes, a new is created. For , , , , , , , or : is enabled. For , , , , , or : is disabled.| +|







|

()|The set of WPF properties is translated into a corresponding . When one of these properties changes, a new is created. The hosted Windows Forms control resizes based on the font size.

Font size in WPF is expressed as one ninety-sixth of an inch, and in Windows Forms as one seventy-second of an inch. The corresponding conversion is:

Windows Forms font size = WPF font size * 72.0 / 96.0.| |

()|

()|The property mapping is performed by using the following rules:

- If is a , use for .
- If is a , use the color of the with the lowest offset value for .
- For any other type, leave unchanged. This means the default is used.| |||When is set, element sets the property on the hosted control.| |||All four values of the property on the hosted Windows Forms control are set to the same value.

- Values greater than are set to .
- Values less than are set to .| @@ -110,7 +110,7 @@ The Windows Forms and [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharpt - Visible - The control translates default Windows Forms properties to their [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] equivalents by using the following translation table. + The control translates default Windows Forms properties to their WPF equivalents by using the following translation table. For more information, see [Walkthrough: Mapping Properties Using the ElementHost Control](walkthrough-mapping-properties-using-the-elementhost-control.md). @@ -119,9 +119,9 @@ The Windows Forms and [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharpt |

()|

() on the hosted element|Setting this property forces a repaint with an . If the property is set to `false` (the default value), this is based on the appearance of the control, including its , , properties, and any attached paint handlers.

If the property is set to `true`, the is based on the appearance of the control's parent, including the parent's , , properties, and any attached paint handlers.| |

()|

() on the hosted element|Setting this property causes the same behavior described for the mapping.| ||

() on the hosted element|Setting this property causes the same behavior described for the mapping.| -|

()|

()|The Windows Forms standard cursor is translated to the corresponding [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] standard cursor. If the Windows Forms is not a standard cursor, the default is assigned.| +|

()|

()|The Windows Forms standard cursor is translated to the corresponding WPF standard cursor. If the Windows Forms is not a standard cursor, the default is assigned.| |||When is set, the control sets the property on the hosted element.| -|

()|







|The value is translated into a corresponding set of [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] font properties.| +|

()|







|The value is translated into a corresponding set of WPF font properties.| || on hosted element|If is `true`, is set to .

If is `false`, is set to .| || on hosted element|If is `true`, is set to .

If is `false`, is set to .| || on hosted element|Applies only when hosting a control.| diff --git a/dotnet-desktop-guide/framework/wpf/advanced/windows-forms-controls-and-equivalent-wpf-controls.md b/dotnet-desktop-guide/framework/wpf/advanced/windows-forms-controls-and-equivalent-wpf-controls.md index 502678c..04b1a97 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/windows-forms-controls-and-equivalent-wpf-controls.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/windows-forms-controls-and-equivalent-wpf-controls.md @@ -10,11 +10,11 @@ ms.assetid: 8a157e6b-8054-46db-a5cf-a78966acc7a1 --- # Windows Forms Controls and Equivalent WPF Controls -Many Windows Forms controls have equivalent [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] controls, but some Windows Forms controls have no equivalents in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. This topic compares control types provided by the two technologies. +Many Windows Forms controls have equivalent WPF controls, but some Windows Forms controls have no equivalents in WPF. This topic compares control types provided by the two technologies. - You can always use interoperation to host Windows Forms controls that do not have equivalents in your [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]-based applications. + You can always use interoperation to host Windows Forms controls that do not have equivalents in your WPF-based applications. - The following table shows which Windows Forms controls and components have equivalent [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] control functionality. + The following table shows which Windows Forms controls and components have equivalent WPF control functionality. |Windows Forms control|WPF equivalent control|Remarks| |---------------------------|----------------------------|-------------| @@ -47,7 +47,7 @@ Many Windows Forms controls have equivalent [!INCLUDE[TLA2#tla_winclient](../../ |||| ||No equivalent control.|| || and two controls.|| -|||The class is a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] wrapper around the Win32 control.| +|||The class is a WPF wrapper around the Win32 control.| ||No equivalent control.|| |||| |||| @@ -59,7 +59,7 @@ Many Windows Forms controls have equivalent [!INCLUDE[TLA2#tla_winclient](../../ ||No equivalent control.|| |||| |||| -|||The class is a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] wrapper around the Win32 control.| +|||The class is a WPF wrapper around the Win32 control.| |||| |||| |||| diff --git a/dotnet-desktop-guide/framework/wpf/advanced/wpf-and-win32-interoperation.md b/dotnet-desktop-guide/framework/wpf/advanced/wpf-and-win32-interoperation.md index 235b157..d424904 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/wpf-and-win32-interoperation.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/wpf-and-win32-interoperation.md @@ -11,35 +11,35 @@ ms.assetid: 0ffbde0d-701d-45a3-a6fa-dd71f4d9772e --- # WPF and Win32 Interoperation -This topic provides an overview of how to interoperate [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] and Win32 code. [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides a rich environment for creating applications. However, when you have a substantial investment in Win32 code, it might be more effective to reuse some of that code. +This topic provides an overview of how to interoperate WPF and Win32 code. Windows Presentation Foundation (WPF) provides a rich environment for creating applications. However, when you have a substantial investment in Win32 code, it might be more effective to reuse some of that code. ## WPF and Win32 Interoperation Basics -There are two basic techniques for interoperation between [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] and Win32 code. +There are two basic techniques for interoperation between WPF and Win32 code. -- Host [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content in a Win32 window. With this technique, you can use the advanced graphics capabilities of [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] within the framework of a standard Win32 window and application. +- Host WPF content in a Win32 window. With this technique, you can use the advanced graphics capabilities of WPF within the framework of a standard Win32 window and application. -- Host a Win32 window in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content. With this technique, you can use an existing custom Win32 control in the context of other [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content, and pass data across the boundaries. +- Host a Win32 window in WPF content. With this technique, you can use an existing custom Win32 control in the context of other WPF content, and pass data across the boundaries. -Each of these techniques is conceptually introduced in this topic. For a more code-oriented illustration of hosting [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] in Win32, see [Walkthrough: Hosting WPF Content in Win32](walkthrough-hosting-wpf-content-in-win32.md). For a more code-oriented illustration of hosting Win32 in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], see [Walkthrough: Hosting a Win32 Control in WPF](walkthrough-hosting-a-win32-control-in-wpf.md). +Each of these techniques is conceptually introduced in this topic. For a more code-oriented illustration of hosting WPF in Win32, see [Walkthrough: Hosting WPF Content in Win32](walkthrough-hosting-wpf-content-in-win32.md). For a more code-oriented illustration of hosting Win32 in WPF, see [Walkthrough: Hosting a Win32 Control in WPF](walkthrough-hosting-a-win32-control-in-wpf.md). ## WPF Interoperation Projects -[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] APIs are managed code, but most existing Win32 programs are written in unmanaged C++. You cannot call [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] APIs from a true unmanaged program. However, by using the `/clr` option with the Microsoft Visual C++ compiler, you can create a mixed managed-unmanaged program where you can seamlessly mix managed and unmanaged API calls. +WPF APIs are managed code, but most existing Win32 programs are written in unmanaged C++. You cannot call WPF APIs from a true unmanaged program. However, by using the `/clr` option with the Microsoft Visual C++ compiler, you can create a mixed managed-unmanaged program where you can seamlessly mix managed and unmanaged API calls. -One project-level complication is that you cannot compile [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] files into a C++ project. There are several project division techniques to compensate for this. +One project-level complication is that you cannot compile Extensible Application Markup Language (XAML) files into a C++ project. There are several project division techniques to compensate for this. -- Create a C# DLL that contains all your [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] pages as a compiled assembly, and then have your C++ executable include that DLL as a reference. +- Create a C# DLL that contains all your XAML pages as a compiled assembly, and then have your C++ executable include that DLL as a reference. -- Create a C# executable for the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content, and have it reference a C++ DLL that contains the Win32 content. +- Create a C# executable for the WPF content, and have it reference a C++ DLL that contains the Win32 content. -- Use to load any [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] at run time, instead of compiling your [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]. +- Use to load any XAML at run time, instead of compiling your XAML. -- Do not use [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] at all, and write all your [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] in code, building up the element tree from . +- Do not use WPF in code, building up the element tree from . Use whatever approach works best for you. @@ -50,9 +50,9 @@ Use whatever approach works best for you. ## How WPF Uses Hwnds -To make the most of [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] "HWND interop", you need to understand how [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] uses HWNDs. For any HWND, you cannot mix [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] rendering with DirectX rendering or GDI / GDI+ rendering. This has a number of implications. Primarily, in order to mix these rendering models at all, you must create an interoperation solution, and use designated segments of interoperation for each rendering model that you choose to use. Also, the rendering behavior creates an "airspace" restriction for what your interoperation solution can accomplish. The "airspace" concept is explained in greater detail in the topic [Technology Regions Overview](technology-regions-overview.md). +To make the most of WPF "HWND interop", you need to understand how WPF uses HWNDs. For any HWND, you cannot mix WPF rendering with DirectX rendering or GDI / GDI+ rendering. This has a number of implications. Primarily, in order to mix these rendering models at all, you must create an interoperation solution, and use designated segments of interoperation for each rendering model that you choose to use. Also, the rendering behavior creates an "airspace" restriction for what your interoperation solution can accomplish. The "airspace" concept is explained in greater detail in the topic [Technology Regions Overview](technology-regions-overview.md). -All [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] elements on the screen are ultimately backed by a HWND. When you create a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] , [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] creates a top-level HWND, and uses an to put the and its [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content inside the HWND. The rest of your [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content in the application shares that singular HWND. An exception is menus, combo box drop downs, and other pop-ups. These elements create their own top-level window, which is why a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] menu can potentially go past the edge of the window HWND that contains it. When you use to put an HWND inside [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] informs Win32 how to position the new child HWND relative to the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] HWND. +All WPF elements on the screen are ultimately backed by a HWND. When you create a WPF , WPF creates a top-level HWND, and uses an to put the and its WPF content inside the HWND. The rest of your WPF content in the application shares that singular HWND. An exception is menus, combo box drop downs, and other pop-ups. These elements create their own top-level window, which is why a WPF menu can potentially go past the edge of the window HWND that contains it. When you use to put an HWND inside WPF, WPF informs Win32 how to position the new child HWND relative to the WPF HWND. A related concept to HWND is transparency within and between each HWND. This is also discussed in the topic [Technology Regions Overview](technology-regions-overview.md). @@ -60,13 +60,13 @@ A related concept to HWND is transparency within and between each HWND. This is ## Hosting WPF Content in a Microsoft Win32 Window -The key to hosting a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] on a Win32 window is the class. This class wraps the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content in a Win32 window, so that the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content can be incorporated into your [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] as a child window. The following approach combines the Win32 and [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] in a single application. +The key to hosting a WPF on a Win32 window is the class. This class wraps the WPF content in a Win32 window, so that the WPF content can be incorporated into your WPF in a single application. -1. Implement your [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content (the content root element) as a managed class. Typically, the class inherits from one of the classes that can contain multiple child elements and/or used as a root element, such as or . In subsequent steps, this class is referred to as the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content class, and instances of the class are referred to as [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content objects. +1. Implement your WPF content (the content root element) as a managed class. Typically, the class inherits from one of the classes that can contain multiple child elements and/or used as a root element, such as or . In subsequent steps, this class is referred to as the WPF content class, and instances of the class are referred to as WPF content objects. 2. Implement a Windows application with C++/CLI. If you are starting with an existing unmanaged C++ application, you can usually enable it to call managed code by changing your project settings to include the `/clr` compiler flag (the full scope of what might be necessary to support `/clr` compilation is not described in this topic). -3. Set the threading model to Single Threaded Apartment (STA). [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] uses this threading model. +3. Set the threading model to Single Threaded Apartment (STA). WPF uses this threading model. 4. Handle the WM_CREATE notification in your window procedure. @@ -74,20 +74,20 @@ The key to hosting a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptl 1. Create a new object with the parent window HWND as its `parent` parameter. - 2. Create an instance of your [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content class. + 2. Create an instance of your WPF content class. - 3. Assign a reference to the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content object to the object property. + 3. Assign a reference to the WPF content object to the object property. 4. The object property contains the window handle (HWND). To get an HWND that you can use in the unmanaged part of your application, cast `Handle.ToPointer()` to an HWND. -6. Implement a managed class that contains a static field that holds a reference to your [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content object. This class allows you to get a reference to the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content object from your Win32 code, but more importantly it prevents your from being inadvertently garbage collected. +6. Implement a managed class that contains a static field that holds a reference to your WPF content object. This class allows you to get a reference to the WPF content object from your Win32 code, but more importantly it prevents your from being inadvertently garbage collected. -7. Receive notifications from the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content object by attaching a handler to one or more of the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content object events. +7. Receive notifications from the WPF content object by attaching a handler to one or more of the WPF content object events. -8. Communicate with the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content object by using the reference that you stored in the static field to set properties, call methods, etc. +8. Communicate with the WPF content object by using the reference that you stored in the static field to set properties, call methods, etc. > [!NOTE] -> You can do some or all of the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content class definition for Step One in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] using the default partial class of the content class, if you produce a separate assembly and then reference it. Although you typically include an object as part of compiling the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] into an assembly, you do not end up using that as part of the interoperation, you just use one or more of the root classes for [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] files referred to by the application and reference their partial classes. The remainder of the procedure is essentially similar to that outlined above. +> You can do some or all of the WPF content class definition for Step One in XAML using the default partial class of the content class, if you produce a separate assembly and then reference it. Although you typically include an object as part of compiling the XAML into an assembly, you do not end up using that as part of the interoperation, you just use one or more of the root classes for XAML files referred to by the application and reference their partial classes. The remainder of the procedure is essentially similar to that outlined above. > > Each of these steps is illustrated through code in the topic [Walkthrough: Hosting WPF Content in Win32](walkthrough-hosting-wpf-content-in-win32.md). @@ -95,13 +95,13 @@ The key to hosting a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptl ## Hosting a Microsoft Win32 Window in WPF -The key to hosting a Win32 window within other [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content is the class. This class wraps the window in a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] element which can be added to a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] element tree. also supports APIs that allow you to do such tasks as process messages for the hosted window. The basic procedure is: +The key to hosting a Win32 window within other WPF content is the class. This class wraps the window in a WPF element which can be added to a WPF element tree. also supports APIs that allow you to do such tasks as process messages for the hosted window. The basic procedure is: -1. Create an element tree for a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application (can be through code or markup). Find an appropriate and permissible point in the element tree where the implementation can be added as a child element. In the remainder of these steps, this element is referred to as the reserving element. +1. Create an element tree for a WPF application (can be through code or markup). Find an appropriate and permissible point in the element tree where the implementation can be added as a child element. In the remainder of these steps, this element is referred to as the reserving element. 2. Derive from to create an object that holds your Win32 content. -3. In that host class, override the method . Return the HWND of the hosted window. You might want to wrap the actual control(s) as a child window of the returned window; wrapping the controls in a host window provides a simple way for your [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content to receive notifications from the controls. This technique helps correct for some Win32 issues regarding message handling at the hosted control boundary. +3. In that host class, override the method . Return the HWND of the hosted window. You might want to wrap the actual control(s) as a child window of the returned window; wrapping the controls in a host window provides a simple way for your WPF content to receive notifications from the controls. This technique helps correct for some Win32 issues regarding message handling at the hosted control boundary. 4. Override the methods and . The intention here is to process cleanup and remove references to the hosted content, particularly if you created references to unmanaged objects. @@ -111,7 +111,7 @@ The key to hosting a Win32 window within other [!INCLUDE[TLA2#tla_winclient](../ - Implement message processing for all messages (not just shutdown messages) in your override of the method . - - Have the hosting [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] element process the messages by handling the event. This event is raised for every message that is sent to the main window procedure of the hosted window. + - Have the hosting WPF element process the messages by handling the event. This event is raised for every message that is sent to the main window procedure of the hosted window. - You cannot process messages from windows that are out of process using . @@ -123,7 +123,7 @@ Each of these steps is illustrated through code in the topic [Walkthrough: Hosti ### Hwnds Inside WPF -You can think of as a special control. (Technically, is a derived class, not a derived class, but it can be considered a control for purposes of interoperation.) abstracts the underlying Win32 nature of the hosted content such that the remainder of [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] considers the hosted content to be another control-like object, which should render and process input. generally behaves like any other [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] , although there are some important differences around output (drawing and graphics) and input (mouse and keyboard) based on limitations of what the underlying HWNDs can support. +You can think of as a special control. (Technically, is a derived class, not a derived class, but it can be considered a control for purposes of interoperation.) abstracts the underlying Win32 nature of the hosted content such that the remainder of WPF considers the hosted content to be another control-like object, which should render and process input. generally behaves like any other WPF , although there are some important differences around output (drawing and graphics) and input (mouse and keyboard) based on limitations of what the underlying HWNDs can support. #### Notable Differences in Output Behavior @@ -133,7 +133,7 @@ You can think of as a special control. (T - does not support the property (alpha blending). If content inside the performs operations that include alpha information, that is itself not a violation, but the as a whole only supports Opacity = 1.0 (100%). -- will appear on top of other [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] elements in the same top-level window. However, a or generated menu is a separate top-level window, and so will behave correctly with . +- will appear on top of other WPF elements in the same top-level window. However, a or generated menu is a separate top-level window, and so will behave correctly with . - does not respect the clipping region of its parent . This is potentially an issue if you attempt to put an class inside a scrolling region or . @@ -141,11 +141,11 @@ You can think of as a special control. (T - In general, while input devices are scoped within the hosted Win32 region, input events go directly to Win32. -- While the mouse is over the , your application does not receive [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] mouse events, and the value of the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] property will be `false`. +- While the mouse is over the , your application does not receive WPF mouse events, and the value of the WPF property will be `false`. -- While the has keyboard focus, your application will not receive [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] keyboard events and the value of the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] property will be `false`. +- While the has keyboard focus, your application will not receive WPF keyboard events and the value of the WPF property will be `false`. -- When focus is within the and changes to another control inside the , your application will not receive the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] events or . +- When focus is within the and changes to another control inside the , your application will not receive the WPF events or . - Related stylus properties and events are analogous, and do not report information while the stylus is over . @@ -153,15 +153,15 @@ You can think of as a special control. (T ## Tabbing, Mnemonics, and Accelerators -The and interfaces allow you to create a seamless keyboard experience for mixed [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] and Win32 applications: +The and interfaces allow you to create a seamless keyboard experience for mixed WPF and Win32 applications: -- Tabbing between Win32 and [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] components +- Tabbing between Win32 and WPF components - Mnemonics and accelerators that work both when focus is within a Win32 component and when it is within a WPF component. The and classes both provide implementations of , but they may not handle all the input messages that you want for more advanced scenarios. Override the appropriate methods to get the keyboard behavior you want. -The interfaces only provide support for what happens on the transition between the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] and Win32 regions. Within the Win32 region, tabbing behavior is entirely controlled by the Win32 implemented logic for tabbing, if any. +The interfaces only provide support for what happens on the transition between the WPF and Win32 regions. Within the Win32 region, tabbing behavior is entirely controlled by the Win32 implemented logic for tabbing, if any. ## See also diff --git a/dotnet-desktop-guide/framework/wpf/advanced/wpf-and-windows-forms-interoperation.md b/dotnet-desktop-guide/framework/wpf/advanced/wpf-and-windows-forms-interoperation.md index ebbbc0d..e9ac3bd 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/wpf-and-windows-forms-interoperation.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/wpf-and-windows-forms-interoperation.md @@ -11,48 +11,48 @@ helpviewer_keywords: ms.assetid: 9e8aa6b6-112c-4579-98d1-c974917df499 --- # WPF and Windows Forms Interoperation -[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] and Windows Forms present two different architectures for creating application interfaces. The namespace provides classes that enable common interoperation scenarios. The two key classes that implement interoperation capabilities are and . This topic describes which interoperation scenarios are supported and which scenarios are not supported. +WPF and Windows Forms present two different architectures for creating application interfaces. The namespace provides classes that enable common interoperation scenarios. The two key classes that implement interoperation capabilities are and . This topic describes which interoperation scenarios are supported and which scenarios are not supported. > [!NOTE] -> Special consideration is given to the *hybrid control* scenario. A hybrid control has a control from one technology nested in a control from the other technology. This is also called a *nested interoperation*. A *multilevel hybrid control* has more than one level of hybrid control nesting. An example of a multilevel nested interoperation is a Windows Forms control that contains a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] control, which contains another Windows Forms control. Multilevel hybrid controls are not supported. +> Special consideration is given to the *hybrid control* scenario. A hybrid control has a control from one technology nested in a control from the other technology. This is also called a *nested interoperation*. A *multilevel hybrid control* has more than one level of hybrid control nesting. An example of a multilevel nested interoperation is a Windows Forms control that contains a WPF control, which contains another Windows Forms control. Multilevel hybrid controls are not supported. ## Hosting Windows Forms Controls in WPF - The following interoperation scenarios are supported when a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] control hosts a Windows Forms control: + The following interoperation scenarios are supported when a WPF control hosts a Windows Forms control: -- The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] control may host one or more Windows Forms controls using XAML. +- The WPF control may host one or more Windows Forms controls using XAML. - It may host one or more Windows Forms controls using code. - It may host Windows Forms container controls that contain other Windows Forms controls. -- It may host a master/detail form with a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] master and Windows Forms details. +- It may host a master/detail form with a WPF master and Windows Forms details. -- It may host a master/detail form with a Windows Forms master and [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] details. +- It may host a master/detail form with a Windows Forms master and WPF details. - It may host one or more ActiveX controls. - It may host one or more composite controls. -- It may host hybrid controls using [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)]. +- It may host hybrid controls using Extensible Application Markup Language (XAML). - It may host hybrid controls using code. ### Layout Support - The following list describes the known limitations when the element attempts to integrate its hosted Windows Forms control into the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] layout system. + The following list describes the known limitations when the element attempts to integrate its hosted Windows Forms control into the WPF layout system. -- In some cases, Windows Forms controls cannot be resized, or can be sized only to specific dimensions. For example, a Windows Forms control supports only a single height, which is defined by the control's font size. In a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] dynamic layout, which assumes that elements can stretch vertically, a hosted control will not stretch as expected. +- In some cases, Windows Forms controls cannot be resized, or can be sized only to specific dimensions. For example, a Windows Forms control supports only a single height, which is defined by the control's font size. In a WPF dynamic layout, which assumes that elements can stretch vertically, a hosted control will not stretch as expected. - Windows Forms controls cannot be rotated or skewed. For example, when you rotate your user interface by 90 degrees, hosted Windows Forms controls will maintain their upright position. - In most cases, Windows Forms controls do not support proportional scaling. Although the overall dimensions of the control will scale, child controls and component elements of the control may not resize as expected. This limitation depends on how well each Windows Forms control supports scaling. -- In a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] user interface, you can change the z-order of elements to control overlapping behavior. A hosted Windows Forms control is drawn in a separate HWND, so it is always drawn on top of [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] elements. +- In a WPF user interface, you can change the z-order of elements to control overlapping behavior. A hosted Windows Forms control is drawn in a separate HWND, so it is always drawn on top of WPF elements. -- Windows Forms controls support autoscaling based on the font size. In a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] user interface, changing the font size does not resize the entire layout, although individual elements may dynamically resize. +- Windows Forms controls support autoscaling based on the font size. In a WPF user interface, changing the font size does not resize the entire layout, although individual elements may dynamically resize. ### Ambient Properties - Some of the ambient properties of [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] controls have Windows Forms equivalents. These ambient properties are propagated to the hosted Windows Forms controls and exposed as public properties on the control. The control translates each [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] ambient property into its Windows Forms equivalent. + Some of the ambient properties of WPF controls have Windows Forms equivalents. These ambient properties are propagated to the hosted Windows Forms controls and exposed as public properties on the control. The control translates each WPF ambient property into its Windows Forms equivalent. For more information, see [Windows Forms and WPF Property Mapping](windows-forms-and-wpf-property-mapping.md). @@ -61,41 +61,41 @@ ms.assetid: 9e8aa6b6-112c-4579-98d1-c974917df499 |Behavior|Supported|Not supported| |--------------|---------------|-------------------| -|Transparency|Windows Forms control rendering supports transparency. The background of the parent [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] control can become the background of hosted Windows Forms controls.|Some Windows Forms controls do not support transparency. For example, the and controls will not be transparent when hosted by [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)].| -|Tabbing|Tab order for hosted Windows Forms controls is the same as when those controls are hosted in a Windows Forms-based application.

Tabbing from a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] control to a Windows Forms control with the TAB key and SHIFT+TAB keys works as usual.

Windows Forms controls that have a property value of `false` do not receive focus when the user tabs through controls.

- Each control has a value, which determines when that control will receive focus.
- Windows Forms controls that are contained inside a container follow the order specified by the property. Tabbing from the last tab index puts focus on the next [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] control, if one exists. If no other focusable [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] control exists, tabbing returns to the first Windows Forms control in the tab order.
- values for controls inside the are relative to sibling Windows Forms controls that are contained in the control.
- Tabbing honors control-specific behavior. For example, pressing the TAB key in a control that has a property value of `true` enters a tab in the text box instead of moving the focus.|Not applicable.| -|Navigation with arrow keys|- Navigation with arrow keys in the control is the same as in an ordinary Windows Forms container control: The UP ARROW and LEFT ARROW keys select the previous control, and the DOWN ARROW and RIGHT ARROW keys select the next control.
- The UP ARROW and LEFT ARROW keys from the first control that is contained in the control perform the same action as the SHIFT+TAB keyboard shortcut. If there is a focusable [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] control, focus moves outside the control. This behavior differs from the standard behavior in that no wrapping to the last control occurs. If no other focusable [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] control exists, focus returns to the last Windows Forms control in the tab order.
- The DOWN ARROW and RIGHT ARROW keys from the last control that is contained in the control perform the same action as the TAB key. If there is a focusable [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] control, focus moves outside the control. This behavior differs from the standard behavior in that no wrapping to the first control occurs. If no other focusable [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] control exists, focus returns to the first Windows Forms control in the tab order.|Not applicable.| -|Accelerators|Accelerators work as usual, except where noted in the "Not supported" column.|Duplicate accelerators across technologies do not work like ordinary duplicate accelerators. When an accelerator is duplicated across technologies, with at least one on a Windows Forms control and the other on a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] control, the Windows Forms control always receives the accelerator. Focus does not toggle between the controls when the duplicate accelerator is pressed.| -|Shortcut keys|Shortcut keys work as usual, except where noted in the "Not supported" column.|- Windows Forms shortcut keys that are handled at the preprocessing stage always take precedence over [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] shortcut keys. For example, if you have a control with CTRL+S shortcut keys defined, and there is a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] command bound to CTRL+S, the control handler is always invoked first, regardless of focus.
- Windows Forms shortcut keys that are handled by the event are processed last in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. You can prevent this behavior by overriding the Windows Forms control's method or handling the event. Return `true` from the method, or set the value of the property to `true` in your event handler.| -|AcceptsReturn, AcceptsTab, and other control-specific behavior|Properties that change the default keyboard behavior work as usual, assuming that the Windows Forms control overrides the method to return `true`.|Windows Forms controls that change default keyboard behavior by handling the event are processed last in the host [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] control. Because these controls are processed last, they can produce unexpected behavior.| +|Transparency|Windows Forms control rendering supports transparency. The background of the parent WPF control can become the background of hosted Windows Forms controls.|Some Windows Forms controls do not support transparency. For example, the and controls will not be transparent when hosted by WPF.| +|Tabbing|Tab order for hosted Windows Forms controls is the same as when those controls are hosted in a Windows Forms-based application.

Tabbing from a WPF control to a Windows Forms control with the TAB key and SHIFT+TAB keys works as usual.

Windows Forms controls that have a property value of `false` do not receive focus when the user tabs through controls.

- Each control has a value, which determines when that control will receive focus.
- Windows Forms controls that are contained inside a container follow the order specified by the property. Tabbing from the last tab index puts focus on the next WPF control, if one exists. If no other focusable WPF control exists, tabbing returns to the first Windows Forms control in the tab order.
- values for controls inside the are relative to sibling Windows Forms controls that are contained in the control.
- Tabbing honors control-specific behavior. For example, pressing the TAB key in a control that has a property value of `true` enters a tab in the text box instead of moving the focus.|Not applicable.| +|Navigation with arrow keys|- Navigation with arrow keys in the control is the same as in an ordinary Windows Forms container control: The UP ARROW and LEFT ARROW keys select the previous control, and the DOWN ARROW and RIGHT ARROW keys select the next control.
- The UP ARROW and LEFT ARROW keys from the first control that is contained in the control perform the same action as the SHIFT+TAB keyboard shortcut. If there is a focusable WPF control, focus moves outside the control. This behavior differs from the standard behavior in that no wrapping to the last control occurs. If no other focusable WPF control exists, focus returns to the last Windows Forms control in the tab order.
- The DOWN ARROW and RIGHT ARROW keys from the last control that is contained in the control perform the same action as the TAB key. If there is a focusable WPF control, focus moves outside the control. This behavior differs from the standard behavior in that no wrapping to the first control occurs. If no other focusable WPF control exists, focus returns to the first Windows Forms control in the tab order.|Not applicable.| +|Accelerators|Accelerators work as usual, except where noted in the "Not supported" column.|Duplicate accelerators across technologies do not work like ordinary duplicate accelerators. When an accelerator is duplicated across technologies, with at least one on a Windows Forms control and the other on a WPF control, the Windows Forms control always receives the accelerator. Focus does not toggle between the controls when the duplicate accelerator is pressed.| +|Shortcut keys|Shortcut keys work as usual, except where noted in the "Not supported" column.|- Windows Forms shortcut keys that are handled at the preprocessing stage always take precedence over WPF shortcut keys. For example, if you have a control with CTRL+S shortcut keys defined, and there is a WPF command bound to CTRL+S, the control handler is always invoked first, regardless of focus.
- Windows Forms shortcut keys that are handled by the event are processed last in WPF. You can prevent this behavior by overriding the Windows Forms control's method or handling the event. Return `true` from the method, or set the value of the property to `true` in your event handler.| +|AcceptsReturn, AcceptsTab, and other control-specific behavior|Properties that change the default keyboard behavior work as usual, assuming that the Windows Forms control overrides the method to return `true`.|Windows Forms controls that change default keyboard behavior by handling the event are processed last in the host WPF control. Because these controls are processed last, they can produce unexpected behavior.| |Enter and Leave Events|When focus is not going to the containing control, the Enter and Leave events are raised as usual when focus changes in a single control.|Enter and Leave events are not raised when the following focus changes occur:

- From inside to outside a control.
- From outside to inside a control.
- Outside a control.
- From a Windows Forms control hosted in a control to an control hosted inside the same .| -|Multithreading|All varieties of multithreading are supported.|Both the Windows Forms and [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] technologies assume a single-threaded concurrency model. During debugging, calls to framework objects from other threads will raise an exception to enforce this requirement.| +|Multithreading|All varieties of multithreading are supported.|Both the Windows Forms and WPF technologies assume a single-threaded concurrency model. During debugging, calls to framework objects from other threads will raise an exception to enforce this requirement.| |Security|All interoperation scenarios require full trust.|No interoperation scenarios are allowed in partial trust.| -|Accessibility|All accessibility scenarios are supported. Assistive technology products function correctly when they are used for hybrid applications that contain both Windows Forms and [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] controls.|Not applicable.| -|Clipboard|All Clipboard operations work as usual. This includes cutting and pasting between Windows Forms and [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] controls.|Not applicable.| -|Drag-and-drop feature|All drag-and-drop operations work as usual. This includes operations between Windows Forms and [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] controls.|Not applicable.| +|Accessibility|All accessibility scenarios are supported. Assistive technology products function correctly when they are used for hybrid applications that contain both Windows Forms and WPF controls.|Not applicable.| +|Clipboard|All Clipboard operations work as usual. This includes cutting and pasting between Windows Forms and WPF controls.|Not applicable.| +|Drag-and-drop feature|All drag-and-drop operations work as usual. This includes operations between Windows Forms and WPF controls.|Not applicable.| ## Hosting WPF Controls in Windows Forms - The following interoperation scenarios are supported when a Windows Forms control hosts a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] control: + The following interoperation scenarios are supported when a Windows Forms control hosts a WPF control: -- Hosting one or more [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] controls using code. +- Hosting one or more WPF controls using code. -- Associating a property sheet with one or more hosted [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] controls. +- Associating a property sheet with one or more hosted WPF controls. -- Hosting one or more [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] pages in a form. +- Hosting one or more WPF pages in a form. -- Starting a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] window. +- Starting a WPF window. -- Hosting a master/detail form with a Windows Forms master and [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] details. +- Hosting a master/detail form with a Windows Forms master and WPF details. -- Hosting a master/detail form with a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] master and Windows Forms details. +- Hosting a master/detail form with a WPF master and Windows Forms details. -- Hosting custom [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] controls. +- Hosting custom WPF controls. - Hosting hybrid controls. ### Ambient Properties - Some of the ambient properties of Windows Forms controls have [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] equivalents. These ambient properties are propagated to the hosted [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] controls and exposed as public properties on the control. The control translates each Windows Forms ambient property to its [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] equivalent. + Some of the ambient properties of Windows Forms controls have WPF equivalents. These ambient properties are propagated to the hosted WPF controls and exposed as public properties on the control. The control translates each Windows Forms ambient property to its WPF equivalent. For more information, see [Windows Forms and WPF Property Mapping](windows-forms-and-wpf-property-mapping.md). @@ -104,12 +104,12 @@ ms.assetid: 9e8aa6b6-112c-4579-98d1-c974917df499 |Behavior|Supported|Not supported| |--------------|---------------|-------------------| -|Transparency|[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] control rendering supports transparency. The background of the parent Windows Forms control can become the background of hosted [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] controls.|Not applicable.| -|Multithreading|All varieties of multithreading are supported.|Both the Windows Forms and [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] technologies assume a single-threaded concurrency model. During debugging, calls to framework objects from other threads will raise an exception to enforce this requirement.| +|Transparency|WPF control rendering supports transparency. The background of the parent Windows Forms control can become the background of hosted WPF controls.|Not applicable.| +|Multithreading|All varieties of multithreading are supported.|Both the Windows Forms and WPF technologies assume a single-threaded concurrency model. During debugging, calls to framework objects from other threads will raise an exception to enforce this requirement.| |Security|All interoperation scenarios require full trust.|No interoperation scenarios are allowed in partial trust.| -|Accessibility|All accessibility scenarios are supported. Assistive technology products function correctly when they are used for hybrid applications that contain both Windows Forms and [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] controls.|Not applicable.| -|Clipboard|All Clipboard operations work as usual. This includes cutting and pasting between Windows Forms and [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] controls.|Not applicable.| -|Drag-and-drop feature|All drag-and-drop operations work as usual. This includes operations between Windows Forms and [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] controls.|Not applicable.| +|Accessibility|All accessibility scenarios are supported. Assistive technology products function correctly when they are used for hybrid applications that contain both Windows Forms and WPF controls.|Not applicable.| +|Clipboard|All Clipboard operations work as usual. This includes cutting and pasting between Windows Forms and WPF controls.|Not applicable.| +|Drag-and-drop feature|All drag-and-drop operations work as usual. This includes operations between Windows Forms and WPF controls.|Not applicable.| ## See also diff --git a/dotnet-desktop-guide/framework/wpf/advanced/wpf-architecture.md b/dotnet-desktop-guide/framework/wpf/advanced/wpf-architecture.md index 9256ee6..1d717b8 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/wpf-architecture.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/wpf-architecture.md @@ -112,7 +112,7 @@ This topic provides a guided tour of the Windows Presentation Foundation (WPF) c The two most critical things that introduces are data binding and styles. - The data binding subsystem in WPF should be relatively familiar to anyone that has used Windows Forms or ASP.NET for creating an application [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)]. In each of these systems, there is a simple way to express that you want one or more properties from a given element to be bound to a piece of data. WPF has full support for property binding, transformation, and list binding. + The data binding subsystem in WPF should be relatively familiar to anyone that has used Windows Forms or ASP.NET for creating an application user interface (UI). In each of these systems, there is a simple way to express that you want one or more properties from a given element to be bound to a piece of data. WPF has full support for property binding, transformation, and list binding. One of the most interesting features of data binding in WPF is the introduction of data templates. Data templates allow you to declaratively specify how a piece of data should be visualized. Instead of creating a custom user interface that can be bound to data, you can instead turn the problem around and let the data determine the display that will be created. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/wpf-globalization-and-localization-overview.md b/dotnet-desktop-guide/framework/wpf/advanced/wpf-globalization-and-localization-overview.md index 1b03e46..8cb0bb9 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/wpf-globalization-and-localization-overview.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/wpf-globalization-and-localization-overview.md @@ -12,25 +12,25 @@ ms.assetid: 56e5a5c8-6c96-4d19-b8e1-a5be1dc564af When you limit your product's availability to only one language, you limit your potential customer base to a fraction of our world's 7.5 billion population. If you want your applications to reach a global audience, cost-effective localization of your product is one of the best and most economical ways to reach more customers. -This overview introduces globalization and localization in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)]. Globalization is the design and development of applications that perform in multiple locations. For example, globalization supports localized user interfaces and regional data for users in different cultures. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides globalized design features, including automatic layout, satellite assemblies, and localized attributes and commenting. +This overview introduces globalization and localization in WPF provides globalized design features, including automatic layout, satellite assemblies, and localized attributes and commenting. -Localization is the translation of application resources into localized versions for the specific cultures that the application supports. When you localize in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], you use the APIs in the namespace. These APIs power the [LocBaml Tool Sample](https://github.com/microsoft/WPF-Samples/tree/master/Tools/LocBaml) command-line tool. For information about how to build and use LocBaml, see [Localize an Application](how-to-localize-an-application.md). +Localization is the translation of application resources into localized versions for the specific cultures that the application supports. When you localize in WPF, you use the APIs in the namespace. These APIs power the [LocBaml Tool Sample](https://github.com/microsoft/WPF-Samples/tree/master/Tools/LocBaml) command-line tool. For information about how to build and use LocBaml, see [Localize an Application](how-to-localize-an-application.md). ## Best Practices for Globalization and Localization in WPF -You can make the most of the globalization and localization functionality that is built into [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] by following the UI design and localization-related tips that this section provides. +You can make the most of the globalization and localization functionality that is built into WPF by following the UI design and localization-related tips that this section provides. ### Best Practices for WPF UI Design -When you design a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]–based [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)], consider implementing these best practices: +When you design a UI, consider implementing these best practices: -- Write your [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]; avoid creating [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] in code. When you create your [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] by using [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], you expose it through built-in localization APIs. +- Write your UI in UI in code. When you create your UI by using XAML, you expose it through built-in localization APIs. - Avoid using absolute positions and fixed sizes to lay out content; instead, use relative or automatic sizing. - Use and keep widths and heights set to `Auto`. - - Avoid using to lay out [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)]s. + - Avoid using to lay out UIs. - Use and its size-sharing feature. @@ -38,9 +38,9 @@ When you design a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-w - Enable on to avoid clipping. -- Set the `xml:lang` attribute. This attribute describes the culture of a specific element and its child elements. The value of this property changes the behavior of several features in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. For example, it changes the behavior of hyphenation, spell checking, number substitution, complex script shaping, and font fallback. See [Globalization for WPF](globalization-for-wpf.md) for more information about setting the [xml:lang Handling in XAML](/dotnet/desktop/xaml-services/xml-language-handling). +- Set the `xml:lang` attribute. This attribute describes the culture of a specific element and its child elements. The value of this property changes the behavior of several features in WPF. For example, it changes the behavior of hyphenation, spell checking, number substitution, complex script shaping, and font fallback. See [Globalization for WPF](globalization-for-wpf.md) for more information about setting the [xml:lang Handling in XAML](/dotnet/desktop/xaml-services/xml-language-handling). -- Create a customized composite font to obtain better control of fonts that are used for different languages. By default, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] uses the GlobalUserInterface.composite font in your Windows\Fonts directory. +- Create a customized composite font to obtain better control of fonts that are used for different languages. By default, WPF uses the GlobalUserInterface.composite font in your Windows\Fonts directory. - When you create navigation applications that may be localized in a culture that presents text in a right-to-left format, explicitly set the of every page to ensure the page does not inherit from the . @@ -48,13 +48,13 @@ When you design a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-w ### Best Practices for WPF Localization -When you localize [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]–based applications, consider implementing these best practices: +When you localize WPF–based applications, consider implementing these best practices: - Use localization comments to provide extra context for localizers. - Use localization attributes to control localization instead of selectively omitting properties on elements. See [Localization Attributes and Comments](localization-attributes-and-comments.md) for more information. -- Use `msbuild -t:updateuid` and `-t:checkuid` to add and check properties in your [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]. Use properties to track changes between development and localization. properties help you localize new development changes. If you manually add properties to a [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)], the task is typically tedious and less accurate. +- Use `msbuild -t:updateuid` and `-t:checkuid` to add and check properties in your UI, the task is typically tedious and less accurate. - Do not edit or change properties after you begin localization. @@ -66,27 +66,27 @@ When you localize [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-w ## Localize a WPF Application -When you localize a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application, you have several options. For example, you can bind the localizable resources in your application to an XML file, store localizable text in resx tables, or have your localizer use [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] files. This section describes a localization workflow that uses the BAML form of XAML, which provides several benefits: +When you localize a WPF application, you have several options. For example, you can bind the localizable resources in your application to an XML file, store localizable text in resx tables, or have your localizer use Extensible Application Markup Language (XAML) files. This section describes a localization workflow that uses the BAML form of XAML, which provides several benefits: - You can localize after you build. - You can update to a newer version of the BAML form of XAML with localizations from an older version of the BAML form of XAML so that you can localize at the same time that you develop. -- You can validate original source elements and semantics at compile time because the BAML form of XAML is the compiled form of [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]. +- You can validate original source elements and semantics at compile time because the BAML form of XAML is the compiled form of XAML. ### Localization Build Process -When you develop a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application, the build process for localization is as follows: +When you develop a WPF application, the build process for localization is as follows: -- The developer creates and globalizes the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application. In the project file the developer sets `en-US` so that when the application is compiled, a language-neutral main assembly is generated. This assembly has a satellite .resources.dll file that contains all the localizable resources. Optionally, you can keep the source language in the main assembly because our localization APIs support extraction from the main assembly. +- The developer creates and globalizes the WPF application. In the project file the developer sets `en-US` so that when the application is compiled, a language-neutral main assembly is generated. This assembly has a satellite .resources.dll file that contains all the localizable resources. Optionally, you can keep the source language in the main assembly because our localization APIs support extraction from the main assembly. -- When the file is compiled into the build, the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] is converted to the BAML form of XAML. The culturally neutral `MyDialog.exe` and the culturally dependent (English) `MyDialog.resources.dll` files are released to the English-speaking customer. +- When the file is compiled into the build, the XAML is converted to the BAML form of XAML. The culturally neutral `MyDialog.exe` and the culturally dependent (English) `MyDialog.resources.dll` files are released to the English-speaking customer. ### Localization Workflow -The localization process begins after the unlocalized `MyDialog.resources.dll` file is built. The [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] elements and properties in your original [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] are extracted from the BAML form of XAML into key-value pairs by using the APIs under . Localizers use the key-value pairs to localize the application. You can generate a new .resource.dll from the new values after localization is complete. +The localization process begins after the unlocalized `MyDialog.resources.dll` file is built. The UI elements and properties in your original XAML are extracted from the BAML form of XAML into key-value pairs by using the APIs under . Localizers use the key-value pairs to localize the application. You can generate a new .resource.dll from the new values after localization is complete. -The keys of the key-value pairs are `x:Uid` values that are placed by the developer in the original [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]. These `x:Uid` values enable the API to track and merge changes that happen between the developer and the localizer during localization. For example, if the developer changes the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] after the localizer begins localizing, you can merge the development change with the already completed localization work so that minimal translation work is lost. +The keys of the key-value pairs are `x:Uid` values that are placed by the developer in the original UI after the localizer begins localizing, you can merge the development change with the already completed localization work so that minimal translation work is lost. The following graphic shows a typical localization workflow that is based on the BAML form of XAML. This diagram assumes the developer writes the application in English. The developer creates and globalizes the WPF application. In the project file the developer sets `en-US` so that on build, a language neutral main assembly gets generated with a satellite .resources.dll containing all localizable resources. Alternately, one could keep the source language in the main assembly because WPF localization APIs support extraction from the main assembly. After the build process, the XAML get compiled into BAML. The culturally neutral MyDialog.exe.resources.dll get shipped to the English speaking customer. @@ -96,7 +96,7 @@ The following graphic shows a typical localization workflow that is based on the ## Examples of WPF Localization -This section contains examples of localized applications to help you understand how to build and localize [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications. +This section contains examples of localized applications to help you understand how to build and localize WPF applications. ### Run Dialog Box Example @@ -112,7 +112,7 @@ The following graphics show the output of the **Run** dialog box sample. **Designing a Global Run Dialog Box** -This example produces a **Run** dialog box by using [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] and [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]. This dialog box is equivalent to the **Run** dialog box that is available from the Microsoft Windows Start menu. +This example produces a **Run** dialog box by using WPF and XAML. This dialog box is equivalent to the **Run** dialog box that is available from the Microsoft Windows Start menu. Some highlights for making global dialog boxes are: @@ -126,15 +126,15 @@ The previous Window property automatically resizes the window according to the s `` - properties are needed in order for [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] localization APIs to work correctly. + properties are needed in order for WPF localization APIs to work correctly. -They are used by [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] localization APIs to track changes between the development and localization of the [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)]. properties enable you to merge a newer version of the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] with an older localization of the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)]. You add a property by running `msbuild -t:updateuid RunDialog.csproj` in a command shell. This is the recommended method of adding properties because manually adding them is typically time-consuming and less accurate. You can check that properties are correctly set by running `msbuild -t:checkuid RunDialog.csproj`. +They are used by UI with an older localization of the UI. You add a property by running `msbuild -t:updateuid RunDialog.csproj` in a command shell. This is the recommended method of adding properties because manually adding them is typically time-consuming and less accurate. You can check that properties are correctly set by running `msbuild -t:checkuid RunDialog.csproj`. -The [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] is structured by using the control, which is a useful control for taking advantage of the automatic layout in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. Note that the dialog box is split into three rows and five columns. Not one of the row and column definitions has a fixed size; hence, the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] elements that are positioned in each cell can adapt to increases and decreases in size during localization. +The UI is structured by using the control, which is a useful control for taking advantage of the automatic layout in UI elements that are positioned in each cell can adapt to increases and decreases in size during localization. [!code-xaml[GlobalizationRunDialog#GridColumnDef](~/samples/snippets/csharp/VS_Snippets_Wpf/GlobalizationRunDialog/CS/Window1.xaml#gridcolumndef)] -The first two columns where the **Open:** label and are placed use 10 percent of the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] total width. +The first two columns where the **Open:** label and are placed use 10 percent of the UI total width. [!code-xaml[GlobalizationRunDialog#GridColumnDef2](~/samples/snippets/csharp/VS_Snippets_Wpf/GlobalizationRunDialog/CS/Window1.xaml#gridcolumndef2)] @@ -144,7 +144,7 @@ Note that of the example uses the shared-sizing feature of property on . Changing this property to will change the of the and its children elements so that the layout of this [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] is flipped to become right-to-left as an Arabic user would expect. One can override the inheritance behavior by specifying an explicit on any element. The property is available on any or document related element and has an implicit value of . +Notice the property on . Changing this property to will change the of the and its children elements so that the layout of this UI is flipped to become right-to-left as an Arabic user would expect. One can override the inheritance behavior by specifying an explicit on any element. The property is available on any or document related element and has an implicit value of . Observe that even the background gradient brushes are flipped correctly when the root is changed: @@ -253,7 +253,7 @@ Observe that even the background gradient brushes are flipped correctly when the **Avoid Using Fixed Dimensions for Panels and Controls** -Take a look through Homepage.xaml, notice that aside from the fixed width and height specified for the entire [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] on the top , there are no other fixed dimensions. Avoid using fixed dimensions to prevent clipping localized text that may be longer than the source text. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] panels and controls will automatically resize based on the content that they contain. Most controls also have minimum and maximum dimensions that you can set for more control (for example, MinWidth="20"). With , you can also set relative widths and heights by using '\*' (for example, `Width="0.25*"`) or use its cell size sharing feature. +Take a look through Homepage.xaml, notice that aside from the fixed width and height specified for the entire UI on the top , there are no other fixed dimensions. Avoid using fixed dimensions to prevent clipping localized text that may be longer than the source text. WPF panels and controls will automatically resize based on the content that they contain. Most controls also have minimum and maximum dimensions that you can set for more control (for example, MinWidth="20"). With , you can also set relative widths and heights by using '\*' (for example, `Width="0.25*"`) or use its cell size sharing feature. **Localization Comments** @@ -273,15 +273,15 @@ Comments can be placed on the content or property of any element using the follo **Localization Attributes** -Often the developer or localization manager needs control of what localizers can read and modify. For example, you might not want the localizer to translate the name of your company or legal wording. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides attributes that enable you to set the readability, modifiability, and category of an element's content or property which your localization tool can use to lock, hide, or sort elements. For more information, see . For the purposes of this sample, the LocBaml Tool just outputs the values of these attributes. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] controls all have default values for these attributes, but you the can override them. For example, the following example overrides the default localization attributes for `TextBlock_1` and sets the content to be readable but unmodifiable for localizers. +Often the developer or localization manager needs control of what localizers can read and modify. For example, you might not want the localizer to translate the name of your company or legal wording. WPF provides attributes that enable you to set the readability, modifiability, and category of an element's content or property which your localization tool can use to lock, hide, or sort elements. For more information, see . For the purposes of this sample, the LocBaml Tool just outputs the values of these attributes. WPF controls all have default values for these attributes, but you the can override them. For example, the following example overrides the default localization attributes for `TextBlock_1` and sets the content to be readable but unmodifiable for localizers. [!code-xaml[LocalizationComAtt#LocalizationAttributes](~/samples/snippets/csharp/VS_Snippets_Wpf/LocalizationComAtt/CSharp/Attributes.xaml#localizationattributes)] -In addition to the readability and modifiability attributes, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides an enumeration of common UI categories () that can be used to give localizers more context. The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] default categories for platform controls can be overridden in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] as well: +In addition to the readability and modifiability attributes, WPF provides an enumeration of common UI categories () that can be used to give localizers more context. The WPF default categories for platform controls can be overridden in XAML as well: [!code-xaml[LocalizationComAtt#LocalizationAttributesOverridden](~/samples/snippets/csharp/VS_Snippets_Wpf/LocalizationComAtt/CSharp/Attributes.xaml#localizationattributesoverridden)] -The default localization attributes that [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides can also be overridden through code, so you can correctly set the right default values for custom controls. For example: +The default localization attributes that WPF provides can also be overridden through code, so you can correctly set the right default values for custom controls. For example: ```csharp [Localizability(Readability = Readability.Readable, Modifiability=Modifiability.Unmodifiable, LocalizationCategory.None)] @@ -291,11 +291,11 @@ public class CorporateLogo : TextBlock } ``` -The per instance attributes set in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] will take precedence over the values set in code on custom controls. For more information on attributes and comments, see [Localization Attributes and Comments](localization-attributes-and-comments.md). +The per instance attributes set in XAML will take precedence over the values set in code on custom controls. For more information on attributes and comments, see [Localization Attributes and Comments](localization-attributes-and-comments.md). **Font Fallback and Composite Fonts** -If you specify a font that does not support a given codepoint range, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] will automatically fallback to one that does by using the Global User Interface.compositefont that is located in your Windows\Fonts directory. Composite fonts work just as any other font and can be used explicitly by setting an element's `FontFamily` (for instance, `FontFamily="Global User Interface"`). You can specify your own font fallback preference by creating your own composite font and specifying what font to use for specific codepoint ranges and languages. +If you specify a font that does not support a given codepoint range, WPF will automatically fallback to one that does by using the Global User Interface.compositefont that is located in your Windows\Fonts directory. Composite fonts work just as any other font and can be used explicitly by setting an element's `FontFamily` (for instance, `FontFamily="Global User Interface"`). You can specify your own font fallback preference by creating your own composite font and specifying what font to use for specific codepoint ranges and languages. For more information on composite fonts see . diff --git a/dotnet-desktop-guide/framework/wpf/advanced/wpf-xaml-namescopes.md b/dotnet-desktop-guide/framework/wpf/advanced/wpf-xaml-namescopes.md index 894c9d7..75bf2c8 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/wpf-xaml-namescopes.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/wpf-xaml-namescopes.md @@ -12,16 +12,16 @@ helpviewer_keywords: ms.assetid: 52bbf4f2-15fc-40d4-837b-bb4c21ead7d4 --- # WPF XAML Namescopes -XAML namescopes are a concept that identifies objects that are defined in XAML. The names in a XAML namescope can be used to establish relationships between the XAML-defined names of objects and their instance equivalents in an object tree. Typically, XAML namescopes in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] managed code are created when loading the individual XAML page roots for a XAML application. XAML namescopes as the programming object are defined by the interface and are also implemented by the practical class . +XAML namescopes are a concept that identifies objects that are defined in XAML. The names in a XAML namescope can be used to establish relationships between the XAML-defined names of objects and their instance equivalents in an object tree. Typically, XAML namescopes in WPF managed code are created when loading the individual XAML page roots for a XAML application. XAML namescopes as the programming object are defined by the interface and are also implemented by the practical class . ## Namescopes in Loaded XAML Applications In a broader programming or computer science context, programming concepts often include the principle of a unique identifier or name that can be used to access an object. For systems that use identifiers or names, the namescope defines the boundaries within which a process or technique will search if an object of that name is requested, or the boundaries wherein uniqueness of identifying names is enforced. These general principles are true for XAML namescopes. In WPF, XAML namescopes are created on the root element for a XAML page when the page is loaded. Each name specified within the XAML page starting at the page root is added to a pertinent XAML namescope. - In WPF XAML, elements that are common root elements (such as , and ) always control a XAML namescope. If an element such as or is the root element of the page in markup, a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor adds a root implicitly so that the can provide a working XAML namescope. + In WPF XAML, elements that are common root elements (such as , and ) always control a XAML namescope. If an element such as or is the root element of the page in markup, a XAML processor adds a root implicitly so that the can provide a working XAML namescope. > [!NOTE] -> WPF build actions create a XAML namescope for a XAML production even if no `Name` or `x:Name` attributes are defined on any elements in the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] markup. +> WPF build actions create a XAML namescope for a XAML production even if no `Name` or `x:Name` attributes are defined on any elements in the XAML markup. If you try to use the same name twice in any XAML namescope, an exception is raised. For WPF XAML that has code-behind and is part of a compiled application, the exception is raised at build time by WPF build actions, when creating the generated class for the page during the initial markup compile. For XAML that is not markup-compiled by any build action, exceptions related to XAML namescope issues might be raised when the XAML is loaded. XAML designers might also anticipate XAML namescope issues at design time. @@ -33,7 +33,7 @@ XAML namescopes are a concept that identifies objects that are defined in XAML. If you call on an object other than the object that defines the XAML namescope, the name is still registered to the XAML namescope that the calling object is held within, as if you had called on the XAML namescope defining object. ### XAML Namescopes in Code - You can create and then use XAML namescopes in code. The APIs and the concepts involved in XAML namescope creation are the same even for a pure code usage, because the XAML processor for [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] uses these APIs and concepts when it processes XAML itself. The concepts and API exist mainly for the purpose of being able to find objects by name within an object tree that is typically defined partially or entirely in XAML. + You can create and then use XAML namescopes in code. The APIs and the concepts involved in XAML namescope creation are the same even for a pure code usage, because the XAML processor for WPF uses these APIs and concepts when it processes XAML itself. The concepts and API exist mainly for the purpose of being able to find objects by name within an object tree that is typically defined partially or entirely in XAML. For applications that are created programmatically, and not from loaded XAML, the object that defines a XAML namescope must implement , or be a or derived class, in order to support creation of a XAML namescope on its instances. @@ -45,7 +45,7 @@ XAML namescopes are a concept that identifies objects that are defined in XAML. ## XAML Namescopes in Styles and Templates - Styles and templates in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provide the ability to reuse and reapply content in a straightforward way. However, styles and templates might also include elements with XAML names defined at the template level. That same template might be used multiple times in a page. For this reason, styles and templates both define their own XAML namescopes, independent of whatever location in an object tree where the style or template is applied. + Styles and templates in WPF provide the ability to reuse and reapply content in a straightforward way. However, styles and templates might also include elements with XAML names defined at the template level. That same template might be used multiple times in a page. For this reason, styles and templates both define their own XAML namescopes, independent of whatever location in an object tree where the style or template is applied. Consider the following example: @@ -80,7 +80,7 @@ XAML namescopes are a concept that identifies objects that are defined in XAML. does not use XAML names or namescopes ; it uses keys instead, because it is a dictionary implementation. The only reason that implements is so it can raise exceptions to user code that help clarify the distinction between a true XAML namescope and how a handles keys, and also to assure that XAML namescopes are not applied to a by parent elements. - and implement through explicit interface definitions. The explicit implementations allow these XAML namescopes to behave conventionally when they are accessed through the interface, which is how XAML namescopes are communicated by [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] internal processes. But the explicit interface definitions are not part of the conventional API surface of and , because you seldom need to call the methods on and directly, and instead would use other API such as . + and implement through explicit interface definitions. The explicit implementations allow these XAML namescopes to behave conventionally when they are accessed through the interface, which is how XAML namescopes are communicated by WPF internal processes. But the explicit interface definitions are not part of the conventional API surface of and , because you seldom need to call the methods on and directly, and instead would use other API such as . The following classes define their own XAML namescope, by using the helper class and connecting to its XAML namescope implementation through the attached property: diff --git a/dotnet-desktop-guide/framework/wpf/advanced/xaml-and-custom-classes-for-wpf.md b/dotnet-desktop-guide/framework/wpf/advanced/xaml-and-custom-classes-for-wpf.md index 163c741..737f0a0 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/xaml-and-custom-classes-for-wpf.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/xaml-and-custom-classes-for-wpf.md @@ -8,11 +8,11 @@ helpviewer_keywords: ms.assetid: e7313137-581e-4a64-8453-d44e15a6164a --- # XAML and Custom Classes for WPF -XAML as implemented in common language runtime (CLR) frameworks supports the ability to define a custom class or structure in any common language runtime (CLR) language, and then access that class using XAML markup. You can use a mixture of [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)]-defined types and your custom types within the same markup file, typically by mapping the custom types to a XAML namespace prefix. This topic discusses the requirements that a custom class must satisfy to be usable as a XAML element. +XAML as implemented in common language runtime (CLR) frameworks supports the ability to define a custom class or structure in any common language runtime (CLR) language, and then access that class using XAML markup. You can use a mixture of Windows Presentation Foundation (WPF)-defined types and your custom types within the same markup file, typically by mapping the custom types to a XAML namespace prefix. This topic discusses the requirements that a custom class must satisfy to be usable as a XAML element. ## Custom Classes in Applications or Assemblies - Custom classes that are used in XAML can be defined in two distinct ways: within the code-behind or other code that produces the primary [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] application, or as a class in a separate assembly, such as an executable or DLL used as a class library. Each of these approaches has particular advantages and disadvantages. + Custom classes that are used in XAML can be defined in two distinct ways: within the code-behind or other code that produces the primary Windows Presentation Foundation (WPF) application, or as a class in a separate assembly, such as an executable or DLL used as a class library. Each of these approaches has particular advantages and disadvantages. - The advantage of creating a class library is that any such custom classes can be shared across many different possible applications. A separate library also makes versioning issues of applications easier to control, and simplifies creating a class where the intended class usage is as a root element on a XAML page. @@ -26,12 +26,12 @@ XAML as implemented in common language runtime (CLR) frameworks supports the abi - Your custom class must be public and support a default (parameterless) public constructor. (See following section for notes regarding structures.) -- Your custom class must not be a nested class. Nested classes and the "dot" in their general CLR usage syntax interfere with other [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] and/or XAML features such as attached properties. +- Your custom class must not be a nested class. Nested classes and the "dot" in their general CLR usage syntax interfere with other WPF and/or XAML features such as attached properties. In addition to enabling object element syntax, your object definition also enables property element syntax for any other public properties that take that object as the value type. This is because the object can now be instantiated as an object element and can fill the property element value of such a property. ### Structures - Structures that you define as custom types are always able to be constructed in XAML in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] .This is because the CLR compilers implicitly create a parameterless constructor for a structure that initializes all property values to their defaults. In some cases, the default construction behavior and/or object element usage for a structure is not desirable. This might be because the structure is intended to fill values and function conceptually as a union, where the values contained might have mutually exclusive interpretations and thus none of its properties are settable. A [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] example of such a structure is . Generally, such structures should implement a type converter such that the values can be expressed in attribute form, using string conventions that create the different interpretations or modes of the structure's values. The structure should also expose similar behavior for code construction through a non-parameterless constructor. + Structures that you define as custom types are always able to be constructed in XAML in WPF .This is because the CLR compilers implicitly create a parameterless constructor for a structure that initializes all property values to their defaults. In some cases, the default construction behavior and/or object element usage for a structure is not desirable. This might be because the structure is intended to fill values and function conceptually as a union, where the values contained might have mutually exclusive interpretations and thus none of its properties are settable. A WPF example of such a structure is . Generally, such structures should implement a type converter such that the values can be expressed in attribute form, using string conventions that create the different interpretations or modes of the structure's values. The structure should also expose similar behavior for code construction through a non-parameterless constructor. ## Requirements for Properties of a Custom Class as XAML Attributes @@ -51,9 +51,9 @@ XAML as implemented in common language runtime (CLR) frameworks supports the abi Examples of properties where attribute syntax is allowed but property element syntax that contains an object element is disallowed through XAML are various properties that take the type. The class has a dedicated type converter , but does not expose a parameterless constructor, so the property can only be set through attribute syntax even though the actual type is a reference type. ### Per-Property Type Converters - Alternatively, the property itself may declare a type converter at the property level. This enables a "mini language" that instantiates objects of the type of the property inline, by processing incoming string values of the attribute as input for a operation based on the appropriate type. Typically this is done to provide a convenience accessor, and not as the sole means to enable setting a property in XAML. However, it is also possible to use type converters for attributes where you want to use existing CLR types that do not supply either a parameterless constructor or an attributed type converter. Examples from the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] API are certain properties that take the type. In this case, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] used the existing Microsoft .NET Framework type to better address compatibility and migration scenarios that were used in earlier versions of frameworks, but the type did not support the necessary constructors or type-level type conversion to be usable as a XAML property value directly. + Alternatively, the property itself may declare a type converter at the property level. This enables a "mini language" that instantiates objects of the type of the property inline, by processing incoming string values of the attribute as input for a operation based on the appropriate type. Typically this is done to provide a convenience accessor, and not as the sole means to enable setting a property in XAML. However, it is also possible to use type converters for attributes where you want to use existing CLR types that do not supply either a parameterless constructor or an attributed type converter. Examples from the WPF API are certain properties that take the type. In this case, WPF used the existing Microsoft .NET Framework type to better address compatibility and migration scenarios that were used in earlier versions of frameworks, but the type did not support the necessary constructors or type-level type conversion to be usable as a XAML property value directly. - Whenever you expose a property that has a XAML usage, particularly if you are a control author, you should strongly consider backing that property with a dependency property. This is particularly true if you use the existing [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] implementation of the XAML processor, because you can improve performance by using backing. A dependency property will expose property system features for your property that users will come to expect for a XAML accessible property. This includes features such as animation, data binding, and style support. For more information, see [Custom Dependency Properties](custom-dependency-properties.md) and [XAML Loading and Dependency Properties](xaml-loading-and-dependency-properties.md). + Whenever you expose a property that has a XAML usage, particularly if you are a control author, you should strongly consider backing that property with a dependency property. This is particularly true if you use the existing Windows Presentation Foundation (WPF) implementation of the XAML processor, because you can improve performance by using backing. A dependency property will expose property system features for your property that users will come to expect for a XAML accessible property. This includes features such as animation, data binding, and style support. For more information, see [Custom Dependency Properties](custom-dependency-properties.md) and [XAML Loading and Dependency Properties](xaml-loading-and-dependency-properties.md). ### Writing and Attributing a Type Converter You occasionally will need to write a custom derived class to provide type conversion for your property type. For instructions on how to derive from and create a type converter that can support XAML usages, and how to apply the , see [TypeConverters and XAML](typeconverters-and-xaml.md). @@ -81,12 +81,12 @@ XAML as implemented in common language runtime (CLR) frameworks supports the abi - Derives from (for more information about arrays in XAML, see [x:Array Markup Extension](/dotnet/desktop/xaml-services/xarray-markup-extension).) -- Implements (an interface defined by [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]). +- Implements (an interface defined by WPF). Each of these types in CLR has an `Add` method, which is used by the XAML processor to add items to the underlying collection when creating the object graph. > [!NOTE] -> The generic `List` and `Dictionary` interfaces ( and ) are not supported for collection detection by the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] XAML processor. However, you can use the class as a base class, because it implements directly, or as a base class, because it implements directly. +> The generic `List` and `Dictionary` interfaces ( and ) are not supported for collection detection by the WPF XAML processor. However, you can use the class as a base class, because it implements directly, or as a base class, because it implements directly. When you declare a property that takes a collection, be cautious about how that property value is initialized in new instances of the type. If you are not implementing the property as a dependency property, then having the property use a backing field that calls the collection type constructor is adequate. If your property is a dependency property, then you may need to initialize the collection property as part of the default type constructor. This is because a dependency property takes its default value from metadata, and you typically do not want the initial value of a collection property to be a static, shared collection. There should be a collection instance per each containing type instance. For more information, see [Custom Dependency Properties](custom-dependency-properties.md). @@ -94,7 +94,7 @@ XAML as implemented in common language runtime (CLR) frameworks supports the abi ## Declaring XAML Content Properties - The XAML language defines the concept of a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] content property. Each class that is usable in object syntax can have exactly one XAML content property. To declare a property to be the XAML content property for your class, apply the as part of the class definition. Specify the name of the intended XAML content property as the in the attribute. The property is specified as a string by name, not as a reflection construct such as . + The XAML language defines the concept of a XAML content property. Each class that is usable in object syntax can have exactly one XAML content property. To declare a property to be the XAML content property for your class, apply the as part of the class definition. Specify the name of the intended XAML content property as the in the attribute. The property is specified as a string by name, not as a reflection construct such as . You can specify a collection property to be the XAML content property. This results in a usage for that property whereby the object element can have one or more child elements, without any intervening collection object elements or property element tags. These elements are then treated as the value for the XAML content property and added to the backing collection instance. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/xaml-in-wpf.md b/dotnet-desktop-guide/framework/wpf/advanced/xaml-in-wpf.md index 6115147..951bb15 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/xaml-in-wpf.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/xaml-in-wpf.md @@ -10,7 +10,7 @@ ms.assetid: 5d858575-a83b-42df-ad3f-047ed2d6e3c8 --- # XAML in WPF -[!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] is a markup language for declarative application programming. [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] implements a XAML processor implementation and provides XAML language support. The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] types are implemented such that they can provide the required type backing for a XAML representation. In general, you can create the majority of your [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application UI in XAML markup. +WPF types are implemented such that they can provide the required type backing for a XAML representation. In general, you can create the majority of your WPF application UI in XAML markup. ## In This Section diff --git a/dotnet-desktop-guide/framework/wpf/advanced/xaml-loading-and-dependency-properties.md b/dotnet-desktop-guide/framework/wpf/advanced/xaml-loading-and-dependency-properties.md index 4949d5c..37e6761 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/xaml-loading-and-dependency-properties.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/xaml-loading-and-dependency-properties.md @@ -11,7 +11,7 @@ helpviewer_keywords: ms.assetid: 6eea9f4e-45ce-413b-a266-f08238737bf2 --- # XAML Loading and Dependency Properties -The current [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] implementation of its [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor is inherently dependency property aware. The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor uses property system methods for dependency properties when loading binary [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] and processing attributes that are dependency properties. This effectively bypasses the property wrappers. When you implement custom dependency properties, you must account for this behavior and should avoid placing any other code in your property wrapper other than the property system methods and . +The current WPF implementation of its WPF XAML processor uses property system methods for dependency properties when loading binary XAML and processing attributes that are dependency properties. This effectively bypasses the property wrappers. When you implement custom dependency properties, you must account for this behavior and should avoid placing any other code in your property wrapper other than the property system methods and . ## Prerequisites @@ -19,15 +19,15 @@ The current [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclie ## The WPF XAML Loader Implementation, and Performance - For implementation reasons, it is computationally less expensive to identify a property as a dependency property and access the property system method to set it, rather than using the property wrapper and its setter. This is because a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor must infer the entire object model of the backing code based only on knowing the type and member relationships that are indicated by the structure of the markup and various strings. + For implementation reasons, it is computationally less expensive to identify a property as a dependency property and access the property system method to set it, rather than using the property wrapper and its setter. This is because a XAML processor must infer the entire object model of the backing code based only on knowing the type and member relationships that are indicated by the structure of the markup and various strings. - The type is looked up through a combination of xmlns and assembly attributes, but identifying the members, determining which could support being set as an attribute, and resolving what types the property values support would otherwise require extensive reflection using . Because dependency properties on a given type are accessible as a storage table through the property system, the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] implementation of its [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor uses this table and infers that any given property *ABC* can be more efficiently set by calling on the containing derived type, using the dependency property identifier *ABCProperty*. + The type is looked up through a combination of xmlns and assembly attributes, but identifying the members, determining which could support being set as an attribute, and resolving what types the property values support would otherwise require extensive reflection using . Because dependency properties on a given type are accessible as a storage table through the property system, the WPF implementation of its XAML processor uses this table and infers that any given property *ABC* can be more efficiently set by calling on the containing derived type, using the dependency property identifier *ABCProperty*. ## Implications for Custom Dependency Properties - Because the current [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] implementation of the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor behavior for property setting bypasses the wrappers entirely, you should not put any additional logic into the set definitions of the wrapper for your custom dependency property. If you put such logic in the set definition, then the logic will not be executed when the property is set in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] rather than in code. + Because the current WPF implementation of the XAML processor behavior for property setting bypasses the wrappers entirely, you should not put any additional logic into the set definitions of the wrapper for your custom dependency property. If you put such logic in the set definition, then the logic will not be executed when the property is set in XAML rather than in code. - Similarly, other aspects of the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor that obtain property values from [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processing also use rather than using the wrapper. Therefore, you should also avoid any additional implementation in the `get` definition beyond the call. + Similarly, other aspects of the XAML processor that obtain property values from XAML processing also use rather than using the wrapper. Therefore, you should also avoid any additional implementation in the `get` definition beyond the call. The following example is a recommended dependency property definition with wrappers, where the property identifier is stored as a `public` `static` `readonly` field, and the `get` and `set` definitions contain no code beyond the necessary property system methods that define the dependency property backing. diff --git a/dotnet-desktop-guide/framework/wpf/advanced/xaml-namespaces-and-namespace-mapping-for-wpf-xaml.md b/dotnet-desktop-guide/framework/wpf/advanced/xaml-namespaces-and-namespace-mapping-for-wpf-xaml.md index 1ce8db2..d992ba6 100644 --- a/dotnet-desktop-guide/framework/wpf/advanced/xaml-namespaces-and-namespace-mapping-for-wpf-xaml.md +++ b/dotnet-desktop-guide/framework/wpf/advanced/xaml-namespaces-and-namespace-mapping-for-wpf-xaml.md @@ -36,7 +36,7 @@ This topic further explains the presence and purpose of the two XAML namespace m `xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"` - The relationship between these declarations is that the `x:` prefix mapping supports the intrinsics that are part of the XAML language definition, and [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] is one implementation that uses XAML as a language and defines a vocabulary of its objects for XAML. Because the WPF vocabulary's usages will be far more common than the XAML intrinsics usages, the WPF vocabulary is mapped as the default. + The relationship between these declarations is that the `x:` prefix mapping supports the intrinsics that are part of the XAML language definition, and WPF is one implementation that uses XAML as a language and defines a vocabulary of its objects for XAML. Because the WPF vocabulary's usages will be far more common than the XAML intrinsics usages, the WPF vocabulary is mapped as the default. The `x:` prefix convention for mapping the XAML language intrinsics support is followed by project templates, sample code, and the documentation of language features within this SDK. The XAML namespace defines many commonly-used features that are necessary even for basic WPF applications. For instance, in order to join any code-behind to a XAML file through a partial class, you must name that class as the `x:Class` attribute in the root element of the relevant XAML file. Or, any element as defined in a XAML page that you wish to access as a keyed resource should have the `x:Key` attribute set on the element in question. For more information on these and other aspects of XAML see [XAML in WPF](xaml-in-wpf.md) or [XAML Syntax In Detail](xaml-syntax-in-detail.md). diff --git a/dotnet-desktop-guide/framework/wpf/app-development/build-and-deploy-how-to-topics.md b/dotnet-desktop-guide/framework/wpf/app-development/build-and-deploy-how-to-topics.md index 3e0fb33..538f7ff 100644 --- a/dotnet-desktop-guide/framework/wpf/app-development/build-and-deploy-how-to-topics.md +++ b/dotnet-desktop-guide/framework/wpf/app-development/build-and-deploy-how-to-topics.md @@ -10,7 +10,7 @@ ms.assetid: 88952ad2-5b74-48ca-a4c5-3f4fbb53ce12 --- # Build and deploy how-to topics -The following topics show how to create project files for the various [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application types. +The following topics show how to create project files for the various WPF application types. ## In this section diff --git a/dotnet-desktop-guide/framework/wpf/app-development/building-a-wpf-application-wpf.md b/dotnet-desktop-guide/framework/wpf/app-development/building-a-wpf-application-wpf.md index a9bb9cb..84cc494 100644 --- a/dotnet-desktop-guide/framework/wpf/app-development/building-a-wpf-application-wpf.md +++ b/dotnet-desktop-guide/framework/wpf/app-development/building-a-wpf-application-wpf.md @@ -59,17 +59,17 @@ The build process locates and binds the assemblies required to build the applica ### Markup Compilation—Pass 1 -In this step, [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] files are parsed and compiled so that the runtime does not spend time parsing XML and validating property values. The compiled [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file is pre-tokenized so that, at run time, loading it should be much faster than loading a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file. +In this step, XAML files are parsed and compiled so that the runtime does not spend time parsing XML and validating property values. The compiled XAML file is pre-tokenized so that, at run time, loading it should be much faster than loading a XAML file. -During this step, the following activities take place for every [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file that is a `Page` build item: +During this step, the following activities take place for every XAML file that is a `Page` build item: -1. The [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file is parsed by the markup compiler. +1. The XAML file is parsed by the markup compiler. -2. A compiled representation is created for that [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] and copied to the obj\Release folder. +2. A compiled representation is created for that XAML and copied to the obj\Release folder. 3. A CodeDOM representation of a new partial class is created and copied to the obj\Release folder. -In addition, a language-specific code file is generated for every [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file. For example, for a Page1.xaml page in a Visual Basic project, a Page1.g.vb is generated; for a Page1.xaml page in a C# project, a Page1.g.cs is generated. The ".g" in the file name indicates the file is generated code that has a partial class declaration for the top-level element of the markup file (such as `Page` or `Window`). The class is declared with the `partial` modifier in C# (`Extends` in Visual Basic) to indicate there is another declaration for the class elsewhere, usually in the code-behind file Page1.xaml.cs. +In addition, a language-specific code file is generated for every XAML file. For example, for a Page1.xaml page in a Visual Basic project, a Page1.g.vb is generated; for a Page1.xaml page in a C# project, a Page1.g.cs is generated. The ".g" in the file name indicates the file is generated code that has a partial class declaration for the top-level element of the markup file (such as `Page` or `Window`). The class is declared with the `partial` modifier in C# (`Extends` in Visual Basic) to indicate there is another declaration for the class elsewhere, usually in the code-behind file Page1.xaml.cs. The partial class extends from the appropriate base class (such as for a page) and implements the interface. The interface has methods to initialize a component and connect names and events on elements in its content. Consequently, the generated code file has a method implementation like the following: @@ -109,13 +109,13 @@ By default, markup compilation runs in the same as the M ### Markup Compilation—Pass 2 -Not all [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] pages are compiled at during pass 1 of markup compilation. [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] files that have locally defined type references (references to types defined in code elsewhere in the same project) are exempt from compilation at this time. This is because those locally defined types exist only in source and have not yet been compiled. In order to determine this, the parser uses heuristics that involve looking for items such as `x:Name` in the markup file. When such an instance is found, that markup file’s compilation is postponed until the code files have been compiled, after which, the second markup compilation pass processes these files. +Not all XAML pages are compiled at during pass 1 of markup compilation. XAML files that have locally defined type references (references to types defined in code elsewhere in the same project) are exempt from compilation at this time. This is because those locally defined types exist only in source and have not yet been compiled. In order to determine this, the parser uses heuristics that involve looking for items such as `x:Name` in the markup file. When such an instance is found, that markup file’s compilation is postponed until the code files have been compiled, after which, the second markup compilation pass processes these files. ### File Classification -The build process puts output files into different resource groups based on which application assembly they will be placed in. In a typical nonlocalized application, all data files marked as `Resource` are placed in the main assembly (executable or library). When `UICulture` is set in the project, all compiled [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] files and those resources specifically marked as language-specific are placed in the satellite resource assembly. Furthermore, all language-neutral resources are placed in the main assembly. In this step of the build process, that determination is made. +The build process puts output files into different resource groups based on which application assembly they will be placed in. In a typical nonlocalized application, all data files marked as `Resource` are placed in the main assembly (executable or library). When `UICulture` is set in the project, all compiled XAML files and those resources specifically marked as language-specific are placed in the satellite resource assembly. Furthermore, all language-neutral resources are placed in the main assembly. In this step of the build process, that determination is made. The `ApplicationDefinition`, `Page`, and `Resource` build actions in the project file can be augmented with the `Localizable` metadata (acceptable values are `true` and `false`), which dictates whether the file is language-specific or language-neutral. @@ -123,7 +123,7 @@ The `ApplicationDefinition`, `Page`, and `Resource` build actions in the project ### Core Compilation -The core compile step involves compilation of code files. This is orchestrated by logic in the language-specific targets files Microsoft.CSharp.targets and Microsoft.VisualBasic.targets. If heuristics have determined that a single pass of the markup compiler is sufficient, then the main assembly is generated. However, if one or more [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] files in the project have references to locally defined types, then a temporary .dll file is generated so the final application assemblies may be created after the second pass of markup compilation is complete. +The core compile step involves compilation of code files. This is orchestrated by logic in the language-specific targets files Microsoft.CSharp.targets and Microsoft.VisualBasic.targets. If heuristics have determined that a single pass of the markup compiler is sufficient, then the main assembly is generated. However, if one or more XAML files in the project have references to locally defined types, then a temporary .dll file is generated so the final application assemblies may be created after the second pass of markup compilation is complete. @@ -147,29 +147,29 @@ The WPF build system provides support for incremental builds. It is fairly intel - An $(*AssemblyName*)_MarkupCompiler.Cache file to maintain current compiler state. -- An $(*AssemblyName*)_MarkupCompiler.lref file to cache the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] files with references to locally defined types. +- An $(*AssemblyName*)_MarkupCompiler.lref file to cache the XAML files with references to locally defined types. The following is a set of rules governing incremental build: - The file is the smallest unit at which the build system detects change. So, for a code file, the build system cannot tell if a type was changed or if code was added. The same holds for project files. -- The incremental build mechanism must be cognizant that a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] page either defines a class or uses other classes. +- The incremental build mechanism must be cognizant that a XAML page either defines a class or uses other classes. - If `Reference` entries change, then recompile all pages. - If a code file changes, recompile all pages with locally defined type references. -- If a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file changes: +- If a XAML file changes: - - If [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] is declared as `Page` in the project: if the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] does not have locally defined type references, recompile that [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] plus all [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] pages with local references; if the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] has local references, recompile all [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] pages with local references. + - If XAML is declared as `Page` in the project: if the XAML does not have locally defined type references, recompile that XAML plus all XAML pages with local references; if the XAML has local references, recompile all XAML pages with local references. - - If [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] is declared as `ApplicationDefinition` in the project: recompile all [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] pages (reason: each [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] has reference to an type that may have changed). + - If XAML is declared as `ApplicationDefinition` in the project: recompile all XAML pages (reason: each XAML has reference to an type that may have changed). -- If the project file declares a code file as application definition instead of a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file: +- If the project file declares a code file as application definition instead of a XAML file: - Check if the `ApplicationClassName` value in the project file has changed (is there a new application type?). If so, recompile the entire application. - - Otherwise, recompile all [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] pages with local references. + - Otherwise, recompile all XAML pages with local references. - If a project file changes: apply all preceding rules and see what needs to be recompiled. Changes to the following properties trigger a complete recompile: `AssemblyName`, `IntermediateOutputPath`, `RootNamespace`, and `HostInBrowser`. @@ -177,7 +177,7 @@ The following recompile scenarios are possible: - The entire application is recompiled. -- Only those [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] files that have locally defined type references are recompiled. +- Only those XAML files that have locally defined type references are recompiled. - Nothing is recompiled (if nothing in the project has changed). diff --git a/dotnet-desktop-guide/framework/wpf/app-development/deploying-a-wpf-application-wpf.md b/dotnet-desktop-guide/framework/wpf/app-development/deploying-a-wpf-application-wpf.md index 17e87ea..ff12a0a 100644 --- a/dotnet-desktop-guide/framework/wpf/app-development/deploying-a-wpf-application-wpf.md +++ b/dotnet-desktop-guide/framework/wpf/app-development/deploying-a-wpf-application-wpf.md @@ -74,7 +74,7 @@ After Windows Presentation Foundation (WPF) applications are built, they need to - Standalone applications. -- Markup-only [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] applications. +- Markup-only XAML applications. - XAML browser applications (XBAPs). @@ -88,11 +88,11 @@ After Windows Presentation Foundation (WPF) applications are built, they need to ### Deploying Markup-Only XAML Applications - Markup-only [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] pages are usually published to Web servers, like HTML pages, and can be viewed using Internet Explorer. Markup-only [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] pages run within a partial-trust security sandbox with restrictions that are defined by the Internet zone permission set. This provides an equivalent security sandbox to HTML-based Web applications. + Markup-only XAML pages are usually published to Web servers, like HTML pages, and can be viewed using Internet Explorer. Markup-only XAML pages run within a partial-trust security sandbox with restrictions that are defined by the Internet zone permission set. This provides an equivalent security sandbox to HTML-based Web applications. For more information about security for WPF applications, see [Security](../security-wpf.md). - Markup-only [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] pages can be installed to the local file system by using either XCopy or Windows Installer. These pages can be viewed using Internet Explorer or Windows Explorer. + Markup-only XAML pages can be installed to the local file system by using either XCopy or Windows Installer. These pages can be viewed using Internet Explorer or Windows Explorer. For more information about XAML, see [XAML in WPF](../advanced/xaml-in-wpf.md). @@ -111,7 +111,7 @@ After Windows Presentation Foundation (WPF) applications are built, they need to > [!NOTE] > For more information about deployment and application manifests, see [Building a WPF Application](building-a-wpf-application-wpf.md). - These files are produced when an XBAP is built. For more information, see [How to: Create a New WPF Browser Application Project](/previous-versions/visualstudio/visual-studio-2010/bb628663(v=vs.100)). Like markup-only [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] pages, XBAPs are typically published to a Web server and viewed using Internet Explorer. + These files are produced when an XBAP is built. For more information, see [How to: Create a New WPF Browser Application Project](/previous-versions/visualstudio/visual-studio-2010/bb628663(v=vs.100)). Like markup-only XAML pages, XBAPs are typically published to a Web server and viewed using Internet Explorer. XBAPs can be deployed to clients using any of the deployment techniques. However, ClickOnce is recommended since it provides the following capabilities: diff --git a/dotnet-desktop-guide/framework/wpf/app-development/dialog-boxes-overview.md b/dotnet-desktop-guide/framework/wpf/app-development/dialog-boxes-overview.md index 6ca633a..72075bc 100644 --- a/dotnet-desktop-guide/framework/wpf/app-development/dialog-boxes-overview.md +++ b/dotnet-desktop-guide/framework/wpf/app-development/dialog-boxes-overview.md @@ -13,7 +13,7 @@ helpviewer_keywords: ms.assetid: 0d23d544-a393-4a02-a3aa-d8cd5d3d6511 --- # Dialog boxes overview -Standalone applications typically have a main window that both displays the main data over which the application operates and exposes the functionality to process that data through [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] mechanisms like menu bars, tool bars, and status bars. A non-trivial application may also display additional windows to do the following: +Standalone applications typically have a main window that both displays the main data over which the application operates and exposes the functionality to process that data through user interface (UI) mechanisms like menu bars, tool bars, and status bars. A non-trivial application may also display additional windows to do the following: - Display specific information to users. diff --git a/dotnet-desktop-guide/framework/wpf/app-development/firefox-add-ons-to-support-net-application-deployment.md b/dotnet-desktop-guide/framework/wpf/app-development/firefox-add-ons-to-support-net-application-deployment.md index e8f71c0..f268ebd 100644 --- a/dotnet-desktop-guide/framework/wpf/app-development/firefox-add-ons-to-support-net-application-deployment.md +++ b/dotnet-desktop-guide/framework/wpf/app-development/firefox-add-ons-to-support-net-application-deployment.md @@ -9,10 +9,10 @@ helpviewer_keywords: ms.assetid: 2403403b-9b14-48e9-b70d-fa288a3c9081 --- # Firefox Add-ons to Support .NET Application Deployment -The Windows Presentation Foundation (WPF) plug-in for Firefox and the .NET Framework Assistant for Firefox enable XAML browser applications (XBAPs), loose [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], and ClickOnce applications to work with the Mozilla Firefox browser. +The Windows Presentation Foundation (WPF) plug-in for Firefox and the .NET Framework Assistant for Firefox enable XAML browser applications (XBAPs), loose XAML, and ClickOnce applications to work with the Mozilla Firefox browser. ## WPF Plug-in for Firefox - The WPF plug-in for Firefox enables XBAPs and loose [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] files to be navigated to and run at the top-level or in an HTML IFRAME in the Firefox browser. An XBAP is a WPF application that can be published to a Web server and launched within supported browsers. Loose [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] is a XAML-only file that can be navigated to and displayed in supported browsers, much like an XML file. + The WPF plug-in for Firefox enables XBAPs and loose XAML files to be navigated to and run at the top-level or in an HTML IFRAME in the Firefox browser. An XBAP is a WPF application that can be published to a Web server and launched within supported browsers. Loose XAML is a XAML-only file that can be navigated to and displayed in supported browsers, much like an XML file. The WPF plug-in for Firefox is installed with the .NET Framework 3.5. Window 7 includes the .NET Framework 3.5, but does not include the WPF plug-in for Firefox. You cannot install the WPF plug-in for Firefox on Windows 7. diff --git a/dotnet-desktop-guide/framework/wpf/app-development/how-to-call-a-page-function.md b/dotnet-desktop-guide/framework/wpf/app-development/how-to-call-a-page-function.md index 6977199..29f251d 100644 --- a/dotnet-desktop-guide/framework/wpf/app-development/how-to-call-a-page-function.md +++ b/dotnet-desktop-guide/framework/wpf/app-development/how-to-call-a-page-function.md @@ -11,7 +11,7 @@ helpviewer_keywords: ms.assetid: a4808397-c6d5-406a-83e0-0091f0c15ae4 --- # How to: Call a Page Function -This example shows how to call a page function from a [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] page. +This example shows how to call a page function from a Extensible Application Markup Language (XAML) page. ## Example You can navigate to a page function using a uniform resource identifier (URI), just as you can when you navigate to a page. This is shown in the following example. diff --git a/dotnet-desktop-guide/framework/wpf/app-development/how-to-configure-iis-5-0-and-iis-6-0-to-deploy-wpf-applications.md b/dotnet-desktop-guide/framework/wpf/app-development/how-to-configure-iis-5-0-and-iis-6-0-to-deploy-wpf-applications.md index e772cee..6e8bd14 100644 --- a/dotnet-desktop-guide/framework/wpf/app-development/how-to-configure-iis-5-0-and-iis-6-0-to-deploy-wpf-applications.md +++ b/dotnet-desktop-guide/framework/wpf/app-development/how-to-configure-iis-5-0-and-iis-6-0-to-deploy-wpf-applications.md @@ -18,9 +18,9 @@ ms.assetid: c6e8c2cb-9ba2-4e75-a0d5-180ec9639433 # How to: Configure IIS 5.0 and IIS 6.0 to Deploy WPF Applications -You can deploy a [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] application from most Web servers, as long as they are configured with the appropriate Multipurpose Internet Mail Extensions (MIME) types. By default, Microsoft Internet Information Services (IIS) 7.0 is configured with these MIME types, but Microsoft Internet Information Services (IIS) 5.0 and Microsoft Internet Information Services (IIS) 6.0 are not. +You can deploy a Windows Presentation Foundation (WPF) application from most Web servers, as long as they are configured with the appropriate Multipurpose Internet Mail Extensions (MIME) types. By default, Microsoft Internet Information Services (IIS) 7.0 is configured with these MIME types, but Microsoft Internet Information Services (IIS) 5.0 and Microsoft Internet Information Services (IIS) 6.0 are not. -This topic describes how to configure Microsoft Internet Information Services (IIS) 5.0 and Microsoft Internet Information Services (IIS) 6.0 to deploy [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications. +This topic describes how to configure Microsoft Internet Information Services (IIS) 5.0 and Microsoft Internet Information Services (IIS) 6.0 to deploy WPF applications. > [!NOTE] > You can check the *UserAgent* string in the registry to determine whether a system has .NET Framework installed. For details and a script that examines the *UserAgent* string to determine whether .NET Framework is installed on a system, see [Detect Whether the .NET Framework 3.0 Is Installed](how-to-detect-whether-the-net-framework-3-0-is-installed.md). diff --git a/dotnet-desktop-guide/framework/wpf/app-development/index.md b/dotnet-desktop-guide/framework/wpf/app-development/index.md index e0c8b53..120eaf3 100644 --- a/dotnet-desktop-guide/framework/wpf/app-development/index.md +++ b/dotnet-desktop-guide/framework/wpf/app-development/index.md @@ -34,7 +34,7 @@ Windows Presentation Foundation (WPF) is a presentation framework that can be us - Retrieving and processing command-line parameters. -- Sharing application-scope properties and [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] resources. +- Sharing application-scope properties and UI resources. - Detecting and processing unhandled exceptions. diff --git a/dotnet-desktop-guide/framework/wpf/app-development/iwpfhostsupport.md b/dotnet-desktop-guide/framework/wpf/app-development/iwpfhostsupport.md index 7f55edf..853e691 100644 --- a/dotnet-desktop-guide/framework/wpf/app-development/iwpfhostsupport.md +++ b/dotnet-desktop-guide/framework/wpf/app-development/iwpfhostsupport.md @@ -7,7 +7,7 @@ ms.assetid: cc5a0281-de81-4cc1-87e4-0e46b1a811e9 --- # IWpfHostSupport -Applications that host [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] content via PresentationHost.exe implement this interface to provide a point of integration between the host and PresentationHost.exe. +Applications that host Windows Presentation Foundation (WPF) content via PresentationHost.exe implement this interface to provide a point of integration between the host and PresentationHost.exe. ## Remarks diff --git a/dotnet-desktop-guide/framework/wpf/app-development/navigation-how-to-topics.md b/dotnet-desktop-guide/framework/wpf/app-development/navigation-how-to-topics.md index 7b8d326..bc971c8 100644 --- a/dotnet-desktop-guide/framework/wpf/app-development/navigation-how-to-topics.md +++ b/dotnet-desktop-guide/framework/wpf/app-development/navigation-how-to-topics.md @@ -8,7 +8,7 @@ helpviewer_keywords: ms.assetid: f804648e-558c-4f60-8e48-d11f4a23c436 --- # Navigation How-to Topics -The following topics show how to use [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] navigation. +The following topics show how to use Windows Presentation Foundation (WPF) navigation. ## In This Section [Call a Page Function](how-to-call-a-page-function.md) diff --git a/dotnet-desktop-guide/framework/wpf/app-development/navigation-overview.md b/dotnet-desktop-guide/framework/wpf/app-development/navigation-overview.md index 1fa2743..29645cc 100644 --- a/dotnet-desktop-guide/framework/wpf/app-development/navigation-overview.md +++ b/dotnet-desktop-guide/framework/wpf/app-development/navigation-overview.md @@ -31,7 +31,7 @@ ms.assetid: 86ad2143-606a-4e34-bf7e-51a2594248b8 Windows Presentation Foundation (WPF) supports browser-style navigation that can be used in two types of applications: standalone applications and XAML browser applications (XBAPs). To package content for navigation, WPF provides the class. You can navigate from one to another declaratively, by using a , or programmatically, by using the . WPF uses the journal to remember pages that have been navigated from and to navigate back to them. -, , , and the journal form the core of the navigation support offered by WPF. This overview explores these features in detail before covering advanced navigation support that includes navigation to loose [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] files, HTML files, and objects. +, , , and the journal form the core of the navigation support offered by WPF. This overview explores these features in detail before covering advanced navigation support that includes navigation to loose Extensible Application Markup Language (XAML) files, HTML files, and objects. > [!NOTE] > In this topic, the term "browser" refers only to browsers that can host WPF applications, which currently includes Microsoft Internet Explorer and Firefox. Where specific WPF features are supported only by a particular browser, the browser version is referred to. @@ -75,13 +75,13 @@ This section explains and demonstrates the following aspects of navigation: ### Implementing a Page -In WPF, you can navigate to several content types that include .NET Framework objects, custom objects, enumeration values, user controls, [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] files, and HTML files. However, you'll find that the most common and convenient way to package content is by using . Furthermore, implements navigation-specific features to enhance their appearance and simplify development. +In WPF, you can navigate to several content types that include .NET Framework objects, custom objects, enumeration values, user controls, XAML files, and HTML files. However, you'll find that the most common and convenient way to package content is by using . Furthermore, implements navigation-specific features to enhance their appearance and simplify development. -Using , you can declaratively implement a navigable page of [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] content by using markup like the following. +Using , you can declaratively implement a navigable page of XAML content by using markup like the following. [!code-xaml[NavigationOverviewSnippets#Page1XAML](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/Page1.xaml#page1xaml)] -A that is implemented in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] markup has `Page` as its root element and requires the WPF XML namespace declaration. The `Page` element contains the content that you want to navigate to and display. You add content by setting the `Page.Content` property element, as shown in the following markup. +A that is implemented in XAML markup has `Page` as its root element and requires the WPF XML namespace declaration. The `Page` element contains the content that you want to navigate to and display. You add content by setting the `Page.Content` property element, as shown in the following markup. [!code-xaml[NavigationOverviewSnippets#Page2XAML](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/Page2.xaml#page2xaml)] @@ -102,7 +102,7 @@ A markup-only is useful for displaying conte To allow a markup file and code-behind file to work together, the following configuration is required: -- In markup, the `Page` element must include the `x:Class` attribute. When the application is built, the existence of `x:Class` in the markup file causes Microsoft build engine (MSBuild) to create a `partial` class that derives from and has the name that is specified by the `x:Class` attribute. This requires the addition of an XML namespace declaration for the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] schema ( `xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"` ). The generated `partial` class implements `InitializeComponent`, which is called to register the events and set the properties that are implemented in markup. +- In markup, the `Page` element must include the `x:Class` attribute. When the application is built, the existence of `x:Class` in the markup file causes Microsoft build engine (MSBuild) to create a `partial` class that derives from and has the name that is specified by the `x:Class` attribute. This requires the addition of an XML namespace declaration for the XAML schema ( `xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"` ). The generated `partial` class implements `InitializeComponent`, which is called to register the events and set the properties that are implemented in markup. - In code-behind, the class must be a `partial` class with the same name that is specified by the `x:Class` attribute in markup, and it must derive from . This allows the code-behind file to be associated with the `partial` class that is generated for the markup file when the application is built (see [Building a WPF Application](building-a-wpf-application-wpf.md)). @@ -214,9 +214,9 @@ The following shows an example of a `Hyperlink` that is configured to navigate t > This section describes the default fragment navigation implementation in WPF. WPF also allows you to implement your own fragment navigation scheme which, in part, requires handling the event. > [!IMPORTANT] -> You can navigate to fragments in loose [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] pages (markup-only [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] files with `Page` as the root element) only if the pages can be browsed via HTTP. +> You can navigate to fragments in loose XAML pages (markup-only XAML files with `Page` as the root element) only if the pages can be browsed via HTTP. > -> However, a loose [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] page can navigate to its own fragments. +> However, a loose XAML page can navigate to its own fragments. @@ -367,7 +367,7 @@ Conceptually, the journal operates the same way that the **Back** and **Forward* ![Back and Forward buttons](./media/navigation-overview/back-and-forward-navigation.png "Navigate with the back and forward buttons.") -For XBAPs that are hosted by Internet Explorer, WPF integrates the journal into the navigation [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] of Internet Explorer. This allows users to navigate pages in an XBAP by using the **Back**, **Forward**, and **Recent Pages** buttons in Internet Explorer. +For XBAPs that are hosted by Internet Explorer, WPF integrates the journal into the navigation UI of Internet Explorer. This allows users to navigate pages in an XBAP by using the **Back**, **Forward**, and **Recent Pages** buttons in Internet Explorer. > [!IMPORTANT] > In Internet Explorer, when a user navigates away from and back to an XBAP, only the journal entries for pages that were not kept alive are retained in the journal. For discussion on keeping pages alive, see [Page Lifetime and the Journal](#PageLifetime) later in this topic. @@ -537,7 +537,7 @@ The following are some of the ways that cookies are supported in WPF: - XBAPs and HTML pages from the same domain can create and share cookies. -- Cookies are dispatched when XBAPs and loose [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] pages make Web requests. +- Cookies are dispatched when XBAPs and loose XAML pages make Web requests. - Both top-level XBAPs and XBAPs hosted in IFRAMES can access cookies. @@ -608,7 +608,7 @@ As you can see, displays Inter If your pages provide their own journal navigation support and UI, you can hide the **Back** and **Forward** buttons displayed by by setting the value of the property to `false`. -Alternatively, you can use customization support in WPF to replace the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] of the itself. +Alternatively, you can use customization support in WPF to replace the UI of the itself. @@ -642,12 +642,12 @@ The following figure illustrates the effect of navigating within a , rather than by Internet Explorer. +Notice that the journal entries are shown by the navigation UI in the , rather than by Internet Explorer. > [!NOTE] -> If a is part of content that is hosted in a , uses its own journal and, consequently, displays its own navigation [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)]. +> If a is part of content that is hosted in a , uses its own journal and, consequently, displays its own navigation UI. -If your user experience requires a to provide its own journal without showing the navigation [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)], you can hide the navigation [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] by setting the to . This is shown in the following markup. +If your user experience requires a to provide its own journal without showing the navigation UI, you can hide the navigation UI by setting the to . This is shown in the following markup. [!code-xaml[NavigationOverviewSnippets#FrameHostPageHidesUIXAML1](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/FrameHostPageOwnHiddenJournal.xaml#framehostpagehidesuixaml1)] [!code-xaml[NavigationOverviewSnippets#FrameHostPageHidesUIXAML2](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/FrameHostPageOwnHiddenJournal.xaml#framehostpagehidesuixaml2)] @@ -667,7 +667,7 @@ Besides using and a journal, ![A journal in a Frame and in a NavigationWindow](./media/navigation-overview/navigation-window-and-frame.png "Navigation Window and Frame") -This allows you to program navigation support directly against them. You may consider this if you need to provide a custom navigation [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] for a that is hosted in a . Furthermore, both types implement additional, navigation-related members, including `BackStack` (, ) and `ForwardStack` (, ), which allow you to enumerate the journal entries in the back stack and forward stack, respectively. +This allows you to program navigation support directly against them. You may consider this if you need to provide a custom navigation UI for a that is hosted in a . Furthermore, both types implement additional, navigation-related members, including `BackStack` (, ) and `ForwardStack` (, ), which allow you to enumerate the journal entries in the back stack and forward stack, respectively. As mentioned earlier, more than one journal can exist within an application. The following figure provides an example of when this can happen. @@ -679,21 +679,21 @@ As mentioned earlier, more than one journal can exist within an application. The Throughout this topic, and pack XBAPs have been used to demonstrate the various navigation capabilities of WPF. However, a that is compiled into an application is not the only type of content that can be navigated to, and pack XBAPs aren't the only way to identify content. -As this section demonstrates, you can also navigate to loose [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] files, HTML files, and objects. +As this section demonstrates, you can also navigate to loose XAML files, HTML files, and objects. ### Navigating to Loose XAML Files -A loose [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file is a file with the following characteristics: +A loose XAML file is a file with the following characteristics: -- Contains only [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] (that is, no code). +- Contains only XAML (that is, no code). - Has an appropriate namespace declaration. - Has the .xaml file name extension. -For example, consider the following content that is stored as a loose [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file, Person.xaml. +For example, consider the following content that is stored as a loose XAML file, Person.xaml. [!code-xaml[NavigationOverviewSnippets#LooseXAML](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/Person.xaml#loosexaml)] @@ -701,7 +701,7 @@ When you double-click the file, the browser opens and navigates to and displays ![Display of the content in the Person.XAML file](./media/navigation-overview/contents-of-person-xaml-file.png "Shows the contents of the Person.XAML file.") -You can display a loose [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file from the following: +You can display a loose XAML file from the following: - A Web site on the local machine, the intranet, or the Internet. @@ -709,18 +709,18 @@ You can display a loose [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla- - The local disk. -A loose [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file can be added to the browser's favorites, or be the browser's home page. +A loose XAML file can be added to the browser's favorites, or be the browser's home page. > [!NOTE] -> For more information about publishing and launching loose [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] pages, see [Deploying a WPF Application](deploying-a-wpf-application-wpf.md). +> For more information about publishing and launching loose XAML pages, see [Deploying a WPF Application](deploying-a-wpf-application-wpf.md). -One limitation with respect to loose [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] is that you can only host content that is safe to run in partial trust. For example, `Window` cannot be the root element of a loose [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file. For more information, see [WPF Partial Trust Security](../wpf-partial-trust-security.md). +One limitation with respect to loose XAML is that you can only host content that is safe to run in partial trust. For example, `Window` cannot be the root element of a loose XAML file. For more information, see [WPF Partial Trust Security](../wpf-partial-trust-security.md). ### Navigating to HTML Files by Using Frame -As you might expect, you can also navigate to HTML. You simply need to provide a URI that uses the http scheme. For example, the following [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] shows a that navigates to an HTML page. +As you might expect, you can also navigate to HTML. You simply need to provide a URI that uses the http scheme. For example, the following XAML shows a that navigates to an HTML page. [!code-xaml[NavigationOverviewSnippets#FrameHtmlNavMARKUP](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/FrameHTMLNavPage.xaml#framehtmlnavmarkup)] diff --git a/dotnet-desktop-guide/framework/wpf/app-development/navigation-topologies-overview.md b/dotnet-desktop-guide/framework/wpf/app-development/navigation-topologies-overview.md index 004ba21..957df87 100644 --- a/dotnet-desktop-guide/framework/wpf/app-development/navigation-topologies-overview.md +++ b/dotnet-desktop-guide/framework/wpf/app-development/navigation-topologies-overview.md @@ -38,7 +38,7 @@ ms.assetid: 5d5ee837-629a-4933-869a-186dc22ac43d These pages are arranged in a *navigation topology* whose structure is determined by how you can navigate between the pages. This particular navigation topology is suitable in simple scenarios, although navigation can require more complex topologies, some of which can only be defined when an application is running. - This topic covers three common navigation topologies: *fixed linear*, *fixed hierarchical*, and *dynamically generated*. Each navigation topology is demonstrated with a sample that has a [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] like the one that is shown in the following figure: + This topic covers three common navigation topologies: *fixed linear*, *fixed hierarchical*, and *dynamically generated*. Each navigation topology is demonstrated with a sample that has a UI like the one that is shown in the following figure: ![Task pages with data items and navigation buttons.](./media/navigation-topologies-overview/navigation-topology-data-items.png) @@ -60,7 +60,7 @@ ms.assetid: 5d5ee837-629a-4933-869a-186dc22ac43d The typical behaviors for navigating over a fixed linear topology include the following: -- Navigating from the calling page to a launcher page that initializes the wizard and navigates to the first wizard page. A launcher page (a [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)]-less ) is not required, since a calling page can call the first wizard page directly. Using a launcher page, however, can simplify wizard initialization, particularly if initialization is complex. +- Navigating from the calling page to a launcher page that initializes the wizard and navigates to the first wizard page. A launcher page (a UI-less ) is not required, since a calling page can call the first wizard page directly. Using a launcher page, however, can simplify wizard initialization, particularly if initialization is complex. - Users can navigate between pages by using Back and Forward buttons (or hyperlinks). @@ -88,7 +88,7 @@ ms.assetid: 5d5ee837-629a-4933-869a-186dc22ac43d Even though the sequence in which pages in a fixed hierarchical structure are navigated is determined at run time, the user experience is the same as the user experience for a fixed linear topology: -- Navigating from the calling page to a launcher page that initializes the wizard and navigates to the first wizard page. A launcher page (a [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)]-less ) is not required, since a calling page can call the first wizard page directly. Using a launcher page, however, can simplify wizard initialization, particularly if initialization is complex. +- Navigating from the calling page to a launcher page that initializes the wizard and navigates to the first wizard page. A launcher page (a UI-less ) is not required, since a calling page can call the first wizard page directly. Using a launcher page, however, can simplify wizard initialization, particularly if initialization is complex. - Users can navigate between pages by using Back and Forward buttons (or hyperlinks). @@ -118,7 +118,7 @@ ms.assetid: 5d5ee837-629a-4933-869a-186dc22ac43d The navigation sequence is known as a dynamically generated topology. For the user, as with the other navigation topologies, the user experience is the same as it is for the previous topologies: -- Navigating from the calling page to a launcher page that initializes the wizard and navigates to the first wizard page. A launcher page (a [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)]-less ) is not required, since a calling page can call the first wizard page directly. Using a launcher page, however, can simplify wizard initialization, particularly if initialization is complex. +- Navigating from the calling page to a launcher page that initializes the wizard and navigates to the first wizard page. A launcher page (a UI-less ) is not required, since a calling page can call the first wizard page directly. Using a launcher page, however, can simplify wizard initialization, particularly if initialization is complex. - Users can navigate between pages by using Back and Forward buttons (or hyperlinks). diff --git a/dotnet-desktop-guide/framework/wpf/app-development/pack-uris-in-wpf.md b/dotnet-desktop-guide/framework/wpf/app-development/pack-uris-in-wpf.md index 7f63e15..c9b61f8 100644 --- a/dotnet-desktop-guide/framework/wpf/app-development/pack-uris-in-wpf.md +++ b/dotnet-desktop-guide/framework/wpf/app-development/pack-uris-in-wpf.md @@ -15,7 +15,7 @@ ms.assetid: 43adb517-21a7-4df3-98e8-09e9cdf764c4 In Windows Presentation Foundation (WPF), uniform resource identifiers (URIs) are used to identify and load files in many ways, including the following: -- Specifying the [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] to show when an application first starts. +- Specifying the user interface (UI) to show when an application first starts. - Loading images. @@ -92,11 +92,11 @@ The pack URI for a resource file that is compiled into the local assembly uses t - **Path**: The name of the resource file, including its path, relative to the local assembly project folder root. -The following example shows the pack URI for a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] resource file that is located in the root of the local assembly's project folder. +The following example shows the pack URI for a XAML resource file that is located in the root of the local assembly's project folder. `pack://application:,,,/ResourceFile.xaml` -The following example shows the pack URI for a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] resource file that is located in a subfolder of the local assembly's project folder. +The following example shows the pack URI for a XAML resource file that is located in a subfolder of the local assembly's project folder. `pack://application:,,,/Subfolder/ResourceFile.xaml` @@ -122,15 +122,15 @@ The pack URI for a resource file that is compiled into a referenced assembly use - **/Path**: the name of the resource file, including its path, relative to the root of the referenced assembly's project folder. -The following example shows the pack URI for a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] resource file that is located in the root of the referenced assembly's project folder. +The following example shows the pack URI for a XAML resource file that is located in the root of the referenced assembly's project folder. `pack://application:,,,/ReferencedAssembly;component/ResourceFile.xaml` -The following example shows the pack URI for a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] resource file that is located in a subfolder of the referenced assembly's project folder. +The following example shows the pack URI for a XAML resource file that is located in a subfolder of the referenced assembly's project folder. `pack://application:,,,/ReferencedAssembly;component/Subfolder/ResourceFile.xaml` -The following example shows the pack URI for a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] resource file that is located in the root folder of a referenced, version-specific assembly's project folder. +The following example shows the pack URI for a XAML resource file that is located in the root folder of a referenced, version-specific assembly's project folder. `pack://application:,,,/ReferencedAssembly;v1.0.0.1;component/ResourceFile.xaml` @@ -148,11 +148,11 @@ The pack URI for a content file uses the following authority and path: - **Path**: The name of the content file, including its path relative to the file system location of the application's main executable assembly. -The following example shows the pack URI for a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] content file, located in the same folder as the executable assembly. +The following example shows the pack URI for a XAML content file, located in the same folder as the executable assembly. `pack://application:,,,/ContentFile.xaml` -The following example shows the pack URI for a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] content file, located in a subfolder that is relative to the application's executable assembly. +The following example shows the pack URI for a XAML content file, located in a subfolder that is relative to the application's executable assembly. `pack://application:,,,/Subfolder/ContentFile.xaml` @@ -169,11 +169,11 @@ The pack URI for a site of origin file uses the following authority and path: - **Path**: The name of the site of origin file, including its path relative to the location from which the executable assembly was launched. -The following example shows the pack URI for a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] site of origin file, stored in the location from which the executable assembly is launched. +The following example shows the pack URI for a XAML site of origin file, stored in the location from which the executable assembly is launched. `pack://siteoforigin:,,,/SiteOfOriginFile.xaml` -The following example shows the pack URI for a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] site of origin file, stored in subfolder that is relative to the location from which the application's executable assembly is launched. +The following example shows the pack URI for a XAML site of origin file, stored in subfolder that is relative to the location from which the application's executable assembly is launched. `pack://siteoforigin:,,,/Subfolder/SiteOfOriginFile.xaml` @@ -183,7 +183,7 @@ The following example shows the pack URI for a [!INCLUDE[TLA2#tla_xaml](../../.. XAML files that are configured as MSBuild `Page` items are compiled into assemblies in the same way as resource files. Consequently, MSBuild `Page` items can be identified using pack URIs for resource files. -The types of [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] files that are commonly configured as MSBuild`Page` items have one of the following as their root element: +The types of XAML files that are commonly configured as MSBuild`Page` items have one of the following as their root element: - @@ -201,7 +201,7 @@ The types of [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md) ## Absolute vs. Relative Pack URIs -A fully qualified pack URI includes the scheme, the authority, and the path, and it is considered an absolute pack URI. As a simplification for developers, [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] elements typically allow you to set appropriate attributes with a relative pack URI, which includes only the path. +A fully qualified pack URI includes the scheme, the authority, and the path, and it is considered an absolute pack URI. As a simplification for developers, XAML elements typically allow you to set appropriate attributes with a relative pack URI, which includes only the path. For example, consider the following absolute pack URI for a resource file in the local assembly. @@ -398,7 +398,7 @@ The preceding sections have discussed how to construct pack URIs to identify res #### Specifying the UI to Show When an Application Starts - specifies the first [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] to show when a WPF application is launched. For standalone applications, the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] can be a window, as shown in the following example. + specifies the first UI to show when a WPF application is launched. For standalone applications, the UI can be a window, as shown in the following example. [!code-xaml[PackURIOverviewSnippets#StartupUriWindow](~/samples/snippets/csharp/VS_Snippets_Wpf/PackURIOverviewSnippets/CS/Copy of App.xaml#startupuriwindow)] diff --git a/dotnet-desktop-guide/framework/wpf/app-development/structured-navigation-overview.md b/dotnet-desktop-guide/framework/wpf/app-development/structured-navigation-overview.md index b097bb5..6d6927a 100644 --- a/dotnet-desktop-guide/framework/wpf/app-development/structured-navigation-overview.md +++ b/dotnet-desktop-guide/framework/wpf/app-development/structured-navigation-overview.md @@ -69,7 +69,7 @@ Because the calling page can use the called page to collect and return data from [!code-csharp[StructuredNavigationSample#CalledPageFunctionCODEBEHIND2](~/samples/snippets/csharp/VS_Snippets_Wpf/StructuredNavigationSample/CSharp/CalledPageFunction.xaml.cs#calledpagefunctioncodebehind2)] [!code-vb[StructuredNavigationSample#CalledPageFunctionCODEBEHIND2](~/samples/snippets/visualbasic/VS_Snippets_Wpf/StructuredNavigationSample/VisualBasic/CalledPageFunction.xaml.vb#calledpagefunctioncodebehind2)] -The declaration of a is similar to the declaration of a with the addition of the type arguments. As you can see from the code example, the type arguments are specified in both [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] markup, using the `x:TypeArguments` attribute, and code-behind, using standard generic type argument syntax. +The declaration of a is similar to the declaration of a with the addition of the type arguments. As you can see from the code example, the type arguments are specified in both XAML markup, using the `x:TypeArguments` attribute, and code-behind, using standard generic type argument syntax. You don't have to use only .NET Framework classes as type arguments. A could be called to gather domain-specific data that is abstracted as a custom type. The following code shows how to use a custom type as a type argument for a . diff --git a/dotnet-desktop-guide/framework/wpf/app-development/window-management-how-to-topics.md b/dotnet-desktop-guide/framework/wpf/app-development/window-management-how-to-topics.md index e3b87bb..b20d53e 100644 --- a/dotnet-desktop-guide/framework/wpf/app-development/window-management-how-to-topics.md +++ b/dotnet-desktop-guide/framework/wpf/app-development/window-management-how-to-topics.md @@ -8,7 +8,7 @@ helpviewer_keywords: ms.assetid: 3090b408-94e4-446a-92ca-50f1fd36e5d8 --- # Window Management How-to Topics -The following topics show how to manage [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] windows. +The following topics show how to manage Windows Presentation Foundation (WPF) windows. ## In This Section [Automatically Size a Window to Fit Its Content](how-to-automatically-size-a-window-to-fit-its-content.md) diff --git a/dotnet-desktop-guide/framework/wpf/app-development/wpf-application-resource-content-and-data-files.md b/dotnet-desktop-guide/framework/wpf/app-development/wpf-application-resource-content-and-data-files.md index b533783..dbc441e 100644 --- a/dotnet-desktop-guide/framework/wpf/app-development/wpf-application-resource-content-and-data-files.md +++ b/dotnet-desktop-guide/framework/wpf/app-development/wpf-application-resource-content-and-data-files.md @@ -20,7 +20,7 @@ helpviewer_keywords: ms.assetid: 7ad2943b-3961-41d3-8fc6-1582d43f5d99 --- # WPF Application Resource, Content, and Data Files -Microsoft Windows applications often depend on files that contain non-executable data, such as [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)], images, video, and audio. Windows Presentation Foundation (WPF) offers special support for configuring, identifying, and using these types of data files, which are called application data files. This support revolves around a specific set of application data file types, including: +Microsoft Windows applications often depend on files that contain non-executable data, such as Extensible Application Markup Language (XAML), images, video, and audio. Windows Presentation Foundation (WPF) offers special support for configuring, identifying, and using these types of data files, which are called application data files. This support revolves around a specific set of application data file types, including: - **Resource Files**: Data files that are compiled into either an executable or library WPF assembly. @@ -106,10 +106,10 @@ Microsoft Windows applications often depend on files that contain non-executable > [!NOTE] > In Visual Studio, you add a new , , , , or to a project, the `Build Action` for the markup file will default to `Page`. - When a project with `Page` items is compiled, the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] items are converted to binary format and compiled into the associated assembly. Consequently, these files can be used in the same way as typical resource files. + When a project with `Page` items is compiled, the XAML items are converted to binary format and compiled into the associated assembly. Consequently, these files can be used in the same way as typical resource files. > [!NOTE] -> If a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file is configured as a `Resource` item, and does not have a code-behind file, the raw [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] is compiled into an assembly rather than a binary version of the raw [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]. +> If a XAML file is configured as a `Resource` item, and does not have a code-behind file, the raw XAML is compiled into an assembly rather than a binary version of the raw XAML. ## Content Files diff --git a/dotnet-desktop-guide/framework/wpf/app-development/wpf-host-presentationhost-exe.md b/dotnet-desktop-guide/framework/wpf/app-development/wpf-host-presentationhost-exe.md index c631c26..60ef92d 100644 --- a/dotnet-desktop-guide/framework/wpf/app-development/wpf-host-presentationhost-exe.md +++ b/dotnet-desktop-guide/framework/wpf/app-development/wpf-host-presentationhost-exe.md @@ -10,7 +10,7 @@ ms.assetid: 3215bfa1-722c-4ac8-a7c5-bdd02d30afbd # WPF Host (PresentationHost.exe) Windows Presentation Foundation (WPF) Host (PresentationHost.exe) is the application that enables WPF applications to be hosted in compatible browsers (including Microsoft Internet Explorer 6 and later). By default, Windows Presentation Foundation (WPF) Host is registered as the shell and MIME handler for browser-hosted WPF content, which includes: -- Loose (uncompiled) [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] files (.xaml). +- Loose (uncompiled) XAML files (.xaml). - XAML browser application (XBAP) (.xbap). diff --git a/dotnet-desktop-guide/framework/wpf/app-development/wpf-windows-overview.md b/dotnet-desktop-guide/framework/wpf/app-development/wpf-windows-overview.md index deaacde..aa46356 100644 --- a/dotnet-desktop-guide/framework/wpf/app-development/wpf-windows-overview.md +++ b/dotnet-desktop-guide/framework/wpf/app-development/wpf-windows-overview.md @@ -35,7 +35,7 @@ ms.assetid: 737d04ec-8861-46c3-8d44-fa11d3528d23 Users interact with Windows Presentation Foundation (WPF) standalone applications through windows. The primary purpose of a window is to host content that visualizes data and enables users to interact with data. Standalone WPF applications provide their own windows by using the class. This topic introduces before covering the fundamentals of creating and managing windows in standalone applications. > [!NOTE] -> Browser-hosted WPF applications, including XAML browser applications (XBAPs) and loose [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] pages, don't provide their own windows. Instead, they are hosted in windows provided by Windows Internet Explorer. See [WPF XAML Browser Applications Overview](wpf-xaml-browser-applications-overview.md). +> Browser-hosted WPF applications, including XAML browser applications (XBAPs) and loose Extensible Application Markup Language (XAML) pages, don't provide their own windows. Instead, they are hosted in windows provided by Windows Internet Explorer. See [WPF XAML Browser Applications Overview](wpf-xaml-browser-applications-overview.md). ## The Window Class @@ -73,18 +73,18 @@ Users interact with Windows Presentation Foundation (WPF) standalone application ## Implementing a Window - The implementation of a typical window comprises both appearance and behavior, where *appearance* defines how a window looks to users and *behavior* defines the way a window functions as users interact with it. In WPF, you can implement the appearance and behavior of a window using either code or [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] markup. + The implementation of a typical window comprises both appearance and behavior, where *appearance* defines how a window looks to users and *behavior* defines the way a window functions as users interact with it. In WPF, you can implement the appearance and behavior of a window using either code or XAML markup. - In general, however, the appearance of a window is implemented using [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] markup, and its behavior is implemented using code-behind, as shown in the following example. + In general, however, the appearance of a window is implemented using XAML markup, and its behavior is implemented using code-behind, as shown in the following example. [!code-xaml[WindowsOverviewSnippets#MarkupAndCodeBehindWindowMARKUP](~/samples/snippets/csharp/VS_Snippets_Wpf/WindowsOverviewSnippets/CSharp/MarkupAndCodeBehindWindow.xaml#markupandcodebehindwindowmarkup)] [!code-csharp[WindowsOverviewSnippets#MarkupAndCodeBehindWindowCODEBEHIND](~/samples/snippets/csharp/VS_Snippets_Wpf/WindowsOverviewSnippets/CSharp/MarkupAndCodeBehindWindow.xaml.cs#markupandcodebehindwindowcodebehind)] [!code-vb[WindowsOverviewSnippets#MarkupAndCodeBehindWindowCODEBEHIND](~/samples/snippets/visualbasic/VS_Snippets_Wpf/WindowsOverviewSnippets/VisualBasic/MarkupAndCodeBehindWindow.xaml.vb#markupandcodebehindwindowcodebehind)] - To enable a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] markup file and code-behind file to work together, the following are required: + To enable a XAML markup file and code-behind file to work together, the following are required: -- In markup, the `Window` element must include the `x:Class` attribute. When the application is built, the existence of `x:Class` in the markup file causes Microsoft build engine (MSBuild) to create a `partial` class that derives from and has the name that is specified by the `x:Class` attribute. This requires the addition of an XML namespace declaration for the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] schema ( `xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"` ). The generated `partial` class implements the `InitializeComponent` method, which is called to register the events and set the properties that are implemented in markup. +- In markup, the `Window` element must include the `x:Class` attribute. When the application is built, the existence of `x:Class` in the markup file causes Microsoft build engine (MSBuild) to create a `partial` class that derives from and has the name that is specified by the `x:Class` attribute. This requires the addition of an XML namespace declaration for the XAML schema ( `xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"` ). The generated `partial` class implements the `InitializeComponent` method, which is called to register the events and set the properties that are implemented in markup. - In code-behind, the class must be a `partial` class with the same name that is specified by the `x:Class` attribute in markup, and it must derive from . This allows the code-behind file to be associated with the `partial` class that is generated for the markup file when the application is built (see [Building a WPF Application](building-a-wpf-application-wpf.md)). @@ -93,7 +93,7 @@ Users interact with Windows Presentation Foundation (WPF) standalone application > [!NOTE] > When you add a new to your project by using Visual Studio, the is implemented using both markup and code-behind, and includes the necessary configuration to create the association between the markup and code-behind files as described here. - With this configuration in place, you can focus on defining the appearance of the window in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] markup and implementing its behavior in code-behind. The following example shows a window with a button, implemented in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] markup, and an event handler for the button's event, implemented in code-behind. + With this configuration in place, you can focus on defining the appearance of the window in XAML markup and implementing its behavior in code-behind. The following example shows a window with a button, implemented in XAML markup, and an event handler for the button's event, implemented in code-behind. [!code-xaml[WindowsOverviewWindowWithButtonSnippets#MarkupAndCodeBehindWindowMARKUP](~/samples/snippets/csharp/VS_Snippets_Wpf/WindowsOverviewWindowWithButtonSnippets/CSharp/MarkupAndCodeBehindWindow.xaml#markupandcodebehindwindowmarkup)] @@ -102,7 +102,7 @@ Users interact with Windows Presentation Foundation (WPF) standalone application ## Configuring a Window Definition for MSBuild - How you implement your window determines how it is configured for MSBuild. For a window that is defined using both [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] markup and code-behind: + How you implement your window determines how it is configured for MSBuild. For a window that is defined using both XAML markup and code-behind: - XAML markup files are configured as MSBuild `Page` items. @@ -408,7 +408,7 @@ Users interact with Windows Presentation Foundation (WPF) standalone application - - As with , the resize mode of a window is unlikely to change during its lifetime, which means that you'll most likely set it from [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] markup. + As with , the resize mode of a window is unlikely to change during its lifetime, which means that you'll most likely set it from XAML markup. [!code-xaml[WindowsOverviewSnippets#ResizeModeWindowMARKUP1](~/samples/snippets/csharp/VS_Snippets_Wpf/WindowsOverviewSnippets/CSharp/ResizeModeWindow.xaml#resizemodewindowmarkup1)] @@ -432,7 +432,7 @@ Users interact with Windows Presentation Foundation (WPF) standalone application ![Illustration of window border styles.](./media/wpf-windows-overview/window-border-styles.png) - You can set using either [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] markup or code; because it is unlikely to change during the lifetime of a window, you will most likely configure it using [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] markup. + You can set using either XAML markup or code; because it is unlikely to change during the lifetime of a window, you will most likely configure it using XAML markup. [!code-xaml[WindowsOverviewSnippets#WindowStyleWindowMARKUP1](~/samples/snippets/csharp/VS_Snippets_Wpf/WindowsOverviewSnippets/CSharp/WindowStyleWindow.xaml#windowstylewindowmarkup1)] diff --git a/dotnet-desktop-guide/framework/wpf/class-library-wpf.md b/dotnet-desktop-guide/framework/wpf/class-library-wpf.md index 650eb4a..4db3c30 100644 --- a/dotnet-desktop-guide/framework/wpf/class-library-wpf.md +++ b/dotnet-desktop-guide/framework/wpf/class-library-wpf.md @@ -7,7 +7,7 @@ helpviewer_keywords: ms.assetid: dcb35927-00ad-4141-a1ab-a7a524dd3f10 --- # Class Library (WPF) -The following links refer to namespaces that contain [!INCLUDE[TLA#tla_winclient](../../includes/tlasharptla-winclient-md.md)] APIs. +The following links refer to namespaces that contain Windows Presentation Foundation (WPF) APIs. ## In This Section diff --git a/dotnet-desktop-guide/framework/wpf/controls/adorners-how-to-topics.md b/dotnet-desktop-guide/framework/wpf/controls/adorners-how-to-topics.md index 723ce8e..97e1f78 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/adorners-how-to-topics.md +++ b/dotnet-desktop-guide/framework/wpf/controls/adorners-how-to-topics.md @@ -8,7 +8,7 @@ helpviewer_keywords: ms.assetid: e29d7516-d5e6-4500-bd4f-775e6f830984 --- # Adorners How-to Topics -The following examples demonstrate how to accomplish common tasks using the [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] adorner framework. +The following examples demonstrate how to accomplish common tasks using the Windows Presentation Foundation (WPF) adorner framework. ## In This Section [Implement an Adorner](how-to-implement-an-adorner.md) diff --git a/dotnet-desktop-guide/framework/wpf/controls/adorners-overview.md b/dotnet-desktop-guide/framework/wpf/controls/adorners-overview.md index 1af4857..c12c9f6 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/adorners-overview.md +++ b/dotnet-desktop-guide/framework/wpf/controls/adorners-overview.md @@ -26,7 +26,7 @@ Common applications for adorners include: - Overlay visual decorations on a . - Visually mask or override part or all of a . -[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides a basic framework for adorning visual elements. The following table lists the primary types used when adorning objects, and their purpose. Several usage examples follow: +Windows Presentation Foundation (WPF) provides a basic framework for adorning visual elements. The following table lists the primary types used when adorning objects, and their purpose. Several usage examples follow: | Class | Description | |------|-------------| @@ -36,7 +36,7 @@ Common applications for adorners include: ## Implementing a Custom Adorner -The adorners framework provided by [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] is intended primarily to support the creation of custom adorners. A custom adorner is created by implementing a class that inherits from the abstract class. +The adorners framework provided by Windows Presentation Foundation (WPF) is intended primarily to support the creation of custom adorners. A custom adorner is created by implementing a class that inherits from the abstract class. > [!NOTE] > The parent of an is the that renders the , not the element being adorned. @@ -77,7 +77,7 @@ To bind an adorner to a particular , follow these [!code-vb[Adorners_SimpleCircleAdorner#_AdornSingleElement](~/samples/snippets/visualbasic/VS_Snippets_Wpf/Adorners_SimpleCircleAdorner/VisualBasic/Window1.xaml.vb#_adornsingleelement)] > [!NOTE] -> Using [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] to bind an adorner to another element is currently not supported. +> Using Extensible Application Markup Language (XAML) to bind an adorner to another element is currently not supported. ## Adorning the Children of a Panel diff --git a/dotnet-desktop-guide/framework/wpf/controls/adorners.md b/dotnet-desktop-guide/framework/wpf/controls/adorners.md index 8e84e29..85601d7 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/adorners.md +++ b/dotnet-desktop-guide/framework/wpf/controls/adorners.md @@ -8,7 +8,7 @@ helpviewer_keywords: ms.assetid: 5d5f656b-8e05-4839-9d53-b0324d902aa9 --- # Adorners -This section provides information about Adorners and the [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] Adorner framework. +This section provides information about Adorners and the Windows Presentation Foundation (WPF) Adorner framework. ## In This Section [Adorners Overview](adorners-overview.md) diff --git a/dotnet-desktop-guide/framework/wpf/controls/button.md b/dotnet-desktop-guide/framework/wpf/controls/button.md index e6221df..a463829 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/button.md +++ b/dotnet-desktop-guide/framework/wpf/controls/button.md @@ -9,7 +9,7 @@ helpviewer_keywords: ms.assetid: a9d8f5a5-c98c-463e-808a-5a4e63173098 --- # Button -A control reacts to user input from a mouse, keyboard, stylus, or other input device and raises a event. A is a basic [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] component that can contain simple content, such as text, and can also contain complex content, such as images and controls. +A control reacts to user input from a mouse, keyboard, stylus, or other input device and raises a event. A is a basic user interface (UI) component that can contain simple content, such as text, and can also contain complex content, such as images and controls. ![Button states](./media/ss-ctl-buttons.png "SS_CTL_buttons") diff --git a/dotnet-desktop-guide/framework/wpf/controls/change-selection-in-a-richtextbox-programmatically.md b/dotnet-desktop-guide/framework/wpf/controls/change-selection-in-a-richtextbox-programmatically.md index cc31b1e..78cfb87 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/change-selection-in-a-richtextbox-programmatically.md +++ b/dotnet-desktop-guide/framework/wpf/controls/change-selection-in-a-richtextbox-programmatically.md @@ -15,7 +15,7 @@ ms.assetid: f1213205-1ad7-4cd2-b115-460173cc5aa3 This example shows how to programmatically change the current selection in a . This selection is the same as if the user had selected the content by using the user interface. ## Code example for a RichTextBox control - The following [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] code describes a named control with simple content. + The following Extensible Application Markup Language (XAML) code describes a named control with simple content. [!code-xaml[RichTextBoxMiscSnippets_snip#ChangeSelectionProgrammaticalyExampleWholePage](~/samples/snippets/csharp/VS_Snippets_Wpf/RichTextBoxMiscSnippets_snip/CSharp/ChangeSelectionProgrammaticaly.xaml#changeselectionprogrammaticalyexamplewholepage)] diff --git a/dotnet-desktop-guide/framework/wpf/controls/checkbox.md b/dotnet-desktop-guide/framework/wpf/controls/checkbox.md index fe1c88d..eb603ae 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/checkbox.md +++ b/dotnet-desktop-guide/framework/wpf/controls/checkbox.md @@ -9,7 +9,7 @@ helpviewer_keywords: ms.assetid: ee701cc2-968b-4683-8f81-3fafd8542700 --- # CheckBox -You can use a in the [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] of your application to represent options that a user can select or clear. You can use a single check box or you can group two or more check boxes. +You can use a in the user interface (UI) of your application to represent options that a user can select or clear. You can use a single check box or you can group two or more check boxes. The following graphic shows the different states of a . diff --git a/dotnet-desktop-guide/framework/wpf/controls/contextmenu-overview.md b/dotnet-desktop-guide/framework/wpf/controls/contextmenu-overview.md index 9f0e345..e23ba25 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/contextmenu-overview.md +++ b/dotnet-desktop-guide/framework/wpf/controls/contextmenu-overview.md @@ -10,7 +10,7 @@ helpviewer_keywords: ms.assetid: 16909c42-799a-4561-91e0-7d69dcfeea91 --- # ContextMenu Overview -The class represents the element that exposes functionality by using a context-specific . Typically, a user exposes the in the [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] by right-clicking the mouse button. This topic introduces the element and provides examples of how to use it in [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] and code. +The class represents the element that exposes functionality by using a context-specific . Typically, a user exposes the in the user interface (UI) by right-clicking the mouse button. This topic introduces the element and provides examples of how to use it in Extensible Application Markup Language (XAML) and code. ## ContextMenu Control diff --git a/dotnet-desktop-guide/framework/wpf/controls/contextmenu.md b/dotnet-desktop-guide/framework/wpf/controls/contextmenu.md index e3bb128..706765b 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/contextmenu.md +++ b/dotnet-desktop-guide/framework/wpf/controls/contextmenu.md @@ -10,7 +10,7 @@ helpviewer_keywords: ms.assetid: 2f40b2bb-b702-4706-9fc4-10bcfd7cc35d --- # ContextMenu -The allows a control to display a that is specific to the context of the control. Typically, the is exposed in the [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] through the right mouse button or through the keyboard’s menu button. +The allows a control to display a that is specific to the context of the control. Typically, the is exposed in the user interface (UI) through the right mouse button or through the keyboard’s menu button. The following figure illustrates a in two different states: the default state and the open state. In the default state, the control is collapsed. When the right mouse button is pressed over the parent of the menu, the control expands and displays the menu items. diff --git a/dotnet-desktop-guide/framework/wpf/controls/control-authoring-overview.md b/dotnet-desktop-guide/framework/wpf/controls/control-authoring-overview.md index ce16b4a..382ce34 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/control-authoring-overview.md +++ b/dotnet-desktop-guide/framework/wpf/controls/control-authoring-overview.md @@ -13,21 +13,21 @@ ms.assetid: 3d864748-cff0-4e63-9b23-d8e5a635b28f --- # Control authoring overview -The extensibility of the [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] control model greatly reduces the need to create a new control. However, in certain cases you may still need to create a custom control. This topic discusses the features that minimize your need to create a custom control and the different control authoring models in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)]. This topic also demonstrates how to create a new control. +The extensibility of the Windows Presentation Foundation (WPF) control model greatly reduces the need to create a new control. However, in certain cases you may still need to create a custom control. This topic discusses the features that minimize your need to create a custom control and the different control authoring models in Windows Presentation Foundation (WPF). This topic also demonstrates how to create a new control. ## Alternatives to Writing a New Control -Historically, if you wanted to get a customized experience from an existing control, you were limited to changing the standard properties of the control, such as background color, border width, and font size. If you wished to extend the appearance or behavior of a control beyond these predefined parameters, you would need to create a new control, usually by inheriting from an existing control and overriding the method responsible for drawing the control. Although that is still an option, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] enables to you customize existing controls by using its rich content model, styles, templates, and triggers. The following list gives examples of how these features can be used to create custom and consistent experiences without having to create a new control. +Historically, if you wanted to get a customized experience from an existing control, you were limited to changing the standard properties of the control, such as background color, border width, and font size. If you wished to extend the appearance or behavior of a control beyond these predefined parameters, you would need to create a new control, usually by inheriting from an existing control and overriding the method responsible for drawing the control. Although that is still an option, WPF enables to you customize existing controls by using its rich content model, styles, templates, and triggers. The following list gives examples of how these features can be used to create custom and consistent experiences without having to create a new control. -- **Rich Content.** Many of the standard [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] controls support rich content. For example, the content property of a is of type , so theoretically anything can be displayed on a . To have a button display an image and text, you can add an image and a to a and assign the to the property. Because the controls can display [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] visual elements and arbitrary data, there is less need to create a new control or to modify an existing control to support a complex visualization. For more information about the content model for and other content models in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], see [WPF Content Model](wpf-content-model.md). +- **Rich Content.** Many of the standard WPF controls support rich content. For example, the content property of a is of type , so theoretically anything can be displayed on a . To have a button display an image and text, you can add an image and a to a and assign the to the property. Because the controls can display WPF visual elements and arbitrary data, there is less need to create a new control or to modify an existing control to support a complex visualization. For more information about the content model for and other content models in WPF, see [WPF Content Model](wpf-content-model.md). - **Styles.** A is a collection of values that represent properties for a control. By using styles, you can create a reusable representation of a desired control appearance and behavior without writing a new control. For example, assume that you want all of your controls to have red, Arial font with a font size of 14. You can create a style as a resource and set the appropriate properties accordingly. Then every that you add to your application will have the same appearance. - **Data Templates.** A enables you to customize how data is displayed on a control. For example, a can be used to specify how data is displayed in a . For an example of this, see [Data Templating Overview](../data/data-templating-overview.md). In addition to customizing the appearance of data, a can include UI elements, which gives you a lot of flexibility in custom UIs. For example, by using a , you can create a in which each item contains a check box. -- **Control Templates.** Many controls in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] use a to define the control's structure and appearance, which separates the appearance of a control from the functionality of the control. You can drastically change the appearance of a control by redefining its . For example, suppose you want a control that looks like a stoplight. This control has a simple user interface and functionality. The control is three circles, only one of which can be lit up at a time. After some reflection, you might realize that a offers the functionality of only one being selected at a time, but the default appearance of the looks nothing like the lights on a stoplight. Because the uses a control template to define its appearance, it is easy to redefine the to fit the requirements of the control, and use radio buttons to make your stoplight. +- **Control Templates.** Many controls in WPF use a to define the control's structure and appearance, which separates the appearance of a control from the functionality of the control. You can drastically change the appearance of a control by redefining its . For example, suppose you want a control that looks like a stoplight. This control has a simple user interface and functionality. The control is three circles, only one of which can be lit up at a time. After some reflection, you might realize that a offers the functionality of only one being selected at a time, but the default appearance of the looks nothing like the lights on a stoplight. Because the uses a control template to define its appearance, it is easy to redefine the to fit the requirements of the control, and use radio buttons to make your stoplight. > [!NOTE] > Although a can use a , a is not sufficient in this example. The defines the appearance of the content of a control. In the case of a , the content is whatever appears to the right of the circle that indicates whether the is selected. In the example of the stoplight, the radio button needs just be a circle that can "light up." Because the appearance requirement for the stoplight is so different than the default appearance of the , it is necessary to redefine the . In general a is used for defining the content (or data) of a control, and a is used for defining how a control is structured. @@ -42,11 +42,11 @@ In general, if your control mirrors the functionality of an existing control, bu ## Models for Control Authoring -The rich content model, styles, templates, and triggers minimize the need for you to create a new control. However, if you do need to create a new control, it is important to understand the different control authoring models in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides three general models for creating a control, each of which provides a different set of features and level of flexibility. The base classes for the three models are , , and . +The rich content model, styles, templates, and triggers minimize the need for you to create a new control. However, if you do need to create a new control, it is important to understand the different control authoring models in WPF. WPF provides three general models for creating a control, each of which provides a different set of features and level of flexibility. The base classes for the three models are , , and . ### Deriving from UserControl -The simplest way to create a control in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] is to derive from . When you build a control that inherits from , you add existing components to the , name the components, and reference event handlers in [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)]. You can then reference the named elements and define the event handlers in code. This development model is very similar to the model used for application development in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. +The simplest way to create a control in WPF is to derive from . When you build a control that inherits from , you add existing components to the , name the components, and reference event handlers in WPF. If built correctly, a can take advantage of the benefits of rich content, styles, and triggers. However, if your control inherits from , people who use your control will not be able to use a or to customize its appearance. It is necessary to derive from the class or one of its derived classes (other than ) to create a custom control that supports templates. @@ -62,7 +62,7 @@ Consider deriving from if all of the ### Deriving from Control -Deriving from the class is the model used by most of the existing [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] controls. When you create a control that inherits from the class, you define its appearance by using templates. By doing so, you separate the operational logic from the visual representation. You can also ensure the decoupling of the UI and logic by using commands and bindings instead of events and avoiding referencing elements in the whenever possible. If the UI and logic of your control are properly decoupled, a user of your control can redefine the control's to customize its appearance. Although building a custom is not as simple as building a , a custom provides the most flexibility. +Deriving from the class is the model used by most of the existing WPF controls. When you create a control that inherits from the class, you define its appearance by using templates. By doing so, you separate the operational logic from the visual representation. You can also ensure the decoupling of the UI and logic by using commands and bindings instead of events and avoiding referencing elements in the whenever possible. If the UI and logic of your control are properly decoupled, a user of your control can redefine the control's to customize its appearance. Although building a custom is not as simple as building a , a custom provides the most flexibility. #### Benefits of Deriving from Control @@ -76,7 +76,7 @@ Consider deriving from instead of using t Controls that derive from or rely upon composing existing elements. For many scenarios, this is an acceptable solution, because any object that inherits from can be in a . However, there are times when a control's appearance requires more than the functionality of simple element composition. For these scenarios, basing a component on is the right choice. -There are two standard methods for building -based components: direct rendering and custom element composition. Direct rendering involves overriding the method of and providing operations that explicitly define the component visuals. This is the method used by and . Custom element composition involves using objects of type to compose the appearance of your component. For an example, see [Using DrawingVisual Objects](../graphics-multimedia/using-drawingvisual-objects.md). is an example of a control in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] that uses custom element composition. It is also possible to mix direct rendering and custom element composition in the same control. +There are two standard methods for building -based components: direct rendering and custom element composition. Direct rendering involves overriding the method of and providing operations that explicitly define the component visuals. This is the method used by and . Custom element composition involves using objects of type to compose the appearance of your component. For an example, see [Using DrawingVisual Objects](../graphics-multimedia/using-drawingvisual-objects.md). is an example of a control in WPF that uses custom element composition. It is also possible to mix direct rendering and custom element composition in the same control. #### Benefits of Deriving from FrameworkElement @@ -92,7 +92,7 @@ Consider deriving from if any of the foll ## Control Authoring Basics -As discussed earlier, one of the most powerful features of [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] is the ability to go beyond setting basic properties of a control to change its appearance and behavior, yet still not needing to create a custom control. The styling, data binding, and trigger features are made possible by the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] property system and the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] event system. The following sections describe some practices that you should follow, regardless of the model you use to create the custom control, so that users of your custom control can use these features just as they would for a control that is included with [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. +As discussed earlier, one of the most powerful features of WPF is the ability to go beyond setting basic properties of a control to change its appearance and behavior, yet still not needing to create a custom control. The styling, data binding, and trigger features are made possible by the WPF property system and the WPF event system. The following sections describe some practices that you should follow, regardless of the model you use to create the custom control, so that users of your custom control can use these features just as they would for a control that is included with WPF. ### Use Dependency Properties @@ -120,7 +120,7 @@ If you want a property of your control to support any of this functionality, you - The metadata for the property. The metadata contains the property's default value, a and a . -- Define a CLR wrapper property named `Value`, which is the same name that is used to register the dependency property, by implementing the property's `get` and `set` accessors. Note that the `get` and `set` accessors only call and respectively. It is recommended that the accessors of dependency properties not contain additional logic because clients and [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] can bypass the accessors and call and directly. For example, when a property is bound to a data source, the property's `set` accessor is not called. Instead of adding additional logic to the get and set accessors, use the , , and delegates to respond to or check the value when it changes. For more information on these callbacks, see [Dependency Property Callbacks and Validation](../advanced/dependency-property-callbacks-and-validation.md). +- Define a CLR wrapper property named `Value`, which is the same name that is used to register the dependency property, by implementing the property's `get` and `set` accessors. Note that the `get` and `set` accessors only call and respectively. It is recommended that the accessors of dependency properties not contain additional logic because clients and WPF can bypass the accessors and call and directly. For example, when a property is bound to a data source, the property's `set` accessor is not called. Instead of adding additional logic to the get and set accessors, use the , , and delegates to respond to or check the value when it changes. For more information on these callbacks, see [Dependency Property Callbacks and Validation](../advanced/dependency-property-callbacks-and-validation.md). - Define a method for the named `CoerceValue`. `CoerceValue` ensures that `Value` is greater or equal to `MinValue` and less than or equal to `MaxValue`. @@ -133,13 +133,13 @@ For more information, see [Custom Dependency Properties](../advanced/custom-depe ### Use Routed Events -Just as dependency properties extend the notion of CLR properties with additional functionality, routed events extend the notion of standard CLR events. When you create a new [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] control, it is also good practice to implement your event as a routed event because a routed event supports the following behavior: +Just as dependency properties extend the notion of CLR properties with additional functionality, routed events extend the notion of standard CLR events. When you create a new WPF control, it is also good practice to implement your event as a routed event because a routed event supports the following behavior: - Events can be handled on a parent of multiple controls. If an event is a bubbling event, a single parent in the element tree can subscribe to the event. Then application authors can use one handler to respond to the event of multiple controls. For example, if your control is a part of each item in a (because it is included in a ), the application developer can define the event handler for your control's event on the . Whenever the event occurs on any of the controls, the event handler is called. - Routed events can be used in an , which enables application developers to specify the handler of an event within a style. -- Routed events can be used in an , which is useful for animating properties by using [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]. For more information, see [Animation Overview](../graphics-multimedia/animation-overview.md). +- Routed events can be used in an , which is useful for animating properties by using XAML. For more information, see [Animation Overview](../graphics-multimedia/animation-overview.md). The following example defines a routed event by doing the following: @@ -155,7 +155,7 @@ The following example defines a routed event by doing the following: - The owning type of the event is `NumericUpDown`. -- Declare a public event named `ValueChanged` and includes event-accessor declarations. The example calls in the `add` accessor declaration and in the `remove` accessor declaration to use the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] event services. +- Declare a public event named `ValueChanged` and includes event-accessor declarations. The example calls in the `add` accessor declaration and in the `remove` accessor declaration to use the WPF event services. - Create a protected, virtual method named `OnValueChanged` that raises the `ValueChanged` event. @@ -187,7 +187,7 @@ To receive support for custom WPF controls in the WPF Designer for Visual Studio #### Dependency Properties -Be sure to implement CLR `get` and `set` accessors as described earlier, in "Use Dependency Properties." Designers may use the wrapper to detect the presence of a dependency property, but they, like [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] and clients of the control, are not required to call the accessors when getting or setting the property. +Be sure to implement CLR `get` and `set` accessors as described earlier, in "Use Dependency Properties." Designers may use the wrapper to detect the presence of a dependency property, but they, like WPF and clients of the control, are not required to call the accessors when getting or setting the property. #### Attached Properties @@ -227,9 +227,9 @@ You can define shared resources at the element level by creating a custom resour [!code-xaml[SharedResources#1](~/samples/snippets/csharp/VS_Snippets_Wpf/SharedResources/CS/Dictionary1.xaml#1)] -Once you have defined your dictionary, you need to merge it with your control's resource dictionary. You can do this by using [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] or code. +Once you have defined your dictionary, you need to merge it with your control's resource dictionary. You can do this by using XAML or code. -The following example merges a resource dictionary by using [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]. +The following example merges a resource dictionary by using XAML. [!code-xaml[SharedResources#2](~/samples/snippets/csharp/VS_Snippets_Wpf/SharedResources/CS/ShapeResizer.xaml#2)] @@ -239,13 +239,13 @@ The following example creates a class that returns a shared is created only once. Because the resource dictionary was merged before `InitializeComponent` was called, the resources are available to the control in its [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file. +The following example merges the shared resource with the resources of a custom control in the control's constructor before it calls `InitializeComponent`. Because the `SharedDictionaryManager.SharedDictionary` is a static property, the is created only once. Because the resource dictionary was merged before `InitializeComponent` was called, the resources are available to the control in its XAML file. [!code-csharp[SharedResources#4](~/samples/snippets/csharp/VS_Snippets_Wpf/SharedResources/CS/ShapeResizer.xaml.cs#4)] #### Defining Resources at the Theme Level -[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] enables you to create resources for different Windows themes. As a control author, you can define a resource for a specific theme to change your control's appearance depending on what theme is in use. For example, the appearance of a in the Windows Classic theme (the default theme for Windows 2000) differs from a in the Windows Luna theme (the default theme for Windows XP) because the uses a different for each theme. +WPF enables you to create resources for different Windows themes. As a control author, you can define a resource for a specific theme to change your control's appearance depending on what theme is in use. For example, the appearance of a in the Windows Classic theme (the default theme for Windows 2000) differs from a in the Windows Luna theme (the default theme for Windows XP) because the uses a different for each theme. Resources that are specific to a theme are kept in a resource dictionary with a specific file name. These files must be in a folder named `Themes` that is a subfolder of the folder that contains the control. The following table lists the resource dictionary files and the theme that is associated with each file: diff --git a/dotnet-desktop-guide/framework/wpf/controls/control-customization.md b/dotnet-desktop-guide/framework/wpf/controls/control-customization.md index 922418d..9e48df6 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/control-customization.md +++ b/dotnet-desktop-guide/framework/wpf/controls/control-customization.md @@ -9,7 +9,7 @@ helpviewer_keywords: ms.assetid: a3d9930e-5597-470e-a636-dcf65eac500b --- # Control Customization -This category covers the various base classes, interfaces and other elements and concepts used in creating a fully functional [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] control. +This category covers the various base classes, interfaces and other elements and concepts used in creating a fully functional Windows Presentation Foundation (WPF) control. ## In This Section [Control Authoring Overview](control-authoring-overview.md) diff --git a/dotnet-desktop-guide/framework/wpf/controls/creating-a-control-that-has-a-customizable-appearance.md b/dotnet-desktop-guide/framework/wpf/controls/creating-a-control-that-has-a-customizable-appearance.md index c7713c4..a141fb6 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/creating-a-control-that-has-a-customizable-appearance.md +++ b/dotnet-desktop-guide/framework/wpf/controls/creating-a-control-that-has-a-customizable-appearance.md @@ -17,7 +17,7 @@ ms.assetid: 9e356d3d-a3d0-4b01-a25f-2d43e4d53fe5 # Creating a Control That Has a Customizable Appearance -[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] gives you the ability to create a control whose appearance can be customized. For example, you can change the appearance of a beyond what setting properties will do by creating a new . The following illustration shows a that uses a default and a that uses a custom . +Windows Presentation Foundation (WPF) gives you the ability to create a control whose appearance can be customized. For example, you can change the appearance of a beyond what setting properties will do by creating a new . The following illustration shows a that uses a default and a that uses a custom . ![A checkbox with the default control template.](./media/ndp-checkboxdefault.png "NDP_CheckBoxDefault") A CheckBox that uses the default control template @@ -65,7 +65,7 @@ The parts and states model specifies how to define the visual structure and visu - Provide a control contract to specify what should be included in the . -When you define the visual structure and visual behavior in the of a control, application authors can change the visual structure and visual behavior of your control by creating a new instead of writing code. You must provide a control contract that tells application authors which objects and states should be defined in the . You should follow some best practices when you interact with the parts in the so that your control properly handles an incomplete . If you follow these three principles, application authors will be able to create a for your control just as easily as they can for the controls that ship with [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. The following section explains each of these recommendations in detail. +When you define the visual structure and visual behavior in the of a control, application authors can change the visual structure and visual behavior of your control by creating a new instead of writing code. You must provide a control contract that tells application authors which objects and states should be defined in the . You should follow some best practices when you interact with the parts in the so that your control properly handles an incomplete . If you follow these three principles, application authors will be able to create a for your control just as easily as they can for the controls that ship with WPF. The following section explains each of these recommendations in detail. diff --git a/dotnet-desktop-guide/framework/wpf/controls/expander-overview.md b/dotnet-desktop-guide/framework/wpf/controls/expander-overview.md index 192bf01..39006d6 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/expander-overview.md +++ b/dotnet-desktop-guide/framework/wpf/controls/expander-overview.md @@ -30,7 +30,7 @@ An control provides a way to provide con When you set a size dimension on an control in the direction that the expanded content is displayed, the takes control of the area that is used by the content and displays a border around it. The border shows even when the content is collapsed. To set the size of the expanded content area, set size dimensions on the content of the , or if you want scrolling capability, on the that encloses the content. - When an control is the last element in a , [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] automatically sets the dimensions to equal the remaining area of the . To prevent this default behavior, set the property on the object to `false`, or make sure that the is not the last element in a . + When an control is the last element in a , Windows Presentation Foundation (WPF) automatically sets the dimensions to equal the remaining area of the . To prevent this default behavior, set the property on the object to `false`, or make sure that the is not the last element in a . ## Creating Scrollable Content diff --git a/dotnet-desktop-guide/framework/wpf/controls/guidelines-for-designing-stylable-controls.md b/dotnet-desktop-guide/framework/wpf/controls/guidelines-for-designing-stylable-controls.md index d44ceb1..f6bdd68 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/guidelines-for-designing-stylable-controls.md +++ b/dotnet-desktop-guide/framework/wpf/controls/guidelines-for-designing-stylable-controls.md @@ -8,7 +8,7 @@ ms.assetid: c52dde45-a311-4531-af4c-853371c4d5f4 --- # Guidelines for Designing Stylable Controls -This document summarizes a set of best practices to consider when designing a control which you intend to be easily stylable and templatable. We came to this set of best practices through a lot of trial and error while working on the theme control styles for the built-in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] control set. We learned that successful styling is as much a function of a well-designed object model as it is of the style itself. The intended audience for this document is the control author, not the style author. +This document summarizes a set of best practices to consider when designing a control which you intend to be easily stylable and templatable. We came to this set of best practices through a lot of trial and error while working on the theme control styles for the built-in WPF control set. We learned that successful styling is as much a function of a well-designed object model as it is of the style itself. The intended audience for this document is the control author, not the style author. @@ -42,7 +42,7 @@ To understand your control's common usage, it's good to think about the value pr - Minimize contracts as much as possible. - - Design around the expectation that during design time (that is, when using a design tool) it is common for a control template to be in an incomplete state. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] does not offer a "composing" state infrastructure, so controls have to be built with the expectation that such a state might be valid. + - Design around the expectation that during design time (that is, when using a design tool) it is common for a control template to be in an incomplete state. WPF does not offer a "composing" state infrastructure, so controls have to be built with the expectation that such a state might be valid. - Do not throw exceptions when any aspect of a template contract is not followed. Along these lines, panels should not throw exceptions if they have too many or too few children. @@ -101,7 +101,7 @@ To understand your control's common usage, it's good to think about the value pr - **Be consistent with existing styling patterns.** Many times there are multiple ways to solve a problem. Be aware of and, when possible, consistent with existing control styling patterns. This is especially important for controls that derive from the same base type (for example, , , , and so on). -- **Expose properties to enable common customization scenarios without retemplating**. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] does not support pluggable/customizable parts, so a control user is left with only two methods of customization: setting properties directly or setting properties using styles. With that in mind, it is appropriate to surface a limited number of properties targeted at very common, high-priority customization scenarios which would otherwise require the retemplating. Here are best practices for when and how to enable customization scenarios: +- **Expose properties to enable common customization scenarios without retemplating**. WPF does not support pluggable/customizable parts, so a control user is left with only two methods of customization: setting properties directly or setting properties using styles. With that in mind, it is appropriate to surface a limited number of properties targeted at very common, high-priority customization scenarios which would otherwise require the retemplating. Here are best practices for when and how to enable customization scenarios: - Very common customizations should be exposed as properties on the control and consumed by the template. diff --git a/dotnet-desktop-guide/framework/wpf/controls/how-to-adorn-the-children-of-a-panel.md b/dotnet-desktop-guide/framework/wpf/controls/how-to-adorn-the-children-of-a-panel.md index 84a3803..7974c21 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/how-to-adorn-the-children-of-a-panel.md +++ b/dotnet-desktop-guide/framework/wpf/controls/how-to-adorn-the-children-of-a-panel.md @@ -25,7 +25,7 @@ This example shows how to programmatically bind an adorner to the children of a [!code-vb[Adorners_SimpleCircleAdorner#_AdornChildren](~/samples/snippets/visualbasic/VS_Snippets_Wpf/Adorners_SimpleCircleAdorner/VisualBasic/Window1.xaml.vb#_adornchildren)] > [!NOTE] -> Using [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] to bind an adorner to another element is currently not supported. +> Using Extensible Application Markup Language (XAML) to bind an adorner to another element is currently not supported. ## See also diff --git a/dotnet-desktop-guide/framework/wpf/controls/how-to-apply-stretch-properties-to-the-contents-of-a-viewbox.md b/dotnet-desktop-guide/framework/wpf/controls/how-to-apply-stretch-properties-to-the-contents-of-a-viewbox.md index 4b3a508..a9c3f88 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/how-to-apply-stretch-properties-to-the-contents-of-a-viewbox.md +++ b/dotnet-desktop-guide/framework/wpf/controls/how-to-apply-stretch-properties-to-the-contents-of-a-viewbox.md @@ -15,11 +15,11 @@ ms.assetid: b9c22ef4-bce4-4300-9e0c-8260b7db83cc ## Example This example shows how to change the value of the and properties of a . - The first example uses [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] to define a element. It assigns a and of 400. The example nests an element within the . elements that correspond to the property values for the and enumerations manipulate the stretching behavior of the nested . + The first example uses Extensible Application Markup Language (XAML) to define a element. It assigns a and of 400. The example nests an element within the . elements that correspond to the property values for the and enumerations manipulate the stretching behavior of the nested . [!code-xaml[viewboxStretchLayoutSamp#1](~/samples/snippets/csharp/VS_Snippets_Wpf/viewboxStretchLayoutSamp/CSharp/Window1.xaml#1)] - The following code-behind file handles the events that the previous [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] example defines. + The following code-behind file handles the events that the previous XAML example defines. [!code-csharp[viewboxStretchLayoutSamp#2](~/samples/snippets/csharp/VS_Snippets_Wpf/viewboxStretchLayoutSamp/CSharp/Window1.xaml.cs#2)] [!code-vb[viewboxStretchLayoutSamp#2](~/samples/snippets/visualbasic/VS_Snippets_Wpf/viewboxStretchLayoutSamp/VisualBasic/Window1.xaml.vb#2)] diff --git a/dotnet-desktop-guide/framework/wpf/controls/how-to-bind-an-adorner-to-an-element.md b/dotnet-desktop-guide/framework/wpf/controls/how-to-bind-an-adorner-to-an-element.md index 1d79396..a1c28de 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/how-to-bind-an-adorner-to-an-element.md +++ b/dotnet-desktop-guide/framework/wpf/controls/how-to-bind-an-adorner-to-an-element.md @@ -25,7 +25,7 @@ This example shows how to programmatically bind an adorner to a specified [!NOTE] -> Using [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] to bind an adorner to another element is currently not supported. +> Using Extensible Application Markup Language (XAML) to bind an adorner to another element is currently not supported. ## See also diff --git a/dotnet-desktop-guide/framework/wpf/controls/how-to-build-a-standard-ui-dialog-box-by-using-grid.md b/dotnet-desktop-guide/framework/wpf/controls/how-to-build-a-standard-ui-dialog-box-by-using-grid.md index b93a692..57f3caa 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/how-to-build-a-standard-ui-dialog-box-by-using-grid.md +++ b/dotnet-desktop-guide/framework/wpf/controls/how-to-build-a-standard-ui-dialog-box-by-using-grid.md @@ -10,7 +10,7 @@ helpviewer_keywords: ms.assetid: d6ac3d51-844b-4d29-96d8-81a696a7b960 --- # How to: Build a Standard UI Dialog Box by Using Grid -This example shows how to create a standard [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] dialog box by using the element. +This example shows how to create a standard user interface (UI) dialog box by using the element. ## Example The following example creates a dialog box like the **Run** dialog box in the Windows operating system. diff --git a/dotnet-desktop-guide/framework/wpf/controls/how-to-create-a-grid-element.md b/dotnet-desktop-guide/framework/wpf/controls/how-to-create-a-grid-element.md index 8062c7e..e2ad598 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/how-to-create-a-grid-element.md +++ b/dotnet-desktop-guide/framework/wpf/controls/how-to-create-a-grid-element.md @@ -10,7 +10,7 @@ ms.assetid: b2f07626-9df8-43b8-8d36-492f3cb42837 --- # How to: Create a Grid Element ## Example - The following example shows how to create and use an instance of by using either [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] or code. This example uses three objects and three objects to create a grid that has nine cells, such as in a worksheet. Each cell contains a element that represents data, and the top row contains a with the property applied. To show the boundaries of each cell, the property is enabled. + The following example shows how to create and use an instance of by using either Extensible Application Markup Language (XAML) or code. This example uses three objects and three objects to create a grid that has nine cells, such as in a worksheet. Each cell contains a element that represents data, and the top row contains a with the property applied. To show the boundaries of each cell, the property is enabled. [!code-csharp[Grid#3](~/samples/snippets/csharp/VS_Snippets_Wpf/Grid/CSharp/Grid_Code.cs#3)] [!code-vb[Grid#3](~/samples/snippets/visualbasic/VS_Snippets_Wpf/Grid/VisualBasic/grid_vb.vb#3)] diff --git a/dotnet-desktop-guide/framework/wpf/controls/how-to-create-a-multiline-textbox-control.md b/dotnet-desktop-guide/framework/wpf/controls/how-to-create-a-multiline-textbox-control.md index 4c04903..00c1967 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/how-to-create-a-multiline-textbox-control.md +++ b/dotnet-desktop-guide/framework/wpf/controls/how-to-create-a-multiline-textbox-control.md @@ -7,7 +7,7 @@ helpviewer_keywords: ms.assetid: 05914a93-d0ea-4a9a-b693-09df7d4e2ac2 --- # How to: Create a Multiline TextBox Control -This example shows how to use [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] to define a control that will automatically expand to accommodate multiple lines of text. +This example shows how to use Extensible Application Markup Language (XAML) to define a control that will automatically expand to accommodate multiple lines of text. ## Example Setting the attribute to **Wrap** will cause entered text to wrap to a new line when the edge of the control is reached, automatically expanding the control to include room for a new line, if necessary. diff --git a/dotnet-desktop-guide/framework/wpf/controls/how-to-create-and-use-a-canvas.md b/dotnet-desktop-guide/framework/wpf/controls/how-to-create-and-use-a-canvas.md index 5f765f9..2173178 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/how-to-create-and-use-a-canvas.md +++ b/dotnet-desktop-guide/framework/wpf/controls/how-to-create-and-use-a-canvas.md @@ -17,7 +17,7 @@ This example shows how to create and use an instance of elements by using the and methods of . The example also assigns a color of `LightSteelBlue` to the . > [!NOTE] -> When you use [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] to position elements, use the and properties. +> When you use Extensible Application Markup Language (XAML) to position elements, use the and properties. [!code-csharp[CanvasCode#1](~/samples/snippets/csharp/VS_Snippets_Wpf/CanvasCode/CSharp/Canvas_Code.cs#1)] [!code-vb[CanvasCode#1](~/samples/snippets/visualbasic/VS_Snippets_Wpf/CanvasCode/VisualBasic/canvas_vb.vb#1)] diff --git a/dotnet-desktop-guide/framework/wpf/controls/how-to-create-and-use-a-gridlengthconverter-object.md b/dotnet-desktop-guide/framework/wpf/controls/how-to-create-and-use-a-gridlengthconverter-object.md index 4cdeeae..35163ce 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/how-to-create-and-use-a-gridlengthconverter-object.md +++ b/dotnet-desktop-guide/framework/wpf/controls/how-to-create-and-use-a-gridlengthconverter-object.md @@ -14,7 +14,7 @@ ms.assetid: 5ab75911-e36a-4825-80e4-081c57e8e182 The example also defines a second custom method, called `changeColVal`. This custom method converts the of a to a and then passes that value back to the as the of the element. - Note that a separate [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] file defines the contents of a . + Note that a separate Extensible Application Markup Language (XAML) file defines the contents of a . [!code-csharp[gridlengthConverterGrid#1](~/samples/snippets/csharp/VS_Snippets_Wpf/gridlengthConverterGrid/CSharp/Window1.xaml.cs#1)] [!code-vb[gridlengthConverterGrid#1](~/samples/snippets/visualbasic/VS_Snippets_Wpf/gridlengthConverterGrid/VisualBasic/Window1.xaml.vb#1)] diff --git a/dotnet-desktop-guide/framework/wpf/controls/how-to-crop-an-image.md b/dotnet-desktop-guide/framework/wpf/controls/how-to-crop-an-image.md index 7ac3e0b..38d15db 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/how-to-crop-an-image.md +++ b/dotnet-desktop-guide/framework/wpf/controls/how-to-crop-an-image.md @@ -17,7 +17,7 @@ This example shows how to crop an image using event to execute a method whenever the text in a control has changed. -In the code-behind class for the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] that contains the control that you want to monitor for changes, insert a method to call whenever the event fires. This method must have a signature that matches what is expected by the delegate. +In the code-behind class for the XAML that contains the control that you want to monitor for changes, insert a method to call whenever the event fires. This method must have a signature that matches what is expected by the delegate. The event handler is called whenever the contents of the control are changed, either by a user or programmatically. @@ -25,13 +25,13 @@ The event handler is called whenever the contents of the control, specify the attribute with a value that matches the event handler method name. +In the Extensible Application Markup Language (XAML) that defines your control, specify the attribute with a value that matches the event handler method name. [!code-xaml[TextBox_MiscCode#_TextChangedXAML](~/samples/snippets/csharp/VS_Snippets_Wpf/TextBox_MiscCode/CSharp/Window1.xaml#_textchangedxaml)] ## Monitor the TextBox control changes -In the code-behind class for the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] that contains the control that you want to monitor for changes, insert a method to call whenever the event fires. This method must have a signature that matches what is expected by the delegate. +In the code-behind class for the XAML that contains the control that you want to monitor for changes, insert a method to call whenever the event fires. This method must have a signature that matches what is expected by the delegate. [!code-csharp[TextBox_MiscCode#_TextChangedEventHandler](~/samples/snippets/csharp/VS_Snippets_Wpf/TextBox_MiscCode/CSharp/Window1.xaml.cs#_textchangedeventhandler)] [!code-vb[TextBox_MiscCode#_TextChangedEventHandler](~/samples/snippets/visualbasic/VS_Snippets_Wpf/TextBox_MiscCode/VisualBasic/Window1.xaml.vb#_textchangedeventhandler)] diff --git a/dotnet-desktop-guide/framework/wpf/controls/how-to-extract-the-text-content-from-a-richtextbox.md b/dotnet-desktop-guide/framework/wpf/controls/how-to-extract-the-text-content-from-a-richtextbox.md index d3e5a8e..17d42a8 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/how-to-extract-the-text-content-from-a-richtextbox.md +++ b/dotnet-desktop-guide/framework/wpf/controls/how-to-extract-the-text-content-from-a-richtextbox.md @@ -17,7 +17,7 @@ ms.assetid: f13c093f-1a05-45b3-ac8f-c9ea5e4a11c5 This example shows how to extract the contents of a as plain text. ## Describe a RichTextBox control - The following [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] code describes a named control with simple content. + The following Extensible Application Markup Language (XAML) code describes a named control with simple content. [!code-xaml[RichTextBoxSnippets#_RTB_XAML](~/samples/snippets/csharp/VS_Snippets_Wpf/RichTextBoxSnippets/CSharp/Window1.xaml#_rtb_xaml)] diff --git a/dotnet-desktop-guide/framework/wpf/controls/how-to-handle-the-scrollchanged-event.md b/dotnet-desktop-guide/framework/wpf/controls/how-to-handle-the-scrollchanged-event.md index 633f9cd..f6c7639 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/how-to-handle-the-scrollchanged-event.md +++ b/dotnet-desktop-guide/framework/wpf/controls/how-to-handle-the-scrollchanged-event.md @@ -13,7 +13,7 @@ ms.assetid: 42c695d8-ee28-49d4-80fd-fc71e9be7f29 ## Example This example shows how to handle the event of a . - A element with parts is defined in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]. When the event occurs due to user interaction, a handler is invoked, and text is written to a indicating that the event has occurred. + A element with parts is defined in XAML. When the event occurs due to user interaction, a handler is invoked, and text is written to a indicating that the event has occurred. [!code-xaml[scrollchangedeventargsLayout#1](~/samples/snippets/csharp/VS_Snippets_Wpf/scrollchangedeventargsLayout/CSharp/Window1.xaml#1)] [!code-xaml[scrollchangedeventargsLayout#2](~/samples/snippets/csharp/VS_Snippets_Wpf/scrollchangedeventargsLayout/CSharp/Window1.xaml#2)] diff --git a/dotnet-desktop-guide/framework/wpf/controls/how-to-horizontally-or-vertically-align-content-in-a-stackpanel.md b/dotnet-desktop-guide/framework/wpf/controls/how-to-horizontally-or-vertically-align-content-in-a-stackpanel.md index ac75aba..2bd2e78 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/how-to-horizontally-or-vertically-align-content-in-a-stackpanel.md +++ b/dotnet-desktop-guide/framework/wpf/controls/how-to-horizontally-or-vertically-align-content-in-a-stackpanel.md @@ -15,7 +15,7 @@ ms.assetid: c1e8f962-72c8-4e7a-8670-7a2d7e021791 This example shows how to adjust the of content within a element, and also how to adjust the and of child content. ## Example - The following example creates three elements in [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)]. Each represents the possible values of the , , and properties of a . When a user selects a value in any of the elements, the associated property of the and its child elements change. + The following example creates three elements in Extensible Application Markup Language (XAML). Each represents the possible values of the , , and properties of a . When a user selects a value in any of the elements, the associated property of the and its child elements change. [!code-xaml[StackPanelIntroSamp#1](~/samples/snippets/csharp/VS_Snippets_Wpf/StackPanelIntroSamp/CSharp/Window1.xaml#1)] diff --git a/dotnet-desktop-guide/framework/wpf/controls/how-to-make-a-textbox-control-read-only.md b/dotnet-desktop-guide/framework/wpf/controls/how-to-make-a-textbox-control-read-only.md index 477b39d..9bfefab 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/how-to-make-a-textbox-control-read-only.md +++ b/dotnet-desktop-guide/framework/wpf/controls/how-to-make-a-textbox-control-read-only.md @@ -14,7 +14,7 @@ This example shows how to configure a con [!code-xaml[TextBox_MiscCode#_ReadOnlyTextBoxXAML](~/samples/snippets/csharp/VS_Snippets_Wpf/TextBox_MiscCode/CSharp/Window1.xaml#_readonlytextboxxaml)] - The attribute affects user input only; it does not affect text set in the [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] description of a control, or text set programmatically through the property. + The attribute affects user input only; it does not affect text set in the Extensible Application Markup Language (XAML) description of a control, or text set programmatically through the property. The default value of is **false**. diff --git a/dotnet-desktop-guide/framework/wpf/controls/how-to-partition-space-by-using-the-dockpanel-element.md b/dotnet-desktop-guide/framework/wpf/controls/how-to-partition-space-by-using-the-dockpanel-element.md index 7e95ef8..523c3ba 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/how-to-partition-space-by-using-the-dockpanel-element.md +++ b/dotnet-desktop-guide/framework/wpf/controls/how-to-partition-space-by-using-the-dockpanel-element.md @@ -12,7 +12,7 @@ helpviewer_keywords: ms.assetid: a219b9e5-b205-4438-89b5-0a137ac463ab --- # How to: Partition Space by Using the DockPanel Element -The following example creates a simple [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] framework using a element. The partitions available space to its child elements. +The following example creates a simple user interface (UI) framework using a element. The partitions available space to its child elements. ## Example This example uses the property, which is an attached property, to dock two identical elements at the of the partitioned space. A third element is docked to the , with its width set to 200 pixels. A fourth is docked to the of the screen. The last element automatically fills the remaining space. diff --git a/dotnet-desktop-guide/framework/wpf/controls/how-to-position-a-tooltip.md b/dotnet-desktop-guide/framework/wpf/controls/how-to-position-a-tooltip.md index 4eb26b0..cba7baa 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/how-to-position-a-tooltip.md +++ b/dotnet-desktop-guide/framework/wpf/controls/how-to-position-a-tooltip.md @@ -27,7 +27,7 @@ This example shows how to specify the position of a tooltip on the screen. If you define the contents of a tooltip by using a object, you can use the properties of either class; however, the properties take precedence. Use the properties for tooltips that are not defined as objects. - The following illustrations show how to position a tooltip by using these properties. Although, the [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] examples in these illustrations show how to set the properties that are defined by the class, the corresponding properties of the class follow the same layout rules. For more information about the possible values for the Placement property, see [Popup Placement Behavior](popup-placement-behavior.md). + The following illustrations show how to position a tooltip by using these properties. Although, the Extensible Application Markup Language (XAML) examples in these illustrations show how to set the properties that are defined by the class, the corresponding properties of the class follow the same layout rules. For more information about the possible values for the Placement property, see [Popup Placement Behavior](popup-placement-behavior.md). The following image shows tooltip placement by using the Placement property: diff --git a/dotnet-desktop-guide/framework/wpf/controls/how-to-retrieve-a-text-selection.md b/dotnet-desktop-guide/framework/wpf/controls/how-to-retrieve-a-text-selection.md index 38ae3f5..be1d173 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/how-to-retrieve-a-text-selection.md +++ b/dotnet-desktop-guide/framework/wpf/controls/how-to-retrieve-a-text-selection.md @@ -16,14 +16,14 @@ ms.assetid: d5793172-1e11-4a39-9be0-73f336ed858d This example shows one way to use the property to retrieve text that the user has selected in a control. ## Define a TextBox control - The following [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] example shows the definition of a control that contains some text to select, and a control with a specified method. + The following Extensible Application Markup Language (XAML) example shows the definition of a control that contains some text to select, and a control with a specified method. In this example, a button with an associated event handler is used to retrieve the text selection. When the user clicks the button, the method copies any selected text in the textbox into a string. The particular circumstances by which the text selection is retrieved (clicking a button), as well as the action taken with that selection (copying the text selection to a string), can easily be modified to accommodate a wide variety of scenarios. [!code-xaml[TextBox_MiscCode#_TextBoxSelectTextXAML](~/samples/snippets/csharp/VS_Snippets_Wpf/TextBox_MiscCode/CSharp/Window1.xaml#_textboxselecttextxaml)] ## OnClick event handler - The following C# example shows an event handler for the button defined in the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] for this example. + The following C# example shows an event handler for the button defined in the XAML for this example. [!code-csharp[TextBox_MiscCode#_SelectText](~/samples/snippets/csharp/VS_Snippets_Wpf/TextBox_MiscCode/CSharp/Window1.xaml.cs#_selecttext)] [!code-vb[TextBox_MiscCode#_SelectText](~/samples/snippets/visualbasic/VS_Snippets_Wpf/TextBox_MiscCode/VisualBasic/Window1.xaml.vb#_selecttext)] diff --git a/dotnet-desktop-guide/framework/wpf/controls/how-to-scroll-content-by-using-the-iscrollinfo-interface.md b/dotnet-desktop-guide/framework/wpf/controls/how-to-scroll-content-by-using-the-iscrollinfo-interface.md index ec18f74..e0343de 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/how-to-scroll-content-by-using-the-iscrollinfo-interface.md +++ b/dotnet-desktop-guide/framework/wpf/controls/how-to-scroll-content-by-using-the-iscrollinfo-interface.md @@ -14,11 +14,11 @@ ms.assetid: d8700bef-a3f8-4c12-9de2-fc3b79f32cd3 This example shows how to scroll content by using the interface. ## Example - The following example demonstrates the features of the interface. The example creates a element in [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] that is nested in a parent . The child elements of the can be scrolled logically by using the methods defined by the interface and cast to the instance of (`sp1`) in code. + The following example demonstrates the features of the interface. The example creates a element in Extensible Application Markup Language (XAML) that is nested in a parent . The child elements of the can be scrolled logically by using the methods defined by the interface and cast to the instance of (`sp1`) in code. [!code-xaml[IScrollInfoMethods#2](~/samples/snippets/csharp/VS_Snippets_Wpf/IScrollInfoMethods/CSharp/Window1.xaml#2)] - Each in the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file triggers an associated custom method that controls scrolling behavior in . The following example shows how to use the and methods; it also generically shows how to use all the positioning methods that the class defines. + Each in the XAML file triggers an associated custom method that controls scrolling behavior in . The following example shows how to use the and methods; it also generically shows how to use all the positioning methods that the class defines. [!code-csharp[IScrollInfoMethods#3](~/samples/snippets/csharp/VS_Snippets_Wpf/IScrollInfoMethods/CSharp/Window1.xaml.cs#3)] [!code-vb[IScrollInfoMethods#3](~/samples/snippets/visualbasic/VS_Snippets_Wpf/IScrollInfoMethods/VisualBasic/Window1.xaml.vb#3)] diff --git a/dotnet-desktop-guide/framework/wpf/controls/how-to-set-focus-in-a-textbox-control.md b/dotnet-desktop-guide/framework/wpf/controls/how-to-set-focus-in-a-textbox-control.md index 5692495..61136a3 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/how-to-set-focus-in-a-textbox-control.md +++ b/dotnet-desktop-guide/framework/wpf/controls/how-to-set-focus-in-a-textbox-control.md @@ -15,7 +15,7 @@ ms.assetid: 24b61b45-dc2d-425e-9839-b017af7ab86f This example shows how to use the method to set focus on a control. ## Define a simple TextBox control - The following [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] example describes a simple control named *tbFocusMe* + The following Extensible Application Markup Language (XAML) example describes a simple control named *tbFocusMe* [!code-xaml[TextBox_MiscCode#_TextBoxFocusXAML](~/samples/snippets/csharp/VS_Snippets_Wpf/TextBox_MiscCode/CSharp/Window1.xaml#_textboxfocusxaml)] diff --git a/dotnet-desktop-guide/framework/wpf/controls/how-to-set-the-height-properties-of-an-element.md b/dotnet-desktop-guide/framework/wpf/controls/how-to-set-the-height-properties-of-an-element.md index 8ec7c40..562f022 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/how-to-set-the-height-properties-of-an-element.md +++ b/dotnet-desktop-guide/framework/wpf/controls/how-to-set-the-height-properties-of-an-element.md @@ -11,11 +11,11 @@ ms.assetid: 5ab9e781-dbb8-469a-a3c8-cf38ce312647 --- # How to: Set the Height Properties of an Element ## Example - This example visually shows the differences in rendering behavior among the four height-related properties in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)]. + This example visually shows the differences in rendering behavior among the four height-related properties in Windows Presentation Foundation (WPF). The class exposes four properties that describe the height characteristics of an element. These four properties can conflict, and when they do, the value that takes precedence is determined as follows: the value takes precedence over the value, which in turn takes precedence over the value. A fourth property, , is read-only, and reports the actual height as determined by interactions with the layout process. - The following [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] examples draw a element (`rect1`) as a child of . You can change the height properties of a by using a series of elements that represent the property values of , , and . In this manner, the precedence of each property is visually displayed. + The following Extensible Application Markup Language (XAML) examples draw a element (`rect1`) as a child of . You can change the height properties of a by using a series of elements that represent the property values of , , and . In this manner, the precedence of each property is visually displayed. [!code-xaml[HeightMinHeightMaxHeight#1](~/samples/snippets/csharp/VS_Snippets_Wpf/HeightMinHeightMaxHeight/CSharp/Window1.xaml#1)] [!code-xaml[HeightMinHeightMaxHeight#2](~/samples/snippets/csharp/VS_Snippets_Wpf/HeightMinHeightMaxHeight/CSharp/Window1.xaml#2)] diff --git a/dotnet-desktop-guide/framework/wpf/controls/how-to-set-the-text-content-of-a-textbox-control.md b/dotnet-desktop-guide/framework/wpf/controls/how-to-set-the-text-content-of-a-textbox-control.md index 964c62f..9f12d23 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/how-to-set-the-text-content-of-a-textbox-control.md +++ b/dotnet-desktop-guide/framework/wpf/controls/how-to-set-the-text-content-of-a-textbox-control.md @@ -16,7 +16,7 @@ ms.assetid: bcd25fc7-a52f-4453-b802-2c8d2b335ab8 This example shows how to use the property to set the initial text contents of a control. > [!NOTE] -> Although the [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] version of the example could use the `` tags around the text of each button's content, it is not necessary because the applies the attribute to the property. For more information, see [XAML in WPF](../advanced/xaml-in-wpf.md). +> Although the Extensible Application Markup Language (XAML) version of the example could use the `` tags around the text of each button's content, it is not necessary because the applies the attribute to the property. For more information, see [XAML in WPF](../advanced/xaml-in-wpf.md). ## Use the Text property to set the text contents diff --git a/dotnet-desktop-guide/framework/wpf/controls/how-to-set-the-width-properties-of-an-element.md b/dotnet-desktop-guide/framework/wpf/controls/how-to-set-the-width-properties-of-an-element.md index 78fccb5..89c23e9 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/how-to-set-the-width-properties-of-an-element.md +++ b/dotnet-desktop-guide/framework/wpf/controls/how-to-set-the-width-properties-of-an-element.md @@ -11,11 +11,11 @@ ms.assetid: 6ee04a9d-63f0-4f5b-a406-0a8cd4c35729 --- # How to: Set the Width Properties of an Element ## Example - This example visually shows the differences in rendering behavior among the four width-related properties in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)]. + This example visually shows the differences in rendering behavior among the four width-related properties in Windows Presentation Foundation (WPF). The class exposes four properties that describe the width characteristics of an element. These four properties can conflict, and when they do, the value that takes precedence is determined as follows: the value takes precedence over the value, which in turn takes precedence over the value. A fourth property, , is read-only, and reports the actual width as determined by interactions with the layout process. - The following [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] examples draw a element (`rect1`) as a child of . You can change the width properties of a by using a series of elements that represent the property values of , , and . In this manner, the precedence of each property is visually displayed. + The following Extensible Application Markup Language (XAML) examples draw a element (`rect1`) as a child of . You can change the width properties of a by using a series of elements that represent the property values of , , and . In this manner, the precedence of each property is visually displayed. [!code-xaml[WidthMinWidthMaxWidth#1](~/samples/snippets/csharp/VS_Snippets_Wpf/WidthMinWidthMaxWidth/CSharp/Window1.xaml#1)] [!code-xaml[WidthMinWidthMaxWidth#2](~/samples/snippets/csharp/VS_Snippets_Wpf/WidthMinWidthMaxWidth/CSharp/Window1.xaml#2)] diff --git a/dotnet-desktop-guide/framework/wpf/controls/how-to-sort-a-gridview-column-when-a-header-is-clicked.md b/dotnet-desktop-guide/framework/wpf/controls/how-to-sort-a-gridview-column-when-a-header-is-clicked.md index ca8f2ba..8ab7cb0 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/how-to-sort-a-gridview-column-when-a-header-is-clicked.md +++ b/dotnet-desktop-guide/framework/wpf/controls/how-to-sort-a-gridview-column-when-a-header-is-clicked.md @@ -55,7 +55,7 @@ The following example shows the data items that are defined as an ``` -The `s` and `p` identifiers in the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] tags refer to namespace mappings that are defined in the metadata of the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] page. The following example shows the metadata definition. +The `s` and `p` identifiers in the XAML tags refer to namespace mappings that are defined in the metadata of the XAML page. The following example shows the metadata definition. ```xaml . ## Define a Custom Context Menu - The following [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] example defines a control that includes a custom context menu. + The following Extensible Application Markup Language (XAML) example defines a control that includes a custom context menu. The context menu is defined using a element. The context menu itself consists of a series of elements and elements. Each element defines a command in the context menu; the attribute defines the display text for the menu command, and the attribute specifies a handler method for each menu item. The element simply causes a separating line to be rendered between the previous and subsequent menu items. diff --git a/dotnet-desktop-guide/framework/wpf/controls/how-to-use-spell-checking-with-a-context-menu.md b/dotnet-desktop-guide/framework/wpf/controls/how-to-use-spell-checking-with-a-context-menu.md index dc36449..321cbad 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/how-to-use-spell-checking-with-a-context-menu.md +++ b/dotnet-desktop-guide/framework/wpf/controls/how-to-use-spell-checking-with-a-context-menu.md @@ -16,7 +16,7 @@ ms.assetid: 61f69a20-2ff3-4056-9060-e32f4483ec5e By default, when you enable spell checking in an editing control like or , you get spell-checking choices in the context menu. For example, when users right-click a misspelled word, they get a set of spelling suggestions or the option to **Ignore All**. However, when you override the default context menu with your own custom context menu, this functionality is lost, and you need to write code to reenable the spell-checking feature in the context menu. The following example shows how to enable this on a . ## Define a Context Menu - The following example shows the [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] that creates a with some events that are used to implement the context menu. + The following example shows the Extensible Application Markup Language (XAML) that creates a with some events that are used to implement the context menu. [!code-xaml[TextBoxMiscSnippets_snip#SpellerCustomContextMenuExampleWholePage](~/samples/snippets/csharp/VS_Snippets_Wpf/TextBoxMiscSnippets_snip/csharp/speller_custom_context_menu.xaml#spellercustomcontextmenuexamplewholepage)] diff --git a/dotnet-desktop-guide/framework/wpf/controls/how-to-use-the-content-scrolling-methods-of-scrollviewer.md b/dotnet-desktop-guide/framework/wpf/controls/how-to-use-the-content-scrolling-methods-of-scrollviewer.md index c82f919..48251c7 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/how-to-use-the-content-scrolling-methods-of-scrollviewer.md +++ b/dotnet-desktop-guide/framework/wpf/controls/how-to-use-the-content-scrolling-methods-of-scrollviewer.md @@ -14,7 +14,7 @@ ms.assetid: 4708cc65-6510-45f8-82e6-30b0d3e30045 This example shows how to use the scrolling methods of the element. These methods provide incremental scrolling of content, either by line or by page, in a . ## Example - The following example creates a named `sv1`, which hosts a child element. Because the is larger than the parent , scroll bars appear in order to enable scrolling. elements that represent the various scrolling methods are docked on the left in a separate . Each in the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file calls a related custom method that controls scrolling behavior in . + The following example creates a named `sv1`, which hosts a child element. Because the is larger than the parent , scroll bars appear in order to enable scrolling. elements that represent the various scrolling methods are docked on the left in a separate . Each in the XAML file calls a related custom method that controls scrolling behavior in . [!code-xaml[ScrollViewerMethods#1](~/samples/snippets/csharp/VS_Snippets_Wpf/ScrollViewerMethods/CSharp/Window1.xaml#1)] diff --git a/dotnet-desktop-guide/framework/wpf/controls/how-to-use-the-image-element.md b/dotnet-desktop-guide/framework/wpf/controls/how-to-use-the-image-element.md index 45613ad..a93e6f2 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/how-to-use-the-image-element.md +++ b/dotnet-desktop-guide/framework/wpf/controls/how-to-use-the-image-element.md @@ -16,7 +16,7 @@ ms.assetid: 5b92e74b-1b56-4756-ac64-d5e9e08d9854 This example shows how to include images in an application by using the element. ## Define an image - The following example shows how to render an image 200 pixels wide. In this [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] example, both attribute syntax and property tag syntax are used to define the image. For more information on attribute syntax and property syntax, see [Dependency Properties Overview](../advanced/dependency-properties-overview.md). A is used to define the image's source data and is explicitly defined for the property tag syntax example. In addition, the of the is set to the same width as the of the . This is done to ensure that the minimum amount of memory is used rendering the image. + The following example shows how to render an image 200 pixels wide. In this Extensible Application Markup Language (XAML) example, both attribute syntax and property tag syntax are used to define the image. For more information on attribute syntax and property syntax, see [Dependency Properties Overview](../advanced/dependency-properties-overview.md). A is used to define the image's source data and is explicitly defined for the property tag syntax example. In addition, the of the is set to the same width as the of the . This is done to ensure that the minimum amount of memory is used rendering the image. > [!NOTE] > In general, if you want to specify the size of a rendered image, specify only the or the but not both. If you only specify one, the image's aspect ratio is preserved. Otherwise, the image may unexpectedly appear stretched or warped. To control the image's stretching behavior, use the and properties. diff --git a/dotnet-desktop-guide/framework/wpf/controls/image.md b/dotnet-desktop-guide/framework/wpf/controls/image.md index 1da132f..d6b1f38 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/image.md +++ b/dotnet-desktop-guide/framework/wpf/controls/image.md @@ -9,7 +9,7 @@ helpviewer_keywords: ms.assetid: 5707e860-ee4a-4c9f-b123-80c64996af19 --- # Image -The element is used to display bitmap images in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] applications. +The element is used to display bitmap images in Windows Presentation Foundation (WPF) applications. ## In This Section [How-to Topics](image-how-to-topics.md) diff --git a/dotnet-desktop-guide/framework/wpf/controls/index.md b/dotnet-desktop-guide/framework/wpf/controls/index.md index 1840931..20d5412 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/index.md +++ b/dotnet-desktop-guide/framework/wpf/controls/index.md @@ -11,15 +11,15 @@ ms.assetid: 3f255a8a-35a8-4712-9065-472ff7d75599 --- # Controls -[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] ships with many of the common UI components that are used in almost every Windows application, such as , , , , and . Historically, these objects have been referred to as controls. While the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] SDK continues to use the term "control" to loosely mean any class that represents a visible object in an application, it is important to note that a class does not need to inherit from the class to have a visible presence. Classes that inherit from the class contain a , which allows the consumer of a control to radically change the control's appearance without having to create a new subclass. This topic discusses how controls (both those that do inherit from the class and those that do not) are commonly used in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. +WPF SDK continues to use the term "control" to loosely mean any class that represents a visible object in an application, it is important to note that a class does not need to inherit from the class to have a visible presence. Classes that inherit from the class contain a , which allows the consumer of a control to radically change the control's appearance without having to create a new subclass. This topic discusses how controls (both those that do inherit from the class and those that do not) are commonly used in WPF. ## Creating an Instance of a Control - You can add a control to an application by using either [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] or code. The following example shows how to create a simple application that asks a user for their first and last name. This example creates six controls: two labels, two text boxes, and two buttons, in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]. All controls can be created similarly. + You can add a control to an application by using either XAML. All controls can be created similarly. [!code-xaml[ControlsOverview#1](~/samples/snippets/csharp/VS_Snippets_Wpf/ControlsOverview/CSharp/Window1.xaml#1)] - The following example creates the same application in code. For brevity, the creation of the , `grid1`, has been excluded from the sample. `grid1` has the same column and row definitions as shown in the preceding [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] example. + The following example creates the same application in code. For brevity, the creation of the , `grid1`, has been excluded from the sample. `grid1` has the same column and row definitions as shown in the preceding XAML example. [!code-csharp[ControlsOverview#2](~/samples/snippets/csharp/VS_Snippets_Wpf/ControlsOverview/CSharp/AppInCode.xaml.cs#2)] [!code-vb[ControlsOverview#2](~/samples/snippets/visualbasic/VS_Snippets_Wpf/ControlsOverview/VisualBasic/AppInCode.xaml.vb#2)] @@ -35,7 +35,7 @@ ms.assetid: 3f255a8a-35a8-4712-9065-472ff7d75599 - Create a new for the control. ### Changing a Control's Property Value - Many controls have properties that allow you to change how the control appears, such as the of a . You can set the value properties in both [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] and code. The following example sets the , , and properties on a in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]. + Many controls have properties that allow you to change how the control appears, such as the of a . You can set the value properties in both XAML and code. The following example sets the , , and properties on a in XAML. [!code-xaml[ControlsOverview#3](~/samples/snippets/csharp/VS_Snippets_Wpf/ControlsOverview/CSharp/AppInCode.xaml#3)] @@ -45,7 +45,7 @@ ms.assetid: 3f255a8a-35a8-4712-9065-472ff7d75599 [!code-vb[ControlsOverview#4](~/samples/snippets/visualbasic/VS_Snippets_Wpf/ControlsOverview/VisualBasic/AppInCode.xaml.vb#4)] ### Creating a Style for a Control - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] gives you the ability to specify the appearance of controls wholesale, instead of setting properties on each instance in the application, by creating a . The following example creates a that is applied to each in the application. definitions are typically defined in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] in a , such as the property of the . + WPF gives you the ability to specify the appearance of controls wholesale, instead of setting properties on each instance in the application, by creating a . The following example creates a that is applied to each in the application. definitions are typically defined in XAML in a , such as the property of the . [!code-xaml[ControlsOverview#5](~/samples/snippets/csharp/VS_Snippets_Wpf/ControlsOverview/CSharp/AppInCode.xaml#5)] @@ -54,7 +54,7 @@ ms.assetid: 3f255a8a-35a8-4712-9065-472ff7d75599 ### Creating a ControlTemplate A allows you to set properties on multiple controls at a time, but sometimes you might want to customize the appearance of a beyond what you can do by creating a . Classes that inherit from the class have a , which defines the structure and appearance of a . The property of a is public, so you can give a a that is different than its default. You can often specify a new for a instead of inheriting from a control to customize the appearance of a . - Consider the very common control, . The primary behavior of a is to enable an application to take some action when the user clicks it. By default, the in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] appears as a raised rectangle. While developing an application, you might want to take advantage of the behavior of a --that is, by handling the button's click event--but you might change the button's appearance beyond what you can do by changing the button's properties. In this case, you can create a new . + Consider the very common control, . The primary behavior of a is to enable an application to take some action when the user clicks it. By default, the in WPF appears as a raised rectangle. While developing an application, you might want to take advantage of the behavior of a --that is, by handling the button's click event--but you might change the button's appearance beyond what you can do by changing the button's properties. In this case, you can create a new . The following example creates a for a . The creates a with rounded corners and a gradient background. The contains a whose is a with two objects. The first uses data binding to bind the property of the to the color of the button's background. When you set the property of the , the color of that value will be used as the first . For more information about data binding, see [Data Binding Overview](../data/data-binding-overview.md). The example also creates a that changes the appearance of the when is `true`. @@ -66,7 +66,7 @@ ms.assetid: 3f255a8a-35a8-4712-9065-472ff7d75599 ## Subscribing to Events - You can subscribe to a control's event by using either [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] or code, but you can only handle an event in code. The following example shows how to subscribe to the `Click` event of a . + You can subscribe to a control's event by using either XAML or code, but you can only handle an event in code. The following example shows how to subscribe to the `Click` event of a . [!code-xaml[ControlsOverview#10](~/samples/snippets/csharp/VS_Snippets_Wpf/ControlsOverview/CSharp/Window1.xaml#10)] @@ -80,7 +80,7 @@ ms.assetid: 3f255a8a-35a8-4712-9065-472ff7d75599 ## Rich Content in Controls - Most classes that inherit from the class have the capacity to contain rich content. For example, a can contain any object, such as a string, an , or a . The following classes provide support for rich content and act as base classes for most of the controls in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. + Most classes that inherit from the class have the capacity to contain rich content. For example, a can contain any object, such as a string, an , or a . The following classes provide support for rich content and act as base classes for most of the controls in WPF. - -- Some examples of classes that inherit from this class are , , and . diff --git a/dotnet-desktop-guide/framework/wpf/controls/label.md b/dotnet-desktop-guide/framework/wpf/controls/label.md index afa8eb9..b7c9405 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/label.md +++ b/dotnet-desktop-guide/framework/wpf/controls/label.md @@ -10,7 +10,7 @@ ms.assetid: 241c1ce2-60f8-4613-a0ec-9b9bb25fb6af --- # Label - controls usually provide information in the [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)]. Historically, a has contained only text, but because the that ships with [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] is a , it can contain either text or a . + controls usually provide information in the user interface (UI). Historically, a has contained only text, but because the that ships with Windows Presentation Foundation (WPF) is a , it can contain either text or a . A provides both functional and visual support for access keys. It is frequently used to enable quick keyboard access to controls such as a . To assign a to a , set the property to the control that should get focus when the user presses the access key. diff --git a/dotnet-desktop-guide/framework/wpf/controls/listview-overview.md b/dotnet-desktop-guide/framework/wpf/controls/listview-overview.md index ede08b2..1dda89c 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/listview-overview.md +++ b/dotnet-desktop-guide/framework/wpf/controls/listview-overview.md @@ -22,7 +22,7 @@ The control provides the infrastructure ## Defining a View Mode for a ListView - To specify a view mode for the content of a control, you set the property. One view mode that [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides is , which displays a collection of data items in a table that has customizable columns. + To specify a view mode for the content of a control, you set the property. One view mode that Windows Presentation Foundation (WPF) provides is , which displays a collection of data items in a table that has customizable columns. The following example shows how to define a for a control that displays employee information. diff --git a/dotnet-desktop-guide/framework/wpf/controls/manipulate-columns-and-rows-by-using-columndefinitionscollections.md b/dotnet-desktop-guide/framework/wpf/controls/manipulate-columns-and-rows-by-using-columndefinitionscollections.md index 3f0b2ac..a79f40e 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/manipulate-columns-and-rows-by-using-columndefinitionscollections.md +++ b/dotnet-desktop-guide/framework/wpf/controls/manipulate-columns-and-rows-by-using-columndefinitionscollections.md @@ -18,7 +18,7 @@ This example shows how to use the methods in the event in the [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] file. You can change the number of columns and rows in the in several ways, which includes adding or removing rows and columns; and counting the total number of rows and columns. To prevent and exceptions, you can use the error-checking functionality that the method provides. + This example defines a series of custom methods, each corresponding to a event in the Extensible Application Markup Language (XAML) file. You can change the number of columns and rows in the in several ways, which includes adding or removing rows and columns; and counting the total number of rows and columns. To prevent and exceptions, you can use the error-checking functionality that the method provides. :::code language="csharp" source="snippets/manipulate-columns-and-rows-by-using-columndefinitionscollections/csharp/Window1.xaml.cs" id="Snippet2"::: :::code language="vb" source="snippets/manipulate-columns-and-rows-by-using-columndefinitionscollections/vb/Window1.xaml.vb" id="Snippet2"::: diff --git a/dotnet-desktop-guide/framework/wpf/controls/panel.md b/dotnet-desktop-guide/framework/wpf/controls/panel.md index fcd0372..49fd3fe 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/panel.md +++ b/dotnet-desktop-guide/framework/wpf/controls/panel.md @@ -10,7 +10,7 @@ helpviewer_keywords: ms.assetid: 792943c5-335d-49dd-aa5b-ec1582a10088 --- # Panel - is the base class for all elements that support application layout in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)]. + is the base class for all elements that support application layout in Windows Presentation Foundation (WPF). ## In This Section [Panels Overview](panels-overview.md) diff --git a/dotnet-desktop-guide/framework/wpf/controls/panels-overview.md b/dotnet-desktop-guide/framework/wpf/controls/panels-overview.md index 3d5f6e9..f9a69c7 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/panels-overview.md +++ b/dotnet-desktop-guide/framework/wpf/controls/panels-overview.md @@ -13,7 +13,7 @@ ms.assetid: f73644af-9941-4611-8754-6d4cef03fc44 --- # Panels Overview - elements are components that control the rendering of elements—their size and dimensions, their position, and the arrangement of their child content. The [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides a number of predefined elements as well as the ability to construct custom elements. + elements are components that control the rendering of elements—their size and dimensions, their position, and the arrangement of their child content. The Windows Presentation Foundation (WPF) provides a number of predefined elements as well as the ability to construct custom elements. This topic contains the following sections. @@ -35,9 +35,9 @@ ms.assetid: f73644af-9941-4611-8754-6d4cef03fc44 ## The Panel Class - is the base class for all elements that provide layout support in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)]. Derived elements are used to position and arrange elements in [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] and code. + is the base class for all elements that provide layout support in Windows Presentation Foundation (WPF). Derived elements are used to position and arrange elements in Extensible Application Markup Language (XAML) and code. - The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] includes a comprehensive suite of derived panel implementations that enable many complex layouts. These derived classes expose properties and methods that enable most standard [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] scenarios. Developers who are unable to find a child arrangement behavior that meets their needs can create new layouts by overriding the and methods. For more information on custom layout behaviors, see [Custom Panel Elements](#Panels_custom_panel_elements). + The WPF includes a comprehensive suite of derived panel implementations that enable many complex layouts. These derived classes expose properties and methods that enable most standard user interface (UI) scenarios. Developers who are unable to find a child arrangement behavior that meets their needs can create new layouts by overriding the and methods. For more information on custom layout behaviors, see [Custom Panel Elements](#Panels_custom_panel_elements). @@ -53,15 +53,15 @@ ms.assetid: f73644af-9941-4611-8754-6d4cef03fc44 #### Attached Properties - Derived panel elements make extensive use of attached properties. An attached property is a specialized form of dependency property that does not have the conventional common language runtime (CLR) property "wrapper". Attached properties have a specialized syntax in [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)], which can be seen in several of the examples that follow. + Derived panel elements make extensive use of attached properties. An attached property is a specialized form of dependency property that does not have the conventional common language runtime (CLR) property "wrapper". Attached properties have a specialized syntax in Extensible Application Markup Language (XAML), which can be seen in several of the examples that follow. - One purpose of an attached property is to allow child elements to store unique values of a property that is actually defined by a parent element. An application of this functionality is having child elements inform the parent how they wish to be presented in the [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)], which is extremely useful for application layout. For more information, see [Attached Properties Overview](../advanced/attached-properties-overview.md). + One purpose of an attached property is to allow child elements to store unique values of a property that is actually defined by a parent element. An application of this functionality is having child elements inform the parent how they wish to be presented in the user interface (UI), which is extremely useful for application layout. For more information, see [Attached Properties Overview](../advanced/attached-properties-overview.md). ## Derived Panel Elements - Many objects derive from , but not all of them are intended for use as root layout providers. There are six defined panel classes (, , , , , and ) that are designed specifically for creating application [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)]. + Many objects derive from , but not all of them are intended for use as root layout providers. There are six defined panel classes (, , , , , and ) that are designed specifically for creating application UI. Each panel element encapsulates its own special functionality, as seen in the following table. @@ -82,7 +82,7 @@ ms.assetid: f73644af-9941-4611-8754-6d4cef03fc44 ## User Interface Panels - There are six panel classes available in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] that are optimized to support [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] scenarios: , , , , , and . These panel elements are easy to use, versatile, and extensible enough for most applications. + There are six panel classes available in UI scenarios: , , , , , and . These panel elements are easy to use, versatile, and extensible enough for most applications. Each derived element treats sizing constraints differently. Understanding how a handles constraints in either the horizontal or vertical direction can make layout more predictable. @@ -113,13 +113,13 @@ ms.assetid: f73644af-9941-4611-8754-6d4cef03fc44 #### Defining and Using a Canvas - A can be instantiated simply by using [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] or code. The following example demonstrates how to use to absolutely position content. This code produces three 100-pixel squares. The first square is red, and its top-left (*x, y*) position is specified as (0, 0). The second square is green, and its top-left position is (100, 100), just below and to the right of the first square. The third square is blue, and its top-left position is (50, 50), thus encompassing the lower-right quadrant of the first square and the upper-left quadrant of the second. Because the third square is laid out last, it appears to be on top of the other two squares—that is, the overlapping portions assume the color of the third box. + A can be instantiated simply by using Extensible Application Markup Language (XAML) or code. The following example demonstrates how to use to absolutely position content. This code produces three 100-pixel squares. The first square is red, and its top-left (*x, y*) position is specified as (0, 0). The second square is green, and its top-left position is (100, 100), just below and to the right of the first square. The third square is blue, and its top-left position is (50, 50), thus encompassing the lower-right quadrant of the first square and the upper-left quadrant of the second. Because the third square is laid out last, it appears to be on top of the other two squares—that is, the overlapping portions assume the color of the third box. [!code-csharp[CanvasOvwSample#1](~/samples/snippets/csharp/VS_Snippets_Wpf/CanvasOvwSample/CSharp/Canvas_Ovw_Sample.cs#1)] [!code-vb[CanvasOvwSample#1](~/samples/snippets/visualbasic/VS_Snippets_Wpf/CanvasOvwSample/VisualBasic/canvas_vb.vb#1)] [!code-xaml[CanvasOvwSample#1](~/samples/snippets/xaml/VS_Snippets_Wpf/CanvasOvwSample/XAML/default.xaml#1)] - The compiled application yields a new [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] that looks like this. + The compiled application yields a new UI that looks like this. ![A typical Canvas Element.](./media/panel-intro-canvas.PNG "panel_intro_canvas") @@ -129,7 +129,7 @@ ms.assetid: f73644af-9941-4611-8754-6d4cef03fc44 The element uses the attached property as set in child content elements to position content along the edges of a container. When is set to or , it positions child elements above or below each other. When is set to or , it positions child elements to the left or right of each other. The property determines the position of the final element added as a child of a . - You can use to position a group of related controls, such as a set of buttons. Alternately, you can use it to create a "paned" [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)], similar to that found in Microsoft Outlook. + You can use to position a group of related controls, such as a set of buttons. Alternately, you can use it to create a "paned" UI, similar to that found in Microsoft Outlook. #### Sizing to Content @@ -148,7 +148,7 @@ ms.assetid: f73644af-9941-4611-8754-6d4cef03fc44 [!code-vb[DockPanelOvwSample#1](~/samples/snippets/visualbasic/VS_Snippets_Wpf/DockPanelOvwSample/VisualBasic/dockpanel_vb.vb#1)] [!code-xaml[DockPanelOvwSample#1](~/samples/snippets/xaml/VS_Snippets_Wpf/DockPanelOvwSample/XAML/default.xaml#1)] - The compiled application yields a new [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] that looks like this. + The compiled application yields a new UI that looks like this. ![A typical DockPanel scenario.](./media/panel-intro-dockpanel.PNG "panel_intro_dockpanel") @@ -164,16 +164,16 @@ ms.assetid: f73644af-9941-4611-8754-6d4cef03fc44 #### Sizing Behavior of Columns and Rows - Columns and rows defined within a can take advantage of sizing in order to distribute remaining space proportionally. When is selected as the Height or Width of a row or column, that column or row receives a weighted proportion of remaining available space. This is in contrast to , which will distribute space evenly based on the size of the content within a column or row. This value is expressed as `*` or `2*` when using [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)]. In the first case, the row or column would receive one times the available space, in the second case, two times, and so on. By combining this technique to proportionally distribute space with a and value of `Stretch` it is possible to partition layout space by percentage of screen space. is the only layout panel that can distribute space in this manner. + Columns and rows defined within a can take advantage of sizing in order to distribute remaining space proportionally. When is selected as the Height or Width of a row or column, that column or row receives a weighted proportion of remaining available space. This is in contrast to , which will distribute space evenly based on the size of the content within a column or row. This value is expressed as `*` or `2*` when using Extensible Application Markup Language (XAML). In the first case, the row or column would receive one times the available space, in the second case, two times, and so on. By combining this technique to proportionally distribute space with a and value of `Stretch` it is possible to partition layout space by percentage of screen space. is the only layout panel that can distribute space in this manner. #### Defining and Using a Grid - The following example demonstrates how to build a [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] similar to that found on the Run dialog available on the Windows Start menu. + The following example demonstrates how to build a UI similar to that found on the Run dialog available on the Windows Start menu. [!code-csharp[GridRunDialog#1](~/samples/snippets/csharp/VS_Snippets_Wpf/GridRunDialog/CSharp/window1.xaml.cs#1)] [!code-vb[GridRunDialog#1](~/samples/snippets/visualbasic/VS_Snippets_Wpf/GridRunDialog/VisualBasic/grid_vb.vb#1)] - The compiled application yields a new [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] that looks like this. + The compiled application yields a new UI that looks like this. ![A typical Grid Element.](./media/avalon-run-dialog.PNG "avalon_run_dialog") @@ -205,7 +205,7 @@ ms.assetid: f73644af-9941-4611-8754-6d4cef03fc44 [!code-csharp[StackPanel_ovw2#1](~/samples/snippets/csharp/VS_Snippets_Wpf/StackPanel_ovw2/CSharp/StackPanel_Ovw_Sample2.cs#1)] [!code-vb[StackPanel_ovw2#1](~/samples/snippets/visualbasic/VS_Snippets_Wpf/StackPanel_ovw2/VisualBasic/StackPanelOvw.vb#1)] - The compiled application yields a new [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] that looks like this. + The compiled application yields a new UI that looks like this. ![A typical StackPanel element.](./media/panel-intro-stackpanel.PNG "panel_intro_stackpanel") @@ -213,7 +213,7 @@ ms.assetid: f73644af-9941-4611-8754-6d4cef03fc44 #### VirtualizingStackPanel - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] also provides a variation of the element that automatically "virtualizes" data-bound child content. In this context, the word virtualize refers to a technique by which a subset of elements are generated from a larger number of data items based upon which items are visible on-screen. It is intensive, both in terms of memory and processor, to generate a large number of UI elements when only a few may be on the screen at a given time. (through functionality provided by ) calculates visible items and works with the from an (such as or ) to only create elements for visible items. + WPF also provides a variation of the element that automatically "virtualizes" data-bound child content. In this context, the word virtualize refers to a technique by which a subset of elements are generated from a larger number of data items based upon which items are visible on-screen. It is intensive, both in terms of memory and processor, to generate a large number of UI elements when only a few may be on the screen at a given time. (through functionality provided by ) calculates visible items and works with the from an (such as or ) to only create elements for visible items. The element is automatically set as the items host for controls such as the . When hosting a data bound collection, content is automatically virtualized, as long as the content is within the bounds of a . This greatly improves performance when hosting many child items. @@ -225,7 +225,7 @@ ms.assetid: f73644af-9941-4611-8754-6d4cef03fc44 ### WrapPanel - is used to position child elements in sequential position from left to right, breaking content to the next line when it reaches the edge of its parent container. Content can be oriented horizontally or vertically. is useful for simple flowing [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] scenarios. It can also be used to apply uniform sizing to all of its child elements. + is used to position child elements in sequential position from left to right, breaking content to the next line when it reaches the edge of its parent container. Content can be oriented horizontally or vertically. is useful for simple flowing user interface (UI) scenarios. It can also be used to apply uniform sizing to all of its child elements. The following example demonstrates how to create a to display controls that wrap when they reach the edge of their container. @@ -234,7 +234,7 @@ ms.assetid: f73644af-9941-4611-8754-6d4cef03fc44 [!code-vb[WrapPanel_Intro#1](~/samples/snippets/visualbasic/VS_Snippets_Wpf/WrapPanel_Intro/VisualBasic/WrapPanel_vb.vb#1)] [!code-xaml[WrapPanel_Intro#1](~/samples/snippets/xaml/VS_Snippets_Wpf/WrapPanel_Intro/XAML/default.xaml#1)] - The compiled application yields a new [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] that looks like this. + The compiled application yields a new UI that looks like this. ![A typical WrapPanel Element.](./media/wrappanel-element.PNG "WrapPanel_Element") @@ -242,16 +242,16 @@ ms.assetid: f73644af-9941-4611-8754-6d4cef03fc44 ## Nested Panel Elements - elements can be nested within each other in order to produce complex layouts. This can prove very useful in situations where one is ideal for a portion of a [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)], but may not meet the needs of a different portion of the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)]. + elements can be nested within each other in order to produce complex layouts. This can prove very useful in situations where one is ideal for a portion of a UI, but may not meet the needs of a different portion of the UI. There is no practical limit to the amount of nesting that your application can support, however, it is generally best to limit your application to only use those panels that are actually necessary for your desired layout. In many cases, a element can be used instead of nested panels due to its flexibility as a layout container. This can increase performance in your application by keeping unnecessary elements out of the tree. - The following example demonstrates how to create a [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] that takes advantage of nested elements in order to achieve a specific layout. In this particular case, a element is used to provide [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] structure, and nested elements, a , and a are used to position child elements precisely within the parent . + The following example demonstrates how to create a UI that takes advantage of nested elements in order to achieve a specific layout. In this particular case, a element is used to provide UI structure, and nested elements, a , and a are used to position child elements precisely within the parent . [!code-csharp[Nested_Panels#1](~/samples/snippets/csharp/VS_Snippets_Wpf/Nested_Panels/CSharp/nestedpanels.cs#1)] [!code-vb[Nested_Panels#1](~/samples/snippets/visualbasic/VS_Snippets_Wpf/Nested_Panels/VisualBasic/nestedpanels.vb#1)] - The compiled application yields a new [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] that looks like this. + The compiled application yields a new UI that looks like this. ![A UI that takes advantage of nested panels.](./media/nested-panels.PNG "nested_panels") @@ -259,7 +259,7 @@ ms.assetid: f73644af-9941-4611-8754-6d4cef03fc44 ## Custom Panel Elements - While [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides an array of flexible layout controls, custom layout behaviors can also be achieved by overriding the and methods. Custom sizing and positioning can be accomplished by defining new positioning behaviors within these override methods. + While WPF provides an array of flexible layout controls, custom layout behaviors can also be achieved by overriding the and methods. Custom sizing and positioning can be accomplished by defining new positioning behaviors within these override methods. Similarly, custom layout behaviors based on derived classes (such as or ) can be defined by overriding their and methods. @@ -275,15 +275,15 @@ ms.assetid: f73644af-9941-4611-8754-6d4cef03fc44 ## Localization/Globalization Support - [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] supports a number of features that assist in the creation of localizable [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)]. + UI. All panel elements natively support the property, which can be used to dynamically re-flow content based on a user's locale or language settings. For more information, see . - The property provides a mechanism that enables application developers to anticipate the needs of localized [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)]. Using the value of this property, a parent always sizes dynamically to fit content and is not constrained by artificial height or width restrictions. + The property provides a mechanism that enables application developers to anticipate the needs of localized UI. Using the value of this property, a parent always sizes dynamically to fit content and is not constrained by artificial height or width restrictions. - , , and are all good choices for localizable [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)]. is not a good choice, however, because it positions content absolutely, making it difficult to localize. + , , and are all good choices for localizable UI. is not a good choice, however, because it positions content absolutely, making it difficult to localize. - For additional information on creating [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications with localizable user interfaces (UIs)s, see the [Use Automatic Layout Overview](../advanced/use-automatic-layout-overview.md). + For additional information on creating WPF applications with localizable user interfaces (UIs)s, see the [Use Automatic Layout Overview](../advanced/use-automatic-layout-overview.md). ## See also diff --git a/dotnet-desktop-guide/framework/wpf/controls/position-the-cursor-at-the-beginning-or-end-of-text.md b/dotnet-desktop-guide/framework/wpf/controls/position-the-cursor-at-the-beginning-or-end-of-text.md index 2102f9f..d273d4d 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/position-the-cursor-at-the-beginning-or-end-of-text.md +++ b/dotnet-desktop-guide/framework/wpf/controls/position-the-cursor-at-the-beginning-or-end-of-text.md @@ -16,7 +16,7 @@ ms.assetid: c771a0b8-c6b4-4240-aecd-a21d0ba51a2e This example shows how to position the cursor at the beginning or end of the text contents of a control. ## Define a TextBox control - The following [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] code describes a control and assigns it a Name. + The following Extensible Application Markup Language (XAML) code describes a control and assigns it a Name. [!code-xaml[TextBox_MiscCode#_MoveCursorXAML](~/samples/snippets/csharp/VS_Snippets_Wpf/TextBox_MiscCode/CSharp/Window1.xaml#_movecursorxaml)] diff --git a/dotnet-desktop-guide/framework/wpf/controls/richtextbox-overview.md b/dotnet-desktop-guide/framework/wpf/controls/richtextbox-overview.md index ba58df6..160bb82 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/richtextbox-overview.md +++ b/dotnet-desktop-guide/framework/wpf/controls/richtextbox-overview.md @@ -12,7 +12,7 @@ ms.assetid: c94548b2-c1e9-4b62-b10c-dd8740eb23d8 --- # RichTextBox Overview -The control enables you to display or edit flow content including paragraphs, images, tables, and more. This topic introduces the class and provides examples of how to use it in both [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] and C#. +The control enables you to display or edit flow content including paragraphs, images, tables, and more. This topic introduces the class and provides examples of how to use it in both Extensible Application Markup Language (XAML) and C#. diff --git a/dotnet-desktop-guide/framework/wpf/controls/scrollviewer-overview.md b/dotnet-desktop-guide/framework/wpf/controls/scrollviewer-overview.md index ff9a763..87c5079 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/scrollviewer-overview.md +++ b/dotnet-desktop-guide/framework/wpf/controls/scrollviewer-overview.md @@ -13,13 +13,13 @@ ms.assetid: 94a13b94-cfdf-4b12-a1aa-90cb50c6e9b9 --- # ScrollViewer Overview -Content within a user interface is often larger than a computer screen's display area. The control provides a convenient way to enable scrolling of content in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] applications. This topic introduces the element and provides several usage examples. +Content within a user interface is often larger than a computer screen's display area. The control provides a convenient way to enable scrolling of content in Windows Presentation Foundation (WPF) applications. This topic introduces the element and provides several usage examples. ## The ScrollViewer Control - There are two predefined elements that enable scrolling in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications: and . The control encapsulates horizontal and vertical elements and a content container (such as a element) in order to display other visible elements in a scrollable area. You must build a custom object in order to use the element for content scrolling. However, you can use the element by itself because it is a composite control that encapsulates functionality. + There are two predefined elements that enable scrolling in WPF applications: and . The control encapsulates horizontal and vertical elements and a content container (such as a element) in order to display other visible elements in a scrollable area. You must build a custom object in order to use the element for content scrolling. However, you can use the element by itself because it is a composite control that encapsulates functionality. The control responds to both mouse and keyboard commands, and defines numerous methods with which to scroll content by predetermined increments. You can use the event to detect a change in a state. @@ -29,7 +29,7 @@ Content within a user interface is often larger than a computer screen's display ## Physical vs. Logical Scrolling - Physical scrolling is used to scroll content by a predetermined physical increment, typically by a value that is declared in pixels. Logical scrolling is used to scroll to the next item in the logical tree. Physical scrolling is the default scroll behavior for most elements. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] supports both types of scrolling. + Physical scrolling is used to scroll content by a predetermined physical increment, typically by a value that is declared in pixels. Logical scrolling is used to scroll to the next item in the logical tree. Physical scrolling is the default scroll behavior for most elements. WPF supports both types of scrolling. #### The IScrollInfo Interface diff --git a/dotnet-desktop-guide/framework/wpf/controls/textblock-overview.md b/dotnet-desktop-guide/framework/wpf/controls/textblock-overview.md index bd1580e..f304241 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/textblock-overview.md +++ b/dotnet-desktop-guide/framework/wpf/controls/textblock-overview.md @@ -10,9 +10,9 @@ helpviewer_keywords: ms.assetid: 24720bca-341a-4b03-8a6b-7a678023b10a --- # TextBlock Overview -The control provides flexible text support for [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications. The element is targeted primarily toward basic [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] scenarios that do not require more than one paragraph of text. It supports a number of properties that enable precise control of presentation, such as , , , , and . Text content can be added using the property. When used in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], content between the open and closing tag is implicitly added as the text of the element. +The control provides flexible text support for UI scenarios that do not require more than one paragraph of text. It supports a number of properties that enable precise control of presentation, such as , , , , and . Text content can be added using the property. When used in XAML, content between the open and closing tag is implicitly added as the text of the element. - A element can be instantiated very simply using [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]. + A element can be instantiated very simply using XAML. [!code-xaml[TextBlockSnip_XAML#2](~/samples/snippets/csharp/VS_Snippets_Wpf/TextBlockSnip_XAML/CS/default.xaml#2)] diff --git a/dotnet-desktop-guide/framework/wpf/controls/textblock.md b/dotnet-desktop-guide/framework/wpf/controls/textblock.md index 8f16ee1..2fa3853 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/textblock.md +++ b/dotnet-desktop-guide/framework/wpf/controls/textblock.md @@ -9,7 +9,7 @@ helpviewer_keywords: ms.assetid: ea5f7826-7a92-4de9-9eee-10ef700ce7b6 --- # TextBlock -The control provides flexible text support for [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications. The element is targeted primarily toward basic [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] scenarios that do not require more than one paragraph of text. +The control provides flexible text support for UI scenarios that do not require more than one paragraph of text. ## In This Section [TextBlock Overview](textblock-overview.md) diff --git a/dotnet-desktop-guide/framework/wpf/controls/textbox-overview.md b/dotnet-desktop-guide/framework/wpf/controls/textbox-overview.md index 045144f..a59b401 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/textbox-overview.md +++ b/dotnet-desktop-guide/framework/wpf/controls/textbox-overview.md @@ -7,7 +7,7 @@ helpviewer_keywords: ms.assetid: 1ba6dc5b-11a7-4247-9213-36c6729ee35f --- # TextBox Overview -The class enables you to display or edit unformatted text. A common use of a is editing unformatted text in a form. For example, a form asking for the user's name, phone number, etc would use controls for text input. This topic introduces the class and provides examples of how to use it in both [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] and C#. +The class enables you to display or edit unformatted text. A common use of a is editing unformatted text in a form. For example, a form asking for the user's name, phone number, etc would use controls for text input. This topic introduces the class and provides examples of how to use it in both Extensible Application Markup Language (XAML) and C#. ## TextBox or RichTextBox? @@ -43,7 +43,7 @@ The class enables you to display or edit [!code-xaml[TextBoxMiscSnippets_snip#BasicTextBoxExampleWholePage](~/samples/snippets/csharp/VS_Snippets_Wpf/TextBoxMiscSnippets_snip/csharp/basictextboxexample.xaml#basictextboxexamplewholepage)] - You can also create a that allows the user to enter multiple lines of text. For example, if your form asked for a biographical sketch of the user, you would want to use a that supports multiple lines of text. The following example shows how to use [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] to define a control that automatically expands to accommodate multiple lines of text. + You can also create a that allows the user to enter multiple lines of text. For example, if your form asked for a biographical sketch of the user, you would want to use a that supports multiple lines of text. The following example shows how to use Extensible Application Markup Language (XAML) to define a control that automatically expands to accommodate multiple lines of text. [!code-xaml[TextBox_MiscCode#_MultilineTextBoxXAML](~/samples/snippets/csharp/VS_Snippets_Wpf/TextBox_MiscCode/CSharp/Window1.xaml#_multilinetextboxxaml)] diff --git a/dotnet-desktop-guide/framework/wpf/controls/toolbar-overview.md b/dotnet-desktop-guide/framework/wpf/controls/toolbar-overview.md index 6f3ba42..0f240e8 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/toolbar-overview.md +++ b/dotnet-desktop-guide/framework/wpf/controls/toolbar-overview.md @@ -11,7 +11,7 @@ ms.assetid: a8edb32c-118d-4f31-b6e6-8899082b504b ## ToolBar Control - The control takes its name from the bar-like arrangement of buttons or other controls into a single row or column. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] controls provide an overflow mechanism which places any items that do not fit naturally within a size-constrained into a special overflow area. Also, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] controls are usually used with the related control, which provides special layout behavior as well as support for user-initiated sizing and arranging of toolbars. + The control takes its name from the bar-like arrangement of buttons or other controls into a single row or column. WPF controls provide an overflow mechanism which places any items that do not fit naturally within a size-constrained into a special overflow area. Also, WPF controls are usually used with the related control, which provides special layout behavior as well as support for user-initiated sizing and arranging of toolbars. ## Specifying the Position of ToolBars in a ToolBarTray diff --git a/dotnet-desktop-guide/framework/wpf/controls/tooltip-overview.md b/dotnet-desktop-guide/framework/wpf/controls/tooltip-overview.md index 54567d1..a670f1a 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/tooltip-overview.md +++ b/dotnet-desktop-guide/framework/wpf/controls/tooltip-overview.md @@ -35,7 +35,7 @@ A tooltip is a small pop-up window that appears when a user pauses the mouse poi [!code-xaml[GroupBoxSnippet#ToolTipString](~/samples/snippets/csharp/VS_Snippets_Wpf/GroupBoxSnippet/CS/Window1.xaml#tooltipstring)] - You can also define a tooltip as a object. The following example uses [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] to specify a object as the tooltip of a element. Note that the example specifies the by setting the property. + You can also define a tooltip as a object. The following example uses XAML to specify a object as the tooltip of a element. Note that the example specifies the by setting the property. [!code-xaml[ToolTipSimple#ToolTip](~/samples/snippets/csharp/VS_Snippets_Wpf/ToolTipSimple/CSharp/Pane1.xaml#tooltip)] diff --git a/dotnet-desktop-guide/framework/wpf/controls/treeview-overview.md b/dotnet-desktop-guide/framework/wpf/controls/treeview-overview.md index 24e518e..02aea4d 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/treeview-overview.md +++ b/dotnet-desktop-guide/framework/wpf/controls/treeview-overview.md @@ -21,7 +21,7 @@ The control provides a way to display in ## Creating a TreeView The control contains a hierarchy of controls. A control is a that has a and an collection. - If you are defining a by using [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)], you can explicitly define the content of a control and the items that make up its collection. The previous illustration demonstrates this method. + If you are defining a by using Extensible Application Markup Language (XAML), you can explicitly define the content of a control and the items that make up its collection. The previous illustration demonstrates this method. You can also specify an as a data source and then specify a and to define the content. diff --git a/dotnet-desktop-guide/framework/wpf/controls/ui-automation-of-a-wpf-custom-control.md b/dotnet-desktop-guide/framework/wpf/controls/ui-automation-of-a-wpf-custom-control.md index 23fe5d6..917153f 100644 --- a/dotnet-desktop-guide/framework/wpf/controls/ui-automation-of-a-wpf-custom-control.md +++ b/dotnet-desktop-guide/framework/wpf/controls/ui-automation-of-a-wpf-custom-control.md @@ -13,13 +13,13 @@ helpviewer_keywords: ms.assetid: 47b310fc-fbd5-4ce2-a606-22d04c6d4911 --- # UI Automation of a WPF Custom Control -[!INCLUDE[TLA#tla_uiautomation](../../../includes/tlasharptla-uiautomation-md.md)] provides a single, generalized interface that automation clients can use to examine or operate the user interfaces of a variety of platforms and frameworks. [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)] enables both quality-assurance (test) code and accessibility applications such as screen readers to examine user-interface elements and simulate user interaction with them from other code. For information about [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)] across all platforms, see Accessibility. +UI Automation enables both quality-assurance (test) code and accessibility applications such as screen readers to examine user-interface elements and simulate user interaction with them from other code. For information about UI Automation across all platforms, see Accessibility. - This topic describes how to implement a server-side UI Automation provider for a custom control that runs in a WPF application. WPF supports [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)] through a tree of peer automation objects that parallels the tree of user interface elements. Test code and applications that provide accessibility features can use automation peer objects directly (for in-process code) or through the generalized interface provided by [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)]. + This topic describes how to implement a server-side UI Automation provider for a custom control that runs in a WPF application. WPF supports UI Automation through a tree of peer automation objects that parallels the tree of user interface elements. Test code and applications that provide accessibility features can use automation peer objects directly (for in-process code) or through the generalized interface provided by UI Automation. ## Automation Peer Classes - WPF controls support [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)] through a tree of peer classes that derive from . By convention, peer class names begin with the control class name and end with "AutomationPeer". For example, is the peer class for the control class. The peer classes are roughly equivalent to [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)] control types but are specific to WPF elements. Automation code that accesses WPF applications through the [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)] interface does not use automation peers directly, but automation code in the same process space can use automation peers directly. + WPF controls support UI Automation through a tree of peer classes that derive from . By convention, peer class names begin with the control class name and end with "AutomationPeer". For example, is the peer class for the control class. The peer classes are roughly equivalent to UI Automation control types but are specific to WPF elements. Automation code that accesses WPF applications through the UI Automation interface does not use automation peers directly, but automation code in the same process space can use automation peers directly. ## Built-in Automation Peer Classes @@ -45,7 +45,7 @@ ms.assetid: 47b310fc-fbd5-4ce2-a606-22d04c6d4911 Override the method for your custom control so that it returns your provider object, which must derive directly or indirectly from . ### Override GetPattern - Automation peers simplify some implementation aspects of server-side [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)] providers, but custom control automation peers must still handle pattern interfaces. Like non-WPF providers, peers support control patterns by providing implementations of interfaces in the namespace, such as . The control pattern interfaces can be implemented by the peer itself or by another object. The peer's implementation of returns the object that supports the specified pattern. [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)] code calls the method and specifies a enumeration value. Your override of should return the object that implements the specified pattern. If your control does not have a custom implementation of a pattern, you can call the base type's implementation of to retrieve either its implementation or null if the pattern is not supported for this control type. For example, a custom NumericUpDown control can be set to a value within a range, so its [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)] peer would implement the interface. The following example shows how the peer's method is overridden to respond to a value. + Automation peers simplify some implementation aspects of server-side UI Automation providers, but custom control automation peers must still handle pattern interfaces. Like non-WPF providers, peers support control patterns by providing implementations of interfaces in the namespace, such as . The control pattern interfaces can be implemented by the peer itself or by another object. The peer's implementation of returns the object that supports the specified pattern. UI Automation code calls the method and specifies a enumeration value. Your override of should return the object that implements the specified pattern. If your control does not have a custom implementation of a pattern, you can call the base type's implementation of to retrieve either its implementation or null if the pattern is not supported for this control type. For example, a custom NumericUpDown control can be set to a value within a range, so its UI Automation peer would implement the interface. The following example shows how the peer's method is overridden to respond to a value. [!code-csharp[CustomControlNumericUpDown#GetPattern](~/samples/snippets/csharp/VS_Snippets_Wpf/CustomControlNumericUpDown/CSharp/CustomControlLibrary/NumericUpDown.cs#getpattern)] [!code-vb[CustomControlNumericUpDown#GetPattern](~/samples/snippets/visualbasic/VS_Snippets_Wpf/CustomControlNumericUpDown/visualbasic/customcontrollibrary/numericupdown.vb#getpattern)] @@ -102,11 +102,11 @@ End Class [!code-csharp[CustomControlNumericUpDown#CoreOverrides](~/samples/snippets/csharp/VS_Snippets_Wpf/CustomControlNumericUpDown/CSharp/CustomControlLibrary/NumericUpDown.cs#coreoverrides)] [!code-vb[CustomControlNumericUpDown#CoreOverrides](~/samples/snippets/visualbasic/VS_Snippets_Wpf/CustomControlNumericUpDown/visualbasic/customcontrollibrary/numericupdown.vb#coreoverrides)] - Your implementation of describes your control by returning a value. Although you can return , you should return one of the more specific control types if it accurately describes your control. A return value of requires extra work for the provider to implement [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)], and [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)] client products are unable to anticipate the control structure, keyboard interaction, and possible control patterns. + Your implementation of describes your control by returning a value. Although you can return , you should return one of the more specific control types if it accurately describes your control. A return value of requires extra work for the provider to implement UI Automation, and UI Automation client products are unable to anticipate the control structure, keyboard interaction, and possible control patterns. Implement the and methods to indicate whether your control contains data content or fulfills an interactive role in the user interface (or both). By default, both methods return `true`. These settings improve the usability of automation tools such as screen readers, which may use these methods to filter the automation tree. If your method transfers pattern handling to a subelement peer, the subelement peer's method can return false to hide the subelement peer from the automation tree. For example, scrolling in a is handled by a , and the automation peer for is returned by the method of the that is associated with the .Therefore, the method of the returns `false`, so that the does not appear in the automation tree. - Your automation peer should provide appropriate default values for your control. Note that XAML that references your control can override your peer implementations of core methods by including attributes. For example, the following XAML creates a button that has two customized [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)] properties. + Your automation peer should provide appropriate default values for your control. Note that XAML that references your control can override your peer implementations of core methods by including attributes. For example, the following XAML creates a button that has two customized UI Automation properties. ```xaml