From 6b447dbf9c00c88f4d52c1f1e51e04c076f17070 Mon Sep 17 00:00:00 2001 From: Taojunshen Date: Fri, 10 Dec 2021 02:23:36 +0800 Subject: [PATCH] 12/9/2021 AM Publish (#3982) * Add gray border * LinkFix: cpp-docs-pr (2021-11) * Clarify C4146 per VCSig list (#3923) * Clarify C4146 per VCSig list * Fix link issues. * Update enable CMake Presets * fix rel links * fix github 3528 * acrolinx * change order of example * Add version info to NMAKE macro functions * Bulk fix entity `&` part 3 * threshhold test * Eliminate even more `&` entities * Minimum Viable Phix * Once more into the `&` breech * Add Visual Studio 2022 Platform Toolset Version * Add /fpcvt compiler option docs (#3886) * Add /fpcvt compiler option docs * Fix copypasta error * Update fp conversion intrinsics, too. * Replace deleted table row * Acrolinx pass * Fix TOC issues * Add useful links to intrinsics * Updates per John Morgan, plus acrolink * Update version info * Clean up rvalue reference article * Fix to `/fpcvt` per John Morgan email * Reformat WeakRef class document. * Update Advanced prop page and C1107 * Remove unrelated change. * Minimizing entity form of & (#3916) * Initial pass minimizing on > entities (#3919) * Initial pass on > entities * Fix everything. * Try without `<` entities in title/desc * Clean up pass * Update docs/atl-mfc-shared/reference/cfiletime-class.md Co-authored-by: Tracey Torble * Update tn026-ddx-and-ddv-routines.md `DoDialogExchange` -> `DoDataExchange` * github fix 3544 * GITHUB FIX FOR #3549 * Add UWP to list of unsupported ASAN features. * Fix misnamed mt.exe options. Acrolinx all. * Attempt fpcvt simplification per John Morgan. * Fix cpp-docs 3546 * Address complaint in cpp-docs 3554 (#3950) * 17.1 Update warnings, fix cpp-docs 3563 (#3954) * 17.1 Update warnings, fix cpp-docs 3563 * fix date * Add `/Zc:externC` compiler option doc, fix 1594 * Tweaks. * Fix links, header syntax issues * Fix issues in XML Docs reference * Make list match apparently intended style * Fix broken link. * Add docs for new check Signed-off-by: Kyle Reed * fix toc * remove .md from toc title * Revert "Add docs for new linter check" * update runtime spelling * Bulk fix: remove HTML entities from yml headers (#3962) * Style and content fixes in cpp language docs * Bulk fix HTML entities in H1 (#3966) * Fix lt-gt entity pairs * Bulk fix of `<`-`>` pairs in H1 headings * Oops, deleted initial `#` * Fix two more H1 issues * update with existing .openpublishing.publish.config.json * C++ tutorial landing page, attempt 2 * Revert redirection of get-started index.yml file * Fix typo * Bulk fix `<`, `>`, and `.period;` entities * operatoroperator * `/hotpatch`: No jump to the first instruction * Update Acrolinx for main branch * Change learn about item type * Add get started TOC * fix over machine translation problems (#3977) * fix over machine translation problems * acrolinx and misses * markdown fixes Co-authored-by: TylerMSFT * Make the grammar bot happy * Fix things that look like parameters. (#3978) * Fix things that look like parameters. * Acrolinxy * Misc fixes * Other fixes * Fix typos * Acrolinx some more * [17.0] Update links to download Visual Studio (#3981) * Update links to download Visual Studio * Remove VS 2019 reference Co-authored-by: Erika Co-authored-by: opbld16 Co-authored-by: Colin Robertson Co-authored-by: opbld17 Co-authored-by: Christopher McClister Co-authored-by: PRMerger16 Co-authored-by: Laura Brenner <90344170+laurabren@users.noreply.github.com> Co-authored-by: opbld15 Co-authored-by: TylerMSFT Co-authored-by: PRMerger18 Co-authored-by: PRMerger4 Co-authored-by: PRMerger6 Co-authored-by: MohammadHadi Attarieh Co-authored-by: PRMerger15 Co-authored-by: PRMerger10 Co-authored-by: Haig MacGregor <92189915+hmacgregor1@users.noreply.github.com> Co-authored-by: Tracey Torble Co-authored-by: Waiting Co-authored-by: Tyler Whitney Co-authored-by: branh Co-authored-by: John Ellison <88344157+johne2021@users.noreply.github.com> Co-authored-by: PRMerger8 Co-authored-by: PRMerger17 Co-authored-by: Colin Cooper <72402153+v-ccolin@users.noreply.github.com> Co-authored-by: Paula Miller Co-authored-by: Kyle Reed Co-authored-by: Anna Huff <92125952+AnnaMHuff@users.noreply.github.com> Co-authored-by: Ying Hua Co-authored-by: Alex Guteniev Co-authored-by: Dennis Rea --- docs/assembler/masm/masm-for-x64-ml64-exe.md | 2 +- docs/atl/reference/ccomsafearray-class.md | 410 +++++++++--------- .../tutorials/vcperf-and-wpa.md | 6 +- docs/build/building-on-the-command-line.md | 2 +- docs/build/projects-and-build-systems-cpp.md | 2 +- .../hotpatch-create-hotpatchable-image.md | 4 +- docs/build/vscpp-step-0-installation.md | 8 +- docs/build/walkthrough-build-debug-wsl2.md | 4 +- ...compile-a-c-program-on-the-command-line.md | 2 +- ...-native-cpp-program-on-the-command-line.md | 2 +- docs/build/working-with-project-properties.md | 62 +-- docs/c-language/index.yml | 2 +- docs/c-runtime-library/outp-outpw-outpd.md | 8 +- docs/cpp/index.yml | 2 +- docs/cpp/variant-t-variant-t.md | 90 ++-- ...p-for-cross-platform-mobile-development.md | 2 +- ...ints-on-generic-type-parameters-cpp-cli.md | 36 +- docs/extensions/generic-functions-cpp-cli.md | 48 +- .../property-cpp-component-extensions.md | 86 ++-- ...-studio-ide-for-cpp-desktop-development.md | 18 +- docs/mfc/derived-window-classes.md | 50 +-- docs/mfc/dialog-boxes-in-ole.md | 38 +- .../class-factories-and-licensing.md | 68 +-- ...bonquickaccesstoolbardefaultstate-class.md | 54 +-- docs/mfc/standard-commands.md | 30 +- docs/windows/attributes/idl-module.md | 54 +-- 26 files changed, 535 insertions(+), 555 deletions(-) diff --git a/docs/assembler/masm/masm-for-x64-ml64-exe.md b/docs/assembler/masm/masm-for-x64-ml64-exe.md index e204ecef2b1..95c7e531492 100644 --- a/docs/assembler/masm/masm-for-x64-ml64-exe.md +++ b/docs/assembler/masm/masm-for-x64-ml64-exe.md @@ -7,7 +7,7 @@ ms.assetid: 89059103-f372-4968-80ea-0c7f90bb9c91 --- # MASM for x64 (ml64.exe) -Visual Studio includes both 32-bit and 64-bit hosted versions of MASM (the Microsoft Macro Assembler) to target x64 code. Named ml64.exe, it's the assembler that accepts x64 assembler language. The MASM command-line tools are installed when you choose a C++ workload during Visual Studio installation. The MASM tools aren't available as a separate download. For instructions on how to download and install a copy of Visual Studio, see [Install Visual Studio](/visualstudio/install/install-visual-studio). If you only want the command-line tools, not the full IDE, download the [Build Tools for Visual Studio](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2019). +Visual Studio includes both 32-bit and 64-bit hosted versions of MASM (the Microsoft Macro Assembler) to target x64 code. Named ml64.exe, it's the assembler that accepts x64 assembler language. The MASM command-line tools are installed when you choose a C++ workload during Visual Studio installation. The MASM tools aren't available as a separate download. For instructions on how to download and install a copy of Visual Studio, see [Install Visual Studio](/visualstudio/install/install-visual-studio). If you only want the command-line tools, not the full IDE, download the [Build Tools for Visual Studio](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022). To use ml64.exe on the command line, start a developer command prompt for x64 targets. A developer command prompt sets the required path and other environment variables. For information on how to start a developer command prompt, see [Build C/C++ code on the command line](../../build/building-on-the-command-line.md). diff --git a/docs/atl/reference/ccomsafearray-class.md b/docs/atl/reference/ccomsafearray-class.md index 79187fb155a..df693cce9ad 100644 --- a/docs/atl/reference/ccomsafearray-class.md +++ b/docs/atl/reference/ccomsafearray-class.md @@ -6,20 +6,20 @@ f1_keywords: ["CComSafeArray", "ATLSAFE/ATL::CComSafeArray", "ATLSAFE/ATL::CComS helpviewer_keywords: ["CComSafeArray class"] ms.assetid: ee349aef-33db-4c85-bd08-5d86a3c9d53a --- -# CComSafeArray Class +# `CComSafeArray` Class This class is a wrapper for the `SAFEARRAY` structure. ## Syntax -``` +```cpp template ::type> class CComSafeArray ``` -#### Parameters +### Parameters -*T*
+*`T`*\ The type of data to be stored in the array. ## Members @@ -28,76 +28,76 @@ The type of data to be stored in the array. |Name|Description| |----------|-----------------| -|[CComSafeArray::CComSafeArray](#ccomsafearray)|The constructor.| -|[CComSafeArray::~CComSafeArray](#dtor)|The destructor.| +|[`CComSafeArray::CComSafeArray`](#ccomsafearray)|The constructor.| +|[`CComSafeArray::~CComSafeArray`](#dtor)|The destructor.| ### Public Methods |Name|Description| |----------|-----------------| -|[CComSafeArray::Add](#add)|Adds one or more elements, or a `SAFEARRAY` structure, to a `CComSafeArray`.| -|[CComSafeArray::Attach](#attach)|Attaches a `SAFEARRAY` structure to a `CComSafeArray` object.| -|[CComSafeArray::CopyFrom](#copyfrom)|Copies the contents of a `SAFEARRAY` structure into the `CComSafeArray` object.| -|[CComSafeArray::CopyTo](#copyto)|Creates a copy of the `CComSafeArray` object.| -|[CComSafeArray::Create](#create)|Creates a `CComSafeArray` object.| -|[CComSafeArray::Destroy](#destroy)|Destroys a `CComSafeArray` object.| -|[CComSafeArray::Detach](#detach)|Detaches a `SAFEARRAY` from a `CComSafeArray` object.| -|[CComSafeArray::GetAt](#getat)|Retrieves a single element from a single-dimensional array.| -|[CComSafeArray::GetCount](#getcount)|Returns the number of elements in the array.| -|[CComSafeArray::GetDimensions](#getdimensions)|Returns the number of dimensions in the array.| -|[CComSafeArray::GetLowerBound](#getlowerbound)|Returns the lower bound for a given dimension of the array.| -|[CComSafeArray::GetSafeArrayPtr](#getsafearrayptr)|Returns the address of the `m_psa` data member.| -|[CComSafeArray::GetType](#gettype)|Returns the type of data stored in the array.| -|[CComSafeArray::GetUpperBound](#getupperbound)|Returns the upper bound for any dimension of the array.| -|[CComSafeArray::IsSizable](#issizable)|Tests if a `CComSafeArray` object can be resized.| -|[CComSafeArray::MultiDimGetAt](#multidimgetat)|Retrieves a single element from a multidimensional array.| -|[CComSafeArray::MultiDimSetAt](#multidimsetat)|Sets the value of an element in a multidimensional array.| -|[CComSafeArray::Resize](#resize)|Resizes a `CComSafeArray` object.| -|[CComSafeArray::SetAt](#setat)|Sets the value of an element in a single-dimensional array.| +|[`CComSafeArray::Add`](#add)|Adds one or more elements, or a `SAFEARRAY` structure, to a `CComSafeArray`.| +|[`CComSafeArray::Attach`](#attach)|Attaches a `SAFEARRAY` structure to a `CComSafeArray` object.| +|[`CComSafeArray::CopyFrom`](#copyfrom)|Copies the contents of a `SAFEARRAY` structure into the `CComSafeArray` object.| +|[`CComSafeArray::CopyTo`](#copyto)|Creates a copy of the `CComSafeArray` object.| +|[`CComSafeArray::Create`](#create)|Creates a `CComSafeArray` object.| +|[`CComSafeArray::Destroy`](#destroy)|Destroys a `CComSafeArray` object.| +|[`CComSafeArray::Detach`](#detach)|Detaches a `SAFEARRAY` from a `CComSafeArray` object.| +|[`CComSafeArray::GetAt`](#getat)|Retrieves a single element from a single-dimensional array.| +|[`CComSafeArray::GetCount`](#getcount)|Returns the number of elements in the array.| +|[`CComSafeArray::GetDimensions`](#getdimensions)|Returns the number of dimensions in the array.| +|[`CComSafeArray::GetLowerBound`](#getlowerbound)|Returns the lower bound for a given dimension of the array.| +|[`CComSafeArray::GetSafeArrayPtr`](#getsafearrayptr)|Returns the address of the `m_psa` data member.| +|[`CComSafeArray::GetType`](#gettype)|Returns the type of data stored in the array.| +|[`CComSafeArray::GetUpperBound`](#getupperbound)|Returns the upper bound for any dimension of the array.| +|[`CComSafeArray::IsSizable`](#issizable)|Tests if a `CComSafeArray` object can be resized.| +|[`CComSafeArray::MultiDimGetAt`](#multidimgetat)|Retrieves a single element from a multidimensional array.| +|[`CComSafeArray::MultiDimSetAt`](#multidimsetat)|Sets the value of an element in a multidimensional array.| +|[`CComSafeArray::Resize`](#resize)|Resizes a `CComSafeArray` object.| +|[`CComSafeArray::SetAt`](#setat)|Sets the value of an element in a single-dimensional array.| ### Public Operators |Name|Description| |----------|-----------------| -|[CComSafeArray::operator LPSAFEARRAY](#operator_lpsafearray)|Casts a value to a `SAFEARRAY` pointer.| -|[CComSafeArray::operator\[\]](ccomsafearray-class.md#operator_at)|Retrieves an element from the array.| -|[CComSafeArray::operator =](#operator_eq)|Assignment operator.| +|[`CComSafeArray::operator LPSAFEARRAY`](#operator_lpsafearray)|Casts a value to a `SAFEARRAY` pointer.| +|[`CComSafeArray::operator[]`](ccomsafearray-class.md#operator_at)|Retrieves an element from the array.| +|[`CComSafeArray::operator =`](#operator_eq)|Assignment operator.| ### Public Data Members |Name|Description| |----------|-----------------| -|[CComSafeArray::m_psa](#m_psa)|This data member holds the address of the `SAFEARRAY` structure.| +|[`CComSafeArray::m_psa`](#m_psa)|This data member holds the address of the `SAFEARRAY` structure.| ## Remarks -`CComSafeArray` provides a wrapper for the [SAFEARRAY Data Type](/windows/win32/api/oaidl/ns-oaidl-safearray) class, making it a simple matter to create and manage single- and multidimensional arrays of almost any of the VARIANT-supported types. +`CComSafeArray` provides a wrapper for the [`SAFEARRAY` data type](/windows/win32/api/oaidl/ns-oaidl-safearray) class, making it a simple matter to create and manage single- and multidimensional arrays of almost any of the supported `VARIANT` types. `CComSafeArray` simplifies passing arrays between processes, and in addition provides extra security by checking array index values against upper and lower bounds. The lower bound of a `CComSafeArray` can start at any user-defined value; however, arrays that are accessed through C++ should use a lower bound of 0. Other languages such as Visual Basic may use other bounding values (for example, -10 to 10). -Use [CComSafeArray::Create](#create) to create a `CComSafeArray` object, and [CComSafeArray::Destroy](#destroy) to delete it. - -A `CComSafeArray` can contain the following subset of VARIANT data types: - -|VARTYPE|Description| -|-------------|-----------------| -|VT_I1|char| -|VT_I2|short| -|VT_I4|int| -|VT_I4|long| -|VT_I8|longlong| -|VT_UI1|byte| -|VT_UI2|ushort| -|VT_UI4|uint| -|VT_UI4|ulong| -|VT_UI8|ulonglong| -|VT_R4|float| -|VT_R8|double| -|VT_DECIMAL|decimal pointer| -|VT_VARIANT|variant pointer| -|VT_CY|Currency data type| +Use [`CComSafeArray::Create`](#create) to create a `CComSafeArray` object, and [`CComSafeArray::Destroy`](#destroy) to delete it. + +A `CComSafeArray` can contain the following subset of `VARIANT` data types: + +| `VARTYPE` | Description | +|--|--| +| `VT_I1` | `char` | +| `VT_I2` | `short` | +| `VT_I4` | `int` | +| `VT_I4` | `long` | +| `VT_I8` | `longlong` | +| `VT_UI1` | `byte` | +| `VT_UI2` | `ushort` | +| `VT_UI4` | `uint` | +| `VT_UI4` | `ulong` | +| `VT_UI8` | `ulonglong` | +| `VT_R4` | `float` | +| `VT_R8` | `double` | +| `VT_DECIMAL` | decimal pointer | +| `VT_VARIANT` | variant pointer | +| `VT_CY` | Currency data type | ## Requirements @@ -107,11 +107,11 @@ A `CComSafeArray` can contain the following subset of VARIANT data types: [!code-cpp[NVC_ATL_Utilities#75](../../atl/codesnippet/cpp/ccomsafearray-class_1.cpp)] -## CComSafeArray::Add +## `CComSafeArray::Add` Adds one or more elements, or a `SAFEARRAY` structure, to a `CComSafeArray`. -``` +```cpp HRESULT Add(const SAFEARRAY* psaSrc); HRESULT Add(ULONG ulCount, const T* pT, BOOL bCopy = TRUE); HRESULT Add(const T& t, BOOL bCopy = TRUE); @@ -119,57 +119,57 @@ HRESULT Add(const T& t, BOOL bCopy = TRUE); ### Parameters -*psaSrc*
+*`psaSrc`*\ A pointer to a `SAFEARRAY` object. -*ulCount*
+*`ulCount`*\ The number of objects to add to the array. -*pT*
+*`pT`*\ A pointer to one or more objects to be added to the array. -*t*
+*`t`*\ A reference to the object to be added to the array. -*bCopy*
-Indicates whether a copy of the data should be created. The default value is TRUE. +*`bCopy`*\ +Indicates whether a copy of the data should be created. The default value is `TRUE`. -### Return Value +### Return value -Returns S_OK on success, or an error HRESULT on failure. +Returns `S_OK` on success, or an error `HRESULT` on failure. ### Remarks -The new objects are appended to the end of the existing `SAFEARRAY` object. Adding an object to a multidimensional `SAFEARRAY` object is not supported. When adding an existing array of objects, both arrays must contain elements of the same type. +The new objects are appended to the end of the existing `SAFEARRAY` object. Adding an object to a multidimensional `SAFEARRAY` object isn't supported. When adding an existing array of objects, both arrays must contain elements of the same type. -The *bCopy* flag is taken into account when elements of type BSTR or VARIANT are added to an array. The default value of TRUE ensures that a new copy is made of the data when the element is added to the array. +The *`bCopy`* flag is taken into account when elements of type `BSTR` or `VARIANT` are added to an array. The default value of `TRUE` ensures that a new copy is made of the data when the element is added to the array. -## CComSafeArray::Attach +## `CComSafeArray::Attach` Attaches a `SAFEARRAY` structure to a `CComSafeArray` object. -``` +```cpp HRESULT Attach(const SAFEARRAY* psaSrc); ``` ### Parameters -*psaSrc*
+*`psaSrc`*\ A pointer to the `SAFEARRAY` structure. -### Return Value +### Return value -Returns S_OK on success, or an error HRESULT on failure. +Returns `S_OK` on success, or an error `HRESULT` on failure. ### Remarks Attaches a `SAFEARRAY` structure to a `CComSafeArray` object, making the existing `CComSafeArray` methods available. -## CComSafeArray::CComSafeArray +## `CComSafeArray::CComSafeArray` The constructor. -``` +```cpp CComSafeArray(); CComSafeArray(const SAFEARRAYBOUND& bound); CComSafeArray(ULONG ulCount, LONG lLBound = 0); @@ -181,36 +181,36 @@ CComSafeArray(const SAFEARRAY* psaSrc); ### Parameters -*bound*
+*`bound`*\ A `SAFEARRAYBOUND` structure. -*ulCount*
+*`ulCount`*\ The number of elements in the array. -*lLBound*
+*`lLBound`*\ The lower bound value; that is, the index of the first element in the array. -*pBound*
+*`pBound`*\ A pointer to a `SAFEARRAYBOUND` structure. -*uDims*
+*`uDims`*\ The count of dimensions in the array. -*saSrc*
-A reference to a `SAFEARRAY` structure or `CComSafeArray` object. In either case the constructor uses this reference to make a copy of the array, so the array is not referenced after construction. +*`saSrc`*\ +A reference to a `SAFEARRAY` structure or `CComSafeArray` object. In either case, the constructor uses this reference to make a copy of the array, so the array isn't referenced after construction. -*psaSrc*
-A pointer to a `SAFEARRAY` structure. The constructor uses this address to make a copy of the array, so the array is not referenced after construction. +*`psaSrc`*\ +A pointer to a `SAFEARRAY` structure. The constructor uses this address to make a copy of the array, so the array is never referenced after construction. ### Remarks Creates a `CComSafeArray` object. -## CComSafeArray::~CComSafeArray +## `CComSafeArray::~CComSafeArray` The destructor. -``` +```cpp ~CComSafeArray() throw() ``` @@ -218,104 +218,104 @@ The destructor. Frees all allocated resources. -## CComSafeArray::CopyFrom +## `CComSafeArray::CopyFrom` Copies the contents of a `SAFEARRAY` structure into the `CComSafeArray` object. -``` +```cpp HRESULT CopyFrom(LPSAFEARRAY* ppArray); ``` ### Parameters -*ppArray*
+*`ppArray`*\ Pointer to the `SAFEARRAY` to copy. -### Return Value +### Return value -Returns S_OK on success, or an error HRESULT on failure. +Returns `S_OK` on success, or an error `HRESULT` on failure. ### Remarks This method copies the contents of a `SAFEARRAY` into the current `CComSafeArray` object. The existing contents of the array are replaced. -## CComSafeArray::CopyTo +## `CComSafeArray::CopyTo` Creates a copy of the `CComSafeArray` object. -``` +```cpp HRESULT CopyTo(LPSAFEARRAY* ppArray); ``` ### Parameters -*ppArray*
+*`ppArray`*\ A pointer to a location in which to create the new `SAFEARRAY`. -### Return Value +### Return value -Returns S_OK on success, or an error HRESULT on failure. +Returns `S_OK` on success, or an error `HRESULT` on failure. ### Remarks This method copies the contents of a `CComSafeArray` object into a `SAFEARRAY` structure. -## CComSafeArray::Create +## `CComSafeArray::Create` Creates a `CComSafeArray`. -``` +```cpp HRESULT Create(const SAFEARRAYBOUND* pBound, UINT uDims = 1); HRESULT Create(ULONG ulCount = 0, LONG lLBound = 0); ``` ### Parameters -*pBound*
+*`pBound`*\ A pointer to a `SAFEARRAYBOUND` object. -*uDims*
+*`uDims`*\ The number of dimensions in the array. -*ulCount*
+*`ulCount`*\ The number of elements in the array. -*lLBound*
+*`lLBound`*\ The lower bound value; that is, the index of the first element in the array. -### Return Value +### Return value -Returns S_OK on success, or an error HRESULT on failure. +Returns `S_OK` on success, or an error `HRESULT` on failure. ### Remarks A `CComSafeArray` object can be created from an existing `SAFEARRAYBOUND` structure and the number of dimensions, or by specifying the number of elements in the array and the lower bound. If the array is to be accessed from C++, the lower bound should be 0. Other languages may allow other values for the lower bound (for example, Visual Basic supports arrays with elements with a range such as -10 to 10). -## CComSafeArray::Destroy +## `CComSafeArray::Destroy` Destroys a `CComSafeArray` object. -``` +```cpp HRESULT Destroy(); ``` -### Return Value +### Return value -Returns S_OK on success, or an error HRESULT on failure. +Returns `S_OK` on success, or an error `HRESULT` on failure. ### Remarks Destroys an existing `CComSafeArray` object and all of the data it contains. -## CComSafeArray::Detach +## `CComSafeArray::Detach` Detaches a `SAFEARRAY` from a `CComSafeArray` object. -``` +```cpp LPSAFEARRAY Detach(); ``` -### Return Value +### Return value Returns a pointer to a `SAFEARRAY` object. @@ -323,37 +323,37 @@ Returns a pointer to a `SAFEARRAY` object. This method detaches the `SAFEARRAY` object from the `CComSafeArray` object. -## CComSafeArray::GetAt +## `CComSafeArray::GetAt` Retrieves a single element from a single-dimensional array. -``` +```cpp T& GetAt(LONG lIndex) const; ``` ### Parameters -*lIndex*
+*`lIndex`*\ The index number of the value in the array to return. -### Return Value +### Return value Returns a reference to the required array element. -## CComSafeArray::GetCount +## `CComSafeArray::GetCount` Returns the number of elements in the array. -``` +```cpp ULONG GetCount(UINT uDim = 0) const; ``` ### Parameters -*uDim*
+*`uDim`*\ The array dimension. -### Return Value +### Return value Returns the number of elements in the array. @@ -361,279 +361,279 @@ Returns the number of elements in the array. When used with a multidimensional array, this method will return the number of elements in a specific dimension only. -## CComSafeArray::GetDimensions +## `CComSafeArray::GetDimensions` Returns the number of dimensions in the array. -``` +```cpp UINT GetDimensions() const; ``` -### Return Value +### Return value Returns the number of dimensions in the array. -## CComSafeArray::GetLowerBound +## `CComSafeArray::GetLowerBound` Returns the lower bound for a given dimension of the array. -``` +```cpp LONG GetLowerBound(UINT uDim = 0) const; ``` ### Parameters -*uDim*
+*`uDim`*\ The array dimension for which to get the lower bound. If omitted, the default is 0. -### Return Value +### Return value Returns the lower bound. ### Remarks -If the lower bound is 0, this indicates a C-like array whose first element is element number 0. In the event of an error, for example, an invalid dimension argument, this method calls `AtlThrow` with an HRESULT describing the error. +If the lower bound is 0, this indicates a C-like array whose first element is element number 0. In the event of an error, for example, an invalid dimension argument, this method calls `AtlThrow` with an `HRESULT` describing the error. -## CComSafeArray::GetSafeArrayPtr +## `CComSafeArray::GetSafeArrayPtr` Returns the address of the `m_psa` data member. -``` +```cpp LPSAFEARRAY* GetSafeArrayPtr() throw(); ``` -### Return Value +### Return value -Returns a pointer to the [CComSafeArray::m_psa](#m_psa) data member. +Returns a pointer to the [`CComSafeArray::m_psa`](#m_psa) data member. -## CComSafeArray::GetType +## `CComSafeArray::GetType` Returns the type of data stored in the array. -``` +```cpp VARTYPE GetType() const; ``` -### Return Value +### Return value Returns the type of data stored in the array, which could be any of the following types: -|VARTYPE|Description| -|-------------|-----------------| -|VT_I1|char| -|VT_I2|short| -|VT_I4|int| -|VT_I4|long| -|VT_I8|longlong| -|VT_UI1|byte| -|VT_UI2|ushort| -|VT_UI4|uint| -|VT_UI4|ulong| -|VT_UI8|ulonglong| -|VT_R4|float| -|VT_R8|double| -|VT_DECIMAL|decimal pointer| -|VT_VARIANT|variant pointer| -|VT_CY|Currency data type| - -## CComSafeArray::GetUpperBound +| `VARTYPE` | Description | +|--|--| +| `VT_I1` | `char` | +| `VT_I2` | `short` | +| `VT_I4` | `int` | +| `VT_I4` | `long` | +| `VT_I8` | `longlong` | +| `VT_UI1` | `byte` | +| `VT_UI2` | `ushort` | +| `VT_UI4` | `uint` | +| `VT_UI4` | `ulong` | +| `VT_UI8` | `ulonglong` | +| `VT_R4` | `float` | +| `VT_R8` | `double` | +| `VT_DECIMAL` | decimal pointer | +| `VT_VARIANT` | variant pointer | +| `VT_CY` | Currency data type | + +## `CComSafeArray::GetUpperBound` Returns the upper bound for any dimension of the array. -``` +```cpp LONG GetUpperBound(UINT uDim = 0) const; ``` ### Parameters -*uDim*
+*`uDim`*\ The array dimension for which to get the upper bound. If omitted, the default is 0. -### Return Value +### Return value Returns the upper bound. This value is inclusive, the maximum valid index for this dimension. ### Remarks -In the event of an error, for example, an invalid dimension argument, this method calls `AtlThrow` with an HRESULT describing the error. +In the event of an error, for example, an invalid dimension argument, this method calls `AtlThrow` with an `HRESULT` describing the error. -## CComSafeArray::IsSizable +## `CComSafeArray::IsSizable` Tests if a `CComSafeArray` object can be resized. -``` +```cpp bool IsSizable() const; ``` -### Return Value +### Return value -Returns TRUE if the `CComSafeArray` can be resized, FALSE if it cannot. +Returns `TRUE` if the `CComSafeArray` can be resized, `FALSE` if it cannot. -## CComSafeArray::m_psa +## `CComSafeArray::m_psa` Holds the address of the `SAFEARRAY` structure accessed. -``` +```cpp LPSAFEARRAY m_psa; ``` -## CComSafeArray::MultiDimGetAt +## `CComSafeArray::MultiDimGetAt` Retrieves a single element from a multidimensional array. -``` +```cpp HRESULT MultiDimGetAt(const LONG* alIndex, T& t); ``` ### Parameters -*alIndex*
+*`alIndex`*\ Pointer to a vector of indexes for each dimension in the array. The leftmost (most significant) dimension is `alIndex[0]`. -*t*
+*`t`*\ A reference to the data returned. -### Return Value +### Return value -Returns S_OK on success, or an error HRESULT on failure. +Returns `S_OK` on success, or an error `HRESULT` on failure. -## CComSafeArray::MultiDimSetAt +## `CComSafeArray::MultiDimSetAt` Sets the value of an element in a multidimensional array. -``` +```cpp HRESULT MultiDimSetAt(const LONG* alIndex, const T& t); ``` ### Parameters -*alIndex*
-Pointer to a vector of indexes for each dimension in the array. The rightmost (least significant) dimension is `alIndex`[0]. +*`alIndex`*\ +Pointer to a vector of indexes for each dimension in the array. The rightmost (least significant) dimension is `alIndex[0]`. -*T*
+*`T`*\ Specifies the value of the new element. -### Return Value +### Return value -Returns S_OK on success, or an error HRESULT on failure. +Returns `S_OK` on success, or an error `HRESULT` on failure. ### Remarks -This is a multidimensional version of [CComSafeArray::SetAt](#setat). +This is a multidimensional version of [`CComSafeArray::SetAt`](#setat). -## CComSafeArray::operator \[\] +## `CComSafeArray::operator []` Retrieves an element from the array. -``` +```cpp T& operator[](long lindex) const; T& operator[]int nindex) const; ``` ### Parameters -*lIndex, nIndex*
+*`lIndex`*, *`nIndex`*\ The index number of the required element in the array. -### Return Value +### Return value Returns the appropriate array element. ### Remarks -Performs a similar function to [CComSafeArray::GetAt](#getat), however this operator only works with single-dimensional arrays. +Performs a similar function to [`CComSafeArray::GetAt`](#getat), however this operator only works with single-dimensional arrays. -## CComSafeArray::operator = +## `CComSafeArray::operator =` Assignment operator. -``` +```cpp ATL::CComSafeArray& operator=(const ATL::CComSafeArray& saSrc); ATL::CComSafeArray& operator=(const SAFEARRAY* psaSrc); ``` ### Parameters -*saSrc*
+*`saSrc`*\ A reference to a `CComSafeArray` object. -*psaSrc*
+*`psaSrc`*\ A pointer to a `SAFEARRAY` object. -### Return Value +### Return value Returns the type of data stored in the array. -## CComSafeArray::operator LPSAFEARRAY +## `CComSafeArray::operator LPSAFEARRAY` Casts a value to a `SAFEARRAY` pointer. -``` +```cpp operator LPSAFEARRAY() const; ``` -### Return Value +### Return value Casts a value to a `SAFEARRAY` pointer. -## CComSafeArray::Resize +## `CComSafeArray::Resize` Resizes a `CComSafeArray` object. -``` +```cpp HRESULT Resize(const SAFEARRAYBOUND* pBound); HRESULT Resize(ULONG ulCount, LONG lLBound = 0); ``` ### Parameters -*pBound*
+*`pBound`*\ A pointer to a `SAFEARRAYBOUND` structure that contains information on the number of elements and the lower bound of an array. -*ulCount*
+*`ulCount`*\ The requested number of objects in the resized array. -*lLBound*
+*`lLBound`*\ The lower bound. -### Return Value +### Return value -Returns S_OK on success, or an error HRESULT on failure. +Returns `S_OK` on success, or an error `HRESULT` on failure. ### Remarks -This method only resizes the rightmost dimension. It will not resize arrays that return `IsResizable` as FALSE. +This method only resizes the rightmost dimension. It will not resize arrays that return `IsResizable` as `FALSE`. -## CComSafeArray::SetAt +## `CComSafeArray::SetAt` Sets the value of an element in a single-dimensional array. -``` +```cpp HRESULT SetAt(LONG lIndex, const T& t, BOOL bCopy = TRUE); ``` ### Parameters -*lIndex*
+*`lIndex`*\ The index number of the array element to set. -*t*
+*`t`*\ The new value of the specified element. -*bCopy*
-Indicates whether a copy of the data should be created. The default value is TRUE. +*`bCopy`*\ +Indicates whether a copy of the data should be created. The default value is `TRUE`. -### Return Value +### Return value -Returns S_OK on success, or an error HRESULT on failure. +Returns `S_OK` on success, or an error `HRESULT` on failure. ### Remarks -The *bCopy* flag is taken into account when elements of type BSTR or VARIANT are added to an array. The default value of TRUE ensures that a new copy is made of the data when the element is added to the array. +The *`bCopy`* flag is taken into account when elements of type `BSTR` or `VARIANT` are added to an array. The default value of `TRUE` ensures that a new copy is made of the data when the element is added to the array. ## See also -[SAFEARRAY Data Type](/windows/win32/api/oaidl/ns-oaidl-safearray)
-[CComSafeArray::Create](#create)
-[CComSafeArray::Destroy](#destroy)
+[`SAFEARRAY` Data Type](/windows/win32/api/oaidl/ns-oaidl-safearray)\ +[`CComSafeArray::Create`](#create)\ +[`CComSafeArray::Destroy`](#destroy)\ [Class Overview](../../atl/atl-class-overview.md) diff --git a/docs/build-insights/tutorials/vcperf-and-wpa.md b/docs/build-insights/tutorials/vcperf-and-wpa.md index ac87f886b6c..e4bf41a1e1e 100644 --- a/docs/build-insights/tutorials/vcperf-and-wpa.md +++ b/docs/build-insights/tutorials/vcperf-and-wpa.md @@ -38,8 +38,8 @@ NOTE: Windows 8 or above is required for installing the Windows Performance Anal Viewing C++ Build Insights traces in WPA requires a special add-in. Follow these steps to install it: 1. Obtain the add-in by downloading one of the components below. You don't need to get both. Choose the one that you find most convenient. - 1. [Visual Studio 2019 version 16.6 and above](https://visualstudio.microsoft.com/downloads/), or, - 1. [C++ Build Insights NuGet package](https://www.nuget.org/packages/Microsoft.Cpp.BuildInsights/). + - Visual Studio 2019 version 16.6 and above. For the latest version, see [Visual Studio Downloads](https://visualstudio.microsoft.com/downloads/). + - [C++ Build Insights NuGet package](https://www.nuget.org/packages/Microsoft.Cpp.BuildInsights/). 1. Copy the `perf_msvcbuildinsights.dll` file into your WPA installation directory. 1. In Visual Studio 2019 version 16.6 and above, this file is located here: `C:\Program Files (x86)\Microsoft Visual Studio\{Year}\{Edition}\VC\Tools\MSVC\{Version}\bin\Host{Architecture}\{Architecture}`. @@ -57,7 +57,7 @@ Viewing C++ Build Insights traces in WPA requires a special add-in. Follow these To view C++ Build Insights data, first collect it into a trace file by following these steps: -1. Open an **x64** or **x86 Native Tools Command Prompt for VS 2019** in administrator mode. (Right-click the Start menu item and choose **More** > **Run as administrator**.) +1. Open an **x64** or **x86 Native Tools Command Prompt for VS** in administrator mode. (Right-click the Start menu item and choose **More** > **Run as administrator**.) 1. Choose **x64** if you have a 64-bit version of Windows. Otherwise, choose **x86**. 1. In the command prompt window, enter this command: diff --git a/docs/build/building-on-the-command-line.md b/docs/build/building-on-the-command-line.md index 9be16d1ec9c..f44936dd0bc 100644 --- a/docs/build/building-on-the-command-line.md +++ b/docs/build/building-on-the-command-line.md @@ -17,7 +17,7 @@ You can build C and C++ applications on the command line by using tools that are ::: moniker range=">=msvc-160" -If you've installed Visual Studio and a C++ workload, you have all the command-line tools. For information on how to install C++ and Visual Studio, see [Install C++ support in Visual Studio](vscpp-step-0-installation.md). If you only want the command-line toolset, download the [Build Tools for Visual Studio](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2019). When you run the downloaded executable, it updates and runs the Visual Studio Installer. To install only the tools you need for C++ development, select the **Desktop development with C++** workload. You can select optional libraries and toolsets to include under **Installation details**. To build code by using the Visual Studio 2015 or 2017 toolsets, select the optional MSVC v140 or MSVC v141 build tools. When you're satisfied with your selections, choose **Install**. +If you've installed Visual Studio and a C++ workload, you have all the command-line tools. For information on how to install C++ and Visual Studio, see [Install C++ support in Visual Studio](vscpp-step-0-installation.md). If you only want the command-line toolset, download the [Build Tools for Visual Studio](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022). When you run the downloaded executable, it updates and runs the Visual Studio Installer. To install only the tools you need for C++ development, select the **Desktop development with C++** workload. You can select optional libraries and toolsets to include under **Installation details**. To build code by using the Visual Studio 2015, 2017, or 2019 toolsets, select the optional MSVC v140, v141, or v142 build tools. When you're satisfied with your selections, choose **Install**. ::: moniker-end ::: moniker range="<=msvc-150" diff --git a/docs/build/projects-and-build-systems-cpp.md b/docs/build/projects-and-build-systems-cpp.md index 4b2068e8bc1..156cd4acfd8 100644 --- a/docs/build/projects-and-build-systems-cpp.md +++ b/docs/build/projects-and-build-systems-cpp.md @@ -23,7 +23,7 @@ Basic C++ compilation involves three main steps: ## The MSVC toolset -The Microsoft C++ compiler, linker, standard libraries, and related utilities make up the MSVC compiler toolset (also called a toolchain or "build tools"). These are included in Visual Studio. You can also download and use the toolset as a free standalone package from [Build Tools for Visual Studio 2019 download](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2019). +The Microsoft C++ compiler, linker, standard libraries, and related utilities make up the MSVC compiler toolset (also called a toolchain or "build tools"). These are included in Visual Studio. You can also download and use the command-line toolset as a free standalone package. For more information, see [Build Tools for Visual Studio](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022) on the Visual Studio Downloads page. You can build simple programs by invoking the MSVC compiler (cl.exe) directly from the command line. The following command accepts a single source code file, and invokes cl.exe to build an executable called *hello.exe*: diff --git a/docs/build/reference/hotpatch-create-hotpatchable-image.md b/docs/build/reference/hotpatch-create-hotpatchable-image.md index 2930f364f74..ecd2b6467e5 100644 --- a/docs/build/reference/hotpatch-create-hotpatchable-image.md +++ b/docs/build/reference/hotpatch-create-hotpatchable-image.md @@ -1,7 +1,7 @@ --- description: "Learn more about: /hotpatch (Create Hotpatchable Image)" title: "/hotpatch (Create Hotpatchable Image)" -ms.date: "11/12/2018" +ms.date: "12/7/2021" f1_keywords: ["/hotpatch", "VC.Project.VCCLCompilerTool.CreateHotpatchableImage"] helpviewer_keywords: ["hot patching", "-hotpatch compiler option [C++]", "/hotpatch compiler option [C++]", "hotpatching"] ms.assetid: aad539b6-c053-4c78-8682-853d98327798 @@ -18,7 +18,7 @@ Prepares an image for hot patching. ## Remarks -When **/hotpatch** is used in a compilation, the compiler ensures that first instruction of each function is at least two bytes, which is required for hot patching. +When **/hotpatch** is used in a compilation, the compiler ensures that the first instruction of each function is at least two bytes, and no jump within the function goes to the first instruction. These conditions are required for hot patching. To complete the preparation for making an image hotpatchable, after you use **/hotpatch** to compile, you must use [/FUNCTIONPADMIN (Create Hotpatchable Image)](functionpadmin-create-hotpatchable-image.md) to link. When you compile and link an image by using one invocation of cl.exe, **/hotpatch** implies **/functionpadmin**. diff --git a/docs/build/vscpp-step-0-installation.md b/docs/build/vscpp-step-0-installation.md index 2cb19c7c0f9..f36a65840b9 100644 --- a/docs/build/vscpp-step-0-installation.md +++ b/docs/build/vscpp-step-0-installation.md @@ -144,10 +144,10 @@ For questions about running previous versions of Visual Studio side by side with ### Step 2 - Download Visual Studio -Next, download the Visual Studio bootstrapper file. To do so, choose the following button to go to the Visual Studio download page. Select the edition of Visual Studio that you want and choose the **Free trial** or **Free download** button. +Next, download the Visual Studio bootstrapper file. To do so, choose the following button to go to the Visual Studio download page. Choose the Download button, then you can select the edition of Visual Studio that you want. > [!div class="button"] - > [Download Visual Studio](https://visualstudio.microsoft.com/downloads/?utm_medium=microsoft&utm_source=docs.microsoft.com&utm_campaign=button+cta&utm_content=download+vs2019+rc) + > [Download Visual Studio 2019](https://visualstudio.microsoft.com/vs/older-downloads/#visual-studio-2019-and-other-products) ### Step 3 - Install the Visual Studio installer @@ -241,7 +241,7 @@ For details on the disk space and operating system requirements, see [Visual Stu ### Download and install -1. To download the latest Visual Studio 2017 installer for Windows, go to the Microsoft Visual Studio [Older downloads](https://www.visualstudio.com/vs/older-downloads/) page. Expand the **2017** section, and choose the **Download** button. +1. To download the latest Visual Studio 2017 installer for Windows, go to the Microsoft Visual Studio [Older downloads](https://visualstudio.microsoft.com/vs/older-downloads/#visual-studio-2017-and-other-products) page. Expand the **2017** section, and choose the **Download** button. >[!Tip] > The Community edition is for individual developers, classroom learning, academic research, and open source development. For other uses, install Visual Studio 2017 Professional or Visual Studio 2017 Enterprise. @@ -280,7 +280,7 @@ For details on the disk space and operating system requirements, see [Visual Stu ## Visual Studio 2015 Installation -To install Visual Studio 2015, go to the Microsoft Visual Studio [Older downloads](https://www.visualstudio.com/vs/older-downloads/) page. Expand the **2015** section, and choose the **Download** button. Run the downloaded setup program and choose **Custom installation** and then choose the C++ component. To add C and C++ support to an existing Visual Studio 2015 installation, click on the Windows Start button and type **Add Remove Programs**. Open the program from the results list and then find your Visual Studio 2015 installation in the list of installed programs. Double-click it, then choose **Modify** and select the Visual C++ components to install. +To install Visual Studio 2015, go to the Microsoft Visual Studio [Older downloads](https://visualstudio.microsoft.com/vs/older-downloads/#visual-studio-2015-and-other-products) page. Expand the **2015** section, and choose the **Download** button. Run the downloaded setup program and choose **Custom installation** and then choose the C++ component. To add C and C++ support to an existing Visual Studio 2015 installation, click on the Windows Start button and type **Add Remove Programs**. Open the program from the results list and then find your Visual Studio 2015 installation in the list of installed programs. Double-click it, then choose **Modify** and select the Visual C++ components to install. In general, we highly recommend that you use the latest version of Visual Studio even if you need to compile your code using the Visual Studio 2015 compiler. For more information, see [Use native multi-targeting in Visual Studio to build old projects](../porting/use-native-multi-targeting.md). diff --git a/docs/build/walkthrough-build-debug-wsl2.md b/docs/build/walkthrough-build-debug-wsl2.md index d7483477531..93ec4961f3f 100644 --- a/docs/build/walkthrough-build-debug-wsl2.md +++ b/docs/build/walkthrough-build-debug-wsl2.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["wsl2", "cmake", "linux", "build"] --- # Walkthrough: Build and debug C++ with WSL 2 and Visual Studio 2022 -Visual Studio 2022 introduces a native C++ toolset for Windows Subsystem for Linux version 2 (WSL 2) development. This toolset is available now in [Visual Studio 2022 version 17.0 Preview 2](https://visualstudio.microsoft.com/vs/preview/vs2022/) or higher. +Visual Studio 2022 introduces a native C++ toolset for Windows Subsystem for Linux version 2 (WSL 2) development. This toolset is available now in [Visual Studio 2022 version 17.0](https://visualstudio.microsoft.com/downloads/) or higher. WSL 2 is the new, recommended version of the [Windows Subsystem for Linux](/windows/wsl/about) (WSL). It provides better Linux file system performance, GUI support, and full system call compatibility. Visual Studio’s WSL 2 toolset allows you to use Visual Studio to build and debug C++ code on WSL 2 distros without adding a SSH connection. You can already build and debug C++ code on WSL 1 distros using the native [WSL 1 toolset](https://devblogs.microsoft.com/cppblog/c-with-visual-studio-2019-and-windows-subsystem-for-linux-wsl/) introduced in Visual Studio 2019 version 16.1. @@ -129,6 +129,6 @@ In most cases, it’s best to use the WSL 2 toolset with WSL 2 distributions bec ## See also [Video: Debug C++ with WSL 2 Distributions and Visual Studio 2022](https://youtu.be/IKI2w75aAow)\ -[Download Visual Studio 2022 preview](https://visualstudio.microsoft.com/vs/preview/)\ +[Download Visual Studio 2022](https://visualstudio.microsoft.com/downloads/)\ [Create a CMake Linux project in Visual Studio](../linux/cmake-linux-project.md)\ [Tutorial: Debug a CMake project on a remote Windows machine](cmake-remote-debugging.md) \ No newline at end of file diff --git a/docs/build/walkthrough-compile-a-c-program-on-the-command-line.md b/docs/build/walkthrough-compile-a-c-program-on-the-command-line.md index 71df112c980..548923ec710 100644 --- a/docs/build/walkthrough-compile-a-c-program-on-the-command-line.md +++ b/docs/build/walkthrough-compile-a-c-program-on-the-command-line.md @@ -18,7 +18,7 @@ To complete this walkthrough, you must have installed either Visual Studio and t Visual Studio is a powerful integrated development environment that supports a full-featured editor, resource managers, debuggers, and compilers for many languages and platforms. For information on these features and how to download and install Visual Studio, including the free Visual Studio Community edition, see [Install Visual Studio](/visualstudio/install/install-visual-studio). -The Build Tools for Visual Studio version of Visual Studio installs only the command-line toolset, the compilers, tools, and libraries you need to build C and C++ programs. It's perfect for build labs or classroom exercises and installs relatively quickly. To install only the command-line toolset, download Build Tools for Visual Studio from the [Visual Studio downloads](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2019) page and run the installer. In the Visual Studio installer, select the **C++ build tools** workload, and choose **Install**. +The Build Tools for Visual Studio version of Visual Studio installs only the command-line toolset, the compilers, tools, and libraries you need to build C and C++ programs. It's perfect for build labs or classroom exercises and installs relatively quickly. To install only the command-line toolset, download Build Tools for Visual Studio from the [Visual Studio downloads](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022) page and run the installer. In the Visual Studio installer, select the **C++ build tools** workload, and choose **Install**. Before you can build a C or C++ program on the command line, you must verify that the tools are installed, and that you can access them from the command line. Visual C++ has complex requirements for the command-line environment to find the tools, headers, and libraries it uses. **You can't use Visual C++ in a plain command prompt window** without some preparation. You need a *developer command prompt* window, which is a regular command prompt window that has all the required environment variables set. Fortunately, Visual C++ installs shortcuts for you to launch developer command prompts that have the environment set up for command line builds. Unfortunately, the names of the developer command prompt shortcuts and where they're located are different in almost every version of Visual C++ and on different versions of Windows. Your first walkthrough task is to find the right shortcut to use. diff --git a/docs/build/walkthrough-compiling-a-native-cpp-program-on-the-command-line.md b/docs/build/walkthrough-compiling-a-native-cpp-program-on-the-command-line.md index 84d62671104..03f3e090ca3 100644 --- a/docs/build/walkthrough-compiling-a-native-cpp-program-on-the-command-line.md +++ b/docs/build/walkthrough-compiling-a-native-cpp-program-on-the-command-line.md @@ -20,7 +20,7 @@ To complete this walkthrough, you must have installed either Visual Studio and t Visual Studio is an *integrated development environment* (IDE). It supports a full-featured editor, resource managers, debuggers, and compilers for many languages and platforms. Versions available include the free Visual Studio Community edition, and all can support C and C++ development. For information on how to download and install Visual Studio, see [Install C++ support in Visual Studio](vscpp-step-0-installation.md). -The Build Tools for Visual Studio installs only the command-line compilers, tools, and libraries you need to build C and C++ programs. It's perfect for build labs or classroom exercises and installs relatively quickly. To install only the command-line tools, look for Build Tools for Visual Studio on the [Visual Studio Downloads](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2019) page. +The Build Tools for Visual Studio installs only the command-line compilers, tools, and libraries you need to build C and C++ programs. It's perfect for build labs or classroom exercises and installs relatively quickly. To install only the command-line tools, look for Build Tools for Visual Studio on the [Visual Studio Downloads](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022) page. Before you can build a C or C++ program on the command line, verify that the tools are installed, and you can access them from the command line. Visual C++ has complex requirements for the command-line environment to find the tools, headers, and libraries it uses. **You can't use Visual C++ in a plain command prompt window** without doing some preparation. Fortunately, Visual C++ installs shortcuts for you to launch a developer command prompt that has the environment set up for command line builds. Unfortunately, the names of the developer command prompt shortcuts and where they're located are different in almost every version of Visual C++ and on different versions of Windows. Your first walkthrough task is finding the right one to use. diff --git a/docs/build/working-with-project-properties.md b/docs/build/working-with-project-properties.md index c724c7115c8..1e6c5ddd665 100644 --- a/docs/build/working-with-project-properties.md +++ b/docs/build/working-with-project-properties.md @@ -7,19 +7,19 @@ ms.assetid: 9b0d6f8b-7d4e-4e61-aa75-7d14944816cd --- # Set compiler and build properties -In the IDE, all information that is needed to build a project is exposed as *properties*. This information includes the application name, extension (such as DLL, LIB, EXE), compiler options, linker options, debugger settings, custom build steps, and many other things. Typically, you use *property pages* to view and modify these properties. To access the property pages, choose **Project** > **_projectname_ Properties** from the main menu, or right-click on the project node in **Solution Explorer** and choose **Properties**. +In the IDE, all information that's needed to build a project is exposed as *properties*. This information includes the application name, extension (such as DLL, LIB, EXE), compiler options, linker options, debugger settings, custom build steps, and many other things. Typically, you use *property pages* to view and modify these properties. To access the property pages, choose **Project** > **_project-name_ Properties** from the main menu, or right-click on the project node in **Solution Explorer** and choose **Properties**. ## Default properties -When you create a project, the system assigns values for various properties. The defaults vary somewhat depending on the kind of project and what options you choose in the app wizard. For example, an ATL project has properties related to MIDL files, but these are absent in a basic console application. The default properties are shown in the General pane in the Property Pages: +When you create a project, the system assigns values for various properties. The defaults vary somewhat depending on the kind of project and what options you choose in the app wizard. For example, an ATL project has properties related to MIDL files, but these properties are absent in a basic console application. The default properties are shown in the General pane in the Property Pages: ![Screenshot of the Property Pages dialog with the Project Defaults properties highlighted.](media/visual-c---project-defaults.png "Visual C++ project Defaults") ## Applying properties to build configurations and target platforms -Some properties, such as the application name, apply to all build variations, regardless of the target platform or whether it is a debug or release build. But most properties are configuration-dependent. This is because the compiler has to know what specific platform the program will run on and what specific compiler options to use in order to generate the correct code. Therefore, when you set a property, it is important to pay attention to which configuration and platform the new value should apply to. Should it apply only to Debug Win32 builds, or should it also apply to Debug ARM and Debug x64? For example, the **Optimization** property, by default, is set to **Maximize Speed (/O2)** in a Release configuration, but is disabled in the Debug configuration. +Some properties, such as the application name, apply to all build variations and target platforms, whether it's a debug or release build. But most properties are configuration-dependent. To generate the correct code, the compiler has to know both the specific platform the program will run on and which specific compiler options to use. So when you set a property, it's important to pay attention to which configuration and platform the new value should apply to. Should it apply only to Debug Win32 builds, or should it also apply to Debug ARM64 and Debug x64? For example, the **Optimization** property, by default, is set to **Maximize Speed (/O2)** in a Release configuration, but it's disabled in the Debug configuration. -The property pages are designed so that you can always see, and if necessary modify, which configuration and platform a property value should apply to. The following illustration shows the property pages with the configuration and platform information in the list boxes at the top. When the **Optimization** property is set here, it will apply only to Debug Win32 builds, which happens to be the active configuration, as shown by the red arrows. +You can always see and change the configuration and platform a property value should apply to. The following illustration shows the property pages with the configuration and platform information controls at the top. When the **Optimization** property is set here, it will apply only to Debug Win32 builds, the currently active configuration, as shown by the red arrows. ![Screenshot of the Property Pages dialog showing property values for the currently active configuration.](media/visual-c---property-pages-showing-active-configuration.png "Visual C++ Property Pages showing active configuration") @@ -29,9 +29,9 @@ The following illustration shows the same project property page, but the configu ## Target platforms -*Target platform* refers to the kind of device and/or operating system that the executable will run on. You can build a project for more than one platform. The available target platforms for C++ projects depend on the kind of project; they include but are not limited to Win32, x64, ARM, Android, and iOS. The **x86** target platform that you might see in **Configuration Manager** is identical to **Win32** in native C++ projects. Win32 means 32-bit Windows and **x64** means 64-bit Windows. For more information about these two platforms, see [Running 32-bit applications](/windows/win32/WinProg64/running-32-bit-applications). +*Target platform* refers to the kind of device and operating system that the executable will run on. You can build a project for more than one platform. The available target platforms for C++ projects depend on the kind of project. They include but aren't limited to Win32, x64, ARM, ARM64, Android, and iOS. The **x86** target platform that you might see in **Configuration Manager** is identical to **Win32** in native C++ projects. Win32 means 32-bit Windows and **x64** means 64-bit Windows. For more information about these two platforms, see [Running 32-bit applications](/windows/win32/WinProg64/running-32-bit-applications). -The **Any CPU** target platform value that you might see in **Configuration Manager** has no effect on native C++ projects; it is relevant for C++/CLI and other .NET project types. For more information, see [/CLRIMAGETYPE (Specify Type of CLR Image)](reference/clrimagetype-specify-type-of-clr-image.md). +The **Any CPU** target platform value that you might see in **Configuration Manager** has no effect on native C++ projects. It's only relevant for C++/CLI and other .NET project types. For more information, see [`/CLRIMAGETYPE` (Specify Type of CLR Image)](reference/clrimagetype-specify-type-of-clr-image.md). For more information about setting properties for a Debug build, see: @@ -42,37 +42,37 @@ For more information about setting properties for a Debug build, see: ## C++ compiler and linker options -C++ compiler and linker options are located under the **C/C++** and **Linker** nodes in the left pane under **Configuration Properties**. These translate directly to command-line options that will be passed to the compiler. To read documentation about a specific option, select the option in the center pane and press **F1**. Or, you can browse documentation for all the options at [MSVC Compiler Options](reference/compiler-options.md) and [MSVC Linker Options](reference/linker-options.md). +C++ compiler and linker options are located under the **C/C++** and **Linker** nodes in the left pane under **Configuration Properties**. These options translate directly to command-line options that will be passed to the compiler. To read documentation about a specific option, select the option in the center pane and press **F1**. Or, you can browse documentation for all the options at [MSVC compiler options](reference/compiler-options.md) and [MSVC linker options](reference/linker-options.md). -The **Property Pages** dialog box shows only the property pages that are relevant to the current project. For example, if the project does not have an .idl file, the MIDL property page is not displayed. For more information about the setting on each property pages, see [Property Pages (C++)](reference/property-pages-visual-cpp.md). +The **Property Pages** dialog box shows only the property pages that are relevant to the current project. For example, if the project doesn't have an *`.idl`* file, the MIDL property page isn't displayed. For more information about the settings on each property page, see [Property Pages (C++)](reference/property-pages-visual-cpp.md). ## Directory and path values -MSBuild supports the use of compile-time constants called "macros" for certain string values include directories and paths. These are exposed in the property pages, where you can refer to and modify them by using the [Property Editor](#property_editor). +MSBuild supports the use of compile-time constants for certain string values, such as include directories and paths, called *macros*. A macro can refer to a value that's defined by Visual Studio or the MSBuild system, or to a user-defined value. Macros look like `$(macro-name)` or `%(item-macro-name)`. They're exposed in the property pages, where you can refer to and modify them by using the [Property Editor](#property_editor). Use macros instead of hard-coded values such as directory paths. Macros make it easier to share property settings between machines and between versions of Visual Studio. And, you can better ensure that your project settings participate correctly in [property inheritance](project-property-inheritance.md). -The following illustration shows the property pages for a Visual Studio C++ project. In the left pane, the **VC++ Directories** *rule* is selected, and the right pane lists the properties that are associated with that rule. The `$(...)` values are called *macros*. A *macro* is a compile-time constant that can refer to a value that is defined by Visual Studio or the MSBuild system, or to a user-defined value. By using macros instead of hard-coded values such as directory paths, you can more easily share property settings between machines and between versions of Visual Studio, and you can better ensure that your project settings participate correctly in [property inheritance](project-property-inheritance.md). +The following illustration shows the property pages for a Visual Studio C++ project. In the left pane, the **VC++ Directories** *rule* is selected, and the right pane lists the properties that are associated with that rule. The property values are often macros, such as `$(VC_SourcePath)`: ![Screenshot of the Property Pages dialog showing the VC project directories.](media/project_property_pages_vc.png "Project_Property_Pages_VC") -You can use the Property Editor to view the values of all available macros. +You can use the [Property Editor](#property_editor) to view the values of all available macros. ### Predefined macros -*global macros*
-Applies to all items in a project configuration. Has the syntax `$(name)`. An example of a global macro is `$(VCInstallDir)`, which stores the root directory of your Visual Studio installation. A global macro corresponds to a `PropertyGroup` in MSBuild. +- **Global macros**:\ + Global macros apply to all items in a project configuration. A global macro has the syntax `$(name)`. An example of a global macro is `$(VCInstallDir)`, which stores the root directory of your Visual Studio installation. A global macro corresponds to a `PropertyGroup` in MSBuild. -*item macros*
-Has the syntax `%(name)`. For a file, an item macro applies only to that file—for example, you can use `%(AdditionalIncludeDirectories)` to specify include directories that apply only to a particular file. This kind of item macro corresponds to an `ItemGroup` metadata in MSBuild. When it's used in the context of a project configuration, an item macro applies to all files of a certain type. For example, the C/C++ **Preprocessor Definitions** configuration property can take a `%(PreprocessorDefinitions)` item macro that applies to all .cpp files in the project. This kind of item macro corresponds to an `ItemDefinitionGroup` metadata in MSBuild. For more information, see [Item Definitions](/visualstudio/msbuild/item-definitions). +- **Item macros**\ + Item macros have the syntax `%(name)`. For a file, an item macro applies only to that file—for example, you can use `%(AdditionalIncludeDirectories)` to specify include directories that apply only to a particular file. This kind of item macro corresponds to an `ItemGroup` metadata in MSBuild. When it's used in the context of a project configuration, an item macro applies to all files of a certain type. For example, the C/C++ **Preprocessor Definitions** configuration property can take a `%(PreprocessorDefinitions)` item macro that applies to all .cpp files in the project. This kind of item macro corresponds to an `ItemDefinitionGroup` metadata in MSBuild. For more information, see [Item Definitions](/visualstudio/msbuild/item-definitions). ### User-defined macros You can create *user-defined macros* to use as variables in project builds. For example, you could create a user-defined macro that provides a value to a custom build step or a custom build tool. A user-defined macro is a name/value pair. In a project file, use the `$(name)` notation to access the value. -A user-defined macro is stored in a property sheet. If your project does not already contain a property sheet, you can create one by following the steps under [Share or reuse Visual Studio project settings](create-reusable-property-configurations.md). +A user-defined macro is stored in a property sheet. If your project doesn't already contain a property sheet, you can create one by following the steps under [Share or reuse Visual Studio project settings](create-reusable-property-configurations.md). #### To create a user-defined macro -1. Open the **Property Manager** window. (On the menu bar, choose **View** > **Property Manager** or **View** > **Other Windows** > **Property Manager**.) Open the shortcut menu for a property sheet (its name ends in .user) and then choose **Properties**. The **Property Pages** dialog box for that property sheet opens. +1. Open the **Property Manager** window. (On the menu bar, choose **View** > **Property Manager** or **View** > **Other Windows** > **Property Manager**.) Open the shortcut menu for a property sheet (its name ends in *`.user`*) and then choose **Properties**. The **Property Pages** dialog box for that property sheet opens. 1. In the left pane of the dialog box, select **User Macros**. In the right pane, choose the **Add Macro** button to open the **Add User Macro** dialog box. @@ -84,30 +84,30 @@ You can use the Property Editor to modify certain string properties and select m ![A property drop-down control is used to access the Property Editor.](media/property_editor_dropdown.png "Property Editor dropdown") -In the Property Editor, you can choose the **Macros** button to view the available macros and their current values. The following illustration shows the Property Editor for the **Additional Include Directories** property after the **Macros** button was chosen. When the **Inherit from parent or project defaults** check box is selected and you add a new value, it is appended to any values that are currently being inherited. If you clear the check box, your new value replaces the inherited values. In most cases, leave the check box selected. +In the Property Editor, you can choose the **Macros** button to view the available macros and their current values. The following illustration shows the Property Editor for the **Additional Include Directories** property after the **Macros** button was chosen. When the **Inherit from parent or project defaults** check box is selected and you add a new value, it's appended to any values that are currently being inherited. If you clear the check box, your new value replaces the inherited values. In most cases, leave the check box selected. ![The Property Editor dialog for the Include Directories property.](media/propertyeditorvc.png "PropertyEditorVC") ## Add an include directory to the set of default directories -When you add an include directory to a project, it is important not to override all the default directories. The correct way to add a directory is to append the new path, for example "C:\MyNewIncludeDir\", and then to Append the **$(IncludePath)** macro to the property value. +When you add an include directory to a project, it's important not to override all the default directories. The correct way to add a directory is to append the new path, for example "`C:\MyNewIncludeDir\`", and then to Append the **`$(IncludePath)`** macro to the property value. ## Quickly browse and search all properties The **All Options** property page (under the **Configuration Properties | C/C++** node in the **Property Pages** dialog box) provides a quick way to browse and search the properties that are available in the current context. It has a special search box and a simple syntax to help you filter results: -No prefix:
+No prefix:\ Search in property names only (case-insensitive substring). -'/' or '-' :
+'`/`' or '`-`':\ Search only in compiler switches (case-insensitive prefix) -v:
+`v`:\ Search only in values (case-insensitive substring). ## Set environment variables for a build -The MSVC compiler (cl.exe) recognizes certain environment variables, specifically LIB, LIBPATH, PATH, and INCLUDE. When you build with the IDE, the properties that are set in the [VC++ Directories Property Page](reference/vcpp-directories-property-page.md) property page are used to set those environment variables. If LIB, LIBPATH, and INCLUDE values have already been set, for example by a Developer Command Prompt, they are replaced with the values of the corresponding MSBuild properties. The build then prepends the value of the VC++ Directories executable directories property to PATH. You can set a user-defined environment variable by creating a user-defined macro and then checking the box that says **Set this macro as an environment variable in the build environment**. +The MSVC compiler (cl.exe) recognizes certain environment variables, specifically `LIB`, `LIBPATH`, `PATH`, and `INCLUDE`. When you build with the IDE, the properties that are set in the [VC++ Directories Property Page](reference/vcpp-directories-property-page.md) are used to set those environment variables. If `LIB`, `LIBPATH`, and `INCLUDE` values have already been set, for example by a Developer Command Prompt, they're replaced with the values of the corresponding MSBuild properties. The build then prepends the value of the VC++ Directories executable directories property to `PATH`. You can set a user-defined environment variable by creating a user-defined macro and then checking the box that says **Set this macro as an environment variable in the build environment**. ## Set environment variables for a debugging session @@ -117,17 +117,17 @@ In the right pane, modify the **Environment** or **Merge Environment** project s ## In this section -[Share or reuse Visual Studio project settings](create-reusable-property-configurations.md)
-How to create a .props file with custom build settings that can be shared or reused. +[Share or reuse Visual Studio project settings](create-reusable-property-configurations.md)\ +How to create a *`.props`* file with custom build settings that can be shared or reused. -[Project property inheritance](project-property-inheritance.md)
-Describes the order of evaluation for the .props, .targets, .vcxproj files and environment variables in the build process. +[Project property inheritance](project-property-inheritance.md)\ +Describes the order of evaluation for the *`.props`*, *`.targets`*, *`.vcxproj`* files, and environment variables in the build process. -[Modify properties and targets without changing the project file](modify-project-properties-without-changing-project-file.md)
+[Modify properties and targets without changing the project file](modify-project-properties-without-changing-project-file.md)\ How to create temporary build settings without having to modify a project file. ## See also -[Visual Studio Projects - C++](creating-and-managing-visual-cpp-projects.md)
-[.vcxproj and .props file structure](reference/vcxproj-file-structure.md)
-[Property page XML files](reference/property-page-xml-files.md)
+[Visual Studio Projects - C++](creating-and-managing-visual-cpp-projects.md)\ +[`.vcxproj` and `.props` file structure](reference/vcxproj-file-structure.md)\ +[Property page XML files](reference/property-page-xml-files.md) diff --git a/docs/c-language/index.yml b/docs/c-language/index.yml index 083ec675270..feb5f6855ef 100644 --- a/docs/c-language/index.yml +++ b/docs/c-language/index.yml @@ -26,7 +26,7 @@ landingContent: - text: Install C/C++ support in Visual Studio url: ../build/vscpp-step-0-installation.md - text: Download only the command-line build tools - url: https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2019 + url: https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022 - linkListType: tutorial links: - text: Compile a C program on the command line diff --git a/docs/c-runtime-library/outp-outpw-outpd.md b/docs/c-runtime-library/outp-outpw-outpd.md index 02cdeec2ce0..161f457d1ef 100644 --- a/docs/c-runtime-library/outp-outpw-outpd.md +++ b/docs/c-runtime-library/outp-outpw-outpd.md @@ -10,7 +10,7 @@ f1_keywords: ["_outpw", "_outpd", "_outp", "outp", "outpw", "outpd"] helpviewer_keywords: ["outpw function", "words", "_outpd function", "outpd function", "outp function", "ports, writing bytes at", "bytes, writing to ports", "words, writing to ports", "double words", "double words, writing to ports", "_outpw function", "_outp function"] ms.assetid: c200fe22-41f6-46fd-b0be-ebb805b35181 --- -# outp, outpw, _outp, _outpw, _outpd +# `outp`, `outpw`, `_outp`, `_outpw`, `_outpd` Outputs, at a port, a byte (`outp`, `_outp`), a word (`outpw`, `_outpw`), or a double word (`_outpd`). @@ -37,10 +37,10 @@ unsigned long _outpd( ### Parameters -*port*\ +*`port`*\ Port number. -*data_byte, data_word*\ +*`data_byte`*, *`data_word`*\ Output values. ## Return Value @@ -49,7 +49,7 @@ The functions return the data output. There's no error return. ## Remarks -The `_outp`, `_outpw`, and `_outpd` functions write a byte, a word, and a double word, respectively, to the specified output port. The *port* argument can be any unsigned integer in the range 0 - 65,535. *data_byte* can be any integer in the range 0 - 255. *data_word* can be any value in the range of an integer, an unsigned short integer, and an unsigned long integer, respectively. +The `_outp`, `_outpw`, and `_outpd` functions write a byte, a word, and a double word, respectively, to the specified output port. The *`port`* argument can be any unsigned integer in the range 0 - 65,535. *`data_byte`* can be any integer in the range 0 - 255. *`data_word`* can be any value in the range of an integer, an unsigned short integer, and an unsigned long integer, respectively. Because these functions write directly to an I/O port, they can't be used in user-mode Windows code. diff --git a/docs/cpp/index.yml b/docs/cpp/index.yml index 3e765ab712d..61c7cf7a41b 100644 --- a/docs/cpp/index.yml +++ b/docs/cpp/index.yml @@ -26,7 +26,7 @@ landingContent: - text: Install C/C++ support in Visual Studio url: ../build/vscpp-step-0-installation.md - text: Download only the command-line build tools - url: https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2019 + url: https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022 - linkListType: get-started links: - text: Hello world in Visual Studio with C++ diff --git a/docs/cpp/variant-t-variant-t.md b/docs/cpp/variant-t-variant-t.md index 293aed6eca3..48f311b9eb8 100644 --- a/docs/cpp/variant-t-variant-t.md +++ b/docs/cpp/variant-t-variant-t.md @@ -6,7 +6,7 @@ f1_keywords: ["_variant_t::_variant_t"] helpviewer_keywords: ["_variant_t class [C++], constructor", "_variant_t method [C++]"] ms.assetid: a50e5b33-d4c6-4a26-8e7e-a0a25fd9895b --- -# _variant_t::_variant_t +# `_variant_t::_variant_t` **Microsoft Specific** @@ -14,7 +14,7 @@ Constructs a `_variant_t` object. ## Syntax -``` +```cpp _variant_t( ) throw( ); _variant_t( @@ -120,114 +120,114 @@ _variant_t( ) throw(); ``` -#### Parameters +### Parameters -*varSrc*
+*`varSrc`*\ A `VARIANT` object to be copied into the new `_variant_t` object. -*pVarSrc*
+*`pVarSrc`*\ Pointer to a `VARIANT` object to be copied into the new `_variant_t` object. -*var_t_Src*
+*`var_t_Src`*\ A `_variant_t` object to be copied into the new `_variant_t` object. -*fCopy*
+*`fCopy`*\ If **`false`**, the supplied `VARIANT` object is attached to the new `_variant_t` object without making a new copy by `VariantCopy`. -*ISrc, sSrc*
+*`ISrc`*, *`sSrc`*\ An integer value to be copied into the new `_variant_t` object. -*vtSrc*
+*`vtSrc`*\ The `VARTYPE` for the new `_variant_t` object. -*fltSrc, dblSrc*
+*`fltSrc`*, *`dblSrc`*\ A numerical value to be copied into the new `_variant_t` object. -*cySrc*
+*`cySrc`*\ A `CY` object to be copied into the new `_variant_t` object. -*bstrSrc*
+*`bstrSrc`*\ A `_bstr_t` object to be copied into the new `_variant_t` object. -*strSrc, wstrSrc*
+*`strSrc`*, *`wstrSrc`*\ A string to be copied into the new `_variant_t` object. -*bSrc*
+*`bSrc`*\ A **`bool`** value to be copied into the new `_variant_t` object. -*pIUknownSrc*
+*`pIUknownSrc`*\ COM interface pointer to a VT_UNKNOWN object to be encapsulated into the new `_variant_t` object. -*pDispSrc*
+*`pDispSrc`*\ COM interface pointer to a VT_DISPATCH object to be encapsulated into the new `_variant_t` object. -*decSrc*
+*`decSrc`*\ A `DECIMAL` value to be copied into the new `_variant_t` object. -*bSrc*
+*`bSrc`*\ A `BYTE` value to be copied into the new `_variant_t` object. -*cSrc*
+*`cSrc`*\ A **`char`** value to be copied into the new `_variant_t` object. -*usSrc*
+*`usSrc`*\ A **`unsigned short`** value to be copied into the new `_variant_t` object. -*ulSrc*
+*`ulSrc`*\ A **`unsigned long`** value to be copied into the new `_variant_t` object. -*iSrc*
+*`iSrc`*\ An **`int`** value to be copied into the new `_variant_t` object. -*uiSrc*
+*`uiSrc`*\ An **`unsigned int`** value to be copied into the new `_variant_t` object. -*i8Src*
+*`i8Src`*\ An **`__int64`** value to be copied into the new `_variant_t` object. -*ui8Src*
-An **unsigned __int64** value to be copied into the new `_variant_t` object. +*`ui8Src`*\ +An **`unsigned __int64`** value to be copied into the new `_variant_t` object. ## Remarks -- **_variant_t( )** Constructs an empty `_variant_t` object, `VT_EMPTY`. +- **`_variant_t()`** Constructs an empty `_variant_t` object, `VT_EMPTY`. -- **_variant_t( VARIANT&** *varSrc* **)** Constructs a `_variant_t` object from a copy of the `VARIANT` object. The variant type is retained. +- **`_variant_t( VARIANT& varSrc )`** Constructs a `_variant_t` object from a copy of the `VARIANT` object. The variant type is retained. -- **_variant_t( VARIANT**\* *pVarSrc* **)** Constructs a `_variant_t` object from a copy of the `VARIANT` object. The variant type is retained. +- **`_variant_t( VARIANT* pVarSrc )`** Constructs a `_variant_t` object from a copy of the `VARIANT` object. The variant type is retained. -- **_variant_t( _variant_t&** *var_t_Src* **)** Constructs a `_variant_t` object from another `_variant_t` object. The variant type is retained. +- **`_variant_t( _variant_t& var_t_Src )`** Constructs a `_variant_t` object from another `_variant_t` object. The variant type is retained. -- **_variant_t( VARIANT&** *varSrc* **, bool** `fCopy` **)** Constructs a `_variant_t` object from an existing `VARIANT` object. If *fCopy* is **`false`**, the **VARIANT** object is attached to the new object without making a copy. +- **`_variant_t( VARIANT& varSrc, bool fCopy )`** Constructs a `_variant_t` object from an existing `VARIANT` object. If *`fCopy`* is **`false`**, the **`VARIANT`** object is attached to the new object without making a copy. -- **_variant_t( short** *sSrc* **, VARTYPE** `vtSrc` **= VT_I2 )** Constructs a `_variant_t` object of type VT_I2 or VT_BOOL from a **`short`** integer value. Any other `VARTYPE` results in an E_INVALIDARG error. +- **`_variant_t( short sSrc, VARTYPE vtSrc = VT_I2 )`** Constructs a `_variant_t` object of type `VT_I2` or `VT_BOOL` from a **`short`** integer value. Any other `VARTYPE` results in an `E_INVALIDARG` error. -- **_variant_t( long** `lSrc` **, VARTYPE** `vtSrc` **= VT_I4 )** Constructs a `_variant_t` object of type VT_I4, VT_BOOL, or VT_ERROR from a **`long`** integer value. Any other `VARTYPE` results in an E_INVALIDARG error. +- **`_variant_t( long lSrc, VARTYPE vtSrc = VT_I4 )`** Constructs a `_variant_t` object of type `VT_I4`, `VT_BOOL`, or `VT_ERROR` from a **`long`** integer value. Any other `VARTYPE` results in an `E_INVALIDARG` error. -- **_variant_t( float** `fltSrc` **)** Constructs a `_variant_t` object of type VT_R4 from a **`float`** numerical value. +- **`_variant_t( float fltSrc )`** Constructs a `_variant_t` object of type `VT_R4` from a **`float`** numerical value. -- **_variant_t( double** `dblSrc` **, VARTYPE** `vtSrc` **= VT_R8 )** Constructs a `_variant_t` object of type VT_R8 or VT_DATE from a **`double`** numerical value. Any other `VARTYPE` results in an E_INVALIDARG error. +- **`_variant_t( double dblSrc, VARTYPE vtSrc = VT_R8 )`** Constructs a `_variant_t` object of type `VT_R8` or `VT_DATE` from a **`double`** numerical value. Any other `VARTYPE` results in an `E_INVALIDARG` error. -- **_variant_t( CY&** `cySrc` **)** Constructs a `_variant_t` object of type VT_CY from a `CY` object. +- **`_variant_t( CY& cySrc )`** Constructs a `_variant_t` object of type `VT_CY` from a `CY` object. -- **_variant_t( _bstr_t&** `bstrSrc` **)** Constructs a `_variant_t` object of type VT_BSTR from a `_bstr_t` object. A new `BSTR` is allocated. +- *`*_variant_t( _bstr_t& bstrSrc )`** Constructs a `_variant_t` object of type `VT_BSTR` from a `_bstr_t` object. A new `BSTR` is allocated. -- **_variant_t( wchar_t** \* *wstrSrc* **)** Constructs a `_variant_t` object of type VT_BSTR from a Unicode string. A new `BSTR` is allocated. +- **`_variant_t( wchar_t* wstrSrc )`** Constructs a `_variant_t` object of type `VT_BSTR` from a Unicode string. A new `BSTR` is allocated. -- **_variant_t( char**\* `strSrc` **)** Constructs a `_variant_t` object of type VT_BSTR from a string. A new `BSTR` is allocated. +- **`_variant_t( char* strSrc )`** Constructs a `_variant_t` object of type `VT_BSTR` from a string. A new `BSTR` is allocated. -- **_variant_t( bool** `bSrc` **)** Constructs a `_variant_t` object of type VT_BOOL from a **`bool`** value. +- **`_variant_t( bool bSrc )`** Constructs a `_variant_t` object of type `VT_BOOL` from a **`bool`** value. -- **_variant_t( IUnknown**\* `pIUknownSrc` **, bool** `fAddRef` **= true )** Constructs a `_variant_t` object of type VT_UNKNOWN from a COM interface pointer. If `fAddRef` is **`true`**, then `AddRef` is called on the supplied interface pointer to match the call to `Release` that will occur when the `_variant_t` object is destroyed. It is up to you to call `Release` on the supplied interface pointer. If `fAddRef` is **`false`**, this constructor takes ownership of the supplied interface pointer; do not call `Release` on the supplied interface pointer. +- **`_variant_t( IUnknown* pIUknownSrc, bool fAddRef = true )`** Constructs a `_variant_t` object of type `VT_UNKNOWN` from a COM interface pointer. If `fAddRef` is **`true`**, then `AddRef` is called on the supplied interface pointer to match the call to `Release` that will occur when the `_variant_t` object is destroyed. It is up to you to call `Release` on the supplied interface pointer. If `fAddRef` is **`false`**, this constructor takes ownership of the supplied interface pointer; don't call `Release` on the supplied interface pointer. -- **_variant_t( IDispatch**\* `pDispSrc` **, bool** `fAddRef` **= true )** Constructs a `_variant_t` object of type VT_DISPATCH from a COM interface pointer. If `fAddRef` is **`true`**, then `AddRef` is called on the supplied interface pointer to match the call to `Release` that will occur when the `_variant_t` object is destroyed. It is up to you to call `Release` on the supplied interface pointer. If `fAddRef` is **`false`**, this constructor takes ownership of the supplied interface pointer; do not call `Release` on the supplied interface pointer. +- **`_variant_t( IDispatch* pDispSrc, bool fAddRef = true )`** Constructs a `_variant_t` object of type `VT_DISPATCH` from a COM interface pointer. If `fAddRef` is **`true`**, then `AddRef` is called on the supplied interface pointer to match the call to `Release` that will occur when the `_variant_t` object is destroyed. It's up to you to call `Release` on the supplied interface pointer. If `fAddRef` is **`false`**, this constructor takes ownership of the supplied interface pointer; don't call `Release` on the supplied interface pointer. -- **_variant_t( DECIMAL&** `decSrc` **)** Constructs a `_variant_t` object of type VT_DECIMAL from a `DECIMAL` value. +- **`_variant_t( DECIMAL& decSrc )`** Constructs a `_variant_t` object of type `VT_DECIMAL` from a `DECIMAL` value. -- **_variant_t( BYTE** `bSrc` **)** Constructs a `_variant_t` object of type `VT_UI1` from a `BYTE` value. +- **`_variant_t( BYTE bSrc )`** Constructs a `_variant_t` object of type `VT_UI1` from a `BYTE` value. **END Microsoft Specific** ## See also -[_variant_t Class](../cpp/variant-t-class.md) +[`_variant_t` Class](../cpp/variant-t-class.md) diff --git a/docs/cross-platform/install-visual-cpp-for-cross-platform-mobile-development.md b/docs/cross-platform/install-visual-cpp-for-cross-platform-mobile-development.md index 7286f3b1551..5d610defde3 100644 --- a/docs/cross-platform/install-visual-cpp-for-cross-platform-mobile-development.md +++ b/docs/cross-platform/install-visual-cpp-for-cross-platform-mobile-development.md @@ -23,7 +23,7 @@ This article describes how to install the tools and third-party software require ::: moniker-end ::: moniker range=">=msvc-160" -- For installation requirements, see [Visual Studio product family system requirements](/visualstudio/releases/2019/system-requirements). +- For installation requirements, see [Visual Studio product family system requirements](/visualstudio/releases/2022/system-requirements). > [!IMPORTANT] > If you are using Windows 7 or Windows Server 2008 R2, you can develop code for Windows Desktop applications, Android Native Activity apps and libraries, and apps and code libraries for iOS, but not Windows Phone or UWP apps. diff --git a/docs/extensions/constraints-on-generic-type-parameters-cpp-cli.md b/docs/extensions/constraints-on-generic-type-parameters-cpp-cli.md index fbca1690457..e36d5db911d 100644 --- a/docs/extensions/constraints-on-generic-type-parameters-cpp-cli.md +++ b/docs/extensions/constraints-on-generic-type-parameters-cpp-cli.md @@ -1,41 +1,41 @@ --- -description: "Learn more about: Constraints on Generic Type Parameters (C++/CLI)" -title: "Constraints on Generic Type Parameters (C++/CLI)" +description: "Learn more about: Constraints on generic type parameters (C++/CLI)" +title: "Constraints on generic type parameters (C++/CLI)" ms.date: "10/12/2018" ms.topic: "reference" f1_keywords: ["where"] helpviewer_keywords: ["where keyword [C++]", "constraints, C++"] ms.assetid: eb828cc9-684f-48a3-a898-b327700c0a63 --- -# Constraints on Generic Type Parameters (C++/CLI) +# Constraints on generic type parameters (C++/CLI) -In generic type or method declarations, you can qualify a type parameter with constraints. A constraint is a requirement that types used as type arguments must satisfy. For example, a constraint might be that the type argument must implement a certain interface or inherit from a specific class. +In generic type or method declarations, you can qualify a type parameter with *constraints*. A constraint is a requirement that types used as type arguments must satisfy. For example, a constraint might be that the type argument must implement a certain interface or inherit from a specific class. Constraints are optional; not specifying a constraint on a parameter is equivalent to constraining that parameter to . ## Syntax ```cpp -where type-parameter: constraint list +where type-parameter: constraint-list ``` ### Parameters -*type-parameter*
+*`type-parameter`*\ One of the type parameters, to be constrained. -*constraint list*
-*constraint list* is a comma-separated list of constraint specifications. The list can include interfaces to be implemented by the type parameter. +*`constraint-list`*\ +*`constraint-list`* is a comma-separated list of constraint specifications. The list can include interfaces to be implemented by the type parameter. The list can also include a class. For the type argument to satisfy a base class constraint, it must be the same class as the constraint or derive from the constraint. -You can also specify **gcnew()** to indicate the type argument must have a public parameterless constructor; or **ref class** to indicate the type argument must be a reference type, including any class, interface, delegate, or array type; or **value class** to indicate the type argument must be a value type. Any value type except Nullable\ can be specified. +You can also specify **`gcnew()`** to indicate the type argument must have a public parameterless constructor; or **`ref class`** to indicate the type argument must be a reference type, including any class, interface, delegate, or array type; or **`value class`** to indicate the type argument must be a value type. Any value type except `Nullable` can be specified. -You can also specify a generic parameter as a constraint. The type argument supplied for the type you are constraining must be or derive from the type of the constraint. This is called a naked type constraint. +You can also specify a generic parameter as a constraint. The type argument supplied for the type you're constraining must be or derive from the type of the constraint. This parameter is called a *naked type constraint*. ## Remarks -The constraint clause consists of **where** followed by a type parameter, a colon (**:**), and the constraint, which specifies the nature of the restriction on the type parameter. **where** is a context-sensitive keyword; see [Context-Sensitive Keywords](context-sensitive-keywords-cpp-component-extensions.md) for more information. Separate multiple **where** clauses with a space. +The constraint clause consists of **`where`** followed by a type parameter, a colon (**`:`**), and the constraint, which specifies the nature of the restriction on the type parameter. **`where`** is a context-sensitive keyword. For more information, see [Context-sensitive keywords](context-sensitive-keywords-cpp-component-extensions.md). Separate multiple **`where`** clauses with a space. Constraints are applied to type parameters to place limitations on the types that can be used as arguments for a generic type or method. @@ -54,11 +54,11 @@ ref class List {}; This constraint requires that a type argument used for `T` implements `IComparable` at compile time. It also allows interface methods, such as `CompareTo`, to be called. No cast is needed on an instance of the type parameter to call interface methods. -Static methods in the type argument's class cannot be called through the type parameter; they can be called only through the actual named type. +Static methods in the type argument's class can't be called through the type parameter; they can be called only through the actual named type. -A constraint cannot be a value type, including built-in types such as **`int`** or **`double`**. Since value types cannot have derived classes, only one class would ever be able to satisfy the constraint. In that case, the generic can be rewritten with the type parameter replaced by the specific value type. +A constraint can't be a value type, including built-in types such as **`int`** or **`double`**. Since value types cannot have derived classes, only one class could ever satisfy the constraint. In that case, the generic can be rewritten with the type parameter replaced by the specific value type. -Constraints are required in some cases since the compiler will not allow the use of methods or other features of an unknown type unless the constraints imply that the unknown type supports the methods or interfaces. +Constraints are required in some cases since the compiler won't allow the use of methods or other features of an unknown type unless the constraints imply that the unknown type supports the methods or interfaces. Multiple constraints for the same type parameter can be specified in a comma-separated list @@ -86,13 +86,13 @@ generic ref class Dictionary {}; ``` -To summarize, use constraints in your code according to the following rules: +Use constraints in your code according to the following rules: - If multiple constraints are listed, the constraints may be listed in any order. -- Constraints can also be class types, such as abstract base classes. However, constraints cannot be value types or sealed classes. +- Constraints can also be class types, such as abstract base classes. However, constraints can't be value types or `sealed` classes. -- Constraints cannot themselves be type parameters, but they can involve the type parameters in an open constructed type. For example: +- Constraints can't themselves be type parameters, but they can involve the type parameters in an open constructed type. For example: ```cpp // generics_constraints_4.cpp @@ -167,7 +167,7 @@ int main() { "grandfather" is a senior ``` -When a generic type parameter is used as a constraint, it is called a naked type constraint. Naked type constraints are useful when a member function with its own type parameter needs to constrain that parameter to the type parameter of the containing type. +When a generic type parameter is used as a constraint, it's called a *naked type constraint*. Naked type constraints are useful when a member function with its own type parameter needs to constrain that parameter to the type parameter of the containing type. In the following example, `T` is a naked type constraint in the context of the `Add` method. diff --git a/docs/extensions/generic-functions-cpp-cli.md b/docs/extensions/generic-functions-cpp-cli.md index 9cf55c49229..02b61934bbf 100644 --- a/docs/extensions/generic-functions-cpp-cli.md +++ b/docs/extensions/generic-functions-cpp-cli.md @@ -1,26 +1,26 @@ --- -description: "Learn more about: Generic Functions (C++/CLI)" +description: "Learn more about: Generic functions (C++/CLI)" title: "Generic Functions (C++/CLI)" ms.date: "10/12/2018" ms.topic: "reference" helpviewer_keywords: ["functions [C++], generic", "generic methods", "generics [C++], functions", "methods [C++], generic", "generic functions"] ms.assetid: 8e409364-58f9-4360-b486-e7d555e0c218 --- -# Generic Functions (C++/CLI) +# Generic functions (C++/CLI) A generic function is a function that is declared with type parameters. When called, actual types are used instead of the type parameters. -## All Platforms +## All platforms ### Remarks -This feature does not apply to all platforms. +This feature doesn't apply to all platforms. ## Windows Runtime ### Remarks -This feature is not supported in the Windows Runtime. +This feature isn't supported in the Windows Runtime. ### Requirements @@ -28,14 +28,14 @@ Compiler option: `/ZW` ## Common Language Runtime -A generic function is a function that is declared with type parameters. When called, actual types are used instead of the type parameters. +A generic function is a function that's declared with type parameters. When called, actual types are used instead of the type parameters. ### Syntax ```cpp [attributes] [modifiers] -return-type identifier -[type-parameter-constraints clauses] +return-type identifier +[type-parameter-constraints-clauses] ([formal-parameters]) {function-body} @@ -43,37 +43,37 @@ return-type identifier ### Parameters -*attributes*
-(Optional) Additional declarative information. For more information on attributes and attribute classes, see attributes. +*`attributes`*\ +(Optional) Additional declarative information. For more information on attributes and attribute classes, see [attributes](../cppcx/attributes-c-cx.md). -*modifiers*
-(Optional) A modifier for the function, such as static. **`virtual`** is not allowed since virtual methods may not be generic. +*`modifiers`*\ +(Optional) A modifier for the function, such as `static`. **`virtual`** isn't allowed since virtual methods may not be generic. -*return-type*
+*`return-type`*\ The type returned by the method. If the return type is void, no return value is required. -*identifier*
+*`identifier`*\ The function name. -*type-parameter identifier(s)*
+*`type-parameter-identifier-list`*\ Comma-separated identifiers list. -*formal-parameters*
+*`formal-parameters`*\ (Optional) Parameter list. -*type-parameter-constraints-clauses*
-This specifies restrictions on the types that may be used as type arguments, and takes the form specified in [Constraints on Generic Type Parameters (C++/CLI)](constraints-on-generic-type-parameters-cpp-cli.md). +*`type-parameter-constraints-clauses`*\ +This set specifies restrictions on the types that may be used as type arguments, and takes the form specified in [Constraints on Generic Type Parameters (C++/CLI)](constraints-on-generic-type-parameters-cpp-cli.md). -*function-body*
+*`function-body`*\ The body of the method, which may refer to the type parameter identifiers. ### Remarks -Generic functions are functions declared with a generic type parameter. They may be methods in a class or struct, or standalone functions. A single generic declaration implicitly declares a family of functions that differ only in the substitution of a different actual type for the generic type parameter. +Generic functions are functions declared with a generic type parameter. They may be methods in a `class` or `struct`, or standalone functions. A single generic declaration implicitly declares a family of functions that differ only in the substitution of a different actual type for the generic type parameter. -A class or struct constructor may not be declared with generic type parameters. +A `class` or `struct` constructor may not be declared with generic type parameters. -When called, the generic type parameter is replaced by an actual type. The actual type may be explicitly specified in angled brackets using syntax similar to a template function call. If called without the type parameters, the compiler will attempt to deduce the actual type from the parameters supplied in the function call. If the intended type argument cannot be deduced from the parameters used, the compiler will report an error. +When called, the generic type parameter is replaced by an actual type. The actual type may be explicitly specified in angled brackets using syntax similar to a template function call. If called without the type parameters, the compiler will attempt to deduce the actual type from the parameters supplied in the function call. The compiler reports an error if the intended type argument cannot be deduced from the parameters used. ### Requirements @@ -114,7 +114,7 @@ int main() { } ``` -Generic functions can be overloaded based on signature or arity, the number of type parameters on a function. Also, generic functions can be overloaded with non-generic functions of the same name, as long as the functions differ in some type parameters. For example, the following functions can be overloaded: +Generic functions can be overloaded based on signature or *arity*, the number of type parameters on a function. Also, generic functions can be overloaded with non-generic functions of the same name, as long as the functions differ in some type parameters. For example, the following functions can be overloaded: ```cpp // generics_generic_function_2.cpp @@ -173,5 +173,5 @@ My function returned a string: Hello generic functions! ## See also -[Component Extensions for .NET and UWP](component-extensions-for-runtime-platforms.md)
+[Component Extensions for .NET and UWP](component-extensions-for-runtime-platforms.md)\ [Generics](generics-cpp-component-extensions.md) diff --git a/docs/extensions/property-cpp-component-extensions.md b/docs/extensions/property-cpp-component-extensions.md index a60a3159185..37158925a45 100644 --- a/docs/extensions/property-cpp-component-extensions.md +++ b/docs/extensions/property-cpp-component-extensions.md @@ -1,33 +1,33 @@ --- -description: "Learn more about: property (C++/CLI and C++/CX)" -title: "property (C++/CLI and C++/CX)" +description: "Learn more about: 'property' functions (C++/CLI and C++/CX)" +title: "property (C++/CLI and C++/CX)" ms.date: "10/12/2018" ms.topic: "reference" helpviewer_keywords: ["property keyword [C++]"] ms.assetid: cc79d2b2-f013-4d81-8252-eece97a18704 --- -# property (C++/CLI and C++/CX) +# `property` (C++/CLI and C++/CX) Declares a *property*, which is a member function that behaves and is accessed like a data member or an array element. -## All Runtimes +## All runtimes You can declare one of the following types of properties. -*simple property*
-By default, creates a *set accessor* that assigns the property value, a *get accessor* that retrieves the property value, and a compiler-generated private data member that contains the property value. +- **simple property**
+ By default, creates a `set` accessor that assigns the property value, a `get` accessor that retrieves the property value, and a compiler-generated private data member that contains the property value. -*property block*
-Use this to create user-defined get and/or set accessors. The property is read/write if both the get and set accessors are defined, read-only if only the get accessor is defined, and write-only if only the set accessor is defined. +- **property block**
+ Use a property block to create user-defined `get` or `set` accessors. The property is read and write if both the `get` and `set` accessors are defined, read-only if only the `get` accessor is defined, and write-only if only the `set` accessor is defined. -You must explicitly declare a data member to contain the property value. + You need to explicitly declare a data member to contain the property value. -*indexed property*
-A property block that you can use to get and set a property value that is specified by one or more indexes. +- **indexed property**
+ A property block that you can use to get and set a property value that is specified by one or more indexes. -You can create an indexed property that has either a user-defined property name or a *default* property name. The name of a default index property is the name of the class in which the property is defined. To declare a default property, specify the **`default`** keyword instead of a property name. + You can create an indexed property that has either a user-defined property name or a *default* property name. The name of a default index property is the name of the class in which the property is defined. To declare a default property, specify the **`default`** keyword instead of a property name. -You must explicitly declare a data member to contain the property value. For an indexed property, the data member is typically an array or a collection. +Explicitly declare a data member to contain the property value. For an indexed property, the data member is typically an array or a collection. ### Syntax @@ -52,28 +52,28 @@ property type default[index_list] { ### Parameters -*type*
-The data type of the property value, and consequently the property itself. +*`type`*\ +The data type of the property value, and of the property itself. -*property_name*
+*`property_name`*\ The name of the property. -*access-modifier*
+*`access-modifier`*\ An access qualifier. Valid qualifiers are **`static`** and **`virtual`**. -The get or set accessors need not agree on the **`virtual`** qualifier, but they must agree on the **`static`** qualifier. +The `get` or `set` accessors need not agree on the **`virtual`** qualifier, but they must agree on the **`static`** qualifier. -*inheritance-modifier*
-An inheritance qualifier. Valid qualifiers are **abstract** and **sealed**. +*`inheritance-modifier`*\ +An inheritance qualifier. Valid qualifiers are **`abstract`** and **`sealed`**. -*index_list*
+*`index_list`*\ A comma-delimited list of one or more indexes. Each index consists of an index type, and an optional identifier that can be used in the property method body. -*value*
-The value to assign to the property in a set operation, or retrieve in a get operation. +*`value`*\ +The value to assign to the property in a `set` operation, or retrieve in a `get` operation. -*property_body*
-The property method body of the set or get accessor. The *property_body* can use the *index_list* to access the underlying property data member, or as parameters in user-defined processing. +*`property_body`*\ +The property method body of the `set` or `get` accessor. The *`property_body`* can use the *`index_list`* to access the underlying property data member, or as parameters in user-defined processing. ## Windows Runtime @@ -104,17 +104,17 @@ modifier property type default[index]; ### Parameters -*modifier*
+*`modifier`*\ A modifier that can be used on either a property declaration or a get/set accessor method. Possible values are **`static`** and **`virtual`**. -*type*
+*`type`*\ The type of the value that is represented by the property. -*property_name*
-Parameter(s) for the raise method; must match the signature of the delegate. +*`property_name`*\ +Parameter(s) for the `raise` method; must match the signature of the delegate. -*index_list*
-A comma-delimited list of one or more indexes, specified in square brackets (the subscript operator, ([])). For each index, specify a type and optionally an identifier that can be used in the property method body. +*`index_list`*\ +A comma-delimited list of one or more indexes, specified in square brackets (the subscript operator, **`[]`**). For each index, specify a type and optionally an identifier that can be used in the property method body. ### Remarks @@ -122,37 +122,37 @@ The first syntax example shows a *simple property*, which implicitly declares bo The second syntax example shows a *property block*, which explicitly declares both a `set` and `get` method. -The third syntax example shows a customer-defined *index property*. An index property takes parameters in addition to the value to be set or retrieved. You must specify a name for the property. Unlike a simple property, the `set` and/or `get` methods of an index property must be explicitly defined, and you must specify a name for the property. +The third syntax example shows a customer-defined *index property*. An index property takes parameters in addition to the value to be set or retrieved. Specify a name for the property. Unlike a simple property, the `set` and `get` methods of an index property must be explicitly defined, and so you must specify a name for the property. The fourth syntax example shows a *default* property, which provides array-like access to an instance of the type. The keyword, **`default`**, serves only to specify a default property. The name of the default property is the name of the type in which the property is defined. -The **`property`** keyword can appear in a class, interface, or value type. A property can have a get function (read-only), a set function (write-only), or both (read-write). +The **`property`** keyword can appear in a class, interface, or value type. A property can have a `get` function (read-only), a `set` function (write-only), or both (read-write). -A property name cannot match the name of the managed class that contains it. The return type of the getter function must match the type of the last parameter of a corresponding setter function. +A property name can't match the name of the managed class that contains it. The return type of the getter function must match the type of the last parameter of a corresponding setter function. To client code, a property has the appearance of an ordinary data member, and can be written to or read from by using the same syntax as a data member. -The get and set methods need not agree on the **`virtual`** modifier. +The `get` and `set` methods need not agree on the **`virtual`** modifier. -The accessibility of the get and set method can differ. +The accessibility of the `get` and `set` method can differ. The definition of a property method can appear outside the class body, just like an ordinary method. -The get and the set method for a property shall agree on the **`static`** modifier. +The `get` and the `set` method for a property shall agree on the **`static`** modifier. -A property is scalar if its get and set methods fit the following description: +A property is scalar if its `get` and `set` methods fit the following description: -- The get method has no parameters, and has return type `T`. +- The `get` method has no parameters, and has return type `T`. -- The set method has a parameter of type `T`, and return type **`void`**. +- The `set` method has a parameter of type `T`, and return type **`void`**. There shall be only one scalar property declared in a scope with the same identifier. Scalar properties cannot be overloaded. -When a property data member is declared, the compiler injects a data member—sometimes referred to as the "backing store"—in the class. However, the name of the data member is of a form such that you cannot reference the member in the source as if it were an actual data member of the containing class. Use ildasm.exe to view the metadata for your type and see the compiler-generated name for the property's backing store. +When a property data member is declared, the compiler injects a data member—sometimes referred to as the "backing store"—in the class. However, the name of the data member is of a form such that you can't reference the member in the source as if it were an actual data member of the containing class. Use ildasm.exe to view the metadata for your type and see the compiler-generated name for the property's backing store. -Different accessibility is allowed for the accessor methods in a property block. That is, the set method can be public and the get method can be private. However, it is an error for an accessor method to have a less restrictive accessibility than what is on the declaration of the property itself. +Different accessibility is allowed for the accessor methods in a property block. That is, the `set` method can be `public` and the `get` method can be `private`. However, it's an error for an accessor method to have a less restrictive accessibility than what is on the declaration of the property itself. -**`property`** is a context-sensitive keyword. For more information, see [Context-Sensitive Keywords](context-sensitive-keywords-cpp-component-extensions.md). +**`property`** is a context-sensitive keyword. For more information, see [Context-sensitive keywords](context-sensitive-keywords-cpp-component-extensions.md). ### Requirements diff --git a/docs/ide/using-the-visual-studio-ide-for-cpp-desktop-development.md b/docs/ide/using-the-visual-studio-ide-for-cpp-desktop-development.md index 79f6055f7d8..330552cf38a 100644 --- a/docs/ide/using-the-visual-studio-ide-for-cpp-desktop-development.md +++ b/docs/ide/using-the-visual-studio-ide-for-cpp-desktop-development.md @@ -11,23 +11,11 @@ The Visual Studio Integrated Development Environment (IDE) offers a set of featu ## Prerequisites -If you haven't installed Visual Studio yet, now is the time. For download links and a quick walkthrough, see [Install C++ support in Visual Studio](../build/vscpp-step-0-installation.md). For more information about how to install Visual Studio in general, and troubleshooting tips if something goes wrong, see [Install Visual Studio](/visualstudio/install/install-visual-studio). Be sure to choose the **Desktop development with C++** workload to include the C++ compilers, tools, and libraries when you install Visual Studio, because they are not installed by default. +If you haven't installed Visual Studio yet, now is the time. For download links and a quick walkthrough, see [Install C++ support in Visual Studio](../build/vscpp-step-0-installation.md). For more information about how to install Visual Studio in general, and troubleshooting tips if something goes wrong, see [Install Visual Studio](/visualstudio/install/install-visual-studio). Be sure to choose the **Desktop development with C++** workload to include the C++ compilers, tools, and libraries when you install Visual Studio, because they're not installed by default. -These walkthroughs assume that you have installed Visual Studio and the C++ components required for Windows Desktop development. We also assume you understand the fundamentals of the C++ language. If you need to learn C++, there are many books and web resources available. One good place to start is the [Get Started](https://isocpp.org/get-started) page of the Standard C++ Foundation website. +These walkthroughs assume that you've installed Visual Studio and the C++ components required for Windows Desktop development. We also assume you understand the fundamentals of the C++ language. If you need to learn C++, there are many books and web resources available. One good place to start is the [Get Started](https://isocpp.org/get-started) page of the Standard C++ Foundation website. -If you haven't installed Visual Studio yet, now is the time. In general, we highly recommend that you use Visual Studio 2019 even if you need to compile your code using the Visual Studio 2017 or Visual Studio 2015 compiler. For more information, see [Use native multi-targeting in Visual Studio to build old projects](../porting/use-native-multi-targeting.md). - -**Visual Studio 2019 Installation** - -To get Visual Studio 2019, you can download it from [Visual Studio Downloads](https://www.visualstudio.com/downloads/). Be sure to include the C++ development tools when you install Visual Studio, because they are not installed by default. For more information about how to install Visual Studio, see [Install Visual Studio](/visualstudio/install/install-visual-studio). - -**Visual Studio 2017 Installation** - -To get Visual Studio 2017, you can download it from [Download older versions of Visual Studio](https://www.visualstudio.com/vs/older-downloads/). Be sure to include the C++ development tools when you install Visual Studio, because they are not installed by default. For more information about how to install Visual Studio, see [Install Visual Studio](/visualstudio/install/install-visual-studio). To see the instructions for Visual Studio 2017, set the Visual Studio **Version** selector control to Visual Studio 2017. It's found at the top of the table of contents on the page. - -**Visual Studio 2015 Installation** - -To install Visual Studio 2015, go to [Download older versions of Visual Studio](https://www.visualstudio.com/vs/older-downloads/). Run the setup program and choose **Custom installation** and then choose the C++ component. +In general, we highly recommend that you use the latest version of Visual Studio even if you need to compile your code using an earlier version of the compiler toolset. For more information, see [Use native multi-targeting in Visual Studio to build old projects](../porting/use-native-multi-targeting.md). Once your Visual Studio installation is complete, you are ready to continue. diff --git a/docs/mfc/derived-window-classes.md b/docs/mfc/derived-window-classes.md index b0cc5bb507f..8102ecae4f0 100644 --- a/docs/mfc/derived-window-classes.md +++ b/docs/mfc/derived-window-classes.md @@ -1,56 +1,56 @@ --- -description: "Learn more about: Derived Window Classes" -title: "Derived Window Classes" +description: "Learn more about: Derived window classes" +title: "Derived window classes" ms.date: "11/04/2016" helpviewer_keywords: ["window class hierarchy", "hierarchies, window classes", "classes [MFC], derived", "CWnd class [MFC], classes derived from", "derived classes [MFC], window classes", "window classes [MFC], derived"] ms.assetid: 6f7e437e-fbde-4a06-bfab-72d9dbf05292 --- -# Derived Window Classes +# Derived window classes -You can create windows directly from [CWnd](reference/cwnd-class.md), or derive new window classes from `CWnd`. This is how you typically create your own custom windows. However, most windows used in a framework program are instead created from one of the `CWnd`-derived frame-window classes supplied by MFC. +You can create windows directly from [`CWnd`](reference/cwnd-class.md), or derive new window classes from `CWnd`. It's how you typically create your own custom windows. However, most windows used in a framework program are instead created from one of the `CWnd`-derived frame-window classes supplied by MFC. -## Frame Window Classes +## Frame window classes -[CFrameWnd](reference/cframewnd-class.md)
+[`CFrameWnd`](reference/cframewnd-class.md)
Used for SDI frame windows that frame a single document and its view. The frame window is both the main frame window for the application and the frame window for the current document. -[CMDIFrameWnd](reference/cmdiframewnd-class.md)
+[`CMDIFrameWnd`](reference/cmdiframewnd-class.md)
Used as the main frame window for MDI applications. The main frame window is a container for all MDI document windows and shares its menu bar with them. An MDI frame window is a top-level window that appears on the desktop. -[CMDIChildWnd](reference/cmdichildwnd-class.md)
-Used for individual documents opened in an MDI main frame window. Each document and its view are framed by an MDI child frame window contained by the MDI main frame window. An MDI child window looks much like a typical frame window but is contained inside an MDI frame window instead of sitting on the desktop. However, the MDI child window lacks a menu bar of its own and must share the menu bar of the MDI frame window that contains it. +[`CMDIChildWnd`](reference/cmdichildwnd-class.md)
+Used for individual documents opened in an MDI main frame window. Each document and its view are framed by an MDI child frame window contained by the MDI main frame window. An MDI child window looks much like a typical frame window but is contained inside an MDI frame window instead of sitting on the desktop. However, the MDI child window lacks a menu bar of its own. It must share the menu bar of the MDI frame window that contains it. -For more information, see [Frame Windows](frame-windows.md). +For more information, see [Frame windows](frame-windows.md). -## Other Window Classes Derived from CWnd +## Other window classes derived from `CWnd` In addition to frame windows, several other major categories of windows are derived from `CWnd`: -*Views*
-Views are created using the `CWnd`-derived class [CView](reference/cview-class.md) (or one of its derived classes). A view is attached to a document and acts as an intermediary between the document and the user. A view is a child window (not an MDI child) that typically fills the client area of an SDI frame window or an MDI child frame window (or that portion of the client area not covered by a toolbar and/or a status bar). +- **Views**:\ + Views are created using the `CWnd`-derived class [`CView`](reference/cview-class.md) (or one of its derived classes). A view is attached to a document and acts as an intermediary between the document and the user. A view is a child window (not an MDI child) that typically fills the client area of an SDI frame window or an MDI child frame window (or that portion of the client area not covered by a toolbar or a status bar). -*Dialog Boxes*
-Dialog boxes are created using the `CWnd`-derived class [CDialog](reference/cdialog-class.md). +- **Dialog Boxes**:\ + Dialog boxes are created using the `CWnd`-derived class [`CDialog`](reference/cdialog-class.md). -*Forms*
-Form views based on dialog-template resources, such as dialog boxes, are created using classes [CFormView](reference/cformview-class.md), [CRecordView](reference/crecordview-class.md), or [CDaoRecordView](reference/cdaorecordview-class.md). +- **Forms**:\ + Form views based on dialog-template resources, such as dialog boxes, are created using classes [`CFormView`](reference/cformview-class.md), [`CRecordView`](reference/crecordview-class.md), or [`CDaoRecordView`](reference/cdaorecordview-class.md). -*Controls*
-Controls such as buttons, list boxes, and combo boxes are created using other classes derived from `CWnd`. See [Control Topics](controls-mfc.md). +- **Controls**:\ + Controls such as buttons, list boxes, and combo boxes are created using other classes derived from `CWnd`. See [Control topics](controls-mfc.md). -*Control Bars*
-Child windows that contain controls. Examples include toolbars and status bars. See [Control Bars](control-bars.md). +- **Control Bars**:\ + Child windows that contain controls. Examples include toolbars and status bars. See [Control bars](control-bars.md). ## Window Class Hierarchy -Refer to the [MFC hierarchy chart](hierarchy-chart.md) in the *MFC Reference*. Views are explained in [Document/View Architecture](document-view-architecture.md). Dialog boxes are explained in [Dialog Boxes](dialog-boxes.md). +Refer to the [MFC hierarchy chart](hierarchy-chart.md) in the *MFC Reference*. Views are explained in [Document/view architecture](document-view-architecture.md). Dialog boxes are explained in [Dialog boxes](dialog-boxes.md). ## Creating Your Own Special-Purpose Window Classes -In addition to the window classes provided by the class library, you may need special-purpose child windows. To create such a window, create your own [CWnd](reference/cwnd-class.md)-derived class and make it a child window of a frame or view. Bear in mind that the framework manages the extent of the client area of a document frame window. Most of the client area is managed by a view, but other windows, such as control bars or your own custom windows, may share the space with the view. You may need to interact with the mechanisms in classes [CView](reference/cview-class.md) and [CControlBar](reference/ccontrolbar-class.md) for positioning child windows in a frame window's client area. +In addition to the window classes provided by the class library, you may need special-purpose child windows. To create such a window, create your own [`CWnd`](reference/cwnd-class.md)-derived class and make it a child window of a frame or view. Bear in mind that the framework manages the extent of the client area of a document frame window. Most of the client area is managed by a view, but other windows, such as control bars or your own custom windows, may share the space with the view. You may need to interact with the mechanisms in classes [`CView`](reference/cview-class.md) and [`CControlBar`](reference/ccontrolbar-class.md) for positioning child windows in a frame window's client area. -[Creating Windows](creating-windows.md) discusses creation of window objects and the windows they manage. +[Creating windows](creating-windows.md) discusses creation of window objects and the windows they manage. ## See also -[Window Objects](window-objects.md) +[Window objects](window-objects.md) diff --git a/docs/mfc/dialog-boxes-in-ole.md b/docs/mfc/dialog-boxes-in-ole.md index 41f677e48ab..dbd432b73d1 100644 --- a/docs/mfc/dialog-boxes-in-ole.md +++ b/docs/mfc/dialog-boxes-in-ole.md @@ -1,34 +1,36 @@ --- -description: "Learn more about: Dialog Boxes in OLE" -title: "Dialog Boxes in OLE" +description: "Learn more about: Dialog boxes in OLE" +title: "Dialog boxes in OLE" ms.date: "11/04/2016" helpviewer_keywords: ["MFC dialog boxes [MFC], OLE dialog boxes", "OLE dialog boxes", "dialog boxes", "OLE dialog boxes [MFC], about OLE dialog boxes", "dialog boxes [MFC], about dialog boxes", "dialog boxes [MFC], OLE", "Insert object"] ms.assetid: 73c41eb8-738a-4d02-9212-d3395bb09a3a --- -# Dialog Boxes in OLE +# Dialog boxes in OLE -While a user runs an OLE-enabled application, there are times when the application needs information from the user in order to carry out the operation. The MFC OLE classes provide a number of dialog boxes to gather the required information. This topic lists the tasks handled by the OLE dialog boxes and the classes needed to display those dialog boxes. For details on OLE dialog boxes and the structures used to customize their behavior, see [MFC Reference](mfc-desktop-applications.md). +While a user runs an OLE-enabled application, there are times when the application needs information from the user to carry out the operation. The MFC OLE classes provide default dialog boxes to gather the required information. This article lists the tasks handled by the OLE dialog boxes and the classes needed to display those dialog boxes. For details on OLE dialog boxes and the structures used to customize their behavior, see [MFC Reference](mfc-desktop-applications.md). -*Insert Object*
-This dialog box allows the user to insert newly created or existing objects into the compound document. It also allows the user to choose to display the item as an icon and enables the Change Icon command button. Display this dialog box when the user chooses Insert Object from the Edit menu. Use the [COleInsertDialog](reference/coleinsertdialog-class.md) class to display this dialog box. Note that you cannot insert an MDI application into itself. An application that is a container/server cannot be inserted into itself unless it is an SDI application. +## Common dialog boxes -*Paste Special*
-This dialog box allows the user to control the format used when pasting data into a compound document. The user can choose the format of the data, whether to embed or link the data, and whether to display it as an icon. Display this dialog box when the user chooses Paste Special from the Edit menu. Use the [COlePasteSpecialDialog](reference/colepastespecialdialog-class.md) class to display this dialog box. +**Insert Object**\ +This dialog box allows the user to insert newly created or existing objects into the compound document. It also allows the user to choose to display the item as an icon and enables the Change Icon command button. Display this dialog box when the user chooses Insert Object from the Edit menu. Use the [`COleInsertDialog`](reference/coleinsertdialog-class.md) class to display this dialog box. You can't insert an MDI application into itself. An application that's a container/server can't be inserted into itself unless it's an SDI application. -*Change Icon*
-This dialog box allows the user to select which icon is displayed to represent the linked or embedded item. Display this dialog box when the user chooses Change Icon from the Edit menu or chooses the Change Icon button in either the Paste Special or Convert dialog boxes. Also display it when the user opens the Insert Object dialog box and chooses Display as Icon. Use the [COleChangeIconDialog](reference/colechangeicondialog-class.md) class to display this dialog box. +**Paste Special**\ +This dialog box allows the user to control the format used when pasting data into a compound document. The user can choose the format of the data, whether to embed or link the data, and whether to display it as an icon. Display this dialog box when the user chooses Paste Special from the Edit menu. Use the [`COlePasteSpecialDialog`](reference/colepastespecialdialog-class.md) class to display this dialog box. -*Convert*
-This dialog box allows the user to change the type of an embedded or linked item. For example, if you have embedded a metafile in a compound document and later want to use another application to modify the embedded metafile, you can use the Convert dialog box. This dialog box is usually displayed by clicking *item type* Object on the Edit menu and then, on the cascading menu, clicking Convert. Use the [COleConvertDialog](reference/coleconvertdialog-class.md) class to display this dialog box. For an example, run the MFC OLE sample [OCLIENT](../overview/visual-cpp-samples.md). +**Change Icon**\ +This dialog box allows the user to select which icon is displayed to represent the linked or embedded item. Display this dialog box when the user chooses Change Icon from the Edit menu or chooses the Change Icon button in either the Paste Special or Convert dialog boxes. Also display it when the user opens the Insert Object dialog box and chooses Display as Icon. Use the [`COleChangeIconDialog`](reference/colechangeicondialog-class.md) class to display this dialog box. -*Edit Links or Update Links*
-The Edit Links dialog box allows the user to change information about the source of a linked object. The Update Links dialog box verifies the sources of all the linked items in the current dialog box and displays the Edit Links dialog box if necessary. Display the Edit Links dialog box when the user chooses Links from the Edit menu. The Update Links dialog box is usually displayed when a compound document is first opened. Use either the [COleLinksDialog](reference/colelinksdialog-class.md) or the [COleUpdateDialog](reference/coleupdatedialog-class.md) class, depending on which dialog box you want to display. +**Convert**\ +This dialog box allows the user to change the type of an embedded or linked item. For example, if you've embedded a metafile in a compound document and later want to use another application to modify the embedded metafile, you can use the Convert dialog box. This dialog box is often displayed by clicking *item type* Object on the Edit menu and then, on the cascading menu, clicking Convert. Use the [`COleConvertDialog`](reference/coleconvertdialog-class.md) class to display this dialog box. For an example, run the MFC OLE sample [OCLIENT](../overview/visual-cpp-samples.md). -*Server Busy or Server Not Responding*
-The Server Busy dialog box is displayed when the user attempts to activate an item and the server is currently unable to handle the request, usually because the server is in use by another user or task. The Server Not Responding dialog box is displayed if the server does not respond to the activation request at all. These dialog boxes are displayed via `COleMessageFilter`, based on an implementation of the OLE interface `IMessageFilter`, and the user can decide whether to attempt the activation request again. Use the [COleBusyDialog](reference/colebusydialog-class.md) class to display this dialog box. +**Edit Links or Update Links**\ +The Edit Links dialog box allows the user to change information about the source of a linked object. The Update Links dialog box verifies the sources of all the linked items in the current dialog box and displays the Edit Links dialog box if necessary. Display the Edit Links dialog box when the user chooses Links from the Edit menu. Usually, the Update Links dialog box is displayed when a compound document is first opened. Use either the [`COleLinksDialog`](reference/colelinksdialog-class.md) or the [`COleUpdateDialog`](reference/coleupdatedialog-class.md) class, depending on which dialog box you want to display. + +**Server Busy or Server Not Responding**\ +The Server Busy dialog box is displayed when the user attempts to activate an item and the server is currently unable to handle the request, usually because the server is in use by another user or task. The Server Not Responding dialog box is displayed if the server doesn't respond to the activation request at all. These dialog boxes are displayed via `COleMessageFilter`, based on an implementation of the OLE interface `IMessageFilter`, and the user can decide whether to attempt the activation request again. Use the [`COleBusyDialog`](reference/colebusydialog-class.md) class to display this dialog box. ## See also -[Dialog Boxes](dialog-boxes.md)
-[Working with Dialog Boxes in MFC](life-cycle-of-a-dialog-box.md)
+[Dialog boxes](dialog-boxes.md)\ +[Working with Dialog Boxes in MFC](life-cycle-of-a-dialog-box.md)\ [OLE](ole-in-mfc.md) diff --git a/docs/mfc/reference/class-factories-and-licensing.md b/docs/mfc/reference/class-factories-and-licensing.md index 5159ced4d12..fb570c46f96 100644 --- a/docs/mfc/reference/class-factories-and-licensing.md +++ b/docs/mfc/reference/class-factories-and-licensing.md @@ -13,27 +13,27 @@ Another important feature of OLE controls is their ability to enforce a license. The following table lists several macros and functions used to declare and implement your control's class factory and to license of your control. -### Class Factories and Licensing +## Class Factories and Licensing -|Macro or function|Description| -|-|-| -|[DECLARE_OLECREATE_EX](#declare_olecreate_ex)|Declares the class factory for an OLE control or property page.| -|[IMPLEMENT_OLECREATE_EX](#implement_olecreate_ex)|Implements the control's `GetClassID` function and declares an instance of the class factory.| -|[BEGIN_OLEFACTORY](#begin_olefactory)|Begins the declaration of any licensing functions.| -|[END_OLEFACTORY](#end_olefactory)|Ends the declaration of any licensing functions.| -|[AfxVerifyLicFile](#afxverifylicfile)|Verifies whether a control is licensed for use on a particular computer.| +| Macro or function | Description | +|--|--| +| [`DECLARE_OLECREATE_EX`](#declare_olecreate_ex) | Declares the class factory for an OLE control or property page. | +| [`IMPLEMENT_OLECREATE_EX`](#implement_olecreate_ex) | Implements the control's `GetClassID` function and declares an instance of the class factory. | +| [`BEGIN_OLEFACTORY`](#begin_olefactory) | Begins the declaration of any licensing functions. | +| [`END_OLEFACTORY`](#end_olefactory) | Ends the declaration of any licensing functions. | +| [`AfxVerifyLicFile`](#afxverifylicfile) | Verifies whether a control is licensed for use on a particular computer. | -## DECLARE_OLECREATE_EX +## `DECLARE_OLECREATE_EX` Declares a class factory and the `GetClassID` member function of your control class. -``` +```cpp DECLARE_OLECREATE_EX(class_name) ``` ### Parameters -*class_name*
+*`class_name`*\ The name of the control class. ### Remarks @@ -48,11 +48,11 @@ Note that this macro serves the same purpose as the following code sample: **Header** afxctl.h -## IMPLEMENT_OLECREATE_EX +## `IMPLEMENT_OLECREATE_EX` -Implements your control's class factory and the [GetClassID](../../mfc/reference/colecontrol-class.md#getclassid) member function of your control class. +Implements your control's class factory and the [`GetClassID`](../../mfc/reference/colecontrol-class.md#getclassid) member function of your control class. -``` +```cpp IMPLEMENT_OLECREATE_EX( class_name, external_name, @@ -71,66 +71,66 @@ IMPLEMENT_OLECREATE_EX( ### Parameters -*class_name*
+*`class_name`*\ The name of the control property page class. -*external_name*
+*`external_name`*\ The object name exposed to applications. -*l, w1, w2, b1, b2, b3, b4, b5, b6, b7, b8*
-Components of the class's CLSID. For more information on these parameters, see the Remarks for [IMPLEMENT_OLECREATE](run-time-object-model-services.md#implement_olecreate). +*`l`*, *`w1`*, *`w2`*, *`b1`*, *`b2`*, *`b3`*, *`b4`*, *`b5`*, *`b6`*, *`b7`*, *`b8`*\ +Components of the class's `CLSID`. For more information on these parameters, see the Remarks for [`IMPLEMENT_OLECREATE`](run-time-object-model-services.md#implement_olecreate). ### Remarks -This macro must appear in the implementation file for any control class that uses the DECLARE_OLECREATE_EX macro or the BEGIN_OLEFACTORY and END_OLEFACTORY macros. The external name is the identifier of the OLE control that is exposed to other applications. Containers use this name to request an object of this control class. +This macro must appear in the implementation file for any control class that uses the `DECLARE_OLECREATE_EX` macro or the `BEGIN_OLEFACTORY` and `END_OLEFACTORY` macros. The external name is the identifier of the OLE control that is exposed to other applications. Containers use this name to request an object of this control class. ### Requirements **Header** afxctl.h -## BEGIN_OLEFACTORY +## `BEGIN_OLEFACTORY` Begins the declaration of your class factory in the header file of your control class. -``` +```cpp BEGIN_OLEFACTORY(class_name) ``` ### Parameters -*class_name*
+*`class_name`*\ Specifies the name of the control class whose class factory this is. ### Remarks -Declarations of class factory licensing functions should begin immediately after BEGIN_OLEFACTORY. +Declarations of class factory licensing functions should begin immediately after `BEGIN_OLEFACTORY`. ### Requirements **Header** afxctl.h -## END_OLEFACTORY +## `END_OLEFACTORY` Ends the declaration of your control's class factory. -``` +```cpp END_OLEFACTORY(class_name) ``` ### Parameters -*class_name*
+*`class_name`*\ The name of the control class whose class factory this is. ### Requirements **Header** afxctl.h -## AfxVerifyLicFile +## `AfxVerifyLicFile` Call this function to verify that the license file named by `pszLicFileName` is valid for the OLE control. -``` +```cpp BOOL AFXAPI AfxVerifyLicFile( HINSTANCE hInstance, LPCTSTR pszLicFileName, @@ -140,16 +140,16 @@ BOOL AFXAPI AfxVerifyLicFile( ### Parameters -*hInstance*
+*`hInstance`*\ The instance handle of the DLL associated with the licensed control. -*pszLicFileName*
+*`pszLicFileName`*\ Points to a null-terminated character string containing the license filename. -*pszLicFileContents*
+*`pszLicFileContents`*\ Points to a byte sequence that must match the sequence found at the beginning of the license file. -*cch*
+*`cch`*\ Number of characters in *pszLicFileContents*. ### Return Value @@ -158,7 +158,7 @@ Nonzero if the license file exists and begins with the character sequence in *ps ### Remarks -If *cch* is -1, this function uses: +If *`cch`* is -1, this function uses: [!code-cpp[NVC_MFC_Utilities#36](../../mfc/codesnippet/cpp/class-factories-and-licensing_2.cpp)] @@ -168,4 +168,4 @@ If *cch* is -1, this function uses: ## See also -[Macros and Globals](../../mfc/reference/mfc-macros-and-globals.md) +[Macros and globals](../../mfc/reference/mfc-macros-and-globals.md) diff --git a/docs/mfc/reference/cmfcribbonquickaccesstoolbardefaultstate-class.md b/docs/mfc/reference/cmfcribbonquickaccesstoolbardefaultstate-class.md index 874b3a79cf8..7065867788b 100644 --- a/docs/mfc/reference/cmfcribbonquickaccesstoolbardefaultstate-class.md +++ b/docs/mfc/reference/cmfcribbonquickaccesstoolbardefaultstate-class.md @@ -6,13 +6,13 @@ f1_keywords: ["CMFCRibbonQuickAccessToolBarDefaultState", "AFXRIBBONQUICKACCESST helpviewer_keywords: ["CMFCRibbonQuickAccessToolBarDefaultState [MFC], CMFCRibbonQuickAccessToolBarDefaultState", "CMFCRibbonQuickAccessToolBarDefaultState [MFC], AddCommand", "CMFCRibbonQuickAccessToolBarDefaultState [MFC], CopyFrom", "CMFCRibbonQuickAccessToolBarDefaultState [MFC], RemoveAll"] ms.assetid: eca99200-b87b-47ba-b2e8-2f3f2444b176 --- -# CMFCRibbonQuickAccessToolBarDefaultState Class +# `CMFCRibbonQuickAccessToolBarDefaultState` Class -A helper class that manages default state for the Quick Access Toolbar that is positioned on the ribbon bar ( [CMFCRibbonBar Class](../../mfc/reference/cmfcribbonbar-class.md)). +A helper class that manages default state for the Quick Access Toolbar that is positioned on the ribbon bar ([`CMFCRibbonBar` Class](../../mfc/reference/cmfcribbonbar-class.md)). ## Syntax -``` +```cpp class CMFCRibbonQuickAccessToolBarDefaultState ``` @@ -20,25 +20,25 @@ class CMFCRibbonQuickAccessToolBarDefaultState ### Public Constructors -|Name|Description| -|----------|-----------------| -|[CMFCRibbonQuickAccessToolBarDefaultState::CMFCRibbonQuickAccessToolBarDefaultState](#cmfcribbonquickaccesstoolbardefaultstate)|Constructs a `CMFCRibbonQuickAccessToolbarDefaultState` object.| +| Name | Description | +|--|--| +| [`CMFCRibbonQuickAccessToolBarDefaultState::CMFCRibbonQuickAccessToolBarDefaultState`](#cmfcribbonquickaccesstoolbardefaultstate) | Constructs a `CMFCRibbonQuickAccessToolbarDefaultState` object. | ### Public Methods -|Name|Description| -|----------|-----------------| -|[CMFCRibbonQuickAccessToolBarDefaultState::AddCommand](#addcommand)|Adds a command to the default state for the Quick Access Toolbar. This does not change the toolbar itself.| -|[CMFCRibbonQuickAccessToolBarDefaultState::CopyFrom](#copyfrom)|Copies the properties of one Quick Access Toolbar to another.| -|[CMFCRibbonQuickAccessToolBarDefaultState::RemoveAll](#removeall)|Removes all commands from the Quick Access Toolbar. This does not change the toolbar itself.| +| Name | Description | +|--|--| +| [`CMFCRibbonQuickAccessToolBarDefaultState::AddCommand`](#addcommand) | Adds a command to the default state for the Quick Access Toolbar. This method doesn't change the toolbar itself. | +| [`CMFCRibbonQuickAccessToolBarDefaultState::CopyFrom`](#copyfrom) | Copies the properties of one Quick Access Toolbar to another. | +| [`CMFCRibbonQuickAccessToolBarDefaultState::RemoveAll`](#removeall) | Removes all commands from the Quick Access Toolbar. This method doesn't change the toolbar itself. | ## Remarks -After you create the Quick Access Toolbar in your application, we recommend that you set its default state by calling [CMFCRibbonBar::SetQuickAccessDefaultState](../../mfc/reference/cmfcribbonbar-class.md#setquickaccessdefaultstate). This default state is restored when a user clicks the **Reset** button on the **Customize** page of your application's **Options** dialog box. +After you create the Quick Access Toolbar in your application, we recommend that you set its default state by calling [`CMFCRibbonBar::SetQuickAccessDefaultState`](../../mfc/reference/cmfcribbonbar-class.md#setquickaccessdefaultstate). This default state is restored when a user chooses the **Reset** button on the **Customize** page of your application's **Options** dialog box. ## Inheritance Hierarchy -[CMFCRibbonQuickAccessToolBarDefaultState](../../mfc/reference/cmfcribbonquickaccesstoolbardefaultstate-class.md) +[`CMFCRibbonQuickAccessToolBarDefaultState`](../../mfc/reference/cmfcribbonquickaccesstoolbardefaultstate-class.md) ## Example @@ -50,7 +50,7 @@ The following example demonstrates how to construct an object of the `CMFCRibbon **Header:** afxribbonquickaccesstoolbar.h -## CMFCRibbonQuickAccessToolBarDefaultState::AddCommand +## `CMFCRibbonQuickAccessToolBarDefaultState::AddCommand` Adds a command to the default state for the Quick Access Toolbar. @@ -62,17 +62,17 @@ void AddCommand( ### Parameters -*[in] uiCmd*
-Specifies command ID. +*`uiCmd`*\ +[in] Specifies command ID. -*[in] bIsVisible*
-Sets the visibility of the command when the Quick Access Toolbar is in the default state. +*`bIsVisible`*\ +[in] Sets the visibility of the command when the Quick Access Toolbar is in the default state. ### Remarks -Adding a command to the CMFCRibbonQuickAccessToolBarDefaultState accomplishes three results. First, each added command is listed on the dropdown on the right side of the Quick Access Toolbar. In this manner, a user can easily add or remove that command from the Quick Access Toolbar. Second, the Quick Access Toolbar is reset to show only those commands that are listed as visible in the default state when the user clicks the **Reset** button in the **Customize** dialog box. Third, if you have not called [CMFCRibbonBar::SetQuickAccessCommands](../../mfc/reference/cmfcribbonbar-class.md#setquickaccesscommands), the Quick Access Toolbar uses the visible commands from this list as the default visible commands the first time a user runs your application. After you have added all the commands that you want, call [CMFCRibbonBar::SetQuickAccessDefaultState](../../mfc/reference/cmfcribbonbar-class.md#setquickaccessdefaultstate) to set this instance as the default state for the Quick Access Toolbar of that Ribbon Bar. +Adding a command to the `CMFCRibbonQuickAccessToolBarDefaultState` accomplishes three results. First, each added command is listed on the dropdown on the right side of the Quick Access Toolbar. In this manner, a user can easily add or remove that command from the Quick Access Toolbar. Second, the Quick Access Toolbar is reset to show only those commands that are listed as visible in the default state when the user chooses the **Reset** button in the **Customize** dialog box. Third, if you haven't called [`CMFCRibbonBar::SetQuickAccessCommands`](../../mfc/reference/cmfcribbonbar-class.md#setquickaccesscommands), the Quick Access Toolbar uses the visible commands from this list as the default visible commands the first time a user runs your application. After you've added all the commands that you want, call [`CMFCRibbonBar::SetQuickAccessDefaultState`](../../mfc/reference/cmfcribbonbar-class.md#setquickaccessdefaultstate) to set this instance as the default state for the Quick Access Toolbar of that Ribbon Bar. -## CMFCRibbonQuickAccessToolBarDefaultState::CopyFrom +## `CMFCRibbonQuickAccessToolBarDefaultState::CopyFrom` Copies the properties of one Quick Access Toolbar to another. @@ -82,26 +82,26 @@ void CopyFrom(const CMFCRibbonQuickAccessToolBarDefaultState& src); ### Parameters -*src*
+*`src`*\ [in] A reference to the source `CMFCRibbonQuickAccessToolBarDefaultState` object to copy from. ### Remarks This method copies each command from the source `CMFCRibbonQuickAccessToolBarDefaultState` object to this object by using the [CMFCRibbonQuickAccessToolBarDefaultState::AddCommand](#addcommand) method. -## CMFCRibbonQuickAccessToolBarDefaultState::CMFCRibbonQuickAccessToolBarDefaultState +## `CMFCRibbonQuickAccessToolBarDefaultState::CMFCRibbonQuickAccessToolBarDefaultState` Constructs the Quick Access Toolbar default state object. -``` +```cpp CMFCRibbonQuickAccessToolBarDefaultState(); ``` ### Remarks -By default, the list of commands that the new instance of [CMFRibbonQuickAccessToolBarDefaultState](../../mfc/reference/cmfcribbonquickaccesstoolbardefaultstate-class.md) contains is empty. +By default, the list of commands that the new instance of [`CMFRibbonQuickAccessToolBarDefaultState`](../../mfc/reference/cmfcribbonquickaccesstoolbardefaultstate-class.md) contains is empty. -## CMFCRibbonQuickAccessToolBarDefaultState::RemoveAll +## `CMFCRibbonQuickAccessToolBarDefaultState::RemoveAll` Clears the list of default commands in the Quick Access Toolbar. @@ -111,10 +111,10 @@ void RemoveAll(); ### Remarks -This function removes from this instance all the commands that the previous calls to [CMFCRibbonQuickAccessToolBarDefaultState::AddCommand](#addcommand) added. +This function removes from this instance all the commands that the previous calls to [`CMFCRibbonQuickAccessToolBarDefaultState::AddCommand`](#addcommand) added. ## See also [Hierarchy Chart](../../mfc/hierarchy-chart.md)
[Classes](../../mfc/reference/mfc-classes.md)
-[CMFCRibbonBar Class](../../mfc/reference/cmfcribbonbar-class.md) +[`CMFCRibbonBar` Class](../../mfc/reference/cmfcribbonbar-class.md) diff --git a/docs/mfc/standard-commands.md b/docs/mfc/standard-commands.md index b8e6be9d5ac..116be5bb811 100644 --- a/docs/mfc/standard-commands.md +++ b/docs/mfc/standard-commands.md @@ -5,35 +5,25 @@ ms.date: "11/04/2016" helpviewer_keywords: ["File menu", "identifiers [MFC], command IDs", "command IDs, standard commands", "OLE commands", "commands [MFC], standard", "standard command IDs", "Window menu commands", "standard commands", "View menu commands", "Edit menu standard commands", "Help [MFC], menus", "programmer-defined IDs [MFC]"] ms.assetid: 88cf3ab4-79b3-4ac6-9365-8ac561036fbf --- -# Standard Commands +# Standard commands -The framework defines many standard command messages. The IDs for these commands typically take the form: +The framework defines many standard command messages. The IDs for these commands typically take the form **`ID__`**, where `` is usually a menu name and `` is a menu item. For example, the command ID for the **New** command on the **File** menu is `ID_FILE_NEW`. Standard command IDs are shown in bold type in the documentation. Programmer-defined IDs are shown in a font that's different from the surrounding text. -**ID_** *Source*_*Item* +The following list shows some of the most important commands supported: -where *Source* is usually a menu name and *Item* is a menu item. For example, the command ID for the New command on the File menu is ID_FILE_NEW. Standard command IDs are shown in bold type in the documentation. Programmer-defined IDs are shown in a font that is different from the surrounding text. +- *File Menu Commands*: New, Open, Close, Save, Save As, Page Setup, Print Setup, Print, Print Preview, Exit, and most-recently-used files. -The following is a list of some of the most important commands supported: +- *Edit Menu Commands*: Clear, Clear All, Copy, Cut, Find, Paste, Repeat, Replace, Select All, Undo, and Redo. -*File Menu Commands*
-New, Open, Close, Save, Save As, Page Setup, Print Setup, Print, Print Preview, Exit, and most-recently-used files. +- *View Menu Commands*: Toolbar and Status Bar. -*Edit Menu Commands*
-Clear, Clear All, Copy, Cut, Find, Paste, Repeat, Replace, Select All, Undo, and Redo. +- *Window Menu Commands*: New, Arrange, Cascade, Tile Horizontal, Tile Vertical, and Split. -*View Menu Commands*
-Toolbar and Status Bar. +- *Help Menu Commands*: Index, Using Help, and About. -*Window Menu Commands*
-New, Arrange, Cascade, Tile Horizontal, Tile Vertical, and Split. +- *OLE Commands (Edit Menu)*: Insert New Object, Edit Links, Paste Link, Paste Special, and *typename* Object (verb commands). -*Help Menu Commands*
-Index, Using Help, and About. - -*OLE Commands (Edit Menu)*
-Insert New Object, Edit Links, Paste Link, Paste Special, and *typename* Object (verb commands). - -The framework provides varying levels of support for these commands. Some commands are supported only as defined command IDs, while others are supported with thorough implementations. For example, the framework implements the Open command on the File menu by creating a new document object, displaying an Open dialog box, and opening and reading the file. In contrast, you must implement commands on the Edit menu yourself, since commands like ID_EDIT_COPY depend on the nature of the data you are copying. +The framework provides varying levels of support for these commands. Some commands are supported only as defined command IDs, while others are supported with thorough implementations. For example, the framework implements the Open command on the File menu by creating a new document object, displaying an Open dialog box, and opening and reading the file. In contrast, you must implement commands on the Edit menu yourself, since commands like ID_EDIT_COPY depend on the nature of the data you're copying. For more information about the commands supported and the level of implementation provided, see [Technical Note 22](../mfc/tn022-standard-commands-implementation.md). The standard commands are defined in the file AFXRES.H. diff --git a/docs/windows/attributes/idl-module.md b/docs/windows/attributes/idl-module.md index d6b446a2bb9..a0cf06f10a5 100644 --- a/docs/windows/attributes/idl-module.md +++ b/docs/windows/attributes/idl-module.md @@ -14,51 +14,51 @@ Specifies an entry point in a .dll file. ```cpp [ idl_module (name=module_name, dllname=dll, uuid="uuid", helpstring="help text", helpstringcontext=helpcontextID, helpcontext=helpcontext, hidden, restricted) ] -function declaration +function_declaration ``` ### Parameters -*name*
+*`name`*\ A user-defined name for the code block that will appear in the .idl file. -*dllname*
+*`dllname`*\ (Optional) The .dll file that contains the export. -*uuid*
+*`uuid`*\ (Optional) A unique ID. -*helpstring*
+*`helpstring`*\ (Optional) A character string used to describe the type library. -*helpstringcontext*
-(Optional) The ID of a help topic in an .hlp or .chm file. +*`helpstringcontext`*\ +(Optional) The ID of a help topic in a *`.hlp`* or *`.chm`* file. -*helpcontext*
+*`helpcontext`*\ (Optional) The Help ID for this type library. -*hidden*
-(Optional) A parameter that prevents the library from being displayed. See the [hidden](/windows/win32/Midl/hidden) MIDL attribute for more information. +*`hidden`*\ +(Optional) A parameter that prevents the library from being displayed. For more information, see the [`hidden`](/windows/win32/Midl/hidden) MIDL attribute. -*restricted*
-(Optional) Members of the library cannot be arbitrarily called. See the [restricted](/windows/win32/Midl/restricted) MIDL attribute for more information. +*`restricted`*\ +(Optional) Members of the library cannot be arbitrarily called. For more information, see the [`restricted`](/windows/win32/Midl/restricted) MIDL attribute. -*function declaration*
-The function that you will define. +*`function_declaration`*\ +The function that you'll define. ## Remarks -The **idl_module** C++ attribute lets you specify the entry point in a .dll file, which allows you to import from a .dll file. +The **`idl_module`** C++ attribute lets you specify the entry point in a *`.dll`* file, which allows you to import from a *`.dll`* file. -The **idl_module** attribute has functionality similar to the [module](/windows/win32/Midl/module) MIDL attribute. +The **`idl_module`** attribute has functionality similar to the [`module`](/windows/win32/Midl/module) MIDL attribute. -You can export anything from a COM object that you can export from a .dll file by putting a DLL entry point in the library block of an .idl file. +You can export anything from a COM object that you can export from a *`.dll`* file by putting a DLL entry point in the library block of an *`.idl`* file. -Your must use **idl_module** in two steps. First, you must define a name/DLL pair. Then, when you use **idl_module** to specify an entry point, specify the name and any additional attributes. +Use **`idl_module`** in two steps. First, define a name/DLL pair. Then, when you use **`idl_module`** to specify an entry point, specify the name and any additional attributes. ## Example -The following code shows how to use the **idl_module** attribute: +The following code shows how to use the **`idl_module`** attribute: ```cpp // cpp_attr_ref_idl_module.cpp @@ -72,16 +72,16 @@ void FuncName(int i); ## Requirements | Attribute context | Value | -|-|-| -|**Applies to**|Anywhere| -|**Repeatable**|No| -|**Required attributes**|None| -|**Invalid attributes**|None| +|--|--| +| **Applies to** | Anywhere | +| **Repeatable** | No | +| **Required attributes** | None | +| **Invalid attributes** | None | For more information, see [Attribute Contexts](cpp-attributes-com-net.md#contexts). ## See also -[IDL Attributes](idl-attributes.md)
-[Stand-Alone Attributes](stand-alone-attributes.md)
-[entry](entry.md) +[IDL attributes](idl-attributes.md)
+[Stand-alone attributes](stand-alone-attributes.md)
+[`entry`](entry.md)